@starci/hfs 4.3.0 → 4.4.1

package/scaffold/add-cli-lite.mjs

@@ -109,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]");
@@ -180,6 +185,9 @@ 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],
     [
@@ -203,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"),
@@ -255,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",
@@ -269,9 +277,9 @@ 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 ?? {}),
+    ...packageManifest.scripts,
     ...managedScripts(resolved, appSource(root)),
   };
   for (const [relative, body] of files) {

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 @@
+

package/scaffold/add-fe-page.mjs

@@ -0,0 +1 @@
+

package/scaffold/add-inbox-lite.mjs

@@ -3,6 +3,9 @@ import path from "node:path";
 import { render, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError, pascalOf } from "./service.mjs";
 import { filesBelow } from "./lite-exports.mjs";
+import { jsonText } from "./app.mjs";
+import { byCodeUnit } from "../report/order.mjs";
+import { withSqlIdentifierError } from "./add-database-lite.mjs";
 
 const MIGRATION = /^(\d{14})_[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.sql$/;
 const PLACEHOLDER = /@@([A-Za-z][A-Za-z0-9]*)@@/g;
@@ -50,7 +53,7 @@ function validateProcessingOwner({ root, service, serviceModule, provider }) {
     );
   const owner = path.join(root, "be", "src", "modules", "domain", ...capability.split("/"));
   const candidates = filesBelow(owner).filter((file) =>
-    file.endsWith(".service.ts") && new RegExp(`\\bexport\\s+class\\s+${service}\\b`).test(fs.readFileSync(file, "utf8")),
+    file.endsWith(".service.ts") && new RegExp(String.raw`\bexport\s+class\s+${service}\b`).test(fs.readFileSync(file, "utf8")),
   );
   if (candidates.length !== 1)
     throw new ScaffoldError(
@@ -70,8 +73,10 @@ const databasePatches = (root) => {
     );
   let index = fs.readFileSync(indexFile, "utf8").replace(/\r\n/g, "\n");
   if (!index.includes('export { recordWebhookDelivery } from "./webhook-inbox.client"'))
-    index = `${index.replace(/\n+$/, "")}\nexport { recordWebhookDelivery } from "./webhook-inbox.client"\n`;
-  let error = fs.readFileSync(errorFile, "utf8").replace(/\r\n/g, "\n");
+    index = `${index.trimEnd()}\nexport { recordWebhookDelivery } from "./webhook-inbox.client"\n`;
+  if (!index.split("\n").some((line) => line.startsWith("export { ") && line.includes("DatabaseErrorCode") && line.endsWith(' } from "./errors/database.error"')))
+    index = `${index.trimEnd()}\nexport { DatabaseError, DatabaseErrorCode } from "./errors/database.error"\n`;
+  let error = withSqlIdentifierError(fs.readFileSync(errorFile, "utf8").replace(/\r\n/g, "\n"));
   const enumLine =
     '    WebhookDeliveryIdRequired = "DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED",';
   if (!error.includes(enumLine)) {
@@ -97,44 +102,58 @@ const databasePatches = (root) => {
   ];
 };
 
-const wiredAppModule = ({ root, repo, provider, Provider }) => {
-  const app = repo.sides.be.apps.find((entry) => entry.kind === "api");
-  if (!app)
-    throw new ScaffoldError(
-      "HFS_ADD_NO_API_OWNER",
-      "add webhook needs a declared lite api app",
-    );
-  const file = path.join(root, "be", "apps", app.name, "src", "app.module.ts");
-  const relative = `be/apps/${app.name}/src/app.module.ts`;
-  if (!fs.existsSync(file))
-    throw new ScaffoldError(
-      "HFS_ADD_WIRE_MISSING",
-      `add webhook registers its inbox in ${relative}, which does not exist`,
-    );
-  const symbol = `${Provider}InboxModule`;
-  const importLine = `import { ${symbol} } from "@modules/domain/${provider}-inbox"`;
-  const lines = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n").split("\n");
-  const lastImport = lines.reduce(
-    (last, line, index) => (line.startsWith("import ") ? index : last),
-    -1,
-  );
-  const imports = lines.findIndex((line) => /^\s*imports: \[$/.test(line));
-  if (lastImport < 0 || imports < 0)
-    throw new ScaffoldError(
-      "HFS_ADD_WIRE_INVALID",
-      `add webhook could not find the imports array in ${relative}`,
-    );
-  if (!lines.includes(importLine)) {
-    lines.splice(lastImport + 1, 0, importLine);
-    const shiftedImports = imports > lastImport ? imports + 1 : imports;
-    const indent = /^(\s*)/.exec(lines[shiftedImports])?.[1] ?? "";
-    lines.splice(
-      shiftedImports + 1,
-      0,
-      `${indent}    ${symbol}.register({ isGlobal: true }),`,
-    );
+/** The first webhook installs only the lite inbox claim and transactional event publisher, shared by all providers. */
+const handoffPlatformFiles = (root, values) => {
+  const planned = [];
+  for (const capability of ["inbox", "event-bus"]) {
+    const base = `be/src/modules/platform/${capability}`;
+    if (fs.existsSync(path.join(root, base, "index.ts"))) continue;
+    const folder = path.join(TEMPLATES_DIR, "be", "inbox", "platform", capability);
+    for (const file of filesBelow(folder)) {
+      const relative = path.relative(folder, file).replaceAll("\\", "/");
+      planned.push({
+        relative: `${base}/${relative.replace(/\.tpl$/, "")}`,
+        text: template(`platform/${capability}/${relative}`, values),
+      });
+    }
   }
-  return { file, text: `${lines.join("\n").replace(/\n+$/, "")}\n` };
+  return planned;
+};
+
+/** A provider may already publish other events; retain its barrel and contract when adding the receipt event. */
+const eventFiles = (root, provider, values) => {
+  const entries = [
+    { relative: `be/src/modules/events/${provider}/index.ts`, text: template("event-index.ts.tpl", values) },
+    { relative: `be/contracts/${provider}/events.json`, text: template("events.json.tpl", values) },
+  ];
+  const planned = [];
+  const patches = [];
+  for (const entry of entries) {
+    const file = path.join(root, ...entry.relative.split("/"));
+    if (!fs.existsSync(file)) {
+      planned.push(entry);
+      continue;
+    }
+    const previous = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+    if (entry.relative.endsWith("index.ts")) {
+      patches.push({ file, text: previous.includes(entry.text.trim()) ? previous : `${previous.trimEnd()}\n${entry.text}` });
+    } else {
+      const contract = JSON.parse(previous);
+      if (contract.schema !== "starci/event-contract@1" || contract.service !== provider || !contract.events || Array.isArray(contract.events) || typeof contract.events !== "object")
+        throw new ScaffoldError("HFS_ADD_EVENT_CONTRACT", `${entry.relative} is not the event contract of ${provider}`);
+      const additions = JSON.parse(entry.text).events;
+      contract.events = { ...contract.events, ...additions };
+      patches.push({ file, text: jsonText(contract) });
+    }
+  }
+  return { planned, patches };
+};
+
+const eventPatternPatch = (root) => {
+  const file = path.join(root, "hfs.json");
+  const declaration = JSON.parse(fs.readFileSync(file, "utf8"));
+  declaration.sides.be.patterns = [...new Set([...(declaration.sides.be.patterns ?? []), "event-bus"])].sort(byCodeUnit);
+  return { file, text: jsonText(declaration) };
 };
 
 /** Writes the lite provider inbox. Processing belongs to a separately added reactor or job, after the record commits. */
@@ -152,7 +171,7 @@ export function addLiteWebhookInbox({
   const table = `${snakeOf(provider)}_inbox`;
   const migrationsDir = path.join(root, "supabase", "migrations");
   const migrations = fs.existsSync(migrationsDir)
-    ? fs.readdirSync(migrationsDir).filter((file) => MIGRATION.test(file)).sort()
+    ? fs.readdirSync(migrationsDir).filter((file) => MIGRATION.test(file)).sort(byCodeUnit)
     : [];
   const suffix = `${provider}-inbox.sql`;
   if (migrations.some((file) => file.endsWith(`_${suffix}`)))
@@ -175,6 +194,7 @@ export function addLiteWebhookInbox({
     table,
   };
   const base = `be/src/modules/domain/${provider}-inbox`;
+  const events = eventFiles(root, provider, renderValues);
   const planned = [
     {
       relative: `supabase/migrations/${stamp}_${suffix}`,
@@ -205,7 +225,18 @@ export function addLiteWebhookInbox({
       relative: `${base}/persistence/${provider}-inbox.sql.ts`,
       text: template("sql.ts.tpl", renderValues),
     },
+    {
+      relative: `be/src/modules/events/${provider}/${provider}-delivery-recorded.event.ts`,
+      text: template("delivery-recorded.event.ts.tpl", renderValues),
+    },
+    ...events.planned,
+    ...handoffPlatformFiles(root, renderValues),
   ];
+  const hasHandoffStorage = migrations.some((file) =>
+    /create\s+table\s+public\.event_bus\b/i.test(fs.readFileSync(path.join(migrationsDir, file), "utf8")),
+  );
+  if (!hasHandoffStorage)
+    planned[0].text = `${template("platform/migration.sql.tpl", renderValues)}\n${planned[0].text}`;
   const databaseSql = "be/src/modules/platform/database/database.sql.ts";
   if (!fs.existsSync(path.join(root, ...databaseSql.split("/")))) {
     planned.push({
@@ -249,7 +280,8 @@ export function addLiteWebhookInbox({
     );
   const patches = [
     ...databasePatches(root),
-    wiredAppModule({ root, repo, provider, Provider }),
+    ...events.patches,
+    eventPatternPatch(root),
   ];
   for (const entry of planned) {
     const target = path.join(root, ...entry.relative.split("/"));