@dokebi/cli 0.4.2 → 0.4.27

package/dist/bin.js

@@ -1,18 +1,94 @@
 #!/usr/bin/env node
+// dokebi-check: allow console-output the CLI prints its human and JSON output on stdout and stderr (D-0151)
+// The modules of a command load when that command runs (`await import(…)` in its branch): the
+// project, server, recipe, check and verify modules pull in yaml, semver and @dokebi/core, which
+// doubled the start of `--help`, `--version` and `guide` (about 80 ms against 35 ms) although
+// they need none of it. Only the light modules every command uses are imported here.
 import { writeBanner } from './banner.js';
 import { loadCatalog } from './catalog.js';
-import { check, checkText } from './check/index.js';
-import { COMMAND_DETAILS, COMMANDS } from './commands.js';
-import { parseSetOption } from './config-edit.js';
+import { COMMAND_DETAILS, COMMANDS, commandHasFlag, DRY_RUN_COMMANDS, dryRunList, } from './commands.js';
 import { CliError } from './errors.js';
 import { buildGuide, HELP_POINTER } from './guide.js';
 import { CLI_VERSION, envelope, failure } from './output.js';
-import { pluginsDoc, pluginsInfo, pluginsList, pluginsSearch } from './plugins-command.js';
-import { Project } from './project.js';
-import { ProjectInspector } from './project-inspector.js';
-import { listRecipes, runRecipe } from './recipe.js';
-import * as server from './server.js';
-import { verify } from './verify.js';
+/** A Project, with its module (and what it imports) loaded on first use. */
+async function newProject() {
+    const { Project } = await import('./project.js');
+    return new Project();
+}
+/** `--set` and config paths are parsed by config-edit.js, which loads yaml. */
+/** Bytes of a secret `config secret --stdin` reads at most. */
+const MAX_SECRET_INPUT = 65_536;
+/**
+ * The secret of `config secret --stdin` (D-0151 follow-up): piped stdin up to its end, or on a
+ * terminal one line typed without echo. One line; the final line break is not part of it. The
+ * value is never printed or logged.
+ */
+async function readSecretInput() {
+    const stdin = process.stdin;
+    const tooLarge = () => new CliError('INVALID_SET', 'The secret on stdin is larger than 64 KiB', {
+        phase: 'arguments',
+    });
+    let text = '';
+    if (stdin.isTTY) {
+        process.stderr.write('Secret (input hidden, Enter to finish): ');
+        text = await new Promise((resolve, reject) => {
+            let typed = '';
+            const finish = (error) => {
+                stdin.setRawMode(false);
+                stdin.off('data', onData);
+                stdin.pause();
+                process.stderr.write('\n');
+                if (error)
+                    reject(error);
+                else
+                    resolve(typed);
+            };
+            const onData = (chunk) => {
+                for (const char of chunk) {
+                    if (char === '\r' || char === '\n' || char === '\u0004') {
+                        finish();
+                        return;
+                    }
+                    if (char === '\u0003') {
+                        finish(new CliError('USAGE', 'config secret --stdin was interrupted'));
+                        return;
+                    }
+                    typed = char === '\u007f' || char === '\b' ? typed.slice(0, -1) : typed + char;
+                    if (Buffer.byteLength(typed) > MAX_SECRET_INPUT) {
+                        finish(tooLarge());
+                        return;
+                    }
+                }
+            };
+            stdin.setRawMode(true);
+            stdin.setEncoding('utf8');
+            stdin.on('data', onData);
+            stdin.resume();
+        });
+    }
+    else {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of stdin) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            size += buffer.length;
+            if (size > MAX_SECRET_INPUT)
+                throw tooLarge();
+            chunks.push(buffer);
+        }
+        text = Buffer.concat(chunks).toString('utf8');
+    }
+    const value = text.replace(/\r?\n$/, '');
+    if (!value || /[\r\n]/.test(value))
+        throw new CliError('INVALID_SET', 'config secret --stdin takes one line on stdin (the secret); it got none or several', {
+            phase: 'arguments',
+            details: { fix: 'pipe the value from a file or a password manager, or type it when asked' },
+        });
+    return value;
+}
+async function setParser() {
+    return (await import('./config-edit.js')).parseSetOption;
+}
 /** The usage lines only (their format is stable; tools parse them). */
 const USAGE_LINES = COMMANDS.map((item) => item.usage).join('\n') + '\n';
 const HELP = `${HELP_POINTER}\n${COMMANDS.map((item) => `${item.usage}\n    ${item.summary}`).join('\n')}\n\ndokebi <command> --help shows one command; dokebi --version prints the CLI version.\n`;
@@ -102,7 +178,7 @@ function flags(input, allowed) {
             const value = input[++index];
             if (value === undefined || value.startsWith('--'))
                 throw new CliError('USAGE', USAGE_LINES);
-            sets.push(parseSetOption(value));
+            sets.push(allowed.set(value));
         }
         else if (arg === '--to' && allowed.to && to === undefined) {
             const value = input[++index];
@@ -116,6 +192,12 @@ function flags(input, allowed) {
                 throw new CliError('USAGE', USAGE_LINES);
             add.adapter = value;
         }
+        else if (arg === '--startup' && allowed.add && add.startup === undefined) {
+            const value = input[++index];
+            if (value !== 'required' && value !== 'optional')
+                throw new CliError('USAGE', USAGE_LINES);
+            add.startup = value;
+        }
         else if (arg === '--no-first-app' && allowed.add && add.firstApp === undefined)
             add.firstApp = false;
         else
@@ -156,7 +238,30 @@ async function main() {
             : value + (value.endsWith('\n') ? '' : '\n'));
         return;
     }
+    // AI-M04 F8: --dry-run on a command without it names the commands that take it.
+    if (args.includes('--dry-run')) {
+        const known = (name) => COMMANDS.some((item) => item.name === name);
+        const sub = args[0] && !args[0].startsWith('-') ? `${command} ${args[0]}` : undefined;
+        const name = sub && known(sub) ? sub : known(command) ? command : undefined;
+        if (name && !commandHasFlag(name, '--dry-run'))
+            throw new CliError('USAGE', `dokebi ${name} takes no --dry-run; only these commands do: ${dryRunList()}\n${USAGE_LINES}`, {
+                phase: 'arguments',
+                details: {
+                    command: name,
+                    dryRunCommands: DRY_RUN_COMMANDS,
+                    hint: `dokebi ${name} --help shows its flags`,
+                },
+            });
+    }
     if (command === 'guide') {
+        if (args.includes('--sync')) {
+            if (args.some((arg) => arg !== '--sync' && arg !== '--dry-run'))
+                throw new CliError('USAGE', USAGE_LINES);
+            const dryRun = args.includes('--dry-run');
+            mutationStarted = !dryRun;
+            print(command, await (await newProject()).syncGuide(process.cwd(), dryRun));
+            return;
+        }
         if (args.length)
             throw new CliError('USAGE', USAGE_LINES);
         const guide = buildGuide(await loadCatalog());
@@ -172,22 +277,142 @@ async function main() {
         await recipeCommand(args);
         return;
     }
+    if (command === 'mail') {
+        const subcommand = args.shift();
+        if (subcommand !== 'preview')
+            throw unknownCommand(subcommand ?? '', ['preview'], 'mail ');
+        const name = args.shift();
+        if (!name || name.startsWith('-'))
+            throw new CliError('USAGE', USAGE_LINES);
+        let locale;
+        if (args[0] === '--locale' && args[1] && !args[1].startsWith('-')) {
+            args.shift();
+            locale = args.shift();
+        }
+        if (args.length)
+            throw new CliError('USAGE', USAGE_LINES);
+        const { describeProject } = await import('./describe.js');
+        const described = await describeProject(process.cwd(), {
+            mailPreview: { name, ...(locale ? { locale } : {}) },
+        });
+        const preview = described.app['mail-preview'];
+        if (!preview) {
+            const unavailable = described.unavailable.find((item) => item.plugin === 'cli-mail-preview' || item.plugin === 'dokebi-mail');
+            throw new CliError(unavailable?.code ?? 'MAIL_PREVIEW_FAILED', unavailable?.reason ?? 'Mail preview is unavailable');
+        }
+        print('mail preview', preview, JSON.stringify(preview, null, 2));
+        return;
+    }
+    if (command === 'verify' && args.includes('--remote')) {
+        // D-0184: a deployed site only; nothing local runs.
+        const at = args.indexOf('--remote');
+        const url = args[at + 1];
+        if (url === undefined || url.startsWith('-'))
+            throw new CliError('USAGE', USAGE_LINES);
+        const options = serverFlags(args.filter((_, index) => index !== at && index !== at + 1), { '--timeout-ms': [100, 120_000] }, []);
+        const { remoteVerify, remoteVerifyText } = await import('./remote-verify.js');
+        const timeoutMs = options.numbers.get('--timeout-ms');
+        const result = await remoteVerify(url, {
+            root: process.cwd(),
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        });
+        print('verify', result, remoteVerifyText(result), result.ok);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (command === 'deploy') {
+        await deployCommand(args);
+        return;
+    }
     if (command === 'verify') {
-        const options = serverFlags(args, { '--wait-ms': undefined }, []);
+        const options = serverFlags(args, { '--wait-ms': undefined, '--test-timeout-ms': [1000, 3_600_000] }, []);
         const waitMs = options.numbers.get('--wait-ms');
-        const result = await verify(process.cwd(), waitMs !== undefined ? { waitMs } : {});
+        const testTimeoutMs = options.numbers.get('--test-timeout-ms');
+        const [{ verify }, { testLines }, { TELL_USER_RELAY }] = await Promise.all([
+            import('./verify.js'),
+            import('./verify-tests.js'),
+            import('./recipe-record.js'),
+        ]);
+        const result = await verify(process.cwd(), {
+            ...(waitMs !== undefined ? { waitMs } : {}),
+            ...(testTimeoutMs !== undefined ? { testTimeoutMs } : {}),
+        });
         print(command, result, `${result.checks
-            .map((check) => `${!check.ok ? 'FAIL' : check.skipped ? '-' : 'ok'} ${check.name} (${check.ms} ms)${check.skipped ? `: skipped, ${check.skipped}` : ''}${check.ok ? '' : `: ${check.code ?? ''} ${check.message ?? ''}`}`)
-            .join('\n')}\n${result.ok ? 'verify ok' : 'verify FAILED'}${addressLines(result)}${result.tellUser
-            ? `\nTell the user (your final message must include these lines):\n${result.tellUser.map((line) => `- ${line}`).join('\n')}`
+            .map((check) => `${!check.ok ? 'FAIL' : check.skipped ? '-' : 'ok'} ${check.name} (${check.ms} ms)${check.skipped ? `: skipped, ${check.skipped}` : ''}${check.ok ? '' : `: ${check.code ?? ''} ${check.message ?? ''}`}${check.name === 'test' && result.tests ? testLines(result.tests) : ''}`)
+            .join('\n')}\n${result.ok ? 'verify ok' : 'verify FAILED'}${addressLines(result)}${(result.warnings ?? [])
+            .map((warning) => `\nwarning: ${warning.code} (${warning.path}): ${warning.hint}`)
+            .join('')}${
+        // A taken port is the user's call (AI-M04 F5), as in the recipe preflight.
+        result.question
+            ? `\n${result.waitForUser ? 'ask the user' : 'question'}: ${result.question}\nnext: ${result.next}`
+            : ''}${result.tellUser
+            ? `\nTell the user exactly these lines. ${TELL_USER_RELAY.instruction}\n${result.tellUser.map((line) => `- ${line}`).join('\n')}`
+            : ''}${
+        // D-0105 §4: what the agent writes into its final message itself (not copied).
+        result.finalReport
+            ? `\nYour final message must also contain:\n${result.finalReport.map((line) => `- ${line}`).join('\n')}`
             : ''}`, result.ok);
         if (!result.ok)
             process.exitCode = 1;
         return;
     }
+    if (command === 'describe') {
+        // Read only (D-0077 B): the app's setup in describe mode; nothing listens or connects.
+        // D-0077 C: --openapi [--app <name>] prints OpenAPI 3.1 documents instead.
+        const appAt = args.indexOf('--app');
+        const appName = appAt < 0 ? undefined : args[appAt + 1];
+        if (appAt >= 0 && (appName === undefined || appName.startsWith('-')))
+            throw new CliError('USAGE', `--app needs an app name\n${USAGE_LINES}`);
+        const rest = appAt < 0 ? args : args.filter((_, index) => index !== appAt && index !== appAt + 1);
+        const options = serverFlags(rest, { '--timeout-ms': [1000, 600_000] }, [
+            '--with-db',
+            '--openapi',
+        ]);
+        if (appName !== undefined && !options.switches.has('--openapi'))
+            throw new CliError('USAGE', `--app is for --openapi\n${USAGE_LINES}`);
+        const timeoutMs = options.numbers.get('--timeout-ms');
+        const { describeProject, describeText } = await import('./describe.js');
+        const result = await describeProject(process.cwd(), {
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            // D-0077 F: --with-db also reads the tables (a separate step that connects).
+            withDb: options.switches.has('--with-db'),
+        });
+        if (options.switches.has('--openapi')) {
+            const { openApi, projectVersion } = await import('./openapi.js');
+            const version = projectVersion(process.cwd());
+            const documents = openApi(result, {
+                ...(appName === undefined ? {} : { app: appName }),
+                ...(version === undefined ? {} : { version }),
+            });
+            print(command, documents, JSON.stringify(documents, null, 2));
+            return;
+        }
+        print(command, result, describeText(result));
+        return;
+    }
+    if (command === 'drift') {
+        // D-0120: describe --with-db (it connects) against an expected file of the describe shape.
+        const at = args.indexOf('--expected');
+        const expected = at < 0 ? undefined : args[at + 1];
+        if (expected === undefined || expected.startsWith('-'))
+            throw new CliError('USAGE', `--expected needs a file\n${USAGE_LINES}`);
+        const options = serverFlags(args.filter((_, index) => index !== at && index !== at + 1), { '--timeout-ms': [1000, 600_000] }, []);
+        const timeoutMs = options.numbers.get('--timeout-ms');
+        const { drift, driftText } = await import('./drift.js');
+        const result = await drift(process.cwd(), {
+            expected,
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        });
+        print(command, result, driftText(result), result.ok);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (command === 'check') {
         if (args.length)
             throw new CliError('USAGE', USAGE_LINES);
+        const { check, checkText } = await import('./check/index.js');
         const result = await check(process.cwd());
         print(command, result, checkText(result), result.ok);
         if (!result.ok)
@@ -196,23 +421,140 @@ async function main() {
     }
     if (command === 'config') {
         const action = args.shift();
+        const parseSetOption = await setParser();
+        if (action === 'show') {
+            // Read only: secrets are hidden in every mode (config-show.ts).
+            if (args.length > 1 || args[0]?.startsWith('-'))
+                throw new CliError('USAGE', USAGE_LINES);
+            const target = args[0];
+            const dot = target?.indexOf('.') ?? -1;
+            if (target !== undefined && (dot === 0 || target.includes('=')))
+                throw new CliError('USAGE', USAGE_LINES);
+            const section = target === undefined ? undefined : dot > 0 ? target.slice(0, dot) : target;
+            // The path is checked like a --set path (segments, no prototype keys).
+            const path = target && dot > 0 ? parseSetOption(`${target.slice(dot + 1)}=0`).path : [];
+            const { configShow, configShowText } = await import('./config-show.js');
+            const result = await configShow(process.cwd(), section === undefined ? undefined : { section, path });
+            print('config show', result, configShowText(result));
+            return;
+        }
+        if (action === 'diff') {
+            // Read only (AI-M45): option paths of dokebi.yaml against dokebi.example.yaml, no values.
+            // --write (AI-M46) copies the paths only in dokebi.yaml into the sample, without secrets.
+            let write = false;
+            let dryRun = false;
+            let prune = false;
+            let values = false;
+            const rest = [];
+            for (const arg of args) {
+                if (arg === '--write' && !write)
+                    write = true;
+                else if (arg === '--dry-run' && !dryRun)
+                    dryRun = true;
+                else if (arg === '--prune' && !prune)
+                    prune = true;
+                else if (arg === '--values' && !values)
+                    values = true;
+                else
+                    rest.push(arg);
+            }
+            if ((dryRun || prune || values) && !write)
+                throw new CliError('USAGE', USAGE_LINES);
+            if (rest.length > 1 || rest[0]?.startsWith('-') || rest[0]?.includes('.'))
+                throw new CliError('USAGE', USAGE_LINES);
+            const { configDiff, configDiffText } = await import('./config-diff.js');
+            if (write) {
+                mutationStarted = true;
+                const result = await (await newProject()).configSample(process.cwd(), rest[0], dryRun, prune, values);
+                const listed = (label, paths) => paths.length
+                    ? `${label} [${paths.length}]:\n${paths.map((path) => `  ${path}`).join('\n')}\n`
+                    : '';
+                print('config diff', result, `${listed('copied into dokebi.example.yaml', result.written) || 'nothing to copy into dokebi.example.yaml\n'}${values ? listed('values written into dokebi.example.yaml', result.valuesWritten ?? []) || 'no value to write into dokebi.example.yaml\n' : ''}${listed('removed from dokebi.example.yaml', result.pruned)}${configDiffText(result.diff)}`);
+                return;
+            }
+            const result = await configDiff(process.cwd(), rest[0]);
+            print('config diff', result, configDiffText(result));
+            return;
+        }
+        if (action === 'init') {
+            // D-0163: a fresh copy of the project (a clone) has no dokebi.yaml; written from the sample.
+            const dryRun = args.includes('--dry-run');
+            if (args.some((arg) => arg !== '--dry-run'))
+                throw new CliError('USAGE', USAGE_LINES);
+            mutationStarted = true;
+            const result = await (await newProject()).configInit(process.cwd(), dryRun);
+            print('config init', result);
+            return;
+        }
+        if (action === 'secrets') {
+            // D-0184: read only; names, never values.
+            if (args.length)
+                throw new CliError('USAGE', USAGE_LINES);
+            const { configSecrets, configSecretsText } = await import('./config-secrets.js');
+            const result = await configSecrets(process.cwd());
+            const ok = result.missing.length === 0;
+            print('config secrets', result, configSecretsText(result), ok);
+            if (!ok)
+                process.exitCode = 1;
+            return;
+        }
         if (action === 'secret') {
             const dryRun = args.includes('--dry-run');
-            const rest = args.filter((arg) => arg !== '--dry-run');
+            const rotate = args.includes('--rotate');
+            const fromStdin = args.includes('--stdin');
+            const rest = args.filter((arg) => arg !== '--dry-run' && arg !== '--rotate' && arg !== '--stdin');
             const target = rest[0];
             const dot = target?.indexOf('.') ?? -1;
             if (rest.length !== 1 || !target || dot <= 0 || target.includes('='))
                 throw new CliError('USAGE', USAGE_LINES);
             // The path is checked like a --set path (segments, no prototype keys).
             const path = parseSetOption(`${target.slice(dot + 1)}=0`).path;
+            // --stdin: a secret someone else issued (a log receiver's token), never on the command line.
+            const value = fromStdin ? await readSecretInput() : undefined;
             mutationStarted = true;
-            const result = await new Project().configSecret(process.cwd(), target.slice(0, dot), path, dryRun);
+            const result = await (await newProject()).configSecret(process.cwd(), target.slice(0, dot), path, dryRun, rotate, value);
             print('config secret', result);
             return;
         }
+        if (action === 'unset') {
+            // D-0153: <plugin-id>.<path>...; never a value (no `=`). A section alone (no path) only
+            // for one no installed plugin reads (an old section left in the files).
+            let dryRun = false;
+            const targets = [];
+            for (const arg of args) {
+                if (arg === '--dry-run' && !dryRun)
+                    dryRun = true;
+                else if (!arg.startsWith('-')) {
+                    if (arg.includes('='))
+                        throw new CliError('USAGE', USAGE_LINES);
+                    const dot = arg.indexOf('.');
+                    if (dot === 0)
+                        throw new CliError('USAGE', USAGE_LINES);
+                    // The path is checked like a --set path (segments, no prototype keys).
+                    if (dot < 0) {
+                        parseSetOption(`${arg}=0`);
+                        targets.push({ plugin: arg, path: [] });
+                    }
+                    else
+                        targets.push({
+                            plugin: arg.slice(0, dot),
+                            path: parseSetOption(`${arg.slice(dot + 1)}=0`).path,
+                        });
+                }
+                else
+                    throw new CliError('USAGE', USAGE_LINES);
+            }
+            if (!targets.length)
+                throw new CliError('USAGE', USAGE_LINES);
+            mutationStarted = true;
+            const result = await (await newProject()).configUnset(process.cwd(), targets, dryRun);
+            printWarnings(result.warnings);
+            print('config unset', result);
+            return;
+        }
         if (action !== 'set') {
             if (action && !action.startsWith('-'))
-                throw unknownCommand(action, ['set', 'secret'], 'config ');
+                throw unknownCommand(action, ['diff', 'init', 'secret', 'secrets', 'set', 'show', 'unset'], 'config ');
             throw new CliError('USAGE', USAGE_LINES);
         }
         let dryRun = false;
@@ -234,17 +576,32 @@ async function main() {
         if (!assignments.length)
             throw new CliError('USAGE', USAGE_LINES);
         mutationStarted = true;
-        const result = await new Project().configSet(process.cwd(), assignments, dryRun);
+        const result = await (await newProject()).configSet(process.cwd(), assignments, dryRun);
         printWarnings(result.warnings);
         print('config set', result);
         return;
     }
     if (command === 'dev-infra') {
+        if (args[0] && !args[0].startsWith('-')) {
+            const action = args[0];
+            args.shift();
+            const files = [];
+            while (args.length) {
+                if (args.shift() !== '--file' || !args[0])
+                    throw new CliError('USAGE', USAGE_LINES);
+                files.push(args[0]);
+                args.shift();
+            }
+            mutationStarted = action !== 'status';
+            const { runDevCompose } = await import('./dev-compose.js');
+            print(command, await runDevCompose(process.cwd(), action, files.length ? files : undefined));
+            return;
+        }
         const dryRun = args.includes('--dry-run');
         const options = serverFlags(args.filter((arg) => arg !== '--dry-run'), { '--db-port': [1, 65535] }, []);
         mutationStarted = true;
         const dbPort = options.numbers.get('--db-port');
-        const result = await new Project().devInfra(process.cwd(), {
+        const result = await (await newProject()).devInfra(process.cwd(), {
             dryRun,
             ...(dbPort !== undefined ? { dbPort } : {}),
         });
@@ -252,12 +609,31 @@ async function main() {
         return;
     }
     if (command === 'inspect' || command === 'doctor') {
-        const verbose = args.length === 1 && args[0] === '--verbose';
-        if (args.length && !verbose)
+        const verbose = args.includes('--verbose');
+        // D-0184: doctor --production adds the checks of a server.
+        const production = command === 'doctor' && args.includes('--production');
+        if (args.some((arg) => arg !== '--verbose' && !(arg === '--production' && production)) ||
+            new Set(args).size !== args.length)
             throw new CliError('USAGE', USAGE_LINES);
+        const { ProjectInspector } = await import('./project-inspector.js');
         const result = await new ProjectInspector().inspect(process.cwd(), {
             runChecks: command === 'doctor',
         });
+        if (production) {
+            const { productionDiagnostics } = await import('./production-doctor.js');
+            result.diagnostics.push(...(await productionDiagnostics(process.cwd())));
+            result.healthy = !result.diagnostics.some((item) => item.severity === 'error');
+            const codes = {};
+            for (const item of result.diagnostics)
+                codes[item.code] = (codes[item.code] ?? 0) + 1;
+            result.summary = {
+                ...result.summary,
+                healthy: result.healthy,
+                errors: result.diagnostics.filter((item) => item.severity === 'error').length,
+                warnings: result.diagnostics.filter((item) => item.severity === 'warning').length,
+                codes,
+            };
+        }
         const ok = command === 'inspect' || result.healthy;
         // --json is always complete (summary first); people get the short form unless --verbose.
         process.stdout.write(machine
@@ -273,7 +649,7 @@ async function main() {
         if (args.length && (args.length !== 1 || args[0] !== '--dry-run'))
             throw new CliError('USAGE', USAGE_LINES);
         mutationStarted = true;
-        const result = await new Project().migrate(process.cwd(), args[0] === '--dry-run');
+        const result = await (await newProject()).migrate(process.cwd(), args[0] === '--dry-run');
         process.stdout.write(JSON.stringify(machine ? envelope(command, result) : result, null, 2) + '\n');
         return;
     }
@@ -281,7 +657,7 @@ async function main() {
         await app(args);
         return;
     }
-    if (['dev', 'start', 'stop', 'status', 'logs'].includes(command)) {
+    if (['dev', 'start', 'stop', 'reload', 'status', 'logs'].includes(command)) {
         await serverCommand(args);
         return;
     }
@@ -289,14 +665,19 @@ async function main() {
         await moduleCommand(args);
         return;
     }
+    if (command === 'settings') {
+        await settingsCommand(args);
+        return;
+    }
     if (!['init', 'add', 'upgrade', 'remove'].includes(command))
         throw unknownCommand(command, [...TOP_LEVEL, '--help', '--version']);
     const target = args.shift();
     if (!target || target.startsWith('-'))
         throw new CliError('USAGE', USAGE_LINES);
-    const project = new Project();
+    const project = await newProject();
     let result;
     if (command === 'init') {
+        let deploy = false;
         let core;
         let dryRun = false;
         for (let index = 0; index < args.length; index++) {
@@ -306,6 +687,8 @@ async function main() {
                 if (!core || core.startsWith('-'))
                     throw new CliError('USAGE', USAGE_LINES);
             }
+            else if (arg === '--deploy' && !deploy)
+                deploy = true;
             else if (arg === '--dry-run' && !dryRun)
                 dryRun = true;
             else
@@ -313,12 +696,18 @@ async function main() {
         }
         writeBanner(process.stderr, machine);
         mutationStarted = !dryRun;
-        result = await project.init(target, core, dryRun);
+        result = await project.init(target, core, dryRun, deploy);
     }
     else if (command === 'add') {
-        const options = flags(args, { set: true, add: true });
+        const options = flags(args, { set: await setParser(), add: true });
         mutationStarted = true;
         result = await project.add(process.cwd(), target, options.dryRun, options.sets, options.add);
+        // D-0098: the first app of the apps host is EJS; its view is recorded (chooser unstated).
+        const firstApp = result.firstApp;
+        if (firstApp) {
+            const { recordAppView } = await import('./view-choice.js');
+            result = await recordAppView(process.cwd(), result, firstApp, 'ejs', {}, options.dryRun);
+        }
     }
     else if (command === 'upgrade') {
         const options = flags(args, { to: true });
@@ -354,15 +743,16 @@ function printWarnings(warnings) {
     if (machine)
         return;
     for (const warning of warnings ?? [])
-        if (warning.code === 'SECRET_ON_COMMAND_LINE')
-            process.stderr.write(`warning: ${warning.path} looks secret; command-line values can remain in shell history\n`);
-        else if (warning.code === 'THIRD_PARTY_PACKAGE')
+        if (warning.code === 'THIRD_PARTY_PACKAGE')
             process.stderr.write(`warning: ${warning.path} is not a @dokebi package; install it only with the user's consent\n`);
+        else if (warning.code === 'DEPRECATED_PLAN_FIELD')
+            process.stderr.write(`warning: ${warning.plugin} uses the deprecated install plan field ${warning.deprecated} (removed in 0.5); upgrade the plugin\n`);
 }
 /** `dokebi plugins list|search|info|doc` (D-0065). */
 async function pluginsCommand(input) {
     const action = input.shift();
     const name = `plugins ${action}`;
+    const { pluginsDoc, pluginsInfo, pluginsList, pluginsSearch } = await import('./plugins-command.js');
     if (action === 'list') {
         let compatible = false;
         let online = false;
@@ -413,6 +803,7 @@ async function recipeCommand(input) {
     const name = input.shift();
     if (!name || name.startsWith('-'))
         throw new CliError('USAGE', USAGE_LINES);
+    const { listRecipes, runRecipe } = await import('./recipe.js');
     if (name === 'list') {
         if (input.length)
             throw new CliError('USAGE', USAGE_LINES);
@@ -428,10 +819,18 @@ async function recipeCommand(input) {
         '--db': 'db',
         '--dev-infra': 'devInfra',
         '--admin': 'admin',
+        '--mail': 'mail',
+        '--apps': 'apps',
+        '--domains': 'domains',
+        '--realms': 'realms',
+        '--worker': 'worker',
     };
     let dir;
     let defaults = false;
     let answersFrom;
+    // D-0095: the given answers the agent chose itself, and its one-line reasons.
+    let aiChose;
+    const aiReasons = new Map();
     let dryRun = false;
     let port;
     let dbPort;
@@ -467,6 +866,21 @@ async function recipeCommand(input) {
                 throw new CliError('USAGE', `--answers-from must be user (the user answered) or defaults (the user said to decide)\n${USAGE_LINES}`);
             answersFrom = value;
         }
+        else if (arg === '--ai-chose' && aiChose === undefined) {
+            const value = input[++index];
+            const ids = value?.split(',').map((item) => item.trim());
+            if (!value || value.startsWith('-') || !ids?.every(Boolean))
+                throw new CliError('USAGE', `--ai-chose takes the comma-separated question ids you chose (for example apps,worker)\n${USAGE_LINES}`);
+            aiChose = [...new Set(ids)];
+        }
+        else if (arg === '--ai-reason') {
+            const value = input[++index];
+            const at = value?.indexOf('=') ?? -1;
+            const id = at > 0 ? value.slice(0, at).trim() : '';
+            if (!value || value.startsWith('--') || !id || aiReasons.has(id))
+                throw new CliError('USAGE', `--ai-reason takes <id>=<why you chose it>, once per question id\n${USAGE_LINES}`);
+            aiReasons.set(id, value.slice(at + 1));
+        }
         else if (arg === '--dry-run' && !dryRun)
             dryRun = true;
         else
@@ -478,11 +892,13 @@ async function recipeCommand(input) {
         answers,
         defaults,
         ...(answersFrom !== undefined ? { answersFrom } : {}),
+        ...(aiChose !== undefined ? { aiChose } : {}),
+        ...(aiReasons.size ? { aiReasons: Object.fromEntries(aiReasons) } : {}),
         dryRun,
         ...(dir !== undefined ? { dir } : {}),
         ...(port !== undefined ? { port } : {}),
         ...(dbPort !== undefined ? { dbPort } : {}),
-    }, new Project());
+    }, await newProject());
     if (result.status === 'needs-answers') {
         // Not an error of the command: the answers come from the user. Nothing was installed.
         process.exitCode = 2;
@@ -517,6 +933,72 @@ async function recipeCommand(input) {
  * Reads `--name <number>` style flags of the server commands; anything else is a usage error.
  * `numbers` maps each flag to its range (default 1 to 3600000).
  */
+/** `dokebi deploy init|proxy` (D-0184). */
+async function deployCommand(input) {
+    const action = input.shift();
+    if (action !== 'init' && action !== 'proxy')
+        throw action && !action.startsWith('-')
+            ? unknownCommand(action, ['init', 'proxy'], 'deploy ')
+            : new CliError('USAGE', USAGE_LINES);
+    const instances = [];
+    const domains = [];
+    let target;
+    let port;
+    let proxy;
+    let dryRun = false;
+    const value = (index) => {
+        const text = input[index];
+        if (text === undefined || text.startsWith('-'))
+            throw new CliError('USAGE', USAGE_LINES);
+        return text;
+    };
+    for (let index = 0; index < input.length; index++) {
+        const arg = input[index];
+        if (arg === '--dry-run' && !dryRun)
+            dryRun = true;
+        else if (arg === '--instance')
+            instances.push(value(++index));
+        else if (action === 'init' && arg === '--target' && target === undefined)
+            target = value(++index);
+        else if (action === 'init' && arg === '--port' && port === undefined) {
+            const number = Number(value(++index));
+            if (!Number.isSafeInteger(number) || number < 1024 || number > 65535)
+                throw new CliError('USAGE', `--port must be an integer from 1024 to 65535\n${USAGE_LINES}`);
+            port = number;
+        }
+        else if (action === 'proxy' && (arg === '--caddy' || arg === '--nginx') && !proxy)
+            proxy = arg === '--caddy' ? 'caddy' : 'nginx';
+        else if (action === 'proxy' && arg === '--domain')
+            domains.push(value(++index));
+        else
+            throw new CliError('USAGE', USAGE_LINES);
+    }
+    if (target !== undefined && target !== 'systemd' && target !== 'compose')
+        throw new CliError('USAGE', `--target is systemd or compose\n${USAGE_LINES}`);
+    const deploy = await import('./deploy.js');
+    mutationStarted = !dryRun;
+    if (action === 'init') {
+        const result = await deploy.deployInit(process.cwd(), {
+            target: (target ?? 'systemd'),
+            instances: instances.length ? instances : ['production'],
+            ...(port === undefined ? {} : { port }),
+            dryRun,
+        });
+        printWarnings(result.warnings);
+        print('deploy init', result);
+        return;
+    }
+    if (!proxy || !domains.length || instances.length > 1)
+        throw new CliError('USAGE', USAGE_LINES);
+    const result = await deploy.deployProxy(process.cwd(), {
+        proxy,
+        domains,
+        instance: instances[0] ?? 'production',
+        dryRun,
+    });
+    printWarnings(result.warnings);
+    print('deploy proxy', result);
+}
 function serverFlags(input, numbers, switches) {
     const result = { numbers: new Map(), switches: new Set() };
     for (let index = 0; index < input.length; index++) {
@@ -536,9 +1018,10 @@ function serverFlags(input, numbers, switches) {
     }
     return result;
 }
-/** `dokebi dev|start|stop|status|logs` (D-0044): the project's process. */
+/** `dokebi dev|start|stop|reload|status|logs` (D-0044, D-0154): the project's process. */
 async function serverCommand(input) {
     const root = process.cwd();
+    const server = await import('./server.js');
     const print = (result, text) => process.stdout.write(machine ? JSON.stringify(envelope(command, result)) + '\n' : text + '\n');
     if (command === 'dev') {
         if (input.length || machine)
@@ -584,6 +1067,23 @@ async function serverCommand(input) {
                 ? `not running (pid ${result.pid} had already exited; removed the pid file)`
                 : 'not running');
     }
+    else if (command === 'reload') {
+        const options = serverFlags(input, { '--timeout-ms': [1000, 3_600_000] }, []);
+        const result = await server.reload(root, options.numbers.get('--timeout-ms'));
+        if (!machine)
+            for (const warning of result.warnings ?? [])
+                process.stderr.write(`warning: ${warning}\n`);
+        // Not running is the answer of status (exit 3), not an error.
+        if (!result.running)
+            process.exitCode = 3;
+        print(result, !result.running
+            ? 'not running (npx dokebi start)'
+            : result.outcome === 'applied'
+                ? `reloaded pid ${result.pid} in ${result.ms} ms${result.revision !== undefined ? ` (revision ${result.revision})` : ''}${result.paths?.length ? `: ${result.paths.join(', ')}` : ''}`
+                : result.outcome === 'unchanged'
+                    ? `pid ${result.pid} read dokebi.yaml again: nothing changed`
+                    : `signalled pid ${result.pid}; its outcome is not in the log yet (npx dokebi logs)`);
+    }
     else if (command === 'status') {
         if (input.length)
             throw new CliError('USAGE', USAGE_LINES);
@@ -617,7 +1117,7 @@ async function serverCommand(input) {
 /** `dokebi app add|remove|list` (D-0030): apps of @dokebi/app and their domains. */
 async function app(input) {
     const action = input.shift();
-    const project = new Project();
+    const project = await newProject();
     let result;
     if (action === 'list') {
         if (input.length)
@@ -631,17 +1131,47 @@ async function app(input) {
         let dryRun = false;
         let inertia = false;
         let ssr = false;
+        let seal = false;
         let template;
+        /** `--view ejs|none` (M50): EJS pages, or no views (a JSON API). */
+        let view;
         const domains = [];
+        // D-0098: who chose the view of this app (the same flags as the recipe's, D-0095).
+        let answersFrom;
+        let aiChose;
+        const aiReasons = new Map();
         for (let index = 0; index < input.length; index++) {
             const arg = input[index];
             const value = input[index + 1];
             if (arg === '--dry-run' && !dryRun)
                 dryRun = true;
+            else if (action === 'add' && arg === '--answers-from' && answersFrom === undefined) {
+                if (value !== 'user' && value !== 'defaults')
+                    throw new CliError('USAGE', `--answers-from must be user (the user chose the view) or defaults (the user left it to you)\n${USAGE_LINES}`);
+                answersFrom = value;
+                index++;
+            }
+            else if (action === 'add' && arg === '--ai-chose' && aiChose === undefined) {
+                const ids = value?.split(',').map((item) => item.trim());
+                if (!value || value.startsWith('-') || !ids?.every(Boolean))
+                    throw new CliError('USAGE', `--ai-chose takes view on app add\n${USAGE_LINES}`);
+                aiChose = [...new Set(ids)];
+                index++;
+            }
+            else if (action === 'add' && arg === '--ai-reason') {
+                const at = value?.indexOf('=') ?? -1;
+                const id = at > 0 ? value.slice(0, at).trim() : '';
+                if (!value || value.startsWith('--') || !id || aiReasons.has(id))
+                    throw new CliError('USAGE', `--ai-reason takes view=<why you chose it>, once\n${USAGE_LINES}`);
+                aiReasons.set(id, value.slice(at + 1));
+                index++;
+            }
             else if (action === 'add' && arg === '--inertia' && !inertia)
                 inertia = true;
             else if (action === 'add' && arg === '--ssr' && !ssr)
                 ssr = true;
+            else if (action === 'add' && arg === '--seal' && !seal)
+                seal = true;
             else if (action === 'add' && arg === '--domain' && value && !value.startsWith('-')) {
                 domains.push(value);
                 index++;
@@ -650,22 +1180,42 @@ async function app(input) {
                 template = value;
                 index++;
             }
+            else if (action === 'add' && arg === '--view' && view === undefined) {
+                if (value !== 'ejs' && value !== 'none')
+                    throw new CliError('USAGE', `--view takes ejs (EJS pages) or none (no views, a JSON API); an Inertia app is --inertia\n${USAGE_LINES}`);
+                view = value;
+                index++;
+            }
             else
                 throw new CliError('USAGE', USAGE_LINES);
         }
         // Server rendering (D-0039) is a choice of an Inertia app.
         if (ssr && !inertia)
             throw new CliError('USAGE', USAGE_LINES);
+        // One flag chooses the view; an app without views has no template.
+        if (view !== undefined && inertia)
+            throw new CliError('USAGE', `--view and --inertia both choose the view: give one\n${USAGE_LINES}`);
+        if (view === 'none' && template !== undefined)
+            throw new CliError('USAGE', `--view none makes an app without views: it takes no --template\n${USAGE_LINES}`);
+        const viewSource = {
+            ...(answersFrom !== undefined ? { answersFrom } : {}),
+            ...(aiChose !== undefined ? { aiChose } : {}),
+            ...(aiReasons.size ? { aiReasons: Object.fromEntries(aiReasons) } : {}),
+        };
+        const views = action === 'add' ? await import('./view-choice.js') : undefined;
+        views?.checkViewSource(viewSource);
         mutationStarted = true;
         result =
-            action === 'add'
-                ? await project.appAdd(process.cwd(), name, {
+            action === 'add' && views
+                ? await views.recordAppView(process.cwd(), await project.appAdd(process.cwd(), name, {
                     domains,
                     dryRun,
                     inertia,
                     ssr,
+                    seal,
                     ...(template ? { template } : {}),
-                })
+                    ...(view ? { view } : {}),
+                }), name, views.appViewValue(inertia, ssr, view === 'none'), viewSource, dryRun)
                 : await project.appRemove(process.cwd(), name, dryRun);
     }
     else if (action === 'link' || action === 'unlink') {
@@ -674,12 +1224,15 @@ async function app(input) {
         if (!first || first.startsWith('-') || !domain || domain.startsWith('-'))
             throw new CliError('USAGE', USAGE_LINES);
         let dryRun = false;
+        let seal = false;
         let template;
         for (let index = 0; index < input.length; index++) {
             const arg = input[index];
             const value = input[index + 1];
             if (arg === '--dry-run' && !dryRun)
                 dryRun = true;
+            else if (action === 'link' && arg === '--seal' && !seal)
+                seal = true;
             else if (action === 'link' && arg === '--template' && value && !template) {
                 template = value;
                 index++;
@@ -692,6 +1245,7 @@ async function app(input) {
             action === 'link'
                 ? await project.appLink(process.cwd(), first, domain, {
                     dryRun,
+                    seal,
                     ...(template ? { template } : {}),
                 })
                 : await project.appUnlink(process.cwd(), domain, dryRun);
@@ -705,7 +1259,7 @@ async function app(input) {
 /** `dokebi module add|remove|list` (D-0032): feature modules in src/shared/modules/<name>. */
 async function moduleCommand(input) {
     const action = input.shift();
-    const project = new Project();
+    const project = await newProject();
     let result;
     if (action === 'list') {
         if (input.length)
@@ -738,6 +1292,50 @@ async function moduleCommand(input) {
         throw new CliError('USAGE', USAGE_LINES);
     process.stdout.write(JSON.stringify(machine ? envelope(`module ${action}`, result) : result, null, 2) + '\n');
 }
+/** `dokebi settings add|sync|remove|list` (D-0155): the settings sections of the application. */
+async function settingsCommand(input) {
+    const action = input.shift();
+    const project = await newProject();
+    let result;
+    if (action === 'list') {
+        if (input.length)
+            throw new CliError('USAGE', USAGE_LINES);
+        result = await project.settingsList(process.cwd());
+    }
+    else if (action === 'sync') {
+        let dryRun = false;
+        for (const arg of input) {
+            if (arg === '--dry-run' && !dryRun)
+                dryRun = true;
+            else
+                throw new CliError('USAGE', USAGE_LINES);
+        }
+        mutationStarted = !dryRun;
+        result = await project.settingsSync(process.cwd(), dryRun);
+    }
+    else if (action === 'add' || action === 'remove') {
+        const section = input.shift();
+        if (!section || section.startsWith('-'))
+            throw new CliError('USAGE', USAGE_LINES);
+        let dryRun = false;
+        for (const arg of input) {
+            if (arg === '--dry-run' && !dryRun)
+                dryRun = true;
+            else
+                throw new CliError('USAGE', USAGE_LINES);
+        }
+        mutationStarted = !dryRun;
+        result =
+            action === 'add'
+                ? await project.settingsAdd(process.cwd(), section, { dryRun })
+                : await project.settingsRemove(process.cwd(), section, dryRun);
+    }
+    else if (action && !action.startsWith('-'))
+        throw unknownCommand(action, ['add', 'sync', 'remove', 'list'], 'settings ');
+    else
+        throw new CliError('USAGE', USAGE_LINES);
+    process.stdout.write(JSON.stringify(machine ? envelope(`settings ${action}`, result) : result, null, 2) + '\n');
+}
 await main().catch((error) => {
     if (machine)
         process.stdout.write(JSON.stringify(failure(command, error, mutationStarted)) + '\n');
@@ -788,6 +1386,9 @@ function nextSteps(error) {
     const hint = error.details.hint;
     if (typeof hint === 'string')
         lines.add(`hint: ${hint}`);
+    const fix = error.details.fix;
+    if (typeof fix === 'string')
+        lines.add(`fix: ${fix}`);
     // A decision that belongs to the user (PREFLIGHT_FAILED with a taken port, AI-M03).
     const { question, next, waitForUser } = error.details;
     if (typeof question === 'string')