@basaltbytes/odoo-agentic-dev 0.1.0-beta.1

package/README.md

@@ -0,0 +1,464 @@
+# @basaltbytes/odoo-agentic-dev
+
+`odoo-agentic-dev` (short alias: `oad`) is an agent-friendly local Odoo development runtime. From the current Git worktree it derives a deterministic database name, deterministic ports, and a namespaced Docker Compose project, then drives the full lifecycle around them: set up a fresh checkout, start Odoo and PostgreSQL, reset and re-initialize the database, update modules, run tests, and start optional companion apps such as a Vite PWA — each branch, agent session, or bug reproduction gets its own isolated stack that cannot collide with the others.
+
+Projects describe themselves with one typed recipe file (`odoo-agentic-dev.config.ts`) instead of copied shell scripts and Compose files. The CLI is built for non-interactive use: flags replace prompts, output is deterministic, `info --json` exposes the whole resolved context to tooling, and destructive actions are guarded so a coding agent (or a tired human) cannot accidentally delete a shared database.
+
+## Requirements
+
+- Node.js 22.15 or newer (the state registry uses the built-in `node:sqlite` — no native dependency)
+- [pnpm](https://pnpm.io)
+- Docker (Docker Desktop on macOS, Docker Engine on Linux) — `info` works without it
+- Windows: **WSL2 only**. Native PowerShell / `cmd.exe` execution is not supported in v1.
+
+WSL2 guidance:
+
+- clone repositories inside the WSL filesystem, not under `/mnt/c`
+- install Node, package manager, Git, and Docker CLI inside WSL
+- enable Docker Desktop WSL integration
+- pass paths as Linux paths
+
+## Quickstart
+
+```bash
+pnpm add -D @basaltbytes/odoo-agentic-dev
+```
+
+Create `odoo-agentic-dev.config.ts` at the project root (also accepted: `.mts`, `.js`, `.mjs` — `.ts` configs load directly, no precompilation needed). For an Odoo-only project:
+
+```ts
+import { defineConfig } from "@basaltbytes/odoo-agentic-dev";
+
+export default defineConfig({
+  project: {
+    id: "billing-odoo",
+    dbPrefix: "billing",
+    sharedDatabase: "billing_dev",
+    sharedBranches: ["main", "develop"]
+  },
+
+  odoo: {
+    version: "18.0",
+    dockerfile: "Dockerfile",
+    configFile: "config/odoo.conf",
+    addons: [
+      { host: "addons", container: "/mnt/extra-addons/custom" }
+    ]
+  },
+
+  database: {
+    initialModules: ["billing_core"]
+  }
+});
+```
+
+For a KRISS LAURE-like monorepo with a frontend companion app:
+
+```ts
+import { defineConfig } from "@basaltbytes/odoo-agentic-dev";
+
+export default defineConfig({
+  project: {
+    id: "kriss-laure",
+    dbPrefix: "kl",
+    sharedDatabase: "kl_e2e_demo",
+    sharedBranches: ["main", "master", "dev", "develop", "development"]
+  },
+
+  ports: {
+    odooBase: 18069,
+    companionBase: 28028,
+    range: 1000,
+    hashAlgorithm: "posix-cksum"
+  },
+
+  odoo: {
+    version: "18.0-20250606",
+    serviceName: "odoo",
+    databaseServiceName: "db",
+    configFile: "config/odoo.worktree.conf",
+    dockerfile: "Dockerfile.odoo",
+    imageName: "krisslaure-odoo-agentic-dev",
+    addons: [
+      { host: "backend/addons/Custom", container: "/mnt/extra-addons/Custom" },
+      { host: "backend/addons/OCA", container: "/mnt/extra-addons/OCA" }
+    ]
+  },
+
+  database: {
+    initialModules: ["KL_setup", "KL_payment_demo"],
+    withoutDemo: "all",
+    postInit: [
+      { type: "odoo-shell-file", file: "scripts/odoo-agentic-dev/post-init.py" }
+    ]
+  },
+
+  setup: {
+    submodules: true,
+    packageManagers: [
+      { cwd: ".", command: "pnpm", args: ["install"] },
+      { cwd: "frontend", command: "pnpm", args: ["install"] }
+    ]
+  },
+
+  worktree: {
+    copyFiles: [".env.e2e"],        // project-root files copied into a fresh worktree when present
+    branchPrefix: "worktree-"       // branch name for `worktree create <name>` (default)
+  },
+
+  companionApps: [
+    {
+      name: "pwa",
+      cwd: "frontend",
+      command: "pnpm",
+      args: ["dev", "--host", "0.0.0.0", "--strictPort"],
+      portEnv: "PWA_PORT",
+      urlEnv: "E2E_BASE_URL",
+      env: {
+        VITE_SERVICE_API_URL: "",
+        VITE_ODOO_DATA_BASE_NAME: "$ODOO_DATABASE",
+        VITE_E2E_PROXY_API_URL: "$ODOO_BASE_URL"
+      }
+    }
+  ]
+});
+```
+
+Ports are derived from a hash of the database name modulo `ports.range`. The default hash is FNV-1a 32-bit (`hashAlgorithm: "fnv1a32"`); set `hashAlgorithm: "posix-cksum"` to reproduce the POSIX `cksum` CRC so a project migrating from bash tooling that derives ports via `cksum <<< "$db"` keeps the exact same port per database.
+
+Database names are derived from the branch: at most **one** leading type segment (`feature`, `feat`, `bugfix`, `bug`, `hotfix`, `fix`, `chore`, `task`) is stripped — `feature/fix/x` becomes `<dbPrefix>_fix_x` — then the remainder is sanitized and prefixed with `project.dbPrefix`. Set `project.stripBranchPrefixes` (for example `["release"]`) to replace the built-in list.
+
+Then:
+
+```bash
+pnpm exec odoo-agentic-dev setup   # prepare the worktree (deps, image, database)
+pnpm exec odoo-agentic-dev up      # start Odoo + companion apps
+pnpm exec odoo-agentic-dev info    # inspect the derived context at any time
+```
+
+## Commands
+
+Every command accepts `--config <path>` to point at an explicit recipe file; otherwise the recipe is discovered from the current working directory upward.
+
+### `odoo-agentic-dev info`
+
+Print the resolved worktree context (worktree name, database, Compose project, Odoo URL, companion URLs) without starting containers. Works without Docker running and is deterministic for the same branch and recipe.
+
+| Flag | Meaning |
+| --- | --- |
+| `--json` | print machine-readable JSON |
+| `--env` | print `KEY=value` env lines |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev setup`
+
+Prepare a new worktree: initialize Git submodules (if the recipe asks for it), run the recipe's package manager install steps, ensure the Docker image builds, reset and initialize the current worktree database, run post-init hooks, and print URLs. It prints the resolved database before destructive work and never deletes a shared database by default. The database step honors the same template fast-reset semantics as `reset-db` (see below).
+
+| Flag | Meaning |
+| --- | --- |
+| `--skip-install` | skip submodule + package manager steps |
+| `--skip-db` | skip database reset/initialization |
+| `--allow-shared` | permit acting on the shared database |
+| `--no-template` | full init even when a template snapshot exists (template kept) |
+| `--refresh-template` | full init and take a fresh template snapshot |
+| `--json` | suppress decorative output; print one final JSON report line |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev up`
+
+Start Odoo (and PostgreSQL) on the derived port, then the configured companion apps with context-derived env injected (`ODOO_DATABASE`, `ODOO_BASE_URL`, per-app ports). In attached mode, Ctrl-C stops all child processes and the first failing process is reported.
+
+Before starting anything, `up` probes the derived Odoo port. If it is busy and the holder is not this worktree's own already-running stack (idempotent `up`), it fails fast with a `PortConflictError` naming the holder stack when the state registry knows it — set `ODOO_HTTP_PORT` to override, or `prune` stale environments.
+
+| Flag | Meaning |
+| --- | --- |
+| `--odoo-only` | skip companion apps |
+| `--no-build` | start containers without rebuilding the image |
+| `--logs` | follow Odoo logs after start |
+| `--detach` | start containers and return |
+| `--json` | suppress decorative output; print one final JSON report line |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev down`
+
+Stop the current worktree stack. Uses the derived Compose project name, so other worktrees are never affected. A plain `down` keeps the environment in the state registry (only refreshing its last-used time); `down --volumes` removes the registry row along with the volumes.
+
+| Flag | Meaning |
+| --- | --- |
+| `--volumes` | also remove this worktree's volumes (guarded for shared databases) |
+| `--allow-shared` | permit acting on the shared database |
+| `--json` | suppress decorative output; print one final JSON report line |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev reset-db`
+
+Delete and recreate the current worktree database and filestore, terminate active database sessions first, install the initial modules, and run post-init hooks. Refuses unsafe database names.
+
+| Flag | Meaning |
+| --- | --- |
+| `--allow-shared` | permit resetting the shared database |
+| `--modules <list>` | comma-separated module list (defaults to the recipe's `initialModules`) |
+| `--without-demo <mode>` | demo-data mode passed straight to Odoo's `--without-demo` |
+| `--no-template` | full init even when a template snapshot exists (template kept) |
+| `--refresh-template` | full init and take a fresh template snapshot |
+| `--json` | suppress decorative output; print one final JSON report line |
+| `--config <path>` | explicit config file path |
+
+Demo data is controlled at database initialization time, not per test run. The recipe's `database.withoutDemo` sets the default: a string mode (for example `"all"`) is passed to Odoo's `--without-demo`, while `withoutDemo: false` omits the flag entirely so Odoo installs demo data. The `--without-demo <mode>` flag overrides the recipe for one reset, passing the mode string straight through to Odoo.
+
+#### Template fast reset
+
+The first successful full init (from `setup` or `reset-db`) is snapshotted — after the post-init hooks — as a PostgreSQL template database named `<database>__tpl` plus a filestore copy. Subsequent `reset-db` runs restore from that template in seconds instead of re-running module installation; post-init hooks are **not** re-run on restore because their effects are baked into the snapshot.
+
+Snapshots carry a key derived from `initialModules`, `withoutDemo`, `odoo.version`, and the `postInit` hooks. Changing any of these invalidates the template: the next `reset-db` automatically falls back to a full init and takes a fresh snapshot. One-off `--modules`/`--without-demo` overrides always force a full init without touching the stored template.
+
+- `--no-template` forces a full init for one run, keeping the existing snapshot.
+- `--refresh-template` forces a full init and replaces the snapshot.
+- PostgreSQL is per-stack, so templates only accelerate resets within the same worktree.
+- Database names are budgeted so `<database>__tpl` fits PostgreSQL's 63-char identifier limit (derived names are capped at 58 chars); an explicitly overridden name longer than 58 chars simply skips snapshotting.
+
+### `odoo-agentic-dev update <modules>`
+
+Update modules in the current worktree database. Starts PostgreSQL if needed, stops Odoo before the update when needed, and restarts Odoo after a successful update unless `--no-restart` is passed.
+
+```bash
+pnpm exec odoo-agentic-dev update KL_setup
+pnpm exec odoo-agentic-dev update KL_base,KL_sale,KL_stock
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--no-restart` | do not restart Odoo after the update |
+| `--json` | suppress decorative output; print one final JSON report line |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev test`
+
+Run Odoo tests against the current worktree database. Options map to Odoo CLI flags, the exit code is non-zero on test failure, and recipes may define reusable test profiles (`test.profiles`) selected with `--profile`.
+
+| Flag | Meaning |
+| --- | --- |
+| `--tags <tags>` | Odoo `--test-tags` value |
+| `--file <path>` | Odoo `--test-file` value |
+| `--module <name>` | restrict tests to a module |
+| `--log-level <level>` | Odoo log level |
+| `--profile <name>` | recipe-defined test profile (extra Odoo args) |
+| `--include-demo` | accepted for compatibility; demo data is controlled at database init in v1 (see `reset-db`) |
+| `--json` | suppress decorative output; print one final JSON report line (includes `exitCode`) |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev link-source`
+
+Create or refresh a local Odoo source pointer such as `.odoo` (a symlink on macOS/Linux/WSL2). Resolution order: `--target`, then the recipe's `odoo.source` (unless it is `"docker-only"`) — both used as-is without validation — then discovery: the conventional `../odoo` sibling checkout, then `<dirname>/odoo` next to every git worktree of the project. A discovered candidate counts only if it looks like an Odoo source checkout (contains `odoo-bin`, `odoo/` and `addons/`); when none qualifies the error lists every candidate checked. It refuses to overwrite anything that is not a symlink, and replaces an existing symlink only with `--force`. The runtime never requires this link; it exists for IDE navigation and direct source inspection.
+
+| Flag | Meaning |
+| --- | --- |
+| `--target <path>` | explicit source checkout path (absolute or relative to the project root) |
+| `--name <link-name>` | link name (default `.odoo`) |
+| `--force` | replace an existing symlink |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev list`
+
+List the environments this machine's state registry knows about, reconciled against Docker reality: status is `running`, `stopped`, or `vanished` (row exists, Docker stack is gone). Labeled Docker stacks that are missing from the registry are adopted into it on sight. Output columns: worktree, database, port, status, relative last-used time, and `shared`/`template` markers. Listing never modifies or removes environments.
+
+| Flag | Meaning |
+| --- | --- |
+| `--all-projects` | every project in the registry (works without a config) |
+| `--json` | print the full rows + status as JSON |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev prune`
+
+Garbage-collect dead environments. By default only clearly-dead targets are candidates: `gone-branch` (root dir exists, is a repo, the recorded branch was deleted), `gone-rootdir` (the worktree directory no longer exists), and `vanished` (registry row with no Docker stack — row-only cleanup). Age alone never makes a candidate unless you pass `--older-than <days>`.
+
+The safety contract:
+
+- Without `--yes`, `prune` is a dry run: it prints the kill list (stack, database, age, reason) and exits 1 when candidates exist, 0 when there are none. Nothing is removed.
+- With `--yes`, teardown is label-based (`docker rm -f` + `docker volume rm` by Compose project label), so it works even when the original compose file is gone; the registry row is removed last.
+- Shared environments are always skipped unless `--allow-shared` is passed.
+- The environment a command is currently running in is never an auto-clean candidate.
+
+| Flag | Meaning |
+| --- | --- |
+| `--older-than <days>` | also prune environments unused for more than `<days>` |
+| `--all-projects` | every project in the registry (works without a config) |
+| `--yes` | actually remove (without it: dry run, exit 1 when candidates exist) |
+| `--allow-shared` | permit pruning shared environments |
+| `--json` | print the candidates/removals report as JSON |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev doctor`
+
+Environment health report (`✓`/`✗` per check, or `--json`): Docker daemon responsive, Compose is v2, Node >= 22.15, config discovery + validation (soft when absent), context derivation, Odoo port free or its holder identified, port collisions among known stacks, state registry openable and writable, git on PATH, WSL2 detection with setup guidance, and the current prune-candidate count. Exits 1 if any hard check fails.
+
+| Flag | Meaning |
+| --- | --- |
+| `--json` | print the checks array as JSON |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev logs [service]`
+
+Stream `docker compose logs` for one service of the current worktree stack (default: the Odoo service).
+
+| Flag | Meaning |
+| --- | --- |
+| `--follow` | follow log output |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev shell`
+
+Open an interactive `odoo shell` against the current worktree database (`docker compose run --rm <odoo> odoo shell -d <database>`), with full TTY passthrough. The child's exit code becomes the command's exit code.
+
+### `odoo-agentic-dev psql [-- <args>]`
+
+Open `psql` inside the database container connected to the current worktree database. Extra `psql` arguments pass through after `--`:
+
+```bash
+pnpm exec odoo-agentic-dev psql -- -c 'SELECT count(*) FROM res_partner;'
+```
+
+### `odoo-agentic-dev run [--env-file <path>]... -- <command> [args...]`
+
+Execute any host command with the worktree environment injected — the assembled context env (`ODOO_DATABASE`, `ODOO_HTTP_PORT`, companion ports/URLs, aliases) layered over the parent environment. Each `--env-file` (repeatable) is a dotenv-style file (`KEY=value` lines, `#` comments, optional surrounding quotes stripped) whose pairs are explicit overrides: parent env < context env < env files, later files win. The child runs with full TTY passthrough and its exit code becomes the command's exit code.
+
+```bash
+pnpm exec odoo-agentic-dev run -- pnpm test:e2e
+pnpm exec odoo-agentic-dev run --env-file .env.e2e -- playwright test
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--env-file <path>` | dotenv-style overrides, repeatable (later files win; missing file = error) |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev compose -- <compose-args...>`
+
+`docker compose` passthrough scoped to this worktree's stack: the canonical preamble (`-p <project>`, `-f <compose-file>`, `--project-directory`, context env) is prepended and the trailing arguments land verbatim, with full stdio inheritance — `logs -f` streams, interactive `exec` works. The child's exit code becomes the command's exit code.
+
+```bash
+pnpm exec odoo-agentic-dev compose -- ps
+pnpm exec odoo-agentic-dev compose -- logs -f --tail 100 odoo
+pnpm exec odoo-agentic-dev compose -- exec db bash
+```
+
+### `odoo-agentic-dev worktree create <name>`
+
+Create a git worktree and run the full `setup` flow inside it: best-effort `git fetch origin`; base ref from `--base`, else `ODOO_WORKTREE_BASE_REF`, else origin's HEAD, else `HEAD`; `git worktree add -b <branchPrefix><name> <path> <base>`; copy the recipe's `worktree.copyFiles` that exist in the project root; then deps + image + database against the worktree as project root. Prints the worktree path when done.
+
+With `--hook-json` (the Claude Code WorktreeCreate hook contract) the `{worktree_name, worktree_path}` payload is read from stdin, all human output goes to stderr, and stdout carries exactly one line — the final worktree path. If setup fails in hook mode the half-made worktree is force-removed and the command exits non-zero so the hook aborts the creation.
+
+| Flag | Meaning |
+| --- | --- |
+| `--path <path>` | worktree directory (default: sibling `<repo-basename>-<name>`) |
+| `--base <ref>` | base ref for the new branch |
+| `--hook-json` | Claude Code hook mode (payload on stdin, path-only stdout) |
+| `--config <path>` | explicit config file path |
+
+### `odoo-agentic-dev worktree remove <path>`
+
+Tear down a worktree's environment. When the directory still has a discoverable config, its own context is resolved and the stack goes down with volumes (`down --volumes` semantics) before the registry row is removed; a shared database is never torn down without `--allow-shared` (logged and skipped instead). When the directory is already gone, the identity is rebuilt from the directory name against the current project root and the teardown is label-based — the same machinery `prune` uses, no compose file needed. The directory itself is not deleted (git owns that).
+
+With `--hook-json` (the WorktreeRemove hook contract) the `{worktree_path}` payload is read from stdin and the command **always exits 0** — a removal hook cannot block — logging each step to `--log-file` (directory created) when given, stderr otherwise.
+
+| Flag | Meaning |
+| --- | --- |
+| `--hook-json` | Claude Code hook mode (payload on stdin, always exit 0) |
+| `--allow-shared` | permit tearing down the shared database |
+| `--log-file <path>` | append step logs to this file |
+| `--config <path>` | explicit config file path |
+
+## Machine-Readable Output (`--json`)
+
+`info`, `list`, `doctor`, and `prune` have dedicated JSON shapes and keep stdout pure JSON (warnings go to stderr).
+
+The lifecycle commands — `setup`, `up`, `down`, `reset-db`, `update`, `test` — accept `--json` too: decorative output is suppressed and one final single-line JSON object is printed to stdout:
+
+```json
+{ "ok": true, "command": "reset-db", "database": "kl_feature_x", "composeProject": "kl_kl_feature_x", "odooUrl": "http://127.0.0.1:18119/web?db=kl_feature_x", "actions": ["restore-from-template"], "durationMs": 4180, "exitCode": 0 }
+```
+
+`actions` records what the command did (for `reset-db`/`setup` it includes `restore-from-template` or `full-init` + `snapshot-template`, so tooling can tell which reset path ran); `exitCode` appears when the command ran a child to completion (`test`). Streamed child output (image builds, Odoo logs) may still precede the report, so parse the **last line** of stdout (`tail -n 1 | jq`). On failure the object is emitted with `"ok": false` before the error is rendered on stderr.
+
+## State Registry
+
+Every lifecycle command records its environment (compose project, database, root dir, branch, port, timestamps, template metadata) in a machine-global SQLite registry at `${XDG_DATA_HOME:-~/.local/share}/odoo-agentic-dev/state.db`, overridable via the `ODOO_AGENTIC_DEV_STATE_DB` environment variable. It needs no setup and no external dependency (built-in `node:sqlite`, hence Node >= 22.15).
+
+The registry is an index — Docker is the truth. Generated compose files stamp `dev.basaltbytes.oad.*` identity labels on services and volumes so `list`/`prune`/`doctor` can reconcile rows against reality and re-adopt stacks whose rows were lost. Project-supplied compose files (recipe `compose.file`) are not labeled; those environments are tracked by their registry rows alone.
+
+## Automatic Cleanup
+
+```ts
+cleanup: {
+  maxAgeDays: 30,  // staleness threshold used by the auto/warn hook
+  auto: false      // false (default): warn only; true: prune automatically
+}
+```
+
+At the end of `up` and `setup`, the registry is checked for dead environments of the current project. With `auto: false` (the default) a one-line warning is printed when candidates exist (`N stale environment(s) — run odoo-agentic-dev prune`). With `auto: true` the prune routine runs immediately for gone/vanished environments and those unused for more than `maxAgeDays`, never touching shared environments or the environment the command is running in, and prints what it removed.
+
+## Network Exposure
+
+The generated Compose file binds Odoo to the loopback interface only (`127.0.0.1:<port>:8069`): another machine on your LAN can never reach a dev Odoo by default. To expose a stack deliberately, supply your own compose file via the recipe's `compose.file` with the port mapping you want (for example `"0.0.0.0:8069:8069"`) — deliberate exposure is a project decision, not a CLI flag.
+
+Every compose subprocess runs with the full context env exported (the same variables `info --env` prints, merged over the parent environment), so a project-supplied compose file can interpolate `${ODOO_DATABASE:?}` or `${ODOO_HTTP_PORT:?}` directly.
+
+## Environment Variables
+
+| Variable | Meaning |
+| --- | --- |
+| `ODOO_DATABASE` | Current worktree Odoo database |
+| `E2E_ODOO_DB` | Alias for test tooling |
+| `ODOO_BASE_URL` | Odoo HTTP origin |
+| `ODOO_HTTP_PORT` | Host port for Odoo |
+| `ODOO_COMPOSE_PROJECT_NAME` | Docker Compose project |
+| `ODOO_WORKTREE_NAME` | Override for derived worktree name |
+| `ODOO_WORKTREE_CONFIG` | Config file path override |
+| `ODOO_AGENTIC_DEV_STATE_DB` | State registry path override (default `${XDG_DATA_HOME:-~/.local/share}/odoo-agentic-dev/state.db`) |
+
+Explicit env overrides win over derived values, but `E2E_ODOO_DB` and `ODOO_DATABASE` must not disagree.
+
+Companion apps contribute their own variables to the context env: `portEnv` receives the allocated port and `urlEnv` receives `http://localhost:<port>`; both show up in `info --env` and `info --json`. Compatibility aliases for existing projects (for example `KL_WORKTREE_DB_NAME`) can be declared in the recipe via `envAliases`: an alias may target **any** assembled env key — canonical or companion-provided (`E2E_PWA_PORT: "PWA_PORT"` works) — and an alias targeting an unknown key fails validation listing the available keys.
+
+## Safety Rules
+
+- A shared database (the recipe's `project.sharedDatabase`, used by `project.sharedBranches`) is never deleted without `--allow-shared`.
+- Database names outside the safe pattern `^[a-z][a-z0-9_]*$` (max 63 chars) are rejected.
+- Destructive actions never run with an empty Compose project name.
+- `link-source` never overwrites a non-symlink path.
+- The resolved database and Compose project are printed before destructive work.
+- Config validation failures fail closed: no command proceeds on an invalid recipe.
+- Confirmations are flags-only — there are no interactive prompts, so non-interactive agents never hang waiting for input.
+- `prune` is a dry run unless `--yes` is passed, skips shared environments unless `--allow-shared`, and only ages out environments when `--older-than` is given.
+- `up` fails fast on a port conflict instead of silently probing for another port — same branch, same port, always.
+- Generated stacks bind Odoo to `127.0.0.1` only; LAN exposure requires a deliberate project-supplied compose file.
+
+## Post-Init Hooks
+
+`database.postInit` hooks run after the initial modules are installed, in the order they are declared:
+
+```ts
+type PostInitHook =
+  | { type: "odoo-shell-file"; file: string }       // run a Python file in `odoo shell`
+  | { type: "odoo-shell-inline"; code: string }     // run inline Python in `odoo shell`
+  | { type: "set-ir-config-parameter"; key: string; value: string }
+  | { type: "command"; command: string; args: ReadonlyArray<string>; cwd?: string };
+```
+
+Hook files resolve relative to the project root. Only `set-ir-config-parameter` commits automatically (it runs `env.cr.commit()` for you); `odoo-shell-file` and `odoo-shell-inline` scripts must call `env.cr.commit()` themselves or their changes are rolled back when the shell exits. Prefer `odoo-shell-file` and `set-ir-config-parameter`; inline code is harder to review.
+
+## Development
+
+```bash
+pnpm install
+pnpm build         # compile to dist/
+pnpm test          # unit + e2e tests (e2e runs against dist/cli.js when built)
+pnpm typecheck     # tsc --noEmit over src + test
+pnpm lint          # oxlint
+pnpm format        # oxfmt --write
+pnpm format:check  # oxfmt --check
+```
+
+The test suite never requires Docker, Git state, or a network connection — adapters are faked, and every state-touching test pins `ODOO_AGENTIC_DEV_STATE_DB` to a temp file so your real registry is never touched. `scripts/docker-integration.sh` is a separate minimal Docker integration check (compose file generation + validation against a real Docker) used by the Linux CI job; it is not part of `pnpm test`.
+
+CI runs lint/typecheck/build/test on Linux, macOS, and Windows across Node 22 and 24 (the Windows job exercises the dry-run unit suite only — no Docker), plus the Docker integration job on Linux. A nightly workflow (`.github/workflows/nightly.yml`, also runnable via `workflow_dispatch`) exercises the real `odoo:18` + `postgres:16` lifecycle end to end: `setup` with a template snapshot, `reset-db` down the template restore path, `update base`, and a fully clean `down --volumes`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./suppress-sqlite-warning.js";

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// must stay first: installs the node:sqlite ExperimentalWarning filter before
+// any import that could transitively load node:sqlite (imports hoist)
+import "./suppress-sqlite-warning.js";
+import { Cause, Console, Effect, Layer } from "effect";
+import { CliError, Command } from "effect/unstable/cli";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { infoCommand } from "./commands/info.js";
+import { setupCommand } from "./commands/setup.js";
+import { upCommand } from "./commands/up.js";
+import { downCommand } from "./commands/down.js";
+import { resetDbCommand } from "./commands/reset-db.js";
+import { updateCommand } from "./commands/update.js";
+import { testCommand } from "./commands/test.js";
+import { linkSourceCommand } from "./commands/link-source.js";
+import { listCommand } from "./commands/list.js";
+import { pruneCommand } from "./commands/prune.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { logsCommand } from "./commands/logs.js";
+import { shellCommand } from "./commands/shell.js";
+import { psqlCommand } from "./commands/psql.js";
+import { runCommand } from "./commands/run.js";
+import { composeCommand } from "./commands/compose.js";
+import { worktreeCommand } from "./commands/worktree.js";
+import { CommandRunnerLive } from "./platform/command-runner.js";
+import { GitLive } from "./platform/git.js";
+import { DockerComposeLive } from "./platform/docker-compose.js";
+import { OdooLifecycleLive } from "./platform/odoo-lifecycle.js";
+import { ProcessSupervisorLive } from "./platform/process-supervisor.js";
+import { StateStoreLive } from "./platform/state-store.js";
+import { PortProbeLive } from "./platform/port-probe.js";
+import { isRuntimeError, renderError } from "./errors/errors.js";
+const root = Command.make("odoo-agentic-dev").pipe(Command.withDescription("Agent-friendly local Odoo development runtime"), Command.withSubcommands([
+    infoCommand,
+    setupCommand,
+    upCommand,
+    downCommand,
+    resetDbCommand,
+    updateCommand,
+    testCommand,
+    linkSourceCommand,
+    listCommand,
+    pruneCommand,
+    doctorCommand,
+    logsCommand,
+    shellCommand,
+    psqlCommand,
+    runCommand,
+    composeCommand,
+    worktreeCommand,
+]));
+const services = Layer.mergeAll(GitLive, OdooLifecycleLive, ProcessSupervisorLive, StateStoreLive, PortProbeLive).pipe(Layer.provideMerge(DockerComposeLive), Layer.provideMerge(CommandRunnerLive), Layer.provideMerge(NodeServices.layer));
+const program = Command.runWith(root, { version: "0.1.0-beta.1" })(process.argv.slice(2)).pipe(Effect.provide(services), Effect.catch((error) => Effect.gen(function* () {
+    // ShowHelp is the cli library's control-flow signal: by the time it
+    // reaches us the help text is already printed (bare invocation or
+    // unknown subcommand), so the error itself must not be rendered.
+    const helpRequested = CliError.isCliError(error) && error._tag === "ShowHelp";
+    if (!helpRequested) {
+        yield* Console.error(isRuntimeError(error) ? renderError(error) : String(error));
+    }
+    process.exitCode = 1;
+})), 
+// Defects (Die causes, thrown TypeErrors, ...) are not on the typed channel
+// above and runMain's reporting is disabled, so render them ourselves
+// instead of exiting silently. Placed after Effect.provide so defects raised
+// during layer construction are caught too.
+Effect.catchDefect((defect) => Effect.gen(function* () {
+    yield* Console.error("Unexpected internal error — this is a bug in odoo-agentic-dev, please report it:");
+    yield* Console.error(Cause.pretty(Cause.die(defect)));
+    process.exitCode = 1;
+})));
+NodeRuntime.runMain(program, { disableErrorReporting: true });
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/compose.d.ts

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+import { Command } from "effect/unstable/cli";
+import type { OdooAgenticDevConfig } from "../core/project-recipe.js";
+import type { WorktreeContext } from "../core/worktree-context.js";
+import type { RuntimeError } from "../errors/errors.js";
+import type { CommandRunnerApi } from "../platform/command-runner.js";
+import type { DockerComposeApi } from "../platform/docker-compose.js";
+import type { StateStoreApi } from "../platform/state-store.js";
+/**
+ * `docker compose <trailing args>` against this worktree's stack: the
+ * canonical preamble (-p/-f/--project-directory + context env) is prepended,
+ * the trailing args land verbatim. Full stdio inheritance so `logs -f`
+ * streams and interactive `exec` works; the child's exit code is propagated.
+ */
+export declare const runCompose: (recipe: OdooAgenticDevConfig, ctx: WorktreeContext, args: ReadonlyArray<string>) => Effect.Effect<number, RuntimeError, DockerComposeApi | CommandRunnerApi | StateStoreApi>;
+export declare const composeCommand: Command.Command<"compose", {
+    readonly args: readonly string[];
+    readonly config: import("effect/Option").Option<string>;
+}, {}, RuntimeError, CommandRunnerApi | import("../platform/git.js").GitApi | DockerComposeApi | StateStoreApi>;

package/dist/commands/compose.js

@@ -0,0 +1,29 @@
+import { Effect } from "effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { ConfigValidationError } from "../errors/errors.js";
+import { trailingOperands } from "./trailing-args.js";
+import { runInteractivePassthrough } from "./shell.js";
+import { resolveContext } from "./resolve-context.js";
+/**
+ * `docker compose <trailing args>` against this worktree's stack: the
+ * canonical preamble (-p/-f/--project-directory + context env) is prepended,
+ * the trailing args land verbatim. Full stdio inheritance so `logs -f`
+ * streams and interactive `exec` works; the child's exit code is propagated.
+ */
+export const runCompose = (recipe, ctx, args) => runInteractivePassthrough(recipe, ctx, args);
+export const composeCommand = Command.make("compose", {
+    args: Argument.string("args").pipe(Argument.variadic(), Argument.withDescription("docker compose arguments (pass them after --)")),
+    config: Flag.string("config").pipe(Flag.optional),
+}, (flags) => Effect.gen(function* () {
+    const args = [...flags.args, ...trailingOperands()];
+    if (args.length === 0) {
+        return yield* Effect.fail(new ConfigValidationError({
+            issues: [
+                "compose requires docker compose arguments, e.g. `odoo-agentic-dev compose -- logs -f`",
+            ],
+        }));
+    }
+    const { ctx, recipe } = yield* resolveContext(flags.config);
+    yield* runCompose(recipe, ctx, args);
+})).pipe(Command.withDescription("docker compose passthrough scoped to this worktree's compose project"));
+//# sourceMappingURL=compose.js.map

package/dist/commands/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/commands/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,MAA4B,EAC5B,GAAoB,EACpB,IAA2B,EAC+D,EAAE,CAC5F,yBAAyB,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CACxC,SAAS,EACT;IACE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAChC,QAAQ,CAAC,QAAQ,EAAE,EACnB,QAAQ,CAAC,eAAe,CAAC,+CAA+C,CAAC,CAC1E;IACD,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;CAClD,EACD,CAAC,KAAK,EAAE,EAAE,CACR,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,gBAAgB,EAAE,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CACvB,IAAI,qBAAqB,CAAC;YACxB,MAAM,EAAE;gBACN,uFAAuF;aACxF;SACF,CAAC,CACH,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5D,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC,CAAC,CACL,CAAC,IAAI,CACJ,OAAO,CAAC,eAAe,CAAC,sEAAsE,CAAC,CAChG,CAAC"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,35 @@
+import { Effect, Option } from "effect";
+import { Command } from "effect/unstable/cli";
+import type { CommandRunnerApi } from "../platform/command-runner.js";
+import type { DockerComposeApi } from "../platform/docker-compose.js";
+import type { GitApi } from "../platform/git.js";
+import type { PortProbeApi } from "../platform/port-probe.js";
+import type { StateStoreApi } from "../platform/state-store.js";
+export type DoctorCheck = {
+    readonly name: string;
+    readonly ok: boolean;
+    /** hard failures drive the exit code; soft ones are informational */
+    readonly hard: boolean;
+    readonly detail: string;
+};
+/** Engines floor: Node >= 22.15 (first unflagged node:sqlite). */
+export declare const nodeVersionOk: (version: string) => boolean;
+/**
+ * "Compose v2" means the Go `docker compose` plugin (the python v1
+ * `docker-compose` is unsupported). Plugin releases moved past v2 numbering
+ * (v5.x today), so accept any major >= 2 instead of grepping for "v2".
+ */
+export declare const composeVersionOk: (stdout: string) => boolean;
+export declare const detectWsl: (procVersion: string | null) => boolean;
+export declare const hasHardFailure: (checks: ReadonlyArray<DoctorCheck>) => boolean;
+export declare const formatDoctorReport: (checks: ReadonlyArray<DoctorCheck>) => string;
+/**
+ * Run every doctor probe and fold each outcome — success or failure — into a
+ * check row. This never fails: a broken docker/state/config is a finding, not
+ * an error. The exit-code decision belongs to the command via hasHardFailure.
+ */
+export declare const collectDoctorChecks: (explicitConfigPath: string | undefined) => Effect.Effect<ReadonlyArray<DoctorCheck>, never, CommandRunnerApi | DockerComposeApi | StateStoreApi | PortProbeApi | GitApi>;
+export declare const doctorCommand: Command.Command<"doctor", {
+    readonly json: boolean;
+    readonly config: Option.Option<string>;
+}, {}, never, CommandRunnerApi | GitApi | DockerComposeApi | StateStoreApi | PortProbeApi>;