@dokebi/cli 0.4.27 → 0.4.28

package/AI.md

@@ -75,7 +75,7 @@ The `blog` plan, depending on the answers: `init` (when the folder is not a proj
 | `dokebi config secret <id>.<path> [--stdin] [--rotate]` | Writes a random secret (32 bytes; a one-item list when the schema wants a list) into dokebi.yaml, or with `--stdin` a secret you were given (the token of a log receiver: `config secret logging.targets.studio.token --stdin < token.txt`, or typed without echo when stdin is a terminal; one line, at most 64 KiB, nothing or several lines is `INVALID_SET`; the result has `generated: false, stdin: true`). The value never appears in output or logs; an existing value stays (`SECRET_KEPT`, with a `hint` naming `--rotate`); an empty one (`token:`, `''`, `[]`) holds no secret and is filled, and so is the sample's placeholder (`<set the postgres URL here or run npx dokebi dev-infra>`, what `config init` lists in `placeholders`). An address (a key `url` or `uri`, or one ending in `Url` or `Uri`) is never generated: without `--stdin` it is `INVALID_SET` with `details.fix` (`config secret dokebi-db.connections.main.options.url --stdin < url.txt`). Example: `config secret dokebi-websocket-hub.secret`. `logging.<path>` is `options.logging` (the @dokebi/logger options); a list item is named by its `name` (else its `type`) or its index (`logging.targets.studio.token`, `logging.targets.3.token`); a name that is not there is `INVALID_SET` with `details.items`. A secret a plugin declares (such as `dokebi-session.secrets`) is already written by `add`; run it after you removed one. `--rotate` replaces an existing value (AI-M05): a list (`dokebi-session.secrets`, `dokebi-csrf.secrets`, `dokebi-auth.secrets`: the first signs, all verify) gets the new secret **first** and keeps the previous ones after it, at most 2 (`kept`); older ones are dropped (`dropped`, warning `SECRETS_DROPPED` with `count`), and fewer are kept when the schema allows fewer items; when the schema takes no list with a kept one (only a new string or a one-item list), every previous secret is dropped and counted the same way. A string is replaced. The result is `secret{path, list, generated, rotated, kept, dropped}` and a next step to restart the app (`dev` restarts on its own); never a value. What a rotation changes: session cookies signed with a kept secret still verify and are re-signed with the new one as they are used (@dokebi/session); CSRF tokens of a kept secret still verify (@dokebi/csrf); auth stamps signed with a kept key still verify, and remember-me and API tokens are never re-signed, so keep the old key for their longest lifetime (@dokebi/auth AI.md §9). A dropped secret (or a replaced string) invalidates what it signed: sessions end, open forms fail once, logins end. An environment override of the option (`secretsEnv`), where it is set, still wins over dokebi.yaml |
 | `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`). A plugin id that is not installed is `UNKNOWN_PLUGIN`; any other section nothing declares is `UNDECLARED_SECTION` (D-0155: declare it with `npx dokebi settings add <name>`). `logging.<path>` sets `options.logging` (D-0151): with @dokebi/logger every key of its schema (`config set logging.level=debug logging.targets.file.enabled=true`; list items by `name`, else `type`, or index); without it only `logging.level` and `logging.plugins.<plugin>` (core's levels), anything else is `INVALID_SET` with the add command in `fix`. An old option name (D-0071 alias, `dokebi-web.bodyLimit` of `maxBodyBytes`) and its new name both set is `INVALID_PLUGIN_OPTIONS` (`details.errors[]` with `keyword: "conflict"` and the `field`; `fix`: `config unset` the old name), since the plugin refuses both at start; nothing is written. `add` and `upgrade` write no default beside a set old name for the same reason. The results of `config set`, `unset`, `secret` and `diff --write` carry `paths`: for each file it changed, the option paths it `removed`, `set` and `added` (`{ "dokebi.yaml": { removed: ["logging.redact"], set: [], added: [] } }`; a list is one path; never a value). A path outside the ones asked for (named list items count as their list) is `PATH_MISMATCH`: refused, or a warning in a `--dry-run`, which therefore shows exactly what a run would change. Spell paths as the files do (`npx dokebi config show`; the logger's are `logging.<path>`). |
 | `dokebi config unset <id>[.<path>]...` | Removes options ([D-0153](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0153-config-unset.md)) from dokebi.yaml and from dokebi.example.yaml where the sample has them, in one transaction, with the mappings left empty (the plugin section stays): `{ removed: [{ option, files }], changed, warnings?, configRequired? }`. Values are never printed. A path that is not set is the warning `OPTION_NOT_SET` (a repeated call changes nothing); a secret may be removed (warning `SECRET_REMOVED`: what it signed no longer verifies; to replace one use `config secret --rotate`). The plugin need not be installed (a section `dokebi remove` kept). `logging.<path>` removes from `options.logging`, list items by `name` (else `type`) or index (`config unset logging.targets.studio` removes that target); an item that is not there is `OPTION_NOT_SET`. The removal may only leave missing required values (`configRequired`) or issues the options already had (warning `OPTIONS_STILL_INVALID` with the next `hint`); a new issue is `INVALID_PLUGIN_OPTIONS` and nothing is written. Use it for a key a plugin does not know: `INVALID_PLUGIN_OPTIONS` (from add, config set, doctor) names `npx dokebi config unset <id>.<key>` in its `fix`, and a key that moved to another plugin (`dokebi-web.files` → `dokebi-static.mounts`, D-0147) says where it went and the commands that carry it over A section a file still holds as written is that section, never the plugin the name belongs to: in a sample with the old `options.dokebi-logger` (now `options.logging`), `config unset dokebi-logger.level` removes that old key and warns `SECTION_NOT_READ`, and the live `logging.level` stays (AI-M47 report: it removed the live one before); with no such section the plugin id is `PATH_MISMATCH` (name it `logging.<path>`). List indexes and names are of each file as it is before the call, whichever name reaches the section; one item named twice (`logging.targets.studio` and its index) is removed once. A section alone (`config unset dokebi-logger`) removes a whole section nothing reads; a plugin's, the settings' or a core section (`logging`, `reload`) that way is `INVALID_SET` |
-| `dokebi config secrets` | The secret option paths the app needs, **by name, never values** ([D-0184](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0184-production-deploy.md)): `{ file, secretsFile, listed, secrets[{path, source, listed, required}], missing }` from the settings the app reads (`DOKEBI_CONFIG`, else dokebi.yaml) merged with the secrets file `DOKEBI_SECRETS` names. `source` is `config`, `secrets` or `null` (not set: absent, empty or a `<placeholder>`); `listed` means the document's `secrets:` list names it (the app refuses to start without it), `required` that an installed plugin's install plan generates it (`dokebi-session.secrets`). Exit 1 with `ok: false` while `missing` is not empty. Warnings `SECRET_IN_CONFIG_FILE` (with `DOKEBI_SECRETS` set, the settings file still holds a secret) and `SECRETS_PLAN_UNREADABLE` (a plugin's install module could not run: npm install). A secrets file readable by others, or the same option in both files, fails as the app would (`CONFIG_SECRETS_UNSAFE`, `CONFIG_SECRETS_CONFLICT`) |
+| `dokebi config secrets` | The secret option paths the app needs, **by name, never values** ([D-0184](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0184-production-deploy.md)): `{ file, secretsFile, listed, secrets[{path, source, listed, required, type}], missing }` from the settings the app reads (`DOKEBI_CONFIG`, else dokebi.yaml) merged with the secrets file `DOKEBI_SECRETS` names. `source` is `config`, `secrets` or `null` (not set: absent, empty or a `<placeholder>`); `listed` means the document's `secrets:` list names it (the app refuses to start without it), `required` that an installed plugin's install plan generates it (`dokebi-session.secrets`). `type` is the option's JSON Schema type (`string`; `array` for a list such as `dokebi-session.secrets`, `dokebi-auth.secrets`, `dokebi-csrf.secrets`, `dokebi-mail.secrets`; several as a list; `null` without a schema): a tool that writes the secrets file writes an `array` as a YAML list, even of one value (a text there is `INVALID_PLUGIN_OPTIONS`). Exit 1 with `ok: false` while `missing` is not empty. Warnings `SECRET_IN_CONFIG_FILE` (with `DOKEBI_SECRETS` set, the settings file still holds a secret) and `SECRETS_PLAN_UNREADABLE` (a plugin's install module could not run: npm install). A secrets file readable by others, or the same option in both files, fails as the app would (`CONFIG_SECRETS_UNSAFE`, `CONFIG_SECRETS_CONFLICT`) |
 | `dokebi deploy init [--target <systemd\|compose>] [--instance <name>]... [--port <n>] [--dry-run]` | **An existing project made ready for a server** (D-0184, §11): per instance (`production` port 3000, `staging` 3001, another name needs `--port`; two instances never share a port: `PORT_IN_USE`) `deploy/<instance>/dokebi.example.yaml` (the sample without its secrets, with the instance's web host/port/trustProxy, storage folder and a `secrets:` list), `deploy/<instance>/secrets.example.yaml` (the secret paths with placeholders), `deploy/systemd/<app>-<instance>.service` (or `deploy/compose/<instance>.yaml` with `--target compose`, and Dockerfile/.dockerignore when missing), with @dokebi/db also `deploy/systemd/<app>-<instance>-backup.service`/`.timer`, `deploy/backup.mjs` and `deploy/restore-drill.mjs`, and `DEPLOY.md`. Result `{ app, target, instances[{instance, port, unit, settings, secrets, code, data, logs, backups, database}], secrets, changed, unchanged, kept }`. A second run changes nothing; a file you edited since is kept (`kept`, warning `DEPLOY_FILE_KEPT`); an untouched one is rewritten (DEPLOY.md gains a new instance). Errors `NOT_A_PROJECT`, `APP_NAME_INVALID` (package.json name), `EXAMPLE_MISSING`, `PORT_REQUIRED`, `PORT_IN_USE`, `OPTIONS_SCHEMA_UNREADABLE` (npm install first: without a plugin's schema its secrets cannot be told apart) |
 | `dokebi deploy proxy --caddy\|--nginx --domain <host>... [--instance <name>] [--dry-run]` | The reverse proxy file of an instance (D-0184): `deploy/proxy/<app>-<instance>.Caddyfile` or `.nginx.conf`, from `deploy/<instance>/dokebi.example.yaml` (port, health routes, body limit, request timeout): TLS (Caddy's automatic certificates; nginx with certbot's paths and an http → https redirect), `X-Forwarded-For/Proto/Host`, WebSocket upgrades, unbuffered SSE (the app sends `X-Accel-Buffering: no`) and a long read timeout when the app keeps streams (SSE, WebSocket, MCP), `/health/live` and `/health/ready` passed through uncached, the app's own `Cache-Control` and compression left as they are. Warnings `TRUST_PROXY_MISSING` (the sample's `dokebi-web.trustProxy` lacks 127.0.0.1 or ::1) and `DOMAIN_NOT_MAPPED` (a domain not in `dokebi-app.domains`). Errors `WEB_NOT_INSTALLED`, `INSTANCE_UNKNOWN` (deploy init first) |
 | `dokebi dev-infra [up\|start\|stop\|down\|status] [--file <path>] [--db-port <n>] [--dry-run]` | Without an action: prepare compose.yaml and the database URL in dokebi.yaml; no .env is generated. With an action: run Docker Compose using the YAML password in the child environment only. Repeat --file for additional Compose files. down retains data volumes. --db-port and --dry-run apply only to preparation. On a kept compose.yaml (`COMPOSE_KEPT`, its published port is the URL's) `--db-port <n>` changes only the published host port of `services.db` in it (every other byte of the file stays) and the URL in dokebi.yaml, with the warning `COMPOSE_PORT_CHANGED` (`hint`: `dev-infra up` recreates a running container on the new port and keeps its data volume); a taken port is `PORT_IN_USE`. A port entry the CLI cannot read (a variable, a range) refuses `--db-port` with `COMPOSE_PORT_UNKNOWN` (`details.file`, `details.fix`: set the entry yourself) and nothing is written; without the flag the run keeps the URL's port and warns `COMPOSE_PORT_UNKNOWN`. A MongoDB is a single-node replica set (`rs0`, D-0103): the generated mongod gets `--replSet rs0` and a key file made inside the container at each start (mongod needs one for a replica set with authentication), the healthcheck initiates the set once and passes when the member is the writable primary (so `up` returns when transactions work), and the URL ends with `replicaSet=rs0&directConnection=true`; `service.replicaSet` says so. A kept compose.yaml whose server is standalone (written before) keeps a standalone URL and gives the warning `DEV_INFRA_STANDALONE`, whose `hint` is the switch: `dev-infra down`, move compose.yaml away, `dev-infra --db-port <its port>`, `dev-infra up` (password and data volume kept). `DEV_INFRA_CONFIG_INVALID` means the main database URL is invalid/unset; `DEV_INFRA_FAILED` means the Compose action failed. |

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.27",
+  "cli": "0.4.28",
   "core": {
     "package": "@dokebi/core",
-    "version": "0.4.3"
+    "version": "0.4.4"
   },
   "capabilities": {
     "admin.ui": {
@@ -713,7 +713,7 @@
     {
       "id": null,
       "package": "@dokebi/cli",
-      "version": "0.4.27",
+      "version": "0.4.28",
       "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.",
@@ -860,7 +860,7 @@
     {
       "id": null,
       "package": "@dokebi/core",
-      "version": "0.4.3",
+      "version": "0.4.4",
       "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.",
@@ -2111,7 +2111,7 @@
     {
       "id": "dokebi-oauth",
       "package": "@dokebi/oauth",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "kind": "plugin",
       "summary": "OAuth 2.1 authorization server on @dokebi/auth tokens: authorization code with PKCE S256, refresh rotation and reuse detection, revocation, client ID metadata documents, protected resource metadata and protected routes",
       "description": "OAuth 2.1 authorization server for @dokebi/web on @dokebi/auth tokens: authorization code with PKCE, refresh rotation, revocation, client ID metadata documents, protected resource metadata and route protection.",
@@ -2784,7 +2784,7 @@
     {
       "id": "dokebi-seal",
       "package": "@dokebi/seal",
-      "version": "0.4.2",
+      "version": "0.4.3",
       "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",

package/dist/config-secrets.d.ts

@@ -8,6 +8,12 @@ export interface SecretEntry {
     readonly listed: boolean;
     /** A secret a plugin's install plan generates (dokebi-session.secrets): it needs one. */
     readonly required: boolean;
+    /**
+     * The JSON Schema type of the option, from its options schema (`string`; `array` for a list
+     * such as dokebi-session.secrets, written as a YAML list in the secrets file), several types as
+     * a list, null when no schema says (a section without one).
+     */
+    readonly type: string | readonly string[] | null;
 }
 export interface ConfigSecretsWarning {
     readonly code: 'SECRET_IN_CONFIG_FILE' | 'SECRETS_PLAN_UNREADABLE';
@@ -30,6 +36,8 @@ export interface ConfigSecretsResult {
         why: string;
     }>;
 }
+/** The JSON Schema types the option at `keys` may have (properties, records, anyOf/oneOf). */
+export declare function schemaTypes(schema: unknown, keys: readonly string[]): Set<string>;
 /**
  * The secrets the installed plugins generate at install (their plans' `configSecrets`, such as
  * `dokebi-session.secrets`): each plugin needs one to start.

package/dist/config-secrets.js

@@ -13,6 +13,7 @@ import { optionsKey } from './manifest.js';
 import { dependencyMap } from './npm-client.js';
 import { planLifecycle } from './plugin-lifecycle.js';
 import { readState } from './project-state.js';
+import { reloadSchemas } from './reloadable.js';
 function valueAt(options, path) {
     let value = options;
     for (const key of path) {
@@ -33,6 +34,40 @@ function empty(value) {
         (Array.isArray(value) && (value.length === 0 || value.every(isPlaceholder))) ||
         (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0));
 }
+/** The JSON Schema types the option at `keys` may have (properties, records, anyOf/oneOf). */
+export function schemaTypes(schema, keys) {
+    const types = new Set();
+    const walk = (node, rest, depth) => {
+        if (!node || typeof node !== 'object' || depth > 32)
+            return;
+        const value = node;
+        for (const branch of ['anyOf', 'oneOf', 'allOf'])
+            if (Array.isArray(value[branch]))
+                for (const item of value[branch])
+                    walk(item, rest, depth + 1);
+        if (!rest.length) {
+            if (typeof value.type === 'string')
+                types.add(value.type);
+            return;
+        }
+        const [key, ...tail] = rest;
+        const properties = value.properties;
+        if (properties && Object.hasOwn(properties, key))
+            walk(properties[key], tail, depth + 1);
+        else if (value.additionalProperties && typeof value.additionalProperties === 'object')
+            walk(value.additionalProperties, tail, depth + 1);
+        else if (/^\d+$/.test(key) && value.items)
+            walk(value.items, tail, depth + 1);
+    };
+    walk(schema, keys, 0);
+    return types;
+}
+/** The type of the option at `path` as `SecretEntry.type` says it. */
+function typeOf(schemas, path) {
+    const [section = '', ...rest] = path.split('.');
+    const types = [...schemaTypes(schemas.get(section), rest)].sort();
+    return types.length === 0 ? null : types.length === 1 ? types[0] : types;
+}
 /** The same failure as the app's start, as a CLI error with the paths and no values. */
 function configFailure(error) {
     return new CliError(error.code, error.message, {
@@ -126,6 +161,9 @@ export async function configSecrets(root, env = process.env) {
         : (await configShow(root, undefined, { source: secretsText, file: secretsFile }))
             .secrets);
     const planned = await requiredSecretPaths(root, document.options);
+    const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    // The types tell a tool that writes the secrets file a list from a text (Studio v2, 11-01).
+    const schemas = await reloadSchemas(root, state.plugins, state.settings ?? []);
     const required = new Set(planned.paths);
     const listed = document.secrets ?? [];
     const paths = [...new Set([...fromConfig, ...fromSecrets, ...listed, ...required])].sort();
@@ -136,6 +174,7 @@ export async function configSecrets(root, env = process.env) {
             source: !set ? null : !empty(valueAt(secretOptions, path.split('.'))) ? 'secrets' : 'config',
             listed: listed.includes(path),
             required: required.has(path),
+            type: typeOf(schemas, path),
         };
     });
     const missing = secrets.filter((entry) => entry.source === null).map((entry) => entry.path);
@@ -180,7 +219,7 @@ export async function configSecrets(root, env = process.env) {
 }
 /** The result for people: one line per path. */
 export function configSecretsText(result) {
-    const lines = result.secrets.map((entry) => `${entry.source === null ? 'MISSING' : entry.source.padEnd(7)} ${entry.path}${entry.listed ? ' (listed)' : ''}${entry.required ? ' (required)' : ''}`);
+    const lines = result.secrets.map((entry) => `${entry.source === null ? 'MISSING' : entry.source.padEnd(7)} ${entry.path}${entry.type === 'array' ? ' (a list)' : ''}${entry.listed ? ' (listed)' : ''}${entry.required ? ' (required)' : ''}`);
     return `${lines.join('\n') || 'no secret options'}\n${result.missing.length ? `missing: ${result.missing.join(', ')}` : 'no secret missing'}${(result.warnings ?? [])
         .map((warning) => `\nwarning: ${warning.code} (${warning.path}): ${warning.hint}`)
         .join('')}\n`;

package/dist/deploy.js

@@ -6,7 +6,7 @@ import { dirname, join } from 'node:path';
 import { parseConfig } from '@dokebi/config';
 import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
 import { isPlaceholder } from './config-init.js';
-import { requiredSecretPaths, unreadableWarning } from './config-secrets.js';
+import { requiredSecretPaths, schemaTypes, unreadableWarning } from './config-secrets.js';
 import { configShow } from './config-show.js';
 import { CONFIG_FILE, renderConfig } from './configuration.js';
 import { BACKUP_SCRIPT, RESTORE_DRILL_SCRIPT } from './deploy-scripts.js';
@@ -156,34 +156,6 @@ function valueAt(options, path) {
     }
     return value;
 }
-/** The JSON Schema types the option at `keys` may have (properties, records, anyOf/oneOf). */
-function schemaTypes(schema, keys) {
-    const types = new Set();
-    const walk = (node, rest, depth) => {
-        if (!node || typeof node !== 'object' || depth > 32)
-            return;
-        const value = node;
-        for (const branch of ['anyOf', 'oneOf', 'allOf'])
-            if (Array.isArray(value[branch]))
-                for (const item of value[branch])
-                    walk(item, rest, depth + 1);
-        if (!rest.length) {
-            if (typeof value.type === 'string')
-                types.add(value.type);
-            return;
-        }
-        const [key, ...tail] = rest;
-        const properties = value.properties;
-        if (properties && Object.hasOwn(properties, key))
-            walk(properties[key], tail, depth + 1);
-        else if (value.additionalProperties && typeof value.additionalProperties === 'object')
-            walk(value.additionalProperties, tail, depth + 1);
-        else if (/^\d+$/.test(key) && value.items)
-            walk(value.items, tail, depth + 1);
-    };
-    walk(schema, keys, 0);
-    return types;
-}
 /** A placeholder for a secret of the secrets sample, saying what goes there (never a value). */
 function placeholderFor(path, at, current, types) {
     const kind = typeof current === 'string'

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "0.4.27";
+export declare const CLI_VERSION = "0.4.28";
 export declare function envelope(command: string, result: unknown, ok?: boolean): object;
 export declare function failure(command: string, error: unknown, mutationStarted: boolean): object;

package/dist/output.js

@@ -1,5 +1,5 @@
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.4.27';
+export const CLI_VERSION = '0.4.28';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/cli",
-  "version": "0.4.27",
+  "version": "0.4.28",
   "description": "Project scaffolding, plugin catalog, recipes, install and verification CLI for Dokebi.",
   "keywords": [
     "dokebi",