@dokebi/cli 0.4.1 → 0.4.2

package/AI.md

@@ -1,4 +1,4 @@
-# AI guide — @dokebi/cli 0.4.1 (`dokebi`)
+# AI guide — @dokebi/cli 0.4.2 (`dokebi`)
 
 The command that creates Dokebi projects and installs, removes and upgrades plugins, apps and modules. It changes the project's "CLI-owned files" (generated registration code, state, the sample settings) in transactions. An AI never edits these files by hand: it always changes them with a command. Command details are in [docs/cli/README.md](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/cli/README.md), the install lifecycle in [docs/cli/installation.md](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/cli/installation.md), and the automation contract in [docs/cli/automation.md](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/cli/automation.md).
 
@@ -47,7 +47,7 @@ The `blog` plan, depending on the answers: `init` (when the folder is not a proj
 | `dokebi config secret <id>.<path>` | Writes a random secret (32 bytes; a one-item list when the schema wants a list) into dokebi.yaml. The value never appears in output or logs; an existing value stays (`SECRET_KEPT`). Example: `config secret dokebi-websocket-hub.secret`. @dokebi/session needs none: `add` generates its secret into `.env` |
 | `dokebi config set <id>.<path>=<value>...` | Non-secret options into dokebi.yaml (the value is JSON when it parses, otherwise text; checked against the plugin schema, only a missing required value becomes `configRequired`). An id that is not installed is `UNKNOWN_PLUGIN` |
 | `dokebi dev-infra [--db-port <n>]` | Development database: `compose.yaml` (user-owned; the project name is the package name), `DOKEBI_DB_PASSWORD` in `.env` (generated, 0600, in `.gitignore`) and `connections.main.options.url`. An existing compose `db` service and password are kept (`COMPOSE_KEPT`). When the port is taken it writes nothing and fails with `PORT_IN_USE` (`details.alternative`: a free port). It does not start the database: `docker compose up -d --wait` |
-| `dokebi verify [--wait-ms <n>]` | `{ ok, checks[{name, ok, skipped?, ms, code?, message?, details?}], urls[], listen[], tellUser? }`: doctor → check (`dokebi check` below, reusing the doctor result) → typecheck (skipped without the script) → build (Vite) → preflight (`ALREADY_RUNNING`, `PORT_IN_USE`, `DB_URL_MISSING`) → start (`--wait-ms`, default 30000) → HTTP (connects to the listening address: `/health/ready`, and `GET /` with the Host header of every app domain) → stop. `urls` are the addresses the app answers (see `start`), `listen` the bound addresses. `ok` only when everything passes (otherwise exit 1). A doctor or preflight failure skips the start; a check failure does not. It never stops an app that already runs. **HTTP counts only answers from the app verify started**: it passes a random token in `DOKEBI_VERIFY_TOKEN` and @dokebi/web echoes it in the response header `x-dokebi-verify` (only while that variable is set, no cost in production). An answer without the token comes from another server on the port: `FOREIGN_SERVER` (`details.requests[].instance: other`). When the app did not start, HTTP is skipped and fails (`NOT_STARTED`). stop ends the processes verify started by the pid start returned (no `ps` needed, works in a sandbox); `APP_EXITED` when the app ended by itself first, `STOP_FAILED` when a signal cannot be sent. With `ok: true` and an applied recipe (`.dokebi/recipe.json`), `tellUser: string[]` holds the lines your final message must include (each choice with who made it, a default with its reason, and the notices); the human output ends with them under `Tell the user`. Without a recipe record there is no `tellUser` |
+| `dokebi verify [--wait-ms <n>]` | `{ ok, checks[{name, ok, skipped?, ms, code?, message?, details?}], urls[], listen[], tellUser? }`: doctor → check (`dokebi check` below, reusing the doctor result) → typecheck (skipped without the script) → build (Vite) → preflight (`ALREADY_RUNNING`, `PORT_IN_USE`, `DB_URL_MISSING`) → start (`--wait-ms`, default 30000) → HTTP (connects to the listening address: `/health/ready`, and `GET /` with the Host header of every app domain; with neither a readiness route (`healthRoutes: false`) nor an app domain, one identity probe `GET /` that passes with any status below 500 carrying this run's header, so HTTP never passes without a request: `details.requests[].identity: true`; each request must complete within 5 s, a response cut off or never finished is `HTTP_FAILED`) → stop. `urls` are the addresses the app answers (see `start`), `listen` the bound addresses. `ok` only when everything passes (otherwise exit 1). A doctor or preflight failure skips the start; a check failure does not. It never stops an app that already runs. **HTTP counts only answers from the app verify started**: it passes a random token in `DOKEBI_VERIFY_TOKEN` and @dokebi/web echoes it in the response header `x-dokebi-verify` (only while that variable is set, no cost in production). An answer without the token comes from another server on the port: `FOREIGN_SERVER` (`details.requests[].instance: other`). When the app did not start, HTTP is skipped and fails (`NOT_STARTED`). stop ends the processes verify started by the pid start returned (no `ps` needed, works in a sandbox); `APP_EXITED` when the app ended by itself first, `STOP_FAILED` when a signal cannot be sent. With `ok: true` and an applied recipe (`.dokebi/recipe.json`), `tellUser: string[]` holds the lines your final message must include (each choice with who made it, a default with its reason, and the notices); the human output ends with them under `Tell the user`. Without a recipe record there is no `tellUser` |
 | `dokebi check` | User-code conventions (D-0072). `{ ok, problems[{rule, severity?, file, line, message, fix}], files, rules, typescript, ms: { total, typescript } }`, exit 1 on a problem (a `severity: 'warning'` problem is reported but never fails: `ok` stays true). The human output prints `file:line  rule  message` and a `fix:` line per problem, then a summary (`check ok` or `check FAILED: N problems`, files, time). Rules: `empty-catch` (an empty `catch`, `.catch(() => {})`, an empty onRejected of `then`, an empty `on('error', …)`), `floating-promise` (a statement that calls something returning a Promise without await, return, `void` or `.catch`; the project's TypeScript decides the type; `test()` of node:test is exempt), `non-erasable-syntax` (enum, namespaces with values, parameter properties, decorators, `import x =`, `export =`, `<T>x`), `private-import` (a path of `@dokebi/*` outside its exports, such as `@dokebi/core/dist/…`), `missing-package` (an @dokebi package that is not installed → `add`; a feature Dokebi does not have → the absent `instead`; an unknown name), `generated-file` (doctor `MODIFIED_REGISTRATION`, `GUIDE_BLOCK_MODIFIED` and `MODIFIED_TEMPLATE` of CLI-owned files), `secret-in-config` (a plugin check `SECRET_IN_CONFIG` while dokebi.yaml could be committed). Warning (D-0074): `inertia-form-only` — an Inertia form submit (`form.post/put/patch/delete/submit(…)` of a `useForm(…)` result, `router.post/put/patch/delete(…)`) whose options are missing or an object literal without `only`; the GET after its redirect would send every prop of the page again. Fix: `form.post(url, { only: ['<props it changes>'] })` (`errors` always comes along). It reads the text of `src/**` files that import `@inertiajs/` (the `<script>` blocks of .vue and .svelte files; comments and strings masked); calls inside a template attribute are not read, and options passed as a variable or with a spread are taken as fine. When an empty catch, a background promise or a full-page form submit (a login) is really intended, put `// dokebi-check: allow <rule> <reason>` on that line or the line above (only `empty-catch`, `floating-promise` and `inertia-form-only`; without a reason the marker is ignored). The sources are the program of `tsconfig.json` (generated files, `.d.ts` and node_modules excluded), read with the API of the TypeScript 7 installed in the project (`typescript/unstable/sync`): when it cannot be loaded `TYPESCRIPT_UNAVAILABLE` (`npm install`), when tsconfig cannot be opened `TSCONFIG_INVALID` |
 | `dokebi upgrade <plugin id> [--to <version\|package\|tgz>] [--dry-run]` | Change the version. Do not use remove and add instead. With the same version and a changed manifest it applies the manifest again (D-0037) |
 | `dokebi remove <plugin id> [--dry-run]` | Remove a plugin. `REVERSE_DEPENDENCY` when a remaining plugin depends on it, `REQUIRED_PLUGIN` for a required part |
@@ -84,7 +84,7 @@ Every command takes `--json` (one machine document) and every changing command `
 
 - One project = one process (`src/main.ts`; several apps share it). Run files live in `.dokebi/run/` (`app.pid`, `app.log`, `app.log.1`…, `log-writer.log`; the `.gitignore` inside is `*`, so Git never takes them).
 - **Log rotation (D-0053)**: `start` launches a separate log writer process, and the writer starts the app with stdout and stderr pipes and writes `app.log` line by line. When the next line would pass `--log-max-mb` (default 50, 1–10240), it moves the file to `app.log.1` at a line boundary and keeps `--log-files` files (default 5, 1–100). Fast writes lose no line (a slow disk makes the app's writes wait). Out of range is `USAGE`, and so is combining them with `--foreground`. There is no dokebi.yaml setting (put fixed values in a package.json script). The writer ignores SIGTERM and, when the app ends (crashes included), writes one line `--- dokebi: app exited (…) ---` and ends. The writer's own errors go to `.dokebi/run/log-writer.log` as one JSON line each (`level: error`, `code`, the full `error`): `LOG_OPEN_FAILED`, `LOG_WRITE_FAILED`, `LOG_ROTATE_FAILED`, `LOG_LINES_DROPPED`, `APP_SPAWN_FAILED`, `APP_OUTPUT_FAILED`.
-- `start`: the inspect checks (an error diagnostic is `START_CHECK_FAILED`), then a background run with `NODE_ENV=production` (kept when already set). The app also gets a random per-start `DOKEBI_INSTANCE_TOKEN`, kept with the pid, the `urls` and the log writer's loopback `control` port in `.dokebi/run/app.pid` (0600) for the proofs below; it never appears in output. When the log shows `Dokebi application started` (the line the generated main writes), `ready: true`. The result has `logWriter` (pid), `logMaxBytes`, `logFiles`, `listen` (the bound addresses from the web server's listening line, such as `http://127.0.0.1:3000`) and `urls`, the addresses the app answers: with @dokebi/app the Host name picks the app, so `urls` are `http://<domain>:<port>` for every configured domain that resolves to this machine (`localhost`, `*.localhost`, `127.x.x.x`), plus `listen` when `unknownDomain` names an app; without @dokebi/app they equal `listen` (`0.0.0.0` shown as `127.0.0.1`). Open and test `urls`: a request to the bound IP gets 404 when that IP is not an app domain (do not add one with `app link` for that). `urls` is empty when only public domains are configured (they answer through DNS or a proxy). `dokebi dev` prints the same addresses (from `dokebi-web.port`) when it starts. Without that line within `--wait-ms` (default 10000) it reports `ready: false` and a warning, even if the process lives. When the process ends before that: `START_FAILED` (details.tail: the last 30 log lines; details.logWriterLog: the end of the writer's diagnostics). Already running: `ALREADY_RUNNING`; another start in progress: `START_IN_PROGRESS`.
+- `start`: the inspect checks (an error diagnostic is `START_CHECK_FAILED`), then a background run with `NODE_ENV=production` (kept when already set). The app also gets a random per-start `DOKEBI_INSTANCE_TOKEN`, kept with the pid, the `urls` and the log writer's loopback `control` port in `.dokebi/run/app.pid` (0600) for the proofs below; it never appears in output. When the log shows `Dokebi application started` (the line the generated main writes), `ready: true`. The result has `logWriter` (pid), `logMaxBytes`, `logFiles`, `listen` (the bound addresses from the web server's listening line, such as `http://127.0.0.1:3000`) and `urls`, the addresses the app answers: with @dokebi/app the Host name picks the app, so `urls` are `http://<domain>:<port>` for every configured domain that resolves to this machine (`localhost`, `*.localhost`, `127.x.x.x`), plus `listen` when `unknownDomain` names an app; without @dokebi/app they equal `listen` (`0.0.0.0` shown as `127.0.0.1`). Open and test `urls`: a request to the bound IP gets 404 when that IP is not an app domain (do not add one with `app link` for that). `urls` is empty when only public domains are configured (they answer through DNS or a proxy). `dokebi dev` prints the same addresses (from `dokebi-web.port`) when it starts. Without that line within `--wait-ms` (default 10000) it reports `ready: false` and a warning, even if the process lives. When the process ends before that: `START_FAILED` (details.tail: the last 30 log lines; details.logWriterLog: the end of the writer's diagnostics). Already running: `ALREADY_RUNNING`; another start in progress: `START_IN_PROGRESS` (one start at a time holds `.dokebi/run/start.lock` from before it checks the running state until the pid file is written, so of two concurrent starts exactly one runs the app and the other starts nothing).
 - **Without process information** (no `ps`, a sandbox blocks it, /proc unreadable; D-0073), `status`, `stop` and `start` (with a PID file) ask the app instead: `kill(pid, 0)` saying the pid does not exist makes the PID file stale; otherwise they send a random challenge in the request header `x-dokebi-instance` to the recorded address (or `dokebi-web.port` of dokebi.yaml), and @dokebi/web answers with HMAC-SHA256 of its `DOKEBI_INSTANCE_TOKEN` (the token itself never goes on the wire). Only the right answer proves the pid is this start's app: `status` then reports `proof: "http"` (no `rssMb`) and `stop` signals it (`proof: "http"` in its result). When the proof fails (no web plugin, another server on the port, a PID file of an older CLI without a token), they fail with `PROCESS_INFO_FAILED` as before (the reason in `cause`; `details.pid`, `source`, `hint` (run outside the sandbox or allow `ps` or /proc), `manualStop` (check the pid yourself, `kill -TERM <pid>`, then delete `.dokebi/run/app.pid`) and `instanceProof{tried, reason}`), signal nothing and **keep** the PID file (the app may still live). With `ps` the behaviour is unchanged (`proof: "process"`). `verify` stops the process it started seconds ago with the pid start returned (only `kill(pid, 0)` and SIGTERM).
 - **When this shell may not signal the app** (an agent sandbox per command, such as Codex CLI, or Claude Code's sandbox for an app started outside it: even `kill(pid, 0)` is refused with EPERM; D-0073 addendum), `stop` and `status` ask the app's **log writer**, its parent from the start command, which can signal it. The writer listens on a random loopback TCP port (`127.0.0.1`, the `control` field of the 0600 PID file) and accepts only `status` and `stop` after both sides proved the instance token (an HMAC challenge each way; the token never goes on the wire). Without process information the writer is asked first (`proof: "log-writer"`), then the HTTP proof above. With `ps` but a refused SIGTERM, `stop` asks the writer as well. The writer sends SIGTERM, waits `--timeout-ms` and, with `--force`, SIGKILL (`STOP_TIMEOUT` as usual); the result says `via: "log-writer"` (otherwise `via: "signal"`). A writer that is gone, refuses the token, or runs another pid is never asked to stop anything: the error is the one above (`PROCESS_INFO_FAILED` with `instanceProof`, or `STOP_FAILED` with `details.logWriter` when `ps` worked). A sandbox without local network access cannot reach the port either; then stop the app from a shell that may signal it.
 - `stop`: SIGTERM **to the app** for a drain (the writer ends after the app's output ends; when it does not end within 5 seconds, `warnings`). When the app does not end within `--timeout-ms` (default 30000): `STOP_TIMEOUT` (the process stays), with `--force` a SIGKILL then. When nothing runs: `stopped: false`.
@@ -107,7 +107,7 @@ One document on stdout: `{ schemaVersion, cliVersion, command, ok, result?, erro
 
 - `result` (changing commands): `changed` (changed files), `preserved`, `preservedDetails` (an edited template that upgrade kept, with the location of the new one), `warnings[{code, path}]`, `configRequired` (missing required values, at most 20 plus `errorCount`), `autoInstalled`, `resolved` (the version add picked), `generatedSecrets[{variable, file, plugin}]` (secrets add generated into `.env`; names only), `nextSteps[{command, why}]` (init, add, app, module, dev-infra and recipe all use this shape; an edit is `edit …`), `workspaceInstall`.
 - `recipe` with missing answers exits **2** with `ok: false` and `error.code: ANSWERS_REQUIRED` (`mutation: none`); `result` holds `status: needs-answers`, `questions`, `missing`, `waitForUser` and `next`. With every answer, `result` is `{ status: planned|applied, root, answers, answersFrom, plan.steps[{id, command, why}], preflight[{code, severity, message, fix}], completedSteps, skippedSteps, nextSteps, report }`. For `verify`, `ok` equals `result.ok`, and a failure exits 1.
-- `error`: `code`, `message`, `phase` (arguments, install, commit, unknown), `mutation`, `details`. With `mutation: 'unknown'` there is no guarantee that the originals are untouched. An npm failure in the temporary install (staging) has `details.stage: staging` and `mutation: none` (the project is untouched). A failure to reach the registry has `details.network: true` and `hint` (try again online, or use the cache with `npm_config_prefer_offline=true npx dokebi …`); when the version came from the snapshot, `details.warnings` holds `CATALOG_OFFLINE`. The `details` of `NPM_FAILED` hold `command`, `exitCode`, `signal`, `timedOut` and the last 4 KB of npm's output (`stderr`, `stdout`; `user:password@` in URLs, `_authToken=` and the like are masked). The same helper masks verify's `TYPECHECK_FAILED` and `BUILD_FAILED`, the recipe's `STEP_COMMAND_FAILED` `details.output` (the last 4 KB of the project script or step command output), and the `tail` and `logWriterLog` of `START_FAILED` (`dokebi logs` shows the log as it is). The CLI always calls npm with `--loglevel=warn` (an inherited `loglevel=silent` from `npx -s` or `npm run -s` used to make npm print not even its errors). `recovery-required` keeps the lock and the backups and needs a person to look (never delete the lock or backups and retry).
+- `error`: `code`, `message`, `phase` (arguments, install, commit, unknown), `mutation`, `details`. With `mutation: 'unknown'` there is no guarantee that the originals are untouched. An npm failure in the temporary install (staging) has `details.stage: staging` and `mutation: none` (the project is untouched). A failure to reach the registry has `details.network: true` and `hint` (try again online, or use the cache with `npm_config_prefer_offline=true npx dokebi …`); when the version came from the snapshot, `details.warnings` holds `CATALOG_OFFLINE`. The `details` of `NPM_FAILED` hold `command`, `exitCode`, `signal`, `timedOut` and the last 4 KB of npm's output (`stderr`, `stdout`; `user:password@` in URLs, `_authToken=` and the like are masked). From npm's whole stderr they also hold `npmCode` (such as `ERESOLVE`), `npmSummary`, `logFile` (npm's debug log: read it for the full cause) and `reportFile`, when npm printed them. The same helper masks verify's `TYPECHECK_FAILED` and `BUILD_FAILED`, the recipe's `STEP_COMMAND_FAILED` `details.output` (the last 4 KB of the project script or step command output), and the `tail` and `logWriterLog` of `START_FAILED` (`dokebi logs` shows the log as it is). The CLI always calls npm with `--loglevel=warn` (an inherited `loglevel=silent` from `npx -s` or `npm run -s` used to make npm print not even its errors). `recovery-required` keeps the lock and the backups and needs a person to look (never delete the lock or backups and retry).
 - Logs of the CLI itself go to stderr (see "Logs" below); stdout holds only the document.
 
 ## 4. Project structure (D-0031, D-0032)
@@ -145,7 +145,7 @@ A plugin manifest cannot write files outside `src/shared/{models,modules,views}/
 
 Each file of `install.files` (and of an install module's `files`) may declare `owner`: `user` (the default: a skeleton the user edits; doctor stays quiet and upgrade keeps an edited file) or `cli` (a file the plugin generates again; editing it is doctor `MODIFIED_TEMPLATE` and check `generated-file`). Entry files are always `user` (`cli` there is `INVALID_MANIFEST`). The owner is recorded in `.dokebi/state.json`.
 
-The CLI has no special case for any plugin ID. App and module commands look for the plugin that declares `hosts`; without one they fail with `APP_PLUGIN_MISSING` or `MODULE_PLUGIN_MISSING` (naming the catalog package that has the role), and when apps or modules are recorded but no plugin takes them, generation fails with `HOST_MISSING`. `planInstall` may return `envSecrets` (environment variable names, at most 8): the CLI generates a secret into `.env` for each one the environment and `.env` lack (§2.2), so a plugin never writes files itself. `planInstall`, `planUpgrade` and `check` of `installModule` run under the Node permission model (no writes, no child processes, no environment variables, 5 s and 1 MiB); the network is not blocked, so it is not a full sandbox. npm lifecycle scripts never run.
+The CLI has no special case for any plugin ID. App and module commands look for the plugin that declares `hosts`; without one they fail with `APP_PLUGIN_MISSING` or `MODULE_PLUGIN_MISSING` (naming the catalog package that has the role), and when apps or modules are recorded but no plugin takes them, generation fails with `HOST_MISSING`. `planInstall` may return `envSecrets` (environment variable names, at most 8): the CLI generates a secret into `.env` for each one the environment and `.env` lack (§2.2), so a plugin never writes files itself. `planInstall`, `planUpgrade` and `check` of `installModule` run under the Node permission model (reads only in the plugin's own package and the packages it depends on, never the project, the workspace root or their `.env`; no writes, no child processes, no environment variables, 5 s and 1 MiB); the network is not blocked, so it is not a full sandbox. npm lifecycle scripts never run.
 
 **A changed manifest needs a new version** (D-0037). The repository check refuses a changed manifest under the same version, and installed projects report doctor `MANIFEST_CHANGED` (hint: `dokebi upgrade <id>`).
 

package/README.md

@@ -1,6 +1,6 @@
 # @dokebi/cli
 
-The tool that creates Dokebi projects and installs plugins, version 0.4.1 (0.4.0 was the stage-3 release, D-0067). The command is `dokebi`. What changed since 0.1.1 (YAML settings, migrate, multi-app and module commands) is in the CHANGELOG. Node.js >=24.0.0, ESM; the default CI runs Node 24.
+The tool that creates Dokebi projects and installs plugins, version 0.4.2 (0.4.0 was the stage-3 release, D-0067). The command is `dokebi`. What changed since 0.1.1 (YAML settings, migrate, multi-app and module commands) is in the CHANGELOG. Node.js >=24.0.0, ESM; the default CI runs Node 24.
 
 ## Running it
 

package/catalog.json

@@ -1,10 +1,10 @@
 {
   "$comment": "Generated by scripts/catalog/build.ts from package.json dokebiCatalog fields and packages/cli/catalog-src (D-0065). Do not edit; run node scripts/catalog/build.ts.",
   "schemaVersion": 1,
-  "cli": "0.4.1",
+  "cli": "0.4.2",
   "core": {
     "package": "@dokebi/core",
-    "version": "0.4.0"
+    "version": "0.4.1"
   },
   "capabilities": {
     "admin.ui": {
@@ -223,7 +223,7 @@
     {
       "id": "dokebi-app",
       "package": "@dokebi/app",
-      "version": "0.4.1",
+      "version": "0.4.2",
       "kind": "plugin",
       "summary": "Several apps chosen by request domain (src/apps/<app>) with a template each; installs web, controller and template-ejs with it",
       "description": "Multiple apps per project for Dokebi: pick the app and template by request domain, with EJS and Inertia skeletons.",
@@ -252,7 +252,7 @@
       "requires": [
         {
           "id": "dokebi-web",
-          "range": "^0.4.1",
+          "range": "^0.4.2",
           "package": "@dokebi/web",
           "automatic": true
         },
@@ -367,7 +367,7 @@
     {
       "id": null,
       "package": "@dokebi/cli",
-      "version": "0.4.1",
+      "version": "0.4.2",
       "kind": "cli",
       "summary": "Commands to create a project, browse the plugin catalog, run recipes, install plugins and verify (dokebi)",
       "description": "Project scaffolding, plugin catalog, recipes, install and verification CLI for Dokebi.",
@@ -438,7 +438,7 @@
     {
       "id": "dokebi-config",
       "package": "@dokebi/config",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "required",
       "summary": "Required part of the core that reads and validates dokebi.yaml into read-only settings per app (installed automatically)",
       "description": "Validated immutable YAML configuration for Dokebi applications.",
@@ -511,7 +511,7 @@
     {
       "id": null,
       "package": "@dokebi/core",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "core",
       "summary": "Application core: settings loading, plugin registration, lifecycle, logger and shared libraries (required)",
       "description": "Minimal composable Node.js application and plugin lifecycle framework.",
@@ -724,7 +724,7 @@
     {
       "id": "dokebi-event-bus",
       "package": "@dokebi/event-bus",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "Named event buses (local or NATS, at most once)",
       "description": "Named event buses for Dokebi: in-process dispatch or NATS Core delivery between processes.",
@@ -921,7 +921,7 @@
     {
       "id": "dokebi-migrate",
       "package": "@dokebi/migrate",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "Migration and seed runner for dokebi-db connections (dokebi-migrate up in the deploy step)",
       "description": "Migrations and seeds for dokebi-db connections: history and lock for PostgreSQL, MySQL, MariaDB and MongoDB, run from the deployment.",
@@ -1127,7 +1127,7 @@
     {
       "id": "dokebi-scheduler",
       "package": "@dokebi/scheduler",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "Submits fixed-interval and cron schedules as @dokebi/job jobs (one leader through Redis)",
       "description": "Interval and cron schedules (with time zones) for Dokebi that submit jobs, with one leader over Redis.",
@@ -1175,7 +1175,7 @@
     {
       "id": "dokebi-seal",
       "package": "@dokebi/seal",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "Seals WebSocket frames and HTTP bodies (obfuscation, replay protection) with a browser client (WASM)",
       "description": "Payload sealing (obfuscation, replay defence, in-transit encryption) for seal hosts: @dokebi/websocket frames and @dokebi/web HTTP bodies, with browser socket, fetch and Inertia clients and their WASM loader",
@@ -1218,7 +1218,7 @@
     {
       "id": "dokebi-session",
       "package": "@dokebi/session",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "Server-side sessions for @dokebi/web (signed cookie, memory or redis store, flash)",
       "description": "Server-side sessions for @dokebi/web: signed cookie, memory or Redis store, flash.",
@@ -1279,7 +1279,7 @@
     {
       "id": "dokebi-sse",
       "package": "@dokebi/sse",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "Server-sent events (SSE) streams and rooms, delivery across workers, and a browser client",
       "description": "Server-sent events for @dokebi/web: authenticated streams, rooms, cross-worker fan-out over @dokebi/event-bus, and a browser client",
@@ -1384,7 +1384,7 @@
     {
       "id": "dokebi-template-inertia",
       "package": "@dokebi/template-inertia",
-      "version": "0.4.1",
+      "version": "0.4.2",
       "kind": "plugin",
       "summary": "Inertia (v3) server adapter: Vue 3 views, Vite build files and optional server-side rendering (SSR)",
       "description": "Inertia v3 server adapter for Dokebi: page JSON, Vite manifest assets and optional server-side rendering.",
@@ -1441,7 +1441,7 @@
       "requires": [
         {
           "id": "dokebi-web",
-          "range": "^0.4.1"
+          "range": "^0.4.2"
         }
       ],
       "optional": [
@@ -1470,7 +1470,7 @@
     {
       "id": "dokebi-web",
       "package": "@dokebi/web",
-      "version": "0.4.1",
+      "version": "0.4.2",
       "kind": "plugin",
       "summary": "Fastify 5 HTTP server (503 before ready, health paths, drain, zero-downtime cluster replacement)",
       "description": "Fastify 5 HTTP server owned by a Dokebi app: 503 before ready, health routes, drain and cluster handover.",
@@ -1524,7 +1524,7 @@
     {
       "id": "dokebi-websocket",
       "package": "@dokebi/websocket",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "WebSocket routes, rooms and broadcast on top of dokebi-web (at most once)",
       "description": "WebSocket routes on @dokebi/web with rooms and broadcast across servers through @dokebi/websocket-hub.",
@@ -1581,7 +1581,7 @@
     {
       "id": "dokebi-websocket-hub",
       "package": "@dokebi/websocket-hub",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "kind": "plugin",
       "summary": "Hub of WebSocket clients, rooms, broadcast and kick (usually used through @dokebi/websocket)",
       "description": "WebSocket hub for Dokebi: connection roster, rooms, broadcast and kick across workers and servers.",

package/dist/bin.js

@@ -774,6 +774,15 @@ function nextSteps(error) {
     const npmError = error.details.stderr;
     if (error.code === 'NPM_FAILED' && typeof npmError === 'string' && npmError.trim())
         lines.add(`npm stderr (end):\n${npmError.trimEnd()}`);
+    if (error.code === 'NPM_FAILED') {
+        const { npmCode, npmSummary, logFile, reportFile } = error.details;
+        if (typeof npmCode === 'string')
+            lines.add(`npm error: ${npmCode}${typeof npmSummary === 'string' ? ` ${npmSummary}` : ''}`);
+        if (typeof reportFile === 'string')
+            lines.add(`npm report: ${reportFile}`);
+        if (typeof logFile === 'string')
+            lines.add(`npm log: ${logFile}`);
+    }
     if (error.code === 'UNKNOWN_COMMAND')
         lines.add('hint: dokebi --help lists the commands');
     const hint = error.details.hint;

package/dist/install-module.d.ts

@@ -14,10 +14,18 @@ export declare class InstallPlanningError extends Error {
 }
 /** Returned when the module does not export the requested phase. */
 export declare const PHASE_MISSING: unique symbol;
+/**
+ * The folders an install module may read (R9): its own package and the packages it depends on
+ * (`dependencies`, `optionalDependencies`, `peerDependencies`, transitively), each found the way
+ * Node resolves it from the importer's real folder, and allowed both where Node finds it (a
+ * `node_modules/<name>` link) and at its real path. Never the project, the workspace root or
+ * the rest of `node_modules`, so `.env` files and other projects' files stay unreadable.
+ */
+export declare function installReadRoots(packageDirectory: string): Promise<string[]>;
 /**
  * Runs one lifecycle phase of a plugin installation module in a child process.
  * The child uses the Node permission model: it may read only `readRoots`
- * (real paths), cannot write files or spawn processes, and receives no
+ * (at their real and link paths), cannot write files or spawn processes, and receives no
  * parent environment variables. Node 24 does not restrict network access.
  */
 export declare function runInstallModule(modulePath: string, phase: InstallPhase, context: InstallModuleContext, readRoots?: readonly string[]): Promise<unknown>;

package/dist/install-module.js

@@ -1,8 +1,8 @@
 import { spawn } from 'node:child_process';
-import { realpath } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, dirname, join, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { debug, debugEnabled, describeError } from './diagnostics.js';
+import { debug, debugEnabled, describeError, isMissing } from './diagnostics.js';
 export class InstallPlanningError extends Error {
     code;
     constructor(code) {
@@ -16,10 +16,96 @@ export const PHASE_MISSING = Symbol('dokebi.install.phase-missing');
 const MAX_BYTES = 1024 * 1024;
 const TIMEOUT_MS = 5000;
 const RUNNER = "\nconst finish = (value) => process.stdout.write(JSON.stringify(value), () => process.exit(0));\ntry {\n let input = '';\n for await (const chunk of process.stdin) input += chunk;\n const freeze = (value) => {\n  if (value && typeof value === 'object') {for (const child of Object.values(value)) freeze(child);Object.freeze(value);}\n  return value;\n };\n const phase = process.argv[2];\n const context = freeze({ ...JSON.parse(input), phase });\n const module = await import(process.argv[1]);\n if (typeof module[phase] !== 'function') finish({ok:true,missing:true});\n else {\n  const plan = await module[phase](context);\n  if(plan === undefined)finish({ok:false,code:'INSTALL_PLAN_INVALID'});\n  else finish({ok:true,plan});\n }\n} catch(error) {\n const code = error && error.code === 'ERR_ACCESS_DENIED' ? 'INSTALL_PERMISSION_DENIED' : error && typeof error.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code) ? error.code : 'INSTALL_MODULE_FAILED';\n finish({ok:false,code});\n}\n";
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i;
+/** Packages an install module may read (its own and its dependencies, transitively). */
+const MAX_READ_PACKAGES = 512;
+async function dependencyNames(directory) {
+    let text;
+    try {
+        text = await readFile(join(directory, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        // A folder without package.json (a bare install module) declares no dependencies.
+        if (!isMissing(error))
+            throw error;
+        debug('Install module package has no package.json', { directory });
+        return [];
+    }
+    const pkg = JSON.parse(text);
+    const names = new Set();
+    for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+        const value = pkg[field];
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            for (const name of Object.keys(value))
+                if (PACKAGE_NAME.test(name))
+                    names.add(name);
+    }
+    return [...names];
+}
+/** Where Node finds `name` from `directory`: `node_modules/<name>` in it or a parent folder. */
+async function findPackage(directory, name) {
+    for (let current = directory;; current = dirname(current)) {
+        if (basename(current) !== 'node_modules') {
+            const candidate = join(current, 'node_modules', name);
+            try {
+                await stat(candidate);
+                return candidate;
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+        if (dirname(current) === current)
+            return undefined;
+    }
+}
+/**
+ * The folders an install module may read (R9): its own package and the packages it depends on
+ * (`dependencies`, `optionalDependencies`, `peerDependencies`, transitively), each found the way
+ * Node resolves it from the importer's real folder, and allowed both where Node finds it (a
+ * `node_modules/<name>` link) and at its real path. Never the project, the workspace root or
+ * the rest of `node_modules`, so `.env` files and other projects' files stay unreadable.
+ */
+export async function installReadRoots(packageDirectory) {
+    const own = await realpath(packageDirectory);
+    const roots = new Set([own]);
+    const visited = new Set([own]);
+    const queue = [own];
+    for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+        for (const name of await dependencyNames(next)) {
+            const found = await findPackage(next, name);
+            if (!found) {
+                // Optional and peer dependencies may be absent; an import of them fails on its own.
+                debug('Install module dependency not found', { package: next, dependency: name });
+                continue;
+            }
+            const real = await realpath(found);
+            roots.add(found);
+            roots.add(real);
+            if (visited.has(real))
+                continue;
+            visited.add(real);
+            if (visited.size > MAX_READ_PACKAGES)
+                throw new InstallPlanningError('INSTALL_DEPENDENCIES_LIMIT');
+            queue.push(real);
+        }
+    }
+    // A folder inside another allowed folder adds nothing; the own package stays first (cwd).
+    const sorted = [...roots].sort();
+    const result = [own];
+    for (const root of sorted)
+        if (root !== own &&
+            !sorted.some((other) => other !== root && root.startsWith(other + sep)) &&
+            !root.startsWith(own + sep))
+            result.push(root);
+    debug('Install module read roots', { package: own, roots: result });
+    return result;
+}
 /**
  * Runs one lifecycle phase of a plugin installation module in a child process.
  * The child uses the Node permission model: it may read only `readRoots`
- * (real paths), cannot write files or spawn processes, and receives no
+ * (at their real and link paths), cannot write files or spawn processes, and receives no
  * parent environment variables. Node 24 does not restrict network access.
  */
 export async function runInstallModule(modulePath, phase, context, readRoots = [dirname(modulePath)]) {
@@ -29,7 +115,13 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
     let roots;
     let moduleUrl;
     try {
-        roots = await Promise.all(readRoots.map((root) => realpath(root)));
+        // Each root at its real path and, when it is a link (a package in node_modules), also at the
+        // link: Node checks the path it resolves through (node_modules/<name>/package.json) as well.
+        const resolved = await Promise.all(readRoots.map(async (root) => [
+            await realpath(root),
+            join(await realpath(dirname(root)), basename(root)),
+        ]));
+        roots = [...new Set(resolved.flat())];
         moduleUrl = pathToFileURL(await realpath(modulePath)).href;
     }
     catch {

package/dist/log-writer-control.js

@@ -26,8 +26,13 @@ import { debug, describeError, reportError } from './diagnostics.js';
 export const CONTROL_HOST = '127.0.0.1';
 const HELLO = 'dokebi-log-writer';
 const VERSION = 1;
-/** A longer line is not this protocol. */
+/** A longer line (in bytes, without its newline) is not this protocol. */
 const MAX_LINE = 4096;
+/** Messages (and their bytes) received but not yet read; the protocol needs one at a time. */
+const MAX_QUEUED = 2;
+const MAX_QUEUED_BYTES = MAX_QUEUED * MAX_LINE;
+const NEWLINE = 0x0a;
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
 /** An unauthenticated connection is closed after this long. */
 const HANDSHAKE_MS = 5000;
 /** The longest stop a client may ask for (one day). */
@@ -43,17 +48,30 @@ function matches(given, expected) {
     const b = Buffer.from(expected);
     return a.length === b.length && timingSafeEqual(a, b);
 }
-/** Newline-delimited JSON over a socket: read one message at a time, write messages. */
+/**
+ * Newline-delimited JSON over a socket: read one message at a time, write messages.
+ *
+ * ISSUE-0006 A05: the limits hold whatever the TCP chunking. Bytes are split on `\n` as they
+ * come; every line (complete or still open) is held to MAX_LINE bytes before it is decoded or
+ * parsed, and a line is taken only while the peer may send one: `expected` messages at first,
+ * then the `replies` each `send` asks for. Anything more is a protocol violation: the queue is
+ * dropped (nothing queued is acted on), next() rejects and the connection is destroyed.
+ */
 class LineSocket {
     socket;
-    #buffer = '';
+    /** The bytes of the line still open (no newline yet). */
+    #pending = [];
+    #pendingBytes = 0;
     #queue = [];
+    #queuedBytes = 0;
+    /** How many more messages the peer may send at this step of the protocol. */
+    #allowance;
     #waiting;
     #failure;
     closed;
-    constructor(socket) {
+    constructor(socket, expected) {
         this.socket = socket;
-        socket.setEncoding('utf8');
+        this.#allowance = expected;
         socket.on('data', (chunk) => this.#data(chunk));
         // Reported to whoever reads next (next() rejects); the socket closes after an error.
         socket.on('error', (error) => this.#fail(error));
@@ -61,28 +79,64 @@ class LineSocket {
         void this.closed.then(() => this.#fail(new Error('connection closed')));
     }
     #data(chunk) {
-        this.#buffer += chunk;
-        for (let end = this.#buffer.indexOf('\n'); end >= 0; end = this.#buffer.indexOf('\n')) {
-            const line = this.#buffer.slice(0, end);
-            this.#buffer = this.#buffer.slice(end + 1);
+        if (this.#failure)
+            return;
+        let start = 0;
+        for (let end = chunk.indexOf(NEWLINE); end >= 0; end = chunk.indexOf(NEWLINE, start)) {
+            const piece = chunk.subarray(start, end);
+            start = end + 1;
+            const bytes = this.#pendingBytes + piece.length;
+            if (!this.#acceptable(bytes))
+                return;
+            const line = this.#pendingBytes ? Buffer.concat([...this.#pending, piece]) : piece;
+            this.#pending = [];
+            this.#pendingBytes = 0;
+            if (this.#queue.length >= MAX_QUEUED || this.#queuedBytes + bytes > MAX_QUEUED_BYTES) {
+                this.#violation('too many messages waiting');
+                return;
+            }
             let message;
             try {
-                message = JSON.parse(line);
+                message = JSON.parse(UTF8.decode(line));
             }
             catch (error) {
-                this.#fail(new Error(`not a protocol message: ${describeError(error).split('\n')[0]}`));
-                this.socket.destroy();
+                this.#violation(`not a protocol message: ${describeError(error).split('\n')[0]}`);
                 return;
             }
-            this.#queue.push(message);
+            this.#allowance--;
+            this.#queue.push({ message, bytes });
+            this.#queuedBytes += bytes;
         }
-        if (this.#buffer.length > MAX_LINE) {
-            this.#fail(new Error(`a line longer than ${MAX_LINE} characters`));
-            this.socket.destroy();
-            return;
+        const rest = chunk.subarray(start);
+        if (rest.length) {
+            if (!this.#acceptable(this.#pendingBytes + rest.length))
+                return;
+            this.#pending.push(rest);
+            this.#pendingBytes += rest.length;
         }
         this.#deliver();
     }
+    /** A line of `bytes` so far may go on: a message is expected and the line is short enough. */
+    #acceptable(bytes) {
+        if (this.#allowance <= 0) {
+            this.#violation('a message the protocol does not expect at this step');
+            return false;
+        }
+        if (bytes > MAX_LINE) {
+            this.#violation(`a line longer than ${MAX_LINE} bytes`);
+            return false;
+        }
+        return true;
+    }
+    #violation(reason) {
+        debug('Control connection broke the protocol', { reason });
+        this.#queue = [];
+        this.#queuedBytes = 0;
+        this.#pending = [];
+        this.#pendingBytes = 0;
+        this.#fail(new Error(reason));
+        this.socket.destroy();
+    }
     #fail(error) {
         this.#failure ??= error;
         this.#deliver();
@@ -92,7 +146,13 @@ class LineSocket {
         if (!waiting || (!this.#queue.length && !this.#failure))
             return;
         this.#waiting = undefined;
-        waiting(this.#queue.length ? this.#queue.shift() : this.#failure);
+        const next = this.#queue.shift();
+        if (next) {
+            this.#queuedBytes -= next.bytes;
+            waiting(next.message);
+        }
+        else
+            waiting(this.#failure);
     }
     /** The next message; rejects when the connection fails or closes first, or after `ms`. */
     next(ms) {
@@ -113,7 +173,9 @@ class LineSocket {
             this.#deliver();
         });
     }
-    send(message) {
+    /** Sends `message`; the peer may then send `replies` messages (the protocol's next step). */
+    send(message, replies = 0) {
+        this.#allowance += replies;
         if (!this.socket.destroyed)
             this.socket.write(`${JSON.stringify(message)}\n`);
     }
@@ -178,7 +240,8 @@ export class ControlServer {
     #connection(socket) {
         this.#sockets.add(socket);
         socket.once('close', () => this.#sockets.delete(socket));
-        const lines = new LineSocket(socket);
+        // The client speaks only after the hello (which allows its proof).
+        const lines = new LineSocket(socket, 0);
         void this.#serve(lines).catch((error) => {
             // A client that broke the protocol or went silent: nothing was done for it.
             reportError('CONTROL_REQUEST_FAILED', 'A control request failed', error, 5000);
@@ -187,7 +250,7 @@ export class ControlServer {
     }
     async #serve(lines) {
         const challenge = randomBytes(24).toString('base64url');
-        lines.send({ hello: HELLO, version: VERSION, challenge });
+        lines.send({ hello: HELLO, version: VERSION, challenge }, 1);
         const hello = await lines.next(HANDSHAKE_MS);
         if (!matches(hello.answer, controlAnswer(this.token, 'client', challenge))) {
             debug('Control client refused: wrong instance proof');
@@ -208,7 +271,7 @@ export class ControlServer {
             answer: controlAnswer(this.token, 'writer', hello.challenge),
             writer: process.pid,
             app: { pid: app.pid, running: app.running() },
-        });
+        }, 1);
         const request = await lines.next(HANDSHAKE_MS);
         if (request.op === 'status') {
             lines.send({ ok: true, app: { pid: app.pid, running: app.running() } });
@@ -266,7 +329,8 @@ export async function askLogWriter(port, token, request,
 stepMs = 3000) {
     const path = `${CONTROL_HOST}:${port}`;
     const socket = createConnection({ host: CONTROL_HOST, port });
-    const lines = new LineSocket(socket);
+    // The writer greets first: one message expected.
+    const lines = new LineSocket(socket, 1);
     const unreached = (reason) => {
         socket.destroy();
         debug('Log writer not reached', { path, reason });
@@ -291,7 +355,7 @@ stepMs = 3000) {
         if (hello.hello !== HELLO || typeof hello.challenge !== 'string')
             return unreached(`${path} is not a dokebi log writer`);
         const challenge = randomBytes(24).toString('base64url');
-        lines.send({ challenge, answer: controlAnswer(token, 'client', hello.challenge) });
+        lines.send({ challenge, answer: controlAnswer(token, 'client', hello.challenge) }, 1);
         const proof = await lines.next(stepMs);
         if (proof.code === 'NOT_READY')
             return unreached('the log writer has not started the app yet');
@@ -303,7 +367,7 @@ stepMs = 3000) {
         if (typeof app?.pid !== 'number' || typeof proof.writer !== 'number')
             return unreached('the log writer sent an unexpected answer');
         debug('Log writer proved the instance token', { path, writer: proof.writer, op: request.op });
-        lines.send(request);
+        lines.send(request, 1);
         const replyMs = request.op === 'stop' ? request.timeoutMs + (request.force ? 5000 : 0) + stepMs : stepMs;
         const reply = await lines.next(replyMs);
         return {

package/dist/npm-client.d.ts

@@ -17,6 +17,8 @@ export interface NpmRun {
     /** The last NPM_OUTPUT_TAIL_BYTES bytes of each stream, redacted. */
     readonly stderr: string;
     readonly stdout: string;
+    /** npm's error code, summary, log file and report file from the whole stderr. */
+    readonly notes: ReturnType<NpmFailureNotes['details']>;
 }
 /**
  * Runs npm in `directory` (the npm that started this CLI when there is one, else `npm` on PATH)
@@ -54,6 +56,23 @@ export declare class OutputTail {
     push(chunk: Buffer): void;
     text(): string;
 }
+/**
+ * What npm says about a failure, read from its whole stderr (not only the bounded tail, which a
+ * long ERESOLVE explanation fills): the error code (`npm error code ERESOLVE`), the line after it
+ * (the summary), the debug log (`A complete log of this run can be found in: …`) and the report
+ * file (`For a full report see:`). Values are redacted; lines are bounded.
+ */
+export declare class NpmFailureNotes {
+    #private;
+    push(chunk: Buffer): void;
+    /** The notes found so far, as NPM_FAILED details (absent ones are left out). */
+    details(): {
+        npmCode?: string;
+        npmSummary?: string;
+        logFile?: string;
+        reportFile?: string;
+    };
+}
 /**
  * Removes credentials npm may print: `user:password@` in URLs, `_authToken=`/`_auth=`/
  * `_password=` values (npmrc lines), bearer tokens and npm access tokens (`npm_…`).