@dokebi/cli 0.4.2 → 0.4.27

package/dist/recipe-site.js

@@ -0,0 +1,396 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AUTO_DOMAIN, devHost } from './dev-host.js';
+import { debug, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { exists, securePath } from './filesystem.js';
+import { MOVED_RECIPE_FILES } from './layout.js';
+import { provider, shell, view } from './recipe-step.js';
+/** Where older site recipes wrote the job worker; it keeps working (doctor LEGACY_LAYOUT). */
+export const LEGACY_SITE_WORKER_PATH = 'src/site-worker.ts';
+/** Process-level runtime wiring sits in src/infra/runtime, beside the cluster worker factory. */
+export const SITE_WORKER_PATH = MOVED_RECIPE_FILES[LEGACY_SITE_WORKER_PATH];
+/** The import specifier src/main.ts uses for a worker file under src/. */
+const fromMain = (path) => `./${path.slice('src/'.length)}`;
+/**
+ * The opening of SITE.md, the guide the recipe writes once (kept byte for byte, so a re-run finds
+ * the guide it wrote). Its conditions ("until connected", "needs … before verify") are how the
+ * scaffold starts. D-0137: it is no longer a recorded notice: the record holds the `{fact:site}`
+ * token and verify says what it finds; records written before keep this text and are read the
+ * same way (recipe-facts.ts recordedFact).
+ */
+export const SITE_NOTICE = 'Site scaffolding separates domains and auth realms. User lookup and login screens are app code: the generated auth extensions deny every login until connected to your user store. Admin and API routes require authentication. A job worker needs a configured NATS connection and a provisioned siteWorker queue before verify; the thread worker handles CPU tasks in this process.';
+/**
+ * The site's apps, domains, realms and worker. `label` is the project's host label (D-0102):
+ * `--domains auto` gives every app `<app>.<label>.localhost`, unique to this project.
+ */
+export function siteDefinition(answers, label) {
+    const apps = answers.apps?.value === 'none' ? [] : (answers.apps?.value ?? '').split(',');
+    const worker = answers.worker?.value ?? 'none';
+    if (!apps.length && worker === 'none')
+        throw new CliError('INVALID_ANSWER', 'Select at least one app or worker', {
+            phase: 'arguments',
+        });
+    const map = (id) => {
+        const raw = answers[id]?.value ?? '';
+        if (raw === AUTO_DOMAIN)
+            return Object.fromEntries(apps.map((app) => [app, id === 'domains' ? devHost(app, label) : app]));
+        const result = Object.create(null);
+        if (!apps.length && raw === 'none')
+            return result;
+        for (const pair of raw.split(',')) {
+            const [app, value, extra] = pair.split('=');
+            const valid = id === 'domains'
+                ? /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/
+                : /^[a-z][a-z0-9-]{0,31}$/;
+            if (!app ||
+                !apps.includes(app) ||
+                !value ||
+                extra !== undefined ||
+                !valid.test(value) ||
+                Object.hasOwn(result, app))
+                throw new CliError('INVALID_ANSWER', `--${id} requires one app=value pair for each selected app`, { phase: 'arguments' });
+            result[app] = value;
+        }
+        if (apps.some((app) => !Object.hasOwn(result, app)) ||
+            (id === 'domains' && new Set(Object.values(result)).size !== apps.length))
+            throw new CliError('INVALID_ANSWER', `--${id} has missing apps or duplicate domains`, {
+                phase: 'arguments',
+            });
+        return Object.fromEntries(apps.map((app) => [app, result[app]]));
+    };
+    return {
+        apps,
+        worker,
+        domains: map('domains'),
+        realms: map('realms'),
+        inertia: answers.view?.value.startsWith('inertia-') ?? false,
+        ssr: answers.view?.value === 'inertia-vue-ssr',
+    };
+}
+export async function checkSite(root, answers, label) {
+    const expected = JSON.stringify(siteDefinition(answers, label), null, 2) + '\n';
+    const path = join(root, '.dokebi/site-plan.json');
+    if (await exists(path)) {
+        if ((await readFile(path, 'utf8')) !== expected)
+            throw new CliError('RECIPE_FILE_CONFLICT', 'This site has different app/domain/realm/worker choices; change it explicitly instead of applying another site plan', { phase: 'arguments' });
+    }
+    else if ((await view(root))?.apps.length)
+        throw new CliError('RECIPE_FILE_CONFLICT', 'The site recipe requires a new project or a project without existing apps', { phase: 'arguments' });
+}
+/** The auth extension the site recipe writes: one stub class per realm (exported for its tests). */
+export function siteAuthSource(realms) {
+    return `import { AuthExtension, type AuthHookContext, type AuthUser } from '@dokebi/auth';
+interface Account { id: string; passwordHash: string; stamp: string; roles: string[] }
+// Connect each realm to its user store. Empty lookup intentionally denies login.
+class SiteAuth extends AuthExtension<Account> {
+  protected override findByIdentity(_identity: string, context: AuthHookContext): Account | undefined {
+    if (context.logger.isEnabled('debug')) context.logger.log('debug', 'Site user store is not configured', { code: 'SITE_AUTH_UNCONFIGURED', realm: context.realm });
+    return undefined;
+  }
+  protected override findById(_id: string, context: AuthHookContext): Account | undefined {
+    if (context.logger.isEnabled('debug')) context.logger.log('debug', 'Site user store is not configured', { code: 'SITE_AUTH_UNCONFIGURED', realm: context.realm });
+    return undefined;
+  }
+  protected override credentials(account: Account): AuthUser { return { id: account.id, passwordHash: account.passwordHash, stamp: account.stamp, roles: account.roles }; }
+}
+export default class DefaultAuth extends SiteAuth {}
+${realms
+        .filter((name) => name !== 'default')
+        .map((_, i) => `class Realm${i} extends SiteAuth {}`)
+        .join('\n')}
+export const realms = { ${realms
+        .filter((name) => name !== 'default')
+        .map((name, i) => `${JSON.stringify(name)}: Realm${i}`)
+        .join(', ')} };
+`;
+}
+/** What the site scaffold's GET /login answers until the app writes its login (verify reads it). */
+export const SITE_LOGIN_HINT = 'Connect the realm extension to your user store and implement login with request.auth.attempt.';
+/** The routes file of a site app (the scaffold's GET /login lives there). */
+export const siteRoutesPath = (app) => `src/apps/${app}/site-routes.ts`;
+function routesSource(app, realm) {
+    return `import type { AppContext, AppRouter } from '@dokebi/app';
+${app === 'api' ? '' : "import { routes as pages } from './routes.ts';"}
+export function siteRoutes(route: AppRouter, app: AppContext): void {
+  ${app === 'api' ? `route.get('/', async (request) => ({ app: 'api', authenticated: Boolean(await request.auth.user()) }));` : 'pages(route, app);'}
+  route.get('/login', () => ({ message: ${JSON.stringify(SITE_LOGIN_HINT)}, realm: ${JSON.stringify(realm)} }), { config: { auth: false } });
+  route.get('/identity', async (request) => ({ authenticated: Boolean(await request.auth.user()), realm: ${JSON.stringify(realm)} }), { config: { auth: 'required' } });
+}
+`;
+}
+const JOB_SOURCE = `import type { Plugin } from '@dokebi/core';
+import { dependency as job } from '@dokebi/job';
+// Process wiring for the siteWorker queue; register feature handlers in the setup of the module
+// that owns the feature (src/shared/modules/<module>/module.ts) and call its services.
+export const siteWorker: Plugin<void> = {
+  metadata: { name: 'site-worker', version: '1.0.0', core: '^0.4.0', dependencies: [job] },
+  setup(context) {
+    context.logger.log('debug', 'Registering site worker handler');
+    const queue = context.getDependency(job).queue('siteWorker');
+    queue.handle('site.example', async (_payload, task) => {
+      // Replace with idempotent business work; a job may be delivered more than once.
+      context.logger.log('debug', 'Processing site example job', { id: task.id, attempt: task.attempt });
+    });
+  },
+};
+`;
+/** SITE.md: what the recipe chose and what remains application work. */
+function siteGuide(spec, workerPath) {
+    return `# Site\n\n${SITE_NOTICE}\n\nApps: ${spec.apps.join(', ') || 'none'}. Worker: ${spec.worker}.\n\n${spec.apps.map((app) => `- ${app}: ${spec.domains[app]}, realm ${spec.realms[app]}`).join('\n')}\n\nDomain mapping does not change DNS: \`*.localhost\` names reach this machine without a hosts file; add other local names to your hosts file or use a proxy.\nSession cookies are host-only; sharing a realm does not automatically share login cookies. The default hosts (\`--domains auto\`) carry the project name, so another Dokebi project on this machine never shares their cookies.\nFor a job worker configure options.dokebi-nats.connections.siteWorker.servers in private dokebi.yaml, then run npx dokebi-job-provision --queue siteWorker before npx dokebi verify --json. The example handler is site.example in ${workerPath}; replace it with idempotent business work. It runs in this process, not a separately deployed service.\nFor a thread worker edit src/infra/worker/tasks.ts and call the worker provider from your own plugin; no public task endpoint is generated.\n`;
+}
+/**
+ * A browser app of the site (not api): its host is sealed (D-0092 §1, D-0062), EJS and Inertia
+ * alike. Server rendering cannot be sealed (SEAL_SSR_CONFLICT), so SSR apps stay plain and the
+ * recipe notice says so.
+ */
+export function sealedSiteApp(spec, app) {
+    return app !== 'api' && !spec.ssr;
+}
+/** Site reuses transactional install/app/config/file commands and the common recipe executor. */
+export function siteSteps(catalog, _recipe, answers, context) {
+    const { root, project } = context;
+    const spec = siteDefinition(answers, context.hostLabel);
+    const steps = [];
+    if (context.init)
+        steps.push({
+            id: 'init',
+            command: `npx -y @dokebi/cli init ${JSON.stringify(root)}`,
+            why: 'create the site project',
+            satisfied: async () => !!(await view(root)),
+            run: async () => {
+                await project.init(root);
+            },
+        });
+    const logger = provider(catalog, 'logging.targets');
+    steps.push({
+        id: 'logger-plugin',
+        command: `npx dokebi add ${logger}`,
+        why: 'the app logger (D-0151): JSON lines on stdout, readable lines in dokebi dev, redaction, and a rotating file target to turn on in production; init adds it, this step adds it to an older project',
+        satisfied: async () => (await view(root))?.packages.has(logger) ?? false,
+        run: async () => {
+            await project.add(root, logger);
+        },
+    });
+    steps.push({
+        id: 'site-plan',
+        command: 'recipe: record site choices',
+        why: 'resume the same plan without taking over existing apps',
+        satisfied: async () => false,
+        run: async () => {
+            await project.writeRecipeFiles(root, {
+                files: [{ path: '.dokebi/site-plan.json', content: JSON.stringify(spec, null, 2) + '\n' }],
+            });
+        },
+    });
+    const add = (capability, id, firstApp, sets = []) => {
+        const name = provider(catalog, capability);
+        steps.push({
+            id,
+            command: `npx dokebi add ${name}${firstApp === false ? ' --no-first-app' : ''}`,
+            why: `install ${capability}`,
+            satisfied: async () => (await view(root))?.packages.has(name) ?? false,
+            run: async () => {
+                await project.add(root, name, false, sets, {
+                    ...(firstApp === undefined ? {} : { firstApp }),
+                });
+            },
+        });
+    };
+    // Browser apps are sealed (the consumer convention, D-0092 §1, D-0062): their hosts get
+    // seal: true. EJS forms go through @dokebi/seal/forms (the shared layout writes the seal head);
+    // Inertia pages and visits through the sealInertia bootstrap of views/app.js. The api app
+    // answers API clients, and SSR apps cannot be sealed (SEAL_SSR_CONFLICT): both stay plain.
+    const sealed = (app) => sealedSiteApp(spec, app);
+    if (spec.apps.length) {
+        add('web.apps', 'apps-plugin', false);
+        if (spec.inertia && spec.apps.some((app) => app !== 'api'))
+            add(`view.${answers.view?.value}`, 'view-plugin');
+        add('web.session', 'session');
+        add('csrf', 'csrf');
+        add('auth', 'auth');
+        if (spec.apps.some(sealed))
+            add('security.seal', 'seal');
+        for (const app of spec.apps)
+            steps.push({
+                id: `app-${app}`,
+                command: `npx dokebi app add ${app} --domain ${spec.domains[app]}${spec.inertia && app !== 'api' ? ` --inertia${spec.ssr ? ' --ssr' : ''}` : ''}${sealed(app) ? ' --seal' : ''}`,
+                why: `separate ${app} domain and realm${sealed(app) ? ' (a sealed browser host)' : ''}`,
+                satisfied: async () => (await view(root))?.apps.includes(app) ?? false,
+                run: async () => {
+                    await project.appAdd(root, app, {
+                        domains: [spec.domains[app]],
+                        inertia: spec.inertia && app !== 'api',
+                        ssr: spec.ssr && app !== 'api',
+                        seal: sealed(app),
+                    });
+                },
+            });
+    }
+    if (spec.worker === 'thread')
+        add('worker.thread', 'worker');
+    if (spec.worker === 'job') {
+        add('messaging.nats', 'nats', undefined, [
+            {
+                path: ['connections', 'siteWorker'],
+                value: { servers: ['nats://configure-me.invalid:4222'] },
+            },
+        ]);
+        add('job.durable', 'worker', undefined, [
+            {
+                path: ['queues', 'siteWorker'],
+                value: {
+                    connection: 'siteWorker',
+                    stream: 'SITE_WORK',
+                    consumer: 'SITE_WORKER',
+                    subject: 'site.work',
+                    deadLetterStream: 'SITE_DEAD',
+                    deadLetterSubject: 'site.dead',
+                },
+            },
+        ]);
+    }
+    steps.push({
+        id: 'site-files',
+        command: 'recipe: write site realm extensions and route/worker entries',
+        why: 'safe starting points; application user stores and login screens remain explicit',
+        satisfied: async () => false,
+        run: async () => {
+            const files = [];
+            const edits = [];
+            if (spec.apps.length)
+                files.push({
+                    path: 'src/infra/auth/extension.ts',
+                    content: siteAuthSource([...new Set(Object.values(spec.realms))]),
+                    replaceTemplate: true,
+                });
+            for (const app of spec.apps) {
+                files.push({
+                    path: siteRoutesPath(app),
+                    content: routesSource(app, spec.realms[app]),
+                });
+                edits.push({
+                    path: `src/apps/${app}/app.ts`,
+                    edit(text) {
+                        const next = "import { siteRoutes as routes } from './site-routes.ts';";
+                        if (text.includes(next))
+                            return text;
+                        const previous = "import { routes } from './routes.ts';";
+                        if (!text.includes(previous))
+                            throw new CliError('RECIPE_FILE_CONFLICT', `src/apps/${app}/app.ts has custom routing`);
+                        return text.replace(previous, next);
+                    },
+                });
+            }
+            // A project made by an older site recipe keeps its worker at the src root: the re-run
+            // writes no second copy and keeps SITE.md naming it; doctor reports LEGACY_LAYOUT.
+            const legacy = spec.worker === 'job' && (await exists(await securePath(root, LEGACY_SITE_WORKER_PATH)));
+            const workerPath = legacy ? LEGACY_SITE_WORKER_PATH : SITE_WORKER_PATH;
+            if (legacy)
+                debug('Site recipe keeps the legacy worker path', {
+                    path: LEGACY_SITE_WORKER_PATH,
+                    moveTo: SITE_WORKER_PATH,
+                });
+            if (spec.worker === 'job') {
+                if (!legacy)
+                    files.push({ path: SITE_WORKER_PATH, content: JOB_SOURCE });
+                edits.push({
+                    path: 'src/main.ts',
+                    edit(text) {
+                        if (text.includes('app.register(siteWorker);'))
+                            return text;
+                        if (!text.includes('await app.start();'))
+                            throw new CliError('RECIPE_FILE_CONFLICT', 'src/main.ts has a custom lifecycle');
+                        return (`import { siteWorker } from '${fromMain(workerPath)}';\n` +
+                            text.replace('await app.start();', 'app.register(siteWorker);\nawait app.start();'));
+                    },
+                });
+            }
+            // SITE.md as an older recipe wrote it (naming the old worker path) is kept as it is.
+            let guide;
+            try {
+                guide = await readFile(await securePath(root, 'SITE.md'), 'utf8');
+            }
+            catch (error) {
+                // A missing SITE.md is the first run; any other read failure stops the step.
+                if (!isMissing(error))
+                    throw error;
+            }
+            const legacyGuide = siteGuide(spec, LEGACY_SITE_WORKER_PATH);
+            files.push({
+                path: 'SITE.md',
+                content: guide === legacyGuide ? legacyGuide : siteGuide(spec, workerPath),
+            });
+            await project.writeRecipeFiles(root, { files, edits });
+        },
+    });
+    steps.push({
+        id: 'site-config',
+        command: 'recipe: configure app domains, realms and worker resources',
+        why: 'apply selected isolation settings; never create credentials for an external server',
+        satisfied: async () => false,
+        run: async () => {
+            const sets = [];
+            if (spec.apps.length) {
+                sets.push({ plugin: 'dokebi-web', set: { path: ['port'], value: context.port } });
+                // Sealed EJS forms are form bodies (dokebi-web refuses them while formBody is off).
+                if (!spec.inertia && spec.apps.some(sealed))
+                    sets.push({ plugin: 'dokebi-web', set: { path: ['formBody'], value: true } });
+                for (const app of spec.apps) {
+                    sets.push({
+                        plugin: 'dokebi-auth',
+                        set: {
+                            path: ['apps', app],
+                            value: {
+                                realm: spec.realms[app],
+                                default: app === 'web' ? 'optional' : 'required',
+                                loginPath: '/login',
+                                homePath: '/',
+                                via: app === 'api' ? 'any' : 'session',
+                            },
+                        },
+                    });
+                }
+            }
+            if (spec.worker === 'job') {
+                const current = await view(root);
+                const nats = current?.options['dokebi-nats'];
+                const job = current?.options['dokebi-job'];
+                if (!nats?.connections?.siteWorker)
+                    sets.push({
+                        plugin: 'dokebi-nats',
+                        set: {
+                            path: ['connections', 'siteWorker'],
+                            value: { servers: ['nats://configure-me.invalid:4222'] },
+                        },
+                    });
+                if (!job?.queues?.siteWorker)
+                    sets.push({
+                        plugin: 'dokebi-job',
+                        set: {
+                            path: ['queues', 'siteWorker'],
+                            value: {
+                                connection: 'siteWorker',
+                                stream: 'SITE_WORK',
+                                consumer: 'SITE_WORKER',
+                                subject: 'site.work',
+                                deadLetterStream: 'SITE_DEAD',
+                                deadLetterSubject: 'site.dead',
+                            },
+                        },
+                    });
+            }
+            if (sets.length)
+                await project.configSet(root, sets);
+        },
+    });
+    if (spec.inertia && spec.apps.some((app) => app !== 'api'))
+        steps.push({
+            id: 'build',
+            command: 'npm run build',
+            why: 'build selected Vue apps and SSR bundles',
+            satisfied: async () => false,
+            run: () => shell(root, 'npm', ['run', 'build'], 300000),
+        });
+    return steps;
+}

package/dist/recipe-step.d.ts

@@ -0,0 +1,42 @@
+import { type Catalog } from './catalog.js';
+/**
+ * Who settled an answer (D-0095): `user` — the user or the request named it; `ai` — the user left
+ * it to the agent, which chose it (`--ai-chose`, with `aiReason` from `--ai-reason`); `default` —
+ * left to the agent and filled with the catalog default (`defaultReason`); `recipe` — fixed by the
+ * recipe, not a question.
+ */
+export type AnsweredBy = 'user' | 'ai' | 'default' | 'recipe';
+export interface Answer {
+    readonly value: string;
+    readonly answeredBy: AnsweredBy;
+    readonly defaultReason?: string;
+    readonly aiReason?: string;
+}
+export interface PlanStep {
+    readonly id: string;
+    /** The real command (run it yourself to do the same step). */
+    readonly command: string;
+    readonly why: string;
+}
+export interface Step extends PlanStep {
+    satisfied(): Promise<boolean>;
+    run(): Promise<void>;
+}
+/** The plugin package that provides a capability (the recipe never names packages). */
+export declare function provider(catalog: Catalog, capability: string): string;
+export interface ProjectView {
+    installed: Set<string>;
+    packages: Set<string>;
+    apps: string[];
+    modules: string[];
+    options: Record<string, unknown>;
+}
+/** The project as the steps see it now; undefined while the folder is not a project yet. */
+export declare function view(root: string): Promise<ProjectView | undefined>;
+/**
+ * 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). The command runs in its own process
+ * group, which the time limit kills whole: killing npm alone left `npm run build`'s Vite running,
+ * and the pipes it holds kept the step open long after the limit.
+ */
+export declare function shell(root: string, command: string, args: string[], timeoutMs: number): Promise<void>;

package/dist/recipe-step.js

@@ -0,0 +1,89 @@
+// What every recipe step builder shares (recipe.ts, recipe-site.ts, recipe-mail.ts): the step
+// and answer shapes, the project as the steps see it, the capability → package lookup and the
+// command runner. It imports none of the recipe modules, so they never import each other for it.
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { providersOf } from './catalog.js';
+import { parseProjectConfig, readProjectSettings } from './configuration.js';
+import { debug, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { OutputTail } from './npm-client.js';
+import { forwardTermination, killGroup, PROCESS_GROUPS } from './process-group.js';
+/** The plugin package that provides a capability (the recipe never names packages). */
+export 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 project as the steps see it now; undefined while the folder is not a project yet. */
+export 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);
+    // M50: the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml).
+    const options = parseProjectConfig((await readProjectSettings(root)).source).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,
+    };
+}
+/**
+ * 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). The command runs in its own process
+ * group, which the time limit kills whole: killing npm alone left `npm run build`'s Vite running,
+ * and the pipes it holds kept the step open long after the limit.
+ */
+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'],
+            detached: PROCESS_GROUPS,
+        });
+        const forwarding = forwardTermination(child.pid);
+        const output = new OutputTail();
+        const keep = (chunk) => output.push(chunk);
+        child.stdout.on('data', keep);
+        child.stderr.on('data', keep);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            debug('recipe: the step command reached its time limit; killing it', { command, timeoutMs });
+            killGroup(child.pid, 'SIGKILL');
+        }, timeoutMs);
+        child.once('error', (cause) => {
+            clearTimeout(timer);
+            forwarding();
+            fail(new CliError('STEP_COMMAND_FAILED', `${command} could not run`, { cause }));
+        });
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            forwarding();
+            if (code === 0)
+                done();
+            else
+                fail(new CliError('STEP_COMMAND_FAILED', `${command} ${args.join(' ')} failed`, {
+                    details: { exitCode: code, signal, timedOut, output: output.text() },
+                }));
+        });
+    });
+}

package/dist/recipe.d.ts

@@ -1,5 +1,8 @@
-import { type CatalogOption } from './catalog.js';
+import { type Catalog, type CatalogOption, type CatalogRecipe } from './catalog.js';
 import { type NextStep, type Project } from './project.js';
+import { type Answer, type PlanStep } from './recipe-step.js';
+export { csrfNotice, SEAL_HEAD, SEAL_HTTP_MODULE, sealNotice, ssrSealNotice, } from './recipe-facts.js';
+export type { Answer, PlanStep, ProjectView, Step } from './recipe-step.js';
 export interface RecipeRequest {
     readonly name: string;
     /** Project folder; created with init when it does not exist yet. Default: the current one. */
@@ -9,10 +12,18 @@ export interface RecipeRequest {
     /** Fill unanswered questions with their defaults (only when the user delegated the choice). */
     readonly defaults: boolean;
     /**
-     * Where the answers came from (D-0065 §11): `user` — the user answered the questions;
-     * `defaults` — the user said to decide (same as `defaults`). Applying needs one of them.
+     * Where the answers came from (D-0065 §11): `user` — the given answers are the user's (or the
+     * request's explicit) choices, except those named in `aiChose`; `defaults` — the user said to
+     * decide everything (same as `defaults`; every given answer is the agent's). Applying needs one.
      */
     readonly answersFrom?: 'user' | 'defaults';
+    /**
+     * D-0095: the question ids (or flag names) of given answers the agent chose itself because the
+     * user left them to it. Each needs its flag; a question the recipe fixes cannot be one.
+     */
+    readonly aiChose?: readonly string[];
+    /** D-0095: the agent's one-line reason per id of `aiChose` (optional, 1–200 characters). */
+    readonly aiReasons?: Readonly<Record<string, string>>;
     readonly dryRun: boolean;
     readonly port?: number;
     readonly dbPort?: number;
@@ -28,23 +39,13 @@ export interface Question {
     readonly flag: string;
     readonly question: string;
     readonly options: readonly QuestionOption[];
+    readonly input?: 'text';
     readonly default: string;
     readonly defaultReason: string;
     /** Asked only when another answer matches (devInfra: when db is not none). */
     readonly when?: Readonly<Record<string, string>>;
     readonly answer?: Answer;
 }
-export interface Answer {
-    readonly value: string;
-    readonly answeredBy: 'flag' | 'default' | 'recipe';
-    readonly defaultReason?: string;
-}
-export interface PlanStep {
-    readonly id: string;
-    /** The real command (run it yourself to do the same step). */
-    readonly command: string;
-    readonly why: string;
-}
 export interface Preflight {
     readonly code: string;
     readonly severity: 'error' | 'info';
@@ -68,11 +69,11 @@ export interface NeedsAnswers {
     readonly missing: readonly string[];
     /** What to do now (D-0065 §11): ask, end the turn, and only then run the command. */
     readonly next: string;
+    /** D-0098: what the recipe does not build (the api recipe: no browser screens), for the AI. */
+    readonly notice?: string;
     /** Always true: the agent's turn ends with the questions; nothing runs before the answers. */
     readonly waitForUser: true;
 }
-/** The first sentence of `next` (and of the guide and AGENTS.md §1), word for word. */
-export declare 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.";
 export interface RecipeOutcome {
     readonly status: 'planned' | 'applied';
     readonly recipe: string;
@@ -82,12 +83,15 @@ export interface RecipeOutcome {
     readonly answersFrom: 'user' | 'defaults' | null;
     /**
      * Tell the user (one line each): the answers and who gave them, defaults with their reasons,
-     * and what the app does not protect (no CSRF protection for HTML forms, csrf is absent).
+     * and what to know: how forms send the CSRF token, where the admin login and its first
+     * password are (D-0076 §6).
      */
     readonly report: string;
     readonly plan: {
         readonly steps: readonly PlanStep[];
     };
+    /** D-0098: what the recipe does not build (the api recipe: no browser screens), for the AI. */
+    readonly notice?: string;
     readonly preflight: readonly Preflight[];
     readonly completedSteps: readonly string[];
     readonly skippedSteps: readonly string[];
@@ -100,6 +104,24 @@ export interface RecipeOutcome {
     readonly question?: string;
     readonly next?: string;
 }
+/**
+ * D-0098: a recipe that builds no browser screens (`screens: false`, the api recipe) answers the
+ * view with `none`. It is not a question (the recipe is the choice) and not a value the recipe
+ * fixes: who chose no screens is recorded like an answer, the user's unless the AI names `view`
+ * in `--ai-chose` (or the user left every choice to it), and verify's tellUser says it. Its app
+ * skeleton (the first app, which `add @dokebi/app` writes) has an EJS home page, but no screens
+ * for people. An app added later with `app add` inherits view none (no views, a JSON API) unless
+ * it says `--view ejs` or `--inertia` (M50).
+ */
+export declare const SCREENS = "view";
+/** The view answer of a recipe without browser screens. */
+export declare const NO_SCREENS = "none";
+/** The recipes that ask the view (blog, site): where a service people use in a browser goes. */
+export declare function screenRecipes(catalog: Catalog): string[];
+/** What a recipe without screens tells the AI before and after planning (D-0098). */
+export declare function noScreensNotice(recipe: string, browserRecipes: readonly string[]): string;
+/** The recorded notice of a recipe without screens: verify's tellUser tells the user (D-0098). */
+export declare function noScreensRecord(recipe: string, browserRecipes: readonly string[]): string;
 /** `dokebi recipe list`. */
 export declare function listRecipes(): Promise<{
     recipes: {
@@ -112,9 +134,23 @@ export declare function listRecipes(): Promise<{
 /** The devInfra docker note when `docker` is not on PATH (the default stays; the user decides). */
 export declare 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)";
 /**
- * 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).
+ * The tellUser line of `--admin login`: where to sign in and where the first password is.
+ * `appUrl` is the app's `<scheme>://<domain>:<port>`, or APP_URL_PLACEHOLDER in the recipe record
+ * (verify fills in the address of the moment, AI-M05). `firstAdmin` is firstAdminPhrase, or
+ * FIRST_ADMIN_PLACEHOLDER in the record: verify reads the login and the section from the project
+ * as it is then (D-0115: the builder may rename the section or sign the admin in by email).
+ */
+export declare function loginNotice(appUrl: string, devInfra: string | undefined, firstAdmin?: string): string;
+/**
+ * The hosts of a blog/api plan (D-0102): the recipe's `web.domain` is `auto`, the project's own
+ * development hosts `main.<label>.localhost` and `admin.<label>.localhost`, so two projects on one
+ * machine never share cookies. A recipe naming a domain keeps it (admin then on `admin.<domain>`).
+ * An app that already exists keeps the first domain dokebi.yaml maps to it (`options`), so a plan
+ * applied again to an older project (main on `localhost`) seals and links the host it really has.
  */
-export declare function shell(root: string, command: string, args: string[], timeoutMs: number): Promise<void>;
+export declare function recipeHosts(recipe: Pick<CatalogRecipe, 'web'>, label: string, options?: Record<string, unknown>): {
+    readonly main: string;
+    readonly admin: string;
+};
 /** `dokebi recipe <name> …`. */
 export declare function runRecipe(request: RecipeRequest, project: Project): Promise<NeedsAnswers | RecipeOutcome>;