@starci/hfs 4.2.17 → 4.4.0

package/scaffold/add-app.mjs

@@ -7,7 +7,7 @@ import {
 } from "../runtime/scripts/hfs/slots.mjs";
 import { imageFiles, render, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError, pascalOf } from "./service.mjs";
-import { PARTIAL_VARIABLES, coreFeApps, jsonText, packageJsonText } from "./app.mjs";
+import { PARTIAL_VARIABLES, bundledPins, callbackSourceFiles, coreFeApps, hasAuthCallback, jsonText, packageJsonText } from "./app.mjs";
 
 /** The shared fe app core (modules/api, auth, toast, redux, the providers, the hooks): the base tree, then the edition overlay. */
 const CORE_DIRS = Object.freeze({
@@ -35,37 +35,8 @@ const fill = (text, values, file) =>
     return values[key];
   });
 
-/**
- * Adds one Next workspace from the edition's canonical app skeleton and the shared app core (both editions, owner ruling
- * 2026-10-13: lite and full have one fe structure), then registers it in hfs.json. The root workspace glob is added only when an
- * older app manifest does not already carry it.
- */
-export function addApp({ root, name }) {
-  if (!NAME.test(String(name)))
-    throw new ScaffoldError(
-      "HFS_ADD_NAME_INVALID",
-      `app name ${name} must be kebab-case (letters, digits and single dashes)`,
-    );
-  const declarationFile = path.join(root, "hfs.json");
-  const packageFile = path.join(root, "package.json");
-  if (!fs.existsSync(declarationFile) || !fs.existsSync(packageFile))
-    throw new ScaffoldError(
-      "HFS_ADD_NOT_AN_APP",
-      "add app runs at the app root containing hfs.json and package.json",
-    );
-  const manifest = loadSlotManifest();
-  const repo = readRepoDeclaration(manifest, root);
-  if (!repo.sides?.fe)
-    throw new ScaffoldError(
-      "HFS_ADD_NO_FRONT_END",
-      "this app has no front-end side",
-    );
-  if (repo.sides.fe.apps.some((app) => app.name === name))
-    throw new ScaffoldError(
-      "HFS_ADD_EXISTS",
-      `front-end app ${name} is already declared`,
-    );
-
+/** Render the edition skeleton followed by its shared core and edition overlay. */
+function planAppTemplates(repo, name) {
   const source = path.join(
     TEMPLATES_DIR,
     "fe",
@@ -94,8 +65,13 @@ export function addApp({ root, name }) {
     if (!fs.existsSync(dir)) continue;
     for (const relative of listFiles(dir)) byPath.set(relative, { relative: `${targetBase}/${relative}`, body: readTemplate(dir, relative) });
   }
-  const planned = [...byPath.values()];
+  return callbackSourceFiles([...byPath.values()].map(file => ({ path: file.relative, content: file.body })), repo)
+    .map(file => ({ relative: file.path, body: file.content }));
+}
 
+/** The package and TypeScript manifests of a new Next workspace. */
+function planWorkspaceManifests(root, repo, name) {
+  const targetBase = `fe/apps/${name}`;
   // The dependency source is a product app (it carries the core's fe-stack packages), else the first Next app.
   const firstApp = coreFeApps(repo.sides.fe.apps)[0] ?? repo.sides.fe.apps.find((app) => app.kind === "next");
   const firstPackage = firstApp
@@ -108,8 +84,14 @@ export function addApp({ root, name }) {
     );
   const workspacePackage = JSON.parse(fs.readFileSync(firstPackage, "utf8"));
   workspacePackage.name = `@${repo.project}/${name}`;
+  if (hasAuthCallback(repo)) {
+    const pins = bundledPins();
+    workspacePackage.dependencies ??= {};
+    for (const dependency of ["@supabase/ssr", "@supabase/supabase-js", "server-only"])
+      workspacePackage.dependencies[dependency] = pins[dependency].version;
+  }
   const appTemplates = path.join(TEMPLATES_DIR, "fe", "app");
-  planned.push(
+  return [
     {
       relative: `${targetBase}/package.json`,
       body:
@@ -121,32 +103,10 @@ export function addApp({ root, name }) {
       relative: `${targetBase}/tsconfig.json`,
       body: fs.readFileSync(path.join(appTemplates, "tsconfig.json"), "utf8"),
     },
-  );
-  const declaration = JSON.parse(fs.readFileSync(declarationFile, "utf8"));
-  declaration.sides.fe.apps.push({ name, kind: "next" });
-  if (repo.edition === "full") {
-    const image = imageFiles(
-      resolveRepoDeclaration(manifest, declaration),
-    ).find((file) => file.path === `${targetBase}/Dockerfile`);
-    if (!image)
-      throw new ScaffoldError(
-        "HFS_ADD_TEMPLATE_MISSING",
-        `the Dockerfile of front-end app ${name} did not render`,
-      );
-    planned.push({ relative: image.path, body: image.content });
-  }
-
-  const clashes = planned
-    .filter((file) =>
-      fs.existsSync(path.join(root, ...file.relative.split("/"))),
-    )
-    .map((file) => file.relative);
-  if (clashes.length)
-    throw new ScaffoldError(
-      "HFS_ADD_EXISTS",
-      `front-end app ${name} already exists: ${clashes.join(", ")}`,
-    );
+  ];
+}
 
+function persistAppFiles({ root, name, planned, declaration, declarationFile, packageFile }) {
   const rootPackage = JSON.parse(fs.readFileSync(packageFile, "utf8"));
   const oldDeclaration = fs.readFileSync(declarationFile, "utf8");
   const oldPackage = fs.readFileSync(packageFile, "utf8");
@@ -173,6 +133,64 @@ export function addApp({ root, name }) {
     fs.writeFileSync(packageFile, oldPackage);
     throw error;
   }
+}
+
+/**
+ * Adds one Next workspace from the edition's canonical app skeleton and the shared app core (both editions, owner ruling
+ * 2026-10-13: lite and full have one fe structure), then registers it in hfs.json. The root workspace glob is added only when an
+ * older app manifest does not already carry it.
+ */
+export function addApp({ root, name }) {
+  if (!NAME.test(String(name)))
+    throw new ScaffoldError(
+      "HFS_ADD_NAME_INVALID",
+      `app name ${name} must be kebab-case (letters, digits and single dashes)`,
+    );
+  const declarationFile = path.join(root, "hfs.json");
+  const packageFile = path.join(root, "package.json");
+  if (!fs.existsSync(declarationFile) || !fs.existsSync(packageFile))
+    throw new ScaffoldError(
+      "HFS_ADD_NOT_AN_APP",
+      "add app runs at the app root containing hfs.json and package.json",
+    );
+  const manifest = loadSlotManifest();
+  const repo = readRepoDeclaration(manifest, root);
+  if (!repo.sides?.fe)
+    throw new ScaffoldError(
+      "HFS_ADD_NO_FRONT_END",
+      "this app has no front-end side",
+    );
+  if (repo.sides.fe.apps.some((app) => app.name === name))
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `front-end app ${name} is already declared`,
+    );
+  const targetBase = `fe/apps/${name}`;
+  const planned = [...planAppTemplates(repo, name), ...planWorkspaceManifests(root, repo, name)];
+  const declaration = JSON.parse(fs.readFileSync(declarationFile, "utf8"));
+  declaration.sides.fe.apps.push({ name, kind: "next" });
+  const image = imageFiles(
+    resolveRepoDeclaration(manifest, declaration),
+  ).find((file) => file.path === `${targetBase}/Dockerfile`);
+  if (!image && repo.edition !== "lite")
+    throw new ScaffoldError(
+      "HFS_ADD_TEMPLATE_MISSING",
+      `the Dockerfile of front-end app ${name} did not render`,
+    );
+  if (image) planned.push({ relative: image.path, body: image.content });
+
+  const clashes = planned
+    .filter((file) =>
+      fs.existsSync(path.join(root, ...file.relative.split("/"))),
+    )
+    .map((file) => file.relative);
+  if (clashes.length)
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `front-end app ${name} already exists: ${clashes.join(", ")}`,
+    );
+
+  persistAppFiles({ root, name, planned, declaration, declarationFile, packageFile });
   return {
     created: planned.map((file) => file.relative),
     registered: { app: name, workspace: "fe/apps/*" },

package/scaffold/add-cli-lite.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveRepoDeclaration } from "../runtime/scripts/hfs/slots.mjs";
 import { parseYaml } from "../runtime/engine/yaml.mjs";
-import { appScripts, imageFiles, TEMPLATES_DIR } from "../sync/index.mjs";
+import { appScripts, appSource, imageFiles, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError } from "./service.mjs";
 import { jsonText, packageJsonText } from "./app.mjs";
 import { registerLiteExports } from "./lite-exports.mjs";
@@ -15,14 +15,12 @@ const read = (relative) =>
 const PINS_FILE = path.join(import.meta.dirname, "..", "runtime", "knowledge", "hfs", "canon-pins.yaml");
 
 
-const managedScripts = (repo) => {
-  const fragment = appScripts(repo).replace(/,\s*$/, "");
+const managedScripts = (repo, source) => {
+  const fragment = appScripts(repo, source).replace(/,\s*$/, "");
   return fragment === "" ? {} : JSON.parse(`{${fragment}}`);
 };
 
-const CLI_OPTIONS = `import type { EnvSource } from "@modules/platform/config"
-import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
-import type { DatabaseConnectionOptions } from "@modules/platform/database"
+const CLI_OPTIONS = `import type { DatabaseConnectionOptions } from "@modules/platform/database"
 
 /** Everything the lite cli needs: the least-privilege Supabase PostgreSQL connection. */
 export interface CliAppOptions {
@@ -30,9 +28,9 @@ export interface CliAppOptions {
     readonly connections: ReadonlyArray<DatabaseConnectionOptions>
 }
 
-/** Reads the one declared connection without adding entities or TypeORM migrations. */
-export const parseCliAppOptions = (env: EnvSource): CliAppOptions => ({
-    connections: [parsePrimaryDatabaseConfig(env)],
+/** Uses the parsed connection without adding entities or TypeORM migrations. */
+export const createCliAppOptions = (primary: DatabaseConnectionOptions): CliAppOptions => ({
+    connections: [primary],
 })
 `;
 
@@ -111,10 +109,15 @@ function enableLiteCliDatabase(root) {
     text = text.replace(anchor, `${anchor}\nimport { MigrationRunnerService } from "./migration-runner.service"`);
   }
   if (!text.includes('import { SeedRunnerService } from "./seed-runner.service"')) {
-    const anchor = 'import { PRIMARY_ENTITY_MANAGER } from "./primary.decorators"';
-    if (!text.includes(anchor)) throw new ScaffoldError("HFS_ADD_CLI_DATABASE", `${relative} has an unknown import shape`);
+    // The import of the entity-manager token, with or without the probe token beside it.
+    const anchor = /^import \{[^}]*\bPRIMARY_ENTITY_MANAGER\b[^}]*\} from "\.\/primary\.decorators"$/m.exec(text)?.[0];
+    if (!anchor) throw new ScaffoldError("HFS_ADD_CLI_DATABASE", `${relative} has an unknown import shape`);
     text = text.replace(anchor, `${anchor}\nimport { SeedRunnerService } from "./seed-runner.service"`);
   }
+  const probeProviders = "providers: [...(base.providers ?? []), ...managers, ...probes]";
+  if (text.includes(probeProviders)) {
+    text = text.replace(probeProviders, "providers: [...(base.providers ?? []), ...managers, ...probes, MigrationRunnerService, SeedRunnerService]");
+  }
   const providers = "providers: [...(base.providers ?? []), ...managers]";
   if (text.includes(providers)) {
     text = text.replace(providers, "providers: [...(base.providers ?? []), ...managers, MigrationRunnerService, SeedRunnerService]");
@@ -142,7 +145,7 @@ function enableLiteCliDatabase(root) {
 }
 
 /**
- * Creates the optional lite cli app and its Supabase migrate/seed groups on first `add cli`.
+ * Creates the optional lite cli app, its typed CliEnv/readCliEnv boundary and Supabase migrate/seed groups on first `add cli`.
  * Existing cli trees are never repaired or overwritten: drift remains a check finding.
  */
 export function ensureLiteCli({ root, manifest, repo }) {
@@ -182,6 +185,10 @@ export function ensureLiteCli({ root, manifest, repo }) {
       "be/apps/cli/src/app.module.ts",
       read("be/skeleton/apps/cli/src/app.module.ts"),
     ],
+    ["be/apps/cli/src/compose/platform.ts", read("be/skeleton-lite/apps/cli/src/compose/platform.ts")],
+    ["be/apps/cli/src/compose/cli.ts", read("be/skeleton/apps/cli/src/compose/cli.ts")],
+    ["be/src/tests/fixtures/builders/cli.builder.ts", read("be/skeleton-lite/src/tests/fixtures/builders/cli.builder.ts")],
+    ["be/apps/cli/src/cli.env.ts", read("be/skeleton-lite/apps/cli/src/cli.env.ts")],
     ["be/apps/cli/src/cli.options.ts", CLI_OPTIONS],
     [
       "be/src/features/cli/index.ts",
@@ -204,7 +211,7 @@ export function ensureLiteCli({ root, manifest, repo }) {
       read("be/skeleton-lite/src/modules/platform/database/migration-runner.service.ts"),
     ],
     ["be/src/features/cli/migrate/subs/run.cli.ts", MIGRATE_RUN],
-    // Owner ruling 2026-10-12: each cli command of a lite back end owes its unit spec, as in full (ruleParams.be.unitRoles).
+    // ruling:R212/case-1, amended by ruling:R212/case-4: each cli command of a lite back end owes its unit spec, as in full (ruleParams.be.unitRoles).
     [
       "be/src/features/cli/migrate/migrate.cli.spec.ts",
       read("be/skeleton/src/features/cli/migrate/migrate.cli.spec.ts"),
@@ -256,7 +263,7 @@ export function ensureLiteCli({ root, manifest, repo }) {
     );
   const nest = JSON.parse(fs.readFileSync(nestFile, "utf8"));
   nest.projects = {
-    ...(nest.projects ?? {}),
+    ...nest.projects,
     cli: {
       type: "application",
       root: "apps/cli",
@@ -270,10 +277,10 @@ export function ensureLiteCli({ root, manifest, repo }) {
   const pin = parseYaml(fs.readFileSync(PINS_FILE, "utf8")).pins?.["nest-commander"]?.version;
   if (typeof pin !== "string" || pin === "")
     throw new ScaffoldError("HFS_ADD_CANON_PIN_MISSING", "add cli needs the nest-commander canon pin");
-  packageManifest.dependencies = { ...(packageManifest.dependencies ?? {}), "nest-commander": pin };
+  packageManifest.dependencies = { ...packageManifest.dependencies, "nest-commander": pin };
   packageManifest.scripts = {
-    ...(packageManifest.scripts ?? {}),
-    ...managedScripts(resolved),
+    ...packageManifest.scripts,
+    ...managedScripts(resolved, appSource(root)),
   };
   for (const [relative, body] of files) {
     const target = path.join(root, ...relative.split("/"));

package/scaffold/add-compose.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { TEMPLATES_DIR } from '../sync/index.mjs';
+import { ScaffoldError } from './service.mjs';
+
+/** Adds `importLine` and one `symbol` entry of the `imports` array of a module file's lines, once. */
+export function addModuleImport(lines, { importLine, entry, relative, noun }) {
+  const active = compositionCode(lines.join('\n')).split('\n');
+  const imported = active.some(line => line.replace(/;\s*$/, '') === importLine);
+  const registered = active.some(line => line.trim() === `${entry},` ||
+    (/\bimports:\s*\[/.test(line) && !line.trim().startsWith('//') && line.replace(/\s+/g, '').includes(entry.replace(/\s+/g, ''))));
+  const lastImport = active.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
+  const importsLine = line => /\bimports:\s*\[/.test(line) && !line.trim().startsWith('//');
+  if (lastImport < 0 || active.findIndex(importsLine) < 0) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add ${noun} could not find the imports array in ${relative}`);
+  if (imported && registered) return;
+  if (!imported) lines.splice(lastImport + 1, 0, importLine);
+  if (registered) return;
+  const imports = compositionCode(lines.join('\n')).split('\n').findIndex(importsLine);
+  const indent = /^(\s*)/.exec(lines[imports])?.[1] ?? '';
+  if (/^\s*imports: \[$/.test(lines[imports])) lines.splice(imports + 1, 0, `${indent}    ${entry},`);
+  else lines[imports] = lines[imports].replace(/(\bimports:\s*\[)\s*/, `$1${entry}, `);
+}
+
+/** Masks comments without changing offsets or treating quoted module specifiers as comments. */
+export function compositionCode(text) {
+  return text.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g,
+    value => value.startsWith('/') ? value.replace(/[^\r\n]/g, ' ') : value);
+}
+
+
+/** Reads the explicitly typed expression body of a group without treating comments as active declarations. */
+export function readComposeGroup({ repoRoot, repo, app, area, noun }) {
+  const relative = `be/apps/${app}/src/compose/${area}.ts`;
+  const file = path.join(repoRoot, ...relative.split('/'));
+  const exists = fs.existsSync(file);
+  const skeleton = repo.edition === 'lite' ? 'skeleton-lite/apps/api' : 'skeleton/apps/__app__';
+  const template = path.join(TEMPLATES_DIR, 'be', ...skeleton.split('/'), 'src', 'compose', `${area}.ts`);
+  const text = fs.readFileSync(exists ? file : template, 'utf8').replace(/\r\n/g, '\n');
+  const argument = area === 'domain' && repo.edition === 'lite' ? 'verifyAccessToken: VerifySupabaseAccessToken' : '';
+  const marker = `export const ${area}Modules = (${argument}): Array<Type<unknown> | DynamicModule> => [`;
+  const declarationAt = compositionCode(text).indexOf(`\n${marker}`);
+  const active = declarationAt >= 0;
+  const tail = active ? text.slice(declarationAt + 1 + marker.length).trimEnd().replace(/;$/, '').trimEnd() : '';
+  const body = tail.endsWith(']') ? tail.slice(0, -1) : undefined;
+  if (body === undefined) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add ${noun} needs the typed ${area}Modules group in ${relative}`);
+  return { relative, file, exists, text, marker, body };
+}
+
+/** Creates a typed group from the edition's template, or adds members without duplicating inline registrations or semicolon imports. */
+export function planComposeGroup(input) {
+  const { relative, file, exists, marker, body, text: original } = readComposeGroup(input);
+  let text = original;
+  let compactBody = compositionCode(body).replace(/\s+/g, '');
+  for (const { importLine, entry } of input.entries) {
+    const lines = text.split('\n');
+    if (!lines.some(line => line.replace(/;\s*$/, '') === importLine)) {
+      const lastImport = lines.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
+      lines.splice(lastImport + 1, 0, importLine);
+      text = lines.join('\n');
+    }
+    const compactEntry = entry.replace(/\s+/g, '');
+    const members = `,${compactBody},`;
+    if (!members.includes(`,${compactEntry},`)) {
+      const afterMarker = compositionCode(text).indexOf(marker) + marker.length;
+      const empty = text.slice(afterMarker).startsWith(']');
+      text = `${text.slice(0, afterMarker)}\n    ${entry},${empty ? '\n' : ''}${text.slice(afterMarker)}`;
+      compactBody = `${compactEntry},${compactBody}`;
+    }
+  }
+  return { relative, file, exists, text };
+}
+
+/** Writes the planned group and reports a newly created composition file. */
+export function writeComposeGroup(input) {
+  const { relative, file, exists, text } = planComposeGroup(input);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  return exists ? [] : [relative];
+}

package/scaffold/add-database-lite.mjs

@@ -0,0 +1,14 @@
+import { ScaffoldError } from './service.mjs';
+
+/** Enables the lazy SQL identifier guard's error family when a lite generator installs database.sql.ts. */
+export function withSqlIdentifierError(text) {
+  const code = '    IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",';
+  if (text.includes(code)) return text;
+  const enumMarker = 'export enum DatabaseErrorCode {';
+  const kindsMarker = 'export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {';
+  if (!text.includes(enumMarker) || !text.includes(kindsMarker)) {
+    throw new ScaffoldError('HFS_ADD_DATABASE_ERROR', 'platform/database has an unknown error-family shape');
+  }
+  return text.replace(enumMarker, enumMarker + '\n    /** A dynamic SQL identifier was not on the names its caller allows. */\n' + code)
+    .replace(kindsMarker, kindsMarker + '\n    [DatabaseErrorCode.IdentifierRejected]: "internal",');
+}

package/scaffold/add-fe-overlay.mjs

@@ -0,0 +1,122 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { ScaffoldError, pascalOf } from "./service.mjs";
+import { feName, readFeContext, readFeFile, requireNewFeOwner, planFeCatalogs, writeFePlan } from "./add-fe-page.mjs";
+
+function loadTypeScript(root) {
+  try { return createRequire(path.join(root, "package.json"))("typescript"); } catch {
+    throw new ScaffoldError("HFS_ADD_TYPESCRIPT_MISSING", "add overlay reads the host page with its installed TypeScript compiler");
+  }
+}
+
+function pageArrow(ts, source, symbol) {
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    const candidate = statement.declarationList.declarations.find((declaration) => declaration.name.getText(source) === symbol);
+    if (candidate?.initializer && ts.isArrowFunction(candidate.initializer)) return candidate.initializer;
+  }
+  return null;
+}
+
+function pageRender(ts, arrow) {
+  if (!arrow) return null;
+  if (!ts.isBlock(arrow.body)) {
+    let body = arrow.body;
+    while (ts.isParenthesizedExpression(body)) body = body.expression;
+    return body;
+  }
+  const returns = arrow.body.statements.filter(ts.isReturnStatement);
+  const unconditional = arrow.body.statements.every((statement) => ts.isVariableStatement(statement) || ts.isExpressionStatement(statement) || ts.isReturnStatement(statement));
+  if (!unconditional || returns.length !== 1) return null;
+  let render = returns[0].expression;
+  while (render && ts.isParenthesizedExpression(render)) render = render.expression;
+  return render;
+}
+
+function mountOverlay({ ts, before, relative, pageSymbol, symbol }) {
+  const source = ts.createSourceFile(relative, before, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const client = source.statements.some((statement) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression) && statement.expression.text === "use client");
+  const render = pageRender(ts, pageArrow(ts, source, pageSymbol));
+  const isJsx = render && (ts.isJsxElement(render) || ts.isJsxSelfClosingElement(render) || ts.isJsxFragment(render));
+  if (source.parseDiagnostics.length || client || !isJsx) {
+    throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `${relative} must export the server ${pageSymbol} arrow with one unconditional JSX return`);
+  }
+  if (before.split(/[^A-Za-z0-9_]/).includes(symbol)) {
+    throw new ScaffoldError("HFS_ADD_EXISTS", `${relative} already references ${symbol}`);
+  }
+  const from = render.getStart(source);
+  const wrapped = ["(", "        <>", `            ${before.slice(from, render.end)}`, `            <${symbol} />`, "        </>", "    )"].join("\n");
+  const body = before.slice(0, from) + wrapped + before.slice(render.end);
+  const imports = source.statements.filter(ts.isImportDeclaration);
+  const last = imports.at(-1)?.end ?? 0;
+  const importLine = `import { ${symbol} } from "@/features/overlays/${symbol}"`;
+  return `${body.slice(0, last)}\n${importLine}${body.slice(last)}`;
+}
+
+function overlaySources(symbol, namespace) {
+  return {
+    entry: `"use client"
+
+import { useTranslations } from "next-intl"
+import { ${symbol}Base } from "./component"
+
+/** Resolve the overlay's copy at its client interaction boundary. */
+export const ${symbol} = () => {
+    const t = useTranslations(${JSON.stringify(namespace)})
+    return <${symbol}Base props={{ title: t("title"), open: t("open"), close: t("close"), description: t("description") }} />
+}
+`,
+    component: `import { Button, Dialog, Text } from "@starci/grammar/common"
+
+/** Settled labels and content for the overlay's accessible dialog. */
+export interface ${symbol}BaseProps {
+    readonly props: {
+        readonly title: string
+        readonly open: string
+        readonly close: string
+        readonly description: string
+    }
+}
+
+/** Draw an accessible dialog with an intrinsic trigger and dismissal. */
+export const ${symbol}Base = (props: ${symbol}BaseProps) => (
+    <Dialog
+        title={props.props.title}
+        closeLabel={props.props.close}
+        trigger={<Button>{props.props.open}</Button>}
+    >
+        <Text>{props.props.description}</Text>
+    </Dialog>
+)
+`,
+  };
+}
+
+/** Add a localized client overlay and mount its public entry in a server feature page. */
+export function addFeOverlay({ root, app, name, page, messages, ts }) {
+  feName(name, "overlay name");
+  if (page === undefined) throw new ScaffoldError("HFS_ADD_OPTION_MISSING", "add overlay needs --page naming its server feature page");
+  feName(page, "host page name");
+  const context = readFeContext({ root, app });
+  const symbol = `${pascalOf(name)}Overlay`;
+  const owner = `${context.source}/features/overlays/${symbol}`;
+  requireNewFeOwner(context, owner);
+  const pageSymbol = `${pascalOf(page)}Page`;
+  const relative = `${context.source}/features/pages/${pageSymbol}/index.tsx`;
+  const before = readFeFile(context, relative);
+  const body = mountOverlay({ ts: ts ?? loadTypeScript(context.root), before, relative, pageSymbol, symbol });
+  const catalogs = planFeCatalogs(context, {
+    group: "overlays", name, messages,
+    defaults: {
+      vi: { title: "Th\u00f4ng tin", open: "M\u1edf th\u00f4ng tin", close: "\u0110\u00f3ng", description: "Xem th\u00f4ng tin c\u1ee7a trang n\u00e0y." },
+      en: { title: "Information", open: "Open information", close: "Close", description: "View information about this page." },
+    },
+  });
+  const sources = overlaySources(symbol, catalogs.namespace);
+  const created = [
+    { relative: `${owner}/index.tsx`, body: sources.entry },
+    { relative: `${owner}/component.tsx`, body: sources.component },
+  ];
+  const updates = [...catalogs.updates, { relative, before, body }];
+  return { ...writeFePlan(context, created, updates), registered: { app: context.app, overlay: symbol, page: pageSymbol } };
+}