@starci/hfs 4.0.8 → 4.0.9

package/scaffold/add-table.mjs

@@ -0,0 +1,344 @@
+import fs from "node:fs";
+import path from "node:path";
+import { emitDbTypes, dbTypesPath } from "../emit/db-types.mjs";
+import {
+  loadSlotManifest,
+  readRepoDeclaration,
+} from "../runtime/scripts/hfs/slots.mjs";
+import { render, TEMPLATES_DIR } from "../sync/index.mjs";
+import { ScaffoldError, pascalOf } from "./service.mjs";
+import { registerLiteExports } from "./lite-exports.mjs";
+
+const NAME = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
+const MIGRATION = /^(\d{14})_[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.sql$/;
+const POSTGRES_RESERVED = new Set([
+  "all",
+  "analyse",
+  "analyze",
+  "and",
+  "any",
+  "array",
+  "as",
+  "asc",
+  "asymmetric",
+  "authorization",
+  "binary",
+  "both",
+  "case",
+  "cast",
+  "check",
+  "collate",
+  "collation",
+  "column",
+  "concurrently",
+  "constraint",
+  "create",
+  "cross",
+  "current_catalog",
+  "current_date",
+  "current_role",
+  "current_schema",
+  "current_time",
+  "current_timestamp",
+  "current_user",
+  "default",
+  "deferrable",
+  "desc",
+  "distinct",
+  "do",
+  "else",
+  "end",
+  "except",
+  "false",
+  "fetch",
+  "for",
+  "foreign",
+  "freeze",
+  "from",
+  "full",
+  "grant",
+  "group",
+  "having",
+  "ilike",
+  "in",
+  "initially",
+  "inner",
+  "intersect",
+  "into",
+  "is",
+  "isnull",
+  "join",
+  "lateral",
+  "leading",
+  "left",
+  "like",
+  "limit",
+  "localtime",
+  "localtimestamp",
+  "natural",
+  "not",
+  "notnull",
+  "null",
+  "nulls",
+  "offset",
+  "on",
+  "only",
+  "or",
+  "order",
+  "outer",
+  "overlaps",
+  "placing",
+  "primary",
+  "references",
+  "returning",
+  "right",
+  "select",
+  "session_user",
+  "similar",
+  "some",
+  "symmetric",
+  "system_user",
+  "table",
+  "tablesample",
+  "then",
+  "to",
+  "trailing",
+  "true",
+  "union",
+  "unique",
+  "user",
+  "using",
+  "variadic",
+  "verbose",
+  "when",
+  "where",
+  "window",
+  "with",
+]);
+
+const timestampOf = (now) =>
+  new Date(now()).toISOString().replace(/\D/g, "").slice(0, 14);
+const snakeOf = (name) => name.replaceAll("-", "_");
+const featureOf = (name) => name.replaceAll("_", "-");
+const sqlIdentifierOf = (name) =>
+  POSTGRES_RESERVED.has(name) ? `"${name}"` : name;
+const singularOf = (name) => (name.endsWith("s") ? name.slice(0, -1) : name);
+const camelOf = (name) => {
+  const pascal = pascalOf(name);
+  return pascal[0].toLowerCase() + pascal.slice(1);
+};
+
+function template(relative, values) {
+  const file = path.join(TEMPLATES_DIR, ...relative.split("/"));
+  if (!fs.existsSync(file))
+    throw new ScaffoldError(
+      "HFS_ADD_TEMPLATE_MISSING",
+      `table template ${relative} is not carried by this package`,
+    );
+  return fs
+    .readFileSync(file, "utf8")
+    .replace(/\{\{([A-Za-z][A-Za-z0-9]*)\}\}/g, (whole, key) => {
+      if (values[key] === undefined)
+        throw new ScaffoldError(
+          "HFS_ADD_PLACEHOLDER_UNKNOWN",
+          `table template ${relative} uses ${whole}, which add table does not provide`,
+        );
+      return values[key];
+    });
+}
+
+function removeEmptyParents(file, stop) {
+  for (
+    let at = path.dirname(file);
+    at.startsWith(stop) && at !== stop;
+    at = path.dirname(at)
+  ) {
+    if (!fs.existsSync(at) || fs.readdirSync(at).length !== 0) break;
+    fs.rmdirSync(at);
+  }
+}
+
+function wireApiModule(root, app, name) {
+  const relative = `be/apps/${app}/src/app.module.ts`;
+  const file = path.join(root, ...relative.split("/"));
+  if (!fs.existsSync(file))
+    throw new ScaffoldError("HFS_ADD_WIRE_MISSING", `add table registers ${name} in ${relative}, which does not exist`);
+  const symbol = `${pascalOf(name)}Module`;
+  const errorKinds = `${snakeOf(name).toUpperCase()}_ERROR_KINDS`;
+  const importLine = `import { ${errorKinds}, ${symbol} } from "@modules/domain/${name}"`;
+  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));
+  const kinds = lines.findIndex((line) => /^\s*kinds: \[$/.test(line));
+  if (lastImport < 0 || imports < 0 || kinds < 0)
+    throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `add table could not find the imports and error kinds arrays in ${relative}`);
+  if (!lines.includes(importLine)) {
+    lines.splice(lastImport + 1, 0, importLine);
+    const shiftedImports = lines.findIndex((line) => /^\s*imports: \[$/.test(line));
+    const indent = /^(\s*)/.exec(lines[shiftedImports])?.[1] ?? "";
+    lines.splice(shiftedImports + 1, 0, `${indent}    ${symbol}.register({ isGlobal: true }),`);
+    const shiftedKinds = lines.findIndex((line) => /^\s*kinds: \[$/.test(line));
+    const kindsIndent = /^(\s*)/.exec(lines[shiftedKinds])?.[1] ?? "";
+    lines.splice(shiftedKinds + 1, 0, `${kindsIndent}    ${errorKinds},`);
+  }
+  fs.writeFileSync(file, `${lines.join("\n").replace(/\n+$/, "")}\n`);
+}
+
+/**
+ * Adds one Supabase table migration and, with `fe`, one typed reader/writer pair to every declared Next app.
+ * `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,
+}) {
+  const requestedName = String(name);
+  if (!NAME.test(requestedName))
+    throw new ScaffoldError(
+      "HFS_ADD_NAME_INVALID",
+      `table name ${name} must use lowercase letters, digits and single dash or underscore separators`,
+    );
+  const feature = featureOf(requestedName);
+  const table = snakeOf(requestedName);
+  const manifest = loadSlotManifest();
+  const repo = readRepoDeclaration(manifest, root);
+  const connection = repo.sides?.be?.connections?.find((candidate) => candidate.provider === "supabase");
+  if (!connection) {
+    throw new ScaffoldError(
+      "HFS_ADD_TABLE_PROVIDER",
+      "add table needs a back-end connection whose provider is supabase",
+    );
+  }
+
+  const migrationsDir = path.join(root, "supabase", "migrations");
+  const migrations = fs.existsSync(migrationsDir)
+    ? fs
+        .readdirSync(migrationsDir)
+        .filter((file) => MIGRATION.test(file))
+        .sort()
+    : [];
+  if (migrations.some((file) => file.endsWith(`_${feature}.sql`)))
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `table ${requestedName} already has a migration`,
+    );
+  const stamp = timestampOf(now);
+  const latest = migrations.at(-1)?.slice(0, 14);
+  if (latest && stamp <= latest)
+    throw new ScaffoldError(
+      "HFS_ADD_MIGRATION_ORDER",
+      `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`,
+    );
+
+  const values = {
+    name: feature,
+    table,
+    tableSql: sqlIdentifierOf(table),
+    Name: pascalOf(feature),
+    nameCamel: camelOf(feature),
+    upper: table.toUpperCase(),
+    singular: singularOf(feature),
+    Singular: pascalOf(singularOf(feature)),
+  };
+  const planned = [
+    {
+      relative: `supabase/migrations/${stamp}_${feature}.sql`,
+      body: template("be/table/migration.sql.tpl", values),
+    },
+    { relative: `be/src/modules/domain/${feature}/index.ts`, body: template("be/table/index.ts.tpl", values) },
+    { relative: `be/src/modules/domain/${feature}/errors/${feature}.error.ts`, body: template("be/table/error.ts.tpl", values) },
+    { relative: `be/src/modules/domain/${feature}/${feature}.module.ts`, body: template("be/table/module.ts.tpl", values) },
+    { relative: `be/src/modules/domain/${feature}/${feature}.module-definition.ts`, body: template("be/table/module-definition.ts.tpl", values) },
+    { relative: `be/src/modules/domain/${feature}/${feature}.options.ts`, body: template("be/table/options.ts.tpl", values) },
+    { relative: `be/src/modules/domain/${feature}/${feature}.service.ts`, body: template("be/table/service.ts.tpl", values) },
+    { relative: `be/src/modules/domain/${feature}/persistence/${feature}.rows.ts`, body: template("be/table/rows.ts.tpl", values) },
+    { relative: `be/src/modules/domain/${feature}/persistence/${feature}.sql.ts`, body: template("be/table/sql.ts.tpl", values) },
+  ];
+  const databaseSql = "be/src/modules/platform/database/database.sql.ts";
+  if (repo.edition === "lite" && !fs.existsSync(path.join(root, ...databaseSql.split("/")))) {
+    planned.splice(1, 0, {
+      relative: databaseSql,
+      body: render(fs.readFileSync(path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", "database.sql.ts"), "utf8"), {}),
+    });
+  }
+  if (fe) {
+    const apps =
+      repo.sides?.fe?.apps?.filter((app) => app.kind === "next") ?? [];
+    if (!apps.length)
+      throw new ScaffoldError(
+        "HFS_ADD_NO_FRONT_END",
+        "add table --fe needs at least one declared Next app",
+      );
+    for (const app of apps) {
+      const base = `fe/apps/${app.name}/src/modules/db/${feature}`;
+      planned.push(
+        {
+          relative: `${base}/read-${feature}.ts`,
+          body: template("fe/table/read.ts.tpl", values),
+        },
+        {
+          relative: `${base}/write-${feature}.ts`,
+          body: template("fe/table/write.ts.tpl", values),
+        },
+      );
+    }
+  }
+
+  const clash = planned
+    .filter((file) =>
+      fs.existsSync(path.join(root, ...file.relative.split("/"))),
+    )
+    .map((file) => file.relative);
+  if (clash.length)
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `table ${requestedName} already exists: ${clash.join(", ")}`,
+    );
+  const owner = repo.sides.be.apps.find((app) => app.name === connection.owner && app.kind === "api");
+  if (!owner)
+    throw new ScaffoldError("HFS_ADD_NO_API_OWNER", `add table needs the Supabase connection owner ${connection.owner} to be a declared api app`);
+  const ownerFile = path.join(root, "be", "apps", owner.name, "src", "app.module.ts");
+  if (!fs.existsSync(ownerFile))
+    throw new ScaffoldError("HFS_ADD_WIRE_MISSING", `add table registers ${name} in be/apps/${owner.name}/src/app.module.ts, which does not exist`);
+  const ownerBefore = fs.readFileSync(ownerFile, "utf8");
+  const databaseIndex = path.join(root, "be", "src", "modules", "platform", "database", "index.ts");
+  const databaseIndexBefore = repo.edition === "lite" && fs.existsSync(databaseIndex) ? fs.readFileSync(databaseIndex) : null;
+  const typesFile = path.join(root, ...dbTypesPath.split("/"));
+  const typesBefore = fs.existsSync(typesFile) ? fs.readFileSync(typesFile) : null;
+  const created = [];
+  try {
+    for (const file of planned) {
+      const target = path.join(root, ...file.relative.split("/"));
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, file.body);
+      created.push(target);
+    }
+    if (emitTypes !== false) {
+      const generated = emitTypes({ root });
+      if (typeof generated === "string") {
+        const target = path.join(root, ...dbTypesPath.split("/"));
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, generated);
+      }
+    }
+    wireApiModule(root, owner.name, feature);
+    if (repo.edition === "lite") registerLiteExports({ root, generator: "table" });
+  } catch (error) {
+    fs.writeFileSync(ownerFile, ownerBefore);
+    if (databaseIndexBefore !== null) fs.writeFileSync(databaseIndex, databaseIndexBefore);
+    if (typesBefore === null) fs.rmSync(typesFile, { force: true });
+    else fs.writeFileSync(typesFile, typesBefore);
+    for (const file of [...created].reverse()) {
+      if (fs.existsSync(file)) fs.rmSync(file);
+      removeEmptyParents(file, root);
+    }
+    throw error;
+  }
+  return {
+    created: planned.map((file) => file.relative),
+    types: emitTypes === false ? "skipped" : dbTypesPath,
+  };
+}

package/scaffold/add.mjs

@@ -0,0 +1,299 @@
+// starci app add <noun> <name> - generates exactly one kind's file tree FROM the pattern knowledge files.
+//
+// The `files:` tree of a pattern topic (knowledge/patterns/be/<topic>.yaml) is the single source of what the pattern places: its paths, the
+// slot that owns each, the rules that judge it, and the one content body (`template`, a file under templates/be/patterns/) of each. This
+// module reads the tree of the noun's topic (`ruleParams.be.addKinds` names it), fills the path variables, writes each instance file that
+// does not exist, adds the platform capabilities the noun's patterns need when they are missing, and registers the patterns and the trigger
+// kind in hfs.json (`sides.be.patterns`, `sides.be.kinds`). There is no second list of files and no second copy of a body: a kind is only
+// generated when it is used, so an empty kind folder never exists.
+//
+//   starci app add job send-receipt                      features/jobs/send-receipt: module, processor, one step; the platform jobs and queue capabilities
+//   starci app add reactor payment-status --event payment-settled --from payment --service PaymentStatusService=@modules/domain/order
+//   starci app add queue receipt                          modules/queues/receipt: the typed producer
+//   starci app add projection order-summary --connection order
+//
+// Body placeholders: for each variable `v` of the tree (job, step, event, ...) `@@v@@` is its kebab name, `@@V@@` its PascalCase and
+// `@@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 { refuseInEdition } from './edition-gate.mjs';
+import { addTable } from './add-table.mjs';
+import { addApp } from './add-app.mjs';
+import { ensureLiteCli, selectLiteCliEntries } from './add-cli-lite.mjs';
+import { addLiteWebhookInbox, selectLiteWebhookEntries } from './add-inbox-lite.mjs';
+import { jsonText } from './app.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;
+}
+
+const selectLiteApiEntries = entries => [
+  ...entries.filter(entry => !entry.path.includes('/transport/graphql/')).map(entry => {
+    if (entry.path === 'src/features/api/<feature>/index.ts') return { ...entry, template: 'api/feature.index.http.ts.tpl' };
+    if (entry.path === 'src/features/api/<feature>/application/<action>.command.ts') return { ...entry, template: 'api/application.command.http.ts.tpl' };
+    if (entry.path === 'src/features/api/<feature>/application/<action>.handler.ts') return { ...entry, template: 'api/application.handler.http.ts.tpl' };
+    return entry;
+  }),
+  { path: 'src/features/api/<feature>/transport/http/<action>.controller.ts', slot: 'be.transport.http', template: 'api/http.controller.ts.tpl' },
+  { path: 'src/features/api/<feature>/transport/http/<action>.mapper.ts', slot: 'be.transport.http', template: 'api/http.mapper.ts.tpl' },
+  { path: 'src/features/api/<feature>/transport/http/dto/<action>.request.ts', slot: 'be.transport.http', template: 'api/http.request.ts.tpl' },
+  { path: 'src/features/api/<feature>/transport/http/dto/<action>.response.ts', slot: 'be.transport.http', template: 'api/http.response.ts.tpl' },
+  { path: 'src/features/api/<feature>/transport/http/<feature>-http.module.ts', slot: 'be.transport.http', template: 'api/http.module.ts.tpl' },
+];
+
+/** The templates the lite api tree names beyond the pattern topic's own files tree (the HTTP door replaces the GraphQL one): 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).
+ *
+ * @param {{ repoRoot: string, noun: string, name: string, options?: object, now?: () => number }} input - The app root, the noun (job, reactor, queue, projection), the instance name and the options the noun needs.
+ * @returns {{ created: Array<string>, registered: { patterns: Array<string>, kinds: Array<string> } }} The files written (app-root relative) and what hfs.json gained.
+ */
+export function addKind({ repoRoot, noun, name, options = {}, now = Date.now }) {
+  if (noun === 'table') {
+    const result = addTable({ root: repoRoot, name, fe: options.fe === true, emitTypes: options.noTypes === true ? false : options.emitTypes, now });
+    return { ...result, registered: { patterns: [], kinds: [] } };
+  }
+  if (noun === 'app') {
+    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';
+  const trees = new Map([...topics].map((topic) => {
+    const entries = repo.edition === 'lite' ? selectLiteWebhookEntries(selectLiteCliEntries(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 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);
+  }
+  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')) {
+    registerLiteDomainService({ root: repoRoot, moduleSpecifier: values.serviceModule, service: values.service });
+  }
+  if (spec.wire) wire({ beRoot, wire: spec.wire, forms, noun, name });
+  if (repo.edition === 'lite' && (noun === 'api' || noun === 'webhook')) wireLiteFeature({ repoRoot, repo, noun, name });
+  const inboxCreated = addLiteWebhookInbox({ root: repoRoot, repo, noun, provider: name, values, now });
+  const registered = register({ declarationFile, spec: { patterns, trigger: spec.trigger } });
+  return { created: [...bootstrapCreated, ...planned.map((file) => `be/${file.target}`), ...inboxCreated], registered };
+}
+
+/** Lite has one API app; compose each generated API or webhook transport into that app immediately. */
+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 symbol = `${pascalOf(name)}HttpModule`;
+  const owner = noun === 'api' ? 'api' : 'webhooks';
+  const importLine = `import { ${symbol} } from "@features/${owner}/${name}"`;
+  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 ${noun} 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},`);
+  }
+  fs.writeFileSync(file, `${lines.join('\n').replace(/\n+$/, '')}\n`);
+  if (noun === 'webhook') wireLiteWebhookConfig({ repoRoot, app: app.name, provider: name });
+}
+
+/** 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;
+  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);
+  if (!imported.includes('parseWebhookProviderConfig')) {
+    const configIndex = imported.indexOf('parseHttpSecurityConfig');
+    imported.splice(configIndex < 0 ? imported.length : configIndex + 1, 0, 'parseWebhookProviderConfig');
+    text = text.replace(httpSecurityImport, `import { ${imported.join(', ')} } from "@modules/platform/http-security"`);
+  }
+  const providerKey = /^[a-z][a-z0-9]*$/.test(provider) ? provider : JSON.stringify(provider);
+  const providerLine = `                ${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'));
+    } else {
+      const found = /^\s*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);
+}
+
+/**
+ * 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.
+ */
+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 symbol = fill(target.symbol);
+  let text = fs.readFileSync(file, 'utf8');
+  if (new RegExp(`\\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(', ')}] })`);
+  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 and the trigger kind 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'));
+  const be = declaration.sides.be;
+  const patterns = [...new Set([...(be.patterns ?? []), ...spec.patterns])].sort();
+  const kinds = [...new Set([...(be.kinds ?? []), ...(spec.trigger ? [spec.trigger] : [])])].sort();
+  be.patterns = patterns;
+  if (kinds.length) be.kinds = kinds;
+  fs.writeFileSync(declarationFile, jsonText(declaration));
+  return { patterns, kinds };
+}