@starci/hfs 4.2.17 → 4.4.0

package/scaffold/add.mjs

@@ -16,101 +16,18 @@
 // `@@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 { createSlotResolver, loadSlotManifest, readRepoDeclaration, ruleParams } from '../runtime/scripts/hfs/slots.mjs';
-import { parseYaml } from '../runtime/engine/yaml.mjs';
-import { TEMPLATES_DIR } from '../sync/index.mjs';
 import { ScaffoldError, pascalOf } from './service.mjs';
-import { refuseFullAdapterInLite, refuseInEdition } from './edition-gate.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, selectLiteWebhookEntries } from './add-inbox-lite.mjs';
+import { addLiteWebhookInbox } from './add-inbox-lite.mjs';
+import { addBuiltinLiteCli, fillKnownForms, formsOf, planKind, readAddContext } from './add-plan.mjs';
+export { liteApiTemplates } from './add-plan.mjs';
 import { bundledPins, jsonText, packageJsonText, peerDependencies } from './app.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { registerLiteDomainService, registerLiteExports } from './lite-exports.mjs';
 
-const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const VARIABLE = /<([A-Za-z][A-Za-z0-9]*)>/g;
-const PLACEHOLDER = /@@([A-Za-z][A-Za-z0-9]*)@@/g;
-const PLATFORM_PREFIX = 'src/modules/platform/';
-const TOPICS_DIR = path.join(import.meta.dirname, '..', 'runtime', 'knowledge', 'patterns', 'be');
-const PATTERN_TEMPLATES = path.join(TEMPLATES_DIR, 'be', 'patterns');
-
-const camelOf = (name) => { const pascal = pascalOf(name); return pascal[0].toLowerCase() + pascal.slice(1); };
-
-/** The `files:` tree of the topic `topic`, read from the knowledge file the package carries. */
-function readTree(topic) {
-  const file = path.join(TOPICS_DIR, `${topic}.yaml`);
-  if (!fs.existsSync(file)) throw new ScaffoldError('HFS_ADD_TOPIC_MISSING', `the pattern topic ${topic} (knowledge/patterns/be/${topic}.yaml) is not carried by this package`);
-  const doc = parseYaml(fs.readFileSync(file, 'utf8'));
-  if (!Array.isArray(doc?.files)) throw new ScaffoldError('HFS_ADD_TREE_MISSING', `knowledge/patterns/be/${topic}.yaml has no files tree`);
-  return doc.files;
-}
-
-/** The parsed document of the topic `topic` (knowledge/patterns/be/<topic>.yaml) the package carries. */
-const readTopic = (topic) => ({ id: topic, doc: parseYaml(fs.readFileSync(path.join(TOPICS_DIR, `${topic}.yaml`), 'utf8')) });
-
-/**
- * The lite api tree: the full tree, GraphQL door included (owner ruling 2026-10-13: lite and full have one code structure), with
- * the command and handler that hand the verified Supabase principal to the domain service (lite's identity adapter).
- */
-const selectLiteApiEntries = entries => entries.map(entry => {
-  if (entry.path === 'src/features/api/<feature>/application/<action>.command.ts') return { ...entry, template: 'api/application.command.principal.ts.tpl' };
-  if (entry.path === 'src/features/api/<feature>/application/<action>.handler.ts') return { ...entry, template: 'api/application.handler.principal.ts.tpl' };
-  return entry;
-});
-
-/** The templates the lite api tree names beyond the pattern topic's own files tree (the principal-aware command and handler): the template set stays one set with the topics' (tests/packages-hfs/hfs-add.spec.mjs). */
-export const liteApiTemplates = () => selectLiteApiEntries(readTree('api')).map(entry => entry.template).filter(Boolean);
-
-/** Fills the `<name>` variables of a path; returns null when a variable has no value. */
-const fillPath = (text, values) => {
-  let missing = false;
-  const filled = text.replace(VARIABLE, (whole, name) => (values[name] === undefined ? ((missing = true), whole) : values[name]));
-  return missing ? null : filled;
-};
-
-/** The body of a template with its placeholders filled; an unknown placeholder is a refusal. */
-const renderBody = (text, values, forms, template) => text.replace(PLACEHOLDER, (whole, name) => {
-  if (forms[name] === undefined) throw new ScaffoldError('HFS_ADD_PLACEHOLDER_UNKNOWN', `template ${template} uses ${whole}, which no variable of this noun provides`);
-  return forms[name];
-});
-
-/** The spellings of every variable: kebab (`job`), Pascal (`Job`), camel (`jobCamel`), UPPER_SNAKE (`jobUpper`) and snake_case (`jobSnake`). */
-function formsOf(values) {
-  const forms = {};
-  for (const [name, value] of Object.entries(values)) {
-    const kebab = KEBAB.test(value);
-    forms[name] = value;
-    forms[name[0].toUpperCase() + name.slice(1)] = kebab ? pascalOf(value) : value[0].toUpperCase() + value.slice(1);
-    forms[`${name}Camel`] = kebab ? camelOf(value) : value[0].toLowerCase() + value.slice(1);
-    forms[`${name}Upper`] = kebab ? value.replaceAll('-', '_').toUpperCase() : value;
-    forms[`${name}Snake`] = kebab ? value.replaceAll('-', '_') : value;
-  }
-  return forms;
-}
-
-/** The variables of the noun: the instance name, the options it needs and the defaults of the others. */
-function variablesOf({ spec, noun, name, options }) {
-  if (!KEBAB.test(name)) throw new ScaffoldError('HFS_ADD_NAME_INVALID', `${noun} name ${name} must be kebab-case (letters, digits and single dashes)`);
-  const values = { [spec.variable]: name };
-  for (const need of spec.needs ?? []) {
-    const value = options[need];
-    if (typeof value !== 'string' || !value) throw new ScaffoldError('HFS_ADD_OPTION_MISSING', `starci app add ${noun} needs --${need}`);
-    if (need === 'service') {
-      const [className, module] = value.split('=');
-      if (!className || !module) throw new ScaffoldError('HFS_ADD_OPTION_INVALID', '--service takes <ServiceClass>=<module specifier>');
-      values.service = className;
-      values.serviceModule = module;
-    } else {
-      if (!KEBAB.test(value)) throw new ScaffoldError('HFS_ADD_OPTION_INVALID', `--${need} ${value} must be kebab-case`);
-      values[need] = value;
-    }
-  }
-  for (const [key, rule] of Object.entries(spec.defaults ?? {})) if (values[key] === undefined) values[key] = rule === '@name' ? name : String(rule);
-  return values;
-}
-
 /**
  * Generates the tree of one noun in the app at `repoRoot` (the folder of hfs.json).
  *
@@ -126,80 +43,32 @@ export function addKind({ repoRoot, noun, name, options = {}, now = Date.now })
     const result = addApp({ root: repoRoot, name });
     return { ...result, registered: { patterns: [], kinds: [] } };
   }
-  const manifest = loadSlotManifest();
-  const params = ruleParams(manifest, 'be');
-  const spec = params.addKinds[noun];
-  if (!spec) throw new ScaffoldError('HFS_ADD_NOUN_UNKNOWN', `starci app add knows ${Object.keys(params.addKinds).join(', ')}; ${noun} is none of them`);
-  const declarationFile = path.join(repoRoot, 'hfs.json');
-  if (!fs.existsSync(declarationFile)) throw new ScaffoldError('HFS_ADD_NOT_AN_APP', 'starci app add runs at the app root (the folder of hfs.json)');
-  const repo = readRepoDeclaration(manifest, repoRoot);
-  if (!repo.sides?.be) throw new ScaffoldError('HFS_ADD_NO_BACK_END', 'this app has no back-end side');
-  const liteCliBuiltIn = noun === 'cli' && repo.edition === 'lite' && (name === 'migrate' || name === 'seed');
-  if (liteCliBuiltIn) {
-    if (repo.sides.be.apps.some(app => app.kind === 'cli'))
-      throw new ScaffoldError('HFS_ADD_EXISTS', `the lite cli already carries its built-in ${name} group`);
-    return { created: ensureLiteCli({ root: repoRoot, manifest, repo }), registered: { patterns: [], kinds: ['cli'] } };
-  }
-  const nouns = [noun, ...(spec.also ?? [])];
-  const specs = nouns.map((each) => [each, params.addKinds[each]]);
-  const patterns = [...new Set(specs.flatMap(([, eachSpec]) => eachSpec.patterns))];
-  const topics = new Set([...specs.map(([, eachSpec]) => eachSpec.topic), ...topicsOfPatterns(patterns)]);
-  const liteCli = noun === 'cli' && repo.edition === 'lite';
-  const liteApi = noun === 'api' && repo.edition === 'lite';
-  // Lite has every pattern (owner ruling 2026-10-12), but a topic with a liteAdapter is generated only from full templates.
-  refuseFullAdapterInLite({ edition: repo.edition, topics: [...topics].map(readTopic), command: `add ${noun}` });
-  const trees = new Map([...topics].map((topic) => {
-    // Lite keeps every colocated unit spec of a tree (owner ruling 2026-10-12); only the webhook door and its spec are lite's own.
-    const entries = repo.edition === 'lite' ? selectLiteWebhookEntries(readTree(topic)) : readTree(topic);
-    return [topic, liteApi && topic === spec.topic ? selectLiteApiEntries(entries) : entries];
-  }));
-  // The slots the noun's trees name decide whether the edition has the noun (a slot lite does not carry or forbids
-  // makes it a full-edition capability); never the noun's name. Optional entries are never generated, so they gate nothing.
-  const writtenSlots = new Set();
-  for (const [each, eachSpec] of specs) for (const entry of trees.get(eachSpec.topic)) if (!entry.path.startsWith(PLATFORM_PREFIX) && entry.optional !== true && entry.slot) writtenSlots.add(entry.slot);
-  for (const topic of topics) for (const entry of trees.get(topic)) if (entry.path.startsWith(PLATFORM_PREFIX) && entry.optional !== true && entry.slot) writtenSlots.add(entry.slot);
-  refuseInEdition({ resolver: createSlotResolver(manifest, repo), slotIds: [...writtenSlots], command: `add ${noun}` });
-  const values = Object.assign({}, ...specs.map(([each, eachSpec]) => variablesOf({ spec: eachSpec, noun: each, name, options })), variablesOf({ spec, noun, name, options }));
-  const stamp = String(now()).padStart(13, '0').slice(0, 13);
-  const withStamp = { ...values, epochMs13: stamp };
-  const forms = formsOf(withStamp);
-  const beRoot = path.join(repoRoot, 'be');
-
-  const planned = [];
-  const consider = (entry, topic, instance, shared = false) => {
-    if (entry.optional === true) return;
-    const target = fillPath(entry.path, withStamp);
-    if (target === null) return;
-    const absolute = path.join(beRoot, ...target.split('/'));
-    // A platform capability is whole or absent: it exists when its index.ts does, and then none of its files is written again.
-    if (!instance && fs.existsSync(path.join(beRoot, ...target.split('/').slice(0, 4), 'index.ts'))) return;
-    if ((!instance || shared) && fs.existsSync(absolute)) return;
-    if (!entry.template) throw new ScaffoldError('HFS_ADD_TEMPLATE_MISSING', `${topic}.yaml lists ${entry.path} without a template, so it cannot be generated`);
-    const templateFile = path.join(PATTERN_TEMPLATES, ...entry.template.split('/'));
-    if (!fs.existsSync(templateFile)) throw new ScaffoldError('HFS_ADD_TEMPLATE_MISSING', `${topic}.yaml names template ${entry.template} for ${entry.path}, which the package does not carry`);
-    planned.push({ target, absolute, body: renderBody(fs.readFileSync(templateFile, 'utf8'), withStamp, forms, entry.template), instance });
-  };
-
-  for (const [each, eachSpec] of specs) for (const entry of trees.get(eachSpec.topic)) if (!entry.path.startsWith(PLATFORM_PREFIX)) consider(entry, eachSpec.topic, true, each !== noun);
-  for (const topic of topics) for (const entry of trees.get(topic)) if (entry.path.startsWith(PLATFORM_PREFIX)) consider(entry, topic, false);
-
-  const clash = planned.filter((file) => file.instance && fs.existsSync(file.absolute)).map((file) => file.target);
-  if (clash.length) throw new ScaffoldError('HFS_ADD_EXISTS', `${noun} ${name} already exists: ${clash.join(', ')}`);
+  const context = readAddContext({ repoRoot, noun, name, options, now });
+  const builtin = addBuiltinLiteCli(context);
+  if (builtin) return builtin;
+  return writeKind({ ...context, ...planKind(context) });
+}
 
-  const bootstrapCreated = liteCli ? ensureLiteCli({ root: repoRoot, manifest, repo }) : [];
-  for (const file of planned) {
-    fs.mkdirSync(path.dirname(file.absolute), { recursive: true });
-    fs.writeFileSync(file.absolute, file.body);
-  }
+function registerFeatureExports({ repoRoot, repo, noun, values }) {
   if (noun === 'webhook' || (repo.edition === 'lite' && noun === 'api')) {
     registerLiteExports({ root: repoRoot, generator: repo.edition === 'lite' ? noun : 'webhook-full' });
   }
-  if (repo.edition === 'lite' && (noun === 'api' || noun === 'webhook')) {
+  if (repo.edition === 'lite' && noun === 'api') {
     registerLiteDomainService({ root: repoRoot, moduleSpecifier: values.serviceModule, service: values.service });
   }
+}
+
+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 });
+    fs.writeFileSync(file.absolute, file.body);
+  }
+  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 };
@@ -223,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. */
@@ -249,38 +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);
+  }
+  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').replace(/\n+$/, '')}\n`);
-  if (noun === 'webhook') wireLiteWebhookConfig({ repoRoot, app: app.name, provider: name });
+  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 parsed options and enables exact raw-body verification. */
-function wireLiteWebhookConfig({ repoRoot, app, provider }) {
-  const relative = `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);
@@ -289,53 +226,98 @@ 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 providerLine = `                ${providerKey}: parseWebhookProviderConfig(env, ${JSON.stringify(formsOf({ provider }).providerUpper)}),`;
+  const indent = /^([ \t]*)httpSecurity:/m.exec(text)?.[1] ?? '        ';
+  const providerLine = `${indent}        ${providerKey}: parseWebhookProviderConfig(env, ${JSON.stringify(formsOf({ provider }).providerUpper)}),`;
   if (!text.includes(providerLine)) {
     const empty = /httpSecurity:\s*parseHttpSecurityConfig\(env\)/;
     if (empty.test(text)) {
-      text = text.replace(empty, ['httpSecurity: {', '            ...parseHttpSecurityConfig(env),', '            webhooks: {', providerLine, '            },', '        }'].join('\n'));
+      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 })');
+    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('/'));
   if (!fs.existsSync(file)) throw new ScaffoldError('HFS_ADD_WIRE_MISSING', `starci app add ${noun} ${name} registers the member in ${target.file}, which does not exist`);
-  const fill = (text) => text.replace(PLACEHOLDER, (whole, key) => forms[key] ?? whole);
+  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);
 }
 
-/** The topics that carry the platform capability of each pattern: the topic whose `pattern` key names it. */
-function topicsOfPatterns(patterns) {
-  const topics = new Set();
-  for (const file of fs.readdirSync(TOPICS_DIR).filter((entry) => entry.endsWith('.yaml'))) {
-    const doc = parseYaml(fs.readFileSync(path.join(TOPICS_DIR, file), 'utf8'));
-    if (patterns.includes(doc?.pattern)) topics.add(file.slice(0, -'.yaml'.length));
-  }
-  return topics;
-}
-
 /** Adds the patterns, the trigger kind and the opt-in slots of the noun to sides.be of hfs.json, keeping its other content and key order. */
 function register({ declarationFile, spec }) {
   const declaration = JSON.parse(fs.readFileSync(declarationFile, 'utf8'));