@dokebi/cli 0.4.1 → 0.4.26

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 });
         });
     });
@@ -61,10 +177,31 @@ export async function npmScript(root, script, timeoutMs) {
 export const VERIFY_TOKEN_ENV = 'DOKEBI_VERIFY_TOKEN';
 /** The response header @dokebi/web answers with when that variable is set. */
 export const VERIFY_HEADER = 'x-dokebi-verify';
-/** GET with a Host header (fetch cannot set one). */
+/**
+ * GET with a Host header (fetch cannot set one). Settles once: with the answer when the body
+ * ended, or with an error when the request fails, the response is aborted or its connection
+ * closes before the end (ISSUE-0006 A09), or nothing complete came within `timeoutMs` in all
+ * (the socket timeout alone never fires for a server that keeps trickling bytes).
+ */
 function get(url, host, timeoutMs = 5000) {
     return new Promise((resolve, reject) => {
         const target = new URL(url);
+        let settled = false;
+        const finish = (error, answer) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            if (error) {
+                // Frees the socket of a response that will never complete.
+                if (!req.destroyed)
+                    req.destroy();
+                reject(error);
+            }
+            else
+                resolve(answer);
+        };
+        const failed = (error) => finish(error);
         const req = request({
             host: target.hostname.replace(/^\[|\]$/g, ''),
             port: target.port,
@@ -73,27 +210,65 @@ function get(url, host, timeoutMs = 5000) {
             timeout: timeoutMs,
         }, (response) => {
             response.resume();
-            response.once('end', () => resolve({
+            response.once('end', () => finish(undefined, {
                 status: response.statusCode ?? 0,
                 type: String(response.headers['content-type'] ?? ''),
                 instance: response.headers[VERIFY_HEADER],
             }));
+            response.once('aborted', () => finish(new Error('The response was aborted')));
+            // Error listeners stay after settling: a late error (the destroy below) is then ignored
+            // by `finish` instead of being an unhandled 'error' event.
+            response.on('error', failed);
+            response.once('close', () => {
+                if (!response.complete)
+                    finish(new Error('The connection closed before the response ended'));
+            });
         });
+        const deadline = setTimeout(() => finish(new Error(`No complete answer within ${timeoutMs} ms`)), timeoutMs);
         req.once('timeout', () => req.destroy(new Error(`No answer within ${timeoutMs} ms`)));
-        req.once('error', reject);
+        req.on('error', failed);
         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'] ?? {});
@@ -123,18 +298,35 @@ async function settings(root) {
  * The HTTP check of verify: GET the readiness path, then `/` of each app domain, at `base`. An
  * answer counts only when it carries `token` in the x-dokebi-verify header (the instance verify
  * started); anything else is retried like a failed request and then reported FOREIGN_SERVER.
+ * 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) {
+export async function httpChecks(base, paths, token, delayMs = 250, timeoutMs = 5000) {
     const requests = [];
-    const probe = async (path, host, attempts) => {
+    const probe = async (path, host, attempts, identity = false) => {
         const url = `${base}${path}`;
+        const kind = identity ? { identity: true } : {};
         for (let attempt = 1;; attempt++) {
             try {
-                const answer = await get(url, host);
+                const answer = await get(url, host, timeoutMs);
                 const instance = answer.instance === token ? 'ours' : 'other';
-                const ok = answer.status >= 200 && answer.status < 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, ok, instance });
+                    requests.push({
+                        url,
+                        ...(host ? { host } : {}),
+                        status: answer.status,
+                        ...(accessDenied ? { accessDenied: true } : {}),
+                        ok,
+                        instance,
+                        ...kind,
+                    });
                     return;
                 }
                 if (instance === 'other')
@@ -151,6 +343,7 @@ export async function httpChecks(base, paths, token, delayMs = 250) {
                         status: 0,
                         ok: false,
                         error: error instanceof Error ? error.message : String(error),
+                        ...kind,
                     });
                     return;
                 }
@@ -163,6 +356,10 @@ export async function httpChecks(base, paths, token, delayMs = 250) {
         await probe(paths.ready, undefined, 20);
     for (const domain of paths.domains)
         await probe('/', domain, 4);
+    if (!paths.ready && !paths.domains.length) {
+        debug('verify: no readiness route and no app domain; probing GET / for this run', { base });
+        await probe('/', undefined, 20, true);
+    }
     const failed = requests.filter((item) => !item.ok);
     const foreign = failed.filter((item) => item.instance === 'other');
     return {
@@ -183,6 +380,38 @@ export async function httpChecks(base, paths, token, delayMs = 250) {
         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) => {
@@ -210,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 });
@@ -225,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
@@ -235,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) => {
@@ -258,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);
@@ -268,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({
@@ -290,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;
@@ -300,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('; ') }),
@@ -366,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>;