@starci/hfs 4.2.16 → 4.3.0

package/scaffold/add-table.mjs

@@ -186,13 +186,48 @@ function wireImport(text, relative, { importLine, symbol, entry, kinds }) {
   return `${lines.join("\n").replace(/\n+$/, "")}\n`;
 }
 
-/** The api app root after the table's domain module is registered (its module and error kinds). */
-const wireDomainModule = (text, relative, name) =>
+/** A line that opens the error kinds array of the errors registration. */
+const KINDS_LINE = /^\s*kinds: \[$/;
+
+/**
+ * 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 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${kinds}\\b`).test(line))) return text;
+  const lastImport = lines.reduce((last, line, index) => (line.startsWith("import ") ? index : last), -1);
+  const kindsAt = lines.findIndex((line) => KINDS_LINE.test(line));
+  if (lastImport < 0 || kindsAt < 0) throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `add table could not find the error kinds array in ${relative}`);
+  const kindsIndent = /^(\s*)/.exec(lines[kindsAt])?.[1] ?? "";
+  lines.splice(kindsAt + 1, 0, `${kindsIndent}    ${kinds},`);
+  lines.splice(lastImport + 1, 0, `import { ${kinds} } from "${specifier}"`);
+  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}
+
+/**
+ * The api app root after the table's domain module is registered: its module, and its error kinds too when the root holds the
+ * kinds array (`kindsInRoot`); otherwise wireKinds lists them in the composition group that does.
+ */
+const wireDomainModule = (text, relative, name, { kindsInRoot = true } = {}) =>
   wireImport(text, relative, {
-    importLine: `import { ${snakeOf(name).toUpperCase()}_ERROR_KINDS, ${pascalOf(name)}Module } from "@modules/domain/${name}"`,
+    importLine: kindsInRoot
+      ? `import { ${snakeOf(name).toUpperCase()}_ERROR_KINDS, ${pascalOf(name)}Module } from "@modules/domain/${name}"`
+      : `import { ${pascalOf(name)}Module } from "@modules/domain/${name}"`,
     symbol: `${pascalOf(name)}Module`,
     entry: `${pascalOf(name)}Module.register({ isGlobal: true })`,
-    kinds: `${snakeOf(name).toUpperCase()}_ERROR_KINDS`,
+    ...(kindsInRoot ? { kinds: `${snakeOf(name).toUpperCase()}_ERROR_KINDS` } : {}),
   });
 
 /** The api app root after the GraphQL server (platform/graphql) and the table's GraphQL transport are registered. */
@@ -458,7 +493,11 @@ export function addTable({
       const generated = emitTypes({ root });
       if (typeof generated === "string") edit(dbTypesPath, () => generated);
     }
-    edit(ownerRelative, (text) => wireDomainModule(text, ownerRelative, feature));
+    const kindsHome = kindsHomeOf(root, ownerRelative);
+    const kindsInRoot = kindsHome === ownerRelative;
+    edit(ownerRelative, (text) => wireDomainModule(text, ownerRelative, feature, { kindsInRoot }));
+    if (!kindsInRoot)
+      edit(kindsHome, (text) => wireKinds(text, kindsHome, { kinds: `${snakeOf(feature).toUpperCase()}_ERROR_KINDS`, specifier: `@modules/domain/${feature}` }));
     const registrations = [
       ...(repo.edition === "lite" ? ["table"] : []),
       ...(fe ? ["api", "graphql"] : []),

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 { 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,77 +43,28 @@ 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 }) {
+  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 });
@@ -275,9 +143,12 @@ function wireLiteFeature({ repoRoot, repo, noun, name }) {
   return created;
 }
 
-/** Adds one generated webhook provider to the lite API's parsed options and enables exact raw-body verification. */
+/** Adds one generated webhook provider to the lite API's typed env reader (or an existing inline bootstrap) and enables exact raw-body verification. */
 function wireLiteWebhookConfig({ repoRoot, app, provider }) {
-  const relative = `be/apps/${app}/src/main.ts`;
+  const envRelative = `be/apps/${app}/src/${app}.env.ts`;
+  const relative = fs.existsSync(path.join(repoRoot, ...envRelative.split('/')))
+    ? envRelative
+    : `be/apps/${app}/src/main.ts`;
   const file = path.join(repoRoot, ...relative.split('/'));
   let text = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
   const httpSecurityImport = /^import \{ ([^}]+) \} from "@modules\/platform\/http-security"$/m;
@@ -290,11 +161,12 @@ function wireLiteWebhookConfig({ repoRoot, app, provider }) {
     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)}),`;
+  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);
       if (!found) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add webhook could not find httpSecurity options in ${relative}`);
@@ -304,6 +176,11 @@ function wireLiteWebhookConfig({ repoRoot, app, provider }) {
   }
   text = text.replace('NestFactory.create(AppModule.register(options))', 'NestFactory.create(AppModule.register(options), { rawBody: true })');
   fs.writeFileSync(file, text);
+  if (relative === envRelative) {
+    const main = path.join(repoRoot, 'be', 'apps', app, 'src', 'main.ts');
+    const entry = fs.readFileSync(main, 'utf8').replace('NestFactory.create(AppModule.register(options))', 'NestFactory.create(AppModule.register(options), { rawBody: true })');
+    fs.writeFileSync(main, entry);
+  }
 }
 
 /**
@@ -313,7 +190,7 @@ function wireLiteWebhookConfig({ repoRoot, app, provider }) {
 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;
@@ -326,16 +203,6 @@ function wire({ beRoot, wire: target, forms, noun, name }) {
   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'));

package/scaffold/app.mjs

@@ -27,6 +27,7 @@ import { revParseQuery } from '../runtime/scripts/api/git/rev-parse-query.mjs';
 import { lsFiles } from '../runtime/scripts/api/git/ls-files.mjs';
 import { insidePath, samePath } from '../runtime/scripts/lib/path-key.mjs';
 import { byCodeUnit } from '../report/order.mjs';
+import { sonarGateName } from '../sync/sonar-key.mjs';
 
 const NAME = /^[a-z][a-z0-9-]*$/;
 const APP_DIR = '__app__';
@@ -353,8 +354,7 @@ export const PARTIAL_VARIABLES = new Proxy(Object.create(null), {
 const CLI_APP_DIR = 'apps/cli/';
 const declaresCliApp = app => app.sides.be.apps.some(entry => entry.kind === 'cli' && entry.name === 'cli');
 
-const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc', '.starciwork/workspace.yaml',
-  '.starciwork/index.yaml', '.starciwork/features/system-health/index.yaml']);
+const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc']);
 const LITE_DEFERRED_GENERATOR_FILES = new Set([
   'src/modules/platform/database/database.sql.ts',
   'src/modules/platform/database/migration-runner.service.ts',
@@ -413,10 +413,10 @@ function skeletonDirectory(scope, directory, app, vars, include = () => true) {
   return files;
 }
 
-/** The canonical product catalog and feature nodes shared by scaffold and upgrades of older lite apps. */
+/** The canonical full Work workspace, catalog and feature nodes an edition upgrade may need. */
 export function scaffoldWorkSeeds(project) {
   return skeletonDirectory('app', 'skeleton', { project }, {},
-    rel => rel === '.starciwork/index.yaml' || rel.startsWith('.starciwork/features/'));
+    rel => rel === '.starciwork/workspace.yaml' || rel === '.starciwork/index.yaml' || rel.startsWith('.starciwork/features/'));
 }
 
 /**
@@ -576,7 +576,7 @@ export function scaffoldApp({ name, into, presets, edition = 'full', manifest =
       { path: `fe/packages/${name}-${pkg}/tsconfig.json`, content: jsonText(fePackageTsconfig()) },
       { path: `fe/packages/${name}-${pkg}/tsconfig.build.json`, content: jsonText(fePackageBuildTsconfig()) },
     ])),
-    ...['app', 'be', 'fe'].flatMap(scope => skeletonOf(scope, app, { sonarGate: parseYaml(fs.readFileSync(SONAR_GATE_FILE, 'utf8')).gate.name, timestamp, ...supabasePortVars(name) })),
+    ...['app', 'be', 'fe'].flatMap(scope => skeletonOf(scope, app, { sonarGate: sonarGateName(parseYaml(fs.readFileSync(SONAR_GATE_FILE, 'utf8')), app.edition), timestamp, ...supabasePortVars(name) })),
   ];
   const writes = scaffoldWrites(root, original);
   try {

package/scaffold/image.mjs

@@ -2,11 +2,11 @@
 // (templates/<side>/image/<kind>, the same render starci app scaffold uses). It never overwrites a file.
 import fs from 'node:fs';
 import path from 'node:path';
-import { imageFiles, loadHfs, validateHfs } from '../sync/index.mjs';
+import { appSource, imageFiles, loadHfs, validateHfs } from '../sync/index.mjs';
 
 /** Writes the missing Dockerfiles of the app at `repoRoot` (the folder of hfs.json); the app-relative paths written. */
 export function newImages({ repoRoot }) {
-  const files = imageFiles(validateHfs(loadHfs(repoRoot)));
+  const files = imageFiles(validateHfs(loadHfs(repoRoot)), appSource(repoRoot));
   const written = [];
   for (const file of files) {
     const target = path.join(repoRoot, ...file.path.split('/'));

package/src/main.mjs

@@ -36,9 +36,10 @@
 //                                            one placeholder it per public method. Never overwrites a file. Both editions: a lite back end keeps full's unit specs (owner ruling 2026-10-12).
 //   starci app new image [--cwd <dir>]                  the Dockerfile of every declared app that has none, from the image canon (scaffold/image.mjs); never overwrites
 //   starci app new spec <file>.service.ts [--cwd <dir>]  the spec skeleton of an existing service, read from its constructor with the repository's TypeScript
-//   starci app secret list | show <slug> | set <slug> | gen <slug> [--key NAME] [--env NAME] [--age RECIPIENT] [--bytes N] [--cwd DIR]
-//                                            the sealed secrets of `.starcistacks/<env>/secrets/` (runtime scripts/hfs/secret.mjs over the sops api): `set` reads the value from
-//                                            stdin, `gen` seals a random one, `show` decrypts one to stdout; a plain `sops` command in a runbook is retired.
+//   starci app secret init | set <env> <slug> <KEY> [--generate <bytes>] | get <env> <slug> [KEY] --to-file [--reveal]
+//   starci app secret materialize <env> | list <env>
+//                                            dotenv custody in .starcistacks, public age rule initialization, private KEY files outside Git;
+//                                            values reach stdout only when get explicitly receives --reveal.
 //   starci app add <api|webhook|realtime|saga|job|reactor|queue|projection> <name> [--event <event> --from <service> --service <Class>=<module>] [--owner <service> --failed <event> --done <event>] [--connection <name>] [--cwd <dir>]
 //                                            exactly that kind's file tree, generated FROM the files: tree of its pattern topic (knowledge/patterns/be) with the
 //                                            one template body of each entry (templates/be/patterns), plus the platform capabilities it needs when they are missing;
@@ -84,7 +85,11 @@ starci app emit [--cwd <dir>]
 starci app new service <dir> <name> [--inject <binding>...] [--cwd <dir>]
 starci app new spec <file>.service.ts [--cwd <dir>]
 starci app new image [--cwd <dir>]
-starci app secret list|show|set|gen ... [--cwd <dir>]
+starci app secret init [--cwd <dir>]
+starci app secret set <env> <slug> <KEY> [--generate <bytes>] [--cwd <dir>]
+starci app secret get <env> <slug> [KEY] --to-file [--reveal] [--cwd <dir>]
+starci app secret materialize <env> [--cwd <dir>]
+starci app secret list <env> [--cwd <dir>]
 starci app hygiene [--cwd <dir>]
 `;
 const PER_CODE_LIMIT = 25;
@@ -124,7 +129,7 @@ function printCheck(result, out) {
     for (const f of list.slice(0, PER_CODE_LIMIT)) out(`  - ${f.message}\n`);
     if (list.length > PER_CODE_LIMIT) out(`  ... and ${list.length - PER_CODE_LIMIT} more (use --json for all)\n`);
   }
-  out(`\n${counts.error} error finding${counts.error === 1 ? '' : 's'}, ${counts.info} report-only\n`);
+  out(`\n${counts.error} error finding${counts.error === 1 ? '' : 's'}, ${counts.warning} warning${counts.warning === 1 ? '' : 's'}, ${counts.info} report-only\n`);
 }
 
 function printExplain(e, out) {
@@ -245,6 +250,7 @@ async function installedStackMain(cwd) {
 /** `cwd`, `presets`, `prettier`, `lock`, `run` and `stackMain` are test seams (`run` is the Supabase types command runner); stdout and stderr never have to be process globals. */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,
+  env = process.env, stdin, sops, tools, platform,
 } = {}) {
   try {
     const global = globalOptions(argv, path.resolve(baseCwd));
@@ -254,7 +260,7 @@ export async function main(argv, {
     if (!VERBS.includes(verb)) { stderr(USAGE); return 2; }
     if (verb === 'sync' || verb === 'hygiene') return await syncMain([verb, ...rest], { cwd: global.cwd, stdout: out });
     if (verb === 'lint') return await lintMain(rest, { cwd: global.cwd, stdout: out, presets, prettier });
-    if (verb === 'secret') return secretMain(rest, { stdout: out, stderr, cwd: global.cwd });
+    if (verb === 'secret') return secretMain(rest, { stdout: out, stderr, cwd: global.cwd, env, stdin, sops, tools, platform });
     if (verb === 'upgrade') return await upgradeMain(['--repo', global.cwd, ...(global.edition ? ['--edition', global.edition] : []), ...rest], { stdout: out, presets });
     if (verb === 'stack') {
       const run = stackMain ?? await installedStackMain(global.cwd);

package/sync/index.mjs

@@ -24,6 +24,7 @@ import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveRepoDeclarat
 import { managedGroupOf } from '../runtime/scripts/hfs/edition-slots.mjs';
 import { feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { DEFAULT_PORT, NODE_IMAGE, dockerfilePath } from '../runtime/scripts/hfs/rules/docker.mjs';
+import { isFile } from '../runtime/scripts/lib/fs-kind.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 
@@ -79,8 +80,8 @@ export function targetsOf(scope, { edition = 'full', manifest = loadSlotManifest
     }
   }
   const unlisted = scope === APP_SCOPE
-    ? UNLISTED_TARGETS.map(target => edition === 'lite' && target.path === '.gitignore'
-      ? { ...target, template: 'app/gitignore-lite' }
+    ? UNLISTED_TARGETS.map(target => edition === 'lite'
+      ? { ...target, template: target.path === '.gitignore' ? 'app/gitignore-lite' : 'app/starciwork.gitignore-lite' }
       : { ...target })
     : [];
   return [...listed, ...unlisted];
@@ -139,7 +140,9 @@ const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
 
 /**
  * The be source of the app at `root` the coverage components read: { files, read }, `files` be-relative posix paths of every `*.ts` file under
- * be/apps and be/src (build output and dependencies skipped) and `read` their text. An app with no be folder has no files.
+ * be/apps and be/src (build output and dependencies skipped) and `read` their text. `workPresent` records whether the optional
+ * lite brand tree exists, so sync can preserve its absence. `hasImage` identifies authored optional Dockerfiles without reading
+ * their content. An app with no be folder has no source files.
  */
 export function appSource(root) {
   const files = [];
@@ -152,7 +155,8 @@ export function appSource(root) {
     }
   };
   for (const dir of ['apps', 'src']) walk(dir);
-  return { files: files.sort(byCodeUnit), read: file => fs.readFileSync(path.join(root, 'be', file), 'utf8') };
+  return { files: files.sort(byCodeUnit), read: file => fs.readFileSync(path.join(root, 'be', file), 'utf8'),
+    workPresent: fs.existsSync(path.join(root, '.starciwork')), hasImage: file => isFile(path.join(root, file), { followLinks: false }) };
 }
 
 /**
@@ -183,7 +187,7 @@ export function jestCoverageSource(coverage) {
  * `docker:build:<app>` builds the image of one app (the exact command its Dockerfile header states, tag `<project>/<app>:dev`) and
  * `docker:build` builds every image, one after the other, never pushing.
  */
-export function appScripts(app) {
+export function appScripts(app, source) {
   const line = (name, command) => `${JSON.stringify(name)}: ${JSON.stringify(command)},`;
   const be = app.sides.be.apps;
   const fe = app.sides.fe.apps;
@@ -194,7 +198,7 @@ export function appScripts(app) {
   const workspace = entry => feAppPackageName(app.project, entry.name);
   // Both editions generate before they run (owner ruling 2026-10-13): the fe's GraphQL wire types, and under lite the Supabase types check.
   const dev = entry => `npm run codegen --silent && turbo run dev --filter=${workspace(entry)}`;
-  const images = imageEntries(app);
+  const images = imageEntries(app, source);
   const imageCommand = ({ side, entry }) => `docker build -f ${dockerfilePath(side, entry.name)} -t ${app.project}/${entry.name}:dev .`;
   return [
     ...(apis.length === 1 ? [line('dev:be', watch(apis[0]))] : apis.map(entry => line(`dev:be:${entry.name}`, watch(entry)))),
@@ -219,9 +223,10 @@ const opensPackages = side => (side.optionalSlots ?? []).some(id => id === 'repo
 /** The stylesheets of the fe side the CSS canon judges, relative to fe/: every app and every workspace package (slot fe.route, fe.package.*). */
 export const STYLE_GLOB = '{apps,packages}/*/src/**/*.css';
 
-/** The images a declaration renders commands and CI entries for. Lite's default deployable is the back-end API image. */
-function imageEntries(app) {
-  return [...app.sides.be.apps.map(entry => ({ side: 'be', entry })), ...(app.edition === 'lite' ? [] : app.sides.fe.apps.map(entry => ({ side: 'fe', entry })))];
+/** Required app images plus lite front ends whose optional Dockerfile the source holds. */
+function imageEntries(app, source) {
+  const frontend = app.sides.fe.apps.filter(entry => app.edition !== 'lite' || source?.hasImage?.(dockerfilePath('fe', entry.name)));
+  return [...app.sides.be.apps.map(entry => ({ side: 'be', entry })), ...frontend.map(entry => ({ side: 'fe', entry }))];
 }
 
 /**
@@ -229,9 +234,9 @@ function imageEntries(app) {
  * runs on the release tag, so every image is built there; no path filter narrows it. A YAML block mapping per entry, indented for
  * `strategy.matrix.include`.
  */
-export function imageMatrix(app) {
+export function imageMatrix(app, source) {
   const entry = (side, item) => `          - name: ${item.name}\n            file: ${dockerfilePath(side, item.name)}`;
-  return imageEntries(app).map(image => entry(image.side, image.entry)).join('\n');
+  return imageEntries(app, source).map(image => entry(image.side, image.entry)).join('\n');
 }
 
 const IMAGE_TEMPLATE = Object.freeze({ api: 'be/image/api', worker: 'be/image/worker', cli: 'be/image/cli', next: 'fe/image/next' });
@@ -241,14 +246,14 @@ const IMAGE_TEMPLATE = Object.freeze({ api: 'be/image/api', worker: 'be/image/wo
  * and then the app's own, judged by the docker rules (R187-R191). A Next image copies the fe packages only when the fe side opts into
  * them and the be contracts only when the fe side reads them, so each COPY names a folder the app has.
  */
-export function imageFiles(app) {
+export function imageFiles(app, source) {
   const side = app.sides.fe;
   const inputs = [...(opensPackages(side) ? ['fe/packages'] : []), ...((side.reads ?? []).includes('be/contracts/') ? ['be/contracts'] : [])];
   const copyInputs = inputs.map(folder => `COPY ${folder} ${folder}\n`).join('');
   // The folders outside be/ that the back end declares it reads (the generated Supabase types of a lite back end, which an upgraded app keeps reading) are in every one of its images.
   const beFolders = (app.sides.be.reads ?? []).map(folder => folder.replace(/\/$/, ''));
   const copyBeInputs = beFolders.map(folder => `COPY ${folder} ${folder}\n`).join('');
-  const entries = imageEntries(app).map(({ side: which, entry: item }) => ({ side: which, item }));
+  const entries = imageEntries(app, source).map(({ side: which, entry: item }) => ({ side: which, item }));
   return entries.map(({ side: which, item }) => {
     const template = IMAGE_TEMPLATE[item.kind];
     const vars = { project: app.project, app: item.name, nodeImage: NODE_IMAGE, port: DEFAULT_PORT, copyInputs, copyBeInputs };
@@ -265,7 +270,7 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
   return {
     header: HEADER(scope),
     appBinary: APP_BINARY,
-    appScripts: appScripts(app),
+    appScripts: appScripts(app, source),
     // turbo builds every fe app workspace; ^build (turbo.json) builds the packages each app imports first, and caches both.
     buildFe: 'npm run codegen --silent && turbo run build --filter=./fe/apps/*',
     // The be side with its tsc; every fe workspace with its own typecheck script through turbo (the packages are built first: ^build).
@@ -283,7 +288,7 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     codecovComponents: scope === APP_SCOPE ? componentsYaml(coverageComponents(manifest, { ...source, apps: app.sides.be.apps, providers })) : '',
     tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
     styleGlob: STYLE_GLOB,
-    imageMatrix: imageMatrix(app),
+    imageMatrix: imageMatrix(app, source),
     imageProject: app.project,
   };
 }
@@ -310,7 +315,9 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
   const hasTemplate = name => { try { return readTemplate(name) !== undefined; } catch { return false; } };
   return SCOPES.flatMap(scope => {
     const vars = variables(app, scope, presets, sonarKey, manifest, source);
-    return targetsOf(scope, { edition: app.edition, manifest, hasTemplate }).map(target => {
+    const targets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate })
+      .filter(target => !(app.edition === 'lite' && source?.workPresent === false && target.path === '.starciwork/.gitignore'));
+    return targets.map(target => {
       const body = render(readTemplate(target.template), vars, readTemplate);
       const where = onSide(scope, target.path);
       if (target.mode === 'scripts') {

package/templates/app/gitignore

@@ -18,6 +18,7 @@ next-env.d.ts
 !.starcistacks/*/infra/compose/**
 !.starcistacks/*/infra/k8s/**
 !.starcistacks/*/infra/terraform/**
+!.starcistacks/*/infra/swarm/**
 .starcistacks/*/infra/**/.env
 .starcistacks/*/infra/**/.env.*
 .starcistacks/*/infra/**/*.env

package/templates/app/gitignore-lite

@@ -21,6 +21,7 @@ next-env.d.ts
 !.starcistacks/*/infra/compose/**
 !.starcistacks/*/infra/k8s/**
 !.starcistacks/*/infra/terraform/**
+!.starcistacks/*/infra/swarm/**
 .starcistacks/*/infra/**/.env
 .starcistacks/*/infra/**/.env.*
 .starcistacks/*/infra/**/*.env

package/templates/app/hooks/husky/pre-commit

@@ -2,19 +2,14 @@
 # Commit gate (L0 only): work hygiene and the secrets guard of the staged files, eslint of the staged files of each side,
 # stylelint over the staged CSS of fe, a prettier check of the staged files. Types and the targeted specs belong to the op gate.
 npx starci app hygiene
-be=$(git diff --cached --name-only --diff-filter=ACMR --relative=be -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' || true)
-if [ -n "$be" ]; then
-  (cd be && npx eslint $be)
-fi
-fe=$(git diff --cached --name-only --diff-filter=ACMR --relative=fe -- '*.ts' '*.tsx' '*.mts' '*.cts' '*.js' '*.jsx' '*.mjs' '*.cjs' || true)
-if [ -n "$fe" ]; then
-  (cd fe && npx eslint --max-warnings=0 --no-warn-ignored $fe)
-fi
+# NUL-delimited paths keep filenames intact; bounded batches fit the Windows command line.
+git diff --cached --name-only --diff-filter=ACMR -z --relative=be -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' |
+  xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd be && npx eslint -- "$@"; fi' sh || exit $?
+git diff --cached --name-only --diff-filter=ACMR -z --relative=fe -- '*.ts' '*.tsx' '*.mts' '*.cts' '*.js' '*.jsx' '*.mjs' '*.cjs' |
+  xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd fe && npx eslint --max-warnings=0 --no-warn-ignored -- "$@"; fi' sh || exit $?
 styles=$(git diff --cached --name-only --diff-filter=ACMR --relative=fe -- '*.css' || true)
 if [ -n "$styles" ]; then
   (cd fe && npx stylelint $styles)
 fi
-formatted=$(git diff --cached --name-only --diff-filter=ACMR || true)
-if [ -n "$formatted" ]; then
-  npx prettier --check --ignore-unknown $formatted
-fi
+git diff --cached --name-only --diff-filter=ACMR -z |
+  xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then npx prettier --check --ignore-unknown -- "$@"; fi' sh || exit $?

package/templates/app/skeleton/.sops.yaml

@@ -1,2 +1,2 @@
-# Set a project-owned age recipient before encrypting the first secret.
+# Run `starci app secret init` to set a project-owned age recipient before encrypting the first secret.
 creation_rules: []