@starci/hfs 4.2.17 → 4.4.0

package/scaffold/add-plan.mjs

@@ -0,0 +1,183 @@
+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 { selectLiteWebhookEntries } from './add-inbox-lite.mjs';
+import { ensureLiteCli } from './add-cli-lite.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 noun's app declaration and the ruleParams entry that supplies its topic and options. */
+export function readAddContext(input) {
+  const manifest = loadSlotManifest();
+  const params = ruleParams(manifest, 'be');
+  const spec = params.addKinds[input.noun];
+  if (!spec) throw new ScaffoldError('HFS_ADD_NOUN_UNKNOWN', `starci app add knows ${Object.keys(params.addKinds).join(', ')}; ${input.noun} is none of them`);
+  const declarationFile = path.join(input.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, input.repoRoot);
+  if (!repo.sides?.be) throw new ScaffoldError('HFS_ADD_NO_BACK_END', 'this app has no back-end side');
+  return { ...input, manifest, params, spec, declarationFile, repo };
+}
+
+/** Lite's built-in migrate and seed groups come from its one CLI bootstrap, without a second instance tree. */
+export function addBuiltinLiteCli({ noun, name, repo, repoRoot, manifest }) {
+  if (noun !== 'cli' || repo.edition !== 'lite' || !['migrate', 'seed'].includes(name)) return null;
+  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 readTopic = (topic) => ({ id: topic, doc: parseYaml(fs.readFileSync(path.join(TOPICS_DIR, `${topic}.yaml`), 'utf8')) });
+
+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.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;
+});
+
+/** Extra lite api templates stay in the same template set as the pattern topics. */
+export const liteApiTemplates = () => selectLiteApiEntries(readTree('api')).map(entry => entry.template).filter(Boolean);
+
+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;
+}
+
+function requiredOption(need, value, noun) {
+  if (typeof value !== 'string' || !value) throw new ScaffoldError('HFS_ADD_OPTION_MISSING', `starci app add ${noun} needs --${need}`);
+  if (need === 'service') {
+    const [service, serviceModule] = value.split('=');
+    if (!service || !serviceModule) throw new ScaffoldError('HFS_ADD_OPTION_INVALID', '--service takes <ServiceClass>=<module specifier>');
+    return { service, serviceModule };
+  }
+  if (!KEBAB.test(value)) throw new ScaffoldError('HFS_ADD_OPTION_INVALID', `--${need} ${value} must be kebab-case`);
+  return { [need]: value };
+}
+
+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 ?? []) Object.assign(values, requiredOption(need, options[need], noun));
+  for (const [key, rule] of Object.entries(spec.defaults ?? {})) {
+    if (values[key] === undefined) values[key] = rule === '@name' ? name : String(rule);
+  }
+  return values;
+}
+
+export 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;
+}
+
+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;
+};
+
+const renderBody = (text, 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];
+});
+
+/** Wiring may leave a placeholder unchanged; template bodies use the strict rendering refusal above. */
+export const fillKnownForms = (text, forms) => text.replace(PLACEHOLDER, (whole, name) => forms[name] ?? whole);
+
+function treesOf({ topics, repo, noun, spec }) {
+  const liteApi = noun === 'api' && repo.edition === 'lite';
+  return new Map([...topics].map((topic) => {
+    const entries = repo.edition === 'lite' ? selectLiteWebhookEntries(readTree(topic)) : readTree(topic);
+    return [topic, liteApi && topic === spec.topic ? selectLiteApiEntries(entries) : entries];
+  }));
+}
+
+function collectSlots(entries, platform, slots) {
+  for (const entry of entries) {
+    if (entry.path.startsWith(PLATFORM_PREFIX) === platform && entry.optional !== true && entry.slot) slots.add(entry.slot);
+  }
+}
+
+/** Optional entries gate nothing; the generated instance and platform slots decide the edition. */
+function validateWrittenSlots({ specs, topics, trees, manifest, repo, noun }) {
+  const slots = new Set();
+  for (const [, spec] of specs) collectSlots(trees.get(spec.topic), false, slots);
+  for (const topic of topics) collectSlots(trees.get(topic), true, slots);
+  refuseInEdition({ resolver: createSlotResolver(manifest, repo), slotIds: [...slots], command: `add ${noun}` });
+}
+
+function planEntry(entry, { topic, instance, shared, beRoot, withStamp, forms }) {
+  if (entry.optional === true) return null;
+  const target = fillPath(entry.path, withStamp);
+  if (target === null) return null;
+  const absolute = path.join(beRoot, ...target.split('/'));
+  // A platform capability is whole or absent: its index prevents regeneration of all its files.
+  if (!instance && fs.existsSync(path.join(beRoot, ...target.split('/').slice(0, 4), 'index.ts'))) return null;
+  if ((!instance || shared) && fs.existsSync(absolute)) return null;
+  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`);
+  return { target, absolute, body: renderBody(fs.readFileSync(templateFile, 'utf8'), forms, entry.template), instance };
+}
+
+function appendEntries(entries, context, planned) {
+  for (const entry of entries) {
+    const file = planEntry(entry, context);
+    if (file) planned.push(file);
+  }
+}
+
+/** Renders all topic-owned paths and bodies before any instance file is written. */
+export function planKind(context) {
+  const { noun, name, spec, params, repo, options, now } = context;
+  const specs = [noun, ...(spec.also ?? [])].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)]);
+  refuseFullAdapterInLite({ edition: repo.edition, topics: [...topics].map(readTopic), command: `add ${noun}` });
+  const trees = treesOf({ topics, repo, noun, spec });
+  validateWrittenSlots({ ...context, specs, topics, trees });
+  const values = Object.assign({}, ...specs.map(([each, eachSpec]) => variablesOf({ spec: eachSpec, noun: each, name, options })), variablesOf({ spec, noun, name, options }));
+  const withStamp = { ...values, epochMs13: String(now()).padStart(13, '0').slice(0, 13) };
+  const forms = formsOf(withStamp);
+  const beRoot = path.join(context.repoRoot, 'be');
+  const planned = [];
+  for (const [each, eachSpec] of specs) {
+    const entries = trees.get(eachSpec.topic).filter(entry => !entry.path.startsWith(PLATFORM_PREFIX));
+    appendEntries(entries, { topic: eachSpec.topic, instance: true, shared: each !== noun, beRoot, withStamp, forms }, planned);
+  }
+  for (const topic of topics) {
+    const entries = trees.get(topic).filter(entry => entry.path.startsWith(PLATFORM_PREFIX));
+    appendEntries(entries, { topic, instance: false, shared: false, beRoot, withStamp, forms }, planned);
+  }
+  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(', ')}`);
+  return { values, forms, beRoot, patterns, planned };
+}

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,53 +165,53 @@ 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("/"));
 
+/** A line that opens the error kinds array of the errors registration. */
+const KINDS_LINE = /^\s*kinds: \[$/;
+
 /**
- * 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.
+ * The composition file of an api app that holds its error kinds array: the root `app.module.ts`, or else the composition group
+ * `compose/<area>.ts` of the same app that holds it (the platform group of a scaffolded app). Repository-relative.
  */
-function wireImport(text, relative, { importLine, symbol, entry, kinds }) {
+function kindsHomeOf(root, appRelative) {
+  const holdsKinds = (relative) => fs.readFileSync(at(root, relative), "utf8").replace(/\r\n/g, "\n").split("\n").some((line) => KINDS_LINE.test(line));
+  if (holdsKinds(appRelative)) return appRelative;
+  const composeRelative = `${path.posix.dirname(appRelative)}/compose`;
+  const groups = fs.existsSync(at(root, composeRelative)) ? fs.readdirSync(at(root, composeRelative)).filter((file) => file.endsWith(".ts")).sort(byCodeUnit) : [];
+  const home = groups.map((file) => `${composeRelative}/${file}`).find(holdsKinds);
+  if (!home) throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `add table could not find the error kinds array in ${appRelative} or a group of its compose/`);
+  return home;
+}
+
+/** 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${symbol}\\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);
-  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`;
+  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").trimEnd()}\n`;
 }
 
-/** The api app root after the table's domain module is registered (its module and error kinds). */
-const wireDomainModule = (text, relative, name) =>
-  wireImport(text, relative, {
-    importLine: `import { ${snakeOf(name).toUpperCase()}_ERROR_KINDS, ${pascalOf(name)}Module } from "@modules/domain/${name}"`,
-    symbol: `${pascalOf(name)}Module`,
-    entry: `${pascalOf(name)}Module.register({ isGlobal: true })`,
-    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";
@@ -252,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) => {
@@ -261,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"],
@@ -275,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) }));
 };
@@ -316,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`;
 };
 
 /**
@@ -324,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(
@@ -349,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(
@@ -369,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,
@@ -382,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 = [
@@ -420,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);
@@ -435,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);
@@ -446,34 +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);
-    }
-    edit(ownerRelative, (text) => wireDomainModule(text, ownerRelative, 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);
@@ -483,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",
   };
 }