@devrouter/cli 0.0.1 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.0.1",
+  "version": "0.0.22",
   "description": "Local dev routing CLI with shared Traefik on macOS",
   "license": "MIT",
   "repository": {
@@ -8,11 +8,12 @@
     "url": "https://github.com/rschlaefli/devrouter.git"
   },
   "files": [
-    "dist"
+    "dist",
+    "upgrade-prompts"
   ],
   "type": "commonjs",
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "bin": {
     "dev": "dist/dev.js"
@@ -27,19 +28,24 @@
     "@types/node": "^22.10.1",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
   },
   "volta": {
-    "node": "22.22.0",
-    "pnpm": "10.28.2"
+    "node": "24.16.0",
+    "pnpm": "11.6.0"
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "check:docs-policy": "./scripts/check-docs-policy.sh",
+    "test:watch": "vitest",
     "demo:smoke": "./scripts/smoke-demo.sh",
     "bench:startup": "zsh -lc 'set -euo pipefail; echo \"=== dev --help (x5) ===\"; for i in {1..5}; do /usr/bin/time -p node dist/dev.js --help >/dev/null; done; echo \"=== dev app add --help (x5) ===\"; for i in {1..5}; do /usr/bin/time -p node dist/dev.js app add --help >/dev/null; done; echo \"=== dev status --json (x3, best effort) ===\"; for i in {1..3}; do /usr/bin/time -p node dist/dev.js status --json >/dev/null || true; done'",
     "typecheck": "tsc --noEmit",
-    "install:local": "./scripts/install-local.sh",
+    "bootstrap": "pnpm install && pnpm install:local",
+    "install:local": "pnpm build && ./scripts/install-local.sh",
     "uninstall:local": "./scripts/uninstall-local.sh"
   }
 }

package/upgrade-prompts/0.0.10.md

@@ -0,0 +1,27 @@
+You are upgrading a repository that uses devrouter to version 0.0.10.
+
+Task:
+1) Refresh discoverability artifacts with the installed CLI version:
+   - `dev repo agents --repo <repo>`
+2) Audit host-run commands that wrap app startup with secret managers (Infisical/Doppler or any wrapper using `run --`):
+   - detect forms like `DATABASE_URI=... <wrapper> run -- ...`
+   - migrate to post-wrapper env override when DB vars must be forced:
+     - `<wrapper> run -- env DATABASE_URI=${DATABASE_URL:?missing DATABASE_URL} <app command ...>`
+3) For one-shot commands, keep deterministic alias mapping:
+   - `dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- <command ...>`
+4) Run env probe before migrate/seed to confirm effective values:
+   - `dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- printenv DATABASE_URL DATABASE_URI DB_HOST DB_PORT SHADOW_DATABASE_URL`
+5) Run diagnostics and resolve new wrapper-precedence warnings:
+   - `dev doctor --repo <repo>`
+   - address `repo.host-command-env-precedence` warnings by moving DB assignments after `run --`.
+
+Validation:
+- run representative host app startup (`dev app run <host-app> --repo <repo> --yes`)
+- run env probe command and confirm `DATABASE_URI` aligns with injected `DATABASE_URL` for local postgres flow
+- run `dev doctor --repo <repo>` and confirm no blocking errors
+
+Report:
+- host-run commands updated
+- env probe output summary
+- doctor check summary (including whether `repo.host-command-env-precedence` is clean)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.11.md

@@ -0,0 +1,26 @@
+You are upgrading a repository that uses devrouter to version 0.0.11.
+
+Task:
+1) Refresh discoverability artifacts with the installed CLI version:
+   - `dev repo agents --repo <repo>`
+2) Review automation/scripts that expect `dev app exec` to always stop dependencies.
+   - Update assumptions: exec now stops only deps it started; already-running deps stay up.
+3) For workflows that chain app startup + seed/migrate:
+   - keep using `dev app run <app> --repo <repo> --yes`
+   - run one-shot commands with `dev app exec <app> --repo <repo> --yes -- <command ...>`
+   - confirm DB/service remains running when it was already up before exec.
+4) Keep deterministic alias mapping for non-Prisma apps:
+   - `dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- <command ...>`
+5) Keep env probe before migrate/seed when secret managers are involved:
+   - `dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- printenv DATABASE_URL DATABASE_URI DB_HOST DB_PORT SHADOW_DATABASE_URL`
+
+Validation:
+- start app/deps: `dev app run <host-app> --repo <repo> --yes`
+- run one-shot command: `dev app exec <host-app> --repo <repo> --yes -- <seed-or-migrate-command ...>`
+- verify dependency service state is unchanged when it was already running before exec
+- run `dev doctor --repo <repo>`
+
+Report:
+- scripts/workflows reviewed for old teardown assumptions
+- command(s) validated and resulting dependency lifecycle behavior
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.12.md

@@ -0,0 +1,26 @@
+You are upgrading a repository that uses devrouter to version 0.0.12.
+
+Task:
+1) Keep `.localhost` hostnames as configured; multi-segment hostnames (for example `elearning.klicker.localhost`) remain supported.
+2) Ensure runtime workflows use normal run/exec entrypoints so TLS host coverage can auto-refresh:
+   - `dev app run <app> --repo <repo> --yes`
+   - `dev app exec <app> --repo <repo> --yes -- <command ...>`
+3) Validate TLS coverage diagnostics:
+   - run `dev doctor --repo <repo>`
+   - inspect `repo.tls-host-coverage`
+4) If `repo.tls-host-coverage` warns, remediate by either:
+   - running app startup via `dev app run <app> --repo <repo> --yes` (auto-refresh), or
+   - running `dev tls install` (manual refresh).
+5) Re-run diagnostics after remediation:
+   - `dev doctor --repo <repo>`
+
+Validation:
+- `dev doctor --repo <repo>` has no blocking errors
+- `repo.tls-host-coverage` is clear for configured hosts
+- representative HTTPS route no longer presents Traefik default cert fallback
+
+Report:
+- hostnames reviewed/kept
+- whether auto-refresh or manual refresh was used
+- doctor summary for `repo.tls-host-coverage`
+- unresolved TLS or certificate-trust risks

package/upgrade-prompts/0.0.13.md

@@ -0,0 +1,29 @@
+You are upgrading a repository that uses devrouter to version 0.0.13.
+
+Task:
+1) Refresh discoverability artifacts with the installed CLI version:
+   - `dev repo agents --repo <repo>`
+2) Identify non-routed Docker dependency workarounds currently modeled as routed apps (for example Redis configured as `protocol=http` + dummy `.localhost` host only to enable dependency startup).
+3) Convert those entries to first-class dependency apps:
+   - set `kind: dependency`
+   - keep `runtime: docker`
+   - keep `docker.service` and `docker.composeFiles`
+   - remove routed-only fields: `host`, `protocol`, `tcpProtocol`, `hostRun`, `docker.internalPort`, `docker.router`
+4) Keep dependency references in dependent apps via `dependencies: [{ app: "<name>" }]`.
+5) Update scripts/docs that previously attempted direct execution of dependency-only entries:
+   - `dev app run <dependency-name>` is intentionally rejected
+   - `dev app exec <dependency-name> -- <cmd>` is intentionally rejected
+   - `dev open <dependency-name>` reports no route exists by design
+
+Validation:
+- run `dev app ls --repo <repo>` and confirm dependency entries show as dependency/docker without route host requirements
+- run routed parent app startup: `dev app run <parent-app> --repo <repo> --yes`
+- run one-shot command on routed parent: `dev app exec <parent-app> --repo <repo> --yes -- <command ...>`
+- run `dev ls` and confirm dependency-only entries do not produce endpoints
+- run `dev doctor --repo <repo>`
+
+Report:
+- entries migrated from workaround style to `kind: dependency`
+- dependency graph and startup behavior validated
+- direct-target script/doc updates completed
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.14.md

@@ -0,0 +1,27 @@
+You are upgrading a repository that uses devrouter to version 0.0.14.
+
+Task:
+1) Ensure the repository stores the applied devrouter release in `.devrouter.yml`:
+   - use top-level `devrouter.version: <semver>`
+   - keep schema `version: 1` unchanged
+2) Verify version state with:
+   - `dev -V --repo <repo>`
+3) Resolve upgrade path with:
+   - `dev upgrade --repo <repo>`
+4) Apply the next required release prompt (incremental upgrade):
+   - `dev upgrade <target-version> --repo <repo>`
+5) If further versions are reported after that target, continue incrementally by repeating step 4 until reaching the desired version.
+6) After finishing upgrade edits, refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows installed CLI version, local repo version, and next target (or none)
+- `dev upgrade --repo <repo>` lists upgrade targets in ascending order and marks the next version
+- `dev upgrade <target-version> --repo <repo>` prints the expected Agent Adaptation Prompt for that version
+- `dev doctor --repo <repo>`
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- target versions applied in order
+- remaining available versions (if any)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.15.md

@@ -0,0 +1,22 @@
+You are upgrading a repository that uses devrouter to version 0.0.15.
+
+Changes in this release:
+- Postgres dependency env injection now includes `DIRECT_URL` (equals `DATABASE_URL`).
+- This enables Prisma + PgBouncer setups where `DIRECT_URL` bypasses the pooler for migrations.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.15`.
+2) No schema or config migration required — `DIRECT_URL` injection is additive.
+3) If your app uses Prisma with PgBouncer, you can now reference `DIRECT_URL` in `schema.prisma` `directUrl` field; devrouter injects it automatically for postgres deps.
+4) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.15` as local repo version
+- `dev doctor --repo <repo>`
+- `dev app exec <app-with-postgres-dep> --repo <repo> -- env | grep DIRECT_URL` confirms injection
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- whether `DIRECT_URL` is consumed by app (if applicable)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.16.md

@@ -0,0 +1,34 @@
+You are upgrading a repository that uses devrouter to version 0.0.16.
+
+Changes in this release:
+- New optional `secretManager.command` field in `.devrouter.yml`.
+- When configured, `dev app run` and `dev app exec` automatically wrap user commands with the secret manager command.
+- Devrouter-injected dependency env vars (`DATABASE_URL`, `DIRECT_URL`, `SHADOW_DATABASE_URL`, `*_HOST`, `*_PORT`) are re-applied after the SM boundary via `env KEY=VAL` prefix, ensuring they take precedence over SM-provided values.
+- Env-map targets (`--env-map TARGET=SOURCE`) are also included in the re-injection set.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.16`.
+2) If your app uses a secret manager (Infisical, Doppler, etc.) with devrouter-managed services:
+   a) Add `secretManager.command` to `.devrouter.yml`:
+      ```yaml
+      secretManager:
+        command: infisical run --env dev --
+      ```
+   b) Simplify `hostRun.command` — remove any manual SM wrapping and env-var forwarding prefixes. The bare application command suffices now (e.g., `turbo run dev --no-daemon` instead of `infisical run --env dev -- env DATABASE_URL=${DATABASE_URL} ... turbo run dev --no-daemon`).
+   c) Simplify package.json scripts — remove `infisical run --env dev -- env DATABASE_URL=... DIRECT_URL=... SHADOW_DATABASE_URL=...` prefixes from npm scripts. The bare command is enough when run through `dev app run` or `dev app exec`.
+   d) Simplify shell helper scripts — if you have wrapper scripts that manually forward DB env vars through the SM, those prefixes can be removed.
+3) Note: `DIRECT_URL` is now injected correctly by devrouter (equal to `DATABASE_URL`). Any workaround like `DIRECT_URL=${DATABASE_URL}` can be removed.
+4) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.16` as local repo version
+- `dev doctor --repo <repo>`
+- `dev app run <app> --repo <repo>` starts with SM wrapping (check process tree or env output)
+- `dev app exec <app> --repo <repo> -- env | grep DATABASE_URL` confirms env injection after SM boundary
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- whether `secretManager.command` was added
+- scripts/commands simplified (list before/after)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.17.md

@@ -0,0 +1,37 @@
+You are upgrading a repository that uses devrouter to version 0.0.17.
+
+Changes in this release:
+- `tcpProtocol` now supports `postgres`, `redis`, `mariadb`, and `mysql` (previously postgres-only).
+- TCP ports (5432, 6379, 3306) are only bound to Traefik when a project first starts an app using that protocol. Released on `dev down`.
+- Generic `NAME_HOST`/`NAME_PORT` env vars injected for all TCP deps. Postgres-specific `DATABASE_URL`/`DIRECT_URL`/`SHADOW_DATABASE_URL` still injected only for `tcpProtocol: postgres`.
+- `DevrouterDockerPostgresApp` type renamed to `DevrouterDockerTcpApp`.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.17`.
+2) If your project uses Redis, MariaDB, or MySQL as a TCP-routed service:
+   a) Change the service from `kind: dependency` (non-routed) to a routed TCP app:
+      ```yaml
+      - name: cache
+        host: cache.localhost
+        protocol: tcp
+        tcpProtocol: redis
+        runtime: docker
+        docker:
+          service: redis
+          internalPort: 6379
+          composeFiles:
+            - docker-compose.yml
+      ```
+   b) TLS is required for TCP routing. Run `dev tls install` if not already done.
+3) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.17` as local repo version
+- `dev doctor --repo <repo>` passes
+- `dev app ls --repo <repo>` shows new TCP apps with correct protocol
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- any new TCP apps added (list names and protocols)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.18.md

@@ -0,0 +1,47 @@
+You are upgrading a repository that uses devrouter to version 0.0.18.
+
+Changes in this release:
+- **Breaking**: Shared hardcoded env vars (`DATABASE_URL`, `DIRECT_URL`, `SHADOW_DATABASE_URL`) are no longer auto-injected for postgres deps. Replaced by per-dep deterministic vars.
+- **Breaking**: `--env-map` CLI flag removed. Env var aliasing is now config-only via `envMap` on dependency references.
+- Per-dep deterministic env vars: `{PREFIX}_HOST`, `{PREFIX}_PORT`, `{PREFIX}_URL`, `{PREFIX}_SHADOW_URL` (where `{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")`).
+- Config-level `envMap` on dependency references for backward-compatible aliasing.
+- Protocol-specific URL builders for redis (`redis://localhost:{PORT}`) and mysql/mariadb (`mysql://root@localhost:{PORT}`).
+- Secret manager `{env}` template support with `--env` CLI override and `defaultEnv` config fallback.
+- `dev app run` now checks for already-running host apps before spawning. If the same app (or a different app claiming the same hostname) is already running with a live PID, the command fails with the existing URL, PID, and repo path.
+- Stale host route entries (dead PID) are evicted automatically on run attempt.
+- `dev doctor` includes a new `routes.stale-host-routes` check that cleans up dead-PID entries from `host-routes-state.json`.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.18`.
+2) Update dependency references to use `envMap` for any env vars your app expects under legacy names:
+   ```yaml
+   dependencies:
+     - app: db
+       envMap:
+         DATABASE_URL: DB_URL
+         DIRECT_URL: DB_URL
+         SHADOW_DATABASE_URL: DB_SHADOW_URL
+   ```
+   This maps the new per-dep var `DB_URL` to the legacy `DATABASE_URL` your app code expects.
+3) If you used `--env-map TARGET=SOURCE` on `dev app exec`, move those mappings into `.devrouter.yml` `envMap` on the relevant dependency reference.
+4) If you use a secret manager with `{env}` templating, optionally add `defaultEnv` to your config:
+   ```yaml
+   secretManager:
+     command: infisical run --env {env} --
+     defaultEnv: dev
+   ```
+5) No config changes required for the concurrent run guard — it is automatic.
+6) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.18` as local repo version
+- `dev doctor --repo <repo>` passes (including `routes.stale-host-routes: ok`)
+- `dev app exec <name> --repo <repo> -- env | grep -E "(DB_URL|DATABASE_URL)"` shows both per-dep vars and envMap aliases
+- `dev app run <name>` in one terminal, then again in another terminal: second invocation should fail with the running URL
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- envMap entries added (list target: source pairs)
+- any `--env-map` CLI usages migrated
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.19.md

@@ -0,0 +1,19 @@
+You are upgrading a repository that uses devrouter to version 0.0.19.
+
+Changes in this release:
+- Bugfix: dependency env vars are now injected even when dependency containers are already running. Previously, if deps were already up, the overlay/port-probing step was skipped and env vars were missing.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.19`.
+2) No schema or config migration required — this is a bugfix-only release.
+3) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.19` as local repo version
+- `dev doctor --repo <repo>`
+- With deps already running: `dev app exec <app> --repo <repo> -- env | grep _URL` confirms env injection
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.20.md

@@ -0,0 +1,33 @@
+You are upgrading a repository that uses devrouter to version 0.0.20.
+
+Changes in this release:
+- New app runtime `runtime: proxy`: registers an HTTP route to an already-running `upstream` (`host:port`) and nothing else — no process lifecycle, env injection, `hostRun`, compose ownership, or dependencies. It fronts a devcontainer or any externally-managed process with a stable `*.localhost` host.
+- New `upstream` field in the app schema (proxy apps only). `dev app add` gains `--upstream <host:port>`.
+- Loopback upstreams (`localhost`/`127.0.0.1`/`0.0.0.0`) are rewritten to `host.docker.internal` so Traefik (in Docker) can reach the host.
+- Proxy routes persist until `dev app rm`; they have no PID and are never evicted as stale.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.20`.
+2) No migration is required for existing host/docker/tcp/dependency apps — they are unchanged.
+3) (Optional) If this repo now runs its app inside a devcontainer / external process (so devrouter should only route, not start it), convert the app to a proxy route:
+   ```yaml
+   - name: app
+     host: <name>.localhost
+     protocol: http
+     runtime: proxy
+     upstream: 127.0.0.1:<port>   # the port the devcontainer/process publishes on the host
+   ```
+   Remove that app's `hostRun`/`docker`/`dependencies` (a proxy app owns none of them). Keep datastore apps as-is only if devrouter should still manage them; if the devcontainer owns the datastores, drop those apps too.
+4) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.20` as local repo version
+- `dev doctor --repo <repo>` passes (proxy apps are not flagged as stale routes)
+- `dev app ls --repo <repo>` shows any proxy apps with their `upstream` target
+- With the upstream running and `dev up` + `dev tls install` done: `dev app run <proxy-app> --repo <repo>` prints `Proxy route ready: https://<host> -> <upstream>` and the host serves the upstream
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- any apps converted to `runtime: proxy` (names + upstreams)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.21.md

@@ -0,0 +1,36 @@
+You are upgrading a repository that uses devrouter to version 0.0.21.
+
+Changes in this release:
+- `runtime: proxy` now supports `protocol: tcp` (in addition to `http`). With `protocol: tcp` and a `tcpProtocol` (`postgres`/`redis`/`mariadb`/`mysql`), devrouter registers a Traefik TLS-SNI TCP route — `HostSNI(<host>)` on the shared protocol entrypoint (e.g. `:5432`) — to an `upstream` reachable by name on a shared Docker network. This fronts an externally-managed datastore (e.g. a devcontainer's Postgres on `devnet`) with a stable `db.*.localhost` and no per-DB host port. Pairs with the existing HTTP proxy so N apps + their DBs route through devrouter with zero host-port collisions.
+- TCP proxy routes require TLS (`dev tls install`): SNI is read from the TLS ClientHello. `dev app run` auto-extends the mkcert cert to cover the new host. devrouter emits a per-protocol Traefik `TLSOption` advertising ALPN `postgresql` (libpq direct-SSL mandates it).
+- `dev app add --runtime proxy --protocol tcp --tcp-protocol <postgres|redis|...> --upstream <host:port>` scaffolds a TCP proxy app.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.21`.
+2) No migration is required for existing host/docker/proxy(http)/dependency/tcp(docker) apps — they are unchanged.
+3) (Optional) If a datastore lives in an externally-managed container that joins a shared Docker network devrouter's Traefik is also on (e.g. `devnet`), you can front it with a stable TCP host instead of a published host port:
+   ```yaml
+   - name: db
+     host: db.<name>.localhost
+     protocol: tcp
+     tcpProtocol: postgres
+     runtime: proxy
+     upstream: <container-network-alias>:5432
+   ```
+   The container must join the shared network with that alias and must NOT publish the port on the host.
+4) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.21` as local repo version
+- With TLS on (`dev up` + `dev tls install`) and the upstream container on the shared network: `dev app run <tcp-proxy-app> --repo <repo>` prints `TCP proxy route ready: <proto>://<host>:<port> -> <upstream> (tls required)`
+- Postgres reachable via direct-SSL (the ClientHello must carry the SNI):
+  `psql "host=db.<name>.localhost port=5432 user=<u> password=<p> dbname=<d> sslmode=require sslnegotiation=direct"` (libpq 17+)
+- Redis reachable via TLS+SNI:
+  `redis-cli -h redis.<name>.localhost -p 6379 --tls --sni redis.<name>.localhost --cacert "$(mkcert -CAROOT)/rootCA.pem" PING`
+- `dev doctor --repo <repo>` passes (proxy routes are not flagged as stale)
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- any datastores fronted with `runtime: proxy` + `protocol: tcp` (names + upstreams)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.22.md

@@ -0,0 +1,51 @@
+You are upgrading a repository that uses devrouter to version 0.0.22.
+
+Changes in this release:
+- **Workspace isolation** for parallel git worktrees / agents. A single "workspace token" now spans three layers with one identity: the devpod workspace id (`devpod up --id <ws>`), the routes devrouter registers, and the `${WORKSPACE}` placeholder in `.devrouter.yml` upstreams + the devcontainer compose network alias. Several worktrees of the same repo can run at once without host/route collisions.
+- Token resolution precedence: `--workspace <slug>` flag > `DEVROUTER_WORKSPACE` env var > auto-derived from a linked git worktree branch (sanitized: lowercase, non-alphanumeric → `-`, capped at 32 chars) > none. The primary checkout resolves to no token and routes exactly as before — **fully back-compatible, no behavior change for existing repos**.
+- When a workspace is active: hosts auto-namespace (`web.localhost` → `web.<ws>.localhost`), `${WORKSPACE}` in an app `upstream` is substituted with the token and re-validated, and the docker `router` key is suffixed per workspace. The runtime config is computed in memory only — the committed `.devrouter.yml` is never rewritten. `${WORKSPACE}` is upstream-only (rejected in `host`; the host is auto-namespaced).
+- New `dev workspace` lifecycle: `dev workspace up <branch> [--path <dir>] [--no-devpod] [--open]`, `dev workspace ls [--json]`, `dev workspace down <workspace|branch> [--keep-worktree] [--keep-devpod]`. `dev app run`/`dev app exec` gain `--workspace <slug>`.
+- `dev doctor` now reclaims orphaned workspace proxy routes whose worktree directory was removed without `dev workspace down` (check `routes.orphaned-workspace-routes`). It uses worktree existence as the signal and never touches primary-checkout routes.
+- TLS: namespaced hosts (`web.<ws>.localhost`) are not covered by the `*.localhost` wildcard; devrouter auto-extends the mkcert cert SANs for active hosts when TLS is enabled.
+- Fix: `dev app run` leaves `runtime: docker` target services running after startup; host app runs still stop auto-started docker deps when the host process exits.
+
+Task:
+1) Bump `.devrouter.yml` `devrouter.version` to `0.0.22`.
+2) No migration is required for existing host/docker/proxy/dependency apps — they are unchanged and the primary checkout routes identically.
+3) (Optional — only if you front a devcontainer and want parallel-worktree isolation) Parameterize the proxy upstream with `${WORKSPACE}` and have the devcontainer compose service expose a matching network alias:
+   ```yaml
+   # .devrouter.yml
+   - name: app
+     host: app.localhost           # auto-namespaced to app.<ws>.localhost when a workspace is active
+     protocol: http
+     runtime: proxy
+     upstream: ${WORKSPACE}-app:3000
+   ```
+   ```yaml
+   # devcontainer docker-compose: join devnet with the workspace alias
+   services:
+     app:
+       networks:
+         devnet:
+           aliases:
+             - ${WORKSPACE}-app   # WORKSPACE defaults to <project> in devcontainer.env
+   networks:
+     devnet:
+       external: true
+   ```
+   Default `WORKSPACE=<project>` in the devcontainer env so the primary checkout still resolves a stable alias.
+4) Refresh discoverability artifacts:
+   - `dev repo agents --repo <repo>`
+
+Validation:
+- `dev -V --repo <repo>` shows `0.0.22` as local repo version.
+- Primary checkout unchanged: `dev app run <app> --repo <repo>` registers the same `*.localhost` host as before.
+- Parallel worktree (if adopted): in a linked worktree on branch `feat-a`, `dev workspace up feat-a` (or `DEVROUTER_WORKSPACE=feat-a dev app run <app>`) registers `app.feat-a.localhost` → `feat-a-app`, reachable alongside the primary host.
+- `dev workspace ls` lists each worktree with its token and route count.
+- `dev workspace down feat-a` frees the `feat-a` routes, stops its devpod, and removes the worktree; `dev ls` is clean afterward.
+- `dev doctor --repo <repo>` passes (and reclaims any orphaned workspace routes from removed worktrees).
+
+Report:
+- `.devrouter.yml` `devrouter.version` before/after
+- whether `${WORKSPACE}` upstream parameterization was adopted (and the devcontainer alias used)
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.6.md

@@ -0,0 +1,32 @@
+You are upgrading a repository that uses devrouter to version 0.0.6.
+
+Task:
+1) Update any workflows/scripts that relied on `dev init` side effects:
+   - use `dev init --write-agents --write-skill`, or
+   - run `dev repo agents` after `dev init`.
+2) Audit `dev open <name>` usage:
+   - confirm names remain unambiguous with app-first resolution,
+   - switch to explicit hosts if needed (for example `dev open api.localhost`).
+3) Migrate any `dev ls` table parsing to `dev ls --json` and consume:
+   - `routes[].appName`
+   - `routes[].serviceName`
+   - `routes[].hosts`
+4) Run `dev doctor --repo <repo>` and handle `repo.postgres-credentials` advisories:
+   - align to `POSTGRES_USER/PASSWORD/DB=prisma` where using injected DB URLs, or
+   - keep custom credentials with explicit app/runtime URL management.
+5) If your repo was copied from older demo patterns:
+   - remove hardcoded host-side `DATABASE_URL` overrides,
+   - align compose Postgres defaults to `prisma/prisma/prisma` when using injected env.
+
+Validation:
+- run `dev ls`
+- run updated `dev open` commands
+- run repo automation that consumes routes
+- run `dev doctor --repo <repo>`
+- run app startup with deps (`dev app run <host-app> --yes`)
+
+Report:
+- files/scripts changed
+- command changes made
+- doctor output summary
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.7.md

@@ -0,0 +1,23 @@
+You are upgrading a repository that uses devrouter to version 0.0.7.
+
+Task:
+1) Replace wrapper-recursion or brittle quoted `dev app exec` invocations with argv-safe form:
+   - `dev app exec <app> --yes -- <command ...>`
+2) For commands that require shell expansion, switch to explicit shell mode:
+   - `dev app exec <app> --yes --shell -- "<single shell command string>"`
+3) For non-Prisma apps expecting `DATABASE_URI`, add deterministic env aliasing:
+   - `dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- <command ...>`
+4) If using secret managers (Infisical/Doppler), verify effective DB env before migrate/seed:
+   - `dev app exec <app> --yes --env-map DATABASE_URI=DATABASE_URL -- printenv DATABASE_URL DATABASE_URI DB_HOST DB_PORT SHADOW_DATABASE_URL`
+5) Update onboarding/docs/scripts in your repo to prefer the new primary forms and keep wrapper scripts as fallback only.
+
+Validation:
+- run one migration/seed command through the updated `dev app exec` flow
+- run the env probe command and confirm expected values
+- run `dev doctor --repo <repo>`
+
+Report:
+- commands/scripts updated
+- env-map usage introduced (if any)
+- probe output summary
+- unresolved risks/ambiguities

package/upgrade-prompts/0.0.8.md

@@ -0,0 +1,26 @@
+You are upgrading a repository that uses devrouter to version 0.0.8.
+
+Task:
+1) Refresh discoverability artifacts with the installed CLI version:
+   - `dev repo agents --repo <repo>`
+2) If your team wants Linear-backed milestone workflow assets, bootstrap them explicitly:
+   - `dev repo agents --repo <repo> --with-linear`
+   - or `dev init --repo <repo> --with-linear --write-agents --write-skill`
+3) Ensure AGENTS.md now references both skills when Linear workflow is enabled:
+   - `.factory/skills/devrouter/SKILL.md`
+   - `.factory/skills/linear-workflow/SKILL.md`
+4) Adopt the linear-workflow templates for new milestone tracking:
+   - `references/LINEAR_ISSUE_TEMPLATE.md`
+   - `references/MILESTONE_PLAN_TEMPLATE.md`
+   - `references/PROGRESS_UPDATE_TEMPLATE.md`
+5) Use devrouter release guidance from `https://github.com/rschlaefli/devrouter/blob/main/CHANGELOG.md` (latest Agent Adaptation Prompt); this does not require adding `CHANGELOG.md` to the target repository unless that repository already has its own policy.
+
+Validation:
+- run `dev init --repo <repo> --with-linear` and confirm the prompt includes "Linear milestone workflow"
+- run `dev repo agents --repo <repo> --with-linear` and confirm Linear skill/template files exist
+- run `dev doctor --repo <repo>`
+
+Report:
+- whether Linear workflow bootstrap was enabled
+- artifacts created/updated
+- any repo-specific deviations from the template policy

package/upgrade-prompts/0.0.9.md

@@ -0,0 +1,30 @@
+You are upgrading a repository that uses devrouter to version 0.0.9.
+
+Task:
+1) Refresh discoverability artifacts with the installed CLI version:
+   - `dev repo agents --repo <repo>`
+2) If Linear workflow is enabled in this repository, re-run with guided metadata capture:
+   - `dev repo agents --repo <repo> --with-linear`
+3) Confirm AGENTS.md contains one managed Linear metadata block between:
+   - `<!-- devrouter-linear-workflow-config:start -->`
+   - `<!-- devrouter-linear-workflow-config:end -->`
+4) Ensure required mapping fields are set (no placeholders left):
+   - `linear.workspace.name`
+   - `linear.team.name`
+   - `linear.project.name`
+5) If placeholders exist from non-interactive runs, re-run the command in an interactive TTY and provide workspace/team/project values.
+6) For Linear-tracked implementation, enforce execution hygiene:
+   - set issue status at session start and each phase transition
+   - post progress comments at meaningful checkpoints during implementation
+   - post an end-of-session recap comment and re-check status/comment freshness before stopping
+
+Validation:
+- run `dev init --repo <repo> --with-linear` and confirm guided Linear questions appear
+- run `dev repo agents --repo <repo> --with-linear` and confirm AGENTS metadata block is populated
+- run `dev doctor --repo <repo>`
+
+Report:
+- final workspace/team/project mapping stored in AGENTS
+- whether placeholders were replaced
+- any unresolved mapping ambiguity
+- confirmation that Linear status/comment cadence was followed during execution and at session end