chore: finish the .superset → .paradev move for repo config, dev data and worktree repair

Merged
SA
14d ago
+302-202

Summary

  • This repo's workspace config moves from .superset/ to .paradev/, and the per-worktree dev data folder superset-dev-data/ becomes paradev-dev-data/. Neither keeps backwards compatibility in the scripts.
  • Fix: after the home move, git worktree repair skipped worktrees whenever one stored workspace path had a deleted parent folder. Machines that already hit it (canary) now get repaired on their next boot: the repair runs on every boot, but only for checkouts whose git records still name ~/.superset.
  • Fix: the agent-setup hook matcher now counts ~/.paradev/hooks/... as managed, so a dev build replaces the installed app's Cursor, Gemini and notify hooks again instead of adding its own next to them.

Why / Context

Part of removing "superset" from every surface. I audited the home move from #9158 on a real machine after the canary ran it:

  • Worktree repair: 8 worktrees in ~/code/paradev still had git records on ~/.superset/.... repairGitWorktrees passes every workspace path for a repo to one git worktree repair. Git exits fatally at the first path whose parent folder is gone (here an archived investigate/<name> workspace) and skips every path after it. A missing leaf folder only logs an error. Git still worked through the ~/.superset symlink, which hid the failure.
  • Hook matcher: SUPERSET_MANAGED_HOOK_PATH_PATTERN only knew .superset(-x) and superset-dev-data, so since the move it treated the default home's own hook entries as foreign.
  • Repo config: .paradev/ is safe to use here because canary desktops (344c299f43) and this morning's production sandbox release both include #9248, which reads .paradev/. Stable desktop-v2.0.2 only reads .superset/, but the company is on canary.

How It Works

  • repairGitWorktrees(worktrees, legacyHomeDir) keeps only checkouts whose .git file or admin gitdir still names the legacy home, comparing against both the path as given and with its parent folder resolved, since git stores /private/var/... on macOS. Missing checkouts drop out the same way. Both callers (host-service, desktop) now run it on every boot instead of only when the boot rewrote database rows.
  • The hook matcher regexes (agent-wrappers-common.ts, agent-wrappers-muse.ts) accept .paradev(-x) and paradev-dev-data, and still accept the old names so stale entries from old worktrees get cleaned up.
  • git mv .superset .paradev. Config commands, scripts, READMEs (all locales), DEVELOPMENT/CONTRIBUTING, agent skills, mobile scripts, .env examples, the contribute plugin skill and the golden release check (test -x /workspace/.paradev/setup.cloud.sh) point at the new paths.
  • In the scripts: DEV_DATA_DIR="paradev-dev-data" lives in lib/common.sh, and prod_app_home is just ~/.paradev. Output text says Paradev, the cloud tmux session is paradev, the local MCP entry is paradev-local, and SUPERSET_SCRIPT_DIR is now PARADEV_SCRIPT_DIR.
  • The CLI build cache is now ~/.paradev-build-cache.
  • .gitignore swaps the .superset/* entries for .paradev/* and keeps .superset/ and superset-dev-data/. Existing worktrees still have leftover untracked ports/overlay/dev data folders, which can hold a sign-in token, and these lines stop git add -A from committing them.

Manual QA

  • Ran the real ./.paradev/setup.sh in this worktree: every step passed, it reused the existing Neon branch, wrote .env with the same keys and SUPERSET_HOME_DIR=<worktree>/paradev-dev-data, and wrote .paradev/ports.json, which git ignores.
  • Host-service loadProjectConfig on this repo resolves .paradev/config.toml → ./.paradev/setup.sh / ./.paradev/teardown.sh.
  • Teardown's dev data removal in a scratch folder: removes paradev-dev-data, leaves superset-dev-data alone, and skips cleanly when the folder is absent. I didn't run real teardown, because it deletes the Neon branch.
  • Reproduced git's behavior by hand: a missing leaf path is non-fatal, while a missing parent folder is fatal: Invalid path, exit 128.
  • On the audited machine, running git worktree repair per worktree fixed the 8 stale records.

Testing

  • bun test in packages/agent-setup (434 pass). The new repair and hook-matcher cases fail without their fixes.
  • bun test for packages/shared/src/project-config, packages/sandbox, packages/trpc/src/lib/sandbox/repo-hooks.test.ts, and packages/host-service/src/daemon/DaemonSupervisor.test.ts
  • tsc --noEmit for agent-setup, sandbox, shared, mcp and auth
  • biome check on the changed files, bun run check:plugins
  • apps/mobile typecheck fails in NewSessionSheet.tsx, which this PR doesn't touch, so it's a failure already on main.

Rollout

  • Existing worktrees re-run ./.paradev/setup.sh (or with --force) to switch to paradev-dev-data. Until then their .env keeps pointing at the old folder, and bun scripts/dev-cli.ts won't find their dev host.
  • Stable desktop-v2.0.2 won't find this repo's setup scripts. That's accepted, because everyone internal is on canary.
  • SUPERSET_* environment variables are unchanged. The app reads them, so they move with the app.

Summary by cubic

Finishes this repo's move from .superset/ to .paradev/: workspace config, per-worktree dev data, docs and scripts now use the new names, and it fixes git worktree repair skipping worktrees after a stored workspace path whose parent folder was deleted.

Bug Fixes

  • repairGitWorktrees skips missing worktree paths, since git worktree repair aborts fatally at the first path whose parent folder is gone and leaves everything after it stale. It now runs on every boot, but only touches checkouts whose git records still name the legacy home — matching both absolute and resolved-relative backlink paths — so the per-boot cost stays low.
  • The managed hook matcher now recognizes ~/.paradev and paradev-dev-data paths, so a dev build replaces the installed app's Cursor, Gemini and notify hooks instead of adding its own next to them; the old .superset/superset-dev-data patterns stay so stale entries are still reaped.

Migration

  • Existing worktrees re-run ./.paradev/setup.sh (--force to replace dev data) to point .env at paradev-dev-data; setup.sh --mcp also drops the old superset-local MCP entry.
  • The CLI build cache moved to ~/.paradev-build-cache.
  • Stable desktop-v2.0.2 still only reads .superset/; canary and production sandboxes read .paradev/.

Summary by CodeRabbit

  • Developer Experience
    • Development setup, teardown, workspace configuration, and data directories now use Paradev naming. Updated setup and teardown commands are available, and development tools recognize Paradev-managed hooks.
    • Git worktree registration can be repaired after a home-directory move, including when other worktree entries point to deleted locations.
  • Documentation
    • Updated development setup and troubleshooting guidance across project documentation and translated readmes to use the Paradev workspace.