@dokebi/cli 0.4.2 → 0.4.27

package/dist/verify.js

@@ -1,5 +1,6 @@
 // `dokebi verify` (D-0065): the one check an AI runs before it says "done". doctor → check
-// (D-0072, user-code conventions) → typecheck → build (Vite projects) → preflight → start →
+// (D-0072, user-code conventions) → typecheck → build (Vite projects) → test (the project's
+// `test` script, a result per node:test test: D-0077 H, verify-tests.ts) → preflight → start →
 // HTTP checks → stop; `ok` only when every check that ran passed. The app it starts is always
 // stopped again.
 //
@@ -16,20 +17,127 @@ import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { appUrls } from './app-urls.js';
 import { check } from './check/index.js';
-import { CONFIG_FILE, parseProjectConfig } from './configuration.js';
-import { portInUse, URL_PLACEHOLDER_PREFIX } from './dev-infra.js';
-import { debug, describeError } from './diagnostics.js';
+import { CONFIG_FILE, configTarget, FRESH_COPY_FIX, parseProjectConfig, readNamedSettings, } from './configuration.js';
+import { freePortAfter, portInUse, portQuestion, URL_PLACEHOLDER_PREFIX } from './dev-infra.js';
+import { debug, describeError, isMissing, reportError } from './diagnostics.js';
+import { envFileWarnings } from './env-file.js';
 import { CliError } from './errors.js';
 import { exists, parseObject, securePath } from './filesystem.js';
+import { firstAdminPhrase, readFirstAdmin } from './first-admin.js';
 import { findHost } from './manifest.js';
 import { OutputTail } from './npm-client.js';
+import { forwardTermination, killGroup, PROCESS_GROUPS } from './process-group.js';
 import { ProjectInspector } from './project-inspector.js';
 import { readState } from './project-state.js';
-import { readAppliedRecipes, tellUserLines } from './recipe-record.js';
+import { factOf, factTexts, readProjectFacts } from './recipe-facts.js';
+import { namesFirstAdmin, readAppliedRecipes, readRecordedChoices, TELL_USER_RELAY, tellUserLines, } from './recipe-record.js';
 import * as server from './server.js';
+import { probeUserStores } from './site-auth.js';
+import { runTests, TEST_TIMEOUT_MS } from './verify-tests.js';
+/**
+ * D-0105 §4: with @dokebi/db installed, what the agent's final message must contain besides
+ * tellUser. The guidance asks for it, and an AI consumer that read it many times still left it
+ * out (AI-M23, AI-M24): verify ok repeats it at the moment the agent is about to report.
+ */
+export function finalReportLines(ok, installed, allowed = []) {
+    if (!ok)
+        return [];
+    return [
+        ...(installed.has('dokebi-db') ? [DB_PRACTICE_REPORT] : []),
+        ...(allowed.length ? [allowedReport(allowed)] : []),
+    ];
+}
+/** The opening of the silenced-rules report and the words before its list of markers. */
+const SILENCED = 'Silenced check rules: ';
+const LISTED = 'why the rule does not apply there: ';
+/**
+ * R1 measurement: a builder printed only `{ ok, checks, tests, tellUser }` of the verify JSON and
+ * never saw `finalReport`, so its final message lacked the section 6 table. The tellUser lines,
+ * which every builder relays, end with what finalReport asks for (the field stays as it is).
+ */
+export function tellUserWithReport(tellUser, finalReport, dbRules = []) {
+    if (!tellUser.length || !finalReport.length)
+        return [...tellUser];
+    // R1 T5 review: the lines are relayed verbatim (relay), so each is said to the user: a heading
+    // the builder's table or list follows, never an instruction to the builder.
+    // R3 Codex T2: Codex reads only ok, checks and tellUser of the result (never relay or
+    // finalReport) and put the table in a file for the fifth time; the heading itself says where
+    // the table is, in words the user reads as a plain statement.
+    return [
+        ...tellUser,
+        ...finalReport.map((line) => line === DB_PRACTICE_REPORT
+            ? `Database practice (@dokebi/db AI.md section 6): the table below, here in this message, has one row per rule of that section (${dbRules.length ? dbRules.join('; ') : 'each by its number, 6.1 onwards'}), with the queries or jobs it applies to, the measurement (rows read, rate, refusals) and the verdict (pass, or the fix you made).`
+            : line.startsWith(SILENCED)
+                ? `Silenced check rules (dokebi-check allow markers), each followed below, here in this message, by why the rule does not apply there: ${line.slice(line.indexOf(LISTED) + LISTED.length).replace(/\. A marker on work[\s\S]*$/, '')}.`
+                : line),
+    ];
+}
+/**
+ * R6 Codex T3: the heading said "one row per rule" and the builder, which reads only tellUser of
+ * the result and had read part of section 6, wrote a table of twelve rules of its own. The
+ * heading names the rules of the installed @dokebi/db AI.md (`### 6.N Title`), so each row has
+ * one to answer. No installed AI.md: none.
+ */
+export async function readDbPracticeRules(root) {
+    let text;
+    try {
+        text = await readFile(join(root, 'node_modules', '@dokebi', 'db', 'AI.md'), 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        debug('verify: no @dokebi/db AI.md for the section 6 rules', { root });
+        return [];
+    }
+    return [...text.matchAll(/^### (6\.\d+ .+)$/gm)].map((match) => (match[1] ?? '').trim());
+}
+/**
+ * M34: a builder silenced background-timer on a database polling loop and check passed. verify ok
+ * asks the final message to list every silenced problem with its reason, so the person reading it
+ * sees each one (the markers stay legitimate for per-process upkeep).
+ */
+export function allowedReport(allowed) {
+    const listed = allowed
+        .slice(0, 20)
+        .map((marker) => `${marker.file}:${marker.line} ${marker.rule} (${marker.reason})`)
+        .join('; ');
+    const more = allowed.length > 20 ? `; and ${allowed.length - 20} more (npx dokebi check)` : '';
+    return `${SILENCED}your final message lists every dokebi-check allow marker of the project with its reason and ${LISTED}${listed}${more}. A marker on work that reads or writes the database (a polling or folding loop) is not a valid reason: move that work to a job or an outbox handler.`;
+}
+/**
+ * R2 Codex T2, T4, T5 (and R1 T1, T2): the builder relayed the headings verbatim, "the table below
+ * …", and put the table in a results file; it reads relay and tellUser, not finalReport. With
+ * finalReport lines, relay itself says that each heading's table or list follows it in the message.
+ * R4 Claude T4 copied the other lines and wrote its own headings for these two (`## Database
+ * practice (…)`): relay called them "a heading". They are lines to copy like the others.
+ */
+export const REPORT_RELAY = Object.freeze({
+    tellUser: 'verbatim',
+    instruction: `${TELL_USER_RELAY.instruction} The lines that start with Database practice and Silenced check rules are copied word for word too (they are lines of this list, not headings to write in your own words), and right under each of them you write the table or list it announces, in the same final message, as finalReport says; a results file or a link to one does not replace it.`,
+});
+export const DB_PRACTICE_REPORT = 'Database practice (@dokebi/db is installed): your final message contains a table with one row per rule of section 6 of node_modules/@dokebi/db/AI.md: the rule, the queries or jobs it applies to, the measurement (rows read, rate, refusals) and the verdict (pass, or the fix you made). A rule you did not measure is not done; a separate results file does not replace the table in the message.';
+/**
+ * The preflight problem for a taken web port (AI-M04 F5), with what the recipe preflight gives:
+ * a free `alternative`, `waitForUser`, `question` and `next`. Who holds the port is not looked up
+ * (no `ps`); verify only knows it is not an app `dokebi start` runs for this project (that is
+ * ALREADY_RUNNING). `delegated`: the last recipe ran with --defaults (`.dokebi/recipe.json`).
+ */
+export async function webPortProblem(port, delegated) {
+    const alternative = await freePortAfter(port);
+    debug('verify: web port in use', { port, alternative, delegated });
+    return {
+        code: 'PORT_IN_USE',
+        message: `Port ${port} (options.dokebi-web.port) is in use by another program (not an app npx dokebi start runs for this project; maybe its npx dokebi dev, another project or another program)`,
+        fix: `ask the user, then npx dokebi config set dokebi-web.port=${alternative ?? '<free port>'} and verify again, or stop what uses ${port}`,
+        ...(alternative ? { alternative } : {}),
+        ...portQuestion({ what: 'Web', port, alternative, flag: 'dokebi-web.port', delegated }),
+    };
+}
 /**
  * Runs an npm script of the project; resolves with its exit code and the bounded, redacted end
- * of its output (stdout and stderr in arrival order, `OutputTail` of npm-client).
+ * of its output (stdout and stderr in arrival order, `OutputTail` of npm-client). The script runs
+ * in its own process group and the time limit kills the whole group: killing npm alone left tsc
+ * or Vite running, and the pipes they hold kept the step open until they ended by themselves.
  */
 export async function npmScript(root, script, timeoutMs) {
     const npmPath = process.env.npm_execpath;
@@ -37,7 +145,12 @@ export async function npmScript(root, script, timeoutMs) {
     const args = [...(npmPath?.endsWith('npm-cli.js') ? [npmPath] : []), 'run', script];
     debug('verify: running npm script', { script, root });
     return new Promise((resolve, reject) => {
-        const child = spawn(command, args, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+        const child = spawn(command, args, {
+            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);
@@ -45,14 +158,17 @@ export async function npmScript(root, script, timeoutMs) {
         let timedOut = false;
         const timer = setTimeout(() => {
             timedOut = true;
-            child.kill('SIGKILL');
+            debug('verify: the npm script reached its time limit; killing it', { script, timeoutMs });
+            killGroup(child.pid, 'SIGKILL');
         }, timeoutMs);
         child.once('error', (cause) => {
             clearTimeout(timer);
+            forwarding();
             reject(new CliError('NPM_FAILED', `Could not run npm run ${script}`, { cause }));
         });
         child.once('close', (code) => {
             clearTimeout(timer);
+            forwarding();
             resolve({ code, output: output.text(), timedOut });
         });
     });
@@ -114,16 +230,45 @@ function get(url, host, timeoutMs = 5000) {
         req.end();
     });
 }
+/**
+ * A file verify needs before any check runs. A missing one is NOT_A_PROJECT with the file and a
+ * fix, never an INTERNAL_ERROR (a project copy without .dokebi/state.json, M32).
+ */
+async function projectFile(root, file) {
+    try {
+        return await readFile(join(root, file), 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw new CliError('READ_FAILED', `Cannot read ${file}`, { cause: error });
+        throw new CliError('NOT_A_PROJECT', `No ${file}: verify runs in a Dokebi project (the folder with package.json, dokebi.yaml and .dokebi/state.json)`, {
+            phase: 'arguments',
+            details: {
+                root,
+                file,
+                fix: file === '.dokebi/state.json'
+                    ? 'run verify in the project folder itself; .dokebi/state.json is written by the CLI and belongs in version control, so a copy needs it too (copy it from the project or check it out from git)'
+                    : file === CONFIG_FILE
+                        ? `run verify in the project folder; ${FRESH_COPY_FIX}`
+                        : 'run verify in the project folder (npx dokebi verify from the folder with dokebi.yaml)',
+            },
+        });
+    }
+}
 async function settings(root) {
-    const pkg = parseObject(await readFile(join(root, 'package.json'), 'utf8'), 'package.json');
+    const pkg = parseObject(await projectFile(root, 'package.json'), 'package.json');
     let vite = false;
     for (const file of ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'])
         vite ||= await exists(await securePath(root, file));
-    const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    const state = readState(parseObject(await projectFile(root, '.dokebi/state.json'), 'state'));
     const ids = new Set(state.plugins.map((plugin) => plugin.id));
     // The domains to check belong to the plugin that hosts apps (D-0070), whatever its id.
     const host = findHost(state.plugins, 'apps');
-    const options = parseProjectConfig(await readFile(join(root, CONFIG_FILE), 'utf8')).options;
+    // M50: the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml).
+    const target = await configTarget(root);
+    const options = parseProjectConfig(target.fromEnvironment
+        ? await readNamedSettings(root, target)
+        : await projectFile(root, CONFIG_FILE)).options;
     const web = (options['dokebi-web'] ?? {});
     const app = ((host ? options[host.id] : undefined) ?? {});
     const db = (options['dokebi-db'] ?? {});
@@ -156,6 +301,8 @@ async function settings(root) {
  * With neither a readiness path (`healthRoutes: false`) nor an app domain, one identity probe
  * runs instead (ISSUE-0006 A08: no request at all used to pass): `GET /`, which passes with any
  * status below 500 that carries the token, a 404 included (the app may have no route at `/`).
+ * Domain probes also accept 401/403 from this instance, reported as accessDenied: true.
+ * These prove reachability only; readiness still requires 2xx/3xx and login needs app tests.
  * Each request must complete within `timeoutMs` (ISSUE-0006 A09).
  */
 export async function httpChecks(base, paths, token, delayMs = 250, timeoutMs = 5000) {
@@ -167,12 +314,15 @@ export async function httpChecks(base, paths, token, delayMs = 250, timeoutMs =
             try {
                 const answer = await get(url, host, timeoutMs);
                 const instance = answer.instance === token ? 'ours' : 'other';
-                const ok = answer.status >= 200 && answer.status < (identity ? 500 : 400) && instance === 'ours';
+                const accessDenied = host !== undefined && (answer.status === 401 || answer.status === 403);
+                const ok = ((answer.status >= 200 && answer.status < (identity ? 500 : 400)) || accessDenied) &&
+                    instance === 'ours';
                 if (ok || attempt >= attempts) {
                     requests.push({
                         url,
                         ...(host ? { host } : {}),
                         status: answer.status,
+                        ...(accessDenied ? { accessDenied: true } : {}),
                         ok,
                         instance,
                         ...kind,
@@ -230,6 +380,38 @@ export async function httpChecks(base, paths, token, delayMs = 250, timeoutMs =
         details: { requests },
     };
 }
+const TERMINATING = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * While the app verify started runs: a SIGINT, SIGTERM or SIGHUP to verify (Ctrl+C, an agent's
+ * command time limit) stops that app first (stopStarted, forced after `limitMs`), then ends verify
+ * as the signal would have. Without it the background app outlived verify and held its port; the
+ * next verify then refused with ALREADY_RUNNING. Returns the function that removes the handlers.
+ */
+export function stopOnTermination(root, started, limitMs = 5000) {
+    const handlers = new Map();
+    const remove = () => {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+        handlers.clear();
+    };
+    for (const signal of TERMINATING) {
+        const handler = () => {
+            remove();
+            debug('verify: terminated; stopping the app it started', { signal, pid: started.pid });
+            server
+                .stopStarted(root, started, limitMs, true)
+                .catch((error) => reportError('VERIFY_STOP_FAILED', 'Unable to stop the app verify started', error))
+                .finally(() => {
+                // The signal's default action (ending this process) applies again.
+                if (process.listenerCount(signal) === 0)
+                    process.kill(process.pid, signal);
+            });
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    return remove;
+}
 export async function verify(root, options = {}) {
     const checks = [];
     const run = async (name, body) => {
@@ -257,6 +439,16 @@ export async function verify(root, options = {}) {
     };
     const skip = (reason) => async () => ({ ok: true, skipped: reason });
     const project = await settings(root);
+    // An unreadable .env fails the steps that need it (test, start) with its code.
+    let warnings = [];
+    try {
+        warnings = envFileWarnings(root).map(({ code, path, hint }) => ({ code, path, hint }));
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        debug('verify: .env not read for its warnings', { code: error.code });
+    }
     let inspection;
     const doctor = await run('doctor', async () => {
         const result = await new ProjectInspector().inspect(root, { runChecks: true });
@@ -272,8 +464,10 @@ export async function verify(root, options = {}) {
         };
     });
     // D-0072: user-code conventions, on doctor's inspection (doctor is not run twice).
+    let allowed = [];
     await run('check', async () => {
         const result = await check(root, inspection ? { inspection } : {});
+        allowed = result.allowed;
         return {
             ok: result.ok,
             ...(result.ok
@@ -282,7 +476,12 @@ export async function verify(root, options = {}) {
                     code: 'CHECK_FAILED',
                     message: `${result.problems.length} convention problem(s): npx dokebi check`,
                 }),
-            details: { problems: result.problems, files: result.files, ms: result.ms },
+            details: {
+                problems: result.problems,
+                allowed: result.allowed,
+                files: result.files,
+                ms: result.ms,
+            },
         };
     });
     const script = async (name, timeoutMs) => {
@@ -305,6 +504,17 @@ export async function verify(root, options = {}) {
     await run('build', typeof project.scripts.build === 'string' && project.vite
         ? () => script('build', 300_000)
         : skip('no Vite build in this project'));
+    // D-0077 H: the project's tests, after the build (they may need it) and before the preflight
+    // and the start (never next to the app: both may want the same port).
+    let tests;
+    await run('test', async () => {
+        const step = await runTests(root, project.scripts, {
+            timeoutMs: options.testTimeoutMs ?? TEST_TIMEOUT_MS,
+        });
+        const { tests: report, ...check } = step;
+        tests = report;
+        return check;
+    });
     const preflight = await run('preflight', async () => {
         const problems = [];
         const running = await server.status(root);
@@ -315,11 +525,7 @@ export async function verify(root, options = {}) {
                 fix: 'npx dokebi stop',
             });
         else if (project.web.installed && project.web.port > 0 && (await portInUse(project.web.port)))
-            problems.push({
-                code: 'PORT_IN_USE',
-                message: `Port ${project.web.port} (options.dokebi-web.port) is in use`,
-                fix: 'stop what uses it, or npx dokebi config set dokebi-web.port=<free port>',
-            });
+            problems.push(await webPortProblem(project.web.port, (await readAppliedRecipes(root)).at(-1)?.answersFrom === 'defaults'));
         for (const db of project.dbUrls)
             if (db.missing)
                 problems.push({
@@ -337,6 +543,7 @@ export async function verify(root, options = {}) {
             : { ok: true };
     });
     let started;
+    let release;
     // Only the instance started here echoes this token (x-dokebi-verify, @dokebi/web).
     const token = randomBytes(16).toString('hex');
     const reason = !doctor.ok ? 'doctor failed' : !preflight.ok ? 'preflight failed' : undefined;
@@ -347,6 +554,7 @@ export async function verify(root, options = {}) {
                 waitMs: options.waitMs ?? 30_000,
                 env: { [VERIFY_TOKEN_ENV]: token },
             });
+            release = stopOnTermination(root, started);
             return {
                 ok: started.ready,
                 ...(started.ready ? {} : { code: 'NOT_READY', message: started.warnings.join('; ') }),
@@ -413,15 +621,58 @@ export async function verify(root, options = {}) {
                 };
             }
             : skip('nothing was started'));
+        release?.();
     }
     const ok = checks.every((check) => check.ok);
-    const tellUser = ok ? tellUserLines(await readAppliedRecipes(root)) : [];
+    const asked = (preflight.details?.problems ?? []).find((item) => item.question);
     const shown = started ? listen : [];
+    const urls = shown.length ? appUrls(shown, await server.appHostsOrNone(root)) : [];
+    // The notices name the app's address as it is now (AI-M05: the port may have changed since),
+    // the first admin as dokebi.yaml and the seed configure it now (D-0115), and every fact they
+    // state as the project has it now (D-0137): the app verify started was ready, so each job
+    // queue it configures was bound.
+    const recipes = ok ? await readAppliedRecipes(root) : [];
+    let firstAdmin;
+    const readAdmin = () => {
+        firstAdmin ??= readFirstAdmin(root);
+        return firstAdmin;
+    };
+    const facts = recipes.some((entry) => entry.notices.some((notice) => factOf(notice)))
+        ? await factTexts(recipes, await readProjectFacts(root, {
+            started: Boolean(started?.ready),
+            firstAdmin: readAdmin,
+            userStores: (realms) => probeUserStores(root, realms),
+        }))
+        : undefined;
+    const tellUser = ok
+        ? tellUserLines(recipes, {
+            urls,
+            ...(project.web.port > 0 ? { port: project.web.port } : {}),
+        }, 
+        // D-0098: the views of apps made outside a recipe, with who chose them.
+        await readRecordedChoices(root), recipes.some((entry) => entry.notices.some(namesFirstAdmin))
+            ? firstAdminPhrase(await readAdmin())
+            : undefined, facts)
+        : [];
+    const finalReport = finalReportLines(ok, new Set(inspection?.plugins.flatMap((item) => item.installed?.id ?? []) ?? []), allowed);
+    if (finalReport.length)
+        debug('verify: final report reminders', { lines: finalReport.length });
     return {
         ok,
         checks,
-        urls: shown.length ? appUrls(shown, await server.appHostsOrNone(root)) : [],
+        urls,
         listen: shown,
-        ...(tellUser.length ? { tellUser } : {}),
+        ...(tests ? { tests } : {}),
+        ...(tellUser.length
+            ? {
+                tellUser: tellUserWithReport(tellUser, finalReport, finalReport.includes(DB_PRACTICE_REPORT) ? await readDbPracticeRules(root) : []),
+                relay: finalReport.length ? REPORT_RELAY : TELL_USER_RELAY,
+            }
+            : {}),
+        ...(finalReport.length ? { finalReport } : {}),
+        ...(asked?.question
+            ? { waitForUser: asked.waitForUser ?? true, question: asked.question, next: asked.next ?? '' }
+            : {}),
+        ...(warnings.length ? { warnings } : {}),
     };
 }

package/dist/view-choice.d.ts

@@ -0,0 +1,58 @@
+import type { RecordedChoice } from './recipe-record.js';
+/**
+ * The longest `--ai-reason` text, one line for the user like a catalog defaultReason: of a recipe
+ * answer (D-0095) and of the view `app add` records (D-0098). One rule, `aiReasonFits`, for both.
+ */
+export declare const AI_REASON_MAX = 200;
+/** The id `--ai-chose` and `--ai-reason` name on `app add`. */
+export declare const VIEW_ID = "view";
+/** The view answer of a project without browser screens (recipe.ts NO_SCREENS), and of `--view none`. */
+export declare const NO_VIEW = "none";
+/** What `app add --view` takes: EJS pages, or no views (a JSON API). */
+export type AppView = 'ejs' | 'none';
+/**
+ * The view the project's latest recipe recorded (`view` answer), if any: `none` for the api
+ * recipe, so `app add` makes an app without views there unless a flag says otherwise.
+ */
+export declare function projectView(root: string): Promise<string | undefined>;
+/** Who chose the view, as `app add` was told (`--answers-from`, `--ai-chose`, `--ai-reason`). */
+export interface ViewSourceFlags {
+    readonly answersFrom?: 'user' | 'defaults';
+    readonly aiChose?: readonly string[];
+    readonly aiReasons?: Readonly<Record<string, string>>;
+}
+/** A trimmed `--ai-reason` text is one line of 1 to AI_REASON_MAX characters. */
+export declare function aiReasonFits(reason: string): boolean;
+/** The value of the view question for an app made with these flags. */
+export declare function appViewValue(inertia: boolean, ssr: boolean, none?: boolean): string;
+/**
+ * Checks the source flags of `app add` before anything changes: `--ai-chose` names only `view`,
+ * `--ai-reason` only an id of `--ai-chose`, and a reason is one line of 1 to 200 characters.
+ */
+export declare function checkViewSource(flags: ViewSourceFlags): void;
+/**
+ * The record of an app's view: `ai` with `--ai-chose view` (or `--answers-from defaults`),
+ * `user` with `--answers-from user`, `unstated` for an EJS app or one without views, without
+ * either (not the default, so the user hears about it); none for an Inertia app without either
+ * (the default), nor for an app without views the project's recipe implied (`inherited`: the
+ * recipe's own line already says who chose no screens).
+ */
+export declare function appViewChoice(app: string, value: string, flags: ViewSourceFlags, now?: Date, inherited?: boolean): RecordedChoice | undefined;
+/** The warning of an EJS app (or one without views) whose chooser was not stated (D-0098). */
+export declare function unstatedViewWarning(app: string, value?: string): {
+    code: 'VIEW_SOURCE_UNSTATED';
+    path: string;
+    hint: string;
+};
+/**
+ * After `app add` (or `add` with the first app): records the app's view with its source and adds
+ * VIEW_SOURCE_UNSTATED to the result's warnings for an EJS app without a source. A dry run only
+ * warns. The result is the command's own; it is returned with the warning added.
+ */
+export declare function recordAppView<T extends {
+    warnings?: object[];
+    appView?: {
+        value: string;
+        from: 'flags' | 'recipe';
+    };
+}>(root: string, result: T, app: string, value: string, flags: ViewSourceFlags, dryRun: boolean): Promise<T>;

package/dist/view-choice.js

@@ -0,0 +1,131 @@
+// D-0098: the view of an app is a product choice whose default is Inertia + Vue. Outside a recipe
+// it is made by `dokebi app add <name>` (EJS unless --inertia or --view none; none when the
+// project's recipe built no browser screens, the api recipe) and by the first app of
+// `dokebi add <apps host>` (EJS). These commands record it in `.dokebi/recipe.json` (`choices`)
+// with who made it, the same way D-0095 records recipe answers, so verify's tellUser says it.
+import { debug } from './diagnostics.js';
+import { CliError } from './errors.js';
+/**
+ * The longest `--ai-reason` text, one line for the user like a catalog defaultReason: of a recipe
+ * answer (D-0095) and of the view `app add` records (D-0098). One rule, `aiReasonFits`, for both.
+ */
+export const AI_REASON_MAX = 200;
+/** The id `--ai-chose` and `--ai-reason` name on `app add`. */
+export const VIEW_ID = 'view';
+/** The view answer of a project without browser screens (recipe.ts NO_SCREENS), and of `--view none`. */
+export const NO_VIEW = 'none';
+/**
+ * The view the project's latest recipe recorded (`view` answer), if any: `none` for the api
+ * recipe, so `app add` makes an app without views there unless a flag says otherwise.
+ */
+export async function projectView(root) {
+    const { readAppliedRecipes } = await import('./recipe-record.js');
+    const recipes = await readAppliedRecipes(root);
+    for (const recipe of [...recipes].reverse()) {
+        const value = recipe.answers[VIEW_ID]?.value;
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+/** A trimmed `--ai-reason` text is one line of 1 to AI_REASON_MAX characters. */
+export function aiReasonFits(reason) {
+    return reason.length > 0 && reason.length <= AI_REASON_MAX && !/[\r\n]/.test(reason);
+}
+/** The value of the view question for an app made with these flags. */
+export function appViewValue(inertia, ssr, none = false) {
+    return inertia ? (ssr ? 'inertia-vue-ssr' : 'inertia-vue') : none ? NO_VIEW : 'ejs';
+}
+/**
+ * Checks the source flags of `app add` before anything changes: `--ai-chose` names only `view`,
+ * `--ai-reason` only an id of `--ai-chose`, and a reason is one line of 1 to 200 characters.
+ */
+export function checkViewSource(flags) {
+    for (const id of flags.aiChose ?? [])
+        if (id !== VIEW_ID)
+            throw new CliError('AI_CHOICE_UNKNOWN', `app add records only the view, not ${id}`, {
+                details: { aiChose: id, questions: [VIEW_ID], fix: '--ai-chose view' },
+                phase: 'arguments',
+            });
+    for (const [id, text] of Object.entries(flags.aiReasons ?? {})) {
+        if (!(flags.aiChose ?? []).includes(id))
+            throw new CliError('AI_REASON_WITHOUT_CHOICE', `--ai-reason ${id} is given, but ${id} is not in --ai-chose`, {
+                details: {
+                    question: id,
+                    aiChose: [...(flags.aiChose ?? [])],
+                    fix: 'add --ai-chose view if you chose the view because the user left it to you',
+                },
+                phase: 'arguments',
+            });
+        const reason = text.trim();
+        if (!aiReasonFits(reason))
+            throw new CliError('INVALID_AI_REASON', `--ai-reason ${id} must be one line of 1 to ${AI_REASON_MAX} characters`, {
+                details: {
+                    question: id,
+                    length: reason.length,
+                    fix: 'give one short line the user reads: why you chose this view',
+                },
+                phase: 'arguments',
+            });
+    }
+}
+/**
+ * The record of an app's view: `ai` with `--ai-chose view` (or `--answers-from defaults`),
+ * `user` with `--answers-from user`, `unstated` for an EJS app or one without views, without
+ * either (not the default, so the user hears about it); none for an Inertia app without either
+ * (the default), nor for an app without views the project's recipe implied (`inherited`: the
+ * recipe's own line already says who chose no screens).
+ */
+export function appViewChoice(app, value, flags, now = new Date(), inherited = false) {
+    const recordedAt = now.toISOString();
+    if ((flags.aiChose ?? []).includes(VIEW_ID) || flags.answersFrom === 'defaults') {
+        const reason = flags.aiReasons?.[VIEW_ID]?.trim();
+        return {
+            app,
+            id: VIEW_ID,
+            value,
+            answeredBy: 'ai',
+            ...(reason ? { aiReason: reason } : {}),
+            recordedAt,
+        };
+    }
+    if (flags.answersFrom === 'user')
+        return { app, id: VIEW_ID, value, answeredBy: 'user', recordedAt };
+    if (inherited) {
+        debug('app view: no views, as the project recipe built no screens', { app, value });
+        return undefined;
+    }
+    if (value === 'ejs' || value === NO_VIEW) {
+        debug('app view: a view other than the default without a stated source', { app, value });
+        return { app, id: VIEW_ID, value, answeredBy: 'unstated', recordedAt };
+    }
+    return undefined;
+}
+/** The warning of an EJS app (or one without views) whose chooser was not stated (D-0098). */
+export function unstatedViewWarning(app, value = 'ejs') {
+    const what = value === NO_VIEW ? 'an app without views (--view none)' : 'EJS';
+    return {
+        code: 'VIEW_SOURCE_UNSTATED',
+        path: `src/apps/${app}`,
+        hint: `The app ${app} is ${what}, which is not the default view (Inertia + Vue, npx dokebi app add <name> --inertia). verify's tellUser tells the user that nobody recorded who chose it. Next time say it: --answers-from user when the user or the request chose it, --ai-chose view --ai-reason view=<why> when the user left the view to you.`,
+    };
+}
+/**
+ * After `app add` (or `add` with the first app): records the app's view with its source and adds
+ * VIEW_SOURCE_UNSTATED to the result's warnings for an EJS app without a source. A dry run only
+ * warns. The result is the command's own; it is returned with the warning added.
+ */
+export async function recordAppView(root, result, app, value, flags, dryRun) {
+    // app add says what the app really got (an app without views in an api project).
+    const actual = result.appView?.value ?? value;
+    const choice = appViewChoice(app, actual, flags, new Date(), result.appView?.from === 'recipe');
+    if (!choice)
+        return result;
+    if (!dryRun) {
+        const { saveRecordedChoice } = await import('./recipe-record.js');
+        await saveRecordedChoice(root, choice);
+    }
+    if (choice.answeredBy !== 'unstated')
+        return result;
+    return { ...result, warnings: [...(result.warnings ?? []), unstatedViewWarning(app, actual)] };
+}

package/dist/vite-watch.js

@@ -1,6 +1,8 @@
 // Run by `dokebi dev` (D-0044) for one Vite config: a watch build that never empties its outDir.
-// The browser build's `emptyOutDir: true` would otherwise delete dist/ssr/ on every rebuild,
-// which is fine for `npm run build` (one build after the other) but not for two watchers.
+// The templates of @dokebi/app write `emptyOutDir: false` (a rolling deploy keeps the previous
+// chunks), but a vite.config of a project created before them still says `true`: the browser
+// build (outDir dist/) would then delete dist/ssr/ on every rebuild, which `npm run build` (one
+// build after the other) survives but two watchers do not. So dev overrides it for every config.
 // Every finished build is reported to dev over the IPC channel ({ built: true } or
 // { failed: true }); output goes to the terminal as usual.
 import { join } from 'node:path';