@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/lib/redact.mjs

@@ -16,10 +16,8 @@ import { parseYaml } from '../../engine/yaml.mjs';
 import { altOf } from './source-phrases.mjs';
 import { trimEdgeChar } from './normalize.mjs';
 import { redactResolvedSecrets } from '../../engine/secrets.mjs';
-
 const REDACTION_VERSION = 'v1';
 export const MARK = '[redacted]';
-
 const withGlobal = (re) => new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
 const PATTERNS = SECRET_PATTERNS.filter((rule) => rule.name !== 'private-key-block').map((rule) => ({ ...rule, g: withGlobal(rule.re) }));
 // Words that make an env-style key a secret, matched per `_`-separated segment of the name (FOO_API_KEY,
@@ -28,25 +26,23 @@ const SECRET_SEGMENTS = new Set(['PASSWORD', 'PASSWD', 'PWD', 'PASS', 'SECRET',
 const isSecretEnvName = (name) => String(name).replace(/^export\s+/, '').replace(/_FILE$/, '').split('_').some((seg) => SECRET_SEGMENTS.has(seg));
 const PEM_BLOCK = /-----BEGIN ((?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?)-----[\s\S]*?(?:-----END \1-----|$)/g;
 const RULES = [
-  { name: 'url-credentials', re: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/"'<>]+):([^\s@/"'<>]+)@/gi, to: (m, scheme, user) => `${scheme}${user}:${MARK}@` },
-  { name: 'auth-header', re: /\b(Bearer|Basic|Token)(\s+)[A-Z0-9._~+/=-]{8,}/gi, to: (m, a, b) => `${a}${b}${MARK}` },
-  { name: 'url-secret', re: /([?&#](?:access_token|refresh_token|id_token|token|key|api_key|apikey|secret|code|password|otp|sig|signature)=)([^&#\s"']+)/gi, to: (m, a) => `${a}${MARK}` },
-  { name: 'otp', re: new RegExp(String.raw`\b(otp|one[-_ ]?time[-_ ]?(?:code|password|pin)|verification[-_ ]?code|2fa[-_ ]?code|${altOf('redact.otpLabel')})(\s*[:=]?\s*["']?)(\d{4,8})\b`, 'giu'), to: (m, a, b) => `${a}${b}${MARK}` },
-  // ENV_STYLE_KEY=value / ENV_STYLE_KEY: value (shell exports, dotenv, compose, CLI echo).
-  { name: 'env-secret', re: /\b((?:export\s+)?[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*)(\s*[:=]\s*["']?)((?!\[redacted)[^\s"'`]{3,})/g,
-    to: (m, a, b, c) => (isSecretEnvName(a) && !c.startsWith('/run/secrets/') && !c.startsWith('$') ? `${a}${b}${MARK}` : m) },
-  { name: 'keyed-secret', re: new RegExp([
-    String.raw`\b(password|passwd|pwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|auth[_-]?token|session[_-]?token|private[_-]?key|otp|pin[_-]?code|cookie|set-cookie)`,
-    String.raw`(["']?\s*[:=]\s*["']?)((?!\[redacted)[^\s"',;&}]{3,})`,
-  ].join(''), 'gi'), to: (m, a, b) => `${a}${b}${MARK}` },
+    { name: 'url-credentials', re: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/"'<>]+):([^\s@/"'<>]+)@/gi, to: (_m, scheme, user) => `${scheme}${user}:${MARK}@` },
+    { name: 'auth-header', re: /\b(Bearer|Basic|Token)(\s+)[A-Z0-9._~+/=-]{8,}/gi, to: (_m, a, b) => `${a}${b}${MARK}` },
+    { name: 'url-secret', re: /([?&#](?:access_token|refresh_token|id_token|token|key|api_key|apikey|secret|code|password|otp|sig|signature)=)([^&#\s"']+)/gi, to: (_m, a) => `${a}${MARK}` },
+    { name: 'otp', re: new RegExp(String.raw `\b(otp|one[-_ ]?time[-_ ]?(?:code|password|pin)|verification[-_ ]?code|2fa[-_ ]?code|${altOf('redact.otpLabel')})(\s*[:=]?\s*["']?)(\d{4,8})\b`, 'giu'), to: (_m, a, b) => `${a}${b}${MARK}` },
+    // ENV_STYLE_KEY=value / ENV_STYLE_KEY: value (shell exports, dotenv, compose, CLI echo).
+    { name: 'env-secret', re: /\b((?:export\s+)?[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*)(\s*[:=]\s*["']?)((?!\[redacted)[^\s"'`]{3,})/g,
+        to: (m, a, b, c) => (isSecretEnvName(a) && !c.startsWith('/run/secrets/') && !c.startsWith('$') ? `${a}${b}${MARK}` : m) },
+    { name: 'keyed-secret', re: new RegExp([
+            String.raw `\b(password|passwd|pwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|auth[_-]?token|session[_-]?token|private[_-]?key|otp|pin[_-]?code|cookie|set-cookie)`,
+            String.raw `(["']?\s*[:=]\s*["']?)((?!\[redacted)[^\s"',;&}]{3,})`,
+        ].join(''), 'gi'), to: (_m, a, b) => `${a}${b}${MARK}` },
 ];
-
 /** Keys whose value is a secret whatever it looks like; the key stays, the value goes. */
 export const SECRET_KEY = new RegExp([
-  '^(?:password|passwd|pwd|pass|secret|otp|pin|pincode|pin_code|credential|credentials|authorization|cookie|cookies|set-cookie|private[_-]?key|client[_-]?secret|api[_-]?key|apikey|[a-z_-]*token|[a-z_-]*secret)',
-  '$',
+    '^(?:password|passwd|pwd|pass|secret|otp|pin|pincode|pin_code|credential|credentials|authorization|cookie|cookies|set-cookie|private[_-]?key|client[_-]?secret|api[_-]?key|apikey|[a-z_-]*token|[a-z_-]*secret)',
+    '$',
 ].join(''), 'i');
-
 // ------------------------------------------------------------------------------ declared stack secrets
 // A product repo's .starcistacks/<stack>/stack.yaml `secrets:` block names each secret and the runtime file
 // that holds its value. Values are refreshed from their declared inputs; values never leave the filter.
@@ -54,155 +50,173 @@ const STACK_DIRS = ['.starcistacks'];
 const secretValues = new Set();
 const secretNames = new Set();
 const envName = (name) => trimEdgeChar(String(name).replace(/[^A-Za-z0-9]+/g, '_'), '_').toUpperCase();
-const readSafe = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
-const listSafe = (dir) => { try { return fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; } };
-
+const readSafe = (file) => { try {
+    return fs.readFileSync(file, 'utf8');
+}
+catch {
+    return null;
+} };
+const listSafe = (dir) => { try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+}
+catch {
+    return [];
+} };
 function learnStackDirectory(root, stackDir, entry) {
-  const dir = path.join(root, stackDir, entry.name);
-  const text = readSafe(path.join(dir, 'stack.yaml'));
-  let doc = null;
-  try { doc = text ? parseYaml(text) : null; } catch { doc = null; }
-  const secrets = doc?.secrets && typeof doc.secrets === 'object' ? doc.secrets : {};
-  for (const [name, spec] of Object.entries(secrets)) {
-    secretNames.add(envName(name));
-    if (typeof spec?.file === 'string') addSecretValue(readSafe(path.resolve(dir, spec.file)));
-  }
-  // Plaintext runtime copies of the secrets (git-ignored): their values are secrets too.
-  for (const file of listSafe(path.join(dir, 'runtime', 'files'))) if (file.isFile()) addSecretValue(readSafe(path.join(dir, 'runtime', 'files', file.name)));
+    const dir = path.join(root, stackDir, entry.name);
+    const text = readSafe(path.join(dir, 'stack.yaml'));
+    let doc = null;
+    try {
+        doc = text ? parseYaml(text) : null;
+    }
+    catch {
+        doc = null;
+    }
+    const secrets = doc?.secrets && typeof doc.secrets === 'object' ? doc.secrets : {};
+    for (const [name, spec] of Object.entries(secrets)) {
+        secretNames.add(envName(name));
+        if (typeof spec?.file === 'string')
+            addSecretValue(readSafe(path.resolve(dir, spec.file)));
+    }
+    // Plaintext runtime copies of the secrets (git-ignored): their values are secrets too.
+    for (const file of listSafe(path.join(dir, 'runtime', 'files')))
+        if (file.isFile())
+            addSecretValue(readSafe(path.join(dir, 'runtime', 'files', file.name)));
 }
-
 /** A value this process must never write out (a secret it resolved itself). Values under 6 chars are ignored. */
 function addSecretValue(value) {
-  const v = typeof value === 'string' ? value.trim() : '';
-  if (v.length >= 6 && !v.startsWith('[redacted')) secretValues.add(v);
+    const v = typeof value === 'string' ? value.trim() : '';
+    if (v.length >= 6 && !v.startsWith('[redacted'))
+        secretValues.add(v);
 }
-
 /** Learn the declared secrets of every .starcistacks stack under `repoRoot` (idempotent). */
 export function learnStackSecrets(repoRoot) {
-  if (typeof repoRoot !== 'string' || !repoRoot) return;
-  const root = path.resolve(repoRoot);
-  for (const stackDir of STACK_DIRS) {
-    for (const entry of listSafe(path.join(root, stackDir))) {
-      if (!entry.isDirectory()) continue;
-      learnStackDirectory(root, stackDir, entry);
+    if (typeof repoRoot !== 'string' || !repoRoot)
+        return;
+    const root = path.resolve(repoRoot);
+    for (const stackDir of STACK_DIRS) {
+        for (const entry of listSafe(path.join(root, stackDir))) {
+            if (!entry.isDirectory())
+                continue;
+            learnStackDirectory(root, stackDir, entry);
+        }
     }
-  }
 }
-
-const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
 let namesRe = null, namesSize = -1;
 const declaredNameRule = () => {
-  if (namesSize !== secretNames.size) {
-    namesSize = secretNames.size;
-    namesRe = secretNames.size ? new RegExp(`\\b((?:${[...secretNames].map(escapeRe).join('|')})(?:_FILE)?)(\\s*[:=]\\s*["']?)((?!\\[redacted)[^\\s"'\`]{3,})`, 'g') : null;
-  }
-  return namesRe;
+    if (namesSize !== secretNames.size) {
+        namesSize = secretNames.size;
+        namesRe = secretNames.size ? new RegExp(`\\b((?:${[...secretNames].map(escapeRe).join('|')})(?:_FILE)?)(\\s*[:=]\\s*["']?)((?!\\[redacted)[^\\s"'\`]{3,})`, 'g') : null;
+    }
+    return namesRe;
 };
-
 // --------------------------------------------------------------------------------------------- text
 const PEM_RULE = 'private-key-block';
-
 /** `text` with `re` replaced by `to`, `hits` counting each replacement that changed the match under the rule's name. */
 function replaceCounting(text, re, name, to, hits) {
-  re.lastIndex = 0;
-  return text.replace(re, (...args) => {
-    const out = to(...args);
-    if (out !== args[0]) hits.set(name, (hits.get(name) ?? 0) + 1);
-    return out;
-  });
+    re.lastIndex = 0;
+    return text.replace(re, (...args) => {
+        const out = to(...args);
+        if (out !== args[0])
+            hits.set(name, (hits.get(name) ?? 0) + 1);
+        return out;
+    });
 }
-
 const patternTo = (rule) => (match, value) => {
-  if (rule.name === 'assigned-secret') return rule.placeholder?.test(value ?? '') ? match : match.replace(value, MARK);
-  return `[redacted:${rule.name}]`;
+    if (rule.name === 'assigned-secret')
+        return rule.placeholder?.test(value ?? '') ? match : match.replace(value, MARK);
+    return `[redacted:${rule.name}]`;
 };
-
 function redactPatterns(text, hits, assignments) {
-  for (const rule of PATTERNS) {
-    if ((rule.name === 'assigned-secret') !== assignments) continue;
-    text = replaceCounting(text, rule.g, rule.name, patternTo(rule), hits);
-  }
-  return text;
+    for (const rule of PATTERNS) {
+        if ((rule.name === 'assigned-secret') !== assignments)
+            continue;
+        text = replaceCounting(text, rule.g, rule.name, patternTo(rule), hits);
+    }
+    return text;
 }
-
-/**
- * `text` with every secret value blanked, and what blanked it: {text, hits: Map(rule name -> replacements that changed the text)}. A rule
- * that meets only a placeholder ([redacted...]) counts nothing, so a text redacted before reports no hit. `repoRoots` (optional) are product
- * repos whose .starcistacks declarations are learned first.
- */
 export function redactTracked(text, { repoRoots = [] } = {}) {
-  const hits = new Map();
-  if (typeof text !== 'string' || !text) return { text, hits };
-  for (const root of repoRoots) learnStackSecrets(root);
-  const resolved = redactResolvedSecrets(text);
-  if (resolved !== text) hits.set('resolved-secret', 1);
-  let out = replaceCounting(resolved, PEM_BLOCK, PEM_RULE, (m, kind) => `[redacted:pem ${kind}]`, hits);
-  for (const value of secretValues) if (out.includes(value)) { hits.set('stack-secret', (hits.get('stack-secret') ?? 0) + 1); out = out.split(value).join('[redacted:stack-secret]'); }
-  out = redactPatterns(out, hits, false);
-  const declared = declaredNameRule();
-  if (declared) out = replaceCounting(out, declared, 'declared-secret-name', (m, a, b) => `${a}${b}${MARK}`, hits);
-  for (const rule of RULES) out = replaceCounting(out, rule.re, rule.name, rule.to, hits);
-  // Specific contexts keep their classifications; the widened assignment heuristic handles the remaining values.
-  out = redactPatterns(out, hits, true);
-  return { text: out, hits };
+    const hits = new Map();
+    if (typeof text !== 'string' || !text)
+        return { text, hits };
+    for (const root of repoRoots)
+        learnStackSecrets(root);
+    const resolved = redactResolvedSecrets(text);
+    if (resolved !== text)
+        hits.set('resolved-secret', 1);
+    let out = replaceCounting(resolved, PEM_BLOCK, PEM_RULE, (_m, kind) => `[redacted:pem ${kind}]`, hits);
+    for (const value of secretValues)
+        if (out.includes(value)) {
+            hits.set('stack-secret', (hits.get('stack-secret') ?? 0) + 1);
+            out = out.split(value).join('[redacted:stack-secret]');
+        }
+    out = redactPatterns(out, hits, false);
+    const declared = declaredNameRule();
+    if (declared)
+        out = replaceCounting(out, declared, 'declared-secret-name', (_m, a, b) => `${a}${b}${MARK}`, hits);
+    for (const rule of RULES)
+        out = replaceCounting(out, rule.re, rule.name, rule.to, hits);
+    // Specific contexts keep their classifications; the widened assignment heuristic handles the remaining values.
+    out = redactPatterns(out, hits, true);
+    return { text: out, hits };
 }
-
-/** `text` with every secret value blanked. */
 export function redactText(text, options = {}) { return redactTracked(text, options).text; }
-
 /** The rules that still find a secret in `text` after redaction ran: [{rule, count}], never the matched text. */
 export function survivingSecrets(text, options = {}) { return [...redactTracked(text, options).hits].map(([rule, count]) => ({ rule, count })); }
-
-/** A path that is a secret by being one (an env file, a key file, .secrets/): blanked, its rule named. */
 export function redactPath(p) {
-  if (typeof p !== 'string') return p;
-  const slashed = p.replaceAll('\\', '/');
-  const rule = FORBIDDEN_FILES.find((r) => r.test(slashed));
-  return rule ? `[redacted:${rule.name}]` : redactText(p);
+    if (typeof p !== 'string')
+        return p;
+    const slashed = p.replaceAll('\\', '/');
+    const rule = FORBIDDEN_FILES.find((r) => r.test(slashed));
+    return rule ? `[redacted:${rule.name}]` : redactText(p);
 }
-
 /** A deep copy of `value` with secret-named keys blanked and every string redacted. */
 export function redactData(value, key = null, depth = 0) {
-  if (depth > 8) return '[depth]';
-  if (key && SECRET_KEY.test(key) && value != null && typeof value !== 'object' && typeof value !== 'boolean') return MARK;
-  if (typeof value === 'string') return /(?:path|ref|file)$/i.test(key ?? '') ? redactPath(value) : redactText(value);
-  if (Array.isArray(value)) return value.map((v) => redactData(v, null, depth + 1));
-  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactData(v, k, depth + 1)]));
-  return value;
+    if (depth > 8)
+        return '[depth]';
+    if (key && SECRET_KEY.test(key) && value != null && typeof value !== 'object' && typeof value !== 'boolean')
+        return MARK;
+    if (typeof value === 'string')
+        return /(?:path|ref|file)$/i.test(key ?? '') ? redactPath(value) : redactText(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactData(v, null, depth + 1));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactData(v, k, depth + 1)]));
+    return value;
 }
-
 // -------------------------------------------------------------------------------------------- bytes
 const TEXT_MEDIA = new RegExp([
-  String.raw`^text\/`,
-  String.raw`|[/+](?:json|xml|yaml|x-yaml|javascript|x-ndjson|x-diff|x-patch|csv|sql|x-sh)\b`,
-  String.raw`|^application\/(?:json|xml|yaml|javascript|x-ndjson|x-diff|x-patch|sql)$`,
+    String.raw `^text\/`,
+    String.raw `|[/+](?:json|xml|yaml|x-yaml|javascript|x-ndjson|x-diff|x-patch|csv|sql|x-sh)\b`,
+    String.raw `|^application\/(?:json|xml|yaml|javascript|x-ndjson|x-diff|x-patch|sql)$`,
 ].join(''), 'i');
-
 /** True for media types whose bytes are text the filter can read. */
 export const isTextMedia = (mediaType) => TEXT_MEDIA.test(String(mediaType ?? ''));
-
 /** The supported text encoding selected by a byte-order mark. */
 export function textEncodingOf(bytes) {
-  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) return 'utf-16le';
-  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return 'utf-16be';
-  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return 'utf-8-bom';
-  return 'utf-8';
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe)
+        return 'utf-16le';
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff)
+        return 'utf-16be';
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        return 'utf-8-bom';
+    return 'utf-8';
 }
-
 /** Decode supported text without accepting malformed bytes as sanitized evidence. */
 export function decodeText(bytes) {
-  const encoding = textEncodingOf(bytes);
-  return new TextDecoder(encoding === 'utf-8-bom' ? 'utf-8' : encoding, { fatal: true }).decode(bytes);
+    const encoding = textEncodingOf(bytes);
+    return new TextDecoder(encoding === 'utf-8-bom' ? 'utf-8' : encoding, { fatal: true }).decode(bytes);
 }
-
 /**
  * Bytes ready for a blob put: text bytes redacted ({redaction:'v1'}), anything else untouched
  * ({redaction:'binary'}). The blob sha is then taken over the returned bytes.
  */
 export function redactBytes(bytes, mediaType, { repoRoots = [] } = {}) {
-  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
-  if (!isTextMedia(mediaType)) return { bytes: buf, redaction: 'binary' };
-  const text = decodeText(buf);
-  const clean = redactText(text, { repoRoots });
-  return { bytes: Buffer.from(clean, 'utf8'), redaction: REDACTION_VERSION };
+    const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+    if (!isTextMedia(mediaType))
+        return { bytes: buf, redaction: 'binary' };
+    const text = decodeText(buf);
+    const clean = redactText(text, { repoRoots });
+    return { bytes: Buffer.from(clean, 'utf8'), redaction: REDACTION_VERSION };
 }

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

@@ -0,0 +1,2 @@
+/** `text` with every regular-expression metacharacter escaped, so it matches itself literally. */
+export declare const escapeRegExp: (text: unknown) => string;

package/runtime/scripts/lib/regex.mjs

@@ -1,4 +1,3 @@
 // regex.mjs - building a RegExp from text.
-
 /** `text` with every regular-expression metacharacter escaped, so it matches itself literally. */
-export const escapeRegExp = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+export const escapeRegExp = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);

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

@@ -0,0 +1,32 @@
+export { tempRoot } from '../../engine/temp-root.mjs';
+export { starciLocalRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
+/** The name of the Work records directory inside a product tree. */
+export declare const WORK_DIR_NAME = ".starciwork";
+/** The directory a command was started in: `io.cwd` when the caller injects one, else the process working directory. A default for flags only. */
+export declare const invocationDir: (io?: {
+    cwd?: string;
+} | undefined) => string;
+/** The trees (workflow tree, main checkout) a product's records may live in. */
+export interface TreeOptions {
+    tree?: string | null;
+    repo?: string | null;
+}
+/** The trees and the Work directory name a Work lookup resolves against. */
+export interface WorkDirOptions extends TreeOptions {
+    workDirName?: string;
+}
+/** The distinct, resolved trees that may hold a product's records, in precedence order: the workflow tree, then the main checkout. */
+export declare const treesInOrder: ({ tree, repo }?: TreeOptions) => string[];
+/** The Work directories of those trees, in the same order. */
+export declare const workDirsInOrder: ({ tree, repo, workDirName }?: WorkDirOptions) => string[];
+/**
+ * The first Work directory (workflow tree first, then the main checkout) that `holds` accepts, else the main checkout's own (the
+ * path a refusal names), else the tree's when there is no main checkout.
+ */
+export declare function workDirHolding(holds: (dir: string) => boolean, { tree, repo, workDirName }?: WorkDirOptions): string | null;
+/** The file of a Work record (`rel` under the Work directory) from the first tree that has it, else the main checkout's path. */
+export declare function workRecordPath(rel: unknown, { tree, repo, workDirName, exists }?: WorkDirOptions & {
+    exists?: (file: string) => boolean;
+}): string;
+/** The directories a tool is looked up from: the caller's (the tree the work happens in, then the project) first, the runtime's own install last. */
+export declare const toolSearchDirs: (dirs: readonly (string | null | undefined)[], runtime?: string) => string[];

package/runtime/scripts/lib/roots.mjs

@@ -18,40 +18,30 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
-
 export { tempRoot } from '../../engine/temp-root.mjs';
 export { starciLocalRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
-
 /** The runtime tree this code runs from. */
 const runtimeTree = skillRoot;
-
-
 /** The name of the Work records directory inside a product tree. */
 export const WORK_DIR_NAME = '.starciwork';
-
 /** The directory a command was started in: `io.cwd` when the caller injects one, else the process working directory. A default for flags only. */
 export const invocationDir = (io = undefined) => path.resolve(io?.cwd ?? process.cwd());
-
 /** The distinct, resolved trees that may hold a product's records, in precedence order: the workflow tree, then the main checkout. */
-export const treesInOrder = ({ tree = null, repo = null } = {}) => [...new Set([tree, repo].filter(Boolean).map((dir) => path.resolve(dir)))];
-
+export const treesInOrder = ({ tree = null, repo = null } = {}) => [...new Set([tree, repo].filter((dir) => Boolean(dir)).map((dir) => path.resolve(dir)))];
 /** The Work directories of those trees, in the same order. */
 export const workDirsInOrder = ({ tree = null, repo = null, workDirName = WORK_DIR_NAME } = {}) => treesInOrder({ tree, repo }).map((dir) => path.join(dir, workDirName));
-
 /**
  * The first Work directory (workflow tree first, then the main checkout) that `holds` accepts, else the main checkout's own (the
  * path a refusal names), else the tree's when there is no main checkout.
  */
 export function workDirHolding(holds, { tree = null, repo = null, workDirName = WORK_DIR_NAME } = {}) {
-  const dirs = workDirsInOrder({ tree, repo, workDirName });
-  return dirs.find((dir) => holds(dir)) ?? (repo ? path.join(path.resolve(repo), workDirName) : (dirs[0] ?? null));
+    const dirs = workDirsInOrder({ tree, repo, workDirName });
+    return dirs.find((dir) => holds(dir)) ?? (repo ? path.join(path.resolve(repo), workDirName) : (dirs[0] ?? null));
 }
-
 /** The file of a Work record (`rel` under the Work directory) from the first tree that has it, else the main checkout's path. */
 export function workRecordPath(rel, { tree = null, repo = null, workDirName = WORK_DIR_NAME, exists = fs.existsSync } = {}) {
-  const parts = String(rel).split('/');
-  return path.join(workDirHolding((dir) => exists(path.join(dir, ...parts)), { tree, repo, workDirName }) ?? '', ...parts);
+    const parts = String(rel).split('/');
+    return path.join(workDirHolding((dir) => exists(path.join(dir, ...parts)), { tree, repo, workDirName }) ?? '', ...parts);
 }
-
 /** The directories a tool is looked up from: the caller's (the tree the work happens in, then the project) first, the runtime's own install last. */
 export const toolSearchDirs = (dirs, runtime = runtimeTree) => [...dirs.filter(Boolean), runtime].filter(Boolean);

package/runtime/scripts/lib/runtime-example.d.mts

@@ -0,0 +1 @@
+export declare function isRuntimeExampleApp(repoRoot: string): boolean;

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

@@ -1,13 +1,15 @@
 // 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;
-  }
+    if (path.basename(path.dirname(repoRoot)) !== 'examples')
+        return false;
+    try {
+        // reason: hfs.json is parsed from disk; only `kind` is read.
+        const runtime = JSON.parse(fs.readFileSync(path.resolve(repoRoot, '..', '..', 'hfs.json'), 'utf8'));
+        return runtime.kind === 'runtime';
+    }
+    catch {
+        return false;
+    }
 }

package/runtime/scripts/lib/same-text.d.mts

@@ -0,0 +1,2 @@
+/** True when both texts exist and are equal once CRLF is folded to LF and trailing whitespace at the end is dropped. */
+export declare const sameText: (a: string | null, b: string | null) => boolean;

package/runtime/scripts/lib/same-text.mjs

@@ -1,5 +1,4 @@
 // same-text.mjs - text equality that ignores the line-ending form and a trailing blank tail (a git runner may trim stdout, a work tree may
 // carry CRLF): the one comparison the database rules use for a committed file against its base or against a regenerated one.
-
 /** True when both texts exist and are equal once CRLF is folded to LF and trailing whitespace at the end is dropped. */
 export const sameText = (a, b) => a !== null && b !== null && a.replaceAll('\r\n', '\n').trimEnd() === b.replaceAll('\r\n', '\n').trimEnd();

package/runtime/scripts/lib/sealed-member.d.mts

@@ -0,0 +1,16 @@
+/** The suffix of a member, and of a legacy one. */
+export declare const MEMBER_SUFFIX = ".enc.yaml";
+export declare const LEGACY_SUFFIX = ".enc";
+/** A sealed member's file name (either suffix), as a pattern for a name or the tail of a path. */
+export declare const SEALED_NAME: RegExp;
+/** True for the file name of a sealed member, current or legacy. */
+export declare const isSealedName: (name: string) => boolean;
+/** True for the file name of a legacy (dotenv `.enc`) member. */
+export declare const isLegacyName: (name: string) => boolean;
+/** The member a sealed file name holds (`sepay.enc.yaml` and `sepay.enc` are both `sepay`). */
+export declare const memberOfName: (name: string) => string;
+/**
+ * The file of member `slug` in `directory`: the existing `.enc.yaml`, else the existing legacy `.enc`, else the `.enc.yaml` a new
+ * member is created as. Both present is refused: one member has one file.
+ */
+export declare function memberFile(directory: string, slug: string): string;

package/runtime/scripts/lib/sealed-member.mjs

@@ -4,33 +4,28 @@
 // folder names, lists and resolves members through this module.
 import fs from 'node:fs';
 import path from 'node:path';
-
 /** The suffix of a member, and of a legacy one. */
 export const MEMBER_SUFFIX = '.enc.yaml';
 export const LEGACY_SUFFIX = '.enc';
-
 /** A sealed member's file name (either suffix), as a pattern for a name or the tail of a path. */
 export const SEALED_NAME = /\.enc(?:\.yaml)?$/u;
-
 /** True for the file name of a sealed member, current or legacy. */
 export const isSealedName = (name) => SEALED_NAME.test(name);
-
 /** True for the file name of a legacy (dotenv `.enc`) member. */
 export const isLegacyName = (name) => name.endsWith(LEGACY_SUFFIX);
-
 /** The member a sealed file name holds (`sepay.enc.yaml` and `sepay.enc` are both `sepay`). */
 export const memberOfName = (name) => name.replace(SEALED_NAME, '');
-
 /**
  * The file of member `slug` in `directory`: the existing `.enc.yaml`, else the existing legacy `.enc`, else the `.enc.yaml` a new
  * member is created as. Both present is refused: one member has one file.
  */
 export function memberFile(directory, slug) {
-  const current = path.join(directory, `${slug}${MEMBER_SUFFIX}`);
-  const legacy = path.join(directory, `${slug}${LEGACY_SUFFIX}`);
-  const hasCurrent = fs.existsSync(current);
-  if (hasCurrent && fs.existsSync(legacy))
-    throw new Error(`${slug} is sealed twice (${slug}${MEMBER_SUFFIX} and ${slug}${LEGACY_SUFFIX}); remove the one migrate replaced`);
-  if (hasCurrent) return current;
-  return fs.existsSync(legacy) ? legacy : current;
+    const current = path.join(directory, `${slug}${MEMBER_SUFFIX}`);
+    const legacy = path.join(directory, `${slug}${LEGACY_SUFFIX}`);
+    const hasCurrent = fs.existsSync(current);
+    if (hasCurrent && fs.existsSync(legacy))
+        throw new Error(`${slug} is sealed twice (${slug}${MEMBER_SUFFIX} and ${slug}${LEGACY_SUFFIX}); remove the one migrate replaced`);
+    if (hasCurrent)
+        return current;
+    return fs.existsSync(legacy) ? legacy : current;
 }

package/runtime/scripts/lib/secret-patterns.d.mts

@@ -0,0 +1,30 @@
+/** A path that is a secret by being one (an env file, a key file): its rule name and the test of a posix path. */
+export interface ForbiddenFile {
+    name: string;
+    test: (file: string) => boolean;
+}
+/** A value shape the runtime refuses to carry: its rule name, the pattern, and the exemptions of the keyword heuristic. */
+export interface SecretPattern {
+    name: string;
+    re: RegExp;
+    sourceCode?: RegExp;
+    placeholder?: RegExp;
+    skipFile?: RegExp;
+}
+export declare const FORBIDDEN_FILES: ForbiddenFile[];
+/** True when a bare variable `name` holds secret material as an identifier segment (DB_PASSWORD, dbPassword,
+ *  STORAGE_SECRET_ACCESS_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 declare const secretNameLike: (name: string) => boolean;
+export declare const SECRET_PATTERNS: SecretPattern[];
+/** The strict secret-shape judgement used by Work custody, including uppercase keyword-assigned credentials. */
+export declare const secretPatternHits: (file: string | null | undefined, text: string) => string[];
+/** The source judgement also admits public SCREAMING_SNAKE codes; every provider shape remains refused. */
+export declare const secretHits: (file: string | null | undefined, text: string) => string[];
+/** Whole-file secret judgement exempts only declared public badge values and preserves original line numbers and every provider shape. */
+export declare function secretHitsInFile(file: string, fullText: string, { manifestText }?: {
+    manifestText?: string | undefined;
+}): {
+    line: number;
+    pattern: string;
+}[];