@devrouter/cli 0.0.24 → 0.0.26

package/README.md

@@ -2,18 +2,32 @@
 
 Local-first routing for macOS development with one shared Traefik router.
 
+## AI Agent Onboarding
+
+If you are pair programming with an AI agent (such as Cursor, GitHub Copilot, Gemini, or Claude) to onboard or work on a repository, run the following command at the very start to generate a ready-to-copy, context-rich onboarding prompt for the agent:
+
+```bash
+# Using npm/npx:
+npx @devrouter/cli init --repo .
+
+# Or using pnpm/pnpm dlx:
+pnpm dlx @devrouter/cli init --repo .
+```
+
+This prints a canonical prompt containing the full config schemas, best-practice workflows, docker dependency configurations, and verification commands required to configure the repo's devrouter setup.
+
 ## What it solves
 
 Run multiple repos concurrently without manual port juggling:
 
 - HTTP apps by hostname: `web.localhost`, `api.localhost`
-- PostgreSQL DBs by hostname on shared `:5432` via TLS/SNI: `db.localhost`
+- Databases (Postgres, Redis, MariaDB, MySQL) by hostname on their standard shared ports via TLS/SNI: `db.localhost`, `redis.localhost`
 
 Traefik owns:
 
 - `:80` (HTTP)
 - `:443` (HTTPS)
-- `:5432` (Postgres TCP routing)
+- Shared protocol ports for activated databases (e.g. `:5432`, `:6379`, `:3306`)
 
 ## Unified repo config
 
@@ -51,6 +65,12 @@ devrouter repo devcontainer verify --live --yes --json
 
 Why prefer it: the environment is reproducible and runs anywhere the devcontainer
 spec runs, while devrouter gives it stable local HTTPS and database hostnames.
+
+We recommend **DevPod** to orchestrate the devcontainer lifecycle locally because:
+- **IDE/Editor Independence**: DevPod manages the container lifecycle and code synchronization in the background, allowing developers to use any local editor (VS Code, JetBrains, vim) with the containerized toolchain.
+- **No Vendor Lock-in**: It is a client-only, open-source runner that runs entirely locally on Docker without requiring Microsoft's proprietary VS Code extensions or cloud-based runners.
+- **devrouter Integration**: DevPod spins up the devcontainer compose stack on the `devnet` network, and devrouter handles dynamic HTTPS domain routing (`*.localhost`), making manual port-forwarding management obsolete.
+
 Agents can add the scaffold with `devrouter repo inspect`, `devrouter repo devcontainer write`,
 and `devrouter repo devcontainer verify`, then include the JSON evidence in a PR. See
 [`docs/DEVCONTAINER.md`](./docs/DEVCONTAINER.md) for the full reference.
@@ -63,7 +83,7 @@ vars. Use it when you are not (yet) on a devcontainer. Fully supported.
 
 ## Core commands
 
-- `devrouter init [--repo <path>] [--entries-json <json>] [--json] [--write-agents] [--write-skill] [--with-linear]`
+- `devrouter init [--repo <path>] [--entries-json <json>] [--json] [--write-agents] [--write-skill]`
 - `devrouter -V [--repo <path>]` (installed CLI version, local repo version, next upgrade target)
 - `devrouter upgrade [version] [--repo <path>]`
 - `devrouter setup --yes [--repo <path>] [--json]`
@@ -78,7 +98,7 @@ vars. Use it when you are not (yet) on a devcontainer. Fully supported.
 - `devrouter repo inspect [--repo <path>] [--json]`
 - `devrouter repo devcontainer write [--repo <path>] [--dry-run] [--yes] [--json]`
 - `devrouter repo devcontainer verify [--repo <path>] [--live] [--yes] [--json]`
-- `devrouter repo agents [--repo <path>] [--with-linear]`
+- `devrouter repo agents [--repo <path>]`
 - `devrouter app add ...` (`--kind app|dependency`, default `app`)
 - `devrouter app ls [--repo <path>] [--json]`
 - `devrouter app run <name> [--repo <path>] [--yes] [--workspace <slug>]`
@@ -86,6 +106,7 @@ vars. Use it when you are not (yet) on a devcontainer. Fully supported.
 - `devrouter app rm <name> [--repo <path>]`
 - `devrouter logs [-f]`
 - `devrouter workspace up <branch> [--path <dir>] [--no-devpod] [--open] [--repo <path>]`
+- `devrouter workspace ensure [path] [--open]`
 - `devrouter workspace ls [--repo <path>] [--json]`
 - `devrouter workspace down <workspace|branch> [--keep-worktree] [--keep-devpod] [--repo <path>]`
 
@@ -100,12 +121,12 @@ mutate local route state.
 
 A **workspace token** lets several git worktrees of the same repo run side-by-side without host or route collisions. The token is a single identity spanning three layers: the devpod workspace id, the routes devrouter registers, and the `${WORKSPACE}` placeholder in `.devrouter.yml` proxy upstreams and devcontainer compose network aliases.
 
-**Token resolution precedence** (highest to lowest):
-
-1. `--workspace <slug>` CLI flag
-2. `DEVROUTER_WORKSPACE` environment variable
-3. Auto-derived from the linked git worktree's branch name (sanitized: lowercase, non-alphanumeric → `-`, capped at 32 chars)
-4. None — the primary checkout uses no token and routes exactly as a plain repo (back-compatible)
+Each linked worktree stores one stable identity in its Git metadata. Once stored,
+that value is authoritative: an explicit flag or `DEVROUTER_WORKSPACE` may repeat
+it but cannot silently rename the environment. On first use, devrouter reuses the
+exact DevPod already bound to the worktree path or derives a sanitized identity
+from the linked branch/path. Ambiguous identities and DevPods owned by another
+worktree fail closed. The primary checkout keeps its plain, non-namespaced routes.
 
 **When a workspace token is active:**
 
@@ -122,6 +143,9 @@ A **workspace token** lets several git worktrees of the same repo run side-by-si
 # Bring up a feature branch as an isolated workspace
 devrouter workspace up feat/my-feature
 
+# Reconcile an existing linked worktree (canonical agent startup command)
+devrouter workspace ensure .
+
 # List git worktrees with workspace tokens and route counts
 devrouter workspace ls
 
@@ -129,7 +153,16 @@ devrouter workspace ls
 devrouter workspace down feat/my-feature
 ```
 
-**devcontainer integration:** the devcontainer compose service exposes a devnet network alias `${WORKSPACE}-app` (defaulting to the project name in `devcontainer.env`); the proxy app uses `upstream: ${WORKSPACE}-app:<port>`. Workspace `feat-a` → alias `feat-a-app`, host `app.feat-a.localhost`.
+New worktrees default to the repository's ignored `trees/<workspace>` directory; use `--path` only when a repository intentionally follows another layout.
+
+**devcontainer integration:** the devcontainer compose service exposes a devnet network alias `${WORKSPACE}-app` (defaulting to the project name in `devcontainer.env`); the proxy app uses `upstream: ${WORKSPACE}-app:<port>`. `.devcontainer/docker-compose.devrouter.yml` passes `WORKSPACE` and `DEVROUTER_WORKSPACE` into the app and bind-mounts `${DEVROUTER_GIT_COMMON_DIR}` to the same absolute container path, so linked-worktree `.git` pointers remain valid. Workspace `feat-a` → alias `feat-a-app`, host `app.feat-a.localhost`.
+
+`workspace ensure` is intentionally proof-driven: it verifies exact worktree
+ownership, the compose overlay and Git mount, workspace env, devnet aliases,
+container health, Git access, HTTP route reachability, and unique running TCP
+upstream ownership (plus health when configured) before reporting ready. It
+retries one stale DevPod with `--recreate`; failed proof does not leave new routes
+behind.
 
 **Try it:** [`examples/workspace/`](examples/workspace/) is a runnable showcase — `./run.sh` brings up one app in two parallel worktrees (`wsdemo.localhost` and `wsdemo.feat-a.localhost`) served at once, then `./run.sh down` tears it down.
 
@@ -187,14 +220,6 @@ Optional repo artifact writes are explicit:
 devrouter init --repo /absolute/path/to/repo --write-agents --write-skill
 ```
 
-Optional: also bootstrap Linear workflow skill/templates and AGENTS section:
-
-```bash
-devrouter init --repo /absolute/path/to/repo --with-linear --write-agents --write-skill
-```
-
-When `--with-linear` is combined with AGENTS writes, devrouter captures minimal Linear mapping (workspace, team, project). In non-interactive mode it writes placeholders and prints a warning so values can be filled in later.
-
 ## Health diagnostics
 
 Run check-only diagnostics for global router state, machine prerequisites, route state, and repo configuration:
@@ -378,38 +403,17 @@ See details:
 
 `devrouter repo agents` writes a devrouter section into the repo's `AGENTS.md` and installs a skill file at `.agents/skills/devrouter/SKILL.md`. The skill content is embedded in the CLI bundle so it stays in sync across repos.
 
-If you also want Linear workflow assets and repository mapping metadata, run:
-
-```bash
-devrouter repo agents --with-linear
-```
+## Development quality
 
-This additionally installs:
+`pnpm check` runs Biome formatting, lint, and import-order checks. `pnpm check:fix` applies safe fixes automatically. `pnpm knip` detects unused files, dependencies, and unresolved imports. `pnpm typecheck` runs TypeScript checks across the repo.
 
-- `.agents/skills/linear-workflow/SKILL.md`
-- `.agents/skills/linear-workflow/references/LINEAR_ISSUE_TEMPLATE.md`
-- `.agents/skills/linear-workflow/references/MILESTONE_PLAN_TEMPLATE.md`
-- `.agents/skills/linear-workflow/references/PROGRESS_UPDATE_TEMPLATE.md`
+Pre-commit hooks run on every commit once installed:
 
-and appends an idempotent `linear-workflow` section to `AGENTS.md`.
-
-With `--with-linear`, AGENTS also stores a managed config block:
-
-- `<!-- devrouter-linear-workflow-config:start -->`
-- `<!-- devrouter-linear-workflow-config:end -->`
-
-The block captures:
-
-- `workspace.name`
-- `team.name` (optional `team.key`)
-- `project.name` (optional `project.id`)
-
-Required Linear execution hygiene:
+```sh
+pre-commit install
+```
 
-1. Set issue status at session start and update it at each phase transition.
-2. Post progress comments at meaningful checkpoints during implementation.
-3. Before ending a session, post a final comment with completed work, remaining work, risks, and next step.
-4. Re-check status and comment freshness toward/at session end before stopping.
+Hooks run Biome safe fixes, Knip, Gitleaks secret scanning, and basic file checks (trailing whitespace, merge conflict markers, large file guard).
 
 ## Known limitations (v1)