@starci/hfs 4.11.22 → 4.12.0

package/sync/index.mjs

@@ -10,8 +10,8 @@
 // and are listed in this module: the marked blocks of the root .gitignore and README.md, and .starciwork/.gitignore, which lives inside the
 // .starciwork directory slot. Every file is rendered with the app's hfs.json (both sides and their apps) and, for the Sonar
 // exclusions, the jest preset the app installs for its be side and the one coverage scope derived from the slot manifest
-// (scripts/hfs/coverage-scope.mjs: the be/jest.config.js scope, sonar.coverage.exclusions and the codecov.yml paths, components and exclusions). `--check` compares the sha256 of the rendered content with the
-// file on disk and fails on any drift; `--write` rewrites the drifted files. `.gitignore` and README.md are shared files: only the marked
+// (scripts/hfs/coverage-scope.mjs: the be/jest.config.js scope, sonar.coverage.exclusions and the codecov.yml paths, components and exclusions). The default run (a dry run) compares the sha256 of the rendered content with the
+// file on disk and fails on any drift; `--execute` rewrites the drifted files. `.gitignore` and README.md are shared files: only the marked
 // block is managed and the app's own lines around it are left alone. The root package.json is managed by its `scripts` block
 // only (mode scripts, compared as parsed JSON): the rest of the file (dependencies, the npm workspaces fe/apps/* and fe/packages/*,
 // HFS_MONO_WORKSPACES) is the app's. The fe side runs through turbo (turbo.json, app.task-graph): each fe app and package is a workspace.
@@ -22,7 +22,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { braceVariants } from '../runtime/scripts/lib/glob.mjs';
 import { codecovPaths, coverageComponents, jestCoverage, sonarCoverageExclusions } from '../runtime/scripts/hfs/coverage-scope.mjs';
-import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveRepoDeclaration, slotInEdition } from '../runtime/scripts/hfs/slots.mjs';
+import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveAppDeclaration, slotInEdition } from '../runtime/scripts/hfs/slots.mjs';
 import { managedGroupOf } from '../runtime/scripts/hfs/edition-slots.mjs';
 import { declaredSlotEnabled } from '../runtime/scripts/hfs/declaration-slots.mjs';
 import { feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
@@ -42,7 +42,6 @@ import { readTruths } from '../runtime/scripts/lib/loosening-state.mjs';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
 import { bootstrapSection } from '../runtime/scripts/hfs/rules/database-constants.mjs';
 import { SERVER_AGE_IDENTITY } from '../stack/server-key.mjs';
-
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
 const APP_BINARY = 'starci app';
@@ -50,116 +49,114 @@ const APP_BINARY = 'starci app';
 export const SCOPES = Object.freeze([APP_SCOPE, ...SIDES]);
 const BLOCK_BEGIN = '# >>> starci app sync (managed block; do not edit) >>>';
 const BLOCK_END = '# <<< starci app sync <<<';
-const HEADER = scope => `# Generated by ${APP_BINARY} sync (${scope === APP_SCOPE ? 'app root' : scope + ' side'}). Do not edit: run "npx ${APP_BINARY} sync --write".`;
-
+const HEADER = (scope) => `# Generated by ${APP_BINARY} sync (${scope === APP_SCOPE ? 'app root' : scope + ' side'}). Do not edit: run "npx ${APP_BINARY} sync --execute".`;
 export class SyncError extends Error {
-  constructor(code, message) {
-    super(`${code}: ${message}`);
-    this.code = code;
-  }
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
 }
-
 // mode: file = whole file, block = the marked block inside a file the app also writes to, scripts = the `scripts` block of
 // package.json, section = the whole file but the one marked section a database verb owns (db/bootstrap.sql, whose squash section
 // `starci app db baseline --squash` writes). A template that can hold a comment opens with {{header}}; a file whose exact content is
 // specified (JSON, the eslint one-liner) has no header.
 const MODE_OF_GROUP = Object.freeze({ 'package-scripts': 'scripts', 'package-scripts-lite': 'scripts', 'db-bootstrap': 'section' });
 const GLOB_CHARACTERS = new Set('*?<>{}[]');
-const literalFile = file => file.length >= 2 && !file.endsWith('/') && ![...file].some(character => GLOB_CHARACTERS.has(character));
-
+const literalFile = (file) => file.length >= 2 && !file.endsWith('/') && ![...file].some(character => GLOB_CHARACTERS.has(character));
 /** The targets no managedBy slot lists as a whole file (see the header of this module); both belong to the app root. */
 const UNLISTED_TARGETS = Object.freeze([
-  { path: '.gitignore', template: 'app/gitignore', mode: 'block' },
-  { path: '.starciwork/.gitignore', template: 'app/starciwork.gitignore', mode: 'file' },
-].map(Object.freeze));
-
+    { path: '.gitignore', template: 'app/gitignore', mode: 'block' },
+    { path: '.starciwork/.gitignore', template: 'app/starciwork.gitignore', mode: 'file' },
+].map((target) => Object.freeze(target)));
 const templateName = (scope, group, file) => `${scope}/${group}/${file.split('/').map(segment => segment.replace(/^\./, '')).join('/')}`;
 const onSide = (scope, file) => (scope === APP_SCOPE ? file : `${scope}/${file}`);
-
 function managedTemplate(scope, group, file, hasTemplate) {
-  const directories = [scope, 'common'];
-  const undotted = directories.map(dir => templateName(dir, group, file)).find(name => hasTemplate(name));
-  if (undotted || !['skeleton', 'skeleton-lite'].includes(group)) return undotted;
-  return directories.map(dir => `${dir}/${group}/${file}`).find(name => hasTemplate(name));
+    const directories = [scope, 'common'];
+    const undotted = directories.map(dir => templateName(dir, group, file)).find(name => hasTemplate(name));
+    if (undotted || !['skeleton', 'skeleton-lite'].includes(group))
+        return undotted;
+    return directories.map(dir => `${dir}/${group}/${file}`).find(name => hasTemplate(name));
 }
-
 function slotTargets(slot, scope, edition, manifest, hasTemplate, enabled) {
-  if (!slot.profiles.includes(scope) || !slotInEdition(manifest, slot, edition)) return [];
-  // An opt-in slot is rendered only for a repository that enables it (app.browser-config with `browser: true`).
-  if (slot.presence === 'opt-in' && !enabled(slot)) return [];
-  if (edition === 'lite' && litePresenceOf(slot, scope) === 'forbidden') return [];
-  const group = managedGroupOf(slot, edition);
-  if (group === undefined) return [];
-  const effectivePath = edition === 'lite' ? (slot.lite?.path ?? slot.path) : slot.path;
-  return braceVariants(effectivePath).map(file => {
-    const managedKey = edition === 'lite' && slot.liteManagedBy !== undefined ? 'liteManagedBy' : 'managedBy';
-    if (!literalFile(file)) throw new SyncError('HFS_SYNC_MANIFEST_MANAGED', `slot ${slot.id} names ${managedKey} but its path ${effectivePath} is not a list of literal files (${file})`);
-    const template = managedTemplate(scope, group, file, hasTemplate);
-    if (!template) throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${scope}, but templates/{${scope},common}/${group} has no template for it`);
-    return { path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id };
-  });
-}
-
+    if (!slot.profiles.includes(scope) || !slotInEdition(manifest, slot, edition))
+        return [];
+    // An opt-in slot is rendered only for a repository that enables it (app.browser-config with `browser: true`).
+    if (slot.presence === 'opt-in' && !enabled(slot))
+        return [];
+    if (edition === 'lite' && litePresenceOf(slot, scope) === 'forbidden')
+        return [];
+    const group = managedGroupOf(slot, edition);
+    if (group === undefined)
+        return [];
+    const effectivePath = edition === 'lite' ? (slot.lite?.path ?? slot.path) : slot.path;
+    return braceVariants(effectivePath).map((file) => {
+        const managedKey = edition === 'lite' && slot.liteManagedBy !== undefined ? 'liteManagedBy' : 'managedBy';
+        if (!literalFile(file))
+            throw new SyncError('HFS_SYNC_MANIFEST_MANAGED', `slot ${slot.id} names ${managedKey} but its path ${effectivePath} is not a list of literal files (${file})`);
+        const template = managedTemplate(scope, group, file, hasTemplate);
+        if (!template)
+            throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${scope}, but templates/{${scope},common}/${group} has no template for it`);
+        return { path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id };
+    });
+}
 function unlistedTargets(scope, edition) {
-  if (scope !== APP_SCOPE) return [];
-  return UNLISTED_TARGETS.map(target => {
-    if (edition !== 'lite') return { ...target };
-    return { ...target, template: target.path === '.gitignore' ? 'app/gitignore-lite' : 'app/starciwork.gitignore-lite' };
-  });
+    if (scope !== APP_SCOPE)
+        return [];
+    return UNLISTED_TARGETS.map(target => {
+        if (edition !== 'lite')
+            return { ...target };
+        return { ...target, template: target.path === '.gitignore' ? 'app/gitignore-lite' : 'app/starciwork.gitignore-lite' };
+    });
 }
-
 /**
  * Every target of `scope` (app, be or fe), its path relative to that scope's folder: the files the manifest's managedBy slots
  * list, then (app root) the unlisted ones. A slot that names managedBy lists literal files only, and each has a template under
  * its scope or under common. `enabled(slot)` decides an opt-in slot (renderTargets passes the declaration's); without it every slot
  * counts, which is what an inventory of the templates needs.
  */
-export function targetsOf(scope, { edition = 'full', manifest = loadSlotManifest(), hasTemplate = name => fs.existsSync(path.join(TEMPLATES_DIR, name)), enabled = () => true } = {}) {
-  const listed = manifest.slots.flatMap(slot => slotTargets(slot, scope, edition, manifest, hasTemplate, enabled));
-  return [...listed, ...unlistedTargets(scope, edition)];
-}
-
-const lf = text => text.replace(/\r\n/g, '\n');
-export const hashOf = text => createHash('sha256').update(lf(text)).digest('hex');
-
+export function targetsOf(scope, { edition = 'full', manifest = loadSlotManifest(), hasTemplate = (name) => fs.existsSync(path.join(TEMPLATES_DIR, name)), enabled = (_slot) => true } = {}) {
+    const listed = manifest.slots.flatMap(slot => slotTargets(slot, scope, edition, manifest, hasTemplate, enabled));
+    return [...listed, ...unlistedTargets(scope, edition)];
+}
+const lf = (text) => text.replace(/\r\n/g, '\n');
+export const hashOf = (text) => createHash('sha256').update(lf(text)).digest('hex');
 /**
  * The hfs.json sync reads: an app declaration valid for the manifest it pins (both sides, their apps, connections, optional slots,
  * reads). Sync never renders configs for a declaration the eslint canons and starci app check would refuse, so a pin bump cannot leave
  * lint unable to start. Answers the resolved app.
  */
 export function validateHfs(hfs, manifest = loadSlotManifest()) {
-  try {
-    return resolveRepoDeclaration(manifest, hfs);
-  } catch (error) {
-    throw new SyncError('HFS_SYNC_HFS_INVALID', `hfs.json is not a valid app declaration for manifest ${manifest.version}: ${error.message}`);
-  }
+    try {
+        return resolveAppDeclaration(manifest, hfs);
+    }
+    catch (error) {
+        throw new SyncError('HFS_SYNC_HFS_INVALID', `hfs.json is not a valid app declaration for manifest ${manifest.version}: ${error.message}`);
+    }
 }
-
 function readBundled(name) {
-  return lf(fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8'));
+    return lf(fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8'));
 }
-
 /**
  * Fill `{{name}}` from vars and expand `{{> partial}}` lines. A partial line may be written as a line comment (`// {{> partial}}`)
  * so a JavaScript template stays valid source before rendering. Variable-only lines may also use a line comment;
  * empty variable-only lines disappear and an unknown name is an error.
  */
 export function render(text, vars, readTemplate = readBundled) {
-  const withPartials = text.replace(/^(?:\/\/ )?\{\{> ([\w./-]+)\}\}\n/gm, (_, name) => trailingNewline(render(readTemplate(name), vars, readTemplate)));
-  const presentLines = withPartials.replace(/^[ \t]*(?:\/\/ )?\{\{([A-Za-z]\w*)\}\}[ \t]*(?:\n|$)/gm,
-    (line, key) => vars[key] === '' ? '' : line.replace(/^(\s*)\/\/ /, '$1'));
-  return presentLines.replace(/\{\{([A-Za-z]\w*)\}\}/g, (_, key) => {
-    if (!Object.hasOwn(vars, key)) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `template names {{${key}}}, which sync does not provide`);
-    return vars[key];
-  });
-}
-
+    const withPartials = text.replace(/^(?:\/\/ )?\{\{> ([\w./-]+)\}\}\n/gm, (_, name) => trailingNewline(render(readTemplate(name), vars, readTemplate)));
+    const presentLines = withPartials.replace(/^[ \t]*(?:\/\/ )?\{\{([A-Za-z]\w*)\}\}[ \t]*(?:\n|$)/gm, (line, key) => vars[key] === '' ? '' : line.replace(/^(\s*)\/\/ /, '$1'));
+    return presentLines.replace(/\{\{([A-Za-z]\w*)\}\}/g, (_, key) => {
+        if (!Object.hasOwn(vars, key))
+            throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `template names {{${key}}}, which sync does not provide`);
+        return vars[key];
+    });
+}
 function trailingNewline(text) {
-  let end = text.length;
-  while (end > 0 && text[end - 1] === '\n') end -= 1;
-  return text.slice(0, end) + '\n';
+    let end = text.length;
+    while (end > 0 && text[end - 1] === '\n')
+        end -= 1;
+    return text.slice(0, end) + '\n';
 }
-
 /**
  * The base image of a lite app's managed .starcistacks/images/db/Dockerfile (contexts/stack/pins.yaml images postgres, ruling:lite-official-postgres-image): the
  * Docker Official postgres image by digest, to which the Dockerfile adds PGVECTOR_PACKAGE from PGDG and the PGMQ release.
@@ -172,57 +169,53 @@ export const PGVECTOR_PACKAGE = 'postgresql-17-pgvector=0.8.7-1.pgdg13+1';
  * when Docker adds it. PGDG does not package pgmq; it is SQL objects only, so the Dockerfile copies its control and script files.
  */
 export const PGMQ = Object.freeze({
-  version: '1.13.1',
-  source: 'https://github.com/pgmq/pgmq/archive/refs/tags/v1.13.1.tar.gz',
-  sha256: '67221f288f42f95c002a64df40f7d660e765e32df8ada0f2672ba915a14827f7',
+    version: '1.13.1',
+    source: 'https://github.com/pgmq/pgmq/archive/refs/tags/v1.13.1.tar.gz',
+    sha256: '67221f288f42f95c002a64df40f7d660e765e32df8ada0f2672ba915a14827f7',
 });
 /** The local tag the development db container and the drift scratch database run, built from the app's .starcistacks/images/db/Dockerfile. */
-export const dbLocalImage = project => `${project}-db:local`;
+export const dbLocalImage = (project) => `${project}-db:local`;
 /** The digest-pinned image of a lite app's declared Redis, in every environment that runs it (ruling:R212/case-10). */
 export const REDIS_IMAGE = 'redis:7@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f';
-
-const redisDevText = project => render(readBundled('app/package-scripts/redis-dev.json'), { project, redisImage: REDIS_IMAGE });
-
+const redisDevText = (project) => render(readBundled('app/package-scripts/redis-dev.json'), { project, redisImage: REDIS_IMAGE });
 /** The development scripts of a lite app's declared Redis (create once, then start and stop it), as a scripts object. */
-export const redisDevScripts = project => JSON.parse(`{${redisDevText(project).trim().replace(/,$/, '')}}`);
-
+export const redisDevScripts = (project) => JSON.parse(`{${redisDevText(project).trim().replace(/,$/, '')}}`);
 /** What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions ({ sonarExclusions }); both editions install it (a lite back end keeps full's unit run, ruling:R212/case-1, amended by ruling:R212/case-4). */
 export async function loadPresets(root) {
-  const name = '@starci/jest-preset';
-  const require = createRequire(path.join(root, 'package.json'));
-  let resolved;
-  try {
-    resolved = require.resolve(name);
-  } catch {
-    throw new SyncError('HFS_SYNC_PRESET_MISSING', `${name} is not installed under ${root}; set it to the exact version in knowledge/hfs/canon-pins.yaml and reinstall`);
-  }
-  return { sonarExclusions: require(resolved).sonarExclusions() };
-}
-
+    const name = '@starci/jest-preset';
+    const require = createRequire(path.join(root, 'package.json'));
+    let resolved;
+    try {
+        resolved = require.resolve(name);
+    }
+    catch {
+        throw new SyncError('HFS_SYNC_PRESET_MISSING', `${name} is not installed under ${root}; set it to the exact version in knowledge/hfs/canon-pins.yaml and reinstall`);
+    }
+    return { sonarExclusions: require(resolved).sonarExclusions() };
+}
 /**
  * The jest preset's Sonar exclusions as @starci/hfs ships them: `@starci/jest-preset/sonar-exclusions.cjs` (a require-free module),
  * carried byte for byte in packages/hfs/runtime, so a fresh `starci app scaffold` (nothing installed
  * yet) and an upgrade render the same list the app's installed preset answers. A missing copy is a refusal, never a render without it.
  */
 const BUNDLED_SONAR_EXCLUSIONS = new URL('../runtime/packages/jest-preset/sonar-exclusions.cjs', import.meta.url);
-
 /** The presets ({ sonarExclusions }) of the jest preset version this @starci/hfs pins, read from its bundled copy. */
 export function bundledPresets() {
-  let list;
-  try {
-    list = createRequire(import.meta.url)(fileURLToPath(BUNDLED_SONAR_EXCLUSIONS));
-  } catch {
-    throw new SyncError('HFS_SYNC_PRESET_MISSING', '@starci/hfs ships no runtime/packages/jest-preset/sonar-exclusions.cjs; reinstall @starci/hfs at its published version');
-  }
-  return { sonarExclusions: list.join(',') };
-}
-
+    let list;
+    try {
+        list = createRequire(import.meta.url)(fileURLToPath(BUNDLED_SONAR_EXCLUSIONS));
+    }
+    catch {
+        throw new SyncError('HFS_SYNC_PRESET_MISSING', '@starci/hfs ships no runtime/packages/jest-preset/sonar-exclusions.cjs; reinstall @starci/hfs at its published version');
+    }
+    return { sonarExclusions: list.join(',') };
+}
 /** Where the be unit run writes the lcov report (jest `coverageDirectory` coverage under be/, reporter lcov), from the app root. */
 const LCOV_REPORT = 'be/coverage/lcov.info';
 /** The design truths this package ships: the one list of the exceptions the canon allows, each with its owner ruling. */
 const DESIGN_TRUTHS = path.join(import.meta.dirname, '..', 'runtime', 'knowledge', 'hfs', 'design-truths.yaml');
 /** Every entry the design truths allow on `list`, in manifest order. */
-const designTruthEntries = list => [...new Set(readTruths(bundledParseYaml(fs.readFileSync(DESIGN_TRUTHS, 'utf8'))).literal.filter(allow => allow.list === list).flatMap(allow => allow.entries))];
+const designTruthEntries = (list) => [...new Set(readTruths(bundledParseYaml(fs.readFileSync(DESIGN_TRUTHS, 'utf8'))).literal.filter((allow) => allow.list === list).flatMap((allow) => allow.entries))];
 /**
  * The entries Sonar's copy-paste detection leaves out: every `cpd-exclusions` entry the design truths
  * (knowledge/hfs/design-truths.yaml) allow, today the message catalogs (ruling message-catalogs-not-duplicate-code): a catalog
@@ -231,7 +224,6 @@ const designTruthEntries = list => [...new Set(readTruths(bundledParseYaml(fs.re
  * accepts the block only as this manifest derives it.
  */
 export const SONAR_CPD_EXCLUSIONS = Object.freeze(designTruthEntries(LIST.cpd));
-
 /**
  * The Sonar scope of the jest preset's exclusions (presets.sonarExclusions): its file patterns are the tests, which
  * `sonar.test.inclusions` takes and `sonar.exclusions` moves out of the sources (`sonar.tests` names every source folder, so the
@@ -239,14 +231,12 @@ export const SONAR_CPD_EXCLUSIONS = Object.freeze(designTruthEntries(LIST.cpd));
  * build and dependency folders are no source at all. Nothing else is excluded: a generated file is analysed like any other.
  */
 export function sonarScope(presets) {
-  const preset = String(presets?.sonarExclusions ?? '').split(',').map(glob => glob.trim()).filter(Boolean);
-  const tests = preset.filter(glob => !glob.endsWith('/**'));
-  return { tests, exclusions: [...new Set([...preset, '**/.next/**', '**/node_modules/**'])] };
+    const preset = String(presets?.sonarExclusions ?? '').split(',').map(glob => glob.trim()).filter(Boolean);
+    const tests = preset.filter(glob => !glob.endsWith('/**'));
+    return { tests, exclusions: [...new Set([...preset, '**/.next/**', '**/node_modules/**'])] };
 }
-
 const SOURCE_FILE = /\.[cm]?ts$/;
 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. `workPresent` records whether the optional
@@ -254,40 +244,48 @@ const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
  * their content. An app with no be folder has no source files.
  */
 export function appSource(root, { parseYaml, notices } = {}) {
-  const files = [];
-  const walk = dir => {
-    let entries;
-    try { entries = fs.readdirSync(path.join(root, 'be', dir), { withFileTypes: true }); } catch { return; }
-    for (const entry of entries) {
-      const rel = `${dir}/${entry.name}`;
-      if (entry.isDirectory()) { if (!SOURCE_SKIPPED.has(entry.name)) walk(rel); } else if (SOURCE_FILE.test(entry.name)) files.push(rel);
-    }
-  };
-  for (const dir of ['apps', 'src']) walk(dir);
-  return { runtimeExample: isRuntimeExampleApp(root), 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 }),
-    stack: readDeclaredStack(root, { parseYaml }), quality: readDeclaredQuality(root, { parseYaml }),
-    badges: readDeclaredBadges(root, { parseYaml, notices }),
-    qualityDeclared: hasDeclaredServices(root, { parseYaml }) };
-}
-
+    const files = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(root, 'be', dir), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const rel = `${dir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (!SOURCE_SKIPPED.has(entry.name))
+                    walk(rel);
+            }
+            else if (SOURCE_FILE.test(entry.name))
+                files.push(rel);
+        }
+    };
+    for (const dir of ['apps', 'src'])
+        walk(dir);
+    return { runtimeExample: isRuntimeExampleApp(root), 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 }),
+        stack: readDeclaredStack(root, { parseYaml }), quality: readDeclaredQuality(root, { parseYaml }),
+        badges: readDeclaredBadges(root, { parseYaml, notices }),
+        qualityDeclared: hasDeclaredServices(root, { parseYaml }) };
+}
 /**
  * The Codecov `individual_components` entries of components [{ id, name, paths }]: one `component_id` block each, `prefix` ahead of every path
  * (the app folder in the runtime repository) and `ids` mapping a component id to its name there.
  */
-export function componentsYaml(components, { prefix = '', ids = id => id } = {}) {
-  return components.map(component => [`    - component_id: ${ids(component.id)}`, `      name: ${ids(component.name)}`, '      paths:', ...component.paths.map(glob => `        - ${JSON.stringify(prefix + glob)}`)].join('\n')).join('\n');
+export function componentsYaml(components, { prefix = '', ids = (id) => id } = {}) {
+    return components.map(component => [`    - component_id: ${ids(component.id)}`, `      name: ${ids(component.name)}`, '      paths:', ...component.paths.map(glob => `        - ${JSON.stringify(prefix + glob)}`)].join('\n')).join('\n');
 }
-
 /** The managed be/jest.config.js option text of a coverage scope { roots, roles, files, excludes }, laid out exactly as prettier lays it out (width 120, indent 4). */
 export function jestCoverageSource(coverage) {
-  const list = (key, items) => {
-    const one = `        ${key}: [${items.map(item => JSON.stringify(item)).join(', ')}],`;
-    return one.length <= 120 ? one : [`        ${key}: [`, ...items.map(item => `            ${JSON.stringify(item)},`), '        ],'].join('\n');
-  };
-  return ['{', list('roots', coverage.roots), list('roles', coverage.roles), list('files', coverage.files), list('excludes', coverage.excludes), '    }'].join('\n');
+    const list = (key, items) => {
+        const one = `        ${key}: [${items.map(item => JSON.stringify(item)).join(', ')}],`;
+        return one.length <= 120 ? one : [`        ${key}: [`, ...items.map(item => `            ${JSON.stringify(item)},`), '        ],'].join('\n');
+    };
+    return ['{', list('roots', coverage.roots), list('roles', coverage.roles), list('files', coverage.files), list('excludes', coverage.excludes), '    }'].join('\n');
 }
-
 /**
  * The script lines the apps add to the root package.json, each ending with a comma (the template puts them mid-object). A be
  * script runs from be/ (`cd be && ...`, the folder its tsconfig and jest configuration are relative to) or runs the built app; an
@@ -300,369 +298,392 @@ export function jestCoverageSource(coverage) {
  * `docker:build` builds every image, one after the other, never pushing.
  */
 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;
-  const apis = be.filter(entry => entry.kind === 'api');
-  const connections = app.sides.be.connections ?? [];
-  const watch = entry => `cd be && ts-node-dev --respawn -r tsconfig-paths/register apps/${entry.name}/src/main.ts`;
-  const built = entry => `node be/dist/apps/${entry.name}/src/main.js`;
-  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 database types check.
-  const dev = entry => `npm run codegen --silent && turbo run dev --filter=${workspace(entry)}`;
-  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)))),
-    ...(fe.length === 1 ? [line('dev:fe', dev(fe[0]))] : fe.map(entry => line(`dev:fe:${entry.name}`, dev(entry)))),
-    ...be.flatMap(entry => {
-      if (entry.kind !== 'cli') return [line(`start:${entry.name}`, built(entry))];
-      return [line('cli', built(entry)), ...(connections.length ? [line('migrate', `${built(entry)} ${MIGRATE_COMMAND}`)] : [])];
-    }),
-    ...fe.map(entry => line(`start:${entry.name}`, `npm run start -w ${workspace(entry)}`)),
-    ...(app.edition !== 'lite' && app.optionalSlots.includes('app.browser') ? [line('test:browser', 'playwright test -c browser/playwright.config.ts')] : []),
-    line('docker:build', images.map(image => `npm run docker:build:${image.entry.name}`).join(' && ')),
-    ...images.map(image => line(`docker:build:${image.entry.name}`, imageCommand(image))),
-  ].join('\n    ');
-}
-
+    const line = (name, command) => `${JSON.stringify(name)}: ${JSON.stringify(command)},`;
+    const be = app.sides.be.apps;
+    const fe = app.sides.fe.apps;
+    const apis = be.filter(entry => entry.kind === 'api');
+    const connections = app.sides.be.connections ?? [];
+    const watch = (entry) => `cd be && ts-node-dev --respawn -r tsconfig-paths/register apps/${entry.name}/src/main.ts`;
+    const built = (entry) => `node be/dist/apps/${entry.name}/src/main.js`;
+    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 database types check.
+    const dev = (entry) => `npm run codegen --silent && turbo run dev --filter=${workspace(entry)}`;
+    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)))),
+        ...(fe.length === 1 ? [line('dev:fe', dev(fe[0]))] : fe.map(entry => line(`dev:fe:${entry.name}`, dev(entry)))),
+        ...be.flatMap(entry => {
+            if (entry.kind !== 'cli')
+                return [line(`start:${entry.name}`, built(entry))];
+            return [line('cli', built(entry)), ...(connections.length ? [line('migrate', `${built(entry)} ${MIGRATE_COMMAND}`)] : [])];
+        }),
+        ...fe.map(entry => line(`start:${entry.name}`, `npm run start -w ${workspace(entry)}`)),
+        ...(app.edition !== 'lite' && app.optionalSlots.includes('app.browser') ? [line('test:browser', 'playwright test -c browser/playwright.config.ts')] : []),
+        line('docker:build', images.map(image => `npm run docker:build:${image.entry.name}`).join(' && ')),
+        ...images.map(image => line(`docker:build:${image.entry.name}`, imageCommand(image))),
+    ].join('\n    ');
+}
 /** The cli command that migrates every connection (src/features/cli/migrate/subs/run.cli.ts). */
 const MIGRATE_COMMAND = 'migrate run';
-
 /** True when the fe side opts into a workspace package (repo.packages or any fe.package.* slot): the sources then include fe/packages/. */
-const opensPackages = side => (side.optionalSlots ?? []).some(id => id === 'repo.packages' || String(id).startsWith('fe.package.'));
-
+const opensPackages = (side) => (side.optionalSlots ?? []).some(id => id === 'repo.packages' || String(id).startsWith('fe.package.'));
 /** 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';
-
 /** 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 }))];
+    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 }))];
 }
-
 /**
  * The build matrix of the images workflow: one entry per declared app (be then fe, then a lite app's db image), each with the image name and its Dockerfile. The workflow
  * 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, source) {
-  const entry = (side, item) => `          - name: ${item.name}\n            file: ${dockerfilePath(side, item.name)}`;
-  const db = app.edition === 'lite' ? [`          - name: ${DB_IMAGE_APP}\n            file: ${DB_DOCKERFILE}`] : [];
-  return [...imageEntries(app, source).map(image => entry(image.side, image.entry)), ...db].join('\n');
+    const entry = (side, item) => `          - name: ${item.name}\n            file: ${dockerfilePath(side, item.name)}`;
+    const db = app.edition === 'lite' ? [`          - name: ${DB_IMAGE_APP}\n            file: ${DB_DOCKERFILE}`] : [];
+    return [...imageEntries(app, source).map(image => entry(image.side, image.entry)), ...db].join('\n');
 }
-
 /** The Dockerfile of the app a deploy image names (be first, then fe, then a lite app's db image); an app hfs.json does not declare cannot be built by the managed workflow. */
 function stackDockerfile(app, name) {
-  if (app.edition === 'lite' && name === DB_IMAGE_APP) return DB_DOCKERFILE;
-  const side = ['be', 'fe'].find(which => app.sides[which].apps.some(entry => entry.name === name));
-  if (!side) throw new SyncError('HFS_SYNC_STACK_IMAGE', `deploy.images names the app ${name}, which hfs.json does not declare under be or fe`);
-  return dockerfilePath(side, name);
+    if (app.edition === 'lite' && name === DB_IMAGE_APP)
+        return DB_DOCKERFILE;
+    const side = ['be', 'fe'].find(which => app.sides[which].apps.some(entry => entry.name === name));
+    if (!side)
+        throw new SyncError('HFS_SYNC_STACK_IMAGE', `deploy.images names the app ${name}, which hfs.json does not declare under be or fe`);
+    return dockerfilePath(side, name);
 }
-
 const IMAGE_TEMPLATE = Object.freeze({ api: 'be/image/api', worker: 'be/image/worker', cli: 'be/image/cli', next: 'fe/image/next' });
-
 /**
  * The Dockerfile of every declared app, [{ path, content }] (app-relative): written once by starci app scaffold from templates/<side>/image/<kind>
  * 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, 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 database types of a lite back end, db/types/) 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, 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 };
-    return { path: dockerfilePath(which, item.name), content: render(readBundled(`${template}/Dockerfile`), vars) };
-  });
-}
-
+    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 database types of a lite back end, db/types/) 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, 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 };
+        return { path: dockerfilePath(which, item.name), content: render(readBundled(`${template}/Dockerfile`), vars) };
+    });
+}
 /** Every value a template of `scope` can name, derived from hfs.json and the presets. */
 export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest(), source = { files: [], read: () => '' }) {
-  const stack = source.stack ?? { images: [], passEnv: [] };
-  const fe = app.sides.fe;
-  const packages = opensPackages(fe);
-  const lite = app.edition === 'lite';
-  const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
-  const quality = source.quality ?? qualityServices({});
-  const grammarLint = scope === 'fe' ? grammarLintFor(fe.grammar) : null;
-  return {
-    header: HEADER(scope),
-    readmeBadges: source.badges ?? '',
-    project: app.project,
-    appBinary: APP_BINARY,
-    appScripts: appScripts(app, source),
-    // A lite app's own database runs in development as one container of the image its .starcistacks/images/db/Dockerfile builds (ruling:lite-db-image-in-stacks).
-    dbImage: dbLocalImage(app.project),
-    dbBaseImage: DB_BASE_IMAGE,
-    pgvectorPackage: PGVECTOR_PACKAGE,
-    pgmqVersion: PGMQ.version,
-    pgmqSource: PGMQ.source,
-    pgmqSha256: PGMQ.sha256,
-    // A lite app's declared Redis (sides.be.backing, ruling:R212/case-10) runs in development as one container of its pinned image.
-    backingScripts: lite && (app.sides.be.backing ?? []).includes('redis') ? redisDevText(app.project) : '',
-    // 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).
-    typecheck: 'npm run codegen --silent && tsc -p be/tsconfig.json && turbo run typecheck',
-    // The typed lint reads the types the fe packages declare (their dist, turbo.json: lint dependsOn ^build), so the packages are built first.
-    lintPrefix: packages ? 'npm run codegen --silent && turbo run build --filter=./fe/packages/* && ' : 'npm run codegen --silent && ',
-    nodeMajor: String(NODE_MAJOR),
-    // The deploy server's age identity the restore workflow writes (stack/server-key.mjs owns the path).
-    serverAgeIdentity: SERVER_AGE_IDENTITY,
-    sonarKey: sonarKey ?? app.project,
-    sonarHostLine: sonarHostLine(quality.sonar),
-    sonarExclusions: sonarScope(presets).exclusions.join(','),
-    sonarTestInclusions: sonarScope(presets).tests.join(','),
-    sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
-    lcovReport: LCOV_REPORT,
-    cpdExclusions: SONAR_CPD_EXCLUSIONS.join(','),
-    ...ciWorkflowCommands(source, LCOV_REPORT, source.qualityDeclared === false ? undefined : source.quality, { app }),
-    // The coverage scope is the same in both editions: lite measures exactly what full measures (ruling:R212/case-1, amended by ruling:R212/case-4).
-    jestCoverage: scope === 'be' ? jestCoverageSource(jestCoverage(manifest, providers)) : '',
-    coverageExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).join(',') : '',
-    codecovExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).map(glob => `  - ${JSON.stringify(glob)}`).join('\n') : '',
-    codecovPaths: scope === APP_SCOPE ? codecovPaths(manifest, providers).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
-    codecovComponents: scope === APP_SCOPE ? componentsYaml(coverageComponents(manifest, { ...source, apps: app.sides.be.apps, providers })) : '',
-    codecovTarget: quality.codecov.target,
-    dependabotUpdates: dependabotUpdates(quality.dependabot),
-    tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
-    styleGlob: STYLE_GLOB,
-    grammarLintImport: grammarLint?.package ? `import { ${grammarLint.factory} } from "${grammarLint.package}"` : '',
-    grammarLintExport: grammarLint?.package ? `export default [...starciFeConfig({ hfs }), ...${grammarLint.factory}({ hfs })]` : 'export default starciFeConfig({ hfs })',
-    imageMatrix: imageMatrix(app, source),
-    imageProject: app.project,
-    ...stackWorkflowVariables(stack, app.project, name => stackDockerfile(app, name)),
-  };
-}
-
+    const stack = source.stack ?? { images: [], passEnv: [] };
+    const fe = app.sides.fe;
+    const packages = opensPackages(fe);
+    const lite = app.edition === 'lite';
+    const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
+    const quality = source.quality ?? qualityServices({});
+    const grammarLint = scope === 'fe' ? grammarLintFor(fe.grammar) : null;
+    return {
+        header: HEADER(scope),
+        readmeBadges: source.badges ?? '',
+        project: app.project,
+        appBinary: APP_BINARY,
+        appScripts: appScripts(app, source),
+        // A lite app's own database runs in development as one container of the image its .starcistacks/images/db/Dockerfile builds (ruling:lite-db-image-in-stacks).
+        dbImage: dbLocalImage(app.project),
+        dbBaseImage: DB_BASE_IMAGE,
+        pgvectorPackage: PGVECTOR_PACKAGE,
+        pgmqVersion: PGMQ.version,
+        pgmqSource: PGMQ.source,
+        pgmqSha256: PGMQ.sha256,
+        // A lite app's declared Redis (sides.be.backing, ruling:R212/case-10) runs in development as one container of its pinned image.
+        backingScripts: lite && (app.sides.be.backing ?? []).includes('redis') ? redisDevText(app.project) : '',
+        // 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).
+        typecheck: 'npm run codegen --silent && tsc -p be/tsconfig.json && turbo run typecheck',
+        // The typed lint reads the types the fe packages declare (their dist, turbo.json: lint dependsOn ^build), so the packages are built first.
+        lintPrefix: packages ? 'npm run codegen --silent && turbo run build --filter=./fe/packages/* && ' : 'npm run codegen --silent && ',
+        nodeMajor: String(NODE_MAJOR),
+        // The deploy server's age identity the restore workflow writes (stack/server-key.mjs owns the path).
+        serverAgeIdentity: SERVER_AGE_IDENTITY,
+        sonarKey: sonarKey ?? app.project,
+        sonarHostLine: sonarHostLine(quality.sonar),
+        sonarExclusions: sonarScope(presets).exclusions.join(','),
+        sonarTestInclusions: sonarScope(presets).tests.join(','),
+        sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
+        lcovReport: LCOV_REPORT,
+        cpdExclusions: SONAR_CPD_EXCLUSIONS.join(','),
+        ...ciWorkflowCommands(source, LCOV_REPORT, source.qualityDeclared === false ? undefined : source.quality, { app }),
+        // The coverage scope is the same in both editions: lite measures exactly what full measures (ruling:R212/case-1, amended by ruling:R212/case-4).
+        jestCoverage: scope === 'be' ? jestCoverageSource(jestCoverage(manifest, providers)) : '',
+        coverageExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).join(',') : '',
+        codecovExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).map(glob => `  - ${JSON.stringify(glob)}`).join('\n') : '',
+        codecovPaths: scope === APP_SCOPE ? codecovPaths(manifest, providers).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
+        codecovComponents: scope === APP_SCOPE ? componentsYaml(coverageComponents(manifest, { ...source, apps: app.sides.be.apps, providers })) : '',
+        codecovTarget: quality.codecov.target,
+        dependabotUpdates: dependabotUpdates(quality.dependabot),
+        tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
+        styleGlob: STYLE_GLOB,
+        grammarLintImport: grammarLint?.package ? `import { ${grammarLint.factory} } from "${grammarLint.package}"` : '',
+        grammarLintExport: grammarLint?.package ? `export default [...starciFeConfig({ hfs }), ...${grammarLint.factory}({ hfs })]` : 'export default starciFeConfig({ hfs })',
+        imageMatrix: imageMatrix(app, source),
+        imageProject: app.project,
+        ...stackWorkflowVariables(stack, app.project, (name) => stackDockerfile(app, name)),
+    };
+}
 // The scripts of a package.json as one comparable text: a line per script, sorted by name (order is not drift).
-const scriptsText = scripts => Object.keys(scripts).sort(byCodeUnit)
-  .map(name => `${name}: ${typeof scripts[name] === 'string' ? scripts[name] : JSON.stringify(scripts[name])}`).join('\n') + '\n';
-
+const scriptsText = (scripts) => Object.keys(scripts).sort(byCodeUnit)
+    .map(name => `${name}: ${typeof scripts[name] === 'string' ? scripts[name] : JSON.stringify(scripts[name])}`).join('\n') + '\n';
 function parseScripts(text) {
-  try {
-    const { scripts } = JSON.parse(text);
-    return scripts && typeof scripts === 'object' && !Array.isArray(scripts) ? scripts : null;
-  } catch {
-    return null;
-  }
+    try {
+        const { scripts } = JSON.parse(text);
+        return scripts && typeof scripts === 'object' && !Array.isArray(scripts) ? scripts : null;
+    }
+    catch {
+        return null;
+    }
 }
-
 /**
  * The managed content of every target of the app: [{ path, mode, content, hash, scope }], paths app-relative (a side's targets under
  * its folder); a scripts target also carries `scripts`, the parsed block. `sonarKey` is the key the be side's stack declaration
  * names; without one the key is the project.
  */
 export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundled, manifest = loadSlotManifest(), source } = {}) {
-  const app = validateHfs(hfs, manifest);
-  const hasTemplate = name => { try { return readTemplate(name) !== undefined; } catch { return false; } };
-  return SCOPES.flatMap(scope => {
-    const vars = variables(app, scope, presets, sonarKey, manifest, source);
-    const repo = scope === APP_SCOPE ? app : app.sides[scope];
-    const declaredTargets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate, enabled: slot => declaredSlotEnabled(slot, repo) });
-    if (scope === APP_SCOPE && source?.badges) declaredTargets.push({ path: 'README.md', mode: 'block', markdown: true, template: 'app/readme-badges/README.md' });
-    const targets = declaredTargets
-      .filter(target => !(app.edition === 'lite' && source?.workPresent === false && target.path === '.starciwork/.gitignore'));
-    return targets.map(target => {
-      const template = target.path === 'codecov.yml' && source?.quality?.codecov.enabled === false
-        ? '{{header}}\n# Codecov is disabled in the manifest.\ncodecov:\n  require_ci_to_pass: false\n'
-        : readTemplate(target.template);
-      const body = trailingNewline(render(template, vars, readTemplate));
-      const where = onSide(scope, target.path);
-      if (target.mode === 'scripts') {
-        const scripts = parseScripts(body);
-        if (!scripts) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `the rendered ${target.template} has no scripts object`);
-        const content = scriptsText(scripts);
-        return { path: where, scope, mode: 'scripts', content, hash: hashOf(content), scripts };
-      }
-      const markers = target.markdown ? { begin: '<!-- >>> starci app sync (managed block; do not edit) >>> -->', end: '<!-- <<< starci app sync <<< -->' } : { begin: BLOCK_BEGIN, end: BLOCK_END };
-      const spacing = target.markdown ? '\n' : '';
-      const managed = target.mode === 'block' ? `${markers.begin}\n${spacing}${trailingNewline(body)}${spacing}${markers.end}\n` : body;
-      return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed) };
+    const app = validateHfs(hfs, manifest);
+    const hasTemplate = (name) => { try {
+        return readTemplate(name) !== undefined;
+    }
+    catch {
+        return false;
+    } };
+    return SCOPES.flatMap(scope => {
+        const vars = variables(app, scope, presets, sonarKey, manifest, source);
+        const repo = scope === APP_SCOPE ? app : app.sides[scope];
+        const declaredTargets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate, enabled: slot => declaredSlotEnabled(slot, repo) });
+        if (scope === APP_SCOPE && source?.badges)
+            declaredTargets.push({ path: 'README.md', mode: 'block', markdown: true, template: 'app/readme-badges/README.md' });
+        const targets = declaredTargets
+            .filter(target => !(app.edition === 'lite' && source?.workPresent === false && target.path === '.starciwork/.gitignore'));
+        return targets.map((target) => {
+            const template = target.path === 'codecov.yml' && source?.quality?.codecov.enabled === false
+                ? '{{header}}\n# Codecov is disabled in the manifest.\ncodecov:\n  require_ci_to_pass: false\n'
+                : readTemplate(target.template);
+            const body = trailingNewline(render(template, vars, readTemplate));
+            const where = onSide(scope, target.path);
+            if (target.mode === 'scripts') {
+                const scripts = parseScripts(body);
+                if (!scripts)
+                    throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `the rendered ${target.template} has no scripts object`);
+                const content = scriptsText(scripts);
+                return { path: where, scope, mode: 'scripts', content, hash: hashOf(content), scripts };
+            }
+            const markers = target.markdown ? { begin: '<!-- >>> starci app sync (managed block; do not edit) >>> -->', end: '<!-- <<< starci app sync <<< -->' } : { begin: BLOCK_BEGIN, end: BLOCK_END };
+            const spacing = target.markdown ? '\n' : '';
+            const managed = target.mode === 'block' ? `${markers.begin}\n${spacing}${trailingNewline(body)}${spacing}${markers.end}\n` : body;
+            return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed) };
+        });
     });
-  });
 }
-
 // The part of a file sync manages: all of it, all of it but the verb's section, the marked block, or the scripts block as text.
 function managedPart(mode, text, markers = { begin: BLOCK_BEGIN, end: BLOCK_END }) {
-  if (mode === 'file') return text;
-  if (mode === 'section') return bootstrapSection(text).head;
-  if (mode === 'scripts') {
-    const scripts = parseScripts(text);
-    return scripts ? scriptsText(scripts) : null;
-  }
-  const start = text.indexOf(markers.begin);
-  const end = text.indexOf(markers.end);
-  if (start < 0 || end < start) return null;
-  const stop = text.indexOf('\n', end);
-  return text.slice(start, stop < 0 ? text.length : stop + 1);
-}
-
+    if (mode === 'file')
+        return text;
+    if (mode === 'section')
+        return bootstrapSection(text).head;
+    if (mode === 'scripts') {
+        const scripts = parseScripts(text);
+        return scripts ? scriptsText(scripts) : null;
+    }
+    const start = text.indexOf(markers.begin);
+    const end = text.indexOf(markers.end);
+    if (start < 0 || end < start)
+        return null;
+    const stop = text.indexOf('\n', end);
+    return text.slice(start, stop < 0 ? text.length : stop + 1);
+}
 function firstDifference(expected, actual) {
-  const want = expected.split('\n'), have = actual.split('\n');
-  for (let index = 0; index < Math.max(want.length, have.length); index += 1) {
-    if (want[index] !== have[index]) return { line: index + 1, expected: want[index] ?? '(end of file)', actual: have[index] ?? '(end of file)' };
-  }
-  return null;
+    const want = expected.split('\n'), have = actual.split('\n');
+    for (let index = 0; index < Math.max(want.length, have.length); index += 1) {
+        if (want[index] !== have[index])
+            return { line: index + 1, expected: want[index] ?? '(end of file)', actual: have[index] ?? '(end of file)' };
+    }
+    return null;
 }
-
 /** Compare every rendered target with the disk: [{ path, status: ok | missing | drift, expectedHash, actualHash?, difference? }]. */
 export function checkTargets(root, targets) {
-  return targets.map(target => {
-    const file = path.join(root, target.path);
-    if (!fs.existsSync(file)) return { path: target.path, status: 'missing', expectedHash: target.hash };
-    const part = managedPart(target.mode, lf(fs.readFileSync(file, 'utf8')), target.markers);
-    if (part === null) return { path: target.path, status: 'missing', expectedHash: target.hash };
-    const actualHash = hashOf(part);
-    if (actualHash === target.hash) return { path: target.path, status: 'ok', expectedHash: target.hash, actualHash };
-    return { path: target.path, status: 'drift', expectedHash: target.hash, actualHash, difference: firstDifference(target.content, part) };
-  });
-}
-
+    return targets.map((target) => {
+        const file = path.join(root, target.path);
+        if (!fs.existsSync(file))
+            return { path: target.path, status: 'missing', expectedHash: target.hash };
+        const part = managedPart(target.mode, lf(fs.readFileSync(file, 'utf8')), target.markers);
+        if (part === null)
+            return { path: target.path, status: 'missing', expectedHash: target.hash };
+        const actualHash = hashOf(part);
+        if (actualHash === target.hash)
+            return { path: target.path, status: 'ok', expectedHash: target.hash, actualHash };
+        return { path: target.path, status: 'drift', expectedHash: target.hash, actualHash, difference: firstDifference(target.content, part) };
+    });
+}
 function insertAfterTitle(existing, content) {
-  const title = /^# [^\n]*(?:\n|$)/m.exec(existing);
-  if (!title) return `${content}\n${existing}`;
-  const end = title.index + title[0].length;
-  const heading = trailingNewline(existing.slice(0, end));
-  return `${heading}\n${content}${existing.slice(end)}`;
+    const title = /^# [^\n]*(?:\n|$)/m.exec(existing);
+    if (!title)
+        return `${content}\n${existing}`;
+    const end = title.index + title[0].length;
+    const heading = trailingNewline(existing.slice(0, end));
+    return `${heading}\n${content}${existing.slice(end)}`;
 }
-
 /** Apply exactly one target to its whole file while preserving content outside the managed block or scripts. */
 export function writtenContent(target, existing) {
-  if (target.mode === 'scripts') {
-    let pkg = {};
-    if (existing) {
-      try { pkg = JSON.parse(existing); } catch { throw new SyncError('HFS_SYNC_HFS_INVALID', `${target.path} is not valid JSON; fix it by hand before sync can set its scripts`); }
+    if (target.mode === 'scripts') {
+        let pkg = {};
+        if (existing) {
+            try {
+                pkg = JSON.parse(existing);
+            }
+            catch {
+                throw new SyncError('HFS_SYNC_HFS_INVALID', `${target.path} is not valid JSON; fix it by hand before sync can set its scripts`);
+            }
+        }
+        return `${JSON.stringify({ ...pkg, scripts: target.scripts }, null, 2)}\n`;
     }
-    return `${JSON.stringify({ ...pkg, scripts: target.scripts }, null, 2)}\n`;
-  }
-  if (target.mode === 'section') return `${target.content}${bootstrapSection(existing ?? '').section ?? ''}`;
-  if (target.mode === 'block' && existing) {
-    const current = managedPart('block', existing, target.markers);
-    if (current !== null) return existing.replace(current, () => target.content);
-    if (target.markdown) return insertAfterTitle(existing, target.content);
-    return `${target.content}\n${existing}`;
-  }
-  return target.content;
-}
-
+    if (target.mode === 'section')
+        return `${target.content}${bootstrapSection(existing ?? '').section ?? ''}`;
+    if (target.mode === 'block' && existing) {
+        const current = managedPart('block', existing, target.markers);
+        if (current !== null)
+            return existing.replace(current, () => target.content);
+        if (target.markdown)
+            return insertAfterTitle(existing, target.content);
+        return `${target.content}\n${existing}`;
+    }
+    return target.content;
+}
 export function writeTargets(root, targets) {
-  const written = [];
-  for (const result of checkTargets(root, targets)) {
-    if (result.status === 'ok') continue;
-    const target = targets.find(candidate => candidate.path === result.path);
-    const file = path.join(root, target.path);
-    const existing = fs.existsSync(file) ? lf(fs.readFileSync(file, 'utf8')) : '';
-    const next = writtenContent(target, existing);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, next);
-    written.push(target.path);
-  }
-  return written;
-}
-
+    const written = [];
+    for (const result of checkTargets(root, targets)) {
+        if (result.status === 'ok')
+            continue;
+        const target = targets.find(candidate => candidate.path === result.path);
+        const file = path.join(root, target.path);
+        const existing = fs.existsSync(file) ? lf(fs.readFileSync(file, 'utf8')) : '';
+        const next = writtenContent(target, existing);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, next);
+        written.push(target.path);
+    }
+    return written;
+}
 /** The hfs.json object of the app at `root` (validated), or a SyncError. */
 export function loadHfs(root, manifest = loadSlotManifest()) {
-  const file = path.join(root, 'hfs.json');
-  if (!fs.existsSync(file)) throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} does not exist; starci app sync runs at the app root`);
-  let hfs;
-  try {
-    hfs = JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch (error) {
-    throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} is not valid JSON: ${error.message}`);
-  }
-  validateHfs(hfs, manifest);
-  return hfs;
-}
-
+    const file = path.join(root, 'hfs.json');
+    if (!fs.existsSync(file))
+        throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} does not exist; starci app sync runs at the app root`);
+    let hfs;
+    try {
+        hfs = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} is not valid JSON: ${error.message}`);
+    }
+    validateHfs(hfs, manifest);
+    return hfs;
+}
 /** The rendered targets of the app at `root`: its hfs.json, the Sonar key the be side's stack declaration names, the presets it installs. */
 export async function renderRepo(root, { presets, parseYaml, notices, manifest = loadSlotManifest() } = {}) {
-  const hfs = loadHfs(root, manifest);
-  const sonarKey = await readDeclaredSonarKey(root, { parseYaml, fail: message => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
-  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: appSource(root, { parseYaml, notices }) }) };
+    const hfs = loadHfs(root, manifest);
+    const sonarKey = await readDeclaredSonarKey(root, { parseYaml, fail: (message) => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
+    return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: appSource(root, { parseYaml, notices }) }) };
 }
-
 /** The folders a lite app's sync retires (ruling lite-self-hosted-postgres-passport-minio): the generated Supabase row types nothing reads any more. */
 const LITE_RETIRED_DIRS = Object.freeze(['supabase/types']);
-/** The files a lite app's sync retires, each with the reason --check prints. */
+/** The files a lite app's sync retires, each with the reason the dry run prints. */
 const LITE_RETIRED_FILES = Object.freeze({
-  [RETIRED_DB_DOCKERFILE]: `the db image moved to ${DB_DOCKERFILE} (ruling lite-db-image-in-stacks)`,
+    [RETIRED_DB_DOCKERFILE]: `the db image moved to ${DB_DOCKERFILE} (ruling lite-db-image-in-stacks)`,
 });
 /** Why a retired file goes: a retired file's own reason, else the folder's. */
 const retiredReason = (file) => LITE_RETIRED_FILES[file] ?? 'the lite edition generates no database types';
-
-/** The app-relative files of the retired folders that still exist under `root` of a lite app; sync --write deletes them, --check reports them. */
+/** The app-relative files of the retired folders that still exist under `root` of a lite app; sync --execute deletes them, the dry run reports them. */
 export function retiredFiles(root, hfs) {
-  if (hfs?.edition !== 'lite') return [];
-  const found = [];
-  const walk = (rel) => {
-    const full = path.join(root, rel);
-    const stat = fs.lstatSync(full, { throwIfNoEntry: false });
-    if (!stat) return;
-    if (stat.isDirectory()) for (const name of fs.readdirSync(full).sort(byCodeUnit)) walk(`${rel}/${name}`);
-    else found.push(rel);
-  };
-  for (const dir of LITE_RETIRED_DIRS) walk(dir);
-  for (const file of Object.keys(LITE_RETIRED_FILES)) walk(file);
-  return found;
-}
-
-/** `starci app sync --check | --write [--cwd <dir>]` at the app root; returns 0 clean, 1 drift, 2 usage. */
+    if (hfs?.edition !== 'lite')
+        return [];
+    const found = [];
+    const walk = (rel) => {
+        const full = path.join(root, rel);
+        const stat = fs.lstatSync(full, { throwIfNoEntry: false });
+        if (!stat)
+            return;
+        if (stat.isDirectory())
+            for (const name of fs.readdirSync(full).sort(byCodeUnit))
+                walk(`${rel}/${name}`);
+        else
+            found.push(rel);
+    };
+    for (const dir of LITE_RETIRED_DIRS)
+        walk(dir);
+    for (const file of Object.keys(LITE_RETIRED_FILES))
+        walk(file);
+    return found;
+}
+/** `starci app sync [--execute] [--cwd <dir>]` at the app root: the dry run reports drift, --execute writes; returns 0 clean, 1 drift, 2 usage. */
 function syncOptions(argv) {
-  const check = argv.includes('--check'), write = argv.includes('--write');
-  const cwdAt = argv.indexOf('--cwd');
-  const known = new Set(['--check', '--write', '--cwd']);
-  const unknown = argv.find((arg, index) => !known.has(arg) && index !== cwdAt + 1);
-  if ([check, write].filter(Boolean).length !== 1 || unknown !== undefined || (cwdAt >= 0 && argv[cwdAt + 1] === undefined)) {
-    return null;
-  }
-  return { write, cwdAt };
+    const write = argv.includes('--execute');
+    const cwdAt = argv.indexOf('--cwd');
+    const known = new Set(['--execute', '--cwd']);
+    const unknown = argv.find((arg, index) => !known.has(arg) && (cwdAt < 0 || index !== cwdAt + 1));
+    if (unknown !== undefined || (cwdAt >= 0 && argv[cwdAt + 1] === undefined) || argv.indexOf('--execute') !== argv.lastIndexOf('--execute')) {
+        return null;
+    }
+    return { write, cwdAt };
 }
-
 function reportSyncCheck(root, targets, out, retired = []) {
-  const results = checkTargets(root, targets);
-  const bad = results.filter(item => item.status !== 'ok');
-  for (const file of retired) out(`HFS_SYNC_DRIFT ${file}: retired, ${retiredReason(file)}; run "npx starci app sync --write" to delete it`);
-  for (const result of bad) {
-    const found = result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : '';
-    const where = result.difference ? ` (line ${result.difference.line}: expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)})` : '';
-    out(`HFS_SYNC_DRIFT ${result.path}: ${result.status}, expected sha256 ${result.expectedHash.slice(0, 12)}${found}${where}`);
-  }
-  out(`starci app sync --check: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx starci app sync --write"' : ''}`);
-  return bad.length || retired.length ? 1 : 0;
-}
-
-export async function runSync(argv, { cwd = process.cwd(), out = line => process.stdout.write(`${line}\n`), presets, parseYaml } = {}) {
-  const options = syncOptions(argv);
-  if (!options) {
-    out('usage: starci app sync (--check | --write) [--cwd <dir>]');
-    return 2;
-  }
-  const { write, cwdAt } = options;
-  const root = cwdAt >= 0 ? path.resolve(cwd, argv[cwdAt + 1]) : cwd;
-  try {
-    const notices = [];
-    const { hfs, targets } = await renderRepo(root, { presets, parseYaml, notices });
-    const retired = retiredFiles(root, hfs);
-    if (targets.some(target => target.path === 'README.md')) for (const notice of new Set(notices)) out(notice);
-    if (write) {
-      const written = writeTargets(root, targets);
-      for (const file of written) out(`wrote ${file}`);
-      for (const file of retired) { fs.rmSync(path.join(root, file)); out(`removed ${file} (retired)`); }
-      for (const dir of LITE_RETIRED_DIRS) if (retired.length && fs.existsSync(path.join(root, dir)) && !fs.readdirSync(path.join(root, dir)).length) fs.rmdirSync(path.join(root, dir));
-      out(`starci app sync: ${written.length} written, ${targets.length - written.length} already in sync`);
-      return 0;
+    const results = checkTargets(root, targets);
+    const bad = results.filter(item => item.status !== 'ok');
+    for (const file of retired)
+        out(`HFS_SYNC_DRIFT ${file}: retired, ${retiredReason(file)}; run "npx --no-install starci app sync --execute" to delete it`);
+    for (const result of bad) {
+        const found = result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : '';
+        const where = result.difference ? ` (line ${result.difference.line}: expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)})` : '';
+        out(`HFS_SYNC_DRIFT ${result.path}: ${result.status}, expected sha256 ${result.expectedHash.slice(0, 12)}${found}${where}`);
+    }
+    out(`starci app sync: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx --no-install starci app sync --execute"' : ''}`);
+    return bad.length || retired.length ? 1 : 0;
+}
+export async function runSync(argv, { cwd = process.cwd(), out = (line) => process.stdout.write(`${line}\n`), presets, parseYaml } = {}) {
+    const options = syncOptions(argv);
+    if (!options) {
+        out('usage: starci app sync [--execute] [--cwd <dir>]');
+        return 2;
+    }
+    const { write, cwdAt } = options;
+    const root = cwdAt >= 0 ? path.resolve(cwd, argv[cwdAt + 1]) : cwd;
+    try {
+        const notices = [];
+        const { hfs, targets } = await renderRepo(root, { presets, parseYaml, notices });
+        const retired = retiredFiles(root, hfs);
+        if (targets.some(target => target.path === 'README.md'))
+            for (const notice of new Set(notices))
+                out(notice);
+        if (write) {
+            const written = writeTargets(root, targets);
+            for (const file of written)
+                out(`wrote ${file}`);
+            for (const file of retired) {
+                fs.rmSync(path.join(root, file));
+                out(`removed ${file} (retired)`);
+            }
+            for (const dir of LITE_RETIRED_DIRS)
+                if (retired.length && fs.existsSync(path.join(root, dir)) && !fs.readdirSync(path.join(root, dir)).length)
+                    fs.rmdirSync(path.join(root, dir));
+            out(`starci app sync: ${written.length} written, ${targets.length - written.length} already in sync`);
+            return 0;
+        }
+        return reportSyncCheck(root, targets, out, retired);
+    }
+    catch (error) {
+        if (!(error instanceof SyncError))
+            throw error;
+        out(error.message);
+        return 1;
     }
-    return reportSyncCheck(root, targets, out, retired);
-  } catch (error) {
-    if (!(error instanceof SyncError)) throw error;
-    out(error.message);
-    return 1;
-  }
 }