@dokebi/cli 0.2.5 → 0.4.0

package/dist/bin.js

@@ -1,11 +1,88 @@
 #!/usr/bin/env node
+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 { 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';
-const HELP = 'dokebi init <directory> [--core <package|local.tgz>] [--json]\ndokebi add <package|local.tgz> [--set <path>=<value>]... [--dry-run] [--json]\ndokebi upgrade <plugin-id> [--to <version|package|local.tgz>] [--dry-run] [--json]\ndokebi remove <plugin-id> [--dry-run] [--json]\ndokebi migrate [--dry-run] [--json]\ndokebi inspect [--json]\ndokebi doctor [--json]\ndokebi app add <name> [--domain <host>]... [--template <name>] [--inertia [--ssr]] [--dry-run] [--json]\ndokebi app remove <name> [--dry-run] [--json]\ndokebi app link <name> <domain> [--template <name>] [--dry-run] [--json]\ndokebi app unlink <domain> [--dry-run] [--json]\ndokebi app list [--json]\ndokebi module add <name> [--no-views] [--dry-run] [--json]\ndokebi module remove <name> [--dry-run] [--json]\ndokebi module list [--json]\ndokebi dev\ndokebi start [--foreground] [--wait-ms <ms>] [--log-max-mb <MB>] [--log-files <n>] [--json]\ndokebi stop [--timeout-ms <ms>] [--force] [--json]\ndokebi status [--json]\ndokebi logs [-n <lines>] [-f]\n';
+import { verify } from './verify.js';
+/** 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`;
+/** Names the top-level dispatcher knows (`app`, `module`, `plugins`, `recipe`, `config` take more). */
+const TOP_LEVEL = [...new Set(COMMANDS.map((item) => item.name.split(' ')[0]))];
+/** Levenshtein distance, small inputs only (command names). */
+function distance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++)
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Close names for an unknown command: same prefix or at most 2 edits (up to 3, best first). */
+export function suggest(input, names) {
+    const aliases = {
+        help: '--help',
+        version: '--version',
+        '-v': '--version',
+    };
+    const alias = aliases[input];
+    if (alias)
+        return [alias];
+    return names
+        .map((name) => ({ name, score: distance(input, name) }))
+        .filter((item) => item.score <= Math.min(2, Math.floor(item.name.length / 2)) ||
+        (input.length >= 3 && item.name.startsWith(input)))
+        .sort((a, b) => a.score - b.score || a.name.localeCompare(b.name))
+        .slice(0, 3)
+        .map((item) => item.name);
+}
+function unknownCommand(input, names, prefix = '') {
+    const suggestions = suggest(input, names).map((name) => name.startsWith('-') ? name : `${prefix}${name}`);
+    const shown = `${prefix}${input}`;
+    return new CliError('UNKNOWN_COMMAND', suggestions.length
+        ? `Unknown command "${shown}". Did you mean ${suggestions.map((name) => `"dokebi ${name}"`).join(' or ')}?`
+        : `Unknown command "${shown}". Run dokebi --help for the commands.`, { details: { command: shown, suggestions }, phase: 'arguments' });
+}
+/** `dokebi <command> [<subcommand>] --help`: that command's usage and summary. */
+function commandHelp(words) {
+    const [first, second] = words;
+    if (!first || first.startsWith('-'))
+        return undefined;
+    const exact = second && !second.startsWith('-') ? `${first} ${second}` : undefined;
+    const matched = COMMANDS.filter((item) => exact && COMMANDS.some((other) => other.name === exact)
+        ? item.name === exact
+        : item.name === first || item.name.startsWith(`${first} `));
+    if (!matched.length)
+        return undefined;
+    return `${matched
+        .map((item) => {
+        const details = COMMAND_DETAILS[item.name];
+        const width = Math.max(0, ...(details?.flags ?? []).map(([flag]) => flag.length));
+        return [
+            item.usage,
+            `    ${item.summary}`,
+            ...(details?.flags.length
+                ? [
+                    '  flags:',
+                    ...details.flags.map(([flag, text]) => `    ${flag.padEnd(width)}  ${text}`),
+                ]
+                : []),
+            ...(details ? [`  example:\n${details.example.replace(/^/gm, '    ')}`] : []),
+        ].join('\n');
+    })
+        .join('\n')}\n`;
+}
 const raw = process.argv.slice(2);
 const machine = raw.includes('--json');
 const args = raw.filter((arg) => arg !== '--json');
@@ -16,6 +93,7 @@ function flags(input, allowed) {
     let dryRun = false;
     let to;
     const sets = [];
+    const add = {};
     for (let index = 0; index < input.length; index++) {
         const arg = input[index];
         if (arg === '--dry-run' && !dryRun)
@@ -23,47 +101,177 @@ function flags(input, allowed) {
         else if (arg === '--set' && allowed.set) {
             const value = input[++index];
             if (value === undefined || value.startsWith('--'))
-                throw new CliError('USAGE', HELP);
+                throw new CliError('USAGE', USAGE_LINES);
             sets.push(parseSetOption(value));
         }
         else if (arg === '--to' && allowed.to && to === undefined) {
             const value = input[++index];
             if (!value || value.startsWith('-'))
-                throw new CliError('USAGE', HELP);
+                throw new CliError('USAGE', USAGE_LINES);
             to = value;
         }
+        else if (arg === '--adapter' && allowed.add && add.adapter === undefined) {
+            const value = input[++index];
+            if (!value || value.startsWith('-'))
+                throw new CliError('USAGE', USAGE_LINES);
+            add.adapter = value;
+        }
+        else if (arg === '--no-first-app' && allowed.add && add.firstApp === undefined)
+            add.firstApp = false;
         else
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
     }
-    return { dryRun, sets, to };
+    return { dryRun, sets, to, add };
+}
+/** Prints a result: the envelope with --json, else pretty JSON (or `text` when given). */
+function print(name, result, text, ok = true) {
+    process.stdout.write(machine
+        ? JSON.stringify(envelope(name, result, ok)) + '\n'
+        : text !== undefined
+            ? text + (text.endsWith('\n') ? '' : '\n')
+            : JSON.stringify(result, null, 2) + '\n');
 }
 async function main() {
     if (raw.filter((arg) => arg === '--json').length > 1)
-        throw new CliError('USAGE', HELP);
-    if (command === '--help' || command === '--version') {
+        throw new CliError('USAGE', USAGE_LINES);
+    if (command !== '--help' &&
+        command !== '-h' &&
+        (args.includes('--help') || args.includes('-h'))) {
+        // `dokebi <command> [<subcommand>] --help`: that command only, exit 0.
+        const words = [command, ...args.filter((arg) => arg !== '--help' && arg !== '-h')];
+        const text = commandHelp(words);
+        if (!text)
+            throw unknownCommand(command, [...TOP_LEVEL, '--help', '--version']);
+        process.stdout.write(machine ? JSON.stringify(envelope(command, text)) + '\n' : text);
+        return;
+    }
+    if (command === '--help' || command === '-h' || command === '--version') {
         if (args.length)
-            throw new CliError('USAGE', HELP);
-        const value = command === '--help' ? HELP : CLI_VERSION;
+            throw new CliError('USAGE', USAGE_LINES);
+        const value = command === '--version' ? CLI_VERSION : HELP;
+        if (command !== '--version')
+            writeBanner(process.stderr, machine);
         process.stdout.write(machine
             ? JSON.stringify(envelope(command, value)) + '\n'
             : value + (value.endsWith('\n') ? '' : '\n'));
         return;
     }
-    if (command === 'inspect' || command === 'doctor') {
+    if (command === 'guide') {
+        if (args.length)
+            throw new CliError('USAGE', USAGE_LINES);
+        const guide = buildGuide(await loadCatalog());
+        writeBanner(process.stderr, machine);
+        print(command, guide, guide.text);
+        return;
+    }
+    if (command === 'plugins') {
+        await pluginsCommand(args);
+        return;
+    }
+    if (command === 'recipe') {
+        await recipeCommand(args);
+        return;
+    }
+    if (command === 'verify') {
+        const options = serverFlags(args, { '--wait-ms': undefined }, []);
+        const waitMs = options.numbers.get('--wait-ms');
+        const result = await verify(process.cwd(), waitMs !== undefined ? { waitMs } : {});
+        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')}`
+            : ''}`, result.ok);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (command === 'check') {
         if (args.length)
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
+        const result = await check(process.cwd());
+        print(command, result, checkText(result), result.ok);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (command === 'config') {
+        const action = args.shift();
+        if (action === 'secret') {
+            const dryRun = args.includes('--dry-run');
+            const rest = args.filter((arg) => arg !== '--dry-run');
+            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;
+            mutationStarted = true;
+            const result = await new Project().configSecret(process.cwd(), target.slice(0, dot), path, dryRun);
+            print('config secret', result);
+            return;
+        }
+        if (action !== 'set') {
+            if (action && !action.startsWith('-'))
+                throw unknownCommand(action, ['set', 'secret'], 'config ');
+            throw new CliError('USAGE', USAGE_LINES);
+        }
+        let dryRun = false;
+        const assignments = [];
+        for (const arg of args) {
+            if (arg === '--dry-run' && !dryRun)
+                dryRun = true;
+            else if (!arg.startsWith('-')) {
+                // <plugin-id>.<path>=<value>: the plugin id has no dot; the path is dot separated.
+                const dot = arg.indexOf('.');
+                const equals = arg.indexOf('=');
+                if (dot <= 0 || equals < dot)
+                    throw new CliError('USAGE', USAGE_LINES);
+                assignments.push({ plugin: arg.slice(0, dot), set: parseSetOption(arg.slice(dot + 1)) });
+            }
+            else
+                throw new CliError('USAGE', USAGE_LINES);
+        }
+        if (!assignments.length)
+            throw new CliError('USAGE', USAGE_LINES);
+        mutationStarted = true;
+        const result = await new Project().configSet(process.cwd(), assignments, dryRun);
+        printWarnings(result.warnings);
+        print('config set', result);
+        return;
+    }
+    if (command === 'dev-infra') {
+        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(), {
+            dryRun,
+            ...(dbPort !== undefined ? { dbPort } : {}),
+        });
+        print(command, result);
+        return;
+    }
+    if (command === 'inspect' || command === 'doctor') {
+        const verbose = args.length === 1 && args[0] === '--verbose';
+        if (args.length && !verbose)
+            throw new CliError('USAGE', USAGE_LINES);
         const result = await new ProjectInspector().inspect(process.cwd(), {
             runChecks: command === 'doctor',
         });
         const ok = command === 'inspect' || result.healthy;
-        process.stdout.write(JSON.stringify(machine ? envelope(command, result, ok) : result, null, 2) + '\n');
+        // --json is always complete (summary first); people get the short form unless --verbose.
+        process.stdout.write(machine
+            ? `${JSON.stringify(envelope(command, result, ok), null, 2)}\n`
+            : verbose
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : inspectionText(result));
         if (!ok)
             process.exitCode = 1;
         return;
     }
     if (command === 'migrate') {
         if (args.length && (args.length !== 1 || args[0] !== '--dry-run'))
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         mutationStarted = true;
         const result = await new Project().migrate(process.cwd(), args[0] === '--dry-run');
         process.stdout.write(JSON.stringify(machine ? envelope(command, result) : result, null, 2) + '\n');
@@ -81,22 +289,36 @@ async function main() {
         await moduleCommand(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', HELP);
+        throw new CliError('USAGE', USAGE_LINES);
     const project = new Project();
     let result;
     if (command === 'init') {
-        if (args.length &&
-            (args.length !== 2 || args[0] !== '--core' || !args[1] || args[1].startsWith('-')))
-            throw new CliError('USAGE', HELP);
-        mutationStarted = true;
-        result = await project.init(target, args[1]);
+        let core;
+        let dryRun = false;
+        for (let index = 0; index < args.length; index++) {
+            const arg = args[index];
+            if (arg === '--core' && core === undefined) {
+                core = args[++index];
+                if (!core || core.startsWith('-'))
+                    throw new CliError('USAGE', USAGE_LINES);
+            }
+            else if (arg === '--dry-run' && !dryRun)
+                dryRun = true;
+            else
+                throw new CliError('USAGE', USAGE_LINES);
+        }
+        writeBanner(process.stderr, machine);
+        mutationStarted = !dryRun;
+        result = await project.init(target, core, dryRun);
     }
     else if (command === 'add') {
-        const options = flags(args, { set: true });
+        const options = flags(args, { set: true, add: true });
         mutationStarted = true;
-        result = await project.add(process.cwd(), target, options.dryRun, options.sets);
+        result = await project.add(process.cwd(), target, options.dryRun, options.sets, options.add);
     }
     else if (command === 'upgrade') {
         const options = flags(args, { to: true });
@@ -109,12 +331,187 @@ async function main() {
         result = await project.remove(process.cwd(), target, options.dryRun);
     }
     else
-        throw new CliError('USAGE', HELP);
-    if (!machine)
-        for (const warning of result.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`);
+        throw new CliError('USAGE', USAGE_LINES);
+    printWarnings(result.warnings);
     process.stdout.write(JSON.stringify(machine ? envelope(command, result) : result, null, 2) + '\n');
+    // stdout stays the result document; the same next steps are printed for people on stderr.
+    if (!machine && result.nextSteps?.length)
+        process.stderr.write(`next steps:\n${result.nextSteps.map((step) => `  ${step.command}\n      ${step.why}\n`).join('')}`);
+}
+/** The short human form of inspect/doctor: summary, each diagnostic and plugin on one line. */
+function inspectionText(result) {
+    const { summary } = result;
+    const lines = [
+        `${summary.healthy ? 'healthy' : 'NOT healthy'}: ${summary.errors} errors, ${summary.warnings} warnings, ${summary.plugins} plugins, core ${result.coreVersion ?? '-'}`,
+        ...result.diagnostics.map((item) => `${item.severity === 'error' ? 'error  ' : 'warning'} ${item.code} ${item.path}${item.plugin ? ` (${item.plugin})` : ''}${item.hint ? `\n        hint: ${item.hint}` : ''}`),
+        ...result.plugins.map((item) => `plugin ${item.expected.id} ${item.installed?.version ?? 'MISSING'}${item.documentation ? ` · ${item.documentation}` : ''}`),
+        'details: --verbose (or --json for the full document)',
+    ];
+    return `${lines.join('\n')}\n`;
+}
+/** Human output: warnings people should see go to stderr (the result stays on stdout). */
+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')
+            process.stderr.write(`warning: ${warning.path} is not a @dokebi package; install it only with the user's consent\n`);
+}
+/** `dokebi plugins list|search|info|doc` (D-0065). */
+async function pluginsCommand(input) {
+    const action = input.shift();
+    const name = `plugins ${action}`;
+    if (action === 'list') {
+        let compatible = false;
+        let online = false;
+        for (const arg of input) {
+            if (arg === '--compatible' && !compatible)
+                compatible = true;
+            else if (arg === '--online' && !online)
+                online = true;
+            else
+                throw new CliError('USAGE', USAGE_LINES);
+        }
+        const result = await pluginsList(process.cwd(), { compatible, online });
+        print(name, result, result.packages
+            .map((item) => `${item.package}@${item.version}${item.installed ? ` (installed ${item.installed})` : ''}${item.compatible ? '' : ' [not for this core]'}\n    ${item.summary}\n    provides: ${item.provides.join(', ') || '-'} · ${item.install}`)
+            .join('\n') +
+            `\n${result.warnings.map((warning) => `warning: ${warning.code} ${warning.message}`).join('\n')}`);
+    }
+    else if (action === 'search') {
+        const words = input.filter((arg) => !arg.startsWith('-'));
+        if (!words.length || words.length !== input.length)
+            throw new CliError('USAGE', USAGE_LINES);
+        const result = await pluginsSearch(words.join(' '));
+        print(name, result, [
+            ...result.matches.map((item) => `${item.package}@${item.version}: ${item.summary}`),
+            ...result.recipes.map((recipe) => `recipe ${recipe.name}: ${recipe.summary}`),
+            ...result.absent.map((entry) => `ABSENT ${entry.capability}: ${entry.summary}. ${entry.instead}`),
+            ...(result.status === 'unknown' ? ['nothing found (not in the catalog)'] : []),
+        ].join('\n'));
+    }
+    else if (action === 'info' || action === 'doc') {
+        const key = input.shift();
+        if (!key || key.startsWith('-') || input.length)
+            throw new CliError('USAGE', USAGE_LINES);
+        if (action === 'info')
+            print(name, await pluginsInfo(process.cwd(), key));
+        else {
+            const result = await pluginsDoc(process.cwd(), key);
+            print(name, result, `# ${result.path} (${result.package} ${result.version})\n\n${result.content}`);
+        }
+    }
+    else if (action && !action.startsWith('-'))
+        throw unknownCommand(action, ['list', 'search', 'info', 'doc'], 'plugins ');
+    else
+        throw new CliError('USAGE', USAGE_LINES);
+}
+/** `dokebi recipe list|<name>` (D-0065). Missing answers: questions, exit 2, nothing installed. */
+async function recipeCommand(input) {
+    const name = input.shift();
+    if (!name || name.startsWith('-'))
+        throw new CliError('USAGE', USAGE_LINES);
+    if (name === 'list') {
+        if (input.length)
+            throw new CliError('USAGE', USAGE_LINES);
+        const result = await listRecipes();
+        print('recipe list', result, result.recipes
+            .map((recipe) => `${recipe.name}: ${recipe.summary}\n    questions: ${recipe.questions.join(', ')}`)
+            .join('\n'));
+        return;
+    }
+    const answers = {};
+    const flagOf = {
+        '--view': 'view',
+        '--db': 'db',
+        '--dev-infra': 'devInfra',
+        '--admin': 'admin',
+    };
+    let dir;
+    let defaults = false;
+    let answersFrom;
+    let dryRun = false;
+    let port;
+    let dbPort;
+    const number = (flag, value) => {
+        const parsed = Number(value);
+        if (value === undefined || !Number.isSafeInteger(parsed) || parsed < 1 || parsed > 65535)
+            throw new CliError('USAGE', `${flag} must be a port from 1 to 65535\n${USAGE_LINES}`);
+        return parsed;
+    };
+    for (let index = 0; index < input.length; index++) {
+        const arg = input[index];
+        const question = flagOf[arg];
+        if (question && answers[question] === undefined) {
+            const value = input[++index];
+            if (!value || value.startsWith('-'))
+                throw new CliError('USAGE', USAGE_LINES);
+            answers[question] = value;
+        }
+        else if (arg === '--dir' && dir === undefined) {
+            dir = input[++index];
+            if (!dir || dir.startsWith('-'))
+                throw new CliError('USAGE', USAGE_LINES);
+        }
+        else if (arg === '--port' && port === undefined)
+            port = number(arg, input[++index]);
+        else if (arg === '--db-port' && dbPort === undefined)
+            dbPort = number(arg, input[++index]);
+        else if (arg === '--defaults' && !defaults)
+            defaults = true;
+        else if (arg === '--answers-from' && answersFrom === undefined) {
+            const value = input[++index];
+            if (value !== 'user' && value !== 'defaults')
+                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 === '--dry-run' && !dryRun)
+            dryRun = true;
+        else
+            throw new CliError('USAGE', USAGE_LINES);
+    }
+    mutationStarted = !dryRun;
+    const result = await runRecipe({
+        name,
+        answers,
+        defaults,
+        ...(answersFrom !== undefined ? { answersFrom } : {}),
+        dryRun,
+        ...(dir !== undefined ? { dir } : {}),
+        ...(port !== undefined ? { port } : {}),
+        ...(dbPort !== undefined ? { dbPort } : {}),
+    }, new Project());
+    if (result.status === 'needs-answers') {
+        // Not an error of the command: the answers come from the user. Nothing was installed.
+        process.exitCode = 2;
+        if (machine)
+            process.stdout.write(JSON.stringify({
+                schemaVersion: 1,
+                cliVersion: CLI_VERSION,
+                command: `recipe ${name}`,
+                ok: false,
+                result,
+                error: {
+                    code: 'ANSWERS_REQUIRED',
+                    message: `Ask the user: ${result.missing.join(', ')} — then end your turn and wait for the answers`,
+                    phase: 'arguments',
+                    mutation: 'none',
+                    details: { missing: result.missing },
+                },
+            }) + '\n');
+        else
+            process.stdout.write(`ANSWERS_REQUIRED — ask the user, then end your turn; install nothing before they answer (recipe ${name}: ${result.summary})\n\n${result.questions
+                .map((question) => `${question.flag} — ${question.question}${question.answer ? ` [answered: ${question.answer.value}]` : ''}${question.when ? ` (only when ${JSON.stringify(question.when)})` : ''}\n${question.options
+                .map((option) => `  ${option.value}${option.value === question.default ? ' (default)' : ''}${option.available ? '' : ' — NOT AVAILABLE'}: ${option.label}${option.why ? ` — ${option.why}` : ''}${option.note ? ` — NOTE: ${option.note}` : ''}${option.pros.length ? `\n      + ${option.pros.join('\n      + ')}` : ''}${option.cons.length ? `\n      - ${option.cons.join('\n      - ')}` : ''}`)
+                .join('\n')}\n  default ${question.default}: ${question.defaultReason}`)
+                .join('\n\n')}\n\n${result.next}\n`);
+        return;
+    }
+    print(`recipe ${name}`, result);
+    if (!machine && result.report)
+        process.stderr.write(`${result.report}\n`);
 }
 /**
  * Reads `--name <number>` style flags of the server commands; anything else is a usage error.
@@ -131,11 +528,11 @@ function serverFlags(input, numbers, switches) {
             const text = input[++index];
             const value = Number(text);
             if (text === undefined || !Number.isSafeInteger(value) || value < min || value > max)
-                throw new CliError('USAGE', `${arg} must be an integer from ${min} to ${max}\n${HELP}`);
+                throw new CliError('USAGE', `${arg} must be an integer from ${min} to ${max}\n${USAGE_LINES}`);
             result.numbers.set(arg, value);
         }
         else
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
     }
     return result;
 }
@@ -145,7 +542,7 @@ async function serverCommand(input) {
     const print = (result, text) => process.stdout.write(machine ? JSON.stringify(envelope(command, result)) + '\n' : text + '\n');
     if (command === 'dev') {
         if (input.length || machine)
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         process.exitCode = await server.dev(root, (line) => process.stderr.write(`[dokebi dev] ${line}\n`));
     }
     else if (command === 'start') {
@@ -158,7 +555,7 @@ async function serverCommand(input) {
         if (options.switches.has('--foreground')) {
             // The foreground app writes to the terminal; rotation belongs to systemd/Docker there.
             if (machine || options.numbers.size)
-                throw new CliError('USAGE', HELP);
+                throw new CliError('USAGE', USAGE_LINES);
             process.exitCode = await server.foreground(root);
             return;
         }
@@ -173,7 +570,7 @@ async function serverCommand(input) {
         if (!machine)
             for (const warning of result.warnings)
                 process.stderr.write(`warning: ${warning}\n`);
-        print(result, `started pid ${result.pid}${result.ready ? ` (ready in ${result.ms} ms)` : ''}\nlog: ${result.log} (rotated at ${Math.round(result.logMaxBytes / 1048576)} MB, ${result.logFiles} older files kept)`);
+        print(result, `started pid ${result.pid}${result.ready ? ` (ready in ${result.ms} ms)` : ''}${addressLines(result)}\nlog: ${result.log} (rotated at ${Math.round(result.logMaxBytes / 1048576)} MB, ${result.logFiles} older files kept)`);
     }
     else if (command === 'stop') {
         const options = serverFlags(input, { '--timeout-ms': undefined }, ['--force']);
@@ -182,14 +579,14 @@ async function serverCommand(input) {
             for (const warning of result.warnings ?? [])
                 process.stderr.write(`warning: ${warning}\n`);
         print(result, result.stopped
-            ? `stopped pid ${result.pid} in ${result.ms} ms${result.forced ? ' (killed)' : ''}`
+            ? `stopped pid ${result.pid} in ${result.ms} ms${result.forced ? ' (killed)' : ''}${result.proof === 'http' ? ' (no ps: the app proved its instance token over HTTP)' : result.proof === 'log-writer' ? ' (no ps: its log writer proved the instance token)' : ''}${result.via === 'log-writer' ? ' (signalled by its log writer: this shell may not signal it)' : ''}`
             : result.stale
                 ? `not running (pid ${result.pid} had already exited; removed the pid file)`
                 : 'not running');
     }
     else if (command === 'status') {
         if (input.length)
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         const result = await server.status(root);
         const files = result.logFiles
             .map((file) => `\n  ${file.file} (${(file.bytes / 1048576).toFixed(1)} MB)`)
@@ -201,7 +598,7 @@ async function serverCommand(input) {
             ? `\nlog writer diagnostics: ${result.logWriterLog}`
             : '';
         print(result, (result.running
-            ? `running pid ${result.pid} · up ${result.uptimeSec} s · ${result.rssMb} MB${writer}`
+            ? `running pid ${result.pid} · up ${result.uptimeSec} s${result.rssMb !== undefined ? ` · ${result.rssMb} MB` : ''}${result.proof === 'http' ? ' · proof: http (no ps; the app answered its instance token)' : result.proof === 'log-writer' ? ' · proof: log-writer (no ps; its log writer proved the instance token)' : ''}${writer}`
             : result.stale
                 ? `stopped: pid ${result.pid} exited without dokebi stop (crashed or killed); see dokebi logs`
                 : 'stopped') +
@@ -212,7 +609,7 @@ async function serverCommand(input) {
     }
     else {
         if (machine)
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         const options = serverFlags(input, { '-n': undefined }, ['-f', '--follow']);
         await server.logs(root, options.numbers.get('-n'), options.switches.has('-f') || options.switches.has('--follow'));
     }
@@ -224,13 +621,13 @@ async function app(input) {
     let result;
     if (action === 'list') {
         if (input.length)
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         result = await project.appList(process.cwd());
     }
     else if (action === 'add' || action === 'remove') {
         const name = input.shift();
         if (!name || name.startsWith('-'))
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         let dryRun = false;
         let inertia = false;
         let ssr = false;
@@ -254,11 +651,11 @@ async function app(input) {
                 index++;
             }
             else
-                throw new CliError('USAGE', HELP);
+                throw new CliError('USAGE', USAGE_LINES);
         }
         // Server rendering (D-0039) is a choice of an Inertia app.
         if (ssr && !inertia)
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         mutationStarted = true;
         result =
             action === 'add'
@@ -275,7 +672,7 @@ async function app(input) {
         const first = input.shift();
         const domain = action === 'link' ? input.shift() : first;
         if (!first || first.startsWith('-') || !domain || domain.startsWith('-'))
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         let dryRun = false;
         let template;
         for (let index = 0; index < input.length; index++) {
@@ -288,7 +685,7 @@ async function app(input) {
                 index++;
             }
             else
-                throw new CliError('USAGE', HELP);
+                throw new CliError('USAGE', USAGE_LINES);
         }
         mutationStarted = true;
         result =
@@ -299,8 +696,10 @@ async function app(input) {
                 })
                 : await project.appUnlink(process.cwd(), domain, dryRun);
     }
+    else if (action && !action.startsWith('-'))
+        throw unknownCommand(action, ['add', 'remove', 'link', 'unlink', 'list'], 'app ');
     else
-        throw new CliError('USAGE', HELP);
+        throw new CliError('USAGE', USAGE_LINES);
     process.stdout.write(JSON.stringify(machine ? envelope(`app ${action}`, result) : result, null, 2) + '\n');
 }
 /** `dokebi module add|remove|list` (D-0032): feature modules in src/shared/modules/<name>. */
@@ -310,13 +709,13 @@ async function moduleCommand(input) {
     let result;
     if (action === 'list') {
         if (input.length)
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         result = await project.moduleList(process.cwd());
     }
     else if (action === 'add' || action === 'remove') {
         const name = input.shift();
         if (!name || name.startsWith('-'))
-            throw new CliError('USAGE', HELP);
+            throw new CliError('USAGE', USAGE_LINES);
         let dryRun = false;
         let views = true;
         for (const arg of input) {
@@ -325,7 +724,7 @@ async function moduleCommand(input) {
             else if (action === 'add' && arg === '--no-views' && views)
                 views = false;
             else
-                throw new CliError('USAGE', HELP);
+                throw new CliError('USAGE', USAGE_LINES);
         }
         mutationStarted = true;
         result =
@@ -333,8 +732,10 @@ async function moduleCommand(input) {
                 ? await project.moduleAdd(process.cwd(), name, { views, dryRun })
                 : await project.moduleRemove(process.cwd(), name, dryRun);
     }
+    else if (action && !action.startsWith('-'))
+        throw unknownCommand(action, ['add', 'remove', 'list'], 'module ');
     else
-        throw new CliError('USAGE', HELP);
+        throw new CliError('USAGE', USAGE_LINES);
     process.stdout.write(JSON.stringify(machine ? envelope(`module ${action}`, result) : result, null, 2) + '\n');
 }
 await main().catch((error) => {
@@ -346,6 +747,17 @@ await main().catch((error) => {
             nextSteps(error));
     process.exitCode = 1;
 });
+/**
+ * `urls:` (where the app answers: its loopback domains) and, when it differs, `listen:` (the
+ * bound address, which answers only the Host names of the app domains) — AI-M03.
+ */
+function addressLines(result) {
+    const same = result.urls.length === result.listen.length &&
+        result.urls.every((url, index) => url === result.listen[index]);
+    return `${result.urls.length ? `\nurls: ${result.urls.join(' ')}` : ''}${result.listen.length && !same
+        ? `\nlisten: ${result.listen.join(' ')} (the bound address${result.urls.length ? '' : '; it answers only the Host names of the app domains, none of which is a loopback name such as localhost'})`
+        : ''}`;
+}
 /** Human-readable follow-ups from error details: missing option fields and plugin hints. */
 function nextSteps(error) {
     if (!(error instanceof CliError) || !error.details || typeof error.details !== 'object')
@@ -359,6 +771,23 @@ function nextSteps(error) {
     const tail = error.details.tail;
     if (typeof tail === 'string' && tail)
         lines.add(`last log lines:\n${tail.trimEnd()}`);
+    const npmError = error.details.stderr;
+    if (error.code === 'NPM_FAILED' && typeof npmError === 'string' && npmError.trim())
+        lines.add(`npm stderr (end):\n${npmError.trimEnd()}`);
+    if (error.code === 'UNKNOWN_COMMAND')
+        lines.add('hint: dokebi --help lists the commands');
+    const hint = error.details.hint;
+    if (typeof hint === 'string')
+        lines.add(`hint: ${hint}`);
+    // 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')
+        lines.add(`${waitForUser === true ? 'ask the user' : 'question'}: ${question}`);
+    if (typeof next === 'string')
+        lines.add(`next: ${next}`);
+    const manual = error.details.manualStop;
+    if (typeof manual === 'string')
+        lines.add(`manual stop: ${manual}`);
     if (error.code === 'WORKSPACE_SYNC_FAILED')
         lines.add('hint: run npm install at the workspace root');
     if (Array.isArray(details.diagnostics))