@starci/hfs 4.3.0 → 4.4.0

package/scaffold/add-table.mjs

@@ -10,6 +10,8 @@ import { ScaffoldError, pascalOf } from "./service.mjs";
 import { filesBelow, registerLiteDomainService, registerLiteExports, registrationFiles } from "./lite-exports.mjs";
 import { byCodeUnit } from "../report/order.mjs";
 import { coreFeApps } from "./app.mjs";
+import { addModuleImport, planComposeGroup } from "./add-compose.mjs";
+import { withSqlIdentifierError } from "./add-database-lite.mjs";
 
 const NAME = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const MIGRATION = /^(\d{14})_[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.sql$/;
@@ -163,29 +165,6 @@ function removeEmptyParents(file, stop) {
 /** The app-root relative path of a file under the app (posix). */
 const at = (root, relative) => path.join(root, ...relative.split("/"));
 
-/**
- * Registers `entry` in the `imports` array of a Nest module file (one import line after the last import, one array entry right
- * after `imports: [`), unless `symbol` is already imported. Returns the new text.
- */
-function wireImport(text, relative, { importLine, symbol, entry, kinds }) {
-  const lines = text.replace(/\r\n/g, "\n").split("\n");
-  if (lines.some((line) => line.startsWith("import ") && new RegExp(`\\b${symbol}\\b`).test(line))) return text;
-  const lastImport = lines.reduce((last, line, index) => (line.startsWith("import ") ? index : last), -1);
-  if (lastImport < 0 || lines.findIndex((line) => /^\s*imports: \[$/.test(line)) < 0)
-    throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `add table could not find the imports array in ${relative}`);
-  lines.splice(lastImport + 1, 0, importLine);
-  const imports = lines.findIndex((line) => /^\s*imports: \[$/.test(line));
-  const indent = /^(\s*)/.exec(lines[imports])?.[1] ?? "";
-  lines.splice(imports + 1, 0, `${indent}    ${entry},`);
-  if (kinds !== undefined) {
-    const kindsAt = lines.findIndex((line) => /^\s*kinds: \[$/.test(line));
-    if (kindsAt < 0) throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `add table could not find the error kinds array in ${relative}`);
-    const kindsIndent = /^(\s*)/.exec(lines[kindsAt])?.[1] ?? "";
-    lines.splice(kindsAt + 1, 0, `${kindsIndent}    ${kinds},`);
-  }
-  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
-}
-
 /** A line that opens the error kinds array of the errors registration. */
 const KINDS_LINE = /^\s*kinds: \[$/;
 
@@ -206,45 +185,33 @@ function kindsHomeOf(root, appRelative) {
 /** A composition group after `kinds` is listed first in its error kinds array and imported from `specifier`. Returns the new text. */
 function wireKinds(text, relative, { kinds, specifier }) {
   const lines = text.replace(/\r\n/g, "\n").split("\n");
-  if (lines.some((line) => line.startsWith("import ") && new RegExp(`\\b${kinds}\\b`).test(line))) return text;
+  if (lines.some((line) => line.startsWith("import ") && new RegExp(String.raw`\b${kinds}\b`).test(line))) return text;
   const lastImport = lines.reduce((last, line, index) => (line.startsWith("import ") ? index : last), -1);
   const kindsAt = lines.findIndex((line) => KINDS_LINE.test(line));
   if (lastImport < 0 || kindsAt < 0) throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `add table could not find the error kinds array in ${relative}`);
   const kindsIndent = /^(\s*)/.exec(lines[kindsAt])?.[1] ?? "";
   lines.splice(kindsAt + 1, 0, `${kindsIndent}    ${kinds},`);
   lines.splice(lastImport + 1, 0, `import { ${kinds} } from "${specifier}"`);
-  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+  return `${lines.join("\n").trimEnd()}\n`;
 }
 
-/**
- * The api app root after the table's domain module is registered: its module, and its error kinds too when the root holds the
- * kinds array (`kindsInRoot`); otherwise wireKinds lists them in the composition group that does.
- */
-const wireDomainModule = (text, relative, name, { kindsInRoot = true } = {}) =>
-  wireImport(text, relative, {
-    importLine: kindsInRoot
-      ? `import { ${snakeOf(name).toUpperCase()}_ERROR_KINDS, ${pascalOf(name)}Module } from "@modules/domain/${name}"`
-      : `import { ${pascalOf(name)}Module } from "@modules/domain/${name}"`,
-    symbol: `${pascalOf(name)}Module`,
-    entry: `${pascalOf(name)}Module.register({ isGlobal: true })`,
-    ...(kindsInRoot ? { kinds: `${snakeOf(name).toUpperCase()}_ERROR_KINDS` } : {}),
+/** Plans the domain and API area groups of the connection owner, keeping registrations out of app.module.ts. */
+function tableComposition({ root, repo, owner, feature, fe, ownerRelative }) {
+  const domain = { importLine: `import { ${pascalOf(feature)}Module } from "@modules/domain/${feature}"`, entry: `${pascalOf(feature)}Module.register({ isGlobal: true })` };
+  const groups = [['domain', [domain]]];
+  if (fe) groups.push(['api', [
+    { importLine: 'import { GraphqlModule } from "@modules/platform/graphql"', entry: 'GraphqlModule.register({ isGlobal: true })' },
+    { importLine: `import { ${pascalOf(feature)}GraphqlModule } from "@features/api/${feature}"`, entry: `${pascalOf(feature)}GraphqlModule.register({})` },
+  ]]);
+  const lines = fs.readFileSync(at(root, ownerRelative), 'utf8').replace(/\r\n/g, '\n').split('\n');
+  const patches = groups.map(([area, entries]) => {
+    const argument = area === 'domain' && repo.edition === 'lite' ? 'verifyAccessToken' : '';
+    addModuleImport(lines, { importLine: `import { ${area}Modules } from "./compose/${area}"`, entry: `...${area}Modules(${argument})`, relative: ownerRelative, noun: 'table' });
+    return planComposeGroup({ repoRoot: root, repo, app: owner.name, area, noun: 'table', entries });
   });
-
-/** The api app root after the GraphQL server (platform/graphql) and the table's GraphQL transport are registered. */
-const wireGraphqlFeature = (text, relative, name) =>
-  wireImport(
-    wireImport(text, relative, {
-      importLine: 'import { GraphqlModule } from "@modules/platform/graphql"',
-      symbol: "GraphqlModule",
-      entry: "GraphqlModule.register({ isGlobal: true })",
-    }),
-    relative,
-    {
-      importLine: `import { ${pascalOf(name)}GraphqlModule } from "@features/api/${name}"`,
-      symbol: `${pascalOf(name)}GraphqlModule`,
-      entry: `${pascalOf(name)}GraphqlModule`,
-    },
-  );
+  patches.push({ relative: ownerRelative, text: lines.join('\n') });
+  return patches;
+}
 
 /** The platform GraphQL server capability (templates/be/platform/graphql), whole or absent: written once, by the first GraphQL feature. */
 const GRAPHQL_PLATFORM = "be/src/modules/platform/graphql";
@@ -287,7 +254,7 @@ const GRAPHQL_URL_READER = [
 
 /** An app's modules/config text with graphqlUrl appended once. */
 const withGraphqlUrl = (text) =>
-  /^export const graphqlUrl\b/m.test(text) ? text : `${text.replace(/\s*$/, "")}\n${GRAPHQL_URL_READER}\n`;
+  /^export const graphqlUrl\b/m.test(text) ? text : `${text.trimEnd()}\n${GRAPHQL_URL_READER}\n`;
 
 /** The be api feature of a table (owner ruling 2026-10-13, lite = full): get-<singular> and create-<singular> over GraphQL. */
 const apiFeatureFiles = (values) => {
@@ -296,6 +263,8 @@ const apiFeatureFiles = (values) => {
   const create = `create-${values.singular}`;
   return [
     [`${base}/index.ts`, "feature.index.ts.tpl"],
+    [`${base}/${values.name}.options.ts`, "feature.options.ts.tpl"],
+    [`${base}/${values.name}.module-definition.ts`, "feature.module-definition.ts.tpl"],
     [`${base}/${values.name}.module.ts`, "feature.module.ts.tpl"],
     [`${base}/application/${get}.query.ts`, "get.query.ts.tpl"],
     [`${base}/application/${get}.handler.ts`, "get.handler.ts.tpl"],
@@ -310,6 +279,8 @@ const apiFeatureFiles = (values) => {
     [`${base}/transport/graphql/${create}.resolver.ts`, "create.resolver.ts.tpl"],
     [`${base}/transport/graphql/${create}.mapper.ts`, "create.mapper.ts.tpl"],
     [`${base}/transport/graphql/dto/${create}.type.ts`, "create.type.ts.tpl"],
+    [`${base}/transport/graphql/${values.name}-graphql.options.ts`, "graphql.options.ts.tpl"],
+    [`${base}/transport/graphql/${values.name}-graphql.module-definition.ts`, "graphql.module-definition.ts.tpl"],
     [`${base}/transport/graphql/${values.name}-graphql.module.ts`, "graphql.module.ts.tpl"],
   ].map(([relative, file]) => ({ relative, body: template(`be/table/api/${file}`, values) }));
 };
@@ -351,7 +322,7 @@ const feBarrels = (app, values) => {
 const withExport = (text, line) => {
   const lines = text.replace(/\r\n/g, "\n").split("\n").filter(Boolean);
   if (lines.includes(line)) return text;
-  return `${[...lines, line].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).join("\n")}\n`;
+  return `${[...lines, line].sort(byCodeUnit).join("\n")}\n`;
 };
 
 /**
@@ -359,13 +330,7 @@ const withExport = (text, line) => {
  * server capability on first use) and, in every product Next app, its operation files and SWR hooks.
  * `emitTypes` returns the generated database.types.ts text; false is the explicit `--no-types` seam.
  */
-export function addTable({
-  root,
-  name,
-  fe = false,
-  emitTypes = emitDbTypes,
-  now = Date.now,
-}) {
+function tableContext({ root, name }) {
   const requestedName = String(name);
   if (!NAME.test(requestedName))
     throw new ScaffoldError(
@@ -384,12 +349,16 @@ export function addTable({
     );
   }
 
+  return { root, name, requestedName, feature, table, repo, connection };
+}
+
+function nextMigration({ root, feature, requestedName, now }) {
   const migrationsDir = path.join(root, "supabase", "migrations");
   const migrations = fs.existsSync(migrationsDir)
     ? fs
         .readdirSync(migrationsDir)
         .filter((file) => MIGRATION.test(file))
-        .sort()
+        .sort(byCodeUnit)
     : [];
   if (migrations.some((file) => file.endsWith(`_${feature}.sql`)))
     throw new ScaffoldError(
@@ -404,6 +373,10 @@ export function addTable({
       `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`,
     );
 
+  return stamp;
+}
+
+function tableValues({ feature, table }) {
   const singular = singularOf(feature);
   const values = {
     name: feature,
@@ -417,12 +390,20 @@ export function addTable({
     singularCamel: camelOf(singular),
     singularUpper: snakeOf(singular).toUpperCase(),
   };
+  return values;
+}
+
+function productApps(repo, fe) {
   const apps = fe ? coreFeApps(repo.sides?.fe?.apps ?? []) : [];
   if (fe && !apps.length)
     throw new ScaffoldError(
       "HFS_ADD_NO_FRONT_END",
       "add table --fe needs at least one declared product Next app",
     );
+  return apps;
+}
+
+function tableFiles({ root, repo, feature, stamp, values, fe, apps }) {
   const api = fe ? ".api" : "";
   const domain = `be/src/modules/domain/${feature}`;
   const planned = [
@@ -455,6 +436,10 @@ export function addTable({
     }
   }
 
+  return planned;
+}
+
+function tableOwner({ root, repo, connection, name, requestedName, planned }) {
   const clash = planned
     .filter((file) => fs.existsSync(at(root, file.relative)))
     .map((file) => file.relative);
@@ -470,8 +455,10 @@ export function addTable({
   if (!fs.existsSync(at(root, ownerRelative)))
     throw new ScaffoldError("HFS_ADD_WIRE_MISSING", `add table registers ${name} in ${ownerRelative}, which does not exist`);
 
-  // Every existing file this run edits, as it was: restored on any failure, with every created file removed.
-  const touched = new Map();
+  return { owner, ownerRelative };
+}
+
+function tableEditor(root, touched) {
   const edit = (relative, change) => {
     const file = at(root, relative);
     if (!touched.has(file)) touched.set(file, fs.existsSync(file) ? fs.readFileSync(file) : null);
@@ -481,38 +468,51 @@ export function addTable({
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, after);
   };
-  const created = [];
-  try {
-    for (const file of planned) {
-      const target = at(root, file.relative);
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, file.body);
-      created.push(target);
-    }
-    if (typeof emitTypes === "function") {
-      const generated = emitTypes({ root });
-      if (typeof generated === "string") edit(dbTypesPath, () => generated);
-    }
-    const kindsHome = kindsHomeOf(root, ownerRelative);
-    const kindsInRoot = kindsHome === ownerRelative;
-    edit(ownerRelative, (text) => wireDomainModule(text, ownerRelative, feature, { kindsInRoot }));
-    if (!kindsInRoot)
-      edit(kindsHome, (text) => wireKinds(text, kindsHome, { kinds: `${snakeOf(feature).toUpperCase()}_ERROR_KINDS`, specifier: `@modules/domain/${feature}` }));
+  return edit;
+}
+
+function writeTableFiles({ root, planned, emitTypes, edit }, created) {
+  for (const file of planned) {
+    const target = at(root, file.relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, file.body);
+    created.push(target);
+  }
+  if (typeof emitTypes === "function") {
+    const generated = emitTypes({ root });
+    if (typeof generated === "string") edit(dbTypesPath, () => generated);
+  }
+
+}
+
+function tableRegistrations({ root, repo, fe, edit }) {
+  const errorFile = "be/src/modules/platform/database/errors/database.error.ts";
+  if (repo.edition === "lite" && fs.existsSync(at(root, errorFile))) edit(errorFile, withSqlIdentifierError);
     const registrations = [
       ...(repo.edition === "lite" ? ["table"] : []),
       ...(fe ? ["api", "graphql"] : []),
     ];
     for (const generator of registrations) for (const relative of registrationFiles(generator)) edit(relative, (text) => text);
     for (const generator of registrations) registerLiteExports({ root, generator });
-    if (fe) {
+}
+
+function wireTableFrontends({ root, feature, values, apps, edit }) {
       registerLiteDomainService({ root, moduleSpecifier: `@modules/domain/${feature}`, service: `${values.Name}Service` });
-      edit(ownerRelative, (text) => wireGraphqlFeature(text, ownerRelative, feature));
       for (const app of apps) {
         for (const [relative, line] of feBarrels(app.name, values)) edit(relative, (text) => withExport(text, line));
         edit(`fe/apps/${app.name}/src/modules/config/index.ts`, withGraphqlUrl);
       }
-    }
-  } catch (error) {
+}
+
+function wireTable({ root, repo, feature, values, ownerRelative, composition, fe, apps, edit }) {
+    const kindsHome = kindsHomeOf(root, ownerRelative);
+    for (const patch of composition) edit(patch.relative, () => patch.text);
+    edit(kindsHome, (text) => wireKinds(text, kindsHome, { kinds: `${snakeOf(feature).toUpperCase()}_ERROR_KINDS`, specifier: `@modules/domain/${feature}` }));
+  tableRegistrations({ root, repo, fe, edit });
+  if (fe) wireTableFrontends({ root, feature, values, apps, edit });
+}
+
+function rollbackTable(root, touched, created) {
     for (const [file, before] of touched) {
       if (before === null) fs.rmSync(file, { force: true });
       else fs.writeFileSync(file, before);
@@ -522,10 +522,33 @@ export function addTable({
       removeEmptyParents(file, root);
     }
     for (const [file, before] of touched) if (before === null) removeEmptyParents(file, root);
+}
+
+function applyTable(context) {
+  const touched = new Map();
+  const created = [];
+  const edit = tableEditor(context.root, touched);
+  try {
+    writeTableFiles({ ...context, edit }, created);
+    wireTable({ ...context, edit });
+  } catch (error) {
+    rollbackTable(context.root, touched, created);
     throw error;
   }
+}
+
+/** Adds one table through typed domain/API groups and restores every touched byte on failure. */
+export function addTable({ root, name, fe = false, emitTypes = emitDbTypes, now = Date.now }) {
+  const context = tableContext({ root, name });
+  const stamp = nextMigration({ ...context, now });
+  const values = tableValues(context);
+  const apps = productApps(context.repo, fe);
+  const planned = tableFiles({ ...context, stamp, values, apps, fe });
+  const owner = tableOwner({ ...context, planned });
+  const composition = tableComposition({ ...context, ...owner, fe });
+  applyTable({ ...context, ...owner, planned, composition, apps, values, fe, emitTypes });
   return {
-    created: planned.map((file) => file.relative),
+    created: [...planned.map((file) => file.relative), ...composition.filter((patch) => patch.exists === false).map((patch) => patch.relative)],
     types: typeof emitTypes === "function" ? dbTypesPath : "skipped",
   };
 }

package/scaffold/add.mjs

@@ -16,9 +16,9 @@
 // `@@vCamel@@` its camelCase, `@@vUpper@@` its UPPER_SNAKE and `@@vSnake@@` its snake_case; the option `--service Class=module` gives `@@service@@` (the class) and `@@serviceModule@@`.
 import fs from 'node:fs';
 import path from 'node:path';
-import { TEMPLATES_DIR } from '../sync/index.mjs';
 import { ScaffoldError, pascalOf } from './service.mjs';
 import { addTable, graphqlPlatformFiles } from './add-table.mjs';
+import { addModuleImport, compositionCode, readComposeGroup, writeComposeGroup } from './add-compose.mjs';
 import { addApp } from './add-app.mjs';
 import { ensureLiteCli } from './add-cli-lite.mjs';
 import { addLiteWebhookInbox } from './add-inbox-lite.mjs';
@@ -59,6 +59,7 @@ function registerFeatureExports({ repoRoot, repo, noun, values }) {
 }
 
 function writeKind({ repoRoot, noun, name, now, manifest, repo, spec, declarationFile, values, forms, beRoot, patterns, planned }) {
+  if (noun === 'api' || noun === 'webhook') preflightFeatureComposition({ repoRoot, repo, noun, name });
   const bootstrapCreated = noun === 'cli' && repo.edition === 'lite' ? ensureLiteCli({ root: repoRoot, manifest, repo }) : [];
   for (const file of planned) {
     fs.mkdirSync(path.dirname(file.absolute), { recursive: true });
@@ -66,8 +67,8 @@ function writeKind({ repoRoot, noun, name, now, manifest, repo, spec, declaratio
   }
   registerFeatureExports({ repoRoot, repo, noun, values });
   if (spec.wire) wire({ beRoot, wire: spec.wire, forms, noun, name });
-  const platformCreated = repo.edition === 'lite' && (noun === 'api' || noun === 'webhook') ? wireLiteFeature({ repoRoot, repo, noun, name }) : [];
   const inboxCreated = addLiteWebhookInbox({ root: repoRoot, repo, noun, provider: name, values, now });
+  const platformCreated = noun === 'api' || noun === 'webhook' ? wireFeature({ repoRoot, repo, noun, name }) : [];
   const graphqlDoor = noun === 'api' ? ensureGraphqlPeers(repoRoot) : [];
   const registered = register({ declarationFile, spec: { patterns, trigger: spec.trigger, optionalSlots: noun === 'api' ? [GRAPHQL_CONTRACT_SLOT] : [] } });
   return { created: [...bootstrapCreated, ...planned.map((file) => `be/${file.target}`), ...platformCreated, ...inboxCreated, ...graphqlDoor], registered };
@@ -91,15 +92,59 @@ function ensureGraphqlPeers(repoRoot) {
   return ['package.json'];
 }
 
-/** Adds `importLine` and one `symbol` entry of the `imports` array of a module file's lines, once. */
-function addModuleImport(lines, { importLine, entry, relative, noun }) {
-  if (lines.includes(importLine)) return;
-  const lastImport = lines.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
-  if (lastImport < 0 || lines.findIndex(line => /^\s*imports: \[$/.test(line)) < 0) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add ${noun} could not find the imports array in ${relative}`);
-  lines.splice(lastImport + 1, 0, importLine);
-  const imports = lines.findIndex(line => /^\s*imports: \[$/.test(line));
-  const indent = /^(\s*)/.exec(lines[imports])?.[1] ?? '';
-  lines.splice(imports + 1, 0, `${indent}    ${entry},`);
+/** The skeleton registrations that move into area groups when the first transport is added. */
+function skeletonComposition(lines, edition) {
+  const active = compositionCode(lines.join('\n')).split('\n');
+  const candidates = [
+    { area: 'domain', symbol: 'IdentityModule', source: '@modules/domain/identity', entry: edition === 'lite' ? 'IdentityModule.register({ isGlobal: true, verifyAccessToken })' : 'IdentityModule.register({ isGlobal: true })' },
+    { area: 'domain', symbol: 'LivenessModule', source: '@modules/domain/liveness', entry: 'LivenessModule.register({ isGlobal: true })' },
+    { area: 'api', symbol: 'SystemHealthHttpModule', source: '@features/api/system-health', entry: 'SystemHealthHttpModule.register({})' },
+    { area: 'api', symbol: 'GraphqlModule', source: '@modules/platform/graphql', entry: 'GraphqlModule.register({ isGlobal: true })' },
+  ];
+  if (edition === 'full') candidates.push({ area: 'domain', symbol: 'NoteModule', source: '@modules/domain/note', entry: 'NoteModule.register({ isGlobal: true })' });
+  return candidates.filter(({ entry }) => active.some(line => line.trim() === `${entry},`));
+}
+
+/** Existing groups that the root spreads must survive when another area is generated. */
+function referencedComposeAreas(lines) {
+  const code = compositionCode(lines.join('\n'));
+  return ['domain', 'system', 'api', 'webhooks'].filter((area) => code.includes(`...${area}Modules(`));
+}
+
+function featureCompositionRoot({ repoRoot, repo, noun }) {
+  const app = repo.sides.be.apps.find(entry => entry.kind === 'api');
+  if (!app) throw new ScaffoldError('HFS_ADD_NO_API_OWNER', `add ${noun} needs a declared api app`);
+  const relative = `be/apps/${app.name}/src/app.module.ts`;
+  const file = path.join(repoRoot, ...relative.split('/'));
+  if (!fs.existsSync(file)) throw new ScaffoldError('HFS_ADD_WIRE_MISSING', `add ${noun} registers its transport in ${relative}, which does not exist`);
+  return { app, relative, file, lines: fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n').split('\n') };
+}
+
+/** Refuse an incompatible root or area group before generating the feature or changing its capability exports. */
+function preflightFeatureComposition({ repoRoot, repo, noun, name }) {
+  const { app, relative, lines } = featureCompositionRoot({ repoRoot, repo, noun });
+  if (noun === 'webhook' && repo.edition === 'lite') {
+    if (!compositionCode(lines.join('\n')).split('\n').some(line => /^\s*imports: \[$/.test(line)))
+      throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add webhook needs a multiline imports array in ${relative}`);
+    planLiteWebhookConfig({ repoRoot, app: app.name, provider: name });
+  }
+  const areas = new Set([noun === 'api' ? 'api' : 'webhooks', ...referencedComposeAreas(lines), ...skeletonComposition(lines, repo.edition).map(entry => entry.area)]);
+  for (const area of areas) {
+    readComposeGroup({ repoRoot, repo, app: app.name, area, noun });
+    const argument = area === 'domain' && repo.edition === 'lite' ? 'verifyAccessToken' : '';
+    addModuleImport(lines, { importLine: `import { ${area}Modules } from "./compose/${area}"`, entry: `...${area}Modules(${argument})`, relative, noun });
+  }
+}
+
+/** Remove only a moved skeleton registration and its named import, keeping guards imported from the same barrel. */
+function removeSkeletonRegistration(lines, { symbol, source, entry }) {
+  const entryAt = compositionCode(lines.join('\n')).split('\n').findIndex(line => line.trim() === `${entry},`);
+  lines.splice(entryAt, 1);
+  const importAt = lines.findIndex(line => line.startsWith('import { ') && line.replace(/;\s*$/, '').endsWith(` } from "${source}"`));
+  if (importAt < 0) return;
+  const symbols = lines[importAt].slice('import { '.length, lines[importAt].indexOf(' } from ')).split(',').map(value => value.trim()).filter(value => value !== symbol);
+  if (symbols.length) lines[importAt] = `import { ${symbols.join(', ')} } from "${source}"`;
+  else lines.splice(importAt, 1);
 }
 
 /** The GraphQL server capability (be/src/modules/platform/graphql), written whole by the first GraphQL feature of an app that has none. */
@@ -117,41 +162,62 @@ function ensureGraphqlPlatform(repoRoot) {
   return written;
 }
 
-/**
- * Lite has one API app; compose each generated transport into that app immediately: an api feature's GraphQL module (with the
- * GraphQL server on first use), a webhook's HTTP door.
- */
-function wireLiteFeature({ repoRoot, repo, noun, name }) {
-  const app = repo.sides.be.apps.find(entry => entry.kind === 'api');
-  if (!app) throw new ScaffoldError('HFS_ADD_NO_API_OWNER', `add ${noun} needs a declared lite api app`);
-  const relative = `be/apps/${app.name}/src/app.module.ts`;
-  const file = path.join(repoRoot, ...relative.split('/'));
-  if (!fs.existsSync(file)) throw new ScaffoldError('HFS_ADD_WIRE_MISSING', `add ${noun} registers its transport in ${relative}, which does not exist`);
-  const lines = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n').split('\n');
-  const created = [];
+/** The typed area members of one transport, including lite transactional handoff capabilities. */
+function transportComposition(noun, name, edition) {
+  const entries = [];
   if (noun === 'api') {
-    created.push(...ensureGraphqlPlatform(repoRoot));
-    addModuleImport(lines, { importLine: 'import { GraphqlModule } from "@modules/platform/graphql"', entry: 'GraphqlModule.register({ isGlobal: true })', relative, noun });
+    entries.push({ importLine: 'import { GraphqlModule } from "@modules/platform/graphql"', entry: 'GraphqlModule.register({ isGlobal: true })' });
     const symbol = `${pascalOf(name)}GraphqlModule`;
-    addModuleImport(lines, { importLine: `import { ${symbol} } from "@features/api/${name}"`, entry: symbol, relative, noun });
+    entries.push({ importLine: `import { ${symbol} } from "@features/api/${name}"`, entry: symbol });
   } else {
     const symbol = `${pascalOf(name)}HttpModule`;
-    addModuleImport(lines, { importLine: `import { ${symbol} } from "@features/webhooks/${name}"`, entry: symbol, relative, noun });
+    entries.push({ importLine: `import { ${symbol} } from "@features/webhooks/${name}"`, entry: symbol });
+    if (edition === 'lite') {
+      const inbox = `${pascalOf(name)}InboxModule`;
+      const importLine = `import { ${inbox} } from "@modules/domain/${name}-inbox"`;
+      const entry = `${inbox}.register({ isGlobal: true })`;
+      entries.push({ importLine, entry });
+      for (const platform of ['InboxModule', 'EventBusModule']) {
+        const capability = platform === 'InboxModule' ? 'inbox' : 'event-bus';
+        entries.push({ importLine: `import { ${platform} } from "@modules/platform/${capability}"`, entry: `${platform}.register({ isGlobal: true })` });
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * Compose each generated transport in its declared API owner through an explicitly typed area group. The root only spreads
+ * the group; it never acquires a second feature list. Lite's inbox capability belongs to its webhook group as well.
+ */
+function wireFeature({ repoRoot, repo, noun, name }) {
+  const { app, relative, file, lines } = featureCompositionRoot({ repoRoot, repo, noun });
+  const created = [];
+  const area = noun === 'api' ? 'api' : 'webhooks';
+  const groups = new Map([...referencedComposeAreas(lines), area].map((group) => [group, []]));
+  for (const migration of skeletonComposition(lines, repo.edition)) {
+    const entries = groups.get(migration.area) ?? [];
+    entries.push({ importLine: `import { ${migration.symbol} } from "${migration.source}"`, entry: migration.entry });
+    groups.set(migration.area, entries);
+    removeSkeletonRegistration(lines, migration);
   }
-  fs.writeFileSync(file, `${lines.join('\n').replace(/\n+$/, '')}\n`);
-  if (noun === 'webhook') wireLiteWebhookConfig({ repoRoot, app: app.name, provider: name });
+  const entries = groups.get(area);
+  if (noun === 'api') created.push(...ensureGraphqlPlatform(repoRoot));
+  entries.push(...transportComposition(noun, name, repo.edition));
+  for (const [group, members] of groups) {
+    const symbol = `${group}Modules`;
+    const argument = group === 'domain' && repo.edition === 'lite' ? 'verifyAccessToken' : '';
+    addModuleImport(lines, { importLine: `import { ${symbol} } from "./compose/${group}"`, entry: `...${symbol}(${argument})`, relative, noun });
+    created.push(...writeComposeGroup({ repoRoot, repo, app: app.name, area: group, entries: members, noun }));
+  }
+  fs.writeFileSync(file, `${lines.join('\n').trimEnd()}\n`);
+  if (noun === 'webhook' && repo.edition === 'lite') wireLiteWebhookConfig({ repoRoot, app: app.name, provider: name });
   return created;
 }
 
-/** Adds one generated webhook provider to the lite API's typed env reader (or an existing inline bootstrap) and enables exact raw-body verification. */
-function wireLiteWebhookConfig({ repoRoot, app, provider }) {
-  const envRelative = `be/apps/${app}/src/${app}.env.ts`;
-  const relative = fs.existsSync(path.join(repoRoot, ...envRelative.split('/')))
-    ? envRelative
-    : `be/apps/${app}/src/main.ts`;
-  const file = path.join(repoRoot, ...relative.split('/'));
-  let text = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
-  const httpSecurityImport = /^import \{ ([^}]+) \} from "@modules\/platform\/http-security"$/m;
+/** Adds the provider config reader to the existing typed HTTP security import. */
+function webhookConfigImport(text, relative) {
+  const httpSecurityImport = /^import \{ ([^}]+) \} from "@modules\/platform\/http-security";?$/m;
   const importMatch = httpSecurityImport.exec(text);
   if (!importMatch) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add webhook could not find the HTTP security import in ${relative}`);
   const imported = importMatch[1].split(',').map(symbol => symbol.trim()).filter(Boolean);
@@ -160,6 +226,40 @@ function wireLiteWebhookConfig({ repoRoot, app, provider }) {
     imported.splice(configIndex < 0 ? imported.length : configIndex + 1, 0, 'parseWebhookProviderConfig');
     text = text.replace(httpSecurityImport, `import { ${imported.join(', ')} } from "@modules/platform/http-security"`);
   }
+  return text;
+}
+
+/** Declares a signing key by name and leaves custody/provisioning to the environment owner. */
+function webhookRosterPatches(repoRoot, provider) {
+  const stacks = path.join(repoRoot, '.starcistacks');
+  if (!fs.existsSync(stacks)) return [];
+  const key = formsOf({ provider }).providerUpper + '_WEBHOOK_SECRET';
+  const patches = [];
+  for (const entry of fs.readdirSync(stacks, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(stacks, entry.name, 'runtime', 'env', 'KEYS.md');
+    if (!fs.existsSync(file)) continue;
+    const before = fs.readFileSync(file, 'utf8');
+    if (before.includes('\x60' + key + '\x60')) continue;
+    const lines = before.replace(/\r\n/g, '\n').split('\n');
+    const lastRow = lines.reduce((last, line, index) => line.startsWith('|') ? index : last, -1);
+    const row = '| \x60' + key + '\x60 | API signed ' + provider + ' webhook; owner must seal this key and provision its versioned external runtime secret before deployment |';
+    lines.splice(lastRow + 1, 0, row);
+    patches.push({ file, text: lines.join('\n') });
+  }
+  return patches;
+}
+
+/** Adds one generated webhook provider to the lite API's typed env reader (or an existing inline bootstrap) and enables exact raw-body verification. */
+function planLiteWebhookConfig({ repoRoot, app, provider }) {
+  const envRelative = `be/apps/${app}/src/${app}.env.ts`;
+  const relative = fs.existsSync(path.join(repoRoot, ...envRelative.split('/')))
+    ? envRelative
+    : `be/apps/${app}/src/main.ts`;
+  const file = path.join(repoRoot, ...relative.split('/'));
+  if (!fs.existsSync(file)) throw new ScaffoldError('HFS_ADD_WIRE_MISSING', `add webhook needs ${relative}`);
+  let text = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+  text = webhookConfigImport(text, relative);
   const providerKey = /^[a-z][a-z0-9]*$/.test(provider) ? provider : JSON.stringify(provider);
   const indent = /^([ \t]*)httpSecurity:/m.exec(text)?.[1] ?? '        ';
   const providerLine = `${indent}        ${providerKey}: parseWebhookProviderConfig(env, ${JSON.stringify(formsOf({ provider }).providerUpper)}),`;
@@ -168,24 +268,39 @@ function wireLiteWebhookConfig({ repoRoot, app, provider }) {
     if (empty.test(text)) {
       text = text.replace(empty, ['httpSecurity: {', `${indent}    ...parseHttpSecurityConfig(env),`, `${indent}    webhooks: {`, providerLine, `${indent}    },`, `${indent}}`].join('\n'));
     } else {
-      const found = /^\s*webhooks: \{$/m.exec(text);
+      const found = /^[ \t]*webhooks: \{$/m.exec(text);
       if (!found) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add webhook could not find httpSecurity options in ${relative}`);
       const insertAt = found.index + found[0].length;
       text = `${text.slice(0, insertAt)}\n${providerLine}${text.slice(insertAt)}`;
     }
   }
   text = text.replace('NestFactory.create(AppModule.register(options))', 'NestFactory.create(AppModule.register(options), { rawBody: true })');
-  fs.writeFileSync(file, text);
+  const planned = [{ file, text }];
   if (relative === envRelative) {
     const main = path.join(repoRoot, 'be', 'apps', app, 'src', 'main.ts');
+    if (!fs.existsSync(main)) throw new ScaffoldError('HFS_ADD_WIRE_MISSING', `add webhook needs be/apps/${app}/src/main.ts`);
     const entry = fs.readFileSync(main, 'utf8').replace('NestFactory.create(AppModule.register(options))', 'NestFactory.create(AppModule.register(options), { rawBody: true })');
-    fs.writeFileSync(main, entry);
+    planned.push({ file: main, text: entry });
+  }
+  planned.push(...webhookRosterPatches(repoRoot, provider));
+  return planned;
+}
+
+/** Applies the preflighted provider configuration and exact raw-body bootstrap option. */
+function wireLiteWebhookConfig(input) {
+  const patches = planLiteWebhookConfig(input);
+  const originals = new Map(patches.map(({ file }) => [file, fs.readFileSync(file)]));
+  try {
+    for (const { file, text } of patches) fs.writeFileSync(file, text);
+  } catch (error) {
+    for (const [file, text] of originals) fs.writeFileSync(file, text);
+    throw error;
   }
 }
 
 /**
  * Registers the generated member in the static module that lists its siblings (the cli feature root lists each group module): one import
- * line after the last import and one more entry of the `imports` array of its `@Module`. Nothing happens when the member is already listed.
+ * line after the last import and one more entry of the `imports` array of its `@Module`, written `Symbol.register({})` (every module has a module definition). Nothing happens when the member is already listed.
  */
 function wire({ beRoot, wire: target, forms, noun, name }) {
   const file = path.join(beRoot, ...target.file.split('/'));
@@ -193,13 +308,13 @@ function wire({ beRoot, wire: target, forms, noun, name }) {
   const fill = (text) => fillKnownForms(text, forms);
   const symbol = fill(target.symbol);
   let text = fs.readFileSync(file, 'utf8');
-  if (new RegExp(`\\b${symbol}\\b`).test(text)) return;
+  if (new RegExp(String.raw`\b${symbol}\b`).test(text)) return;
   const array = /@Module\(\{ imports: \[([^\]]*)\] \}\)/.exec(text);
   const lines = text.split('\n');
   const lastImport = lines.map((line) => line.startsWith('import ')).lastIndexOf(true);
   if (!array || lastImport < 0) throw new ScaffoldError('HFS_ADD_WIRE_FAILED', `${target.file} has no \`@Module({ imports: [...] })\` to register ${symbol} in`);
   lines.splice(lastImport + 1, 0, `import { ${symbol} } from "${fill(target.import)}"`);
-  text = lines.join('\n').replace(array[0], `@Module({ imports: [${[array[1].trim(), symbol].filter(Boolean).join(', ')}] })`);
+  text = lines.join('\n').replace(array[0], `@Module({ imports: [${[array[1].trim(), `${symbol}.register({})`].filter(Boolean).join(', ')}] })`);
   fs.writeFileSync(file, text);
 }