@dokebi/cli 0.4.2 → 0.4.27

package/dist/recipe-facts.js

@@ -0,0 +1,563 @@
+// The recipe notices that state a fact of the project (D-0137): whether CSRF protection, Seal,
+// HTML form bodies or a session are on, where local mail goes, whether the site's realms still
+// deny every login, whether its job queue is provisioned. AI-M27: verify relayed the site notice
+// "the generated auth extensions deny every login until connected to your user store" after the
+// builder had connected them; the recipe had recorded the sentence as fixed text.
+//
+// Such a notice is recorded as a token, `{fact:<id> <args>}`, never as the sentence. The recipe's
+// report (before or right after applying) says what the plan does (`plannedText`); verify says
+// what it finds in the project then (`projectText`): dokebi.yaml, the installed plugins, the
+// files the recipe wrote, whether the app it started bound its queues, the behaviour of the auth
+// extension's hooks (site-auth.ts). When the fact still holds, the sentence is the one the recipe
+// always said; when it changed, the sentence says what was found; when the CLI cannot tell, it
+// says so and where to look. A record written before D-0137 holds the old sentences: each one
+// the old code generated is recognized by being exactly that text (`recordedFact`) and read the
+// same way.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseProjectConfig, readProjectSettings } from './configuration.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { exists, parseObject, securePath } from './filesystem.js';
+import { findHost } from './manifest.js';
+import { readState } from './project-state.js';
+import { EXTENSION_FILE } from './recipe-login.js';
+import { MAIL_COMPOSE, mailComposePorts } from './recipe-mail.js';
+import { LEGACY_SITE_WORKER_PATH, SITE_LOGIN_HINT, SITE_NOTICE, SITE_WORKER_PATH, siteRoutesPath, } from './recipe-site.js';
+const CSRF_MODES = [
+    'inertia',
+    'form-body',
+    'site-api',
+    'site-inertia',
+    'site-ejs',
+];
+/** The recorded form of a fact notice. */
+export function factToken(fact) {
+    const args = fact.id === 'csrf'
+        ? [fact.mode]
+        : fact.id === 'seal'
+            ? [fact.view, ...fact.domains]
+            : fact.id === 'ssr-seal'
+                ? [...fact.domains]
+                : [];
+    return `{fact:${[fact.id, ...args].join(' ')}}`;
+}
+const TOKEN = /^\{fact:([a-z-]+)((?: [^\s{}]+)*)\}$/;
+/** The fact of a recorded token; undefined for any other notice (or a token this CLI does not know). */
+export function parseFact(notice) {
+    const match = TOKEN.exec(notice);
+    if (!match)
+        return undefined;
+    const id = match[1];
+    const args = (match[2] ?? '').split(' ').filter(Boolean);
+    if ((id === 'site' || id === 'mail' || id === 'session') && args.length === 0)
+        return { id };
+    if (id === 'csrf' && args.length === 1 && CSRF_MODES.includes(args[0]))
+        return { id, mode: args[0] };
+    if (id === 'seal' && (args[0] === 'ejs' || args[0] === 'inertia') && args.length > 1)
+        return { id, view: args[0], domains: args.slice(1) };
+    if (id === 'ssr-seal' && args.length > 0)
+        return { id, domains: args };
+    debug('Recipe record: unknown fact token kept as recorded', { notice });
+    return undefined;
+}
+// --- The sentences (the planned ones are what recipes have always said) ---------------------
+/**
+ * How the forms of a plan send the CSRF token (D-0076 §6): @dokebi/csrf is installed for every
+ * write form, so the report says what each view does instead of "no CSRF protection".
+ */
+export function csrfNotice(inertia) {
+    return inertia
+        ? 'CSRF protection is on (@dokebi/csrf): Inertia forms need no code (its client sends the XSRF-TOKEN cookie as the X-XSRF-TOKEN header), and fetch sends the same header.'
+        : 'CSRF protection is on (@dokebi/csrf): every <form method="post"> writes <%- data.csrf.field %>, and fetch sends the XSRF-TOKEN cookie in the X-XSRF-TOKEN header.';
+}
+/** What the notice of a plan with HTML form bodies says before the CSRF sentence. */
+const FORM_BODY_ON = 'HTML forms are on (dokebi-web.formBody=true).';
+const SITE_CSRF = 'CSRF protection is on (@dokebi/csrf): unsafe application API calls go through sealedFetch, which sends the current XSRF-TOKEN cookie as X-XSRF-TOKEN by itself (@dokebi/seal 0.4.2); no adapter of your own.';
+/** The same without @dokebi/seal (AI-M47 Codex removed it): there is no sealedFetch adapter. */
+const SITE_CSRF_PLAIN = 'CSRF protection is on (@dokebi/csrf): unsafe application API calls must send the current XSRF-TOKEN cookie as X-XSRF-TOKEN (with fetch; @dokebi/seal is not installed now, so there is no sealedFetch adapter).';
+const SITE_INERTIA_CSRF = 'Inertia forms send the CSRF header automatically.';
+const SITE_EJS_CSRF = 'EJS write forms include <%- data.csrf.field %>; dokebi-web.formBody is on (sealed forms are form bodies).';
+const CSRF_OFF = 'CSRF protection is off: @dokebi/csrf is not installed now (the recipe installed it), so no unsafe request is checked for its token.';
+const formBodyOff = (file) => `HTML form posts are refused now (415 FORM_BODY_DISABLED): dokebi-web.formBody is not true in ${file} (the recipe turned it on).`;
+/** The seal head an EJS layout writes in its `<head>` (the shipped template-ejs layout's words). */
+export const SEAL_HEAD = "<%- data.seal?.head ?? '' %>";
+/**
+ * The browser module the generated Inertia entry (`views/app.js`) imports on sealed pages: it
+ * imports `@dokebi/seal/http`, which `dokebiInertia()` of the generated vite.config.ts maps to this
+ * served file (D-0062 addendum 2026-10-20).
+ */
+export const SEAL_HTTP_MODULE = '/dokebi/seal/http.mjs';
+/**
+ * What the user must know about the sealed browser hosts of a plan (D-0092 §1, D-0062): the
+ * consumer convention seals every browser app. EJS forms keep working without per-form code;
+ * Inertia pages and visits go sealed through the bootstrap of the generated entry.
+ */
+export function sealNotice(domains, view = 'ejs') {
+    const head = `Seal is on for ${domains.join(', ')} (@dokebi/seal, dokebi-app.domains.<host>.seal: true): `;
+    return view === 'inertia'
+        ? `${head}the first page's data-page and every Inertia visit (page props, form posts, validation errors) go sealed, and a plain JSON body is refused (415 SEAL_REQUIRED). Each app's views/app.js awaits sealInertia(http) from @dokebi/seal/http before createInertiaApp; keep it. dokebiInertia() of vite.config.ts makes every import of @dokebi/seal/http load the served ${SEAL_HTTP_MODULE} (one instance), so REST calls in Vue pages import sealedFetch from '@dokebi/seal/http' as usual.`
+        : `${head}the shared EJS layout writes ${SEAL_HEAD} in its <head>, which loads @dokebi/seal/forms; it sends every <form method="post"> sealed with no per-form code (the handler reads the same request.body; dokebi-web.formBody is on). Pages stay plain HTML; REST calls use sealedFetch.`;
+}
+/**
+ * Why the browser hosts of a server-rendered Inertia plan stay unsealed (D-0062 §5): SSR writes
+ * the page props into the first HTML as plain text, so @dokebi/template-inertia refuses to start
+ * an SSR scope on a seal host (SEAL_SSR_CONFLICT). The user chose SSR; the convention still asks
+ * for Seal, so the user decides between the two.
+ */
+export function ssrSealNotice(domains) {
+    return `${legacySsrSealNotice(domains)} ${READ_ONLY_HOSTS}`;
+}
+/**
+ * Which hosts gain from seal (the @dokebi/seal guide, audit 2026-10-25): a host that only shows
+ * public pages needs no seal, so SSR there is no conflict to ask the user about.
+ */
+export const READ_ONLY_HOSTS = "Seal a host whose pages send data (forms, sealedFetch, Inertia visits). A host that only shows public pages (no writes, no signed-in JSON) gains nothing from seal: leave its domain without `seal: true`. Its pages then need no seal files and no 'wasm-unsafe-eval', and may use Inertia SSR.";
+/** The SSR notice as records before D-0137 hold it (recognised by `recordedFact`). */
+function legacySsrSealNotice(domains) {
+    return `Seal is off for ${domains.join(', ')}: server rendering (view inertia-vue-ssr) writes the page props into the first HTML as plain text, so a sealed host refuses to start it (SEAL_SSR_CONFLICT). Browser apps are sealed by convention: confirm with the user that these hosts stay unsealed, or switch to inertia-vue (drop ssr from the app's inertia settings in app.ts, npx dokebi add @dokebi/seal, then seal: true on these domains in dokebi.yaml) and rebuild.`;
+}
+/** What @dokebi/session would add to an EJS blog without it (AI-M05 F3). */
+export const SESSION_OFFER = 'npx dokebi add @dokebi/session makes a refused form go back to its page with the typed values and the field messages';
+/** The notice of an EJS plan without @dokebi/session (AI-M05 F3: not installed behind the user's back). */
+export const SESSION_NOTICE = 'Without @dokebi/session (not part of these choices), a form with invalid input shows an error page instead of coming back with what was typed; say if you want it added (npx dokebi add @dokebi/session).';
+const SESSION_ADDED = '@dokebi/session is installed now (it was not part of the recipe choices): a form with invalid input comes back to its page with what was typed and the field messages.';
+const MAIL_TOOLS = `Run docker compose -f ${MAIL_COMPOSE} port mailpit 8025 for its loopback inbox address, npx dokebi mail preview welcome --json for a template preview, and docker compose -f ${MAIL_COMPOSE} down to stop it (add -v only to delete queued mail).`;
+const RECOVERY = 'Password recovery needs an email address mapped by the auth extension';
+/** The mail notice as recipes before D-0137 recorded it (the first admin part was fixed text). */
+const RECORDED_MAIL = `Local mail stays in Mailpit. ${MAIL_TOOLS} ${RECOVERY}; the first admin login is not an email address.`;
+/** The site's job worker queue and its example handler (recipe-site.ts). */
+const SITE_QUEUE = 'siteWorker';
+const NATS_PLACEHOLDER = 'configure-me.invalid';
+const LOGIN_SCREENS = 'Login screens are app code: the site scaffold wrote none (its GET /login of each app answers a JSON hint until you replace it).';
+/** The auth default the site recipe gives an app (recipe-site.ts site-config). */
+const plannedDefault = (app) => (app === 'web' ? 'optional' : 'required');
+const list = (items) => items.length > 1 ? `${items.slice(0, -1).join(', ')} and ${items.at(-1)}` : (items[0] ?? '');
+const realmWord = (items) => `${items.length > 1 ? 'realms' : 'realm'} ${list(items)}`;
+const loginWord = (value) => value === 'required' || value === 'optional'
+    ? `login ${value} by default`
+    : `default ${JSON.stringify(value ?? null)}`;
+/** The notice of a fact as the plan makes it (the recipe's report). */
+export function plannedText(fact, plan) {
+    switch (fact.id) {
+        case 'csrf':
+            return fact.mode === 'inertia'
+                ? csrfNotice(true)
+                : fact.mode === 'form-body'
+                    ? `${FORM_BODY_ON} ${csrfNotice(false)}`
+                    : fact.mode === 'site-api'
+                        ? SITE_CSRF
+                        : fact.mode === 'site-inertia'
+                            ? SITE_INERTIA_CSRF
+                            : SITE_EJS_CSRF;
+        case 'seal':
+            return sealNotice(fact.domains, fact.view);
+        case 'ssr-seal':
+            return ssrSealNotice(fact.domains);
+        case 'session':
+            return SESSION_NOTICE;
+        case 'mail':
+            return `Local mail stays in Mailpit. ${MAIL_TOOLS} ${RECOVERY}${plan.adminLogin
+                ? `; the first admin signs in with the login name ${plan.adminLogin}${plan.adminLogin.includes('@') ? '' : ', not an email address'}.`
+                : '.'}`;
+        case 'site': {
+            const site = plan.site;
+            const parts = [];
+            if (site?.apps.length) {
+                parts.push(`Site apps and their auth realms (options.dokebi-auth.apps of dokebi.yaml): ${site.apps
+                    .map((app) => `${app} → realm ${site.realms[app]}, ${loginWord(plannedDefault(app))}`)
+                    .join('; ')}.`);
+                const realms = [...new Set(site.apps.map((app) => site.realms[app]))];
+                parts.push(`User lookup is app code: ${EXTENSION_FILE} gets the site scaffold's stub for ${realmWord(realms)}, whose findByIdentity and findById find nobody, so every login is denied until they read your user store.`, LOGIN_SCREENS);
+            }
+            if (site?.worker === 'job')
+                parts.push(`A job worker needs a configured NATS connection (options.dokebi-nats.connections.${SITE_QUEUE}.servers) and a provisioned ${SITE_QUEUE} queue (npx dokebi-job-provision --queue ${SITE_QUEUE}) before verify.`);
+            if (site?.worker === 'thread')
+                parts.push('The thread worker (@dokebi/worker) handles CPU tasks in this process.');
+            return parts.join(' ');
+        }
+    }
+}
+/** The settings file a notice names (dokebi.yaml unless DOKEBI_CONFIG named another). */
+const settingsFileOf = (facts) => facts.settingsFile ?? 'dokebi.yaml';
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * Reads the installed plugins and the settings file (DOKEBI_CONFIG, else dokebi.yaml) for `projectText`; undefined (and a debug line with
+ * the error) when either cannot be read, and the notices then say the CLI could not read them.
+ */
+export async function readProjectFacts(root, input) {
+    try {
+        const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+        // M50: the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml), named in the notices.
+        const settings = await readProjectSettings(root);
+        const options = parseProjectConfig(settings.source).options;
+        const host = findHost(state.plugins, 'apps');
+        return {
+            root,
+            installed: new Set(state.plugins.map((plugin) => plugin.id)),
+            options,
+            ...(settings.target.fromEnvironment ? { settingsFile: settings.target.file } : {}),
+            ...(host ? { appsHost: host.id } : {}),
+            ...input,
+        };
+    }
+    catch (error) {
+        debug('Recipe facts: the project could not be read', { error: describeError(error) });
+        return undefined;
+    }
+}
+/** The notice of a fact when the project could not be read: that, and where to look. */
+export function unreadText(fact, recipe) {
+    const topic = {
+        site: [
+            "the site's realms, user store and worker",
+            `SITE.md, ${EXTENSION_FILE} and dokebi.yaml`,
+        ],
+        csrf: ['CSRF protection', 'npx dokebi plugins list and dokebi.yaml'],
+        seal: ['Seal', 'npx dokebi plugins list and the domains in dokebi.yaml'],
+        'ssr-seal': ['Seal', 'npx dokebi plugins list and the domains in dokebi.yaml'],
+        mail: ['local mail', `options.dokebi-mail of dokebi.yaml and ${MAIL_COMPOSE}`],
+        session: ['@dokebi/session', 'npx dokebi plugins list'],
+    };
+    const [what, where] = topic[fact.id];
+    return `The CLI could not read the project for the ${recipe} recipe's note on ${what}: look at ${where}.`;
+}
+/** The notice of a fact as the project is now; '' when nothing is left to say (the line is dropped). */
+export async function projectText(fact, entry, facts) {
+    const has = (id) => facts.installed.has(id);
+    const formBody = record(facts.options['dokebi-web'])?.formBody === true;
+    switch (fact.id) {
+        case 'csrf': {
+            if (!has('dokebi-csrf'))
+                return fact.mode === 'site-inertia' ? '' : CSRF_OFF;
+            if (fact.mode === 'form-body')
+                return `${formBody ? FORM_BODY_ON : formBodyOff(settingsFileOf(facts))} ${csrfNotice(false)}`;
+            if (fact.mode === 'site-ejs' && !formBody)
+                return `EJS write forms include <%- data.csrf.field %>; ${formBodyOff(settingsFileOf(facts))}`;
+            if (fact.mode === 'site-api' && !has('dokebi-seal'))
+                return SITE_CSRF_PLAIN;
+            return plannedText(fact, { recipe: entry.recipe });
+        }
+        case 'seal':
+        case 'ssr-seal': {
+            const host = facts.appsHost ?? 'dokebi-app';
+            const domains = record(record(facts.options[host])?.domains) ?? {};
+            const sealedNow = (domain) => has('dokebi-seal') && record(domains[domain])?.seal === true;
+            // The hosts the project serves now: a host the recipe wrote that `app link`/`unlink`
+            // renamed is gone, and its new name is what to report (AI-M42: the note called renamed,
+            // sealed hosts "off"). With no domains left, the recipe's hosts are reported as off.
+            const current = Object.keys(domains);
+            const gone = fact.domains.filter((domain) => !(domain in domains));
+            // Only when a host the recipe wrote is gone are the hosts it does not know its new names
+            // (another fact, such as ssr-seal for one app, keeps to its own hosts otherwise).
+            const hosts = current.length === 0 || gone.length === 0
+                ? fact.domains
+                : [
+                    ...fact.domains.filter((domain) => domain in domains),
+                    ...current.filter((domain) => !fact.domains.includes(domain)),
+                ];
+            const on = hosts.filter(sealedNow);
+            const off = hosts.filter((domain) => !sealedNow(domain));
+            const why = has('dokebi-seal')
+                ? `${host}.domains.<host>.seal is not true in ${settingsFileOf(facts)}`
+                : '@dokebi/seal is not installed now';
+            if (fact.id === 'seal')
+                return [
+                    ...(on.length ? [sealNotice(on, fact.view)] : []),
+                    ...(off.length ? [`Seal is off now for ${off.join(', ')} (${why}).`] : []),
+                ].join(' ');
+            return [
+                ...(off.length ? [ssrSealNotice(off)] : []),
+                ...(on.length
+                    ? [`Seal is on now for ${on.join(', ')} (${host}.domains.<host>.seal: true).`]
+                    : []),
+            ].join(' ');
+        }
+        case 'session':
+            return has('dokebi-session') ? SESSION_ADDED : SESSION_NOTICE;
+        case 'mail':
+            return mailText(facts, entry);
+        case 'site':
+            return siteText(facts, entry);
+    }
+}
+/** Where local mail goes and how the first admin signs in. */
+async function mailText(facts, entry) {
+    const mail = record(facts.options['dokebi-mail']);
+    const transport = record(mail?.transport);
+    let where;
+    if (!facts.installed.has('dokebi-mail') || !mail)
+        where = `Mail is not configured now: @dokebi/mail or options.dokebi-mail of ${settingsFileOf(facts)} is gone (the recipe set up local Mailpit).`;
+    else {
+        const driver = typeof transport?.driver === 'string' ? transport.driver : undefined;
+        const host = typeof transport?.host === 'string' ? transport.host : undefined;
+        const port = typeof transport?.port === 'number' ? transport.port : undefined;
+        const loopback = host !== undefined && ['localhost', '127.0.0.1', '::1'].includes(host);
+        if (driver !== 'smtp' || !loopback || port === undefined)
+            where = `Mail does not go to the local Mailpit now: options.dokebi-mail.transport uses ${driver ?? 'no driver'}${host && !loopback ? ` at ${host}` : ''} (look there for where mail goes).`;
+        else {
+            const smtp = await composeSmtpPort(facts.root);
+            where =
+                smtp.port === port
+                    ? `Local mail stays in Mailpit (options.dokebi-mail.transport: smtp ${host}:${port}, the mailpit service of ${MAIL_COMPOSE}). ${MAIL_TOOLS}`
+                    : smtp.port !== undefined
+                        ? `Mail goes to smtp ${host}:${port} (options.dokebi-mail.transport), not to the Mailpit of ${MAIL_COMPOSE} (port ${smtp.port}): look at both.`
+                        : `Mail goes to smtp ${host}:${port} (options.dokebi-mail.transport); the CLI could not tell whether that is the Mailpit of ${MAIL_COMPOSE} (${smtp.reason}): look at that file.`;
+        }
+    }
+    const admin = entry.answers.admin?.value === 'login' ? await adminPart(facts) : '';
+    return `${where} ${RECOVERY}${admin ? `; ${admin}` : ''}.`;
+}
+/** How the first admin signs in, for the recovery sentence of the mail notice. */
+async function adminPart(facts) {
+    const found = await facts.firstAdmin();
+    if (!found.section || !found.identity)
+        return 'the CLI could not find how the first admin signs in (see the admin login line)';
+    const at = `options.${found.section}.${found.identity.key}`;
+    return found.identity.kind === 'email'
+        ? `the first admin signs in with the email address ${found.identity.value} (${at})`
+        : `the first admin signs in with the login name ${found.identity.value} (${at})${found.identity.value.includes('@') ? '' : ', not an email address'}`;
+}
+/** The SMTP port compose.mail.yaml publishes for Mailpit, or why it is not known. */
+async function composeSmtpPort(root) {
+    let source;
+    try {
+        source = await readFile(join(root, MAIL_COMPOSE), 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { reason: `${MAIL_COMPOSE} does not exist` };
+        debug('Recipe facts: the mail compose file could not be read', { error: describeError(error) });
+        return { reason: `${MAIL_COMPOSE} could not be read` };
+    }
+    try {
+        const ports = mailComposePorts(root, source);
+        return ports ? { port: ports.smtp } : { reason: `${MAIL_COMPOSE} names no published port` };
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        debug('Recipe facts: the mail compose file is not the recipe template', { code: error.code });
+        // An edited file (a service removed, a comment added) still says where Mailpit's SMTP is:
+        // its published loopback port for 1025 (AI-M44: the note said "could not tell" for a file
+        // that published it plainly).
+        const smtp = [...source.matchAll(/127\.0\.0\.1:(\d+):1025\b/g)].map((match) => Number(match[1]));
+        if (smtp.length === 1 && smtp[0] >= 1 && smtp[0] <= 65535)
+            return { port: smtp[0] };
+        return { reason: `${MAIL_COMPOSE} was edited` };
+    }
+}
+/** The site notice: realms and their login default, the user store, the worker. */
+async function siteText(facts, entry) {
+    const appsAnswer = entry.answers.apps?.value ?? 'none';
+    const apps = appsAnswer === 'none' ? [] : appsAnswer.split(',').filter(Boolean);
+    const worker = entry.answers.worker?.value ?? 'none';
+    const parts = [];
+    if (apps.length) {
+        if (!facts.installed.has('dokebi-auth'))
+            parts.push(`@dokebi/auth is not installed now: the site apps ${list(apps)} have no login (the site recipe installed it).`);
+        else {
+            const auth = record(facts.options['dokebi-auth']) ?? {};
+            const configured = record(auth.apps) ?? {};
+            const realmOf = (app) => {
+                const value = record(configured[app])?.realm ?? auth.realm ?? 'default';
+                return typeof value === 'string' ? value : undefined;
+            };
+            parts.push(`Site apps and their auth realms (options.dokebi-auth.apps of ${settingsFileOf(facts)}): ${apps
+                .map((app) => {
+                const settings = record(configured[app]);
+                if (!settings)
+                    return `${app} → no entry`;
+                return `${app} → realm ${realmOf(app) ?? '(not a name)'}, ${loginWord(settings.default ?? auth.default)}`;
+            })
+                .join('; ')}.`);
+            const realms = [
+                ...new Set(apps.flatMap((app) => (configured[app] ? (realmOf(app) ?? []) : []))),
+            ];
+            if (realms.length)
+                parts.push(userStoreText(await facts.userStores(realms)));
+            const hinted = await scaffoldLogins(facts.root, apps);
+            if (hinted.length === apps.length)
+                parts.push(LOGIN_SCREENS);
+            else if (hinted.length)
+                parts.push(`Login screens are app code: GET /login of ${list(hinted)} still answers the site scaffold's JSON hint (${hinted.map(siteRoutesPath).join(', ')}) until you replace it.`);
+        }
+    }
+    if (worker === 'job')
+        parts.push(await jobText(facts));
+    if (worker === 'thread')
+        parts.push(facts.installed.has('dokebi-worker')
+            ? 'The thread worker (@dokebi/worker) handles CPU tasks in this process.'
+            : 'The thread worker the site recipe added (@dokebi/worker) is not installed now.');
+    return parts.join(' ');
+}
+/**
+ * The site apps whose routes file still has the scaffold's GET /login hint. A file that is gone or
+ * unreadable no longer serves the hint (the app replaced or moved its login), so it is not listed.
+ */
+async function scaffoldLogins(root, apps) {
+    const hinted = [];
+    for (const app of apps) {
+        const path = siteRoutesPath(app);
+        try {
+            if ((await readFile(join(root, path), 'utf8')).includes(SITE_LOGIN_HINT))
+                hinted.push(app);
+        }
+        catch (error) {
+            debug('Recipe facts: a site routes file could not be read', {
+                path,
+                error: describeError(error),
+            });
+        }
+    }
+    return hinted;
+}
+/** What the probe of the realms' hooks found (site-auth.ts), in words. */
+export function userStoreText(probe) {
+    if (!probe.ok)
+        return `The CLI could not tell whether ${EXTENSION_FILE} still denies every login (${probe.code}: ${probe.message}): look at findByIdentity and findById of each realm there.`;
+    const stub = [];
+    const app = [];
+    const sentences = [];
+    const missing = [];
+    for (const realm of probe.realms) {
+        if (!realm.defined) {
+            missing.push(realm.realm);
+            continue;
+        }
+        if (realm.failure || !realm.findByIdentity || !realm.findById) {
+            sentences.push(`The CLI could not tell for realm ${realm.realm} (its class could not be made: ${realm.failure ?? 'no hooks'}): look at it in ${EXTENSION_FILE}.`);
+            continue;
+        }
+        const hooks = [
+            ['findByIdentity', realm.findByIdentity.state],
+            ['findById', realm.findById.state],
+        ];
+        const unimplemented = hooks.filter(([, state]) => state === 'unimplemented').map(([h]) => h);
+        const stubbed = hooks.filter(([, state]) => state === 'stub').map(([h]) => h);
+        if (unimplemented.length)
+            sentences.push(`Realm ${realm.realm}: ${list(unimplemented)} ${unimplemented.length > 1 ? 'are' : 'is'} not implemented in ${EXTENSION_FILE} (EXTENSION_REQUIRED).`);
+        else if (stubbed.length === 2)
+            stub.push(realm.realm);
+        else if (stubbed.length === 1)
+            sentences.push(`Realm ${realm.realm}: ${stubbed[0]} is still the site scaffold's stub (it finds nobody) while ${stubbed[0] === 'findById' ? 'findByIdentity' : 'findById'} is app code, so logins there do not hold until both read your user store.`);
+        else
+            app.push(realm.realm);
+    }
+    return [
+        ...(stub.length
+            ? [
+                `User lookup is app code: ${EXTENSION_FILE} is still the site scaffold's stub for ${realmWord(stub)}, whose findByIdentity and findById find nobody, so every login there is denied until they read your user store.`,
+            ]
+            : []),
+        ...(app.length
+            ? [
+                `User lookup of ${realmWord(app)} is connected: findByIdentity and findById in ${EXTENSION_FILE} are app code, no longer the site scaffold's deny-every-login stub (whether they find the right users is for the app's tests).`,
+            ]
+            : []),
+        ...sentences,
+        ...(missing.length
+            ? [
+                `${missing.length > 1 ? 'Realms' : 'Realm'} ${list(missing)} ${missing.length > 1 ? 'are' : 'is'} not defined in ${EXTENSION_FILE} (export default is the default realm, export const realms the others).`,
+            ]
+            : []),
+    ].join(' ');
+}
+/** The site's job worker: whether its queue is configured and was bound by the started app. */
+async function jobText(facts) {
+    if (!facts.installed.has('dokebi-job'))
+        return `@dokebi/job is not installed now: the site recipe's job worker has no ${SITE_QUEUE} queue.`;
+    const queue = record(record(record(facts.options['dokebi-job'])?.queues)?.[SITE_QUEUE]);
+    if (!queue)
+        return `options.dokebi-job.queues of ${settingsFileOf(facts)} has no ${SITE_QUEUE} queue now (the site recipe configured it).`;
+    const connection = typeof queue.connection === 'string' ? queue.connection : undefined;
+    let file;
+    for (const path of [SITE_WORKER_PATH, LEGACY_SITE_WORKER_PATH])
+        if (!file && (await exists(await securePath(facts.root, path))))
+            file = path;
+    const handler = file
+        ? ` Its example handler site.example is in ${file}.`
+        : ` The worker file the recipe wrote (${SITE_WORKER_PATH}) is not there now.`;
+    if (facts.started)
+        return `The job worker's ${SITE_QUEUE} queue (options.dokebi-job.queues.${SITE_QUEUE}, NATS connection ${connection ?? '(not named)'}) was bound when verify started the app: its NATS server answered and its streams and consumer are provisioned.${handler}`;
+    const servers = connection
+        ? record(record(record(facts.options['dokebi-nats'])?.connections)?.[connection])?.servers
+        : undefined;
+    const placeholder = Array.isArray(servers) && servers.some((item) => String(item).includes(NATS_PLACEHOLDER));
+    return `${placeholder
+        ? `options.dokebi-nats.connections.${connection}.servers still holds the placeholder nats://${NATS_PLACEHOLDER}:4222: write your NATS server there (private ${settingsFileOf(facts)}), then`
+        : `The job worker's NATS connection ${connection ?? '(not named)'} is configured; the app was not started, so the CLI could not tell whether the ${SITE_QUEUE} queue is provisioned:`} run npx dokebi-job-provision --queue ${SITE_QUEUE} before npx dokebi verify.${handler}`;
+}
+// --- Records written before D-0137 ----------------------------------------------------------
+/** The sentences of the old notices, each with its fact (the exact text the old code wrote). */
+const RECORDED = new Map([
+    [SITE_NOTICE, { id: 'site' }],
+    [SITE_CSRF, { id: 'csrf', mode: 'site-api' }],
+    [SITE_INERTIA_CSRF, { id: 'csrf', mode: 'site-inertia' }],
+    [SITE_EJS_CSRF, { id: 'csrf', mode: 'site-ejs' }],
+    [csrfNotice(true), { id: 'csrf', mode: 'inertia' }],
+    [`${FORM_BODY_ON} ${csrfNotice(false)}`, { id: 'csrf', mode: 'form-body' }],
+    [RECORDED_MAIL, { id: 'mail' }],
+    [SESSION_NOTICE, { id: 'session' }],
+]);
+const RECORDED_SEAL = /^Seal is on for (\S+(?:, \S+)*) \(@dokebi\/seal, /;
+const RECORDED_SSR_SEAL = /^Seal is off for (\S+(?:, \S+)*): server rendering /;
+/** The fact of a notice a record before D-0137 holds as a sentence; undefined for any other. */
+export function recordedFact(notice) {
+    const known = RECORDED.get(notice);
+    if (known)
+        return known;
+    const sealed = RECORDED_SEAL.exec(notice);
+    if (sealed?.[1]) {
+        const domains = sealed[1].split(', ');
+        for (const view of ['ejs', 'inertia'])
+            if (sealNotice(domains, view) === notice)
+                return { id: 'seal', view, domains };
+    }
+    const unsealed = RECORDED_SSR_SEAL.exec(notice);
+    if (unsealed?.[1]) {
+        const domains = unsealed[1].split(', ');
+        if (ssrSealNotice(domains) === notice || legacySsrSealNotice(domains) === notice)
+            return { id: 'ssr-seal', domains };
+    }
+    return undefined;
+}
+/** The fact of a recorded notice: a token, or an old sentence; undefined for any other notice. */
+export function factOf(notice) {
+    return notice.startsWith('{fact:') ? parseFact(notice) : recordedFact(notice);
+}
+/** The key of a fact notice of a recipe in the map verify fills (`factTexts`). */
+export function factKey(recipe, fact) {
+    return `${recipe}\n${factToken(fact)}`;
+}
+/** Every fact notice of the recipes as the project is now (verify), by `factKey`. */
+export async function factTexts(recipes, facts) {
+    const texts = new Map();
+    for (const entry of recipes)
+        for (const notice of entry.notices) {
+            const fact = factOf(notice);
+            if (!fact)
+                continue;
+            const key = factKey(entry.recipe, fact);
+            if (texts.has(key))
+                continue;
+            let text = unreadText(fact, entry.recipe);
+            if (facts)
+                try {
+                    text = await projectText(fact, entry, facts);
+                }
+                catch (error) {
+                    // A file that cannot be read (not a missing one): the notice says it could not tell.
+                    debug('Recipe facts: a notice could not be read from the project', {
+                        recipe: entry.recipe,
+                        fact: fact.id,
+                        error: describeError(error),
+                    });
+                }
+            texts.set(key, text);
+        }
+    debug('Recipe facts read from the project', { notices: texts.size, read: facts !== undefined });
+    return texts;
+}

package/dist/recipe-login.d.ts

@@ -0,0 +1,63 @@
+import { LEGACY_LOGIN_NAMES, LOGIN_NAMES, type LoginNames, USERS_TABLE } from './recipe-members.js';
+export type LoginDialect = 'postgres' | 'mysql' | 'mariadb' | 'mongodb';
+export type LoginView = 'ejs' | 'inertia';
+/**
+ * The dokebi.yaml section the first admin comes from (no plugin owns it). D-0115: named for what
+ * it holds (the first admin, like the seed first-admin.ts), not for one kind of app.
+ */
+export declare const ADMIN_SECTION = "first-admin";
+/** The name older recipes wrote (until D-0115); such projects keep it and keep working. */
+export declare const LEGACY_ADMIN_SECTION = "blog-admin";
+/** Both names the CLI reads (config show, check, verify). */
+export declare const ADMIN_SECTIONS: readonly string[];
+/** The key of the generated initial password in that section (never printed). */
+export declare const ADMIN_PASSWORD_KEY = "initialPassword";
+/** The login name of the first admin. */
+export declare const ADMIN_LOGIN = "admin";
+/** The table (collection) of the app's users, and the names of its code (D-0115). */
+export { LEGACY_LOGIN_NAMES, LOGIN_NAMES, type LoginNames, USERS_TABLE };
+/** The one sentence of every failed login (never tell an unknown name from a wrong password). */
+export declare const LOGIN_FAILED = "Invalid login or password.";
+/** Where a login goes, and the auth `homePath` (a signed-in user on the login page goes there). */
+export declare const ADMIN_PATH = "/admin";
+export declare const EXTENSION_FILE = "src/infra/auth/extension.ts";
+export declare const SEED_FILE = "src/infra/db/seeds/main/first-admin.ts";
+/**
+ * The section the recipe writes the first admin into (D-0115): the older name when the project
+ * already uses it (its section in dokebi.yaml, or the seed an older recipe wrote reads it), so a
+ * recipe applied again never splits one admin over two sections; otherwise ADMIN_SECTION.
+ */
+export declare function recipeAdminSection(options: Record<string, unknown>, seedText?: string): string;
+/**
+ * The names of the login code for this project (D-0115): an older recipe's blog_authors when the
+ * project has its migration, or a model, extension or seed that names that table; otherwise
+ * LOGIN_NAMES. So migrationPath and a recipe applied again never make a second table or a
+ * migration that conflicts with the one the project has.
+ */
+export declare function recipeLoginNames(migrations: readonly string[], sources?: readonly string[]): LoginNames;
+/** The project files that tell an older recipe's login code (recipeLoginNames). */
+export declare const LOGIN_NAME_SOURCES: readonly string[];
+export interface LoginFile {
+    readonly path: string;
+    readonly content: string;
+    /** The file `add @dokebi/auth` created from its template: replaced while still untouched. */
+    readonly replaceTemplate?: boolean;
+}
+/** `20261017093000`: the UTC time a new migration file is named after (dokebi-migrate make). */
+export declare function migrationStamp(date: Date): string;
+/** The migration file this project already has, else a new name for `now`. */
+export declare function migrationPath(existing: readonly string[], now: Date, names?: LoginNames): string;
+export declare const MIGRATIONS_DIRECTORY = "src/infra/db/migrations/main";
+/** Every file of the admin login for a dialect and view (the migration path decided by the caller). */
+export declare function loginFiles(dialect: LoginDialect, view: LoginView, migrationFile: string, mail?: boolean, 
+/** The section of dokebi.yaml the seed reads (recipeAdminSection). */
+section?: string, 
+/** The table and code names (recipeLoginNames, D-0115). */
+names?: LoginNames): LoginFile[];
+/**
+ * src/apps/main/routes.ts with the login routes added: an import after the last import and a call
+ * at the top of `routes(route, …)`. Unchanged when already there; RECIPE_FILE_CONFLICT when the
+ * file has no `export function routes(<router>…)` to add it to.
+ */
+export declare function withLoginRoutes(text: string): string;
+export declare const ROUTES_FILE = "src/apps/main/routes.ts";