4 Commits

Include renames

Author	SHA1	Message	Date
DottaandPaperclip	0f0e544317	fix(cli): open dashboard after onboarding service starts (#12164) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The CLI can install and start Paperclip as a managed user service during onboarding. > - Recent fixes now install the service shim and remove the redundant foreground start prompt. > - The service path still ends without a dashboard URL or an open browser. > - The server can also move to a free port when the configured port is busy. > - This pull request adds a health-aware handoff to the managed service's actual endpoint. > - The benefit is that new users can reach Paperclip without starting a second process. ## Linked Issues or Issue Description **What happened?** After interactive onboarding installs and starts the managed service, the command ends without printing the dashboard URL or opening the browser. If the configured port is busy, the service can use a fallback port that the onboarding process does not know. **Expected behavior** Onboarding must print the dashboard URL that belongs to the managed service. An interactive terminal should open the URL after the local health check succeeds. A non-interactive terminal should only print the URL. **Steps to reproduce** 1. Start from a host without an installed Paperclip service. 2. Run another process on the configured Paperclip port. 3. Run `npx paperclipai@<version> onboard` in an interactive terminal. 4. Accept the managed service installation. 5. Observe that the service starts on a fallback port, but onboarding does not provide or open that dashboard URL. **Paperclip version or commit** `b6854e61c` on `master`, after #12148, #12151, and #12153. **Deployment mode** Local managed user service on macOS or Linux. **Installation method** `npx paperclipai@<version> onboard`. The same onboarding path can also run after `install.sh`. Related public pull requests: #12148, #12151, and #12153. ## What Changed - Record each running CLI server's PID, selected port, and dashboard URL in atomic per-instance runtime metadata. - Accept runtime metadata only when its PID matches the active managed service. - Wait for the selected runtime endpoint to report healthy before printing its URL. - Open the URL in interactive terminals and keep headless runs browser-free. - Keep the printed configured URL as a fallback when runtime discovery fails. - Use browser-launch wording that only claims the URL was sent to the opener. - Add runtime metadata, fallback-port, health handoff, headless, and failure-path tests. - Document the managed service dashboard handoff. ## Verification - `pnpm exec vitest run cli/src/__tests__/onboard-service.test.ts cli/src/__tests__/runtime-info.test.ts cli/src/__tests__/onboard.test.ts cli/src/__tests__/open-url.test.ts cli/src/__tests__/service-health-check.test.ts` — 44 tests passed. - `node --test scripts/service-onboard-smoke.test.mjs` — 4 tests passed. - `pnpm -r typecheck` — passed on head `82920596a`. - `pnpm build` — passed on head `82920596a`. - `pnpm test:run` — 4,685 tests passed. The command also reported 31 failures in nine server test files outside this change. This machine generated invalid test ports above 65,535, and some project-skill fixtures resolved outside the worktree. ## Risks - Risk is low because the new handoff runs only after a successful service installation. - Onboarding can wait up to 60 seconds when runtime metadata or the health check does not become ready. - Runtime metadata is matched to the supervisor PID, so stale or foreground-process metadata is ignored. - A non-interactive terminal does not open a browser. - A failed health check or browser launch does not fail onboarding. The CLI keeps a manual URL visible. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, GPT-5 family. The runtime did not expose the exact model ID or context window. The model used reasoning, repository tools, GitHub access, and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-08-25 09:33:09 -05:00
Devin Foley	8d714c2d84	fix(cli): skip the foreground-start prompt after the service starts (#12153) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The CLI onboarding wizard can install Paperclip as a background service, and it offers a foreground start when nothing else will serve > - After #12148, an interactive onboard installs and starts the service, then still asks "Start Paperclip now?" > - Answering yes runs the foreground start into the already-running instance guard, so a fully successful onboard ends with an error message > - This pull request excludes the just-installed-service case from the foreground-start prompt > - The benefit is that an interactive onboard that installs the service ends cleanly instead of steering the user into a guard refusal ## Linked Issues or Issue Description Refs #12148 — found while verifying that fix interactively. The `shouldRunNow` flag already accounts for `serviceInstalled`, but the interactive TTY fallback prompt did not, so only real interactive runs hit it: `--yes` runs, CI, and container smokes all skip the prompt branch. **What happened?** Interactive `onboard`, accept the background-service prompt. Output ends with: service installed and started, then "Start Paperclip now?" → yes → "Paperclip instance 'default' is already running as ing.paperclip.paperclipai. Use 'paperclipai service status --instance default' or pass --force to bypass this safety check." **What did you expect to happen?** Onboarding ends cleanly after "Installed and started …" — there is nothing left to start, so no prompt. **Steps to reproduce** Run `npx paperclipai@2026.825.0-nightly.1 onboard --data-dir "$(mktemp -d)"` in a terminal, accept the service prompt, then accept "Start Paperclip now?". ## What Changed - New `shouldOfferForegroundStart` predicate in `cli/src/onboard-service.ts`: the foreground-start prompt is offered only when the start was not already decided by flags, the service was not just installed, onboarding was not invoked by `run`, and the terminal is interactive. - Both onboarding call sites in `cli/src/commands/onboard.ts` use the predicate instead of the inline condition that ignored `serviceInstalled`. - Unit tests cover the predicate matrix in `cli/src/__tests__/onboard-service.test.ts`. ## Verification - `npx vitest run src/__tests__/onboard-service.test.ts` in `cli/`: 12 passed (5 new). - `tsc --noEmit` reports no errors in the changed files (remaining errors are pre-existing in `server/`). - Manual reproduction of the defect on macOS with `2026.825.0-nightly.1` before the fix: service installed, started, and healthy, then the prompt steered into the guard refusal. ## Risks - Low risk. The prompt still appears in every case it did before except when the service was just installed and is already serving. - No behavior change for `--yes`, `--run`, `--install-service` in non-interactive runs: those paths never reached the prompt. ## Model Used - Claude Fable 5 (Anthropic, model ID `claude-fable-5`), extended thinking, agentic tool use via Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge	2026-08-25 01:06:20 -07:00
Devin Foley	faad235aa2	fix(cli): materialize the managed install before the onboarding service install (#12148) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Interactive onboarding offers to install Paperclip as a background service, defaulting to yes > - The service definition targets the managed command shim, but an ephemeral npx run never installs it, and the service step never checks > - The result is a crash-looping service, a doctor hint about a nonexistent port conflict, and a first run that ends with nothing serving > - This pull request materializes the managed install before registering the service, or declines with the repair path > - The benefit is that saying yes to the service prompt yields a working service — or an honest explanation ## Linked Issues or Issue Description **What happened?** On a machine with no managed install, `npx paperclipai@2026.824.0 onboard` (interactive), accepting the background-service prompt, produced: a LaunchAgent pointing at `~/.local/bin/paperclipai` (which does not exist), launchd exit code 78 in a KeepAlive crash loop, doctor reporting "inactive but the configured port is serving another Paperclip process — stop the conflicting foreground process" (no such process existed), and "Service health: fetch failed". Reproduced twice on a clean field. `latest` has carried this path since v2026.817.0 shipped; CI never sees it because `--yes` onboarding skips the service prompt. **Expected behavior** Accepting the service prompt installs a working service (materializing the managed payload and shim first when needed), and doctor diagnoses a missing service binary as exactly that. **Steps to reproduce** On macOS with no `~/.local/bin/paperclipai`: `npx paperclipai@latest onboard`, accept the service prompt, then `launchctl print gui/$UID/ing.paperclip.paperclipai` (exit code 78, spawn scheduled) and `paperclipai doctor`. **Paperclip version or commit** `2026.824.0` (path present since #10045). ## What Changed - `cli/src/onboard-service.ts`: after the user opts in, an `ensureServiceShim` step checks the service shim path. Missing + managed-store location → run `installCommand` pinned to the onboarding version (payload, shim, PATH block), then proceed. Missing + custom `PAPERCLIP_SHIM_PATH`, or install failure → decline with `paperclipai install` / `paperclipai service install` guidance and install nothing. - `cli/src/checks/service-health-check.ts`: the runtime check diagnoses a missing service binary with the install repair hint (instead of the port-conflict hint); an inactive service with a healthy responder gets a `warn` attributing the foreign process instead of a plain "Healthy" pass. - Tests: new cases for shim materialization ordering, decline-on-failure, missing-binary diagnosis, and foreign-responder attribution; existing fixtures updated to inject the new dependencies. ## Verification - `vitest run` on both touched suites: 15 pass. - `tsc --noEmit` error count identical to the master baseline (16 pre-existing, all in `server/`, none in changed files). - The live failure was reproduced on macOS before the fix (twice, clean field) and the mechanism confirmed in source: `install()` writes the definition and bootstraps launchd only; `install-store` was previously reachable solely from the `install`/`update` commands. ## Risks - Low: the new path runs only when the user opts into the service and the shim is absent. The managed install resolves the pinned onboarding version from the public registry; on failure the flow declines exactly as it does on unsupported platforms. `--yes` quickstarts, Docker, and managed installs are untouched. ## Model Used Claude Fable 5 (Claude Code) ## Pre-submission checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template	2026-08-24 23:30:54 -07:00
3 people	fc5a30805e	feat(cli): add managed install, update, and service lifecycle (#10045) ... ## Thinking Path > - Paperclip is the open source control plane people use to manage AI-agent companies > - Operators need a predictable installation path that survives beyond an ephemeral `npx` process > - A durable installation needs an owned per-user payload store, stable command shim, safe shell integration, and supported service lifecycle > - Updates must preserve recoverability by backing up data, installing side-by-side, verifying the new payload, and retaining rollback state > - Bootstrap scripts and privileged service operations must fail closed across download, filesystem, ownership, and consent boundaries > - This pull request integrates managed install, update, rollback, service, uninstall, doctor, bootstrap-installer, and runtime-serving support into one workflow > - The benefit is a recoverable, inspectable, and documented installation lifecycle with explicit safety boundaries across Linux, macOS, containers, WSL, npm, npx, and source checkouts ## Linked Issues or Issue Description ### Problem Paperclip lacks a first-class durable installation and lifecycle workflow. Operators currently have to assemble npm/npx installation, PATH setup, background-service management, updates, rollback, diagnostics, and uninstall behavior themselves. That makes upgrades harder to recover, creates inconsistent behavior across platforms, and leaves shell/download/service trust boundaries without one documented implementation. ### Proposed Solution Add a managed per-user install store and stable shim, a verified shell bootstrap installer, service lifecycle commands, install-mode-aware update/rollback behavior, doctor checks, and documentation. Managed updates back up the database, install and smoke-test a side-by-side payload, atomically switch `current`, and retain prior payloads. The shell installer pins registry/download trust boundaries and requires explicit consent for non-interactive privileged actions. ### Alternatives Considered - Keep recommending `npx`: simple for evaluation, but ephemeral and unsuitable for stable services, atomic updates, or rollback. - Require global npm installation only: familiar, but cannot provide the owned side-by-side payload store and retained rollback semantics. - Split the capability across multiple PRs: rejected because install, update, service, uninstall, bootstrap, and serving behavior share contracts and security boundaries that need review together. ### Related Pull Requests - Supersedes #10042 and #10044 with one integrated final diff. - Incorporates and replaces the closed preparatory work in #10032 and #10034. ## What Changed - Added `paperclipai install`, `update`/`upgrade`, rollback, uninstall, service lifecycle, onboarding integration, and managed-install doctor checks. - Added a private managed payload store, verified manifest/marker ownership, exclusive mutation locks, atomic manifest/current/shim writes, retained previous payloads, and provenance validation. - Added npm and GitHub-ref install sources with exact target resolution, registry isolation, database backup, side-by-side verification, atomic activation, service restart coordination, and failure rollback. - Made managed-update backups report actionable service-start and `--no-backup` recovery guidance for unreachable databases, while clean never-onboarded instances skip an empty backup. - Added systemd user and launchd service definitions, status/health/log commands, single-instance coordination, stale-port recovery, and explicit sudo/lingering consent handling. - Added the `scripts/install.sh` bootstrap path with checked two-stage downloads, pinned public npm registry usage, platform checks, dry-run/non-interactive controls, and Docker fixtures. - Added embedded Postgres/native bootstrap integration, hot-restart/systemd-notify serving support, passive update notices, configuration contracts, README/CLI/install documentation, and focused regression tests. - Security re-review should explicitly re-verify: (1) `addManagedPathBlock`/`removeManagedPathBlock` reject symlinked or non-regular rc files, assert current-user ownership, preserve restrictive modes, and replace atomically; (2) managed shim replacement rejects unsafe parents, foreign-owned or multiply linked files, and uses checked atomic replacement; (3) the shell installer and sudo path preserve explicit consent and checked downloads; and (4) installed service/runtime serving remains bound to the validated managed shim and instance configuration. ## Verification - `bash -n scripts/install.sh scripts/clean-install-git.sh scripts/clean-install-npm.sh scripts/test-install-sh-docker.sh` - `pnpm exec vitest run cli/src/__tests__/install-store.test.ts cli/src/__tests__/install-command.test.ts cli/src/__tests__/managed-install-check.test.ts cli/src/__tests__/onboard-service.test.ts cli/src/__tests__/service-health-check.test.ts cli/src/__tests__/service-manager.test.ts cli/src/__tests__/update-command.test.ts cli/src/__tests__/update-notice.test.ts packages/db/src/embedded-postgres-native.test.ts` — 9 files, 66 tests passed - `pnpm --dir cli typecheck` - `pnpm --dir cli build` - Follow-up verification: `pnpm exec vitest run cli/src/__tests__/update-command.test.ts` (14/14), `pnpm --dir cli typecheck`, `pnpm --dir cli build`, and `pnpm --filter @paperclipai/server typecheck`. - `pnpm -r typecheck` - `pnpm build` - Full `pnpm test:run` exercised all suites; an injected static AWS credential changed one unrelated doctor expectation, which passed when those credentials were removed. A second run cleared that case and exposed stale pre-existing adapter-utils `dist` output; rebuilding `@paperclipai/adapter-utils` made the isolated test pass. The updated PR CI is the authoritative clean-workspace full-suite run. ## Risks - Installer/update code writes executable shims, symlinks, shell rc blocks, service definitions, and managed payloads; ownership, regular-file, symlink, hard-link, marker, and path-containment checks fail closed before destructive changes. - The bootstrap installer executes downloaded tooling; downloads are staged and checked before execution, npm traffic is pinned to the public registry, and non-interactive privileged behavior requires explicit consent. - Linux lingering may invoke `sudo`; the command is surfaced and confirmed before execution, and unsupported service managers fall back to foreground-run guidance. - Database migrations remain forward-only; payload rollback does not reverse migrations, so managed updates create a backup before activation unless explicitly disabled. - Service restart and runtime serving touch process/port ownership; lifecycle locks, health/version checks, and stable-shim service definitions reduce split-brain and stale-process risk. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex coding agents using GPT-5.5 and GPT-5.6-sol, with reasoning, repository/API access, shell execution, and test tooling. The runtime did not expose a reliable context-window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-31 18:52:23 -07:00