@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/guards/hook-io.d.mts

@@ -0,0 +1,22 @@
+import type { Readable } from 'node:stream';
+/** The output stream a hook writes its verdict to (process.stderr or a spec's fake). */ export interface HookOutput {
+    write(text: string, callback: (error?: Error | null) => void): unknown;
+    once?(event: 'error', listener: (error: Error) => void): unknown;
+    removeListener?(event: 'error', listener: (error: Error) => void): unknown;
+} /** The one-shot input stream of a hook (process.stdin or a spec's fake). */
+export type HookInput = Readable & {
+    unref?: () => void;
+};
+export { HOOK_INPUT_LIMITS } from '../lib/hook-limits.mjs';
+/** Keep fail-open and fail-closed input diagnostics on one stderr line, including parser errors containing input. */
+export declare const hookErrorMessage: (error: unknown) => string;
+/** Flush hook output before explicit exit; false means the output deadline elapsed before the write completed. */
+export declare const writeHookOutput: (stream: HookOutput, text: string) => Promise<boolean>;
+/**
+ * Consume one EOF-delimited hook payload within a wall-clock deadline and byte budget. The stream belongs to this
+ * one-shot hook: every outcome releases its input handle and listeners. Callers choose their existing failure policy.
+ */
+export declare const readInput: (stream: HookInput, { timeoutMs, maxBytes }?: {
+    timeoutMs?: number;
+    maxBytes?: number;
+}) => Promise<string>;

package/runtime/scripts/guards/hook-io.mjs

@@ -1,76 +1,90 @@
 import { HOOK_INPUT_LIMITS } from '../lib/hook-limits.mjs';
 export { HOOK_INPUT_LIMITS } from '../lib/hook-limits.mjs';
-
 /** Keep fail-open and fail-closed input diagnostics on one stderr line, including parser errors containing input. */
 export const hookErrorMessage = (error) => String(error?.message ?? error).replace(/[\r\n\u2028\u2029]+/g, ' ');
-
 /** Flush hook output before explicit exit; false means the output deadline elapsed before the write completed. */
 export const writeHookOutput = (stream, text) => new Promise((resolve, reject) => {
-  let settled = false;
-  const onError = (error) => done(error);
-  const done = (error) => {
-    if (settled) return;
-    settled = true;
-    clearTimeout(timer);
-    // A Writable reports callback failure before emitting its error event. Keep the listener through that turn.
-    if (error) setImmediate(() => stream.removeListener?.('error', onError));
-    else stream.removeListener?.('error', onError);
-    if (error) reject(error);
-    else resolve(true);
-  };
-  const timer = setTimeout(() => {
-    settled = true;
-    stream.removeListener?.('error', onError);
-    resolve(false);
-  }, HOOK_INPUT_LIMITS.outputTimeoutMs);
-  stream.once?.('error', onError);
-  try { stream.write(text, done); }
-  catch (error) { done(error); }
+    let settled = false;
+    const onError = (error) => done(error);
+    const done = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        // A Writable reports callback failure before emitting its error event. Keep the listener through that turn.
+        if (error)
+            setImmediate(() => stream.removeListener?.('error', onError));
+        else
+            stream.removeListener?.('error', onError);
+        if (error)
+            reject(error);
+        else
+            resolve(true);
+    };
+    const timer = setTimeout(() => {
+        settled = true;
+        stream.removeListener?.('error', onError);
+        resolve(false);
+    }, HOOK_INPUT_LIMITS.outputTimeoutMs);
+    stream.once?.('error', onError);
+    try {
+        stream.write(text, done);
+    }
+    catch (error) {
+        done(error);
+    }
 });
-
 /**
  * Consume one EOF-delimited hook payload within a wall-clock deadline and byte budget. The stream belongs to this
  * one-shot hook: every outcome releases its input handle and listeners. Callers choose their existing failure policy.
  */
 export const readInput = (stream, { timeoutMs = HOOK_INPUT_LIMITS.minInputWindowMs, maxBytes = HOOK_INPUT_LIMITS.maxBytes } = {}) => new Promise((resolve, reject) => {
-  const chunks = [];
-  const deadline = performance.now() + timeoutMs;
-  const deadlineError = () => Object.assign(new Error(`hook stdin deadline exceeded (${timeoutMs} ms)`), { kind: 'deadline' });
-  let bytes = 0;
-  let settled = false;
-  let closeCheck;
-  const finish = (error) => {
-    if (settled) return;
-    if (!error && performance.now() >= deadline) error = deadlineError();
-    settled = true;
-    clearTimeout(timer);
-    clearImmediate(closeCheck);
-    stream.removeListener('data', onData);
-    stream.removeListener('end', onEnd);
-    stream.removeListener('error', onError);
-    stream.removeListener('close', onClose);
-    stream.pause();
-    stream.unref?.();
-    stream.destroy();
-    if (error) reject(error);
-    else resolve(Buffer.concat(chunks, bytes).toString('utf8'));
-  };
-  const onData = (chunk) => {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    bytes += buffer.length;
-    if (bytes > maxBytes) finish(Object.assign(new Error(`hook stdin exceeds ${maxBytes} bytes; split the tool input`), { kind: 'too-large' }));
-    else chunks.push(buffer);
-  };
-  const onEnd = () => finish();
-  const onError = (error) => finish(error);
-  const onClose = () => finish(stream.errored ?? new Error('hook stdin closed before EOF'));
-  // Keep the timer referenced so an idle pipe still reaches the caller's bound-session refusal.
-  const timer = setTimeout(() => finish(deadlineError()), timeoutMs);
-  stream.on('data', onData);
-  stream.once('end', onEnd);
-  stream.once('error', onError);
-  stream.once('close', onClose);
-  // destroy(error) marks a stream closed before its queued error event; let that event reach our listener first.
-  if (stream.destroyed) closeCheck = setImmediate(onClose);
-  else if (stream.readableEnded) onEnd();
+    const chunks = [];
+    const deadline = performance.now() + timeoutMs;
+    const deadlineError = () => Object.assign(new Error(`hook stdin deadline exceeded (${timeoutMs} ms)`), { kind: 'deadline' });
+    let bytes = 0;
+    let settled = false;
+    let closeCheck;
+    const finish = (error) => {
+        if (settled)
+            return;
+        if (!error && performance.now() >= deadline)
+            error = deadlineError();
+        settled = true;
+        clearTimeout(timer);
+        clearImmediate(closeCheck);
+        stream.removeListener('data', onData);
+        stream.removeListener('end', onEnd);
+        stream.removeListener('error', onError);
+        stream.removeListener('close', onClose);
+        stream.pause();
+        stream.unref?.();
+        stream.destroy();
+        if (error)
+            reject(error);
+        else
+            resolve(Buffer.concat(chunks, bytes).toString('utf8'));
+    };
+    const onData = (chunk) => {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > maxBytes)
+            finish(Object.assign(new Error(`hook stdin exceeds ${maxBytes} bytes; split the tool input`), { kind: 'too-large' }));
+        else
+            chunks.push(buffer);
+    };
+    const onEnd = () => finish();
+    const onError = (error) => finish(error);
+    const onClose = () => finish(stream.errored ?? new Error('hook stdin closed before EOF'));
+    // Keep the timer referenced so an idle pipe still reaches the caller's bound-session refusal.
+    const timer = setTimeout(() => finish(deadlineError()), timeoutMs);
+    stream.on('data', onData);
+    stream.once('end', onEnd);
+    stream.once('error', onError);
+    stream.once('close', onClose);
+    // destroy(error) marks a stream closed before its queued error event; let that event reach our listener first.
+    if (stream.destroyed)
+        closeCheck = setImmediate(onClose);
+    else if (stream.readableEnded)
+        onEnd();
 });

package/runtime/scripts/guards/push-scan.d.mts

@@ -0,0 +1,31 @@
+/** One finding of the scan: the file, line (null for a whole-file rule) and pattern name - never the value. */
+export interface ScanFinding {
+    file: string | null;
+    line: number | null;
+    pattern: string;
+}
+/** scanRange's answer. */
+export interface ScanRangeResult {
+    ok: boolean;
+    error?: string;
+    findings: ScanFinding[];
+    files?: string[];
+}
+/**
+ * Scan a unified diff (added lines only) and its file list. Returns [{file, line, pattern}] - never the value.
+ * `files` are the changed paths (status A/M/R); deleted paths are not scanned.
+ */
+export declare function scanDiff({ diff, files }?: {
+    diff?: string;
+    files?: string[];
+}): ScanFinding[];
+export declare const scanHint: (findings?: Array<{
+    pattern: string;
+}>) => string | null;
+/** Scan the range `from..to` of `cwd`: {ok, findings, files}. The diff is written to a temp file and read
+ *  in chunks, never held whole in a spawn buffer (a 64 MB overflow read as `scan failed: git diff failed`). */
+export declare function scanRange({ cwd, from, to }: {
+    cwd: string;
+    from: string;
+    to: string;
+}): ScanRangeResult;

package/runtime/scripts/guards/push-scan.mjs

@@ -11,24 +11,22 @@ import { FORBIDDEN_FILES, secretHits, secretHitsInFile } from '../lib/secret-pat
 import { slash } from '../lib/path-key.mjs';
 import { isSopsEnvelope, setCommand } from '../lib/sops-envelope.mjs';
 import { forEachFileLine } from '../lib/read-text.mjs';
-
 const SCAN_GIT = { diff: gitDiff, show: gitShow };
 /** The scan's git runner: `args[0]` names the scripts/api/git call file it runs, in `cwd`: {ok, stdout, stderr, error}. */
 function git([verb, ...args], { cwd }) {
-  const r = SCAN_GIT[verb](args, { cwd, timeout: 300_000, maxBuffer: 64 * 1024 * 1024 });
-  return { ok: r.status === 0, stdout: String(r.stdout ?? '').trim(), stderr: String(r.stderr ?? '').trim(), error: r.error?.message ?? null };
+    const r = SCAN_GIT[verb](args, { cwd, timeout: 300_000, maxBuffer: 64 * 1024 * 1024 });
+    return { ok: r.status === 0, stdout: String(r.stdout ?? '').trim(), stderr: String(r.stderr ?? '').trim(), error: r.error?.message ?? null };
 }
-
 /**
  * Scan a unified diff (added lines only) and its file list. Returns [{file, line, pattern}] - never the value.
  * `files` are the changed paths (status A/M/R); deleted paths are not scanned.
  */
 export function scanDiff({ diff = '', files = [] } = {}) {
-  const scanner = diffScanner(files);
-  for (const raw of String(diff).split(/\r?\n/)) scanner.line(raw);
-  return scanner.findings;
+    const scanner = diffScanner(files);
+    for (const raw of String(diff).split(/\r?\n/))
+        scanner.line(raw);
+    return scanner.findings;
 }
-
 /** scanDiff one line at a time: feed each diff line to `line(raw)`; `findings` accumulates.
  *  A `*.enc` file is held back until its diff ends and passes only when it is a sops-encrypted file with no
  *  plaintext value (scripts/lib/sops-envelope.mjs isSopsEnvelope) - judged on the whole file at the pushed commit
@@ -36,93 +34,108 @@ export function scanDiff({ diff = '', files = [] } = {}) {
  *  on its added lines. Anything else in a `.enc` file is scanned like any other file, and a `.enc` under
  *  `.starcistacks/` that is not a sops envelope refuses the push by itself (sops-not-envelope). */
 function diffScanner(files = [], { encText = null, keepHit = null } = {}) {
-  const findings = [];
-  for (const file of files) for (const rule of FORBIDDEN_FILES) if (rule.test(slash(file))) findings.push({ file, line: null, pattern: rule.name });
-  let file = null, line = 0, enc = null;
-  const flushEnc = () => {
-    if (enc && !isSopsEnvelope((encText ? encText(enc.file) : null) ?? enc.added.join('\n'))) {
-      findings.push(...enc.findings);
-      // .starcistacks holds sops twins only: anything else there (a JSON key the value rules cannot see, a
-      // plaintext value next to the sops block) refuses the push by itself.
-      if (/(^|\/)\.starcistacks\//i.test(enc.file)) findings.push({ file: enc.file, line: enc.line, pattern: 'sops-not-envelope' });
-    }
-    enc = null;
-  };
-  return {
-    get findings() { flushEnc(); return findings; },
-    line(raw) {
-      if (raw.startsWith('+++ ')) {
-        flushEnc();
-        file = raw.slice(4).replace(/^b\//, '');
-        if (/\.enc(?:\.yaml)?$/i.test(file)) enc = { file, line: null, added: [], findings: [] };
-        return;
-      }
-      const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
-      if (hunk) { line = Number(hunk[1]); return; }
-      if (raw.startsWith('+')) {
-        const text = raw.slice(1);
-        if (enc) { enc.added.push(text); enc.line ??= line; }
-        (enc ? enc.findings : findings).push(...addedLineFindings(file, line, text, keepHit));
-        line += 1;
-      } else if (!raw.startsWith('-')) line += 1;
-    },
-  };
+    const findings = [];
+    for (const file of files)
+        for (const rule of FORBIDDEN_FILES)
+            if (rule.test(slash(file)))
+                findings.push({ file, line: null, pattern: rule.name });
+    let file = null, line = 0, enc = null;
+    const flushEnc = () => {
+        if (enc && !isSopsEnvelope((encText ? encText(enc.file) : null) ?? enc.added.join('\n'))) {
+            findings.push(...enc.findings);
+            // .starcistacks holds sops twins only: anything else there (a JSON key the value rules cannot see, a
+            // plaintext value next to the sops block) refuses the push by itself.
+            if (/(^|\/)\.starcistacks\//i.test(enc.file))
+                findings.push({ file: enc.file, line: enc.line, pattern: 'sops-not-envelope' });
+        }
+        enc = null;
+    };
+    return {
+        get findings() { flushEnc(); return findings; },
+        line(raw) {
+            if (raw.startsWith('+++ ')) {
+                flushEnc();
+                file = raw.slice(4).replace(/^b\//, '');
+                if (/\.enc(?:\.yaml)?$/i.test(file))
+                    enc = { file, line: null, added: [], findings: [] };
+                return;
+            }
+            const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+            if (hunk) {
+                line = Number(hunk[1]);
+                return;
+            }
+            if (raw.startsWith('+')) {
+                const text = raw.slice(1);
+                if (enc) {
+                    enc.added.push(text);
+                    enc.line ??= line;
+                }
+                (enc ? enc.findings : findings).push(...addedLineFindings(file, line, text, keepHit));
+                line += 1;
+            }
+            else if (!raw.startsWith('-'))
+                line += 1;
+        },
+    };
 }
-
 /** Every added line is scanned first; an optional whole-file judgement can then retain or drop its hits. */
 function addedLineFindings(file, line, text, keepHit) {
-  const patterns = secretHits(file?.replace(/\.tpl$/, ''), text);
-  if (!patterns.length || (keepHit && !keepHit(file, line))) return [];
-  return patterns.map(pattern => ({ file, line, pattern }));
+    const patterns = secretHits(file?.replace(/\.tpl$/, ''), text);
+    if (!patterns.length || (keepHit && !keepHit(file ?? '', line)))
+        return [];
+    return patterns.map((pattern) => ({ file, line, pattern }));
 }
-
 /** Only badge-bearing paths use cached post-images; an unreadable post-image keeps every diff hit. */
 function badgeHitFilter(readText) {
-  const linesByFile = new Map();
-  return (file, line) => {
-    if (!/(?:^|\/)(?:README\.md|\.starcistacks\/application-stacks\.yaml)$/.test(file)) return true;
-    if (!linesByFile.has(file)) {
-      const text = readText(file);
-      const manifestText = /(?:^|\/)README\.md$/.test(file) ? readText(path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) ?? undefined : undefined;
-      linesByFile.set(file, text === null ? null : new Set(secretHitsInFile(file, text, { manifestText }).map(hit => hit.line)));
-    }
-    const lines = linesByFile.get(file);
-    return lines === null || lines.has(line);
-  };
+    const linesByFile = new Map();
+    return (file, line) => {
+        if (!/(?:^|\/)(?:README\.md|\.starcistacks\/application-stacks\.yaml)$/.test(file))
+            return true;
+        if (!linesByFile.has(file)) {
+            const text = readText(file);
+            const manifestText = /(?:^|\/)README\.md$/.test(file) ? readText(path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) ?? undefined : undefined;
+            linesByFile.set(file, text === null ? null : new Set(secretHitsInFile(file, text, { manifestText }).map((hit) => hit.line)));
+        }
+        const lines = linesByFile.get(file);
+        return lines === null || (lines?.has(line) ?? false);
+    };
 }
-
 /** Read each committed post-image once; a NUL commit prefix protects its leading whitespace from the git runner's trim. */
 function postImageReader(cwd, to) {
-  const texts = new Map();
-  return file => {
-    if (!texts.has(file)) {
-      const result = git(['show', '--format=%x00', '--no-patch', to, `${to}:${file}`], { cwd });
-      const readable = result.ok && result.stdout.startsWith('\0\n');
-      texts.set(file, readable ? result.stdout.slice(2) : null);
-    }
-    return texts.get(file);
-  };
+    const texts = new Map();
+    return (file) => {
+        if (!texts.has(file)) {
+            const result = git(['show', '--format=%x00', '--no-patch', to, `${to}:${file}`], { cwd });
+            const readable = result.ok && result.stdout.startsWith('\0\n');
+            texts.set(file, readable ? result.stdout.slice(2) : null);
+        }
+        return texts.get(file) ?? null;
+    };
 }
-
 /** The one fix a refused plaintext test credential gets (owner ruling push-scan-test-secrets-encrypted): the product
  *  repository's own .starcistacks + sops convention, or a value generated per run. */
 const TEST_SECRET_HINT = `move it to .starcistacks/<stack>/secrets/test/<name> and encrypt it with the repository's own command (${setCommand('<name>', '<stack>')}; commit only the .enc, read it with testSecret() from scripts/uat/test-secret.mjs) or generate it per run; never a plaintext literal`;
 export const scanHint = (findings = []) => (findings.some((f) => f.pattern === 'assigned-secret') ? TEST_SECRET_HINT : null);
-
 /** Scan the range `from..to` of `cwd`: {ok, findings, files}. The diff is written to a temp file and read
  *  in chunks, never held whole in a spawn buffer (a 64 MB overflow read as `scan failed: git diff failed`). */
 export function scanRange({ cwd, from, to }) {
-  const names = git(['diff', '--name-only', '--diff-filter=ACMR', `${from}..${to}`], { cwd });
-  if (!names.ok) return { ok: false, error: names.stderr || names.error || 'git diff failed', findings: [] };
-  const files = names.stdout.split(/\r?\n/).filter(Boolean);
-  const dir = makeTempDir('starci-push-scan-');
-  const out = path.join(dir, 'range.diff');
-  try {
-    const diff = git(['diff', '--no-color', '--unified=0', '--diff-filter=ACMR', `--output=${out}`, `${from}..${to}`], { cwd });
-    if (!diff.ok) return { ok: false, error: diff.stderr || diff.error || 'git diff failed', findings: [] };
-    const encText = (f) => { const r = git(['show', `${to}:${f}`], { cwd }); return r.ok ? r.stdout : null; };
-    const scanner = diffScanner(files, { encText, keepHit: badgeHitFilter(postImageReader(cwd, to)) });
-    forEachFileLine(out, (l) => scanner.line(l));
-    return { ok: scanner.findings.length === 0, findings: scanner.findings, files };
-  } finally { safeRemove(dir, { hold: artifactHoldReason }); }
+    const names = git(['diff', '--name-only', '--diff-filter=ACMR', `${from}..${to}`], { cwd });
+    if (!names.ok)
+        return { ok: false, error: names.stderr || names.error || 'git diff failed', findings: [] };
+    const files = names.stdout.split(/\r?\n/).filter(Boolean);
+    const dir = makeTempDir('starci-push-scan-');
+    const out = path.join(dir, 'range.diff');
+    try {
+        const diff = git(['diff', '--no-color', '--unified=0', '--diff-filter=ACMR', `--output=${out}`, `${from}..${to}`], { cwd });
+        if (!diff.ok)
+            return { ok: false, error: diff.stderr || diff.error || 'git diff failed', findings: [] };
+        const encText = (f) => { const r = git(['show', `${to}:${f}`], { cwd }); return r.ok ? r.stdout : null; };
+        const scanner = diffScanner(files, { encText, keepHit: badgeHitFilter(postImageReader(cwd, to)) });
+        forEachFileLine(out, (l) => scanner.line(l));
+        return { ok: scanner.findings.length === 0, findings: scanner.findings, files };
+    }
+    finally {
+        safeRemove(dir, { hold: artifactHoldReason });
+    }
 }

package/runtime/scripts/guards/release-push-gate.d.mts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { type ScanRangeResult } from './push-scan.mjs';
+import { type HookInput, type HookOutput } from './hook-io.mjs';
+/** The secret scan of a range (a spec injects its own). */
+export type RangeScan = (range: {
+    cwd: string;
+    from: string;
+    to: string;
+}) => ScanRangeResult;
+export declare const REFUSAL_CODE = "RIGHTS_PUSH_NOT_RELEASE";
+/** The refusal lines for the pushed refs `text` (git's pre-push stdin) of the repository at `cwd`: [] when every ref may move. `scan` is the secret scan (a seam). */
+export declare function pushRefusals({ text, cwd, scan }: {
+    text: unknown;
+    cwd: string;
+    scan?: RangeScan;
+}): string[];
+/** Read a bounded Git ref list; unavailable input cannot authorize a push of main. */
+export declare function main({ stdin, stderr, cwd }?: {
+    stdin?: HookInput;
+    stderr?: HookOutput;
+    cwd?: string;
+}): Promise<number>;

package/runtime/scripts/guards/release-push-gate.mjs

@@ -13,62 +13,64 @@ import { isMain } from '../lib/is-main.mjs';
 import { invocationDir } from '../lib/roots.mjs';
 import { scanRange } from './push-scan.mjs';
 import { hookErrorMessage, readInput, writeHookOutput } from './hook-io.mjs';
-
 export const REFUSAL_CODE = 'RIGHTS_PUSH_NOT_RELEASE';
 const ZERO = /^0+$/;
 const RELEASE_TAG_REF = /^refs\/tags\/v\d/;
 /** git's empty tree: the range base of a first push, so the whole tree is scanned. */
 const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 const LISTED = 8;
-
 const parseLines = (text) => String(text ?? '').split(/\r?\n/).map((line) => line.trim().split(/\s+/)).filter((parts) => parts.length === 4)
-  .map(([localRef, localSha, remoteRef, remoteSha]) => ({ localRef, localSha, remoteRef, remoteSha }));
+    .map((parts) => ({ localRef: parts[0] ?? '', localSha: parts[1] ?? '', remoteRef: parts[2] ?? '', remoteSha: parts[3] ?? '' }));
 const refuse = (ref, why) => `${REFUSAL_CODE}: ${ref} is closed: ${why}`;
-
 /** The secret-scan refusal of the pushed range, or null when it is clean. A finding names the file, line and pattern, never the value. */
 function scanRefusal(cwd, { localSha, remoteSha }, scan) {
-  const result = scan({ cwd, from: ZERO.test(remoteSha) ? EMPTY_TREE : remoteSha, to: localSha });
-  if (result.ok) return null;
-  if (result.error) return `the secret scan of the pushed range could not run (${result.error}), so it cannot be called clean`;
-  const where = (f) => [f.line ? `${f.file}:${f.line}` : f.file, f.pattern].join(' ');
-  const found = result.findings.slice(0, LISTED).map(where).join('; ');
-  const more = result.findings.length > LISTED ? '; ...' : '';
-  return `the secret scan found ${result.findings.length} candidate(s) in the pushed range: ${found}${more} (remove or encrypt them, then commit again)`;
+    const result = scan({ cwd, from: ZERO.test(remoteSha) ? EMPTY_TREE : remoteSha, to: localSha });
+    if (result.ok)
+        return null;
+    if (result.error)
+        return `the secret scan of the pushed range could not run (${result.error}), so it cannot be called clean`;
+    const where = (f) => [f.line ? `${f.file}:${f.line}` : f.file, f.pattern].join(' ');
+    const found = result.findings.slice(0, LISTED).map(where).join('; ');
+    const more = result.findings.length > LISTED ? '; ...' : '';
+    return `the secret scan found ${result.findings.length} candidate(s) in the pushed range: ${found}${more} (remove or encrypt them, then commit again)`;
 }
-
 function mainRefusal(cwd, { remoteRef, localSha, remoteSha }, scan) {
-  if (ZERO.test(localSha)) return refuse(remoteRef, 'a push never deletes the runtime main');
-  if (!ZERO.test(remoteSha) && !isAncestor(cwd, remoteSha, localSha)) return refuse(remoteRef, 'it is not a fast-forward of the remote main (fetch it first; a force push rewrites main)');
-  const scanned = scanRefusal(cwd, { localSha, remoteSha }, scan);
-  return scanned ? refuse(remoteRef, scanned) : null;
+    if (ZERO.test(localSha))
+        return refuse(remoteRef, 'a push never deletes the runtime main');
+    if (!ZERO.test(remoteSha) && !isAncestor(cwd, remoteSha, localSha))
+        return refuse(remoteRef, 'it is not a fast-forward of the remote main (fetch it first; a force push rewrites main)');
+    const scanned = scanRefusal(cwd, { localSha, remoteSha }, scan);
+    return scanned ? refuse(remoteRef, scanned) : null;
 }
-
 function tagRefusal(cwd, { remoteRef, localSha }) {
-  if (ZERO.test(localSha)) return refuse(remoteRef, 'a push never deletes a release tag');
-  const kind = catFile(['-t', localSha], { cwd, timeout: 60_000 }).stdout?.trim();
-  return kind === 'tag' ? null : refuse(remoteRef, 'a release tag is annotated: its message is the release notes');
+    if (ZERO.test(localSha))
+        return refuse(remoteRef, 'a push never deletes a release tag');
+    const kind = catFile(['-t', localSha], { cwd, timeout: 60_000 }).stdout?.trim();
+    return kind === 'tag' ? null : refuse(remoteRef, 'a release tag is annotated: its message is the release notes');
 }
-
 /** The refusal lines for the pushed refs `text` (git's pre-push stdin) of the repository at `cwd`: [] when every ref may move. `scan` is the secret scan (a seam). */
 export function pushRefusals({ text, cwd, scan = scanRange }) {
-  return parseLines(text).flatMap((ref) => {
-    let line = null;
-    if (ref.remoteRef === 'refs/heads/main') line = mainRefusal(cwd, ref, scan);
-    else if (RELEASE_TAG_REF.test(ref.remoteRef)) line = tagRefusal(cwd, ref);
-    return line ? [line] : [];
-  });
+    return parseLines(text).flatMap((ref) => {
+        let line = null;
+        if (ref.remoteRef === 'refs/heads/main')
+            line = mainRefusal(cwd, ref, scan);
+        else if (RELEASE_TAG_REF.test(ref.remoteRef))
+            line = tagRefusal(cwd, ref);
+        return line ? [line] : [];
+    });
 }
-
 /** Read a bounded Git ref list; unavailable input cannot authorize a push of main. */
 export async function main({ stdin = process.stdin, stderr = process.stderr, cwd = invocationDir() } = {}) {
-  try {
-    const refusals = pushRefusals({ text: await readInput(stdin), cwd });
-    if (refusals.length) await writeHookOutput(stderr, `${refusals.join('\n')}\n`);
-    return refusals.length ? 1 : 0;
-  } catch (error) {
-    await writeHookOutput(stderr, `starci guard: push input error (${hookErrorMessage(error)}); refusing the push\n`);
-    return 1;
-  }
+    try {
+        const refusals = pushRefusals({ text: await readInput(stdin), cwd });
+        if (refusals.length)
+            await writeHookOutput(stderr, `${refusals.join('\n')}\n`);
+        return refusals.length ? 1 : 0;
+    }
+    catch (error) {
+        await writeHookOutput(stderr, `starci guard: push input error (${hookErrorMessage(error)}); refusing the push\n`);
+        return 1;
+    }
 }
-
-if (isMain(import.meta.url)) process.exit(await main());
+if (isMain(import.meta.url))
+    process.exit(await main());

package/runtime/scripts/hfs/allows.d.mts

@@ -0,0 +1,24 @@
+import type { Resolver } from './slots.mjs';
+/** What the slot that owns a file says about it. */
+export interface AllowsResult {
+    slot: string;
+    root: string;
+    relative: string;
+    allowed: boolean;
+    entry?: string | undefined;
+    forbiddenBy?: string | undefined;
+    allows: string[];
+}
+/** The path of `file` below the instance root of the slot that owns it. */
+export declare function relativeToRoot(file: string, root: string | undefined): string;
+/**
+ * Whether the slot that owns `file` names it in `requires` or `allows` (and does not forbid it); null when no enabled slot
+ * owns it. Unlike allowsFile it judges a slot that lists only `requires` too, so a folder closed by its slot (an app's
+ * src/) is read from the slot and never from a check's own list.
+ */
+export declare function slotAdmitsFile(resolver: Resolver, file: string): boolean | null;
+/**
+ * {slot, root, relative, allowed, entry?, forbiddenBy?} for a repository-relative file, or null when no enabled slot owns
+ * it or the slot names no `allows`. `allowed` is true when the relative path matches a `requires` or `allows` entry.
+ */
+export declare function allowsFile(resolver: Resolver, file: string): AllowsResult | null;