@dokebi/cli 0.4.2 → 0.4.26

package/dist/generator.js

@@ -1,4 +1,4 @@
-import { hostOf } from './manifest.js';
+import { findHost, hostOf } from './manifest.js';
 import { CLI_VERSION } from './output.js';
 /** Import specifier of a user entry file, relative to src/dokebi.generated.ts. */
 function entrySpecifier(target) {
@@ -16,45 +16,64 @@ function entrySpecifier(target) {
  *
  * The CLI-managed units reach the plugin whose manifest declares their role (D-0070
  * `dokebi.hosts`): `apps` (`dokebi app add`, src/apps/<name>/app.ts) and `modules`
- * (`dokebi module add`, src/shared/modules/<name>/module.ts).
+ * (`dokebi module add`, src/shared/modules/<name>/module.ts). The `logger` host (D-0151) gives
+ * the exported `createLogger` (src/main.ts passes its logger to the Application, so it writes
+ * from the first setup record), receives that logger as `entry.logger` and its options from
+ * `options.logging`; without one, `createLogger` returns undefined (core's console logger).
  */
-export function generateRegistration(plugins, installations = {}, apps = [], modules = []) {
+export function generateRegistration(plugins, installations = {}, apps = [], modules = [], settings = []) {
     for (const [role, units] of [
         ['apps', apps],
         ['modules', modules],
     ])
         if (units.length)
             hostOf(plugins, role);
+    const logger = findHost(plugins, 'logger');
     const imports = [];
     const factories = [];
     /** Plugins the CLI passes an entry (an entry file or the units they host). */
     const withEntry = new Set();
     plugins.forEach((plugin, index) => {
-        imports.push(`import { createPlugin as factory${index} } from ${JSON.stringify(plugin.packageName)};`);
         const entry = installations[plugin.id]?.entry;
+        if (plugin === logger) {
+            imports.push(`import { createLogger as loggerFactory, createPlugin as factory${index} } from ${JSON.stringify(plugin.packageName)};`);
+            factories.push(`    factory${index}({ app: app.view, options: optionsOf('logging'), entry: appLogger === undefined ? undefined : { logger: appLogger } }),`);
+            withEntry.add(plugin.id);
+            return;
+        }
+        imports.push(`import { createPlugin as factory${index} } from ${JSON.stringify(plugin.packageName)};`);
         if (entry) {
             imports.push(`import * as entry${index} from ${JSON.stringify(entrySpecifier(entry))};`);
             withEntry.add(plugin.id);
         }
-        let entryCode = entry ? `, entry: entry${index}` : '';
+        // The units of the roles the plugin hosts, together in one entry: a plugin hosting apps and
+        // modules (or apps with an entry file of its own) used to get only the last of them.
+        const units = [];
         // The apps host receives the apps recorded by `dokebi app add` (src/apps/<name>/app.ts).
         if (plugin.hosts?.includes('apps')) {
             apps.forEach((name, appIndex) => {
                 imports.push(`import app${appIndex} from ${JSON.stringify(`./apps/${name}/app.ts`)};`);
             });
-            entryCode = `, entry: { apps: { ${apps.map((name, appIndex) => `${JSON.stringify(name)}: app${appIndex}`).join(', ')} } }`;
-            withEntry.add(plugin.id);
+            units.push(`apps: { ${apps.map((name, appIndex) => `${JSON.stringify(name)}: app${appIndex}`).join(', ')} }`);
         }
         // The modules host receives the modules recorded by `dokebi module add` (D-0032), after the
         // list of an older entry file (src/shared/modules/index.ts) when the project still has one.
-        if (plugin.hosts?.includes('modules') && modules.length) {
+        const hostsModules = plugin.hosts?.includes('modules') === true && modules.length > 0;
+        if (hostsModules) {
             modules.forEach((name, moduleIndex) => {
                 imports.push(`import module${moduleIndex} from ${JSON.stringify(`./shared/modules/${name}/module.ts`)};`);
             });
             const list = modules.map((_name, moduleIndex) => `module${moduleIndex}`);
-            entryCode = `, entry: { modules: [${[...(entry ? [`...entry${index}.modules`] : []), ...list].join(', ')}] }`;
-            withEntry.add(plugin.id);
+            units.push(`modules: [${[...(entry ? [`...entry${index}.modules`] : []), ...list].join(', ')}]`);
         }
+        const own = entry && !hostsModules ? `...entry${index}, ` : '';
+        const entryCode = units.length
+            ? `, entry: { ${own}${units.join(', ')} }`
+            : entry
+                ? `, entry: entry${index}`
+                : '';
+        if (units.length)
+            withEntry.add(plugin.id);
         factories.push(`    factory${index}({ app: app.view, options: optionsOf(${JSON.stringify(plugin.id)})${entryCode} }),`);
     });
     // Plugins with an entry may receive user-chosen dependencies (for example web requires),
@@ -65,8 +84,35 @@ export function generateRegistration(plugins, installations = {}, apps = [], mod
         dependencies: plugin.dependencies.map((dependency) => dependency.name),
         entry: withEntry.has(plugin.id),
     }));
+    const loggerCode = logger
+        ? `let appLogger: ReturnType<typeof loggerFactory> | undefined;
+
+/**
+ * The app logger of ${logger.packageName} (D-0151) from options.logging: src/main.ts passes it to
+ * new Application({ logger }), so it writes from the first setup record. Created once.
+ */
+export function createLogger(options: Readonly<Record<string, unknown>>): Logger | undefined {
+  appLogger ??= loggerFactory({ options });
+  return appLogger;
+}`
+        : `/**
+ * No logger plugin is installed (D-0151): undefined, so the Application uses core's console
+ * logger. npx dokebi add @dokebi/logger makes this return its logger.
+ */
+export function createLogger(_options: Readonly<Record<string, unknown>>): Logger | undefined {
+  return undefined;
+}`;
+    // D-0155: the settings sections of the application, checked at start like plugin options.
+    settings.forEach((section, index) => {
+        imports.push(`import settings${index} from ${JSON.stringify(`./shared/settings/${section}.ts`)};`);
+    });
+    const settingsCode = settings.length
+        ? `  // The settings of the application (src/shared/settings): options.<section>, checked here.
+${settings.map((_section, index) => `  app.register(settings${index}.plugin({ app: app.view }));`).join('\n')}
+`
+        : '';
     return `// Generated by dokebi. Change dokebi.yaml options or plugin entry files instead of this file.
-import type { Application, Plugin } from '@dokebi/core';
+import type { Application, Logger, Plugin } from '@dokebi/core';
 ${imports.join('\n')}
 
 const MANIFESTS: readonly {
@@ -76,13 +122,15 @@ const MANIFESTS: readonly {
   entry: boolean;
 }[] = ${JSON.stringify(manifests)};
 
+${loggerCode}
+
 /**
  * Creates and registers the installed plugins. Each factory checks its options.<plugin> section
  * of dokebi.yaml with the plugin's own declaration; an invalid value fails here with
  * INVALID_PLUGIN_OPTIONS (the plugin, the option paths and a fix).
  */
 export async function registerPlugins(app: Application): Promise<void> {
-  const options: Record<string, unknown> = app.config;
+${settingsCode}  const options: Record<string, unknown> = app.config;
   const optionsOf = (id: string): unknown =>
     Object.hasOwn(options, id) && options[id] !== null ? options[id] : {};
   const plugins: Plugin<unknown>[] = [
@@ -116,12 +164,53 @@ try {
   await app.stop();
 }
 `;
-export const MAIN_SOURCE = `import { Application, loadConfig } from '@dokebi/core';
+/**
+ * The long-running entry point before D-0151 (core's console logger only). `add` of a logger
+ * plugin rewrites an unchanged copy to MAIN_SOURCE; migrate still recognizes it.
+ */
+export const MAIN_SOURCE_V2 = `import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Application, loadConfig } from '@dokebi/core';
 import { registerPlugins } from './dokebi.generated.ts';
 
-const document = await loadConfig(new URL('../dokebi.yaml', import.meta.url));
+const configPath = resolve(process.env.DOKEBI_CONFIG ?? fileURLToPath(new URL('../dokebi.yaml', import.meta.url)));
+process.env.DOKEBI_CONFIG = configPath;
+const document = await loadConfig(configPath);
 const app = new Application({ config: document.options });
 await registerPlugins(app);
+app.logger.log('info', 'Dokebi application started');
+
+// The app runs until SIGINT/SIGTERM (servers, consumers) or until nothing is left to run
+// (one-off work), then drains and cleans up once. A second Ctrl+C exits immediately.
+let stopping: Promise<void> | undefined;
+const stop = (reason: string) =>
+  (stopping ??= app.stop().then(
+    () => app.logger.log('info', 'Dokebi application stopped', { reason }),
+    () => {
+      process.exitCode = 1;
+      app.logger.log('error', 'Dokebi application did not stop cleanly', { reason });
+    },
+  ));
+process.once('SIGINT', () => void stop('SIGINT'));
+process.once('SIGTERM', () => void stop('SIGTERM'));
+process.once('beforeExit', () => void stop('idle'));
+`;
+/**
+ * The entry point of D-0151 before D-0154 (no configFile: the app could not read dokebi.yaml
+ * again). `add` of a logger plugin rewrites an unchanged copy to MAIN_SOURCE; migrate still
+ * recognizes it.
+ */
+export const MAIN_SOURCE_V3 = `import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Application, loadConfig } from '@dokebi/core';
+import { createLogger, registerPlugins } from './dokebi.generated.ts';
+
+const configPath = resolve(process.env.DOKEBI_CONFIG ?? fileURLToPath(new URL('../dokebi.yaml', import.meta.url)));
+process.env.DOKEBI_CONFIG = configPath;
+const document = await loadConfig(configPath);
+// The app logger: @dokebi/logger (options.logging targets) when installed, else core's console logger.
+const app = new Application({ config: document.options, logger: createLogger(document.options) });
+await registerPlugins(app);
 await app.start();
 app.logger.log('info', 'Dokebi application started');
 
@@ -140,6 +229,99 @@ process.once('SIGINT', () => void stop('SIGINT'));
 process.once('SIGTERM', () => void stop('SIGTERM'));
 process.once('beforeExit', () => void stop('idle'));
 `;
+/**
+ * The entry point of D-0154 before the IPC start message (AI-M43): `start` knew the app was up
+ * only from the info line, which logging.level warn hides. migrate still recognizes it.
+ */
+export const MAIN_SOURCE_V4 = `import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Application, loadConfig } from '@dokebi/core';
+import { createLogger, registerPlugins } from './dokebi.generated.ts';
+
+const configPath = resolve(process.env.DOKEBI_CONFIG ?? fileURLToPath(new URL('../dokebi.yaml', import.meta.url)));
+process.env.DOKEBI_CONFIG = configPath;
+const document = await loadConfig(configPath);
+// The app logger: @dokebi/logger (options.logging targets) when installed, else core's console logger.
+// configFile: the app reads dokebi.yaml again when it changes (options marked reloadable apply live).
+const app = new Application({
+  config: document.options,
+  configFile: configPath,
+  logger: createLogger(document.options),
+});
+await registerPlugins(app);
+await app.start();
+app.logger.log('info', 'Dokebi application started');
+
+// The app runs until SIGINT/SIGTERM (servers, consumers) or until nothing is left to run
+// (one-off work), then drains and cleans up once. A second Ctrl+C exits immediately.
+let stopping: Promise<void> | undefined;
+const stop = (reason: string) =>
+  (stopping ??= app.stop().then(
+    () => app.logger.log('info', 'Dokebi application stopped', { reason }),
+    () => {
+      process.exitCode = 1;
+      app.logger.log('error', 'Dokebi application did not stop cleanly', { reason });
+    },
+  ));
+process.once('SIGINT', () => void stop('SIGINT'));
+process.once('SIGTERM', () => void stop('SIGTERM'));
+process.once('beforeExit', () => void stop('idle'));
+`;
+/**
+ * The entry point of the IPC start message before an empty DOKEBI_CONFIG counted as unset
+ * (R4CB-1: `DOKEBI_CONFIG= node src/main.ts` resolved '' to the working folder and failed with
+ * CONFIG_READ_FAILED, while every CLI command reads dokebi.yaml then, D-0154 D4). migrate still
+ * recognizes it; doctor names a main.ts with this line (TEMPLATE_FIX_MISSING, template-fixes.ts).
+ */
+export const MAIN_SOURCE_V5 = `import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Application, loadConfig } from '@dokebi/core';
+import { createLogger, registerPlugins } from './dokebi.generated.ts';
+
+const configPath = resolve(process.env.DOKEBI_CONFIG ?? fileURLToPath(new URL('../dokebi.yaml', import.meta.url)));
+process.env.DOKEBI_CONFIG = configPath;
+const document = await loadConfig(configPath);
+// The app logger: @dokebi/logger (options.logging targets) when installed, else core's console logger.
+// configFile: the app reads dokebi.yaml again when it changes (options marked reloadable apply live).
+const app = new Application({
+  config: document.options,
+  configFile: configPath,
+  logger: createLogger(document.options),
+});
+await registerPlugins(app);
+await app.start();
+app.logger.log('info', 'Dokebi application started');
+// dokebi start and verify learn that the app is up from this message as well, so a
+// logging.level above info (which hides the line above) does not look like a failed start.
+if (process.send) {
+  process.send({ dokebi: 'started' });
+  process.channel?.unref();
+}
+
+// The app runs until SIGINT/SIGTERM (servers, consumers) or until nothing is left to run
+// (one-off work), then drains and cleans up once. A second Ctrl+C exits immediately.
+let stopping: Promise<void> | undefined;
+const stop = (reason: string) =>
+  (stopping ??= app.stop().then(
+    () => app.logger.log('info', 'Dokebi application stopped', { reason }),
+    () => {
+      process.exitCode = 1;
+      app.logger.log('error', 'Dokebi application did not stop cleanly', { reason });
+    },
+  ));
+process.once('SIGINT', () => void stop('SIGINT'));
+process.once('SIGTERM', () => void stop('SIGTERM'));
+process.once('beforeExit', () => void stop('idle'));
+`;
+/**
+ * src/main.ts of a new project. D-0151: the logger comes from the generated registration
+ * (@dokebi/logger when installed, else undefined: core's console logger), so it is in place
+ * before the first plugin logs. D-0154: configFile lets the app read dokebi.yaml again while it
+ * runs (a change of the file, SIGHUP, npx dokebi reload); options marked reloadable apply
+ * without a restart. An empty DOKEBI_CONFIG means dokebi.yaml, as for every CLI command (D-0154
+ * D4; `??` took '' for a path and read the working folder).
+ */
+export const MAIN_SOURCE = MAIN_SOURCE_V5.replace('resolve(process.env.DOKEBI_CONFIG ?? fileURLToPath(', 'resolve(process.env.DOKEBI_CONFIG || fileURLToPath(');
 /**
  * tsconfig.json written by init. `node src/main.ts` strips types without compiling, so the
  * editor and `tsc` should reject syntax Node cannot run (erasableSyntaxOnly) and need explicit
@@ -158,6 +340,14 @@ export const PROJECT_DEV_DEPENDENCIES = {
 };
 /** `npm run typecheck`: the checks of the generated tsconfig.json (it already sets noEmit). */
 export const TYPECHECK_SCRIPT = 'tsc -p tsconfig.json --noEmit';
+/**
+ * `npm test` (D-0077 H): node:test over the project's `*.test.ts` files under tests (Node strips
+ * their types; none exist at first, which passes). `dokebi verify` runs it with a result per
+ * test. The pattern is quoted so node expands it the same way on every shell. It covers the
+ * maintained test folders tests/unit and tests/integration; helpers in tests/support are not
+ * named *.test.ts (D-0092 §3, the "Files and folders" rule of capability-guide.ts).
+ */
+export const TEST_SCRIPT = 'node --test "tests/**/*.test.ts"';
 export const TSCONFIG_SOURCE = `${JSON.stringify({
     compilerOptions: {
         target: 'ES2023',
@@ -174,5 +364,5 @@ export const TSCONFIG_SOURCE = `${JSON.stringify({
         // TypeScript 6+ no longer loads every @types package; init installs @types/node.
         types: ['node'],
     },
-    include: ['src/**/*.ts'],
+    include: ['src/**/*.ts', 'tests/**/*.ts'],
 }, null, 2)}\n`;

package/dist/guide.d.ts

@@ -23,7 +23,7 @@ export interface Guide {
     readonly text: string;
 }
 /** The short pointer printed at the top of `dokebi --help`. */
-export declare const HELP_POINTER = "AI and automation: read `dokebi guide` (--json) first. Ask the user every choice and end your turn until they answer; finish with `dokebi verify` and say done only when it is ok. Every command takes --json and changing commands take --dry-run. Outside a project run npx -y @dokebi/cli (inside, npx dokebi uses the project copy); the npm package named \"dokebi\" is not this CLI\n";
+export declare const HELP_POINTER: string;
 export declare const GUIDE_STEPS: readonly GuideStep[];
 export declare const GUIDE_RULES: readonly string[];
 export declare function buildGuide(catalog: Catalog): Guide;

package/dist/guide.js

@@ -1,7 +1,13 @@
-import { COMMANDS } from './commands.js';
+import { ANSWER_SOURCES, ASK_AND_WAIT, BROWSER_APPS, INTEGRATION_RULES, } from './capability-guide.js';
+import { COMMANDS, dryRunList } from './commands.js';
 import { CLI_VERSION } from './output.js';
 /** The short pointer printed at the top of `dokebi --help`. */
-export const HELP_POINTER = 'AI and automation: read `dokebi guide` (--json) first. Ask the user every choice and end your turn until they answer; finish with `dokebi verify` and say done only when it is ok. Every command takes --json and changing commands take --dry-run. Outside a project run npx -y @dokebi/cli (inside, npx dokebi uses the project copy); the npm package named "dokebi" is not this CLI\n';
+export const HELP_POINTER = `AI and automation: read \`dokebi guide\` (--json) first. Use choices the user already supplied; ask only unresolved recipe choices and wait for those answers; finish with \`dokebi verify\` and say done only when it is ok. Use --json except for interactive dev, logs and start --foreground; only these take --dry-run: ${dryRunList()}. Outside a project run npx -y @dokebi/cli (inside, npx dokebi uses the project copy); the npm package named "dokebi" is not this CLI\n`;
+/**
+ * The relay rule of verify's tellUser lines, in the verify step and the rules alike (one text:
+ * the two had been written apart and already said it in different words, D-0110 §5).
+ */
+const RELAY_TELL_USER = "Your final message to the user must include verify's tellUser lines: copy these lines unchanged (do not translate, reword or summarize them); you may add your own summary after them";
 export const GUIDE_STEPS = [
     {
         command: 'npx -y @dokebi/cli init <folder> && cd <folder>',
@@ -9,47 +15,58 @@ export const GUIDE_STEPS = [
     },
     {
         command: 'npx dokebi recipe list --json',
-        why: 'Pick the recipe that fits the request (a blog → blog, a JSON API → api). If none fits, use plugins search',
+        why: `Pick the recipe that fits the request: a service people use in a browser → site (or blog for posts), an API the user asked for, whose clients are other programs → api (no browser screens). ${BROWSER_APPS} If none fits, use plugins search`,
     },
     {
         command: 'npx dokebi recipe <name> --json',
-        why: 'Without answers it installs nothing and returns questions[] (waitForUser: true). Show the user every question with its options, pros/cons and default, then **end your turn**. Ask these questions and end your turn; do not run recipe/add/config until the user answers. Only use --defaults if the user said to decide.',
+        why: `Without answers it installs nothing and returns questions[] (waitForUser: true). Pass the choices the user already gave as flags; show the user every question still in missing[] with its options, pros/cons and default, then **end your turn**. ${ASK_AND_WAIT}`,
     },
     {
-        command: 'npx dokebi recipe <name> --view <v> --db <d> --dev-infra <i> --admin <a> --answers-from user --dry-run --json',
+        command: 'npx dokebi recipe <name> --view <v> --db <d> --dev-infra <i> --admin <a> --mail <m> --answers-from user --dry-run --json',
         why: 'Only after the user answered: see the plan (plan.steps) and the preflight for those answers. Ask the user about a preflight error (never switch the database or a port behind their back)',
     },
     {
-        command: 'npx dokebi recipe <name> --view <v> --db <d> --dev-infra <i> --admin <a> --answers-from user --json',
-        why: 'Apply the plan. Applying needs the source of the answers: --answers-from user (the user answered) or --defaults (the user said to decide); without one it is ANSWERS_SOURCE_REQUIRED. Tell the user the report of the result. Each step runs an existing transactional command; a failure stops with completedSteps, and the same command resumes',
+        command: 'npx dokebi recipe <name> --view <v> --db <d> --dev-infra <i> --admin <a> --mail <m> --answers-from user --json',
+        why: `Apply the plan. Applying needs the source of the answers: --answers-from user (the user answered) or --defaults (the user said to decide); without one it is ANSWERS_SOURCE_REQUIRED. ${ANSWER_SOURCES} Tell the user the report of the result. Each step runs an existing transactional command; a failure stops with completedSteps, and the same command resumes`,
     },
     {
         command: 'npx dokebi plugins doc <id> --json',
         why: 'Read the AI.md of the installed version of every installed plugin (AGENTS.md lists the paths under "Installed packages")',
     },
+    {
+        command: 'npx dokebi plugins search process.cluster --json',
+        why: 'Before implementing the runtime, confirm whether the user wants a single application process or a process cluster, and the worker count. No recipe configures this. App processes (@dokebi/cluster), durable jobs (@dokebi/job) and CPU threads (@dokebi/worker) are different choices. If cluster is selected, install the library using its catalog install command and read node_modules/@dokebi/cluster/AI.md; the blog recipe has no --workers flag. Follow its complete parent/worker example and shared-state prerequisites',
+    },
     {
         command: '(write the app code) src/apps/<app>, src/shared/modules/<module>',
         why: "Follow the nextSteps of the recipe result: attach the module to the app and write the features. Build what Dokebi does not have (absent) in app code, as its instead says. Errors and forms (D-0074): refuse input with throw validationError({ field: 'message' }) from @dokebi/web (422 with errors by field, like a refused schema); Inertia form submits pass only (the props they change) and show form.errors; EJS forms show data.errors.<field> and data.old.<field> (with @dokebi/session a refused form comes back to its page, 303); EJS apps may add views/<template>/errors/404.ejs, errors/422.ejs and errors/error.ejs",
     },
     {
         command: 'npx dokebi check --json',
-        why: 'Convention check while you write code (empty catch, promise without await, syntax Node cannot strip, private @dokebi paths, missing packages, edited generated files, secrets that would be committed). Every problem has file, line and fix',
+        why: 'Convention check while you write code (empty catch, promise without await, syntax Node cannot strip, private @dokebi paths, missing packages, edited generated files, secrets that would be committed; with @dokebi/auth a password compared or hashed by hand, with @dokebi/csrf a post form without the token or a csrf: false route that verifies nothing). Every problem has file, line and fix',
     },
     {
         command: 'npx dokebi verify --json',
-        why: "doctor, check, typecheck, build, start, HTTP checks and stop. Tell the user it is done only when ok: true. Your final message to the user must include verify's tellUser lines (the recipe's choices with who made them, defaults with their reasons, and notices such as no CSRF protection)",
+        why: `doctor, check, typecheck, build, the project's tests (npm test; a result per node:test test, with the [ID] of each name), start, HTTP checks and stop. Tell the user it is done only when ok: true. ${RELAY_TELL_USER}. Those lines are the recipe's choices with who made them, defaults with their reasons, and notices such as how the forms send the CSRF token and where the admin login and its first password are; a notice that states a fact of the project says what verify found when it ran (D-0137)`,
     },
 ];
 export const GUIDE_RULES = [
-    'Never decide choices such as the view, the database, the development database or an admin area yourself. Ask the user the questions[] of the recipe and end your turn. Run no recipe, add or config before they answer (never "I will go on with the defaults while you choose")',
-    'Use --defaults only when the user left the choice to you ("you decide"), and report the chosen values with their defaultReason afterwards. When the user answered, use --answers-from user',
-    'Never invent a plugin, a flag or an API for something Dokebi does not have (absent: auth, csrf, upload, mail, markdown, sqlite, React and more)',
-    'Never install or run a package outside @dokebi/ (THIRD_PARTY_PACKAGE) without the permission of the user',
-    'Never pass a secret with --set or config set (the shell history keeps it). Write it into dokebi.yaml or use the value dev-infra generated',
-    'Preview every changing command with --dry-run --json first. Never blindly re-run a failure, and never delete the lock or a backup',
-    'Only src/dokebi.generated.ts, .dokebi/state.json and the part of AGENTS.md between the dokebi:installed markers are rewritten by the CLI: never edit them by hand. Every other file the CLI or a plugin created (the shared layout src/shared/views/layouts/main.ejs, entry files, app and module files) is user code: edit it where it is (do not move it)',
-    "Never say done before verify returns ok: true. Your final message to the user must include verify's tellUser lines",
-    'Errors (D-0074): Inertia, fetch/XHR, Bearer and JSON-body requests get JSON errors and only plain browser pages get HTML, so read errors from the JSON. Refuse input with validationError({ field: message }) (422 VALIDATION_FAILED, fields and errors), never a hand-made 422; give every Inertia form submit an only option; an EJS write form shows data.errors.<field> and data.old.<field> (add @dokebi/session so a refused form comes back to its page)',
+    'Runtime layout: src/main.ts owns process signals; a cluster worker factory belongs in src/infra/runtime/application.ts. Store the selected process count in dokebi.yaml options.application-runtime.workers. Use ClusterRunner even for one worker once the project has chosen cluster mode. Resolve DOKEBI_CONFIG once to an absolute YAML path in the parent and inherit that same path in workers; never send credentials through IPC or introduce .env. Configure shared session/auth/rate-limit stores and scheduler/WebSocket coordination before claiming multiple workers work. Verify the effective worker count, HTTP readiness and graceful group-signal shutdown, not just typecheck',
+    'Use choices already supplied by the user. For unresolved choices such as the view, database, development infrastructure, mail or admin area, ask the applicable questions[] and wait. Run no dependent recipe, add or config before those answers (never "I will go on with the defaults while you choose")',
+    `Use --defaults or --ai-chose only when the user left the choice to you ("you decide"), and report the chosen values with their reasons afterwards. When the user answered, use --answers-from user. ${ANSWER_SOURCES}`,
+    'Mail (D-0078): ask --mail none|mailpit|smtp|ses. Mailpit starts local mail and a durable queue; SMTP/SES require existing settings in dokebi.yaml. Inspect templates with describe and render preview.json with npx dokebi mail preview <name> --json. In requests use mail.queue, with tokens and links in sealed, never data',
+    'Never invent a plugin, a flag or an API. Use plugins search and the catalog-derived absent list below; read the installed contract for each supported capability and its limits',
+    'Never install or run a package outside @dokebi/ (THIRD_PARTY_PACKAGE) without the permission of the user; the formatter and the headless browser runner the rules ask for are permitted devDependencies, named in the final report. The tools a dokebi command installs as part of its scaffold (app add --inertia: vite, @vitejs/plugin-vue, vue, @inertiajs/vue3, vue-tsc, @typescript/typescript6) belong to the framework and need no permission',
+    "Secrets live in dokebi.yaml (0600, kept out of Git), never in dokebi.example.yaml: add writes the ones a plugin declares (generatedSecrets names them), npx dokebi config secret <id>.<path> generates one later, and a value the user supplies (such as a database URL with a password) is written with your file editor, npx dokebi config set or by the user. An environment variable is only an optional production override where a plugin documents one. dokebi.yaml is the developer's file (D-0165): read and edit it directly, secrets included; npx dokebi config show [<id>[.<path>]] gives it with schema defaults (secrets as <secret: set>, for output you share); to change a secret use npx dokebi config secret <id>.<path> --rotate. What stays out of Git: dokebi.yaml itself and secrets in dokebi.example.yaml",
+    'To see what an app has (routes with their login rule, pages, jobs, schedules, error codes, option keys and environment variable names; never a value), run npx dokebi describe --json: it loads the app without serving or connecting (D-0077). Before you write a migration run npx dokebi describe --with-db --json to see the current tables; npx dokebi describe --openapi gives an OpenAPI 3.1 document per app; npx dokebi drift --expected <file> --json compares the databases (tables, columns, column comments) with a file of the describe shape, such as a design',
+    'Preview commands that support --dry-run with --dry-run --json first; consult command help for the supported flags. Never blindly re-run a failure, and never delete the lock or a backup',
+    'CLI-owned src/dokebi.generated.ts, .dokebi/state.json, .dokebi/recipe.json and the installed/capabilities marker blocks of AGENTS.md must not be edited by hand. Commands also update YAML, package metadata and installation records transactionally; consult command help and ownership metadata before changing a file. The dokebi:project block of AGENTS.md holds the rules of this project: read and follow them; the CLI never changes that block. Scaffold source files declared owner: user (the shared layout src/shared/views/layouts/main.ejs, entry files, app and module files) are user code: maintain it in place unless the user requests restructuring; then update its imports, resources and registration together instead of keeping a duplicate implementation',
+    `Never say done before verify returns ok: true. ${RELAY_TELL_USER}`,
+    "Login and permissions (D-0076): use @dokebi/auth (the blog recipe's --admin login sets it up; ask the user about the admin area first). Implement its extension class on the app's own user table, sign in with request.auth.attempt({ identity, password }), protect routes with config: { auth: 'required' } or { can: '<ability>' }, and show one sentence for every failed login. Never compare or hash passwords yourself: passwords.hash for sign-up and password changes, passwords.verify to check one",
+    "Roles (D-0077): when the design has a role table, return roles: [row.role] from the auth extension's credentials and declare config: { roles: ['admin'] } on the route (any one role passes; with can both must pass) instead of hand-written role ifs in handlers",
+    "CSRF (D-0076): @dokebi/csrf checks every POST, PUT, PATCH and DELETE (the blog recipe installs it). EJS: <%- data.csrf.field %> inside every <form method=\"post\"> (on a sealed domain @dokebi/seal/forms, loaded by <%- data.seal?.head ?? '' %> in the layout <head>, carries it inside the sealed body, and in the x-csrf-token header for a multipart form with a file; sealed forms are form bodies, so dokebi-web.formBody: true; a script submits with form.requestSubmit() or submitSealedForm(form), never form.submit(), which goes out plain and gets 415); Inertia navigation/forms: its HTTP client supplies X-XSRF-TOKEN. Application API calls use sealedFetch, which sends the current XSRF-TOKEN cookie as X-XSRF-TOKEN on every unsafe same-origin request by itself (@dokebi/seal 0.4.2; no adapter of your own). Never turn the check off or exempt a route to make a test pass; only a webhook that verifies its own signature, an @dokebi/auth Bearer-only route (auth: { via: 'token' }) or the token refresh route (it calls tokens.refresh) takes config: { csrf: false }",
+    'Errors (D-0074): Inertia, fetch/XHR, Bearer and JSON-body requests get JSON errors and only plain browser pages get HTML (an EJS form post sealed by @dokebi/seal/forms, request header x-dokebi-form: 1, counts as an HTML form post), so read errors from the JSON. Refuse input with validationError({ field: message }) (422 VALIDATION_FAILED, fields and errors), never a hand-made 422; give every Inertia form submit an only option; an EJS write form shows data.errors.<field> and data.old.<field> (add @dokebi/session so a refused form comes back to its page)',
+    "App error codes (D-0077): declare them once in src/shared/errors.ts with export const errors = defineErrors({ CODE: { status, message, hint? } }) from @dokebi/web and throw errors.CODE({ data }); add a new code to the list first, never invent one inline (new DokebiError('X', …), send({ error: 'X' }): check warns unknown-error-code). A route the user's design names gets config: { id: '<its id>' }",
 ];
 export function buildGuide(catalog) {
     const recipes = catalog.recipes.map((recipe) => ({
@@ -58,15 +75,19 @@ export function buildGuide(catalog) {
         questions: recipe.questions,
     }));
     const absent = catalog.absent.map((entry) => entry.capability);
+    const rules = [
+        ...GUIDE_RULES,
+        ...INTEGRATION_RULES.filter(Boolean).map((rule) => rule.replace(/^- /, '')),
+    ];
     const text = [
         `# Dokebi CLI ${CLI_VERSION} — AI first page`,
         '',
-        'When the user asks in one line, such as "make me a blog with the Dokebi framework (@dokebi/cli)", follow these steps in order.',
+        'When the user asks in one line, such as "make me a web service with the Dokebi framework (@dokebi/cli)", follow these steps in order.',
         '',
         ...GUIDE_STEPS.map((step, index) => `${index + 1}. ${step.command}\n   ${step.why}`),
         '',
         '## Rules',
-        ...GUIDE_RULES.map((rule) => `- ${rule}`),
+        ...rules.map((rule) => `- ${rule}`),
         '',
         '## Recipes',
         ...recipes.map((recipe) => `- ${recipe.name}: ${recipe.summary} (questions: ${recipe.questions.join(', ')})`),
@@ -81,7 +102,7 @@ export function buildGuide(catalog) {
     return {
         cliVersion: CLI_VERSION,
         steps: GUIDE_STEPS,
-        rules: GUIDE_RULES,
+        rules,
         recipes,
         absent,
         commands: COMMANDS.map(({ usage, summary }) => ({ usage, summary })),

package/dist/install-module.d.ts

@@ -1,4 +1,4 @@
-export type InstallPhase = 'planInstall' | 'planUpgrade' | 'check';
+export type InstallPhase = 'planInstall' | 'planUpgrade' | 'check' | 'checkOptions';
 export interface InstallModuleContext {
     readonly options: Readonly<Record<string, unknown>>;
     readonly plugins: readonly {
@@ -10,7 +10,16 @@ export interface InstallModuleContext {
 }
 export declare class InstallPlanningError extends Error {
     readonly code: string;
-    constructor(code: string);
+    /**
+     * What the module said: the message of the error it threw, or the end of its stderr when the
+     * process failed (at most DETAIL_CHARS, `user:password@` and tokens masked). Without it a
+     * failing planInstall was only INSTALL_MODULE_FAILED, and its author could not see why.
+     */
+    readonly detail: string | undefined;
+    constructor(code: string, options?: {
+        readonly cause?: unknown;
+        readonly detail?: string | undefined;
+    });
 }
 /** Returned when the module does not export the requested phase. */
 export declare const PHASE_MISSING: unique symbol;
@@ -28,4 +37,13 @@ export declare function installReadRoots(packageDirectory: string): Promise<stri
  * (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.
  */
+/**
+ * The `--allow-fs-read` flags of the restricted child. Node 24.15's permission model denies a
+ * granted folder when a sibling folder whose name starts with it is granted too (with
+ * `node_modules/@dokebi/web` and `node_modules/@dokebi/websocket`, `realpath` of the first is
+ * ERR_ACCESS_DENIED, so `import('@dokebi/web')` fails: seen with D-0162's options check of
+ * dokebi-websocket). Such a folder is granted as `<folder>*`, which Node handles; it adds only
+ * the siblings that start with the same name.
+ */
+export declare function readPermissions(roots: readonly string[]): string[];
 export declare function runInstallModule(modulePath: string, phase: InstallPhase, context: InstallModuleContext, readRoots?: readonly string[]): Promise<unknown>;

package/dist/install-module.js

@@ -3,19 +3,33 @@ 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, isMissing } from './diagnostics.js';
+import { redactNpmOutput } from './npm-client.js';
 export class InstallPlanningError extends Error {
     code;
-    constructor(code) {
-        super('Plugin installation planning failed (' + code + ').');
+    /**
+     * What the module said: the message of the error it threw, or the end of its stderr when the
+     * process failed (at most DETAIL_CHARS, `user:password@` and tokens masked). Without it a
+     * failing planInstall was only INSTALL_MODULE_FAILED, and its author could not see why.
+     */
+    detail;
+    constructor(code, options) {
+        super(`Plugin installation planning failed (${code}).`, options);
         this.code = code;
         this.name = 'InstallPlanningError';
+        // Masked before it is cut (R4CB-7): a cut inside a password left its first part without the
+        // `@` the mask looks for.
+        const detail = options?.detail ? redactNpmOutput(options.detail).trim() : undefined;
+        this.detail = detail ? detail.slice(0, DETAIL_CHARS) : undefined;
     }
 }
+const DETAIL_CHARS = 2000;
+/** The end of stderr kept for the detail: more than it shows, so the mask sees whole values. */
+const STDERR_CHARS = DETAIL_CHARS * 2;
 /** Returned when the module does not export the requested phase. */
 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 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 failure = (error) => ({ok:false,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',message:String(error && error.stack || error).slice(0, 4000)});\n // D-0162: one child checks the options of every listed plugin (context.entries: {url, options}) with\n // the main entry's createPlugin.checkOptions; each plugin's result or failure is its own.\n if (phase === 'checkOptions') {\n  const results = [];\n  for (const entry of context.entries) {\n   try {\n    const factory = (await import(entry.url)).createPlugin;\n    results.push(typeof factory?.checkOptions === 'function' ? {ok:true,result:factory.checkOptions(entry.options)} : {ok:true,missing:true});\n   } catch (error) { results.push(failure(error)); }\n  }\n  finish({ok:true,plan:results});\n } else {\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 }\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,message:String(error && error.stack || error).slice(0, 4000)});\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;
@@ -108,6 +122,22 @@ export async function installReadRoots(packageDirectory) {
  * (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.
  */
+/**
+ * The `--allow-fs-read` flags of the restricted child. Node 24.15's permission model denies a
+ * granted folder when a sibling folder whose name starts with it is granted too (with
+ * `node_modules/@dokebi/web` and `node_modules/@dokebi/websocket`, `realpath` of the first is
+ * ERR_ACCESS_DENIED, so `import('@dokebi/web')` fails: seen with D-0162's options check of
+ * dokebi-websocket). Such a folder is granted as `<folder>*`, which Node handles; it adds only
+ * the siblings that start with the same name.
+ */
+export function readPermissions(roots) {
+    return roots.map((root) => {
+        const parent = dirname(root);
+        const name = basename(root);
+        const shadowed = roots.some((other) => other !== root && dirname(other) === parent && basename(other).startsWith(name));
+        return `--allow-fs-read=${root}${shadowed ? '*' : ''}`;
+    });
+}
 export async function runInstallModule(modulePath, phase, context, readRoots = [dirname(modulePath)]) {
     const input = JSON.stringify(context);
     if (Buffer.byteLength(input) > MAX_BYTES)
@@ -124,13 +154,13 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
         roots = [...new Set(resolved.flat())];
         moduleUrl = pathToFileURL(await realpath(modulePath)).href;
     }
-    catch {
-        throw new InstallPlanningError('INSTALL_MODULE_MISSING');
+    catch (cause) {
+        throw new InstallPlanningError('INSTALL_MODULE_MISSING', { cause });
     }
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, [
             '--permission',
-            ...roots.map((root) => `--allow-fs-read=${root}`),
+            ...readPermissions(roots),
             '--input-type=module',
             '--eval',
             RUNNER,
@@ -138,6 +168,7 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
             phase,
         ], { stdio: ['pipe', 'pipe', 'pipe'], env: {}, cwd: roots[0] });
         const chunks = [];
+        let stderr = '';
         let size = 0;
         let failure;
         const stop = (code) => {
@@ -156,6 +187,8 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
             size += chunk.length;
             if (size > MAX_BYTES)
                 stop('INSTALL_OUTPUT_LIMIT');
+            else
+                stderr = (stderr + chunk.toString('utf8')).slice(-STDERR_CHARS);
         });
         // Both become the typed InstallPlanningError the caller receives; debug keeps the cause.
         child.on('error', (error) => {
@@ -176,7 +209,9 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
                 return;
             }
             if (code !== 0) {
-                reject(new InstallPlanningError('INSTALL_PROCESS_FAILED'));
+                // The end of stderr, masked while whole (R4CB-7).
+                const tail = redactNpmOutput(stderr).trim().slice(-DETAIL_CHARS);
+                reject(new InstallPlanningError('INSTALL_PROCESS_FAILED', { detail: tail }));
                 return;
             }
             try {
@@ -195,7 +230,9 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
                 if (envelope.ok === false &&
                     typeof envelope.code === 'string' &&
                     /^[A-Z][A-Z0-9_]{0,63}$/.test(envelope.code)) {
-                    reject(new InstallPlanningError(envelope.code));
+                    reject(new InstallPlanningError(envelope.code, {
+                        detail: typeof envelope.message === 'string' ? envelope.message : undefined,
+                    }));
                     return;
                 }
             }