@dokebi/cli 0.2.5 → 0.4.1

package/dist/recipe.js

@@ -0,0 +1,801 @@
+// `dokebi recipe` (D-0065): turns a one-line request into questions, a plan and an applied
+// project. A recipe names capabilities, never packages; the catalog maps each capability to the
+// package that provides it. Without every answer nothing is installed (ANSWERS_REQUIRED). With
+// answers each step calls the existing transactional command, in order, skipping steps that are
+// already satisfied and stopping at the first failure with the steps that completed.
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { HOST_CAPABILITY, loadCatalog, providersOf, } from './catalog.js';
+import { CONFIG_FILE, parseProjectConfig } from './configuration.js';
+import { COMPOSE_FILE, commandOnPath, composeServiceRunning, DB_SERVICE, dockerAvailable, freePortAfter, portInUse, portQuestion, URL_PLACEHOLDER_PREFIX, } from './dev-infra.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { exists } from './filesystem.js';
+import { OutputTail } from './npm-client.js';
+import { initFolder } from './project.js';
+import { saveAppliedRecipe } from './recipe-record.js';
+import * as server from './server.js';
+/** The first sentence of `next` (and of the guide and AGENTS.md §1), word for word. */
+export const ASK_AND_WAIT = '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.';
+/** `dokebi recipe list`. */
+export async function listRecipes() {
+    const catalog = await loadCatalog();
+    return {
+        recipes: catalog.recipes.map((recipe) => ({
+            name: recipe.name,
+            summary: recipe.summary,
+            questions: recipe.questions.filter((id) => !recipe.fixed?.[id]),
+            match: [...recipe.match],
+        })),
+    };
+}
+function recipeOf(catalog, name) {
+    const recipe = catalog.recipes.find((item) => item.name === name);
+    if (!recipe)
+        throw new CliError('UNKNOWN_RECIPE', `No recipe "${name}"`, {
+            details: { recipe: name, recipes: catalog.recipes.map((item) => item.name) },
+            phase: 'arguments',
+        });
+    return recipe;
+}
+function choiceOf(catalog, id) {
+    const choice = catalog.choices.find((item) => item.id === id);
+    if (!choice)
+        throw new CliError('CATALOG_INVALID', `Recipe question ${id} has no choice`);
+    return choice;
+}
+/** `when: { db: '!none' }`: whether the question applies to these answers (unknown: asked). */
+function applies(choice, answers) {
+    for (const [id, rule] of Object.entries(choice.when ?? {})) {
+        const value = answers[id];
+        if (value === undefined)
+            continue;
+        if (rule.startsWith('!') ? value === rule.slice(1) : value !== rule)
+            return false;
+    }
+    return true;
+}
+function variantOf(catalog, capability) {
+    if (!capability)
+        return undefined;
+    for (const item of catalog.packages)
+        for (const variant of item.variants)
+            if (variant.capability === capability)
+                return variant;
+    return undefined;
+}
+/** The plugin package that provides a capability (the recipe never names packages). */
+function provider(catalog, capability) {
+    const found = providersOf(catalog, capability).find((item) => item.kind === 'plugin');
+    if (!found)
+        throw new CliError('CATALOG_INVALID', `No plugin provides ${capability}`, {
+            details: { capability },
+        });
+    return found.package;
+}
+/** The devInfra docker note when `docker` is not on PATH (the default stays; the user decides). */
+export const DOCKER_NOT_FOUND = 'docker was not found on PATH: install and start Docker before applying with docker, or choose url (a database server you already have)';
+/** Question list with options adjusted to the answers given so far (docker per db variant). */
+function questions(catalog, recipe, answers, dockerOnPath = () => commandOnPath('docker')) {
+    const values = Object.fromEntries(Object.entries(answers).map(([id, item]) => [id, item.value]));
+    const db = catalog.choices
+        .find((item) => item.id === 'db')
+        ?.options.find((option) => option.value === values.db);
+    return recipe.questions
+        .filter((id) => !recipe.fixed?.[id])
+        .map((id) => {
+        const choice = choiceOf(catalog, id);
+        const options = choice.options.map((option) => {
+            if (id !== 'devInfra' || option.value !== 'docker' || !db?.capability)
+                return option;
+            const docker = variantOf(catalog, db.capability)?.devInfra?.docker;
+            return docker
+                ? { ...option, alsoInstalls: [...option.alsoInstalls, `docker image ${docker.image}`] }
+                : { ...option, available: false, why: `${db.value} has no Docker setup` };
+        });
+        // AI-M03: say what this machine lacks, but leave the choice (and the default) to the user.
+        const missingDocker = id === 'devInfra' &&
+            options.some((option) => option.value === 'docker' && option.available) &&
+            !dockerOnPath();
+        const shown = missingDocker
+            ? options.map((option) => option.value === 'docker'
+                ? { ...option, missingNeeds: ['docker'], note: DOCKER_NOT_FOUND }
+                : option)
+            : options;
+        const answer = answers[id];
+        return {
+            id,
+            flag: choice.flag,
+            question: choice.question,
+            options: shown,
+            default: choice.default,
+            defaultReason: missingDocker && choice.default === 'docker'
+                ? `${choice.defaultReason}. Note: ${DOCKER_NOT_FOUND}`
+                : choice.defaultReason,
+            ...(choice.when ? { when: choice.when } : {}),
+            ...(answer ? { answer } : {}),
+        };
+    });
+}
+/** Collects answers from flags, recipe-fixed values and (when asked) defaults; validates them. */
+function answer(catalog, recipe, request) {
+    const answers = {};
+    for (const id of Object.keys(request.answers))
+        if (!recipe.questions.includes(id) || recipe.fixed?.[id])
+            throw new CliError('USAGE', `The ${recipe.name} recipe does not ask ${id}`, {
+                details: {
+                    recipe: recipe.name,
+                    questions: recipe.questions.filter((q) => !recipe.fixed?.[q]),
+                },
+                phase: 'arguments',
+            });
+    for (const [id, value] of Object.entries(recipe.fixed ?? {}))
+        answers[id] = { value, answeredBy: 'recipe' };
+    for (const id of recipe.questions) {
+        if (answers[id])
+            continue;
+        const choice = choiceOf(catalog, id);
+        const given = request.answers[id];
+        if (given === undefined)
+            continue;
+        const option = choice.options.find((item) => item.value === given);
+        if (!option)
+            throw new CliError('INVALID_ANSWER', `${choice.flag} ${given} is not an option`, {
+                details: { question: id, options: choice.options.map((item) => item.value) },
+                phase: 'arguments',
+            });
+        if (!option.available)
+            throw new CliError('OPTION_ABSENT', `${choice.flag} ${given}: ${option.why ?? 'not available'}`, {
+                details: { question: id, option: given, why: option.why ?? null },
+                phase: 'arguments',
+            });
+        answers[id] = { value: given, answeredBy: 'flag' };
+    }
+    const missing = [];
+    const values = () => Object.fromEntries(Object.entries(answers).map(([id, item]) => [id, item.value]));
+    for (const id of recipe.questions) {
+        if (answers[id])
+            continue;
+        const choice = choiceOf(catalog, id);
+        if (!applies(choice, values()))
+            continue;
+        if (request.defaults || request.answersFrom === 'defaults')
+            answers[id] = {
+                value: choice.default,
+                answeredBy: 'default',
+                defaultReason: choice.defaultReason,
+            };
+        else
+            missing.push(id);
+    }
+    // A question that does not apply (devInfra with db none) is dropped even if it was answered.
+    for (const id of Object.keys(answers))
+        if (!applies(choiceOf(catalog, id), values()))
+            delete answers[id];
+    return { answers, missing };
+}
+async function view(root) {
+    let stateText;
+    try {
+        stateText = await readFile(join(root, '.dokebi/state.json'), 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    const state = JSON.parse(stateText);
+    const options = parseProjectConfig(await readFile(join(root, CONFIG_FILE), 'utf8')).options;
+    return {
+        installed: new Set((state.plugins ?? []).map((plugin) => plugin.id)),
+        packages: new Set((state.plugins ?? []).flatMap((plugin) => plugin.packageName ?? [])),
+        apps: state.apps ?? [],
+        modules: state.modules ?? [],
+        options,
+    };
+}
+function option(options, path) {
+    let current = options;
+    for (const key of path) {
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Runs a command in the project folder; a failure becomes STEP_COMMAND_FAILED with the bounded,
+ * redacted end of its output (`OutputTail` of npm-client).
+ */
+export async function shell(root, command, args, timeoutMs) {
+    const npmPath = process.env.npm_execpath;
+    const viaNode = command === 'npm' && npmPath?.endsWith('npm-cli.js');
+    const file = viaNode ? process.execPath : command;
+    const argv = viaNode ? [npmPath, ...args] : args;
+    debug('recipe: running', { command, args, root });
+    await new Promise((done, fail) => {
+        const child = spawn(file, argv, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+        const output = new OutputTail();
+        const keep = (chunk) => output.push(chunk);
+        child.stdout.on('data', keep);
+        child.stderr.on('data', keep);
+        const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+        child.once('error', (cause) => {
+            clearTimeout(timer);
+            fail(new CliError('STEP_COMMAND_FAILED', `${command} could not run`, { cause }));
+        });
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0)
+                done();
+            else
+                fail(new CliError('STEP_COMMAND_FAILED', `${command} ${args.join(' ')} failed`, {
+                    details: { exitCode: code, signal, output: output.text() },
+                }));
+        });
+    });
+}
+/** The no-CSRF warning of a plan with HTML forms, with the catalog's `instead` for csrf. */
+function noCsrf(catalog) {
+    const csrf = catalog.absent.find((entry) => entry.capability === 'csrf');
+    return `No CSRF protection: csrf is absent from Dokebi${csrf ? ` — instead: ${csrf.instead}` : ''}.`;
+}
+/** Builds the plan steps for the answers (capability → package through the catalog). */
+function steps(catalog, recipe, answers, context) {
+    const { root, project } = context;
+    const result = [];
+    const value = (id) => answers[id]?.value;
+    const now = () => view(root);
+    const has = async (id) => (await now())?.installed.has(id) ?? false;
+    /** Installed by package name: the app and module hosts come from the catalog (D-0070). */
+    const hasPackage = async (name) => (await now())?.packages.has(name) ?? false;
+    const plugin = (capability) => provider(catalog, capability);
+    const viewChoice = catalog.choices
+        .find((item) => item.id === 'view')
+        ?.options.find((item) => item.value === (value('view') ?? 'ejs'));
+    const inertia = viewChoice?.capability?.startsWith('view.inertia') ?? false;
+    const ssr = viewChoice?.capability === 'view.inertia-vue-ssr';
+    const appFlags = inertia ? ` --inertia${ssr ? ' --ssr' : ''}` : '';
+    const domain = recipe.web.domain;
+    if (context.init)
+        result.push({
+            id: 'init',
+            command: `npx -y @dokebi/cli init ${JSON.stringify(context.dir ?? root)}`,
+            why: 'create the project: core, config, this CLI, TypeScript, AGENTS.md and CLAUDE.md',
+            satisfied: async () => (await now()) !== undefined,
+            run: async () => {
+                await project.init(root);
+            },
+        });
+    const apps = plugin('web.apps');
+    result.push({
+        id: 'app-plugin',
+        command: `npx dokebi add ${apps}${inertia ? ' --no-first-app' : ''}`,
+        why: inertia
+            ? 'multi-app web layer (web, controller, template-ejs come with it); the first app is added as Inertia below'
+            : `multi-app web layer (web, controller, template-ejs come with it) and the EJS app main on ${domain}`,
+        satisfied: () => hasPackage(apps),
+        run: async () => {
+            await project.add(root, apps, false, [], inertia ? { firstApp: false } : {});
+        },
+    });
+    result.push({
+        id: 'web-port',
+        command: `npx dokebi config set dokebi-web.port=${context.port}`,
+        why: `serve on a fixed port (${context.port}) instead of a random one, so verify and the browser know the address`,
+        satisfied: async () => option((await now())?.options ?? {}, ['dokebi-web', 'port']) === context.port,
+        run: async () => {
+            await project.configSet(root, [
+                { plugin: 'dokebi-web', set: { path: ['port'], value: context.port } },
+            ]);
+        },
+    });
+    // HTML forms (the blog's write form) post application/x-www-form-urlencoded, which dokebi-web
+    // refuses (415 FORM_BODY_DISABLED) until formBody is on (AI-M02). Inertia posts JSON.
+    if (recipe.web.forms && !inertia)
+        result.push({
+            id: 'form-body',
+            command: 'npx dokebi config set dokebi-web.formBody=true',
+            why: `HTML forms post application/x-www-form-urlencoded; dokebi-web refuses it (415 FORM_BODY_DISABLED) until formBody is on. ${noCsrf(catalog)}`,
+            satisfied: async () => option((await now())?.options ?? {}, ['dokebi-web', 'formBody']) === true,
+            run: async () => {
+                await project.configSet(root, [
+                    { plugin: 'dokebi-web', set: { path: ['formBody'], value: true } },
+                ]);
+            },
+        });
+    if (inertia && viewChoice?.capability) {
+        const views = plugin(viewChoice.capability);
+        result.push({
+            id: 'view-plugin',
+            command: `npx dokebi add ${views}`,
+            why: `${viewChoice.label}: the server adapter for the Vue pages`,
+            satisfied: () => has('dokebi-template-inertia'),
+            run: async () => {
+                await project.add(root, views);
+            },
+        });
+        result.push({
+            id: 'main-app',
+            command: `npx dokebi app add main${appFlags} --domain ${domain}`,
+            why: `the app main on ${domain} with Vue pages (adds vite.config.ts, the build script, Vite and Vue)`,
+            satisfied: async () => (await now())?.apps.includes('main') ?? false,
+            run: async () => {
+                await project.appAdd(root, 'main', { domains: [domain], inertia: true, ssr });
+            },
+        });
+    }
+    if (recipe.module) {
+        const modules = plugin('web.modules');
+        const moduleName = recipe.module.name;
+        const noViews = recipe.module.views === false || inertia;
+        result.push({
+            id: 'module-plugin',
+            command: `npx dokebi add ${modules}`,
+            why: 'feature modules (src/shared/modules/<name>) that apps mount under a prefix',
+            satisfied: () => hasPackage(modules),
+            run: async () => {
+                await project.add(root, modules);
+            },
+        });
+        result.push({
+            id: 'module',
+            command: `npx dokebi module add ${moduleName}${noViews ? ' --no-views' : ''}`,
+            why: `${recipe.module.why}${noViews && inertia ? ' (JSON routes: Vue pages live in the app views)' : ''}`,
+            satisfied: async () => (await now())?.modules.includes(moduleName) ?? false,
+            run: async () => {
+                await project.moduleAdd(root, moduleName, { views: !noViews });
+            },
+        });
+    }
+    const dbChoice = catalog.choices
+        .find((item) => item.id === 'db')
+        ?.options.find((item) => item.value === value('db'));
+    const variant = variantOf(catalog, dbChoice?.capability ?? null);
+    if (dbChoice?.capability && variant?.adapter) {
+        const db = plugin(dbChoice.capability);
+        const adapter = variant.adapter;
+        result.push({
+            id: 'db',
+            command: `npx dokebi add ${db} --adapter ${adapter}`,
+            why: `${dbChoice.label}: named connection main, adapter src/infra/db/adapters/${adapter}.ts and the ${variant.driver?.package ?? adapter} driver`,
+            satisfied: async () => {
+                const current = await now();
+                return ((current?.installed.has('dokebi-db') ?? false) &&
+                    option(current?.options ?? {}, ['dokebi-db', 'connections', 'main', 'adapter']) ===
+                        adapter);
+            },
+            run: async () => {
+                await project.add(root, db, false, [], { adapter });
+            },
+        });
+        if (variant.migrate) {
+            const migrate = plugin('db.migrate');
+            result.push({
+                id: 'migrate',
+                command: `npx dokebi add ${migrate}`,
+                why: 'migrations and seeds for the connection (run them at deploy time, not at app start)',
+                satisfied: () => has('dokebi-migrate'),
+                run: async () => {
+                    await project.add(root, migrate);
+                },
+            });
+            // The migration history and lock of connection main use the variant's dialect.
+            result.push({
+                id: 'migrate-connection',
+                command: `npx dokebi config set dokebi-migrate.connections.main.dialect=${variant.name}`,
+                why: `migrations of connection main keep their history and lock as ${variant.name}`,
+                satisfied: async () => option((await now())?.options ?? {}, [
+                    'dokebi-migrate',
+                    'connections',
+                    'main',
+                    'dialect',
+                ]) === variant.name,
+                run: async () => {
+                    await project.configSet(root, [
+                        {
+                            plugin: 'dokebi-migrate',
+                            set: { path: ['connections', 'main', 'dialect'], value: variant.name },
+                        },
+                    ]);
+                },
+            });
+        }
+        if (value('devInfra') === 'docker') {
+            result.push({
+                id: 'dev-infra',
+                command: `npx dokebi dev-infra${context.dbPort ? ` --db-port ${context.dbPort}` : ''}`,
+                why: 'compose.yaml, a generated password in .env (git-ignored) and the matching URL in dokebi.yaml',
+                satisfied: async () => {
+                    const url = option((await now())?.options ?? {}, [
+                        'dokebi-db',
+                        'connections',
+                        'main',
+                        'options',
+                        'url',
+                    ]);
+                    return ((await exists(join(root, COMPOSE_FILE))) &&
+                        typeof url === 'string' &&
+                        !url.startsWith(URL_PLACEHOLDER_PREFIX));
+                },
+                run: async () => {
+                    await project.devInfra(root, context.dbPort ? { dbPort: context.dbPort } : {});
+                },
+            });
+            result.push({
+                id: 'dev-db-up',
+                command: 'docker compose up -d --wait',
+                why: `start the ${variant.name} container and wait until it is healthy`,
+                satisfied: () => composeServiceRunning(root),
+                run: () => shell(root, 'docker', ['compose', 'up', '-d', '--wait'], 300_000),
+            });
+        }
+    }
+    if (value('admin') === 'app-code') {
+        const session = plugin('web.session');
+        result.push({
+            id: 'session',
+            command: `npx dokebi add ${session}`,
+            why: 'server-side sessions for the admin login the app writes (Dokebi has no auth plugin); add also generates the cookie-signing secret DOKEBI_SESSION_SECRETS into .env (git-ignored, read by dev, start and verify; the value is never printed)',
+            satisfied: () => has('dokebi-session'),
+            run: async () => {
+                await project.add(root, session);
+            },
+        });
+        result.push({
+            id: 'admin-app',
+            command: `npx dokebi app add admin${appFlags} --domain admin.${domain}`,
+            why: `a separate admin app on admin.${domain}; its login and permission checks are app code`,
+            satisfied: async () => (await now())?.apps.includes('admin') ?? false,
+            run: async () => {
+                await project.appAdd(root, 'admin', { domains: [`admin.${domain}`], inertia, ssr });
+            },
+        });
+    }
+    if (inertia)
+        result.push({
+            id: 'build',
+            command: 'npm run build',
+            why: 'build the Vue pages with Vite (dist/) so the app can serve them',
+            satisfied: async () => false,
+            run: () => shell(root, 'npm', ['run', 'build'], 300_000),
+        });
+    return result;
+}
+async function preflight(root, answers, catalog, plan, port, dbPort, 
+/** The user left the choices to the agent (--defaults / --answers-from defaults). */
+delegated) {
+    const result = [];
+    const devInfra = plan.find((step) => step.id === 'dev-infra');
+    if (devInfra) {
+        const docker = await dockerAvailable();
+        if (!docker.ok)
+            result.push({
+                code: 'DOCKER_MISSING',
+                severity: 'error',
+                message: `Docker (with compose) is not available: ${docker.error ?? 'unknown error'}`,
+                fix: 'start Docker, or ask the user to choose --dev-infra url (an existing database) — never switch the database silently',
+            });
+        else if (!(await devInfra.satisfied()) || !(await composeServiceRunning(root))) {
+            const dbChoice = catalog.choices
+                .find((item) => item.id === 'db')
+                ?.options.find((item) => item.value === answers.db?.value);
+            const wanted = dbPort ?? variantOf(catalog, dbChoice?.capability ?? null)?.devInfra?.docker?.port;
+            // A compose.yaml this project already has decides its port; it is checked by `up`.
+            const kept = await composePort(root);
+            if (wanted && kept === undefined && (await portInUse(wanted))) {
+                const alternative = await freePortAfter(wanted);
+                debug('recipe: database port in use', { port: wanted, alternative, delegated });
+                result.push({
+                    code: 'PORT_IN_USE',
+                    severity: 'error',
+                    message: `Database port ${wanted} on 127.0.0.1 is in use`,
+                    fix: `ask the user, then run again with --db-port ${alternative ?? '<free port>'} (compose.yaml and dokebi.yaml get the same port), or stop what uses ${wanted}`,
+                    ...(alternative ? { alternative } : {}),
+                    ...portQuestion({
+                        what: 'Database',
+                        port: wanted,
+                        alternative,
+                        flag: '--db-port',
+                        delegated,
+                    }),
+                });
+            }
+        }
+    }
+    const running = (await view(root)) ? (await server.status(root)).running : false;
+    if (!running && (await portInUse(port))) {
+        const alternative = await freePortAfter(port);
+        debug('recipe: web port in use', { port, alternative, delegated });
+        result.push({
+            code: 'PORT_IN_USE',
+            severity: 'error',
+            message: `Web port ${port} on 127.0.0.1 is in use`,
+            fix: `ask the user, then run again with --port ${alternative ?? '<free port>'} (or stop what uses ${port})`,
+            ...(alternative ? { alternative } : {}),
+            ...portQuestion({ what: 'Web', port, alternative, flag: '--port', delegated }),
+        });
+    }
+    if (plan.some((step) => step.id === 'build'))
+        result.push({
+            code: 'VITE_BUILD',
+            severity: 'info',
+            message: 'vite, vue, @inertiajs/vue3 and @vitejs/plugin-vue are installed and npm run build runs',
+        });
+    if (plan.some((step) => step.id === 'db'))
+        result.push({
+            code: 'DRIVER_DOWNLOAD',
+            severity: 'info',
+            message: 'the database driver is installed from the npm registry',
+        });
+    return result;
+}
+/**
+ * The taken ports of a preflight as one question for the result (AI-M03): `waitForUser`,
+ * `question` and `next`, like the recipe questions. Empty when no port is taken.
+ */
+function portAsks(checks) {
+    const ports = checks.filter((item) => item.code === 'PORT_IN_USE' && item.question);
+    if (!ports.length)
+        return {};
+    return {
+        waitForUser: ports.some((item) => item.waitForUser),
+        question: ports.map((item) => item.question).join(' '),
+        next: [...new Set(ports.map((item) => item.next))].join(' '),
+    };
+}
+async function composePort(root) {
+    try {
+        const document = parse(await readFile(join(root, COMPOSE_FILE), 'utf8'));
+        const published = String(document?.services?.[DB_SERVICE]?.ports?.[0] ?? '').match(/(?:^|:)(\d+):\d+$/)?.[1];
+        return published ? Number(published) : undefined;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new CliError('COMPOSE_INVALID', `${COMPOSE_FILE} cannot be read`, { cause: error });
+    }
+}
+function nextSteps(catalog, recipe, answers, plan, port) {
+    const result = [];
+    // The app and module hosts by capability (D-0070), the rest by the step that installed them.
+    const ids = new Set([HOST_CAPABILITY.apps, HOST_CAPABILITY.modules].flatMap((capability) => providersOf(catalog, capability).find((item) => item.kind === 'plugin')?.id ?? []));
+    if (plan.some((step) => step.id === 'view-plugin'))
+        ids.add('dokebi-template-inertia');
+    else
+        ids.add('dokebi-template-ejs');
+    if (plan.some((step) => step.id === 'db'))
+        ids.add('dokebi-db');
+    if (plan.some((step) => step.id === 'migrate'))
+        ids.add('dokebi-migrate');
+    if (plan.some((step) => step.id === 'session'))
+        ids.add('dokebi-session');
+    for (const id of ids)
+        result.push({
+            command: `npx dokebi plugins doc ${id} --json`,
+            why: `read the installed ${id} AI.md before writing code with it`,
+        });
+    for (const line of recipe.then ?? [])
+        result.push({ command: `edit: ${line}`, why: recipe.summary });
+    if (answers.devInfra?.value === 'url')
+        result.push({
+            command: 'edit dokebi.yaml: options.dokebi-db.connections.main.options.url',
+            why: 'url mode: write the existing database URL (with its password) here; never pass it with --set',
+        });
+    if (answers.admin?.value === 'app-code')
+        result.push({
+            command: 'edit src/apps/admin: login form, password hash (node:crypto scrypt), session check, CSRF token',
+            why: 'Dokebi has no auth or csrf plugin (absent): the admin app writes them',
+        });
+    if (plan.some((step) => step.id === 'form-body'))
+        result.push({
+            command: 'edit: every HTML form that changes data (the write form) — a CSRF token check in app code',
+            why: `dokebi-web.formBody is on so forms post; ${noCsrf(catalog)} Tell the user the forms have no CSRF protection until the app adds it.`,
+        });
+    // D-0074: how a write form refuses input and shows it, the same for the schema and the app.
+    if (recipe.web.forms)
+        result.push(plan.some((step) => step.id === 'view-plugin')
+            ? {
+                command: "edit: every Inertia write form — useForm().post(url, { only: ['<props it changes>'] }), each field's message from form.errors.<field>; in the handler throw validationError({ <field>: '<message>' }) from @dokebi/web",
+                why: 'a refused field comes back to the form (422 → 303 back with errors, @dokebi/session); only keeps the GET after the redirect to the props that changed (npx dokebi check warns: inertia-form-only)',
+            }
+            : {
+                command: 'edit: every write form — <form method="post">, each field value="<%= data.old.<field> ?? \'\' %>" and its message from data.errors.<field>; in the handler throw validationError({ <field>: \'<message>\' }) from @dokebi/web',
+                why: plan.some((step) => step.id === 'session')
+                    ? 'a refused route schema and the app check give the same 422 VALIDATION_FAILED (D-0074); with @dokebi/session (in this plan) the refused form comes back to its page (303) with data.errors and data.old; never send a hand-made 422'
+                    : 'a refused route schema and the app check give the same 422 VALIDATION_FAILED (D-0074); never send a hand-made 422. Without a session the refused form shows views/default/errors/422.ejs (else errors/error.ejs) with fields, errors and old',
+            });
+    // D-0074 addendum 1: an EJS write form comes back to its page only with a session.
+    if (recipe.web.forms && !plan.some((step) => step.id === 'view-plugin' || step.id === 'session'))
+        result.push({
+            command: 'npx dokebi add @dokebi/session',
+            why: 'so a refused HTML form goes back to its page with the typed values and the field messages (D-0074 addendum 1) instead of the 422 page; ask the user first (it writes DOKEBI_SESSION_SECRETS into .env and keeps sessions in memory until another store is configured)',
+        });
+    const absent = catalog.absent.map((entry) => entry.capability).join(', ');
+    result.push({
+        command: 'npx dokebi plugins search <feature> --json',
+        why: `before adding a feature, check it exists; absent here: ${absent}`,
+    });
+    result.push({
+        command: 'npx dokebi verify --json',
+        why: `doctor, typecheck, build, start on port ${port}, HTTP checks, stop — say done only when ok is true`,
+    });
+    if (answers.devInfra?.value === 'docker')
+        result.push({
+            command: 'docker compose down',
+            why: 'stop the development database when you are done (docker compose up -d --wait starts it again)',
+        });
+    return result;
+}
+/** The lines to tell the user (RecipeOutcome.report). */
+function report(catalog, answers, answersFrom, plan) {
+    const lines = [];
+    const list = (by) => Object.entries(answers).filter(([, item]) => item.answeredBy === by);
+    const defaults = list('default');
+    if (defaults.length)
+        lines.push(`Chosen by default (tell the user): ${defaults
+            .map(([id, item]) => `${id}=${item.value} (${item.defaultReason})`)
+            .join('; ')}`);
+    const given = list('flag')
+        .map(([id, item]) => `${id}=${item.value}`)
+        .join(', ');
+    if (given)
+        lines.push(answersFrom === 'user'
+            ? `Answers from the user: ${given}`
+            : answersFrom === 'defaults'
+                ? `Chosen by you while the user left the choice to you (tell the user): ${given}`
+                : `Answers not yet confirmed (${given}): apply needs --answers-from user (only answers the user gave) or --defaults (only when the user said to decide)`);
+    lines.push(...notices(catalog, plan));
+    return lines.join('\n');
+}
+/** What the user must know about the applied plan (in the report and `.dokebi/recipe.json`). */
+function notices(catalog, plan) {
+    return plan.some((step) => step.id === 'form-body')
+        ? [`HTML forms are on (dokebi-web.formBody=true). ${noCsrf(catalog)}`]
+        : [];
+}
+/** A dry run's first next step: the same command applied, with the answer source to state. */
+function applyStep(recipe, request, answersFrom) {
+    const flagOf = {
+        view: '--view',
+        db: '--db',
+        devInfra: '--dev-infra',
+        admin: '--admin',
+    };
+    const parts = [`npx dokebi recipe ${recipe.name}`];
+    if (request.dir !== undefined)
+        parts.push(`--dir ${JSON.stringify(request.dir)}`);
+    for (const [id, value] of Object.entries(request.answers))
+        parts.push(`${flagOf[id]} ${value}`);
+    if (request.port !== undefined)
+        parts.push(`--port ${request.port}`);
+    if (request.dbPort !== undefined)
+        parts.push(`--db-port ${request.dbPort}`);
+    if (answersFrom === 'defaults')
+        parts.push('--defaults');
+    else {
+        parts.push(`--answers-from ${answersFrom ?? 'user'}`);
+        // The user answered some questions and left the rest to you.
+        if (request.defaults)
+            parts.push('--defaults');
+    }
+    parts.push('--json');
+    return {
+        command: parts.join(' '),
+        why: answersFrom === undefined
+            ? 'apply this plan — only if the user gave these answers (--answers-from user); otherwise ask and end your turn'
+            : 'apply this plan (the same answers without --dry-run)',
+    };
+}
+/** `dokebi recipe <name> …`. */
+export async function runRecipe(request, project) {
+    const catalog = await loadCatalog();
+    const recipe = recipeOf(catalog, request.name);
+    const { answers, missing } = answer(catalog, recipe, request);
+    if (missing.length) {
+        const flags = recipe.questions
+            .filter((id) => !recipe.fixed?.[id])
+            .map((id) => `${choiceOf(catalog, id).flag} <${id}>`)
+            .join(' ');
+        return {
+            status: 'needs-answers',
+            recipe: recipe.name,
+            summary: recipe.summary,
+            questions: questions(catalog, recipe, answers),
+            missing,
+            next: `${ASK_AND_WAIT} Show every question with its options, pros/cons and the default with its reason. After the user answers: npx dokebi recipe ${recipe.name} ${flags} --answers-from user --dry-run --json, then the same without --dry-run. If the user said to decide: --defaults instead of the answers, and tell them the report.`,
+            waitForUser: true,
+        };
+    }
+    const answersFrom = request.answersFrom ?? (request.defaults ? 'defaults' : undefined);
+    // D-0065 §11 (AI-M02): an agent printed the questions and installed anyway. Applying needs the
+    // agent to say where the answers came from; it is recorded in the result (answersFrom, report).
+    if (!request.dryRun && answersFrom === undefined)
+        throw new CliError('ANSWERS_SOURCE_REQUIRED', 'Say where the answers came from: --answers-from user (the user answered these questions) or --defaults (the user said to decide). If the user has not answered yet, ask and end your turn.', {
+            phase: 'arguments',
+            details: {
+                answers: Object.fromEntries(Object.entries(answers).map(([id, item]) => [id, item.value])),
+                fix: `${ASK_AND_WAIT} Then run the same command with --answers-from user (or --defaults when the user left the choice to you).`,
+            },
+        });
+    const root = resolve(request.dir ?? process.cwd());
+    const current = await view(root);
+    let init = false;
+    if (!current) {
+        if (request.dir === undefined)
+            throw new CliError('NOT_A_PROJECT', 'The current folder is not a Dokebi project; pass --dir <new folder> (--dir . when this folder is empty) or run inside a project', { phase: 'arguments', details: { root } });
+        // A new folder, or an existing empty one (D-0065 §11: the same rule as dokebi init).
+        await initFolder(root);
+        init = true;
+    }
+    const port = request.port ?? recipe.web.port;
+    const plan = steps(catalog, recipe, answers, {
+        root,
+        project,
+        port,
+        ...(request.dbPort !== undefined ? { dbPort: request.dbPort } : {}),
+        init,
+        ...(request.dir !== undefined ? { dir: request.dir } : {}),
+    });
+    const checks = await preflight(root, answers, catalog, plan, port, request.dbPort, answersFrom === 'defaults');
+    const asks = portAsks(checks);
+    const base = {
+        recipe: recipe.name,
+        root,
+        answers,
+        answersFrom: answersFrom ?? null,
+        report: report(catalog, answers, answersFrom, plan),
+        plan: { steps: plan.map(({ id, command, why }) => ({ id, command, why })) },
+        preflight: checks,
+        nextSteps: [
+            ...(request.dryRun ? [applyStep(recipe, request, answersFrom)] : []),
+            ...nextSteps(catalog, recipe, answers, plan, port),
+        ],
+    };
+    const blocking = checks.filter((item) => item.severity === 'error');
+    if (request.dryRun)
+        return { status: 'planned', ...base, completedSteps: [], skippedSteps: [], ...asks };
+    if (blocking.length)
+        throw new CliError('PREFLIGHT_FAILED', blocking.map((item) => `${item.code}: ${item.message}`).join('; '), { details: { preflight: checks, plan: base.plan, ...asks }, phase: 'arguments' });
+    const completedSteps = [];
+    const skippedSteps = [];
+    for (const step of plan) {
+        if (await step.satisfied()) {
+            skippedSteps.push(step.id);
+            debug('recipe: step already satisfied', { step: step.id });
+            continue;
+        }
+        try {
+            await step.run();
+        }
+        catch (error) {
+            debug('recipe: step failed', { step: step.id, error: describeError(error) });
+            throw new CliError('RECIPE_STEP_FAILED', `Step ${step.id} failed: ${step.command}`, {
+                cause: error,
+                details: {
+                    failedStep: { id: step.id, command: step.command },
+                    completedSteps,
+                    skippedSteps,
+                    error: {
+                        code: error instanceof CliError ? error.code : 'INTERNAL_ERROR',
+                        message: error instanceof Error ? error.message : String(error),
+                        details: error instanceof CliError ? (error.details ?? null) : null,
+                    },
+                },
+            });
+        }
+        completedSteps.push(step.id);
+    }
+    // `dokebi verify` returns these as tellUser: the agent's final message must carry them (AI-M03).
+    await saveAppliedRecipe(root, {
+        recipe: recipe.name,
+        appliedAt: new Date().toISOString(),
+        answersFrom: answersFrom,
+        // In the recipe's question order, the order the user saw them in.
+        answers: Object.fromEntries(recipe.questions.flatMap((id) => (answers[id] ? [[id, answers[id]]] : []))),
+        notices: notices(catalog, plan),
+    });
+    return { status: 'applied', ...base, completedSteps, skippedSteps };
+}