@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/lib/sops-envelope.mjs

@@ -25,7 +25,12 @@ export function testSecretPaths(name, { repo, stack = 'dev' } = {}) {
 export const setCommand = (name = '<name>', stack = 'dev') => `node scripts/stack-secret.mjs set ${stack}/secrets/test/${name}`;
 
 /** sops' format for a plaintext path, as the repository's stack-secret.mjs formatFor decides it. */
-export const sopsFormatFor = (file) => (file.endsWith('.env') ? 'dotenv' : /\.json$/.test(file) ? 'json' : /\.(ya?ml|kubeconfig)$/.test(file) ? 'yaml' : 'binary');
+export const sopsFormatFor = (file) => {
+  if (file.endsWith('.env')) return 'dotenv';
+  if (file.endsWith('.json')) return 'json';
+  if (/\.(ya?ml|kubeconfig)$/.test(file)) return 'yaml';
+  return 'binary';
+};
 
 /** Every leaf outside the `sops` block is an ENC[...] value (or null); the block itself carries a mac. */
 const allEncrypted = (node) => {
@@ -48,7 +53,7 @@ export function isSopsEnvelope(text) {
   if (!src.trim()) return false;
   try { return sopsTree(JSON.parse(src)); } catch { /* not JSON */ }
   const lines = src.split(/\r?\n/).filter((l) => l.trim() && !/^\s*#/.test(l));
-  if (lines.length && lines.every((l) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(l))) {
+  if (lines.length && lines.every((l) => /^[A-Za-z_]\w*=/.test(l))) {
     const pairs = lines.map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]);
     const meta = pairs.filter(([k]) => k.startsWith('sops_'));
     const vals = pairs.filter(([k]) => !k.startsWith('sops_'));
@@ -56,3 +61,99 @@ export function isSopsEnvelope(text) {
   }
   try { return sopsTree(parseYaml(src)); } catch { return false; }
 }
+
+/** Admit one flat age envelope for the native selected-identity invocation; this is shape admission, never cryptographic proof. */
+const refusal = (reason) => ({ ok: false, reason });
+
+function dotenvMetadataValue(meta, age, key, value) {
+  if (key === 'age__list_0__map_recipient') age.recipient = value;
+  else if (key === 'age__list_0__map_enc') age.enc = value;
+  else if (key === 'mac_only_encrypted') {
+    if (value !== 'false') return 'partial-mac';
+    meta[key] = false;
+  } else if (key.includes('__')) return 'unsupported-key-group';
+  else meta[key] = value;
+  return null;
+}
+
+function readDotenvMetadata(text) {
+  const pairs = new Map();
+  for (const line of String(text).split('\n')) {
+    if (!line || line.startsWith('#')) continue;
+    if (line.includes('\r')) return { refusal: 'unsupported-dotenv' };
+    const at = line.indexOf('=');
+    if (at < 1) return { refusal: 'unsupported-dotenv' };
+    const name = line.slice(0, at);
+    if (pairs.has(name)) return { refusal: 'duplicate-key' };
+    pairs.set(name, line.slice(at + 1).replaceAll(String.raw`\n`, '\n'));
+  }
+  const meta = {};
+  const age = {};
+  for (const [name, value] of pairs) {
+    if (!name.startsWith('sops_')) continue;
+    const reason = dotenvMetadataValue(meta, age, name.slice('sops_'.length), value);
+    if (reason) return { refusal: reason };
+  }
+  meta.age = [age];
+  return { meta };
+}
+
+function readStructuredMetadata(text, format) {
+  const doc = parseYaml(String(text));
+  if (format !== 'yaml') JSON.parse(String(text));
+  if (format === 'binary' && (!doc || Object.keys(doc).length !== 2 || !Object.hasOwn(doc, 'data') || !Object.hasOwn(doc, 'sops') || typeof doc.data !== 'string'))
+    return { refusal: 'unsupported-binary-shape' };
+  return { meta: doc?.sops };
+}
+
+function readAgeMetadata(text, format) {
+  try {
+    return format === 'dotenv' ? readDotenvMetadata(text) : readStructuredMetadata(text, format);
+  } catch { return { refusal: 'invalid-envelope' }; }
+}
+
+function hasNonAgeProvider(meta, providers) {
+  for (const name of providers) {
+    if (Object.hasOwn(meta, name) && (!Array.isArray(meta[name]) || meta[name].length)) return true;
+  }
+  return false;
+}
+
+function isAgeEntry(entry) {
+  return !!entry && typeof entry === 'object' && !Array.isArray(entry)
+    && !Object.keys(entry).some(name => !['recipient', 'enc'].includes(name));
+}
+
+function hasValidAgePayload(entry) {
+  return typeof entry.enc === 'string' && entry.enc.startsWith('-----BEGIN AGE ENCRYPTED FILE-----\n')
+    && entry.enc.includes('\n-----END AGE ENCRYPTED FILE-----');
+}
+
+function hasValidEnvelopeVersion(meta) {
+  return typeof meta.version === 'string' && /^\d+\.\d+\.\d+$/.test(meta.version)
+    && typeof meta.lastmodified === 'string' && Number.isFinite(Date.parse(meta.lastmodified));
+}
+
+function validateAgeMetadata(meta, text, recipient) {
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta) || !isSopsEnvelope(text)) return refusal('invalid-envelope');
+  if (Object.hasOwn(meta, 'key_groups') || Object.hasOwn(meta, 'shamir_threshold')) return refusal('unsupported-key-group');
+  const providers = ['kms', 'gcp_kms', 'hckms', 'azure_kv', 'hc_vault', 'pgp'];
+  if (hasNonAgeProvider(meta, providers)) return refusal('non-age-provider');
+  const fields = new Set([...providers, 'age', 'lastmodified', 'mac', 'version', 'unencrypted_suffix', 'encrypted_suffix', 'unencrypted_regex', 'encrypted_regex', 'unencrypted_comment_regex', 'encrypted_comment_regex', 'mac_only_encrypted']);
+  if (Object.keys(meta).some(name => !fields.has(name))) return refusal('unknown-metadata');
+  if (Object.hasOwn(meta, 'mac_only_encrypted') && meta.mac_only_encrypted !== false) return refusal('partial-mac');
+  if (!Array.isArray(meta.age) || meta.age.length !== 1) return refusal('unsupported-age-set');
+  const entry = meta.age[0];
+  if (!isAgeEntry(entry)) return refusal('invalid-age-entry');
+  if (typeof entry.recipient !== 'string' || entry.recipient !== recipient) return refusal('recipient-mismatch');
+  if (!hasValidAgePayload(entry)) return refusal('invalid-age-entry');
+  if (!hasValidEnvelopeVersion(meta)) return refusal('invalid-envelope');
+  return { ok: true };
+}
+
+export function selectedAgeEnvelope(text, format, recipient) {
+  if (!['binary', 'json', 'yaml', 'dotenv'].includes(format)) return refusal('unsupported-format');
+  const parsed = readAgeMetadata(text, format);
+  if (parsed.refusal) return refusal(parsed.refusal);
+  return validateAgeMetadata(parsed.meta, text, recipient);
+}

package/runtime/scripts/lib/stack-services.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { words } from './dockerfile.mjs';
+import { asList } from './list.mjs';
 
 /**
  * The services of a repository's own stack definition, read from `.starcistacks/application-stacks.yaml` and the compose
@@ -74,8 +75,6 @@ const imagePathOf = image => {
 /** True when the image reference carries a tag or digest (an external image, not a placeholder of the repository's own build). */
 const isTagged = image => image.includes('@') || image.slice(image.lastIndexOf('/') + 1).includes(':');
 
-const asList = value => (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value]);
-
 /** A compose `environment` (map or `KEY=VALUE` list) as a plain object; a `*_FILE` variable becomes the plain variable with the test value. */
 const environmentOf = value => {
   const entries = Array.isArray(value)

package/runtime/scripts/lib/ts-ast.mjs

@@ -2,6 +2,15 @@
 // literal text, a node's 1-based position, a named property's initializer text. `ts` is the caller's
 // already-resolved compiler (see package-at.mjs loadTypescript); nothing here resolves a package.
 
+/** Whether the single-bit `flag` (a ts.NodeFlags member) is set in `flags`: the bit read as arithmetic, no bitwise operator in the condition. */
+export const hasFlag = (flags, flag) => Math.floor(flags / flag) % 2 === 1;
+
+/** Whether any bit of `mask` (a ts flag or an OR of flags) is set in `flags` (absent flags read as none): an explicit comparison of the masked value. */
+export const hasAnyFlag = (flags, mask) => ((flags ?? 0) & mask) !== 0;
+
+/** Whether the variable `declaration` belongs to a `const` list: the TypeScript node-flag test, an explicit comparison of the masked flags. */
+export const isConstVariable = (ts, declaration) => (ts.getCombinedNodeFlags(declaration.parent) & ts.NodeFlags.Const) !== 0;
+
 /** The text of an identifier or a string-literal-like `node`, or null (property names, literal specifiers). */
 export const nameText = (ts, node) => (node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null);
 

package/runtime/scripts/lib/walk.mjs

@@ -20,7 +20,12 @@ export function walkFiles(dir, {filter = () => true, sorted = false, exclude = (
     if (depth > maxDepth) return;
     let entries;
     try { entries = fs.readdirSync(current, {withFileTypes: true}); }
-    catch (error) { if (ignoreReadErrors) return; throw error; }
+    catch (error) {
+      if (ignoreReadErrors) {
+        return;
+      }
+      throw error;
+    }
     if (sorted) entries = entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
       const full = path.join(current, entry.name);

package/scaffold/add-cli-lite.mjs

@@ -6,6 +6,7 @@ import { appScripts, imageFiles, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError } from "./service.mjs";
 import { jsonText, packageJsonText } from "./app.mjs";
 import { registerLiteExports } from "./lite-exports.mjs";
+import { byCodeUnit } from "../report/order.mjs";
 
 const read = (relative) =>
   fs
@@ -204,7 +205,7 @@ export function ensureLiteCli({ root, manifest, repo }) {
   declaration.sides.be.apps.push({ name: "cli", kind: "cli" });
   declaration.sides.be.kinds = [
     ...new Set([...(declaration.sides.be.kinds ?? []), "cli"]),
-  ].sort();
+  ].sort(byCodeUnit);
   const resolved = resolveRepoDeclaration(manifest, declaration);
   const image = imageFiles(resolved).find(
     (file) => file.path === "be/apps/cli/Dockerfile",

package/scaffold/add-table.mjs

@@ -316,7 +316,7 @@ export function addTable({
       fs.writeFileSync(target, file.body);
       created.push(target);
     }
-    if (emitTypes !== false) {
+    if (typeof emitTypes === "function") {
       const generated = emitTypes({ root });
       if (typeof generated === "string") {
         const target = path.join(root, ...dbTypesPath.split("/"));
@@ -339,6 +339,6 @@ export function addTable({
   }
   return {
     created: planned.map((file) => file.relative),
-    types: emitTypes === false ? "skipped" : dbTypesPath,
+    types: typeof emitTypes === "function" ? dbTypesPath : "skipped",
   };
 }

package/scaffold/add.mjs

@@ -26,6 +26,7 @@ import { addApp } from './add-app.mjs';
 import { ensureLiteCli, selectLiteCliEntries } from './add-cli-lite.mjs';
 import { addLiteWebhookInbox, selectLiteWebhookEntries } from './add-inbox-lite.mjs';
 import { jsonText } from './app.mjs';
+import { byCodeUnit } from '../report/order.mjs';
 import { registerLiteDomainService, registerLiteExports } from './lite-exports.mjs';
 
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -290,8 +291,8 @@ function topicsOfPatterns(patterns) {
 function register({ declarationFile, spec }) {
   const declaration = JSON.parse(fs.readFileSync(declarationFile, 'utf8'));
   const be = declaration.sides.be;
-  const patterns = [...new Set([...(be.patterns ?? []), ...spec.patterns])].sort();
-  const kinds = [...new Set([...(be.kinds ?? []), ...(spec.trigger ? [spec.trigger] : [])])].sort();
+  const patterns = [...new Set([...(be.patterns ?? []), ...spec.patterns])].sort(byCodeUnit);
+  const kinds = [...new Set([...(be.kinds ?? []), ...(spec.trigger ? [spec.trigger] : [])])].sort(byCodeUnit);
   be.patterns = patterns;
   if (kinds.length) be.kinds = kinds;
   fs.writeFileSync(declarationFile, jsonText(declaration));

package/scaffold/app.mjs

@@ -25,6 +25,7 @@ import { unlinkOnly } from '../runtime/scripts/api/fs/lib.mjs';
 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';
 
 const NAME = /^[a-z][a-z0-9-]*$/;
 const APP_DIR = '__app__';
@@ -64,7 +65,7 @@ export const packageJsonText = value => `${JSON.stringify(value, null, 2)}\n`;
  * The apps a new app starts with: on the be side the `core` api app and the `cli` app over one `primary` connection, two Next apps
  * (landing, app) on the fe side, which read the be contracts for their codegen.
  */
-export const STARTER_SIDES = Object.freeze({
+const STARTER_SIDES = Object.freeze({
   be: Object.freeze({ apps: [{ name: 'core', kind: 'api' }, { name: 'cli', kind: 'cli' }], kinds: ['api', 'cli'], connections: [{ name: 'primary', envPrefix: 'PRIMARY_DB', owner: 'core', isolation: 'database' }] }),
   // fe: the landing and the product app, over the shared ui and i18n packages (both opt-in slots, enabled here).
   fe: Object.freeze({ apps: [{ name: 'landing', kind: 'next' }, { name: 'app', kind: 'next' }], reads: ['be/contracts/'], optionalSlots: ['fe.package.ui', 'fe.package.i18n'] }),
@@ -277,6 +278,7 @@ const liteBaseFile = (scope, rel) => {
     && rel !== 'src/modules/platform/database/connection-source.client.ts'
     && rel !== 'src/modules/platform/database/migrate-connections.client.ts'
     && rel !== 'src/modules/platform/database/seed-connections.client.ts'
+    && rel !== 'src/modules/platform/primitives/sequence.policy.ts'
     && !LITE_DEFERRED_GENERATOR_FILES.has(rel)
     && !rel.startsWith('src/tests/')
     && !rel.endsWith('.spec.ts');
@@ -486,7 +488,7 @@ export function scaffoldApp({ name, into, presets, edition = 'full', manifest =
     let locked;
     try { locked = lock(root); } finally { writes.lockfile(); }
     if (!locked.ok) throw new ScaffoldError('HFS_SCAFFOLD_LOCK_FAILED', `\`${LOCK_STEP}\` could not resolve the lockfile of ${root} (${locked.detail}). Check the network and the npm registry, then run starci app scaffold ${name} again`);
-    return { root, files: [...new Set([...files.map(file => file.path), ...targets.map(target => target.path), ...(app.edition === 'lite' ? [dbTypesPath] : []), 'package-lock.json'])].sort() };
+    return { root, files: [...new Set([...files.map(file => file.path), ...targets.map(target => target.path), ...(app.edition === 'lite' ? [dbTypesPath] : []), 'package-lock.json'])].sort(byCodeUnit) };
   } catch (error) {
     const held = writes.rollback();
     if (held.length) error.message += `; cleanup retained replaced or occupied entries: ${held.join(', ')}`;

package/scaffold/edition-gate.mjs

@@ -1,25 +1,25 @@
-// The edition gate of `starci app add` and `starci app new` (design 8.6 R8): a verb whose file tree lands in a slot the app's
-// edition does not have - the slot's `editions` exclude it, or its `litePresence` is forbidden - is a full-edition
-// capability and refuses before anything is planned or written. The slot resolver of the app answers, the same
-// view `starci app check` reads; the noun's name is never the test, so a slot the lite manifest forbids refuses every
-// verb that writes into it, with no noun list kept anywhere. The refusal carries no failure code by design: the
-// scaffolders of packages/hfs keep their codes out of the runtime catalog (like HFS_SCAFFOLD_LOCK_FAILED).
-
-/** The refusal of a verb a non-full edition does not carry: printed verbatim by the CLI, exit 2, nothing written. */
-export class EditionRefusal extends Error {
-  constructor(command) {
-    super(`${command}: full edition only; run starci app upgrade --edition full`);
-    this.name = 'EditionRefusal';
-  }
-}
-
-/**
- * Refuses `command` (`add <noun>`, `new <noun>`) when one of `slotIds` - the slots the verb writes into - does not
- * exist for the edition of `resolver`'s repository or is forbidden under it. `resolver` is the
- * createSlotResolver() view of the app; every scope answers a slot id. Under full every verb slot exists and none is
- * forbidden, so the gate never fires. A slot id the view does not answer (an `editions` exclusion, or an unknown id) refuses
- * in every edition alike: the view cannot tell them apart, and the callers name only slots of the manifest.
- */
-export function refuseInEdition({ resolver, slotIds, command }) {
-  if (slotIds.some((id) => resolver.slot(id) === null || resolver.slot(id).presence === 'forbidden')) throw new EditionRefusal(command);
-}
+// The edition gate of `starci app add` and `starci app new` (design 8.6 R8): a verb whose file tree lands in a slot the app's
+// edition does not have - the slot's `editions` exclude it, or its `litePresence` is forbidden - is a full-edition
+// capability and refuses before anything is planned or written. The slot resolver of the app answers, the same
+// view `starci app check` reads; the noun's name is never the test, so a slot the lite manifest forbids refuses every
+// verb that writes into it, with no noun list kept anywhere. The refusal carries no failure code by design: the
+// scaffolders of packages/hfs keep their codes out of the runtime catalog (like HFS_SCAFFOLD_LOCK_FAILED).
+
+/** The refusal of a verb a non-full edition does not carry: printed verbatim by the CLI, exit 2, nothing written. */
+export class EditionRefusal extends Error {
+  constructor(command) {
+    super(`${command}: full edition only; run starci app upgrade --edition full`);
+    this.name = 'EditionRefusal';
+  }
+}
+
+/**
+ * Refuses `command` (`add <noun>`, `new <noun>`) when one of `slotIds` - the slots the verb writes into - does not
+ * exist for the edition of `resolver`'s repository or is forbidden under it. `resolver` is the
+ * createSlotResolver() view of the app; every scope answers a slot id. Under full every verb slot exists and none is
+ * forbidden, so the gate never fires. A slot id the view does not answer (an `editions` exclusion, or an unknown id) refuses
+ * in every edition alike: the view cannot tell them apart, and the callers name only slots of the manifest.
+ */
+export function refuseInEdition({ resolver, slotIds, command }) {
+  if (slotIds.some((id) => resolver.slot(id) === null || resolver.slot(id).presence === 'forbidden')) throw new EditionRefusal(command);
+}

package/scaffold/lite-exports.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs"
 import path from "node:path"
 import { ScaffoldError } from "./service.mjs"
+import { byCodeUnit } from "../report/order.mjs"
 
 const REGISTRATIONS = Object.freeze({
   api: [
@@ -126,7 +127,7 @@ function addExport(text, registration) {
   const line = new RegExp(`^${kind} \\{ ([^}]*) \\} from "${escape(registration.source)}"$`, "m")
   const found = line.exec(text)
   if (found) {
-    const names = [...new Set([...found[1].split(",").map((name) => name.trim()), ...registration.names])].sort()
+    const names = [...new Set([...found[1].split(",").map((name) => name.trim()), ...registration.names])].sort(byCodeUnit)
     return text.replace(line, `${kind} { ${names.join(", ")} } from "${registration.source}"`)
   }
   const added = `${kind} { ${registration.names.join(", ")} } from "${registration.source}"`

package/scaffold/service.mjs

@@ -17,6 +17,7 @@ import { createRequire } from 'node:module';
 import { explainPath } from '../runtime/scripts/hfs/check.mjs';
 import { createSlotResolver, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 import { refuseInEdition } from './edition-gate.mjs';
+import { byCodeUnit } from '../report/order.mjs';
 
 export class ScaffoldError extends Error {
   constructor(code, message) {
@@ -182,8 +183,8 @@ function specSkeleton({ shape, serviceFile, manifest = loadSlotManifest() }) {
   if (kit.size) lines.push(importLine([...kit].sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' })), KIT));
   const modules = [...new Set([...imports.keys(), ...typeImports.keys()])].sort(compareModules);
   for (const module of modules) {
-    if (imports.has(module)) lines.push(importLine([...imports.get(module)].sort(), module));
-    if (typeImports.has(module)) lines.push(importLine([...typeImports.get(module)].sort(), module, true));
+    if (imports.has(module)) lines.push(importLine([...imports.get(module)].sort(byCodeUnit), module));
+    if (typeImports.has(module)) lines.push(importLine([...typeImports.get(module)].sort(byCodeUnit), module, true));
   }
   lines.push(`import { ${shape.className} } from "${subject}"`);
   lines.push('');
@@ -265,8 +266,8 @@ function serviceSource({ name, dependencies = [] }) {
   }
   const lines = [];
   for (const module of [...new Set([...values.keys(), ...types.keys()])].sort(compareModules)) {
-    if (values.has(module)) lines.push(importLine([...values.get(module)].sort(), module));
-    if (types.has(module)) lines.push(importLine([...types.get(module)].sort(), module, true));
+    if (values.has(module)) lines.push(importLine([...values.get(module)].sort(byCodeUnit), module));
+    if (types.has(module)) lines.push(importLine([...types.get(module)].sort(byCodeUnit), module, true));
   }
   lines.push('', '@Injectable()', `/** The ${words(name).join(' ')} service: state what it decides in one sentence. */`);
   if (dependencies.length === 0) lines.push(`export class ${className} {}`);

package/sync/hygiene.mjs

@@ -7,15 +7,22 @@
 // files; scripts/gates/hfs-sync.mjs judges every tracked file.
 //
 // Run inside a full runtime checkout — the repository under judgment is the checkout — it also reports the
-// state-root ledger findings of that checkout's scripts/housekeeping/hk-orphan-ledgers.mjs: LEDGER_ORPHAN_STATE_ROOT and
-// LEDGER_LEGACY_WORK_SQLITE (COOK-BRIEF F4 handover, incident 2026-09-30). Any other repository — a product repo,
+// state-root ledger finding of that checkout's scripts/housekeeping/hk-orphan-ledgers.mjs: LEDGER_ORPHAN_STATE_ROOT. Any other repository — a product repo,
 // a bare repo — carries no scripts/housekeeping/ledger-hygiene.mjs at its root, so that section is silently absent:
 // never a crash, never machine-state findings blamed on a repository that does not own them.
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { secretFileFindings } from '../runtime/scripts/hfs/rules/secrets.mjs';
+import { runGit } from '../runtime/scripts/api/git/lib.mjs';
+
+// One git call through the runtime's git owner (scripts/api/git/lib.mjs): stdout, or the failure thrown the way execFileSync threw it (error.status carries the exit code). The caller's own env is passed on unchanged: a hook runs with GIT_INDEX_FILE set, which the staged reads must keep seeing.
+const git = (cwd, args, options = {}) => {
+  const run = runGit(args, { cwd, env: process.env, ...options });
+  if (run.error) throw run.error;
+  if (run.status !== 0) throw Object.assign(new Error(`git ${args[0]} exited ${run.status}`), { status: run.status });
+  return run.stdout;
+};
 
 const PLAINTEXT_NAME = /(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|identity|age))$/;
 /** The app root's work tree and stack tree, app-relative (`starci app hygiene` runs at the app root). */
@@ -27,7 +34,7 @@ const GUARDED = file => file.startsWith(WORK) || file.startsWith(STACKS);
 function ignoredAmong(cwd, files) {
   if (files.length === 0) return new Set();
   try {
-    const out = execFileSync('git', ['check-ignore', '--no-index', '-z', '--stdin'], { cwd, input: files.join('\0'), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const out = git(cwd, ['check-ignore', '--no-index', '-z', '--stdin'], { input: files.join('\0'), maxBuffer: 64 * 1024 * 1024 });
     return new Set(out.split('\0').filter(Boolean));
   } catch (error) {
     if (error.status === 1) return new Set();
@@ -50,7 +57,7 @@ export function hygieneFindings(files, ignored) {
   return findings;
 }
 
-const gitList = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).split('\0').filter(Boolean);
+const gitList = (cwd, args) => git(cwd, args, { maxBuffer: 64 * 1024 * 1024 }).split('\0').filter(Boolean);
 
 /** Files staged for the next commit (added, copied, modified, renamed). */
 export const stagedFiles = cwd => gitList(cwd, ['diff', '--cached', '--name-only', '--diff-filter=ACMR', '-z']);
@@ -63,7 +70,7 @@ const MAX_STAGED_BYTES = 1024 * 1024;
 /** The text of `file` as the index holds it (what the commit would record), or null when it is absent, binary or over 1 MB. */
 function stagedText(cwd, file) {
   try {
-    const blob = execFileSync('git', ['show', `:${file}`], { cwd, maxBuffer: MAX_STAGED_BYTES * 2, stdio: ['ignore', 'pipe', 'ignore'] });
+    const blob = git(cwd, ['show', `:${file}`], { encoding: 'buffer', maxBuffer: MAX_STAGED_BYTES * 2 });
     return blob.length > MAX_STAGED_BYTES || blob.includes(0) ? null : blob.toString('utf8');
   } catch {
     return null;
@@ -89,7 +96,7 @@ export function judge(cwd, files) {
 // bare repo — has no such file, so the section is silently absent wherever this module happens to be installed.
 const ledgerHygieneScript = cwd => {
   try {
-    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' }).trim();
+    const root = git(cwd, ['rev-parse', '--show-toplevel']).trim();
     return path.join(root, 'scripts', 'housekeeping', 'ledger-hygiene.mjs');
   } catch {
     return null;
@@ -97,7 +104,7 @@ const ledgerHygieneScript = cwd => {
 };
 
 /**
- * The state-root ledger findings (LEDGER_ORPHAN_STATE_ROOT, LEDGER_LEGACY_WORK_SQLITE) of the checkout containing
+ * The state-root ledger findings (LEDGER_ORPHAN_STATE_ROOT) of the checkout containing
  * `cwd`, as {code, file, message} entries; [] when that checkout carries no ledger-hygiene script. Never throws: a
  * report failure is one HFS_LEDGER_HYGIENE_UNAVAILABLE finding, not a crash of `starci app hygiene`.
  */
@@ -109,7 +116,6 @@ async function ledgerHygieneFindings(cwd = process.cwd()) {
     const report = await ledgerHygieneReport({ apply: false });
     return [
       ...report.orphans.map(o => ({ code: o.code, file: o.ledgerId, message: `ledger ${o.name ?? o.ledgerId} - ${o.reason}; source roots: ${o.sourceRoots.join(', ') || '(none)'}` })),
-      ...report.legacy.map(l => ({ code: l.code, file: l.repoRoot, message: `${l.files.length} legacy file(s) still in the repo: ${l.files.join(', ')}` })),
     ];
   } catch (error) {
     return [{ code: 'HFS_LEDGER_HYGIENE_UNAVAILABLE', file: script, message: `could not run: ${String(error?.message ?? error).slice(0, 200)}` }];

package/sync/index.mjs

@@ -25,6 +25,7 @@ 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 { readDeclaredSonarKey } from './sonar-key.mjs';
+import { byCodeUnit } from '../report/order.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
@@ -149,7 +150,7 @@ export function appSource(root) {
     }
   };
   for (const dir of ['apps', 'src']) walk(dir);
-  return { files: files.sort(), 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') };
 }
 
 /**
@@ -241,10 +242,13 @@ export function imageFiles(app) {
   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 }));
   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 };
+    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) };
   });
 }
@@ -281,7 +285,7 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
 }
 
 // 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().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 {

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -24,12 +24,12 @@ jobs:
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: {{nodeMajor}}
           cache: npm
-      - run: npm ci
+      - run: npm ci --ignore-scripts
       - name: lint
         run: npm run lint -- --sonar reports/lint.sonar.json
       - name: format
@@ -39,7 +39,7 @@ jobs:
       - name: unit
         run: npm test -- --ci
       - name: coverage upload
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
         if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
         with:
           use_oidc: true

package/templates/app/ci-workflows/github/workflows/e2e.yml

@@ -12,11 +12,11 @@ jobs:
   e2e:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: {{nodeMajor}}
           cache: npm
-      - run: npm ci
+      - run: npm ci --ignore-scripts
       - name: e2e
         run: npm run test:e2e

package/templates/app/ci-workflows/github/workflows/images.yml

@@ -25,9 +25,9 @@ jobs:
         include:
 {{imageMatrix}}
     steps:
-      - uses: actions/checkout@v4
-      - uses: docker/setup-buildx-action@v3
-      - uses: docker/build-push-action@v6
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+      - uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           file: ${{ matrix.file }}

package/templates/app/ci-workflows/sonar-steps.yml

@@ -1,8 +1,8 @@
-      - uses: SonarSource/sonarqube-scan-action@v7
+      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1
         if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}
         env:
           SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
-      - uses: SonarSource/sonarqube-quality-gate-action@v1
+      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1
         if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}
         timeout-minutes: 10
         env:

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -20,12 +20,12 @@ jobs:
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: {{nodeMajor}}
           cache: npm
-      - run: npm ci
+      - run: npm ci --ignore-scripts
       - name: lint
         if: env.SONAR_TOKEN == ''
         run: npm run lint
@@ -47,12 +47,12 @@ jobs:
   db-types:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: {{nodeMajor}}
           cache: npm
-      - run: npm ci
+      - run: npm ci --ignore-scripts
       - name: start Supabase
         run: npm run db:start
       - name: apply migrations

package/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml

@@ -21,11 +21,11 @@ jobs:
       SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
       SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: {{nodeMajor}}
           cache: npm
-      - run: npm ci
+      - run: npm ci --ignore-scripts
       - name: push migrations
         run: npm run db:push

package/templates/app/ci-workflows-lite/github/workflows/images.yml

@@ -25,9 +25,9 @@ jobs:
         include:
 {{imageMatrix}}
     steps:
-      - uses: actions/checkout@v4
-      - uses: docker/setup-buildx-action@v3
-      - uses: docker/build-push-action@v6
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+      - uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           file: ${{ matrix.file }}

package/templates/app/starciwork.gitignore

@@ -1,4 +1,4 @@
-# StarCi .starciwork: product content only (ARCHITECTURE-DB §5.1, work-layout.yaml shape.productPaths).
+# StarCi .starciwork: product content only (work-layout.yaml shape.productPaths).
 # Agent output (reports, checks, captures, draw rounds, UAT runs, logs, ledgers, worktrees) lives in
 # runtime.sqlite rows and blobs outside the repository.
 /*

package/templates/be/image/api/Dockerfile

@@ -19,7 +19,7 @@ RUN npm ci --ignore-scripts
 
 COPY be/tsconfig.json be/tsconfig.build.json be/
 COPY be/src be/src
-COPY be/apps/{{app}} be/apps/{{app}}
+{{copyBeInputs}}COPY be/apps/{{app}} be/apps/{{app}}
 RUN npm run build:be
 
 FROM {{nodeImage}} AS runtime