@devrouter/cli 0.0.25 → 0.0.27

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.
@@ -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.
 
@@ -370,6 +403,18 @@ 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.
 
+## Development quality
+
+`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.
+
+Pre-commit hooks run on every commit once installed:
+
+```sh
+pre-commit install
+```
+
+Hooks run Biome safe fixes, Knip, Gitleaks secret scanning, and basic file checks (trailing whitespace, merge conflict markers, large file guard).
+
 ## Known limitations (v1)
 
 - Host-runtime dependencies are not auto-started; only Docker dependencies are auto-started.