@dokebi/cli 0.4.1 → 0.4.26

package/README.md

@@ -1,35 +1,37 @@
 # @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, with the installed version recorded in package.json (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
 
 - Outside a project: `npx -y @dokebi/cli@<version> init <new folder>` (the version may be left out). Inside a project: `npx dokebi …` (init puts `@dokebi/cli` in devDependencies, so that copy runs).
 - The npm package named `dokebi` is not this CLI: `npx -y dokebi` runs someone else's code, never use it.
-- Every command takes `--json` (one machine-readable document on stdout) and every changing command takes `--dry-run` (plan only; it may download and install into a temporary folder to read packages, but it never applies managed files or node_modules). `dokebi --help` lists every command; `dokebi <command> --help` explains each flag of one command with an example.
+- Use `--json` for one machine-readable document on stdout, except for interactive `dev`, `logs` and `start --foreground`. Use `--dry-run` only on commands that list it in help (plan only; it may download and install into a temporary folder to read packages, but never applies managed files or node_modules). `dokebi --help` lists every command; `dokebi <command> --help` explains each flag of one command with an example.
 
 ## AI entry (D-0065)
 
 - `dokebi guide`: the AI first page (steps, rules, recipes, what Dokebi does not have, commands). `dokebi --help` starts by pointing to it.
-- `dokebi recipe list` and `dokebi recipe <name>` (`blog`, `api`): without answers they install nothing and return the questions with `waitForUser` (ask the user, end your turn); with answers they plan and apply. Applying needs the source of the answers, `--answers-from user` or `--defaults`. The result's `report` (answers, defaults, no CSRF protection for HTML forms) goes to the user.
-- `dokebi plugins list|search|info|doc`: the catalog inside this CLI (`catalog.json`) and what Dokebi does not have (absent: auth, csrf, upload, mail, markdown, rss, rate-limit, i18n, sqlite, React, ORM, admin generator, search). `plugins doc` prints the AI.md of the installed version.
-- `dokebi verify`: doctor, check, typecheck, build, start, HTTP checks and stop; say done only when it is `ok`. HTTP counts only answers of the app verify started (the `x-dokebi-verify` token), and stop uses that pid without `ps`.
-- `dokebi check`: seven user-code convention rules (D-0072): `empty-catch`, `floating-promise`, `non-erasable-syntax`, `private-import`, `missing-package`, `generated-file`, `secret-in-config`. Each problem has file, line and fix; `// dokebi-check: allow <rule> <reason>` silences an intended empty catch or background promise.
-- `dokebi config set|secret` and `dokebi dev-infra` (compose.yaml, .env and the URL of the development database).
-- The project's `.env` (D-0073): `dev`, `start` and `verify` pass it to the app, under the environment (a variable already set wins; values are never printed; a malformed line is `ENV_FILE_INVALID`). `add` generates the secrets a plugin declares into it (for example @dokebi/session's `DOKEBI_SESSION_SECRETS`) and reports only their names (`generatedSecrets`). `.env` stays out of Git.
+- `dokebi recipe list` and `dokebi recipe <name>` (`blog`, `api`, `site`): without answers they install nothing and return the questions with `waitForUser` (ask the user, end your turn); with answers they plan and apply. Applying needs the source of the answers, `--answers-from user` or `--defaults`; `--answers-from user` only for choices the user or the request explicitly made, and anything the AI decided goes in `--ai-chose` (with `--ai-reason`), so each answer records who made it (D-0095). The result's `report` (answers, defaults, how the forms send the CSRF token, where the admin login is) goes to the user. The `blog` recipe installs @dokebi/csrf for its write forms, and `--admin login` sets up @dokebi/auth with the app's own user table, a login page and a first admin (D-0076 §6).
+- `dokebi plugins list|search|info|doc`: the catalog inside this CLI (`catalog.json`) and what Dokebi does not have (absent: two-factor login, OAuth, markdown, rss, sqlite, React, ORM, admin generator, search). `plugins doc` prints the AI.md of the installed version.
+- `dokebi verify`: doctor, check, typecheck, build, test (the project's `npm test`; with node:test a result per test, a leading `[ID]` of a name as its `id`), start, HTTP checks and stop; say done only when it is `ok`. HTTP counts only answers of the app verify started (the `x-dokebi-verify` token), and stop uses that pid without `ps`.
+- `dokebi describe`: what the app has, without serving (D-0077): routes with their id, schema and login rule, pages (EJS views, Inertia components), jobs, schedules, error codes, option keys and environment variable names (never a value). It loads the project like `start` in core's describe mode: every setup runs, nothing listens or connects. `--json` follows `describe.schema.json` in this package.
+- `dokebi describe --openapi [--app <name>]`: an OpenAPI 3.1 document per app from the same description (D-0077 C): `operationId` is the route id, request and response schemas come from the route schemas, the error answers use the D-0074 body (422 `VALIDATION_FAILED`, 401, 403 for roles, `can` and CSRF), `cookieAuth` and `bearerAuth` follow the login rules, the app's error codes are `x-dokebi-errors`. Several apps without `--app`: `{ apps: { <name>: document } }`.
+- `dokebi check`: user-code convention rules (D-0072): `empty-catch`, `missing-cause` (a catch that throws a new error without the caught one, D-0118), `floating-promise`, `non-erasable-syntax`, `private-import`, `missing-package`, `generated-file`, `secret-in-config`; the warning `inertia-form-only` (D-0074); and, with @dokebi/auth or @dokebi/csrf installed, `plain-password-compare`, `form-without-csrf` and `csrf-exempt-unverified` (D-0076 §6); `background-timer` (periodic work on the app's own timers) and the warnings `responsibility-size` and `memory-filtered-page` (D-0105). Each problem has file, line and fix; `// dokebi-check: allow <rule> <reason>` silences an intended case.
+- `dokebi config show|set|unset|secret` and `dokebi dev-infra` (compose.yaml and the URL of the development database in dokebi.yaml, with its password; no .env is written). `config unset <id>.<path>...` removes options from dokebi.yaml and dokebi.example.yaml without printing them (D-0153; the fix of an unknown key names it). `config show [<id>[.<path>]]` prints the options with every secret hidden (`<secret: set>`): use it instead of cat or sed on dokebi.yaml. `config secret <id>.<path> --rotate` replaces a secret; a list keeps the previous two after the new one, so what they signed still verifies.
+- Secrets live in `dokebi.yaml` (0600, kept out of Git; D-0073 addendum 2): `add` writes the secrets a plugin declares (for example @dokebi/session's `secrets`) and reports only their names (`generatedSecrets`); `config secret <id>.<path>` generates one later. An environment variable is only an optional production override where a plugin documents one. An existing `.env` is still passed to the app by `dev`, `start` and `verify` (a variable already set wins; a malformed line is `ENV_FILE_INVALID`).
 - The full contract is in [AI.md](AI.md) §0.
 
 ## Commands
 
 - dokebi init <folder> [--core <core package spec>] [--dry-run]: prepares a project with core and the required config. devDependencies get this CLI (same version), typescript and @types/node, scripts `start` and `typecheck`, AGENTS.md (with the installed list) and CLAUDE.md, and the result names the next steps (`nextSteps`). The folder must be new or empty (a folder with only `.git`, `.npmrc`, `.npm`, `.npm-cache`, `.DS_Store`, `Thumbs.db`, `.idea`, `.vscode` works too: `init .`). Anything else is `PROJECT_EXISTS`.
-- dokebi add <npm package spec or local tgz> [--set <path>=<value>] [--adapter <id>] [--no-first-app] [--dry-run]: installs and registers an optional plugin (and the plugins it requires). Without a version it picks the newest version for this core.
+- dokebi add <npm package spec or local tgz> [--set <path>=<value>] [--adapter <id>] [--startup <required|optional>] [--no-first-app] [--dry-run]: installs and registers an optional plugin (and the plugins it requires). Without a version it picks the newest version for this core.
 - dokebi upgrade <plugin ID> [--to <version|package|tgz>] [--dry-run]: changes a plugin's version. A changed manifest under the same version is applied again.
 - dokebi remove <plugin ID> [--dry-run]: removes an optional plugin nothing depends on. Required parts cannot be removed.
 - dokebi app add|remove|link|unlink|list: `src/apps/<app>` and its domains (@dokebi/app). `app add --inertia [--ssr]` also prepares the Vue skeleton, the build and server rendering.
 - dokebi module add|remove|list: feature modules `src/shared/modules/<module>` (@dokebi/module).
 - dokebi migrate [--dry-run]: moves an existing JSON project to the YAML contract, explicitly.
 - dokebi inspect, dokebi doctor: read-only checks of installed versions, manifests, schemas and settings (`--verbose` for everything; `--json` is always complete).
-- dokebi dev: a development run that restarts when code or settings change (with a Vite config and a current template-inertia, the Vite dev server runs inside the app with HMR).
+- dokebi dev: a development run that restarts when code or settings change (with a Vite config and a current template-inertia, the CLI shares one Vite dev host with HMR across app workers).
 - dokebi start [--foreground] [--log-max-mb <MB>] [--log-files <n>] · stop [--force] · status · logs [-n <lines>] [-f]: background run, stop, state and logs in `.dokebi/run/app.pid` and `app.log`. Where `ps` is blocked (agent sandboxes), `stop` and `status` prove the recorded pid is this app through its log writer's loopback control port (`proof: log-writer`) or by an HTTP challenge the app answers (@dokebi/web, `proof: http`), both keyed with the per-start `DOKEBI_INSTANCE_TOKEN`; without a proof they refuse with `PROCESS_INFO_FAILED` as before. Where this shell may not even signal the app (a sandbox per command), the log writer, which started the app, stops it on request (`via: log-writer`). A separate writer process takes the log through a pipe, loses no line and rotates by size (default 50 MB, `app.log.1`…`app.log.5`, [D-0053](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0053-cli-log-rotation.md)). `logs -n` reads rotated files too, and `-f` follows across rotations (it tracks files by inode, so it skips no line even when several rotations happen between two checks). There is no automatic restart, so in production use `start --foreground` under systemd or Docker ([D-0044](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0044-cli-server-commands.md)).
 
 The generated app runs with npm start. Call the commands with the installed CLI from the project root (or an npm workspace member folder).
@@ -69,3 +71,26 @@ The catalog entry of a package is `dokebiCatalog` in its package.json (outside t
 User-edited templates are kept on remove. Install scripts never run, but package code runs when the app runs, so use plugins you trust. git or URL dependencies and automatic recovery after a forced kill are not supported. Windows and production hardening are outside the verified scope, as the repository records say.
 
 MIT license. See the [AI contract](AI.md) and the [repository](https://git.nyx-zone.com/dokebi/framework).
+
+
+## Development mail (D-0078 MP4)
+
+The blog and API recipes ask `--mail none|mailpit|smtp|ses` (default `none`). `mailpit` starts a local Mailpit inbox and NATS queue using `compose.mail.yaml`, with free loopback ports selected and persisted in Compose by the CLI so restart keeps the saved YAML addresses. Existing `compose.yaml` is preserved. Find the inbox with `docker compose -f compose.mail.yaml port mailpit 8025`; stop it with `docker compose -f compose.mail.yaml down` (`-v` also deletes queued messages). SMTP and SES require an installed `@dokebi/mail` with the selected transport and sender configured in `dokebi.yaml`; credentials never belong on a command line. Missing settings produce `MAIL_CONFIGURATION_REQUIRED` before applying. Recovery with mail also needs a provisioned job queue (`MAIL_QUEUE_REQUIRED`). The initial admin name has no email: map an email in the auth extension before using recovery.
+
+| Command | Purpose |
+|---|---|
+| `dokebi mail preview <name> [--locale <locale>]` | Render the template's `preview.json` in describe mode, without connecting, sending or running data hooks. `--json` returns subject, html, text and resolved locale in the standard envelope. Missing names are `MAIL_TEMPLATE_NOT_FOUND`. |
+
+Mail templates live in `src/shared/mail/`; install writes a user-owned welcome sample. `describe` lists their names, locales and files. With mail installed, `check` adds two warnings: `mail-send-in-request` recommends `queue` in route handlers, and `mail-secret-in-data` recommends `sealed` for sensitive token/password/link-like fields. These name-based source heuristics do not replace a security review.
+
+## Deployment skeleton
+
+`dokebi init <directory> --deploy` also writes `Dockerfile`, `.dockerignore`, `compose.deploy.yaml` and `DEPLOY.md` inside the new project transaction. `--dry-run --json` reports `deployment.files` without writing or installing. It does not deploy or start services. Read `DEPLOY.md` before building: keep runtime secrets out of the image, mount `dokebi.yaml` read-only, configure the container web host/port and public domains, and prepare databases, queues and migrations separately. A core-only app exits when idle. Use a new folder; init never overlays an existing project.
+
+## Multi-app site recipe
+
+`dokebi recipe site` asks `--apps` (web/admin/api combinations, or none), `--domains` (app=host pairs, or auto), `--realms` (app=realm pairs, or auto), `--view` and `--worker none|thread|job`. Text questions have `input: "text"` and an empty options list; present their question and accept a text answer. The same answer-source and wait-for-user rules apply. `auto` selects separate `<app>.<project>.localhost` domains (unique to this project, so another project's cookies never collide) and realms; it is used only when explicitly answered or delegated through defaults. Duplicate domains, missing mappings and invalid realm names fail before mutation.
+
+The site recipe creates a new project or fills a project without existing apps. Its `.dokebi/site-plan.json` checkpoint permits repeating the same choices after a partial failure; different choices require explicit app/config edits. Admin and API routes require authentication; public web routes are optional. Generated user lookups deny all logins until connected to your own user store. No account database or working login UI is claimed. Shared realms do not automatically share host-only cookies. Read `SITE.md` before running the site. A thread worker uses the generated CPU task module; a job worker needs a configured NATS endpoint and `npx dokebi-job-provision --queue siteWorker`. Both run in the same process; `--apps none` makes a worker-only project.
+
+HTTP verification treats 401/403 from this run's instance on an app domain as reachable and reports `accessDenied: true`; it does not verify login. Readiness endpoints still require 2xx/3xx, and 400/404/5xx domain responses fail. Application tests must cover authentication and authorization.