@starci/hfs 4.11.22 → 4.12.0

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

@@ -4,58 +4,61 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { skillRoot } from '../../engine/runtime-root.mjs';
-
 /** The package.json of `name` as resolved from `dir`, or null. */
 export const packageAt = (dir, name) => {
-  try { return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`); } catch { return null; }
+    try {
+        return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`);
+    }
+    catch {
+        return null;
+    }
 };
-
 /** This runtime's own `starci` bin (packages/cli is the only package that declares one). */
 const RUNTIME_STARCI_BIN = path.join(skillRoot, 'packages', 'cli', 'bin', 'starci.mjs');
-
 /** The `starci` bin of the starci-harness that `dir` installs (a product runs its own pinned CLI), else this runtime's own. */
 function starciBin(dir) {
-  const packageFile = packageAt(dir, 'starci-harness');
-  if (packageFile) {
-    try {
-      const { bin } = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
-      const rel = typeof bin === 'string' ? bin : bin?.starci;
-      const file = rel ? path.join(path.dirname(packageFile), rel) : null;
-      if (file && fs.existsSync(file)) return file;
-    } catch { /* an unreadable install falls back to the runtime's own CLI */ }
-  }
-  return RUNTIME_STARCI_BIN;
+    const packageFile = packageAt(dir, 'starci-harness');
+    if (packageFile) {
+        try {
+            // reason: package.json is parsed from disk; only `bin` is read.
+            const { bin } = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+            const rel = typeof bin === 'string' ? bin : bin?.starci;
+            const file = rel ? path.join(path.dirname(packageFile), rel) : null;
+            if (file && fs.existsSync(file))
+                return file;
+        }
+        catch { /* an unreadable install falls back to the runtime's own CLI */ }
+    }
+    return RUNTIME_STARCI_BIN;
 }
-
 /** The first of `names` resolvable from the first of `dirs` that has one: {name, root, packageFile, version} or null. */
 export function findPackage(dirs, names) {
-  for (const dir of dirs.filter(Boolean)) {
-    for (const name of names) {
-      const packageFile = packageAt(dir, name);
-      if (!packageFile) continue;
-      const require = createRequire(packageFile);
-      return { name, root: path.dirname(packageFile), packageFile, version: require(packageFile).version };
+    for (const dir of dirs.filter((entry) => Boolean(entry))) {
+        for (const name of names) {
+            const packageFile = packageAt(dir, name);
+            if (!packageFile)
+                continue;
+            const require = createRequire(packageFile);
+            return { name, root: path.dirname(packageFile), packageFile, version: require(packageFile).version };
+        }
     }
-  }
-  return null;
+    return null;
 }
-
 /** The CommonJS entry of a package found by findPackage. */
+// reason: a package loaded by a runtime-resolved name has no static type; each caller states the module shape it expects.
 export const requirePackage = (found) => createRequire(found.packageFile)(found.name);
-
 /** The TypeScript compiler resolvable from the first of `dirs` (an app root, then the caller's own), or null. */
 export const loadTypescript = (...dirs) => {
-  const located = findPackage(dirs, ['typescript']);
-  return located ? requirePackage(located) : null;
+    const located = findPackage(dirs, ['typescript']);
+    return located ? requirePackage(located) : null;
 };
-
 /**
  * The app's command line and the app implementation behind it: `bin` the `starci` bin of the app's installed starci-harness, else
  * this runtime's packages/cli/bin/starci.mjs (starciBin); `dir` the @starci/hfs that answers
  * `starci app` - the app's own install, else the one beside its starci-harness, else this runtime's packages/hfs.
  */
 export function hfsEntry(root) {
-  const cli = packageAt(root, 'starci-harness');
-  const manifest = packageAt(root, '@starci/hfs') ?? (cli && packageAt(path.dirname(cli), '@starci/hfs'));
-  return { dir: manifest ? path.dirname(manifest) : path.join(skillRoot, 'packages', 'hfs'), bin: starciBin(root) };
+    const cli = packageAt(root, 'starci-harness');
+    const manifest = packageAt(root, '@starci/hfs') ?? (cli && packageAt(path.dirname(cli), '@starci/hfs'));
+    return { dir: manifest ? path.dirname(manifest) : path.join(skillRoot, 'packages', 'hfs'), bin: starciBin(root) };
 }

package/runtime/scripts/lib/path-key.d.mts

@@ -0,0 +1,76 @@
+/** `p` with every backslash turned into a forward slash; null and undefined read as ''. */
+export declare const slash: (p?: unknown) => string;
+/** `text` without its trailing '/' run (a loop: a trailing-run pattern backtracks super-linearly). */
+export declare const trimTrailingSlashes: (text: string) => string;
+/** A relative path in git's spelling: forward slashes, no leading './'. */
+export declare const posixPath: (p?: unknown) => string;
+/** Whether posix `file` is `prefix` itself or under it (`file === prefix || file` starts with `prefix/`). */
+export declare const sameOrUnder: (file: string, prefix: string) => boolean;
+/** `p` case-folded where the filesystem ignores case (Windows). */
+export declare const foldCase: (p: string) => string;
+/** Whether two spellings name the same path on this host's filesystem. */
+export declare const samePath: (a: string, b: string) => boolean;
+/**
+ * A path's comparable identity: absolute, forward slashes, no trailing slash, case-folded on Windows.
+ * `fold: true` folds case on every platform (a comparison against a lowercase-stored root needs it).
+ */
+export declare const pathKey: (p: string, { fold }?: {
+    fold?: boolean;
+}) => string;
+/** `a` is `b` or under it, or the reverse: two path spellings whose trees touch. */
+export declare const pathsOverlap: (a: string, b: string) => boolean;
+/**
+ * A path-ish string in compare form, options in spelling order:
+ * `trim` blanks at the ends, `collapse` folds '//' runs to '/', `dot` drops a leading './',
+ * `glob` strips a trailing glob ('star': '*'/'**' with their slash, 'double': a '/**' only),
+ * `fold` lowercases. A trailing '/' always goes. Null reads as ''.
+ * @param {string|number|null|undefined} p
+ * @param {{trim?: boolean, collapse?: boolean, dot?: boolean, glob?: string|null, fold?: boolean}} [options]
+ */
+export declare const normPath: (p: string | number | null | undefined, { trim, collapse, dot, glob, fold }?: {
+    trim?: boolean;
+    collapse?: boolean;
+    dot?: boolean;
+    glob?: string | null;
+    fold?: boolean;
+}) => string;
+/** A work-relative path in one spelling: forward slashes, no leading ./, no trailing slash. */
+export declare const normWork: (p?: unknown) => string;
+/** `p` resolved and dereferenced (realpath where the path exists) — the canonical spelling of a checkout dir. */
+export declare const realPath: (p: string) => string;
+/** `p` with its nearest existing ancestor dereferenced and the not-yet-created rest appended: a root's canonical spelling before it exists. */
+export declare const canonicalPath: (p: string) => string;
+/** `p` resolved and case-folded where the filesystem ignores case — the Map key of an absolute path. */
+export declare const resolvedKey: (p: string) => string;
+/** Whether `a` and `b` resolve to the same path (always case-folded, so differently-cased spellings count). */
+export declare const sameResolvedPath: (a: string, b: string) => boolean;
+/**
+ * Whether `file` sits under `root`; `includeSelf` also admits the root itself. `key` normalizes
+ * both sides first (e.g. the registry's realpath-folded treeKey) when their spellings need it.
+ */
+export declare const insidePath: (root: string, file: string, { key, includeSelf }?: {
+    key?: (p: string) => string;
+    includeSelf?: boolean;
+}) => boolean;
+/**
+ * `candidate` (absolute, or relative to `base`) resolved and dereferenced, required to sit under `base` (or be it):
+ * the boundary check for a path an operator, an agent or another process hands in. `base` is canonicalised once and the
+ * candidate is judged below it, so `..` segments and links leading out are refused; returns the canonical path, or throws
+ * a PATH_OUTSIDE_BASE refusal (`label` names the argument in the message).
+ */
+export declare const containedPath: (base: string, candidate: unknown, { label }?: {
+    label?: string;
+}) => string;
+/**
+ * A path-ish value (a string or a {path} entry) in relative compare form: trimmed, forward slashes,
+ * no trailing '/**' glob or slashes, no leading './'; `fold` lowercases for a case-insensitive key.
+ */
+export declare const normRel: (p: string | {
+    path?: unknown;
+} | null | undefined, { fold }?: {
+    fold?: boolean;
+}) => string;
+/** Whether `file` equals or sits under one of `prefixes` (posix spellings; `dot` counts a '.' prefix as covering all). */
+export declare const underAny: (file: string, prefixes: readonly string[] | null | undefined, { dot }?: {
+    dot?: boolean;
+}) => boolean;

package/runtime/scripts/lib/path-key.mjs

@@ -1,21 +1,23 @@
 // path-key.mjs — spelling and comparing paths the way this host's filesystem does.
 import fs from 'node:fs';
 import path from 'node:path';
-
 const WIN = process.platform === 'win32';
-
 /** `p` with every backslash turned into a forward slash; null and undefined read as ''. */
 export const slash = (p) => String(p ?? '').replaceAll('\\', '/');
 /** `text` without its trailing '/' run (a loop: a trailing-run pattern backtracks super-linearly). */
 export const trimTrailingSlashes = (text) => {
-  for (let end = text.length; ; end -= 1) if (end === 0 || text[end - 1] !== '/') return text.slice(0, end);
+    for (let end = text.length;; end -= 1)
+        if (end === 0 || text[end - 1] !== '/')
+            return text.slice(0, end);
 };
 // A trailing '*' run with the one '/' before it (the glob suffix of 'dir/**'); text without a trailing '*' is unchanged.
 const stripTrailingStars = (text) => {
-  let end = text.length;
-  while (end > 0 && text[end - 1] === '*') end -= 1;
-  if (end === text.length) return text;
-  return text.slice(0, end > 0 && text[end - 1] === '/' ? end - 1 : end);
+    let end = text.length;
+    while (end > 0 && text[end - 1] === '*')
+        end -= 1;
+    if (end === text.length)
+        return text;
+    return text.slice(0, end > 0 && text[end - 1] === '/' ? end - 1 : end);
 };
 /** A relative path in git's spelling: forward slashes, no leading './'. */
 export const posixPath = (p) => slash(p).replace(/^\.\//, '');
@@ -30,8 +32,8 @@ export const samePath = (a, b) => foldCase(a) === foldCase(b);
  * `fold: true` folds case on every platform (a comparison against a lowercase-stored root needs it).
  */
 export const pathKey = (p, { fold = WIN } = {}) => {
-  const key = trimTrailingSlashes(slash(path.resolve(p)));
-  return fold ? key.toLowerCase() : key;
+    const key = trimTrailingSlashes(slash(path.resolve(p)));
+    return fold ? key.toLowerCase() : key;
 };
 /** `a` is `b` or under it, or the reverse: two path spellings whose trees touch. */
 export const pathsOverlap = (a, b) => sameOrUnder(a, b) || sameOrUnder(b, a);
@@ -44,32 +46,45 @@ export const pathsOverlap = (a, b) => sameOrUnder(a, b) || sameOrUnder(b, a);
  * @param {{trim?: boolean, collapse?: boolean, dot?: boolean, glob?: string|null, fold?: boolean}} [options]
  */
 export const normPath = (p, { trim = false, collapse = false, dot = false, glob = null, fold = false } = {}) => {
-  let s = p == null ? '' : String(p);
-  if (trim) s = s.trim();
-  s = slash(s);
-  if (collapse) s = s.replace(/\/{2,}/g, '/');
-  if (dot) s = s.replace(/^\.\//, '');
-  if (glob === 'star') s = stripTrailingStars(s);
-  else if (glob === 'double') s = s.replace(/\/\*\*$/, '');
-  s = trimTrailingSlashes(s);
-  return fold ? s.toLowerCase() : s;
+    let s = p == null ? '' : String(p);
+    if (trim)
+        s = s.trim();
+    s = slash(s);
+    if (collapse)
+        s = s.replace(/\/{2,}/g, '/');
+    if (dot)
+        s = s.replace(/^\.\//, '');
+    if (glob === 'star')
+        s = stripTrailingStars(s);
+    else if (glob === 'double')
+        s = s.replace(/\/\*\*$/, '');
+    s = trimTrailingSlashes(s);
+    return fold ? s.toLowerCase() : s;
 };
 /** A work-relative path in one spelling: forward slashes, no leading ./, no trailing slash. */
 export const normWork = (p) => trimTrailingSlashes(String(p ?? '').trim().replaceAll('\\', '/').replace(/^\.\/+/, ''));
-
 /** `p` resolved and dereferenced (realpath where the path exists) — the canonical spelling of a checkout dir. */
 export const realPath = (p) => {
-  const resolved = path.resolve(p);
-  try { return fs.realpathSync.native(resolved); } catch { return resolved; }
+    const resolved = path.resolve(p);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
 };
 /** `p` with its nearest existing ancestor dereferenced and the not-yet-created rest appended: a root's canonical spelling before it exists. */
 export const canonicalPath = (p) => {
-  const rest = [];
-  for (let at = path.resolve(p); ; at = path.dirname(at)) {
-    try { return path.join(fs.realpathSync.native(at), ...rest); } catch { /* not created yet */ }
-    if (path.dirname(at) === at) return path.resolve(p);
-    rest.unshift(path.basename(at));
-  }
+    const rest = [];
+    for (let at = path.resolve(p);; at = path.dirname(at)) {
+        try {
+            return path.join(fs.realpathSync.native(at), ...rest);
+        }
+        catch { /* not created yet */ }
+        if (path.dirname(at) === at)
+            return path.resolve(p);
+        rest.unshift(path.basename(at));
+    }
 };
 /** `p` resolved and case-folded where the filesystem ignores case — the Map key of an absolute path. */
 export const resolvedKey = (p) => foldCase(path.resolve(p));
@@ -80,8 +95,8 @@ export const sameResolvedPath = (a, b) => pathKey(a, { fold: true }) === pathKey
  * both sides first (e.g. the registry's realpath-folded treeKey) when their spellings need it.
  */
 export const insidePath = (root, file, { key = (p) => p, includeSelf = false } = {}) => {
-  const rel = path.relative(key(root), key(file));
-  return (includeSelf || Boolean(rel)) && !rel.startsWith('..') && !path.isAbsolute(rel);
+    const rel = path.relative(key(root), key(file));
+    return (includeSelf || Boolean(rel)) && !rel.startsWith('..') && !path.isAbsolute(rel);
 };
 /**
  * `candidate` (absolute, or relative to `base`) resolved and dereferenced, required to sit under `base` (or be it):
@@ -90,20 +105,20 @@ export const insidePath = (root, file, { key = (p) => p, includeSelf = false } =
  * a PATH_OUTSIDE_BASE refusal (`label` names the argument in the message).
  */
 export const containedPath = (base, candidate, { label = 'path' } = {}) => {
-  const root = canonicalPath(base);
-  const resolved = canonicalPath(path.resolve(root, String(candidate ?? '')));
-  const prefix = root.endsWith(path.sep) ? root : root + path.sep;
-  if (!insidePath(root, resolved, { includeSelf: true }) || (resolved !== root && !resolved.startsWith(prefix))) throw Object.assign(new Error(`${label} ${String(candidate)} is outside ${root} [PATH_OUTSIDE_BASE]`), { code: 'PATH_OUTSIDE_BASE' });
-  return resolved;
+    const root = canonicalPath(base);
+    const resolved = canonicalPath(path.resolve(root, String(candidate ?? '')));
+    const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+    if (!insidePath(root, resolved, { includeSelf: true }) || (resolved !== root && !resolved.startsWith(prefix)))
+        throw Object.assign(new Error(`${label} ${String(candidate)} is outside ${root} [PATH_OUTSIDE_BASE]`), { code: 'PATH_OUTSIDE_BASE' });
+    return resolved;
 };
 /**
  * A path-ish value (a string or a {path} entry) in relative compare form: trimmed, forward slashes,
  * no trailing '/**' glob or slashes, no leading './'; `fold` lowercases for a case-insensitive key.
  */
 export const normRel = (p, { fold = false } = {}) => {
-  const s = trimTrailingSlashes(String(typeof p === 'string' ? p : p?.path ?? '').trim().replaceAll('\\', '/').replace(/\/\*\*$/, '')).replace(/^\.\//, '');
-  return fold ? s.toLowerCase() : s;
+    const s = trimTrailingSlashes(String(typeof p === 'string' ? p : p?.path ?? '').trim().replaceAll('\\', '/').replace(/\/\*\*$/, '')).replace(/^\.\//, '');
+    return fold ? s.toLowerCase() : s;
 };
 /** Whether `file` equals or sits under one of `prefixes` (posix spellings; `dot` counts a '.' prefix as covering all). */
-export const underAny = (file, prefixes, { dot = false } = {}) =>
-  (prefixes ?? []).some((p) => (dot && p === '.') || sameOrUnder(file, p));
+export const underAny = (file, prefixes, { dot = false } = {}) => (prefixes ?? []).some((p) => (dot && p === '.') || sameOrUnder(file, p));

package/runtime/scripts/lib/pid-alive.d.mts

@@ -0,0 +1,2 @@
+/** True while `pid` names a live process (EPERM counts as alive). */
+export declare const pidAlive: (pid: unknown) => boolean;

package/runtime/scripts/lib/pid-alive.mjs

@@ -1,7 +1,14 @@
 // pid-alive.mjs - whether a process id names a live process: the one probe the host locks, the file claim and the machine store share.
-
 /** True while `pid` names a live process (EPERM counts as alive). */
 export const pidAlive = (pid) => {
-  if (!Number.isInteger(pid) || pid <= 0) { return false; }
-  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code === 'EPERM';
+    }
 };

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

@@ -0,0 +1,2 @@
+/** `file` as {key: value}: blank lines and #/! comments skipped, the first = or : splits. Unreadable file → {}. */
+export declare function readProperties(file: string): Record<string, string>;

package/runtime/scripts/lib/properties.mjs

@@ -1,16 +1,22 @@
 // properties.mjs — the .properties file reader (key=value lines, # and ! comments).
 import fs from 'node:fs';
-
 /** `file` as {key: value}: blank lines and #/! comments skipped, the first = or : splits. Unreadable file → {}. */
 export function readProperties(file) {
-  const out = {};
-  let text;
-  try { text = fs.readFileSync(file, 'utf8'); } catch { return out; }
-  for (const raw of text.split(/\r?\n/)) {
-    const line = raw.trim();
-    if (!line || line.startsWith('#') || line.startsWith('!')) continue;
-    const at = line.search(/[=:]/);
-    if (at > 0) out[line.slice(0, at).trim()] = line.slice(at + 1).trim();
-  }
-  return out;
+    const out = {};
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return out;
+    }
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#') || line.startsWith('!'))
+            continue;
+        const at = line.search(/[=:]/);
+        if (at > 0)
+            out[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+    }
+    return out;
 }

package/runtime/scripts/lib/provision-operation-schema.d.mts

@@ -0,0 +1,4 @@
+/** The `$ref` application-stacks.schema.yaml uses for its `operations` block. */
+export declare const PROVISION_OPERATION_SCHEMA_REF = "provision-operation.schema.yaml";
+/** The composed `operations` schema, read from this runtime's modules/schemas. */
+export declare function provisionOperationSchema(): any;

package/runtime/scripts/lib/provision-operation-schema.mjs

@@ -5,13 +5,12 @@
 // bundled in @starci/hfs carries them beside this module (a skillRoot join left provision-operation.schema.yaml out of it).
 import fs from 'node:fs';
 import { parseYaml } from '../../engine/yaml.mjs';
-
 /** The `$ref` application-stacks.schema.yaml uses for its `operations` block. */
 export const PROVISION_OPERATION_SCHEMA_REF = 'provision-operation.schema.yaml';
-
 /** The composed `operations` schema, read from this runtime's modules/schemas. */
+// reason: the composed schema is parsed from YAML and consumed by the self-contained schema walker, which takes any document.
 export function provisionOperationSchema() {
-  const schema = parseYaml(fs.readFileSync(new URL('../../modules/schemas/provision-operation.schema.yaml', import.meta.url), 'utf8'));
-  const stacks = parseYaml(fs.readFileSync(new URL('../../modules/schemas/application-stacks.schema.yaml', import.meta.url), 'utf8'));
-  return { ...schema, $defs: { ...schema.$defs, serviceCredential: stacks.$defs.serviceCredential } };
+    const schema = parseYaml(fs.readFileSync(new URL('../../modules/schemas/provision-operation.schema.yaml', import.meta.url), 'utf8'));
+    const stacks = parseYaml(fs.readFileSync(new URL('../../modules/schemas/application-stacks.schema.yaml', import.meta.url), 'utf8'));
+    return { ...schema, $defs: { ...schema.$defs, serviceCredential: stacks.$defs.serviceCredential } };
 }

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

@@ -0,0 +1,12 @@
+/** The text of `rel` under `root` ('/'-separated rel), or null when it is missing or unreadable. */
+export declare const readTextFile: (root: string, rel: unknown) => string | null;
+/** `file` read and parsed by `parse`, or `fallback` when it is missing, unreadable or malformed. */
+export declare const readParsedFile: <T, F = null>(file: string, parse: (text: string) => T, fallback?: F) => T | F;
+/**
+ * Feed `file`'s lines to `onLine` reading in bounded chunks — a diff or a patch can exceed any single
+ * string. `eol` is the line-ending pattern or literal (default CRLF-aware); a last unterminated line is fed too.
+ */
+export declare function forEachFileLine(file: string, onLine: (line: string) => void, { chunkBytes, eol }?: {
+    chunkBytes?: number;
+    eol?: string | RegExp;
+}): void;

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

@@ -2,33 +2,46 @@
 // never a throw (the JSON twin is ./json.mjs readJsonFile, the YAML twin ./read-yaml.mjs).
 import fs from 'node:fs';
 import path from 'node:path';
-
 /** The text of `rel` under `root` ('/'-separated rel), or null when it is missing or unreadable. */
 export const readTextFile = (root, rel) => {
-  try { return fs.readFileSync(path.join(root, ...String(rel).split('/')), 'utf8'); } catch { return null; }
+    try {
+        return fs.readFileSync(path.join(root, ...String(rel).split('/')), 'utf8');
+    }
+    catch {
+        return null;
+    }
 };
-
 /** `file` read and parsed by `parse`, or `fallback` when it is missing, unreadable or malformed. */
 export const readParsedFile = (file, parse, fallback = null) => {
-  try { return parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+    try {
+        return parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
 };
-
 /**
  * Feed `file`'s lines to `onLine` reading in bounded chunks — a diff or a patch can exceed any single
  * string. `eol` is the line-ending pattern or literal (default CRLF-aware); a last unterminated line is fed too.
  */
 export function forEachFileLine(file, onLine, { chunkBytes = 8 * 1024 * 1024, eol = /\r?\n/ } = {}) {
-  const fd = fs.openSync(file, 'r');
-  try {
-    const buf = Buffer.alloc(chunkBytes);
-    let carry = '';
-    for (;;) {
-      const n = fs.readSync(fd, buf, 0, chunkBytes, null);
-      if (n <= 0) break;
-      const lines = (carry + buf.toString('utf8', 0, n)).split(eol);
-      carry = lines.pop();
-      for (const l of lines) onLine(l);
+    const fd = fs.openSync(file, 'r');
+    try {
+        const buf = Buffer.alloc(chunkBytes);
+        let carry = '';
+        for (;;) {
+            const n = fs.readSync(fd, buf, 0, chunkBytes, null);
+            if (n <= 0)
+                break;
+            const lines = (carry + buf.toString('utf8', 0, n)).split(eol);
+            carry = lines.pop();
+            for (const l of lines)
+                onLine(l);
+        }
+        if (carry)
+            onLine(carry);
+    }
+    finally {
+        fs.closeSync(fd);
     }
-    if (carry) onLine(carry);
-  } finally { fs.closeSync(fd); }
 }

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

@@ -0,0 +1,52 @@
+export declare const MARK = "[redacted]";
+/** The hits of a redaction: rule name -> replacements that changed the text. */
+type Hits = Map<string, number>;
+/** The options of a redaction call. */
+export interface RedactOptions {
+    repoRoots?: readonly unknown[];
+}
+/** Keys whose value is a secret whatever it looks like; the key stays, the value goes. */
+export declare const SECRET_KEY: RegExp;
+/** Learn the declared secrets of every .starcistacks stack under `repoRoot` (idempotent). */
+export declare function learnStackSecrets(repoRoot: unknown): void;
+/**
+ * `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 declare function redactTracked(text: string, options?: RedactOptions): {
+    text: string;
+    hits: Hits;
+};
+export declare function redactTracked(text: unknown, options?: RedactOptions): {
+    text: unknown;
+    hits: Hits;
+};
+/** `text` with every secret value blanked. */
+export declare function redactText(text: string, options?: RedactOptions): string;
+export declare function redactText(text: unknown, options?: RedactOptions): unknown;
+/** The rules that still find a secret in `text` after redaction ran: [{rule, count}], never the matched text. */
+export declare function survivingSecrets(text: unknown, options?: RedactOptions): {
+    rule: string;
+    count: number;
+}[];
+/** A path that is a secret by being one (an env file, a key file, .secrets/): blanked, its rule named. */
+export declare function redactPath(p: string): string;
+export declare function redactPath(p: unknown): unknown;
+/** A deep copy of `value` with secret-named keys blanked and every string redacted. */
+export declare function redactData(value: unknown, key?: string | null, depth?: number): unknown;
+/** True for media types whose bytes are text the filter can read. */
+export declare const isTextMedia: (mediaType: unknown) => boolean;
+/** The supported text encoding selected by a byte-order mark. */
+export declare function textEncodingOf(bytes: Uint8Array): 'utf-16le' | 'utf-16be' | 'utf-8-bom' | 'utf-8';
+/** Decode supported text without accepting malformed bytes as sanitized evidence. */
+export declare function decodeText(bytes: Uint8Array): string;
+/**
+ * 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 declare function redactBytes(bytes: Uint8Array, mediaType: unknown, { repoRoots }?: RedactOptions): {
+    bytes: Buffer;
+    redaction: string;
+};
+export {};