@dokebi/cli 0.4.1 → 0.4.26

package/dist/recipe-record.js

@@ -1,14 +1,52 @@
 // What a recipe chose, kept for the end of the work (AI-M03): `dokebi recipe` writes
 // `.dokebi/recipe.json` when it applied a recipe, and `dokebi verify` (the last command an agent
 // runs) returns the lines the agent must pass on to the user as `tellUser`: every answer with who
-// gave it (a default with its reason) and the notices, such as no CSRF protection for forms.
+// gave it (a default with its reason) and the notices, such as how forms send the CSRF token.
 // The file holds choice values and catalog texts only, never secrets.
+// A notice that names where the app answers holds APP_URL_PLACEHOLDER instead of an address
+// (AI-M05: a recorded `http://localhost:3001/login` was relayed after the port became 3002);
+// verify fills in the current address. Records written before keep their literal text, and a
+// loopback address in it whose port is no longer the app's is replaced by the current one.
+// Each answer says who settled it (D-0095): the user, the AI (the user left it to it), a default
+// or the recipe. Records written before D-0095 say `flag`; reading turns it into `user` or `ai`.
+// D-0098: the view of an app made outside a recipe (`dokebi app add`, the first app of the apps
+// host) is recorded in `choices` of the same file, with who chose it; a recipe that covers the
+// app replaces it. Files without `choices` read as none.
+// D-0115: the login notice holds FIRST_ADMIN_PLACEHOLDER instead of the login name and the
+// section of the initial password; verify fills in what the project configures then (the builder
+// may rename the section or sign the admin in by email). A record from before says them in words;
+// that part is replaced the same way, so a stale name is never relayed.
+// D-0137: a notice that states a fact of the project (CSRF, Seal, form bodies, a session, local
+// mail, the site's realms, user store and worker) is recorded as a `{fact:…}` token
+// (recipe-facts.ts); verify says what it finds then. The old sentences of such notices are read
+// the same way.
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { isLoopbackHost } from './app-urls.js';
 import { debug, isMissing, reportError } from './diagnostics.js';
+import { firstAdminPhrase } from './first-admin.js';
+import { factKey, factOf, unreadText } from './recipe-facts.js';
 export const RECIPE_RECORD = '.dokebi/recipe.json';
-/** The recipes recorded in the project; none when there is no record (or it is unreadable). */
-export async function readAppliedRecipes(root) {
+/**
+ * How the agent passes `tellUser` on (AI-M05 F6: an agent summarized the lines in another
+ * language instead of relaying them): verify's JSON carries it next to the lines, the human
+ * output prints it as the block's heading.
+ */
+export const TELL_USER_RELAY = {
+    tellUser: 'verbatim',
+    instruction: 'Copy these lines unchanged into your final message to the user: do not translate, reword or summarize them. You may add your own summary after them.',
+};
+/** Stands for `<scheme>://<domain>:<port>` of the app in a recorded notice. */
+export const APP_URL_PLACEHOLDER = '{appUrl}';
+/** Stands for the first admin's login and password key in the login notice (firstAdminPhrase). */
+export const FIRST_ADMIN_PLACEHOLDER = '{firstAdmin}';
+/** What the login notice says about protected pages (D-0115: no word of one kind of app). */
+export const LOGIN_PAGES = 'pages that need a login send other visitors to the login page.';
+/** The same part of the login notice as recipes before D-0115 recorded it, in words. */
+const RECORDED_FIRST_ADMIN = / with the login name \S+ and the initial password stored in dokebi\.yaml at options\.[^\s.]+\.initialPassword \(it is never printed\); only signed-in users write posts\. Change that password before going live and then remove the key\./;
+/** Both lists of the record; empty when there is no record (or it is unreadable). */
+async function readRecord(root) {
+    const none = { recipes: [], choices: [] };
     let text;
     try {
         text = await readFile(join(root, RECIPE_RECORD), 'utf8');
@@ -16,52 +54,218 @@ export async function readAppliedRecipes(root) {
     catch (error) {
         if (!isMissing(error))
             reportError('RECIPE_RECORD_READ_FAILED', `Unable to read ${RECIPE_RECORD}`, error);
-        return [];
+        return none;
     }
     try {
         const parsed = JSON.parse(text);
         if (parsed.version === 1 && Array.isArray(parsed.recipes))
-            return parsed.recipes.filter((entry) => typeof entry?.recipe === 'string' &&
-                entry.answers !== null &&
-                typeof entry.answers === 'object' &&
-                Array.isArray(entry.notices));
+            return {
+                recipes: parsed.recipes
+                    .filter((entry) => typeof entry?.recipe === 'string' &&
+                    entry.answers !== null &&
+                    typeof entry.answers === 'object' &&
+                    Array.isArray(entry.notices))
+                    .map(migrateFlagAnswers),
+                choices: (Array.isArray(parsed.choices) ? parsed.choices : []).filter((entry) => typeof entry?.app === 'string' &&
+                    entry.id === 'view' &&
+                    typeof entry.value === 'string' &&
+                    ['user', 'ai', 'unstated'].includes(entry.answeredBy)),
+            };
         debug('Recipe record ignored: unexpected content', { file: RECIPE_RECORD });
     }
     catch (error) {
         reportError('RECIPE_RECORD_INVALID', `${RECIPE_RECORD} is not valid JSON; ignoring it`, error);
     }
-    return [];
+    return none;
 }
-/** Records an applied recipe, replacing an earlier application of the same recipe. */
-export async function saveAppliedRecipe(root, entry) {
+/** The recipes recorded in the project; none when there is no record (or it is unreadable). */
+export async function readAppliedRecipes(root) {
+    return (await readRecord(root)).recipes;
+}
+/** D-0098: the choices recorded outside recipes (the views of apps). */
+export async function readRecordedChoices(root) {
+    return (await readRecord(root)).choices;
+}
+/**
+ * A record written before D-0095 says `answeredBy: 'flag'` for every given answer, and
+ * `answersFrom` said whose they were: `user` → the user's, `defaults` → the agent's. The same
+ * lines come out of tellUser as before.
+ */
+function migrateFlagAnswers(entry) {
+    const old = Object.entries(entry.answers).filter(([, answer]) => answer?.answeredBy === 'flag');
+    if (!old.length)
+        return entry;
+    const answeredBy = entry.answersFrom === 'user' ? 'user' : 'ai';
+    debug('Recipe record: old flag answers read as their source', {
+        recipe: entry.recipe,
+        answers: old.map(([id]) => id),
+        answeredBy,
+    });
+    return {
+        ...entry,
+        answers: Object.fromEntries(Object.entries(entry.answers).map(([id, answer]) => [
+            id,
+            answer.answeredBy === 'flag' ? { ...answer, answeredBy } : answer,
+        ])),
+    };
+}
+async function writeRecord(root, record) {
     const file = join(root, RECIPE_RECORD);
-    const recipes = [
-        ...(await readAppliedRecipes(root)).filter((item) => item.recipe !== entry.recipe),
-        entry,
-    ];
-    const record = { version: 1, recipes };
     await mkdir(dirname(file), { recursive: true });
     await rm(`${file}.tmp`, { force: true });
     await writeFile(`${file}.tmp`, `${JSON.stringify(record, null, 2)}\n`);
     await rename(`${file}.tmp`, file);
+}
+/**
+ * Records an applied recipe, replacing an earlier application of the same recipe. The recorded
+ * app choices of `apps` (the apps the recipe answers for) give way to the recipe's answers.
+ */
+export async function saveAppliedRecipe(root, entry, apps = []) {
+    const current = await readRecord(root);
+    const recipes = [...current.recipes.filter((item) => item.recipe !== entry.recipe), entry];
+    const choices = current.choices.filter((item) => !apps.includes(item.app));
+    if (choices.length < current.choices.length)
+        debug('Recipe record: app choices replaced by the recipe', { recipe: entry.recipe, apps });
+    await writeRecord(root, { version: 1, recipes, ...(choices.length ? { choices } : {}) });
     debug('Recipe record written', { recipe: entry.recipe, file: RECIPE_RECORD });
 }
+/**
+ * `dokebi app remove`: drops the choices recorded for `app`. True when the record changed (the
+ * file is left alone when it holds none of that app).
+ */
+export async function forgetAppChoices(root, app) {
+    const current = await readRecord(root);
+    const choices = current.choices.filter((item) => item.app !== app);
+    if (choices.length === current.choices.length)
+        return false;
+    await writeRecord(root, {
+        version: 1,
+        recipes: current.recipes,
+        ...(choices.length ? { choices } : {}),
+    });
+    debug('Recipe record: choices of a removed app dropped', { app, file: RECIPE_RECORD });
+    return true;
+}
+/** D-0098: records the view of an app made outside a recipe, replacing that app's earlier one. */
+export async function saveRecordedChoice(root, choice) {
+    const current = await readRecord(root);
+    const choices = [
+        ...current.choices.filter((item) => item.app !== choice.app || item.id !== choice.id),
+        choice,
+    ];
+    await writeRecord(root, { version: 1, recipes: current.recipes, choices });
+    debug('Recipe record: app choice written', {
+        app: choice.app,
+        id: choice.id,
+        value: choice.value,
+        answeredBy: choice.answeredBy,
+    });
+}
+const ADDRESS = /\b(https?):\/\/([A-Za-z0-9.-]+|\[[0-9A-Fa-f:]+\]):(\d{1,5})(?![\d])/g;
+/** `<scheme>://<host>:<port>` of a URL; undefined when it does not parse. */
+function origin(url) {
+    try {
+        const parsed = new URL(url);
+        return { href: `${parsed.protocol}//${parsed.host}`, hostname: parsed.hostname };
+    }
+    catch (error) {
+        debug('Skipped an app address that is not a URL', { url, error: String(error) });
+        return undefined;
+    }
+}
+/** The current address of the app for `domain`: a url on that host, else the first, else the port. */
+function appOrigin(domain, address) {
+    const origins = address.urls.flatMap((url) => origin(url) ?? []);
+    const match = origins.find((item) => item.hostname === domain) ?? origins[0];
+    if (match)
+        return match.href;
+    return address.port ? `http://${domain}:${address.port}` : undefined;
+}
+/** Whether a recorded notice names the first admin (filled from the project by verify). */
+export function namesFirstAdmin(notice) {
+    return notice.includes(FIRST_ADMIN_PLACEHOLDER) || RECORDED_FIRST_ADMIN.test(notice);
+}
+/** What the no-screens notice said before D-0137 (present tense: false once screens are added). */
+const RECORDED_NO_SCREENS = 'the app answers JSON for other programs; people cannot sign up, browse or press buttons in a browser.';
+/** The same part as the recipe says it now: what the recipe built, true whatever comes later. */
+export const NO_SCREENS_BUILT = 'the recipe built a JSON API for other programs, with no pages where people sign up, browse or press buttons.';
+/**
+ * One recorded notice as the user hears it now. A fact notice (D-0137) is the text verify read
+ * from the project (`facts`, by factKey), or, without it, that the CLI could not read it; '' when
+ * nothing is left to say. Any other notice gets the current app address: the placeholder filled
+ * in, or (a record from before the placeholder) a loopback address whose port is not the app's
+ * replaced by the current one; without a current address the placeholder becomes
+ * `http://<domain>`. The first admin placeholder gets `firstAdmin` (D-0115).
+ */
+export function fillNotice(notice, entry, address, firstAdmin = firstAdminPhrase({ candidates: [] }), facts) {
+    const fact = factOf(notice);
+    if (fact)
+        return facts?.get(factKey(entry.recipe, fact)) ?? unreadText(fact, entry.recipe);
+    if (notice.includes(RECORDED_NO_SCREENS)) {
+        debug('Recorded no-screens notice: said as what the recipe built', { recipe: entry.recipe });
+        notice = notice.replace(RECORDED_NO_SCREENS, NO_SCREENS_BUILT);
+    }
+    if (RECORDED_FIRST_ADMIN.test(notice)) {
+        debug('Recorded login notice: the first admin is read from the project', {
+            recipe: entry.recipe,
+        });
+        notice = notice.replace(RECORDED_FIRST_ADMIN, ` ${FIRST_ADMIN_PLACEHOLDER}; ${LOGIN_PAGES}`);
+    }
+    notice = notice.replaceAll(FIRST_ADMIN_PLACEHOLDER, firstAdmin);
+    const domain = entry.domain ?? 'localhost';
+    if (notice.includes(APP_URL_PLACEHOLDER))
+        return notice.replaceAll(APP_URL_PLACEHOLDER, appOrigin(domain, address) ?? `http://${domain}`);
+    return notice.replace(ADDRESS, (text, scheme, host, port) => {
+        if (!isLoopbackHost(host))
+            return text;
+        const current = appOrigin(host.replace(/^\[|\]$/g, ''), address);
+        if (!current || current === `${scheme}://${host}:${port}`)
+            return text;
+        debug('Recorded notice address replaced by the current one', {
+            recipe: entry.recipe,
+            recorded: `${scheme}://${host}:${port}`,
+            current,
+        });
+        return current;
+    });
+}
+/** What the user hears about an answer the agent chose (D-0095), with its reason when given. */
+export const AI_CHOICE_LINE = 'chosen by the AI (you left the choice to it)';
+/** D-0098: an EJS app added without saying who chose EJS. */
+export const UNSTATED_VIEW_LINE = 'not the default view (Inertia + Vue), and who chose it was not recorded';
 /**
  * The lines for the user's final message: each answer and who chose it (a default with its
- * reason), then the notices. Answers fixed by the recipe itself are not choices and are left out.
+ * reason, an AI choice with the agent's reason when it gave one), then the notices with the
+ * current app address. Answers fixed by the recipe itself are not choices and are left out.
  */
-export function tellUserLines(recipes) {
+export function tellUserLines(recipes, address = { urls: [] }, choices = [], 
+/** firstAdminPhrase of the project now (D-0115); without it, the not-found words. */
+firstAdmin, 
+/** D-0137: the fact notices as verify read them from the project (factTexts). */
+facts) {
     const lines = [];
     for (const entry of recipes) {
         const prefix = recipes.length > 1 ? `[${entry.recipe}] ` : '';
         for (const [id, answer] of Object.entries(entry.answers)) {
             if (answer.answeredBy === 'default')
                 lines.push(`${prefix}${id} = ${answer.value}: chosen by default (${answer.defaultReason ?? 'the recipe default'})`);
-            else if (answer.answeredBy === 'flag')
-                lines.push(`${prefix}${id} = ${answer.value}: ${entry.answersFrom === 'user' ? 'your answer' : 'chosen by the AI (you left the choice to it)'}`);
+            else if (answer.answeredBy === 'user')
+                lines.push(`${prefix}${id} = ${answer.value}: your answer`);
+            else if (answer.answeredBy === 'ai')
+                lines.push(`${prefix}${id} = ${answer.value}: ${AI_CHOICE_LINE}${answer.aiReason ? `: ${answer.aiReason}` : ''}`);
+        }
+        for (const notice of entry.notices) {
+            const text = fillNotice(notice, entry, address, firstAdmin, facts);
+            if (text)
+                lines.push(`${prefix}${text}`);
         }
-        for (const notice of entry.notices)
-            lines.push(`${prefix}${notice}`);
     }
+    // D-0098: the views of apps made outside a recipe, each with who chose it.
+    for (const choice of choices)
+        lines.push(`[app ${choice.app}] ${choice.id} = ${choice.value}: ${choice.answeredBy === 'user'
+            ? 'your answer'
+            : choice.answeredBy === 'ai'
+                ? `${AI_CHOICE_LINE}${choice.aiReason ? `: ${choice.aiReason}` : ''}`
+                : UNSTATED_VIEW_LINE}`);
     return lines;
 }

package/dist/recipe-reset.d.ts

@@ -0,0 +1,2 @@
+import type { LoginFile } from './recipe-login.js';
+export declare function resetFiles(): LoginFile[];

package/dist/recipe-reset.js

@@ -0,0 +1,117 @@
+export function resetFiles() {
+    return [
+        { path: 'src/apps/main/routes/password-reset.ts', content: ROUTES },
+        { path: 'src/apps/main/controllers/password-reset.ts', content: CONTROLLER },
+        { path: 'src/apps/main/views/default/password-forgot.ejs', content: FORGOT },
+        { path: 'src/apps/main/views/default/password-reset.ejs', content: RESET },
+        { path: 'src/shared/mail/password-reset/en/subject.ejs', content: 'Reset your password\n' },
+        {
+            path: 'src/shared/mail/password-reset/en/html.ejs',
+            content: '<p><a href="<%= data.resetUrl %>">Reset your password</a></p><p>This link expires in <%= data.expiresInMinutes %> minutes. If you did not request it, ignore this email.</p>\n',
+        },
+    ];
+}
+const ROUTES = `import type { AppRouter } from '@dokebi/app';
+import { PasswordResetController } from '../controllers/password-reset.ts';
+
+export function passwordResetRoutes(route: AppRouter): void {
+  const controller = new PasswordResetController();
+  route.get(
+    '/password/forgot',
+    (_request, reply, page) => controller.forgotPage(_request, reply, page),
+    { config: { auth: false } },
+  );
+  route.post(
+    '/password/forgot',
+    (request, reply, page) => controller.requestReset(request, reply, page),
+    { config: { auth: false } },
+  );
+  route.get(
+    '/password/reset',
+    (request, reply, page) => controller.resetPage(request, reply, page),
+    { config: { auth: false } },
+  );
+  route.post('/password/reset', (request, reply, page) => controller.reset(request, reply, page), {
+    config: { auth: false },
+  });
+}
+`;
+const CONTROLLER = `// Password recovery. Mail is queued; tokens never go into a session or a log.
+import type { AppPage } from '@dokebi/app';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { validationError } from '@dokebi/web';
+
+export class PasswordResetController {
+  forgotPage(_request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    return page.view.reply(reply, 'password-forgot', { sent: false }, { layout: false });
+  }
+  async requestReset(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    const body = (request.body ?? {}) as Record<string, unknown>;
+    const result = await request.auth.passwordReset.request(
+      typeof body.identity === 'string' ? body.identity : '',
+    );
+    if (!result.ok && result.error) throw result.error;
+    return page.view.reply(reply, 'password-forgot', { sent: true }, { layout: false });
+  }
+  async resetPage(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    const token = (request.query as { token?: unknown }).token;
+    const text = typeof token === 'string' ? token : '';
+    const checked = await request.auth.passwordReset.check(text);
+    return page.view.reply(
+      reply,
+      'password-reset',
+      {
+        token: checked.ok ? text : '',
+        error: checked.ok ? '' : 'This link is invalid or expired. Request another link.',
+      },
+      { layout: false },
+    );
+  }
+  async reset(request: FastifyRequest, reply: FastifyReply, page: AppPage) {
+    const body = (request.body ?? {}) as Record<string, unknown>;
+    const token = typeof body.token === 'string' ? body.token : '';
+    const password = typeof body.password === 'string' ? body.password : '';
+    // A no-referrer page cannot rely on the generic form-back redirect. Render its field error
+    // directly, with the same validationError message, keeping only the token (never password).
+    if (password.length < 12 || Buffer.byteLength(password) > 1024) {
+      const invalid = validationError({
+        password: 'Use at least 12 characters and at most 1024 bytes.',
+      });
+      return page.view.reply(
+        reply.code(422),
+        'password-reset',
+        { token, error: invalid.errors.password },
+        { layout: false },
+      );
+    }
+    const result = await request.auth.passwordReset.complete({ token, password });
+    if (!result.ok) {
+      if (result.error) throw result.error;
+      return page.view.reply(
+        reply.code(422),
+        'password-reset',
+        { token: '', error: 'This link is invalid or expired. Request another link.' },
+        { layout: false },
+      );
+    }
+    return reply.redirect('/login', 303);
+  }
+}
+`;
+// Both pages render without the shared layout ({ layout: false }), so they write the seal head
+// themselves (D-0092 §1.5): on a sealed domain it loads @dokebi/seal/forms, which seals their post
+// forms. `?.` keeps the pages working on an @dokebi/app that does not provide data.seal yet.
+const FORGOT = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="referrer" content="no-referrer"><title>Reset your password</title><%- data.seal?.head ?? '' %></head><body>
+<h1>Reset your password</h1>
+<% if (data.sent) { %><p>If an eligible account exists, a reset link will be emailed to it.</p><% } %>
+<form method="post" action="/password/forgot"><%- data.csrf.field %>
+<label>Login <input name="identity" autocomplete="username" required></label><button>Send reset link</button></form>
+<a href="/login">Back to login</a></body></html>\n`;
+const RESET = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="referrer" content="no-referrer"><title>Choose a password</title><%- data.seal?.head ?? '' %></head><body>
+<h1>Choose a new password</h1><% if (data.error) { %><p role="alert"><%= data.error %></p><% } %>
+<% if (data.token) { %><form method="post" action="/password/reset"><%- data.csrf.field %>
+<input type="hidden" name="token" value="<%= data.token %>">
+<label>New password <input type="password" name="password" autocomplete="new-password" minlength="12" required></label><button>Change password</button></form><% } %>
+<a href="/password/forgot">Request another link</a></body></html>\n`;

package/dist/recipe-site.d.ts

@@ -0,0 +1,48 @@
+import type { Catalog, CatalogRecipe } from './catalog.js';
+import type { Project } from './project.js';
+import { type Answer, type Step } from './recipe-step.js';
+/** Where older site recipes wrote the job worker; it keeps working (doctor LEGACY_LAYOUT). */
+export declare const LEGACY_SITE_WORKER_PATH = "src/site-worker.ts";
+/** Process-level runtime wiring sits in src/infra/runtime, beside the cluster worker factory. */
+export declare const SITE_WORKER_PATH: string;
+/**
+ * The opening of SITE.md, the guide the recipe writes once (kept byte for byte, so a re-run finds
+ * the guide it wrote). Its conditions ("until connected", "needs … before verify") are how the
+ * scaffold starts. D-0137: it is no longer a recorded notice: the record holds the `{fact:site}`
+ * token and verify says what it finds; records written before keep this text and are read the
+ * same way (recipe-facts.ts recordedFact).
+ */
+export declare const SITE_NOTICE = "Site scaffolding separates domains and auth realms. User lookup and login screens are app code: the generated auth extensions deny every login until connected to your user store. Admin and API routes require authentication. A job worker needs a configured NATS connection and a provisioned siteWorker queue before verify; the thread worker handles CPU tasks in this process.";
+/**
+ * The site's apps, domains, realms and worker. `label` is the project's host label (D-0102):
+ * `--domains auto` gives every app `<app>.<label>.localhost`, unique to this project.
+ */
+export declare function siteDefinition(answers: Readonly<Record<string, Answer>>, label: string): {
+    apps: string[];
+    worker: string;
+    domains: Record<string, string>;
+    realms: Record<string, string>;
+    inertia: boolean;
+    ssr: boolean;
+};
+export declare function checkSite(root: string, answers: Readonly<Record<string, Answer>>, label: string): Promise<void>;
+/** The auth extension the site recipe writes: one stub class per realm (exported for its tests). */
+export declare function siteAuthSource(realms: string[]): string;
+/** What the site scaffold's GET /login answers until the app writes its login (verify reads it). */
+export declare const SITE_LOGIN_HINT = "Connect the realm extension to your user store and implement login with request.auth.attempt.";
+/** The routes file of a site app (the scaffold's GET /login lives there). */
+export declare const siteRoutesPath: (app: string) => string;
+/**
+ * A browser app of the site (not api): its host is sealed (D-0092 §1, D-0062), EJS and Inertia
+ * alike. Server rendering cannot be sealed (SEAL_SSR_CONFLICT), so SSR apps stay plain and the
+ * recipe notice says so.
+ */
+export declare function sealedSiteApp(spec: ReturnType<typeof siteDefinition>, app: string): boolean;
+/** Site reuses transactional install/app/config/file commands and the common recipe executor. */
+export declare function siteSteps(catalog: Catalog, _recipe: CatalogRecipe, answers: Readonly<Record<string, Answer>>, context: {
+    root: string;
+    project: Project;
+    port: number;
+    init: boolean;
+    hostLabel: string;
+}): Step[];