@starci/hfs 4.11.22 → 4.12.0

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

@@ -4,181 +4,209 @@
 // scripts/uat/test-secret.mjs; the sops binary is found by scripts/api/sops/lib.mjs.
 import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
-
 const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 const STACK = /^[a-z0-9][a-z0-9-]{0,31}$/;
 /** One sops-encrypted leaf: `ENC[AES256_GCM,data:...,iv:...,tag:...,type:...]` (data may be empty). */
 const SOPS_VALUE = /^ENC\[AES256_GCM,data:[A-Za-z0-9+/=]*,iv:[A-Za-z0-9+/=]+,tag:[A-Za-z0-9+/=]+,type:[a-z]+\]$/;
-
 /** Where test credential `name` of `stack` lives in `repo`: {plain, enc, rel}. `rel` is the path the repo's
  *  `stack-secret.mjs set` takes. */
 export function testSecretPaths(name, { repo, stack = 'dev' } = {}) {
-  if (!NAME.test(String(name ?? ''))) throw new Error(`test secret name must match ${NAME} (got ${JSON.stringify(name)})`);
-  if (!STACK.test(String(stack ?? ''))) throw new Error(`stack must match ${STACK} (got ${JSON.stringify(stack)})`);
-  if (!repo) throw new Error('test secret needs {repo}: the product repository whose .starcistacks holds it');
-  const rel = `${stack}/secrets/test/${name}`;
-  const plain = path.join(path.resolve(String(repo)), '.starcistacks', stack, 'secrets', 'test', name);
-  return { plain, enc: `${plain}.enc`, rel };
+    if (!NAME.test(String(name ?? '')))
+        throw new Error(`test secret name must match ${NAME} (got ${JSON.stringify(name)})`);
+    if (!STACK.test(String(stack ?? '')))
+        throw new Error(`stack must match ${STACK} (got ${JSON.stringify(stack)})`);
+    if (!repo)
+        throw new Error('test secret needs {repo}: the product repository whose .starcistacks holds it');
+    const rel = `${stack}/secrets/test/${name}`;
+    const plain = path.join(path.resolve(String(repo)), '.starcistacks', stack, 'secrets', 'test', name);
+    return { plain, enc: `${plain}.enc`, rel };
 }
-
 /** The command that stores a test credential, in the product repository's own tooling. */
 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) => {
-  if (file.endsWith('.env')) return 'dotenv';
-  if (file.endsWith('.json')) return 'json';
-  if (/\.(ya?ml|kubeconfig)$/.test(file)) return 'yaml';
-  return 'binary';
+    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) => {
-  if (node === null) return true;
-  if (Array.isArray(node)) return node.every(allEncrypted);
-  if (typeof node === 'object') return Object.values(node).every(allEncrypted);
-  return typeof node === 'string' && SOPS_VALUE.test(node);
+    if (node === null)
+        return true;
+    if (Array.isArray(node))
+        return node.every(allEncrypted);
+    if (typeof node === 'object')
+        return Object.values(node).every(allEncrypted);
+    return typeof node === 'string' && SOPS_VALUE.test(node);
 };
+// reason: a sops document is JSON or YAML parsed from a committed file; the envelope test reads it structurally.
 const sopsTree = (doc) => !!doc && typeof doc === 'object' && !Array.isArray(doc) && !!doc.sops && typeof doc.sops === 'object'
-  && typeof doc.sops.mac === 'string' && SOPS_VALUE.test(doc.sops.mac)
-  && Object.keys(doc).length > 1 && Object.entries(doc).every(([k, v]) => k === 'sops' || allEncrypted(v));
-
+    && typeof doc.sops.mac === 'string' && SOPS_VALUE.test(doc.sops.mac)
+    && Object.keys(doc).length > 1 && Object.entries(doc).every(([k, v]) => k === 'sops' || allEncrypted(v));
 /**
  * True only for a sops-encrypted file with no plaintext value: binary/json form ({"data": ENC[...], "sops": {...}}),
  * yaml form (every value ENC[...] plus the sops block) or dotenv form (KEY=ENC[...] lines plus sops_* metadata).
  * The sops metadata must carry its mac. A key kept plaintext through `unencrypted_suffix` does not pass.
  */
 export function isSopsEnvelope(text) {
-  const src = String(text ?? '').replace(/^/, '');
-  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_]\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_'));
-    return vals.length > 0 && vals.every(([, v]) => SOPS_VALUE.test(v)) && meta.some(([k, v]) => k === 'sops_mac' && SOPS_VALUE.test(v));
-  }
-  try { return sopsTree(parseYaml(src)); } catch { return false; }
+    const src = String(text ?? '').replace(/^/, '');
+    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_]\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_'));
+        return vals.length > 0 && vals.every(([, v]) => SOPS_VALUE.test(v)) && meta.some(([k, v]) => k === 'sops_mac' && SOPS_VALUE.test(v));
+    }
+    try {
+        return sopsTree(parseYaml(src));
+    }
+    catch {
+        return false;
+    }
 }
-
 /** A refused admission, named by its reason. */
 const refusal = (reason) => ({ ok: false, reason });
-
 const DOTENV_AGE_FIELD = /^age__list_(0|[1-9]\d{0,2})__map_(recipient|enc)$/u;
-
 function dotenvMetadataValue(meta, age, key, value) {
-  const field = DOTENV_AGE_FIELD.exec(key);
-  if (field) {
-    const entry = (age[Number(field[1])] ??= {});
-    entry[field[2]] = 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;
+    const field = DOTENV_AGE_FIELD.exec(key);
+    if (field) {
+        const entry = (age[Number(field[1])] ??= {});
+        entry[field[2]] = 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 };
-  }
-  // A gap in the list indices is an entry sops never wrote: refused as an empty entry, never skipped.
-  meta.age = Array.from(age, (entry) => entry ?? null);
-  return { meta };
+    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 };
+    }
+    // A gap in the list indices is an entry sops never wrote: refused as an empty entry, never skipped.
+    meta.age = Array.from(age, (entry) => entry ?? null);
+    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 };
+    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' }; }
+    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;
+    for (const name of providers) {
+        const provider = meta[name];
+        if (Object.hasOwn(meta, name) && (!Array.isArray(provider) || provider.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));
+    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-----');
+    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));
+    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');
-  const set = ageSet(meta.age);
-  if (!set.ok) return set;
-  if (!set.recipients.includes(recipient)) return refusal('recipient-mismatch');
-  if (!hasValidEnvelopeVersion(meta)) return refusal('invalid-envelope');
-  return { ok: true };
+    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');
+    const set = ageSet(meta.age);
+    if (!set.ok)
+        return set;
+    if (!set.recipients.includes(recipient))
+        return refusal('recipient-mismatch');
+    if (!hasValidEnvelopeVersion(meta))
+        return refusal('invalid-envelope');
+    return { ok: true };
 }
-
 const AGE_RECIPIENT = /^age1[ac-hj-np-z02-9]+$/u;
-
 /**
  * The age set of an envelope: one or more entries (the owner key and an environment's server key are the standard pair), each a
  * well-formed recipient with its wrapped data key; an empty entry or a recipient named twice is refused.
  */
 function ageSet(entries) {
-  if (!Array.isArray(entries) || entries.length === 0) return refusal('unsupported-age-set');
-  const recipients = [];
-  for (const entry of entries) {
-    if (!isAgeEntry(entry) || typeof entry.recipient !== 'string' || !AGE_RECIPIENT.test(entry.recipient) || !hasValidAgePayload(entry))
-      return refusal('invalid-age-entry');
-    if (recipients.includes(entry.recipient)) return refusal('duplicate-age-recipient');
-    recipients.push(entry.recipient);
-  }
-  return { ok: true, recipients };
+    if (!Array.isArray(entries) || entries.length === 0)
+        return refusal('unsupported-age-set');
+    const recipients = [];
+    for (const entry of entries) {
+        if (!isAgeEntry(entry) || typeof entry.recipient !== 'string' || !AGE_RECIPIENT.test(entry.recipient) || !hasValidAgePayload(entry))
+            return refusal('invalid-age-entry');
+        if (recipients.includes(entry.recipient))
+            return refusal('duplicate-age-recipient');
+        recipients.push(entry.recipient);
+    }
+    return { ok: true, recipients };
 }
-
 /**
  * Admit one flat age envelope for the native selected-identity invocation when `recipient` (the selected identity's public key) is
  * one of its age set. Shape admission, never cryptographic proof.
  */
 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);
+    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/source-phrases.d.mts

@@ -0,0 +1,4 @@
+/** The phrase list `dotKey` (`<group>.<list>`) of `root`, [] when absent. */
+export declare function phrasesOf(dotKey: string, root?: string): string[];
+/** The regex alternation of `dotKey` ('a|b|c'); '(?!)' - a never-match - when the list is empty. */
+export declare const altOf: (dotKey: string, root?: string) => string;

package/runtime/scripts/lib/source-phrases.mjs

@@ -9,26 +9,26 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-
 const SOURCE_PHRASES_FILE = 'modules/goal/source-phrases.yaml';
-
 const cache = new Map();
-
 /** The lexicon's `phrases` map ({<group>: {<list>: string[]}}), cached per root. */
 function sourcePhrases(root = skillRoot) {
-  if (!cache.has(root)) {
-    let doc = null;
-    try { doc = parseYaml(fs.readFileSync(path.join(root, ...SOURCE_PHRASES_FILE.split('/')), 'utf8')); } catch { doc = null; }
-    cache.set(root, doc?.phrases && typeof doc.phrases === 'object' ? doc.phrases : {});
-  }
-  return cache.get(root);
+    if (!cache.has(root)) {
+        let doc = null;
+        try {
+            doc = parseYaml(fs.readFileSync(path.join(root, ...SOURCE_PHRASES_FILE.split('/')), 'utf8'));
+        }
+        catch {
+            doc = null;
+        }
+        cache.set(root, doc?.phrases && typeof doc.phrases === 'object' ? doc.phrases : {});
+    }
+    return cache.get(root);
 }
-
 /** The phrase list `dotKey` (`<group>.<list>`) of `root`, [] when absent. */
 export function phrasesOf(dotKey, root = skillRoot) {
-  const value = dotKey.split('.').reduce((v, k) => (v && typeof v === 'object' ? v[k] : undefined), sourcePhrases(root));
-  return (Array.isArray(value) ? value : []).map(String);
+    const value = dotKey.split('.').reduce((v, k) => (v && typeof v === 'object' ? v[k] : undefined), sourcePhrases(root));
+    return (Array.isArray(value) ? value : []).map(String);
 }
-
 /** The regex alternation of `dotKey` ('a|b|c'); '(?!)' - a never-match - when the list is empty. */
 export const altOf = (dotKey, root = skillRoot) => phrasesOf(dotKey, root).join('|') || '(?!)';

package/runtime/scripts/lib/sql-ast.d.mts

@@ -0,0 +1,13 @@
+/** String identifier components from libpg-query's wrapped String nodes. */
+export type SqlNode = any;
+export declare const sqlStringParts: (nodes?: SqlNode[] | null) => string[];
+/** Traverse SQL/PLpgSQL objects; executable scans leave function declarations inert. */
+export declare function walkSqlAst(value: SqlNode, visit: (node: SqlNode) => void, executable?: boolean): void;
+/** Build a synchronous parser with the caller's failure policy and initialized parser. */
+export declare function sqlParser<R = null>(parser: {
+    parseSync(text: string): SqlNode;
+} | null | undefined, reject?: (error: unknown) => R): (text: string) => SqlNode | R;
+/** Resolve named arguments before positional arguments, as PostgreSQL does. */
+export declare function sqlCallArgument(call: SqlNode, position: number, names?: readonly string[]): SqlNode;
+/** Read a literal string through static casts without evaluating an expression. */
+export declare function sqlStringLiteral(node: SqlNode): string | null;

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

@@ -1,32 +1,33 @@
 // 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);
+    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); }
-  };
+    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];
+    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;
+    if (node?.TypeCast)
+        return sqlStringLiteral(node.TypeCast.arg);
+    return node?.A_Const?.sval?.sval ?? null;
 }

package/runtime/scripts/lib/sqlite.d.mts

@@ -0,0 +1,21 @@
+/** A prepared better-sqlite3 statement, as far as these helpers use it. */
+export interface SqliteStatement<Run = unknown> {
+    get(...params: unknown[]): unknown;
+    all<Row = Record<string, unknown>>(...params: unknown[]): Row[];
+    run(...params: unknown[]): Run;
+}
+/** A better-sqlite3 database handle, as far as these helpers use it; `Run` is what its statements' run() reports. */
+export interface SqliteDb<Run = unknown> {
+    prepare(sql: string): SqliteStatement<Run>;
+}
+/** Whether the database holds a table `name` (`views: true` also counts views). */
+export declare const hasTable: (db: SqliteDb, name: string, { views }?: {
+    views?: boolean;
+}) => boolean;
+/**
+ * The per-store `insertRow`: binds the caller's own [column, value] mapper (`cellsOf` — where the store's
+ * column validation and value encoding live) to an insertPairs statement.
+ */
+export declare const insertRowWith: <Run, Db extends SqliteDb<Run>, Row>(cellsOf: (db: Db, table: string, row: Row) => readonly (readonly [string, unknown])[]) => (db: Db, table: string, row: Row, { orIgnore }?: {
+    orIgnore?: boolean;
+}) => Run;

package/runtime/scripts/lib/sqlite.mjs

@@ -1,21 +1,15 @@
 // sqlite.mjs — the small better-sqlite3 probes the ledger and machine stores share. The handle is the
 // caller's; these helpers prepare statements on it and return its own result shapes.
-
 /** Whether the database holds a table `name` (`views: true` also counts views). */
-export const hasTable = (db, name, { views = false } = {}) =>
-  Boolean(db.prepare(`SELECT 1 FROM sqlite_master WHERE type${views ? " IN ('table','view')" : "='table'"} AND name=?`).get(name));
-
+export const hasTable = (db, name, { views = false } = {}) => Boolean(db.prepare(`SELECT 1 FROM sqlite_master WHERE type${views ? " IN ('table','view')" : "='table'"} AND name=?`).get(name));
 /**
  * INSERT the [column, value] `pairs` into `table` (`orIgnore` spells OR IGNORE); returns the statement's
  * run() result. Column naming and value encoding are the caller's — this is only the statement shape.
  */
-const insertPairs = (db, table, pairs, { orIgnore = false } = {}) =>
-  db.prepare(`INSERT ${orIgnore ? 'OR IGNORE ' : ''}INTO ${table}(${pairs.map((p) => p[0]).join(',')}) VALUES(${pairs.map(() => '?').join(',')})`)
+const insertPairs = (db, table, pairs, { orIgnore = false } = {}) => db.prepare(`INSERT ${orIgnore ? 'OR IGNORE ' : ''}INTO ${table}(${pairs.map((p) => p[0]).join(',')}) VALUES(${pairs.map(() => '?').join(',')})`)
     .run(...pairs.map((p) => p[1]));
-
 /**
  * The per-store `insertRow`: binds the caller's own [column, value] mapper (`cellsOf` — where the store's
  * column validation and value encoding live) to an insertPairs statement.
  */
-export const insertRowWith = (cellsOf) => (db, table, row, { orIgnore = false } = {}) =>
-  insertPairs(db, table, cellsOf(db, table, row), { orIgnore });
+export const insertRowWith = (cellsOf) => (db, table, row, { orIgnore = false } = {}) => insertPairs(db, table, cellsOf(db, table, row), { orIgnore });

package/runtime/scripts/lib/stack-declaration.d.mts

@@ -0,0 +1,51 @@
+export declare const DECLARATION = "application-stacks.yaml";
+/** The one stack root a repository owns. */
+export declare const STACK_ROOT = ".starcistacks";
+/** A non-blank string, trimmed; anything else is null. */
+export declare const text: (value: unknown) => string | null;
+/** The text of `file`, or null when it is absent or larger than 2 MiB. */
+export declare const readText: (file: string) => string | null;
+/** A parsed YAML mapping (the declaration document). */
+export type DeclarationDoc = Record<string, unknown>;
+/** The read of a declaration file. */
+export type DeclarationRead = {
+    doc: DeclarationDoc;
+    error?: undefined;
+} | {
+    error: string;
+    doc?: undefined;
+};
+/** The stack declaration a repository owns, or {missing:true} when it declares none. */
+export type StackDeclaration = ({
+    repo: string;
+    root: string;
+    file: string;
+    rooted: boolean;
+} & DeclarationRead) | {
+    repo: string;
+    missing: true;
+    rooted: boolean;
+    root?: undefined;
+    file?: undefined;
+    doc?: undefined;
+    error?: undefined;
+};
+/** The stack block of one declared service. */
+export interface DeclaredStack {
+    owner: string | null;
+    root: string | null;
+    repository: string | null;
+    hostOwned: boolean;
+}
+/** The parsed declaration file: {doc} or {error}. */
+export declare function readDeclaration(file: string): DeclarationRead;
+/**
+ * The stack declaration a repository owns: {root, file, rooted, doc|error} - or {missing:true, rooted}
+ * when .starcistacks/application-stacks.yaml does not exist. `rooted` says the .starcistacks tree exists.
+ */
+export declare function findStackDeclaration(repoRoot: unknown): StackDeclaration;
+/**
+ * The stack block of one declared service, or null when it has none: {owner, root, repository, hostOwned}. A stack is
+ * host-owned when it says `owner: host` (it lives in the installed runtime tree, `.claude/ext/<service>`); `root` is posix.
+ */
+export declare function declaredStack(entry: unknown): DeclaredStack | null;

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

@@ -8,45 +8,52 @@ import { isPlainObject as plain } from '../../engine/plain-object.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { isDir, isFile } from './fs-kind.mjs';
 import { posixPath } from './path-key.mjs';
-
 export const DECLARATION = 'application-stacks.yaml';
 /** The one stack root a repository owns. */
 export const STACK_ROOT = '.starcistacks';
 const MAX_BYTES = 2 * 1024 * 1024;
-
 /** A non-blank string, trimmed; anything else is null. */
 export const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
-
 /** The text of `file`, or null when it is absent or larger than 2 MiB. */
-export const readText = (file) => { try { return fs.statSync(file).size > MAX_BYTES ? null : fs.readFileSync(file, 'utf8'); } catch { return null; } };
-
+export const readText = (file) => { try {
+    return fs.statSync(file).size > MAX_BYTES ? null : fs.readFileSync(file, 'utf8');
+}
+catch {
+    return null;
+} };
 /** The parsed declaration file: {doc} or {error}. */
 export function readDeclaration(file) {
-  const raw = readText(file);
-  if (raw === null) return { error: 'unreadable or larger than 2 MiB' };
-  try { const doc = parseYaml(raw); return plain(doc) ? { doc } : { error: 'not a YAML mapping' }; }
-  catch (error) { return { error: `YAML does not parse: ${String(error?.message ?? error).split('\n')[0]}` }; }
+    const raw = readText(file);
+    if (raw === null)
+        return { error: 'unreadable or larger than 2 MiB' };
+    try {
+        const doc = parseYaml(raw);
+        return plain(doc) ? { doc } : { error: 'not a YAML mapping' };
+    }
+    catch (error) {
+        return { error: `YAML does not parse: ${String(error?.message ?? error).split('\n')[0]}` };
+    }
 }
-
 /**
  * The stack declaration a repository owns: {root, file, rooted, doc|error} - or {missing:true, rooted}
  * when .starcistacks/application-stacks.yaml does not exist. `rooted` says the .starcistacks tree exists.
  */
 export function findStackDeclaration(repoRoot) {
-  const repo = path.resolve(String(repoRoot ?? ''));
-  const rooted = isDir(path.join(repo, STACK_ROOT));
-  const file = path.join(repo, STACK_ROOT, DECLARATION);
-  if (isFile(file)) return { repo, root: STACK_ROOT, file, rooted, ...readDeclaration(file) };
-  return { repo, missing: true, rooted };
+    const repo = path.resolve(String(repoRoot ?? ''));
+    const rooted = isDir(path.join(repo, STACK_ROOT));
+    const file = path.join(repo, STACK_ROOT, DECLARATION);
+    if (isFile(file))
+        return { repo, root: STACK_ROOT, file, rooted, ...readDeclaration(file) };
+    return { repo, missing: true, rooted };
 }
-
 /**
  * The stack block of one declared service, or null when it has none: {owner, root, repository, hostOwned}. A stack is
  * host-owned when it says `owner: host` (it lives in the installed runtime tree, `.claude/ext/<service>`); `root` is posix.
  */
 export function declaredStack(entry) {
-  const stack = plain(entry) && plain(entry.stack) ? entry.stack : null;
-  if (!stack) return null;
-  const root = text(stack.root);
-  return { owner: text(stack.owner), root: root === null ? null : posixPath(root), repository: text(stack.repository), hostOwned: text(stack.owner) === 'host' };
+    const stack = (plain(entry) && plain(entry['stack']) ? entry['stack'] : null);
+    if (!stack)
+        return null;
+    const root = text(stack.root);
+    return { owner: text(stack.owner), root: root === null ? null : posixPath(root), repository: text(stack.repository), hostOwned: text(stack.owner) === 'host' };
 }