@starci/hfs 4.3.0 → 4.4.0

package/runtime/scripts/hfs/starcistacks-runtime.mjs

@@ -0,0 +1,61 @@
+// Add app deployment conformance to the delivery/quality service gate without changing legacy runtime custody rules.
+import fs from 'node:fs';
+import path from 'node:path';
+import { walkFiles } from '../lib/walk.mjs';
+import { readJson } from './rules/read.mjs';
+import { stacksFindings } from './rules/stacks.mjs';
+import { stacksRuntimeFindings } from './rules/stacks-runtime.mjs';
+import { findStackDeclaration } from '../lib/stack-declaration.mjs';
+import { loadSlotManifest, openHfs } from './slots.mjs';
+
+/** Source paths admitted to stack and scheduling checks; never descend through symlinks. */
+function safeSourceDirectory(repoRoot, relative) {
+  const root = path.resolve(repoRoot);
+  let cursor = path.resolve(root, relative);
+  while (cursor !== root) {
+    try { if (fs.lstatSync(cursor).isSymbolicLink()) return false; } catch { return false; }
+    cursor = path.dirname(cursor);
+  }
+  return true;
+}
+
+function applicationStackFiles(repoRoot) {
+  return ['.starcistacks', '.github/workflows', 'deploy', 'scripts'].flatMap(relative => {
+    if (!safeSourceDirectory(repoRoot, relative)) return [];
+    return walkFiles(path.join(repoRoot, relative), { ignoreReadErrors: true, exclude: (_name, _file, entry) => entry.isSymbolicLink() })
+      .map(file => path.relative(repoRoot, file).replaceAll('\\', '/'));
+  });
+}
+
+export const appEdition = repoRoot => readJson(repoRoot, 'hfs.json')?.edition ?? 'full';
+
+/** An HFS app uses its edition's slot shape; other repository declarations still receive Swarm runtime checks. */
+export function applicationStackFindings(repoRoot) {
+  const files = applicationStackFiles(repoRoot), declaration = readJson(repoRoot, 'hfs.json');
+  if (declaration?.kind === 'app') {
+    try {
+      const resolver = openHfs({ declaration, manifest: loadSlotManifest() });
+      const findings = stacksFindings({ repoRoot, files, resolver }), manifestFile = '.starcistacks/application-stacks.yaml';
+      if (resolver.slot('app.starcistacks')?.requires?.includes('application-stacks.yaml') && !files.includes(manifestFile))
+        return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: manifestFile, message: `${manifestFile}: the app stacks slot requires this declaration` }, ...findings];
+      return findings;
+    } catch (error) {
+      return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: 'hfs.json', message: `hfs.json: cannot resolve the app stacks shape: ${error.message}` }];
+    }
+  }
+  const doc = findStackDeclaration(repoRoot).doc;
+  return doc ? stacksRuntimeFindings({ repoRoot, files, doc }) : [];
+}
+
+/** Lite may retain value-free development custody metadata without declaring a self-hosted development stack. */
+export function liteCustodyDirectory(directory) {
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
+  return entries.length > 0 && entries.every(entry => {
+    if (entry.isSymbolicLink()) return false;
+    if (entry.isFile()) return entry.name === 'environment.json';
+    if (!entry.isDirectory() || entry.name !== 'secrets') return false;
+    return fs.readdirSync(path.join(directory, entry.name), { withFileTypes: true })
+      .every(secret => secret.isFile() && !secret.isSymbolicLink() && (secret.name === '.gitkeep' || /^[a-z0-9-]+\.enc$/.test(secret.name)));
+  });
+}

package/runtime/scripts/lib/command-tokens.mjs

@@ -0,0 +1,126 @@
+// command-tokens.mjs — the tokens of the tail of a documented `starci` command (the lexer under doc-commands.mjs).
+//
+// A tail is split into shell-like atoms: a run of non-space characters in which <...>, [...], {...}, (...) and quoted parts may hold
+// spaces. [..] and (..) groups are optional text (all their alternatives are named); a (..) group that opens with a plain word is
+// commentary and ends the command; a token that ends a sentence ends the command.
+
+import { trimEndWhile } from './trim-end.mjs';
+
+const CLOSERS = { '<': '>', '[': ']', '{': '}', '(': ')' };
+const TRAILING_CHARS = '.,;:!?)\'"`]}';
+const GROUP_TRAILING_CHARS = '.,;:)';
+const CUT = { text: '#', optional: false };
+const OPENS_VALUE = /^\s*(--|<|\[|\$)/;
+const QUOTED = /^(['"]).*\1$/;
+const NAME = /^[\w.]+$/;
+
+/** The index of the character that closes the bracket group opened at `from`, or -1 when it never closes. */
+function groupEnd(s, from) {
+  const open = s[from];
+  let depth = 0;
+  for (let j = from; j < s.length; j += 1) {
+    if (s[j] === open) depth += 1;
+    else if (s[j] === CLOSERS[open]) {
+      depth -= 1;
+      if (depth === 0) return j;
+    }
+  }
+  return -1;
+}
+
+/** The end of the atom that starts at `start`. */
+function readAtom(s, start) {
+  let i = start;
+  while (i < s.length && !/\s/.test(s[i])) {
+    const c = s[i];
+    if (c in CLOSERS) {
+      const end = groupEnd(s, i);
+      if (end < 0) return s.length;
+      i = end + 1;
+    } else if ((c === '"' || c === "'") && (i === start || s[i - 1] === '=')) {
+      const j = s.indexOf(c, i + 1);
+      i = j < 0 ? i + 1 : j + 1;
+    } else i += 1;
+  }
+  return i;
+}
+
+const stripTrailing = (atom, chars) => trimEndWhile(atom, (c) => chars.includes(c));
+
+/** The maximal run of sentence punctuation at the end of an atom: {index, text}, or null. */
+const trailingRun = (atom) => {
+  let start = atom.length;
+  while (start > 0 && TRAILING_CHARS.includes(atom[start - 1])) start -= 1;
+  return start < atom.length ? { index: start, text: atom.slice(start) } : null;
+};
+
+// ${NAME}, $NAME and ${NAME with an optional closing brace
+const isDollarName = (t) => {
+  if (!t.startsWith('$')) return false;
+  let rest = t.slice(1);
+  if (rest.startsWith('{')) rest = rest.slice(1);
+  if (rest.endsWith('}')) rest = rest.slice(0, -1);
+  return NAME.test(rest);
+};
+
+// an <...> part with at least one character inside
+const hasAnglePart = (t) => {
+  for (let i = t.indexOf('<'); i >= 0; i = t.indexOf('<', i + 1)) {
+    if (t.indexOf('>', i + 1) > i + 1) return true;
+  }
+  return false;
+};
+
+const wrapped = (t, open, close) => t.startsWith(open) && t.endsWith(close) && t.length >= open.length + close.length;
+
+/** A value written as a placeholder: <id>, $VAR, ${VAR}, {x}. */
+export const isPlaceholder = (t) => wrapped(t, '<', '>') || isDollarName(t) || wrapped(t, '${', '}') || wrapped(t, '{', '}')
+  || hasAnglePart(t) || t.includes('${');
+
+/** <a|b>: alternatives written inside angle brackets. */
+export const isAlternation = (t) => {
+  if (!wrapped(t, '<', '>')) return false;
+  const bar = t.indexOf('|', 2);
+  return bar > 0 && bar <= t.length - 3;
+};
+
+const isGroup = (closed) => closed.length > 2 && ((closed.startsWith('[') && closed.endsWith(']')) || (closed.startsWith('(') && closed.endsWith(')')));
+const unquote = (atom) => (atom.length > 1 && QUOTED.test(atom) ? atom.slice(1, -1) : atom);
+
+// {tokens, stop} of a bracket group atom
+function groupTokens(atom, closed) {
+  const body = closed.slice(1, -1);
+  if (atom.startsWith('(') && !OPENS_VALUE.test(body)) return { tokens: [CUT], stop: true };
+  return {
+    tokens: tokenise(body, true).filter((t) => t.text !== '|'),
+    stop: closed !== atom && /[.,;:]/.test(atom.slice(closed.length)),
+  };
+}
+
+// {tokens, stop} of a plain atom
+function plainTokens(atom, optional) {
+  const tail = /^\.{1,3}$/.test(atom) ? null : trailingRun(atom);
+  const trimmed = tail !== null && !isPlaceholder(atom);
+  const bare = trimmed ? atom.slice(0, tail.index) : atom;
+  return { tokens: bare ? [{ text: bare, optional }] : [], stop: trimmed && /[^\]]/.test(tail.text) };
+}
+
+/** The flat tokens {text, optional} of a command tail. */
+export function tokenise(text, optional = false) {
+  const tokens = [];
+  let i = 0;
+  while (i < text.length) {
+    if (/\s/.test(text[i])) {
+      i += 1;
+      continue;
+    }
+    const end = readAtom(text, i);
+    const atom = text.slice(i, end);
+    i = end;
+    const closed = atom.startsWith('[') ? stripTrailing(atom, GROUP_TRAILING_CHARS) : atom;
+    const step = isGroup(closed) ? groupTokens(atom, closed) : plainTokens(unquote(atom), optional);
+    tokens.push(...step.tokens);
+    if (step.stop) break;
+  }
+  return tokens;
+}

package/runtime/scripts/lib/compose-values.mjs

@@ -0,0 +1,11 @@
+import { isPlainObject } from '../../engine/plain-object.mjs';
+
+/** Compose mapping/list entries; callers choose how bare keys and non-string list items are interpreted. */
+export function composeEntries(value, { missingValue = '', stringsOnly = false, isMapping = isPlainObject } = {}) {
+  if (!Array.isArray(value)) return Object.entries(isMapping(value) ? value : {});
+  const entries = stringsOnly ? value.filter(entry => typeof entry === 'string') : value;
+  return entries.map(entry => {
+    const text = String(entry), separator = text.indexOf('=');
+    return separator < 0 ? [text, missingValue] : [text.slice(0, separator), text.slice(separator + 1)];
+  });
+}

package/runtime/scripts/lib/deployment-findings.mjs

@@ -0,0 +1,7 @@
+/** Project issues from available rendered deployments with the caller's finding factory. */
+export function deploymentFindings(deployments, issuesFor, findingFor, defaultFile) {
+  return deployments.filter(entry => !entry.unavailable).flatMap(entry => {
+    const file = entry.file ?? defaultFile;
+    return issuesFor(entry).map(issue => findingFor(issue.code, file, `${file}: ${issue.at}: ${issue.message}`));
+  });
+}

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/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/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;
+}