@devrouter/cli 0.1.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Local dev routing CLI with shared Traefik reverse proxy",
   "author": "Roland Schlaefli",
   "homepage": "https://github.com/rschlaefli/devrouter#readme",
@@ -61,6 +61,7 @@
     "qualify:profiles": "node --import tsx scripts/qualify-profile-alternation.ts",
     "qualify:host-suspend": "node --import tsx scripts/qualify-host-suspend.ts",
     "test:process": "bash scripts/test-devrouter-process.sh",
+    "test:skills": "bash tests/worktree-reclaim/run-corpus.sh && bash tests/worktree-reclaim/test-reclaim.sh && bash tests/worktree-reclaim/test-manifest.sh",
     "check": "biome check .",
     "check:fix": "biome check --write .",
     "check:docs-policy": "./scripts/check-docs-policy.sh",

package/upgrade-prompts/0.2.0.md

@@ -0,0 +1,81 @@
+# Upgrade to devrouter 0.2.0
+
+This minor release adds worktree lifecycle tooling.
+
+- `workspace down` is safer.
+- A Git-safety verdict covers every linked worktree, managed or not.
+- Reclaim and trim commands apply only an approved, hash-bound manifest.
+- Two installable skills ship with the release: `worktree-reclaim` and
+  `devrouter-setup`.
+
+It adds one optional `.devrouter.yml` key, `worktrees`. Earlier versions reject
+unknown keys. A repository that declares `worktrees` therefore needs 0.2.0 or
+later on every machine that loads its configuration.
+
+## What changed for a consumer
+
+- `workspace down` refuses to remove a worktree that holds local state the
+  earlier check missed. That state covers:
+  - unrecognised ignored files;
+  - a detached HEAD;
+  - an index lock;
+  - an unfinished merge, rebase, cherry-pick, revert or bisect;
+  - initialized submodules.
+
+  The error names each reason. `--keep-worktree` still removes only the
+  runtime and routes.
+- `workspace cleanup --all-worktrees --check-merged` reports `RECLAIM`, `KEEP`
+  or `PRUNE` with stable reason codes for every linked worktree. This report
+  uses schema version 3. Without the flag, the report stays at schema version
+  2.
+- `workspace reclaim` removes the worktrees in an approved manifest. It removes
+  their runtime, ownership record and branch along with each worktree.
+- `workspace trim` removes only the ignored paths declared in
+  `worktrees.trim` and leaves the worktree, branch and runtime in place.
+- Both commands follow the same manifest rules:
+  - Both are dry runs until `--yes` is passed.
+  - Both re-check each target inside its lifecycle lock.
+  - Both write receipts, so a rerun reports `already-done`.
+- `cleanup --manifest` emits the manifest, and `workspace manifest hash|select`
+  hashes or narrows it. Manifests are interchangeable with the
+  `worktree-reclaim` skill.
+- `npx skills add rschlaefli/devrouter` installs the `devrouter`,
+  `worktree-reclaim` and `devrouter-setup` skills.
+
+## Task
+
+Install the published 0.2.0 CLI. No migration or runtime-state change is
+needed.
+
+Optionally declare reproducible ignored paths in `.devrouter.yml`. Do this only
+when consumer source changes are authorized. When you add the key, raise the
+documented minimum devrouter version to 0.2.0 in the same change:
+
+```yaml
+worktrees:
+  disposable: ["**/playwright-report"]
+  trim: ["**/node_modules", "**/.next"]
+```
+
+## Validation
+
+1. Run `devrouter -V` from the consumer checkout. A repository Volta pin can
+   change which install resolves.
+2. Run `devrouter doctor --repo <checkout>`.
+3. Run `devrouter workspace cleanup --repo <checkout> --all-worktrees
+   --check-merged` and confirm the report lists every linked worktree with a
+   verdict.
+4. Run every reclaim or trim as a dry run first. Run with `--yes` only after a
+   person has approved the manifest's printed SHA-256.
+
+## Report
+
+Report:
+
+- the release revision;
+- the resolved executable and its installed version;
+- the verdict counts from the cleanup report;
+- for any authorized reclaim or trim, the manifest hash and the per-target
+  outcomes.
+
+Report kept trees with their reason codes, never as failures.

package/upgrade-prompts/0.3.0.md

@@ -0,0 +1,59 @@
+# Upgrade to devrouter 0.3.0
+
+This minor release finishes worktree cleanup after deleted checkouts and adds
+a team guide.
+
+- `workspace gc` can now remove a Devsy workspace whose checkout folder was
+  already deleted.
+- `workspace cleanup --all-worktrees` lists Docker leftovers: the Compose
+  stacks of deleted worktrees.
+- `workspace leftover` removes approved leftovers from a hash-bound manifest.
+- `docs/WORKTREE_CLEANUP.md` explains the whole cleanup flow for engineers.
+
+There is no configuration change and no migration.
+
+## What changed for a consumer
+
+- When the ordinary Devsy delete fails, `gc` forces it only when the recorded
+  folder no longer exists and the runtime is stopped or not found. A failed
+  delete of a folder that still exists is reported, never forced.
+- The cleanup report gains a `dockerLeftovers` section with schema version 3.
+  A stack counts as a leftover only when all of its containers name the same
+  folder below `<repo>/trees/`, at least one container was created by DevPod
+  or Devsy, the folder no longer exists, it is not inside another existing
+  worktree, no registration still names it, and every container is stopped.
+  Blocked stacks name the next step (`workspace gc` or `git worktree prune`).
+- `workspace cleanup --manifest --action leftover --output <file>` writes a
+  `docker-leftover-manifest`. `workspace leftover --manifest <file> --sha256
+  <hash>` is a dry run until `--yes`. It removes the listed containers, then
+  the listed volumes (project and anonymous volumes no other container uses),
+  then networks, and skips any stack that changed.
+- Volumes that no container ties to a deleted worktree are reported and never
+  removed. Worktree `reclaim` and `trim` reject leftover manifests.
+
+## Task
+
+Install the published 0.3.0 CLI. No migration or runtime-state change is
+needed. Raise a repository's documented minimum devrouter version to 0.3.0
+only when consumer source changes are authorized and the team should use the
+leftover commands.
+
+## Validation
+
+1. Run `devrouter -V` from the consumer checkout. A repository Volta pin can
+   change which install resolves.
+2. Run `devrouter workspace cleanup --repo <checkout> --all-worktrees` and
+   confirm the report includes the Docker leftovers section.
+3. Run `devrouter workspace gc` and every leftover removal as a dry run first.
+   Run with `--yes` only after a person has approved the exact targets or the
+   manifest's printed SHA-256.
+
+## Report
+
+Report:
+
+- the release revision;
+- the resolved executable and its installed version;
+- the leftover and blocked counts from the cleanup report;
+- for any authorized gc or leftover removal, the targets or manifest hash and
+  the per-target outcomes.