@starci/hfs 4.3.0 → 4.4.1

package/runtime/scripts/lib/git.mjs

@@ -12,7 +12,7 @@ export const unquoteDiffPath = (value) =>
 
 // git's repository-local variables (git rev-parse --local-env-vars). A hook or alias run in a linked worktree exports
 // GIT_DIR=<main>/.git/worktrees/<wt>; a spec inheriting it pointed every fixture git at the LIVE .claude repo and re-inited
-// it core.bare=true (2026-09-29, a6f60352c). tests/setup/isolated-registry.mjs drops the same list.
+// it core.bare=true (2026-09-29, a6f60352c). e2e/setup/isolated-registry.mjs drops the same list.
 export const GIT_LOCAL_ENV_VARS = ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_IMPLICIT_WORK_TREE', 'GIT_PREFIX', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT', 'GIT_GRAFT_FILE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_SHALLOW_FILE', 'GIT_INTERNAL_SUPER_PREFIX'];
 /** `parent` (the caller's env) without git's repository-local variables (GIT_CONFIG_KEY_n/VALUE_n go with GIT_CONFIG_COUNT). Pure. */
 export function withoutGitLocalEnv(parent) {

package/runtime/scripts/lib/i18n.mjs

@@ -49,8 +49,6 @@ export function loadCatalog(root = skillRoot, { scope = 'runtime' } = {}) {
   return cache.get(key);
 }
 
-/** Forget the cached catalogs (a spec that rewrites a catalog file). */
-export const resetCatalogCache = () => cache.clear();
 
 /** The names each `pattern` match captures (group 1) in `text`, in match order (`sort` sorts them). */
 export const captureNames = (text, pattern, { sort = false } = {}) => {

package/runtime/scripts/lib/json-clone.mjs

@@ -0,0 +1,61 @@
+// json-clone.mjs — a deep copy that keeps exactly what survives a JSON text and nothing else: the plain-data
+// copy of a value, detached from every reference, frozen state and class of the original. `structuredClone` keeps
+// what JSON drops (undefined members, Dates, Maps, sparse holes) and refuses what JSON accepts (functions,
+// `toJSON` objects), so it is not a substitute; this walks the value once under the JSON.stringify rules.
+
+/** The boxed primitives JSON.stringify unwraps: recognised by the internal slot a valueOf call reads, as JSON does. */
+const BOXED = [
+  { slot: Number.prototype.valueOf, read: Number },
+  { slot: String.prototype.valueOf, read: String },
+  { slot: Boolean.prototype.valueOf, read: (box) => Boolean.prototype.valueOf.call(box) },
+  { slot: BigInt.prototype.valueOf, read: (box) => BigInt.prototype.valueOf.call(box) },
+];
+
+/** Whether `value` carries the internal slot `slot` reads (a valueOf of that boxed type does not throw on it). */
+const hasSlot = (slot, value) => {
+  try { slot.call(value); return true; } catch { return false; }
+};
+
+/** What JSON.stringify takes of `holder[key]`: the toJSON result when there is one, a boxed primitive unwrapped. */
+const serialized = (holder, key) => {
+  let value = holder[key];
+  if (value !== null && (typeof value === 'object' || typeof value === 'bigint') && typeof value.toJSON === 'function') value = value.toJSON(key);
+  if (value === null || typeof value !== 'object') return value;
+  const box = BOXED.find((candidate) => hasSlot(candidate.slot, value));
+  return box ? box.read(value) : value;
+};
+
+/** A member JSON leaves out of an object (and writes as null in an array). */
+const isAbsent = (value) => value === undefined || typeof value === 'function' || typeof value === 'symbol';
+
+const copyValue = (value, ancestors) => {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value + 0 : null;
+  if (typeof value === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
+  if (ancestors.includes(value)) throw new TypeError('Converting circular structure to JSON');
+  const inside = [...ancestors, value];
+  if (Array.isArray(value)) {
+    return Array.from({ length: value.length }, (_, index) => {
+      const item = serialized(value, String(index));
+      return isAbsent(item) ? null : copyValue(item, inside);
+    });
+  }
+  const entries = [];
+  for (const name of Object.keys(value)) {
+    const member = serialized(value, name);
+    if (!isAbsent(member)) entries.push([name, copyValue(member, inside)]);
+  }
+  return Object.fromEntries(entries);
+};
+
+/**
+ * `value` copied as JSON data: members that are undefined, functions or symbols are dropped (an array item becomes
+ * null), non-finite numbers become null and -0 becomes 0, `toJSON` results replace their objects (a Date becomes its ISO string), boxed
+ * primitives unwrap, and a cycle or a BigInt throws a TypeError. A value JSON has no text for (undefined, a function,
+ * a symbol) throws a SyntaxError, as parsing the missing text does.
+ */
+export function jsonClone(value) {
+  const top = serialized({ '': value }, '');
+  if (isAbsent(top)) throw new SyntaxError('"undefined" is not valid JSON');
+  return copyValue(top, []);
+}

package/runtime/scripts/lib/language.mjs

@@ -76,7 +76,7 @@ const I18N_CATALOG_DIR = 'modules/i18n/messages/';
 const OP_MANIFEST_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']) });
 const OP_MANIFEST_DIR = 'modules/ops/ops/';
 /** The declared Vietnamese fields of `rel`: its own entry, or the op-manifest text field for a manifest of modules/ops/ops. */
-export const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[rel]
+const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[rel]
   ?? (rel.startsWith(I18N_CATALOG_DIR) && !rel.slice(I18N_CATALOG_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? I18N_CATALOG_VIETNAMESE_FIELDS : null)
   ?? (rel.startsWith(OP_MANIFEST_DIR) && !rel.slice(OP_MANIFEST_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? OP_MANIFEST_VIETNAMESE_FIELDS : null);
 

package/runtime/scripts/lib/list.mjs

@@ -17,6 +17,10 @@ export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => it
 export const stringList = (v, { blank = true } = {}) =>
   Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
 
+/** A non-empty list of distinct values, all accepted by the supplied predicate. */
+export const nonemptyUniqueList = (values, accepts) => Array.isArray(values) && values.length > 0
+  && values.every((entry) => accepts(entry)) && new Set(values).size === values.length;
+
 /** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
 export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
   const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);

package/runtime/scripts/lib/roots.mjs

@@ -17,16 +17,14 @@
 // directory or from the Work directory name outside this module.
 import fs from 'node:fs';
 import path from 'node:path';
-import { skillRoot, runtimeStateDir, starciLocalRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
+import { skillRoot, starciLocalRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
 import { tempRoot } from '../../engine/temp-root.mjs';
 
 export { tempRoot, starciLocalRoot, starciSourceRoot };
 
 /** The runtime tree this code runs from. */
-export const runtimeTree = skillRoot;
+const runtimeTree = skillRoot;
 
-/** The state directory of a runtime tree (default: this one). */
-export const runtimeState = (tree = runtimeTree) => runtimeStateDir(tree);
 
 /** The name of the Work records directory inside a product tree. */
 export const WORK_DIR_NAME = '.starciwork';

package/runtime/scripts/lib/runtime-example.mjs

@@ -0,0 +1,13 @@
+// Identify runtime-owned example apps; an unrelated directory named examples grants no fixture behavior.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function isRuntimeExampleApp(repoRoot) {
+  if (path.basename(path.dirname(repoRoot)) !== 'examples') return false;
+  try {
+    const runtime = JSON.parse(fs.readFileSync(path.resolve(repoRoot, '..', '..', 'hfs.json'), 'utf8'));
+    return runtime.kind === 'runtime';
+  } catch {
+    return false;
+  }
+}

package/runtime/scripts/lib/secret-patterns.mjs

@@ -12,6 +12,57 @@ export const FORBIDDEN_FILES = [
   { name: 'starcistacks-secret-plaintext', test: (f) => /(^|\/)\.starcistacks\/[^/]+\/secrets\//i.test(f) && !/(\.enc|\/\.gitkeep|\/KEYS\.md)$/i.test(f) },
   { name: 'credentials-json', test: (f) => /(^|\/)(credentials|service-account|client_secret)[^/]*\.json$/i.test(f) },
 ];
+// `word` in any case (name checks are case-aware by construction, not by flag).
+const fold = (word) => word.replace(/[a-z]/gi, (c) => `[${c.toLowerCase()}${c.toUpperCase()}]`);
+
+// A name that holds secret material: the keyword is an identifier segment, so DB_PASSWORD, dbPassword,
+// OPENAI_API_KEY, api_secret and accessToken are candidates while `secondary`, `tokenize`, `monkey`, `secrets.x`
+// and `$secret` are not. A segment starts at the name edge, after `_`/`-`/`.`, or at a camel hump.
+const SECRET_WORD = [
+  'password', 'passwd', 'passphrase', 'secret', 'credentials?', 'token',
+  'api[_-]?key', 'access[_-]?token', 'auth[_-]?token', 'refresh[_-]?token', 'id[_-]?token', 'session[_-]?token',
+  'client[_-]?secret', 'api[_-]?secret', 'session[_-]?secret', 'jwt[_-]?secret',
+  'private[_-]?key', 'secret[_-]?key', 'signing[_-]?key', 'encryption[_-]?key', 'master[_-]?key',
+  'service[_-]?role[_-]?key', 'service[_-]?key', 'session[_-]?key',
+].map((word) => fold(word)).join('|');
+
+// A name whose last segment is configuration, not material: SECRET_FILE and *_PATH point at the materialized
+// secret file (the materializer's own form), PASSWORD_MIN_LENGTH is a number, *_REF/_ID a reference.
+const BENIGN_WORD = [
+  'file', 'path', 'dir', 'url', 'uri', 'endpoint', 'host', 'refs?', 'names?', 'ids?', 'arn', 'urn',
+  'length', 'min', 'max', 'size', 'count', 'budget', 'limit', 'regex', 'pattern', 'policy',
+  'algorithm', 'scheme', 'expiry', 'expires', 'ttl', 'required', 'enabled', 'disabled', 'type', 'version',
+].map((word) => fold(word)).join('|');
+
+const SEGMENT_BEFORE = String.raw`(?:(?<![A-Za-z0-9_$])|(?<=[_\-.])|(?<=[a-z])(?=[A-Z]))`;
+const NAME_REST = '[A-Za-z0-9_$.-]*?';
+const SECRET_NAME = [
+  '(?<![A-Za-z0-9_$])',
+  String.raw`(?!${NAME_REST}${SEGMENT_BEFORE}(?:${BENIGN_WORD})(?=\s*[:=]))`,
+  String.raw`(?=${NAME_REST}${SEGMENT_BEFORE}(?:${SECRET_WORD})(?=[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$))`,
+  String.raw`[A-Za-z_$][A-Za-z0-9_$.-]*\s*[:=]\s*`,
+].join('');
+
+// `password = "hunter2hunter2"` — the quoted literal. `env(NAME)` is a reference, never a secret.
+const ASSIGNED_QUOTED = new RegExp(
+  SECRET_NAME + String.raw`['"\`](?!env\([A-Z_][A-Z0-9_]*\)['"\`])([^'"\`\n\s$<{]{12,})['"\`]`,
+);
+// `DB_PASSWORD=hunter2hunter2` — the compose list-item and dotenv form; the dotenv value has no `:` so
+// `password: secret:db/password` and `token: ref:vault/api` stay references, and the end boundary keeps
+// calls and member/index references such as `secret = credentialsSource.current` out of the literals.
+const ASSIGNED_UNQUOTED = new RegExp(
+  SECRET_NAME + String.raw`(?!['"\`]|env\()([A-Za-z0-9_+=-]{12,})(?![A-Za-z0-9_+=.(\[-])`,
+);
+
+const NAME_WORD = (word, tail) => new RegExp(`^${NAME_REST}${SEGMENT_BEFORE}(?:${word})${tail}`);
+const SECRET_NAME_TEST = NAME_WORD(SECRET_WORD, String.raw`(?:[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$)`);
+const BENIGN_TAIL_TEST = NAME_WORD(BENIGN_WORD, '$');
+
+/** True when a bare variable `name` holds secret material as an identifier segment (DB_PASSWORD, dbPassword,
+ *  SUPABASE_SERVICE_ROLE_KEY) and does not end in a config suffix (PASSWORD_MIN_LENGTH, SECRET_FILE,
+ *  tokenBudget). The same name judgement the `assigned-secret` patterns make, for callers that read keys. */
+export const secretNameLike = (name) => SECRET_NAME_TEST.test(name) && !BENIGN_TAIL_TEST.test(name);
+
 export const SECRET_PATTERNS = [
   { name: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
   { name: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
@@ -23,17 +74,20 @@ export const SECRET_PATTERNS = [
   { name: 'telegram-bot-token', re: /\b\d{8,10}:AA[0-9A-Za-z_-]{33}\b/ },
   { name: 'stripe-secret', re: /\b(?:sk|rk)_live_[0-9A-Za-z]{20,}\b/ },
   { name: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+  { name: 'age-secret-key', re: /\bAGE-SECRET-KEY-1[0-9A-Z]{20,}\b/ },
+  { name: 'password-connection-string', re: /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis):\/\/[^:\s/@]+:[^@\s/${}]{8,}@/iu },
   // A value written `env(NAME)` (the Supabase config.toml reference form) names a variable, not a secret.
   // A keyword-assigned value that names itself a stand-in (a test stub's `accessToken: "fixture-..."`) is no
   // candidate; only this heuristic takes the exemption, never a provider-shaped token above.
   // A spec file's keyword-assigned values are test inputs (a spec's sign-in
   // form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
-  { name: 'assigned-secret', re: new RegExp([
-    String.raw`\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)`,
-    String.raw`\b\s*[:=]\s*['"](?!env\([A-Z_][A-Z0-9_]*\)['"])([^'"\s$<{]{12,})`,
-    `['"]`,
-  ].join(''), 'i'), placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  // A SCREAMING_SNAKE quoted value in source is a public code (an enum member whose value is an upper-case code), not a credential.
+  { name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
+  // An unquoted value in TypeScript or JavaScript source is an identifier or a type (`token: InjectionToken`,
+  // `MODULE_OPTIONS_TOKEN: DATABASE_OPTIONS_TOKEN`), never a literal; the unquoted form is the dotenv, compose and toml shape.
+  { name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+    skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$|\.[cm]?[jt]sx?$/ },
 ];
 
 
@@ -43,6 +97,7 @@ export function secretHits(file, text) {
   for (const rule of SECRET_PATTERNS) {
     if (rule.skipFile?.test(file ?? '')) continue;
     const hit = rule.re.exec(text);
+    if (hit && rule.sourceCode?.test(hit[1] ?? '') && /\.[cm]?[jt]sx?$/.test(file ?? '')) continue;
     if (hit && !rule.placeholder?.test(hit[1] ?? '')) names.push(rule.name);
   }
   return names;

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

@@ -0,0 +1,32 @@
+// PostgreSQL AST primitives shared by database verbs and synchronous content rules.
+
+/** String identifier components from libpg-query's wrapped String nodes. */
+export const sqlStringParts = (nodes) => (nodes ?? []).map((node) => node?.String?.sval).filter((value) => value !== undefined);
+
+/** Traverse SQL/PLpgSQL objects; executable scans leave function declarations inert. */
+export function walkSqlAst(value, visit, executable = false) {
+  if (!value || typeof value !== 'object' || (executable && value.CreateFunctionStmt)) return;
+  visit(value);
+  for (const child of Object.values(value)) walkSqlAst(child, visit, executable);
+}
+
+/** Build a synchronous parser with the caller's failure policy and initialized parser. */
+export function sqlParser(parser, reject = () => null) {
+  return (text) => {
+    try { return parser?.parseSync(text) ?? null; }
+    catch (error) { return reject(error); }
+  };
+}
+
+/** Resolve named arguments before positional arguments, as PostgreSQL does. */
+export function sqlCallArgument(call, position, names = []) {
+  const args = call.args ?? [];
+  return args.find((item) => names.includes(item?.NamedArgExpr?.name))?.NamedArgExpr?.arg
+    ?? args.filter((item) => !item.NamedArgExpr)[position];
+}
+
+/** Read a literal string through static casts without evaluating an expression. */
+export function sqlStringLiteral(node) {
+  if (node?.TypeCast) return sqlStringLiteral(node.TypeCast.arg);
+  return node?.A_Const?.sval?.sval ?? null;
+}

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

@@ -58,7 +58,7 @@ const KNOWN_IMAGES = Object.freeze({
 export const STATEFUL_KINDS = Object.freeze(new Set(['database', 'cache', 'identity', 'storage', 'mail', 'queue', 'search']));
 
 /** The repository name of an image reference: `quay.io/keycloak/keycloak:26.0` -> `keycloak`. */
-const repositoryOf = image => {
+export const repositoryOf = image => {
   const withoutDigest = image.split('@')[0];
   const lastSegment = withoutDigest.split('/').at(-1) ?? withoutDigest;
   return lastSegment.split(':')[0];

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

@@ -1,5 +1,7 @@
 // Shared static Swarm contract for app checks and rendered deployment evidence.
 import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { composeEntries } from './compose-values.mjs';
+import { repositoryOf } from './stack-services.mjs';
 
 const PINNED_IMAGE = /@sha256:[a-f0-9]{64}$/i;
 const VERSIONED_SECRET = /-v[1-9][0-9]*$/;
@@ -29,13 +31,6 @@ function runnableHealthcheck(value) {
   return value.slice(1).some(present);
 }
 
-/** Match image repository names, including registry and vendor namespaces, without matching application tags. */
-function duplicatesManagedBacking(image) {
-  if (!present(image)) return false;
-  const repository = image.split('@')[0].split('/').at(-1).split(':')[0];
-  return BACKING_IMAGE.test(repository);
-}
-
 function jobDeclarationIssues(id, component, components, add) {
   if (component.mode !== 'replicated-job') return;
   const scheduler = components[component.scheduler];
@@ -51,7 +46,7 @@ export function swarmInventoryIssues({ components, lite = false }) {
   const add = (at, message) => errors.push({ at, message });
   for (const [id, entry] of Object.entries(catalog)) {
     const component = mapping(entry);
-    if (lite && duplicatesManagedBacking(component.image))
+    if (lite && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)))
       add(`components.${id}.image`, 'lite must use managed Supabase backing services; this image duplicates a Supabase-provided service');
     jobDeclarationIssues(id, component, catalog, add);
   }
@@ -73,14 +68,6 @@ function serviceSafetyIssues(id, service, add) {
     add(`${at}.deploy.restart_policy`, 'every Swarm service needs deploy.restart_policy with a condition');
 }
 
-function labelsOf(value) {
-  if (!Array.isArray(value)) return mapping(value);
-  return Object.fromEntries(value.map(label => {
-    const text = String(label), separator = text.indexOf('=');
-    return separator < 0 ? [text, ''] : [text.slice(0, separator), text.slice(separator + 1)];
-  }));
-}
-
 function jobServiceIssues(id, service, component, services, bindings, add) {
   const deploy = mapping(service.deploy), at = `services.${id}.deploy`;
   if (component.mode !== 'replicated-job') {
@@ -90,7 +77,7 @@ function jobServiceIssues(id, service, component, services, bindings, add) {
   if (deploy.mode !== 'replicated-job') add(`${at}.mode`, 'replicated-job component must use deploy.mode: replicated-job');
   if (deploy.replicas !== 0) add(`${at}.replicas`, 'scheduled replicated-job must keep deploy.replicas: 0 until its scheduler triggers it');
   if (deploy.restart_policy?.condition !== 'none') add(`${at}.restart_policy.condition`, 'scheduled replicated-job must use restart_policy.condition: none');
-  const labels = labelsOf(deploy.labels);
+  const labels = Object.fromEntries(composeEntries(deploy.labels));
   if (String(labels['swarm.cronjob.enable']) !== 'true') add(`${at}.labels`, 'scheduled replicated-job needs swarm.cronjob.enable: "true"');
   if (!present(component.schedule) || labels['swarm.cronjob.schedule'] !== component.schedule)
     add(`${at}.labels`, 'swarm.cronjob.schedule must match the component cron schedule');
@@ -127,7 +114,7 @@ export function swarmModelIssues({ model, components, bindings, lite = false })
       add(`services.${id}.ports`, 'Swarm ports must be an array of published port definitions');
     else if (service.ports?.length && component.role !== 'ingress')
       add(`services.${id}.ports`, 'only a component with role ingress may publish Swarm ports');
-    if (lite && duplicatesManagedBacking(service.image))
+    if (lite && present(service.image) && BACKING_IMAGE.test(repositoryOf(service.image)))
       add(`services.${id}.image`, 'lite stack must not run an image that duplicates a Supabase-provided backing service');
     jobServiceIssues(id, service, component, services, bound, add);
   }

package/runtime/scripts/lib/trim-end.mjs

@@ -0,0 +1,8 @@
+// trim-end.mjs — a string without the run of characters at its end that `matches` accepts.
+
+/** `value` with its trailing characters removed while `matches(char)` holds. */
+export const trimEndWhile = (value, matches) => {
+  let end = value.length;
+  while (end > 0 && matches(value[end - 1])) end -= 1;
+  return value.slice(0, end);
+};

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

@@ -1,7 +1,7 @@
 /** The expression under the wrappers selected by an AST check's contract. */
-export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, satisfiesExpressions = true } = {}) {
+export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, nonNullExpressions = true, satisfiesExpressions = true } = {}) {
   while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
-    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || ts.isNonNullExpression(expression)
+    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || (nonNullExpressions && ts.isNonNullExpression(expression))
     || (satisfiesExpressions && (ts.isSatisfiesExpression?.(expression) ?? false))
     || (awaitExpressions && ts.isAwaitExpression(expression)))) expression = expression.expression;
   return expression;
@@ -18,3 +18,6 @@ export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiterals
   }
   return imports;
 }
+
+/** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
+export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });

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

@@ -11,8 +11,18 @@ 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);
+/** Text of a string-literal-like node or an enabled identifier/numeric name; null for other expressions. */
+export function nameText(ts, node, { identifiers = true, numbers = false } = {}) {
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node) || (identifiers && ts.isIdentifier(node)) || (numbers && ts.isNumericLiteral(node))) return node.text;
+  return null;
+}
+
+/** A statically selected property name, including string-literal element access; null for computed selections. */
+export function accessName(ts, node) {
+  if (ts.isPropertyAccessExpression(node)) return node.name.text;
+  return ts.isElementAccessExpression(node) ? literalText(ts, node.argumentExpression) : null;
+}
 
 /** The text of a string-literal-like `node` (a string literal or a no-substitution template), or null. */
 export const literalText = (ts, node) => (node && ts.isStringLiteralLike(node) ? node.text : null);
@@ -42,3 +52,18 @@ export function propertyText(ts, text, { file = 'source.ts', key, declaration =
   visit(source);
   return value;
 }
+
+/** Initializers of every identifier-named variable, grouped in traversal order across the source's scopes. */
+export function variableInitializerGroups(ts, source) {
+  const groups = new Map();
+  const collect = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      const initializers = groups.get(node.name.text) ?? [];
+      initializers.push(node.initializer);
+      groups.set(node.name.text, initializers);
+    }
+    ts.forEachChild(node, collect);
+  };
+  collect(source);
+  return groups;
+}

package/runtime/scripts/lib/workflow-events.mjs

@@ -0,0 +1,8 @@
+// GitHub workflow `on` supports a scalar event, an event list or an options map.
+
+/** Convert shorthand workflow events into an options map; mappings retain their values. */
+export function workflowEventOptions(on, eventName = (event) => event) {
+  if (typeof on === 'string') return { [on]: null };
+  if (Array.isArray(on)) return Object.fromEntries(on.map((event) => [eventName(event), null]));
+  return on;
+}

package/scaffold/add-app.mjs

@@ -7,7 +7,7 @@ import {
 } from "../runtime/scripts/hfs/slots.mjs";
 import { imageFiles, render, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError, pascalOf } from "./service.mjs";
-import { PARTIAL_VARIABLES, coreFeApps, jsonText, packageJsonText } from "./app.mjs";
+import { PARTIAL_VARIABLES, bundledPins, callbackSourceFiles, coreFeApps, hasAuthCallback, jsonText, packageJsonText } from "./app.mjs";
 
 /** The shared fe app core (modules/api, auth, toast, redux, the providers, the hooks): the base tree, then the edition overlay. */
 const CORE_DIRS = Object.freeze({
@@ -35,37 +35,8 @@ const fill = (text, values, file) =>
     return values[key];
   });
 
-/**
- * Adds one Next workspace from the edition's canonical app skeleton and the shared app core (both editions, owner ruling
- * 2026-10-13: lite and full have one fe structure), then registers it in hfs.json. The root workspace glob is added only when an
- * older app manifest does not already carry it.
- */
-export function addApp({ root, name }) {
-  if (!NAME.test(String(name)))
-    throw new ScaffoldError(
-      "HFS_ADD_NAME_INVALID",
-      `app name ${name} must be kebab-case (letters, digits and single dashes)`,
-    );
-  const declarationFile = path.join(root, "hfs.json");
-  const packageFile = path.join(root, "package.json");
-  if (!fs.existsSync(declarationFile) || !fs.existsSync(packageFile))
-    throw new ScaffoldError(
-      "HFS_ADD_NOT_AN_APP",
-      "add app runs at the app root containing hfs.json and package.json",
-    );
-  const manifest = loadSlotManifest();
-  const repo = readRepoDeclaration(manifest, root);
-  if (!repo.sides?.fe)
-    throw new ScaffoldError(
-      "HFS_ADD_NO_FRONT_END",
-      "this app has no front-end side",
-    );
-  if (repo.sides.fe.apps.some((app) => app.name === name))
-    throw new ScaffoldError(
-      "HFS_ADD_EXISTS",
-      `front-end app ${name} is already declared`,
-    );
-
+/** Render the edition skeleton followed by its shared core and edition overlay. */
+function planAppTemplates(repo, name) {
   const source = path.join(
     TEMPLATES_DIR,
     "fe",
@@ -94,8 +65,13 @@ export function addApp({ root, name }) {
     if (!fs.existsSync(dir)) continue;
     for (const relative of listFiles(dir)) byPath.set(relative, { relative: `${targetBase}/${relative}`, body: readTemplate(dir, relative) });
   }
-  const planned = [...byPath.values()];
+  return callbackSourceFiles([...byPath.values()].map(file => ({ path: file.relative, content: file.body })), repo)
+    .map(file => ({ relative: file.path, body: file.content }));
+}
 
+/** The package and TypeScript manifests of a new Next workspace. */
+function planWorkspaceManifests(root, repo, name) {
+  const targetBase = `fe/apps/${name}`;
   // The dependency source is a product app (it carries the core's fe-stack packages), else the first Next app.
   const firstApp = coreFeApps(repo.sides.fe.apps)[0] ?? repo.sides.fe.apps.find((app) => app.kind === "next");
   const firstPackage = firstApp
@@ -108,8 +84,14 @@ export function addApp({ root, name }) {
     );
   const workspacePackage = JSON.parse(fs.readFileSync(firstPackage, "utf8"));
   workspacePackage.name = `@${repo.project}/${name}`;
+  if (hasAuthCallback(repo)) {
+    const pins = bundledPins();
+    workspacePackage.dependencies ??= {};
+    for (const dependency of ["@supabase/ssr", "@supabase/supabase-js", "server-only"])
+      workspacePackage.dependencies[dependency] = pins[dependency].version;
+  }
   const appTemplates = path.join(TEMPLATES_DIR, "fe", "app");
-  planned.push(
+  return [
     {
       relative: `${targetBase}/package.json`,
       body:
@@ -121,32 +103,10 @@ export function addApp({ root, name }) {
       relative: `${targetBase}/tsconfig.json`,
       body: fs.readFileSync(path.join(appTemplates, "tsconfig.json"), "utf8"),
     },
-  );
-  const declaration = JSON.parse(fs.readFileSync(declarationFile, "utf8"));
-  declaration.sides.fe.apps.push({ name, kind: "next" });
-  if (repo.edition === "full") {
-    const image = imageFiles(
-      resolveRepoDeclaration(manifest, declaration),
-    ).find((file) => file.path === `${targetBase}/Dockerfile`);
-    if (!image)
-      throw new ScaffoldError(
-        "HFS_ADD_TEMPLATE_MISSING",
-        `the Dockerfile of front-end app ${name} did not render`,
-      );
-    planned.push({ relative: image.path, body: image.content });
-  }
-
-  const clashes = planned
-    .filter((file) =>
-      fs.existsSync(path.join(root, ...file.relative.split("/"))),
-    )
-    .map((file) => file.relative);
-  if (clashes.length)
-    throw new ScaffoldError(
-      "HFS_ADD_EXISTS",
-      `front-end app ${name} already exists: ${clashes.join(", ")}`,
-    );
+  ];
+}
 
+function persistAppFiles({ root, name, planned, declaration, declarationFile, packageFile }) {
   const rootPackage = JSON.parse(fs.readFileSync(packageFile, "utf8"));
   const oldDeclaration = fs.readFileSync(declarationFile, "utf8");
   const oldPackage = fs.readFileSync(packageFile, "utf8");
@@ -173,6 +133,64 @@ export function addApp({ root, name }) {
     fs.writeFileSync(packageFile, oldPackage);
     throw error;
   }
+}
+
+/**
+ * Adds one Next workspace from the edition's canonical app skeleton and the shared app core (both editions, owner ruling
+ * 2026-10-13: lite and full have one fe structure), then registers it in hfs.json. The root workspace glob is added only when an
+ * older app manifest does not already carry it.
+ */
+export function addApp({ root, name }) {
+  if (!NAME.test(String(name)))
+    throw new ScaffoldError(
+      "HFS_ADD_NAME_INVALID",
+      `app name ${name} must be kebab-case (letters, digits and single dashes)`,
+    );
+  const declarationFile = path.join(root, "hfs.json");
+  const packageFile = path.join(root, "package.json");
+  if (!fs.existsSync(declarationFile) || !fs.existsSync(packageFile))
+    throw new ScaffoldError(
+      "HFS_ADD_NOT_AN_APP",
+      "add app runs at the app root containing hfs.json and package.json",
+    );
+  const manifest = loadSlotManifest();
+  const repo = readRepoDeclaration(manifest, root);
+  if (!repo.sides?.fe)
+    throw new ScaffoldError(
+      "HFS_ADD_NO_FRONT_END",
+      "this app has no front-end side",
+    );
+  if (repo.sides.fe.apps.some((app) => app.name === name))
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `front-end app ${name} is already declared`,
+    );
+  const targetBase = `fe/apps/${name}`;
+  const planned = [...planAppTemplates(repo, name), ...planWorkspaceManifests(root, repo, name)];
+  const declaration = JSON.parse(fs.readFileSync(declarationFile, "utf8"));
+  declaration.sides.fe.apps.push({ name, kind: "next" });
+  const image = imageFiles(
+    resolveRepoDeclaration(manifest, declaration),
+  ).find((file) => file.path === `${targetBase}/Dockerfile`);
+  if (!image && repo.edition !== "lite")
+    throw new ScaffoldError(
+      "HFS_ADD_TEMPLATE_MISSING",
+      `the Dockerfile of front-end app ${name} did not render`,
+    );
+  if (image) planned.push({ relative: image.path, body: image.content });
+
+  const clashes = planned
+    .filter((file) =>
+      fs.existsSync(path.join(root, ...file.relative.split("/"))),
+    )
+    .map((file) => file.relative);
+  if (clashes.length)
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `front-end app ${name} already exists: ${clashes.join(", ")}`,
+    );
+
+  persistAppFiles({ root, name, planned, declaration, declarationFile, packageFile });
   return {
     created: planned.map((file) => file.relative),
     registered: { app: name, workspace: "fe/apps/*" },