@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/api/git/is-ancestor.d.mts

@@ -0,0 +1,5 @@
+import { type GitRunnerFn } from './lib.mjs';
+/** True when `a` is an ancestor of (or equal to) `b`; false otherwise, and when a ref does not resolve. git: the caller's runner or null. */
+export declare const isAncestor: (cwd: string, a: string, b: string, { git }?: {
+    git?: GitRunnerFn | null;
+}) => boolean;

package/runtime/scripts/api/git/is-ancestor.mjs

@@ -1,5 +1,4 @@
 // is-ancestor.mjs — `git merge-base --is-ancestor <a> <b>`: whether commit `a` is in the history of `b`.
 import { gitRunner } from './lib.mjs';
-
 /** True when `a` is an ancestor of (or equal to) `b`; false otherwise, and when a ref does not resolve. git: the caller's runner or null. */
 export const isAncestor = (cwd, a, b, { git = null } = {}) => gitRunner(git)(['merge-base', '--is-ancestor', a, b], { cwd }).ok;

package/runtime/scripts/api/git/lib.d.mts

@@ -0,0 +1,67 @@
+import { type SpawnSyncOptions, type SpawnSyncReturns } from 'node:child_process';
+/** The spawnSync options a git call takes; encoding 'buffer' is a request for raw bytes (see gitSpawn). */
+export type GitSpawnOptions = Omit<SpawnSyncOptions, 'encoding'> & {
+    encoding?: BufferEncoding | 'buffer' | null;
+};
+/** What runGit takes on top of the spawn options: where (cwd, or `-C` dir), which binary, and `-c key=value` config. */
+export type GitOptions = Omit<GitSpawnOptions, 'cwd'> & {
+    cwd?: string | null;
+    dir?: string | null;
+    git?: string;
+    config?: Record<string, string | number | boolean> | null;
+};
+/** The spawn result of a git call: {status, stdout, stderr, error}. */
+export type GitResult = SpawnSyncReturns<string>;
+/** A caller's git runner or a spec's fake: the result is {ok|status, stdout|out, stderr|err, error}. */
+export interface GitRunnerResult {
+    ok?: boolean;
+    status?: number | null;
+    stdout?: unknown;
+    out?: unknown;
+    stderr?: unknown;
+    err?: unknown;
+    error?: {
+        message?: string;
+    } | string | null | undefined;
+}
+export type GitRunnerFn = (args: string[], opts: GitRunnerOptions) => GitRunnerResult | null | undefined;
+/** The options of a folded runner call. */
+export interface GitRunnerOptions extends GitOptions {
+    timeout?: number;
+    maxBuffer?: number;
+}
+/** The folded runner result. */
+export interface GitRun {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+interface GitPathInputs {
+    env: NodeJS.ProcessEnv;
+    platform: string;
+    home: string;
+    exists: (file: string) => boolean;
+}
+/** gitExecutable's spec seams. */
+export type GitExecutableOptions = Partial<GitPathInputs>;
+/**
+ * `git args` in `cwd`, or `git -C dir args` when `dir` is given. `git` overrides the binary; `config` ({key: value})
+ * prefixes one `-c key=value` per entry (core.quotepath=off, a committer identity). Scoped calls discard ambient
+ * hook repository variables; an explicit env remains authoritative, including an intentional temporary index.
+ */
+export declare const runGit: (args: readonly string[], { cwd, dir, git, config, ...options }?: GitOptions) => GitResult;
+/**
+ * A caller's git runner folded to (args, opts) -> {ok, stdout, stderr}. `git`: the caller's runner (args, {cwd}) ->
+ * {ok|status, stdout|out, stderr|err} (a spec's fake); null: runGit with a 5-minute timeout and a 64 MB buffer.
+ */
+export declare const gitRunner: (git?: GitRunnerFn | null) => (args: string[], opts?: GitRunnerOptions) => GitRun;
+/**
+ * The absolute path of the real git binary, or null: the first PATH directory holding git (git.exe on Windows) that is not
+ * the StarCi shim directory <home>/.starci/bin (a seat's guard shim is never the git the runtime itself runs). A bare name is never
+ * spawned, so a writable directory cannot be reached by name lookup at spawn time. Resolved once per process; options (env,
+ * platform, home, exists) are for a spec and bypass the cache.
+ */
+export declare const gitExecutable: (options?: GitExecutableOptions | null) => string | null;
+/** The output ceiling of the whole-diff and `cat-file --batch` calls batch (a release diff is tens of megabytes). */
+export declare const BATCH_MAX_BUFFER: number;
+export {};

package/runtime/scripts/api/git/lib.mjs

@@ -13,7 +13,6 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 import { withTempEnv } from '../../../engine/temp-root.mjs';
-
 /**
  * Spawn `file` (the git binary) once with `args`: utf8 text, a hidden window, never a shell.
  * Options pass through last, so cwd, timeout, input, env or maxBuffer land as given. encoding:'buffer'
@@ -21,46 +20,46 @@ import { withTempEnv } from '../../../engine/temp-root.mjs';
  * ERR_UNKNOWN_ENCODING, so it reaches spawnSync as encoding:null (Buffer output either way).
  */
 const gitSpawn = (file, args, options = {}) => {
-  assertMutationFence({ kind: 'git-effect', args });
-  const spawn = { encoding: 'utf8', windowsHide: true, ...options };
-  if (spawn.encoding === 'buffer') spawn.encoding = null;
-  // tempChildEnv copies the env (node adds NODE_V8_COVERAGE to the env object it is given: a frozen caller env must not throw under coverage) and points TEMP/TMP/TMPDIR at the temp root
-  return spawnSync(file, args, withTempEnv(spawn));
+    assertMutationFence({ kind: 'git-effect', args });
+    const spawn = { encoding: 'utf8', windowsHide: true, ...options };
+    if (spawn.encoding === 'buffer')
+        spawn.encoding = null;
+    // tempChildEnv copies the env (node adds NODE_V8_COVERAGE to the env object it is given: a frozen caller env must not throw under coverage) and points TEMP/TMP/TMPDIR at the temp root
+    // reason: encoding:null (the former 'buffer') returns Buffers; callers of that mode read the result as raw bytes
+    const spawnOptions = withTempEnv(spawn);
+    return spawnSync(file, args, spawnOptions);
 };
-
 /**
  * `git args` in `cwd`, or `git -C dir args` when `dir` is given. `git` overrides the binary; `config` ({key: value})
  * prefixes one `-c key=value` per entry (core.quotepath=off, a committer identity). Scoped calls discard ambient
  * hook repository variables; an explicit env remains authoritative, including an intentional temporary index.
  */
-export const runGit = (args, { cwd = null, dir = null, git = 'git', config = null, ...options } = {}) =>
-  gitSpawn(git, [...(dir ? ['-C', dir] : []), ...Object.entries(config ?? {}).flatMap(([key, value]) => ['-c', `${key}=${value}`]), ...args], {
+export const runGit = (args, { cwd = null, dir = null, git = 'git', config = null, ...options } = {}) => gitSpawn(git, [...(dir ? ['-C', dir] : []), ...Object.entries(config ?? {}).flatMap(([key, value]) => ['-c', `${key}=${value}`]), ...args], {
     ...(cwd ? { cwd } : {}), ...options,
     ...((cwd || dir) && options.env === undefined ? { env: withoutGitLocalEnv(process.env) } : {}),
-  });
-
+});
 /**
  * A caller's git runner folded to (args, opts) -> {ok, stdout, stderr}. `git`: the caller's runner (args, {cwd}) ->
  * {ok|status, stdout|out, stderr|err} (a spec's fake); null: runGit with a 5-minute timeout and a 64 MB buffer.
  */
 export const gitRunner = (git = null) => (args, opts = {}) => {
-  const r = git ? git(args, opts) : runGit(args, { timeout: 300_000, maxBuffer: 64 * 1024 * 1024, ...opts });
-  return { ok: r?.ok ?? (!r?.error && r?.status === 0), stdout: String(r?.stdout ?? r?.out ?? '').trim(), stderr: String(r?.stderr ?? r?.err ?? r?.error?.message ?? r?.error ?? '').trim() };
+    const r = git ? git(args, opts) : runGit(args, { timeout: 300_000, maxBuffer: 64 * 1024 * 1024, ...opts });
+    return { ok: r?.ok ?? (!r?.error && r?.status === 0), stdout: String(r?.stdout ?? r?.out ?? '').trim(), stderr: String(r?.stderr ?? r?.err ?? (typeof r?.error === 'object' ? r.error?.message : undefined) ?? r?.error ?? '').trim() };
 };
-
 let cachedGit;
 const gitPathOf = ({ env, platform, home, exists }) => {
-  const p = platform === 'win32' ? path.win32 : path.posix;
-  const pathKey = Object.keys(env).find((name) => name.toLowerCase() === 'path');
-  const shim = p.join(home, '.starci', 'bin');
-  const same = (a, b) => (platform === 'win32' ? p.resolve(a).toLowerCase() === p.resolve(b).toLowerCase() : p.resolve(a) === p.resolve(b));
-  const binary = platform === 'win32' ? 'git.exe' : 'git';
-  for (const raw of String(pathKey ? env[pathKey] : '').split(platform === 'win32' ? ';' : ':')) {
-    const dir = raw.replace(/^"(.*)"$/, '$1');
-    const file = dir && p.isAbsolute(dir) && !same(dir, shim) ? p.join(dir, binary) : null;
-    if (file && exists(file)) return file;
-  }
-  return null;
+    const p = platform === 'win32' ? path.win32 : path.posix;
+    const pathKey = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+    const shim = p.join(home, '.starci', 'bin');
+    const same = (a, b) => (platform === 'win32' ? p.resolve(a).toLowerCase() === p.resolve(b).toLowerCase() : p.resolve(a) === p.resolve(b));
+    const binary = platform === 'win32' ? 'git.exe' : 'git';
+    for (const raw of String(pathKey ? env[pathKey] : '').split(platform === 'win32' ? ';' : ':')) {
+        const dir = raw.replace(/^"(.*)"$/, '$1');
+        const file = dir && p.isAbsolute(dir) && !same(dir, shim) ? p.join(dir, binary) : null;
+        if (file && exists(file))
+            return file;
+    }
+    return null;
 };
 /**
  * The absolute path of the real git binary, or null: the first PATH directory holding git (git.exe on Windows) that is not
@@ -69,12 +68,13 @@ const gitPathOf = ({ env, platform, home, exists }) => {
  * platform, home, exists) are for a spec and bypass the cache.
  */
 export const gitExecutable = (options = null) => {
-  if (!options && cachedGit !== undefined) return cachedGit;
-  const { env = process.env, platform = process.platform, home = os.homedir(), exists = (file) => fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true } = options ?? {};
-  const found = gitPathOf({ env, platform, home, exists });
-  if (!options) cachedGit = found;
-  return found;
+    if (!options && cachedGit !== undefined)
+        return cachedGit;
+    const { env = process.env, platform = process.platform, home = os.homedir(), exists = (file) => fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true } = options ?? {};
+    const found = gitPathOf({ env, platform, home, exists });
+    if (!options)
+        cachedGit = found;
+    return found;
 };
-
 /** The output ceiling of the whole-diff and `cat-file --batch` calls batch (a release diff is tens of megabytes). */
-const BATCH_MAX_BUFFER = 1024 * 1024 * 1024;
+export const BATCH_MAX_BUFFER = 1024 * 1024 * 1024;

package/runtime/scripts/api/git/ls-files.d.mts

@@ -0,0 +1,3 @@
+import { type GitOptions, type GitResult } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git ls-files ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export declare const lsFiles: (args?: readonly string[], options?: GitOptions) => GitResult;

package/runtime/scripts/api/git/ls-files.mjs

@@ -1,6 +1,5 @@
 // ls-files.mjs — `git ls-files <args>`: the paths the index tracks (--cached), or the untracked / deleted / ignored ones
 // the flags ask for (-z keeps any file name intact).
 import { runGit } from './lib.mjs';
-
 /** The spawn result {status, stdout, stderr, error} of `git ls-files ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
 export const lsFiles = (args = [], options = {}) => runGit(['ls-files', ...args], options);

package/runtime/scripts/api/git/ls-tree.d.mts

@@ -0,0 +1,3 @@
+import { type GitOptions, type GitResult } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git ls-tree ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export declare const lsTree: (args?: readonly string[], options?: GitOptions) => GitResult;

package/runtime/scripts/api/git/ls-tree.mjs

@@ -1,5 +1,4 @@
 // ls-tree.mjs — `git ls-tree <args>`: the entries of a tree object.
 import { runGit } from './lib.mjs';
-
 /** The spawn result {status, stdout, stderr, error} of `git ls-tree ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
 export const lsTree = (args = [], options = {}) => runGit(['ls-tree', ...args], options);

package/runtime/scripts/api/git/merge-base.d.mts

@@ -0,0 +1,5 @@
+import { type GitRunnerFn } from './lib.mjs';
+/** The best common ancestor of commits `a` and `b` (a sha), or null when they share none or a ref does not resolve. */
+export declare const mergeBase: (cwd: string, a: string, b: string, { git }?: {
+    git?: GitRunnerFn | null;
+}) => string | null;

package/runtime/scripts/api/git/merge-base.mjs

@@ -1,9 +1,8 @@
 // merge-base.mjs — `git merge-base <a> <b>`: the best common ancestor of two commits. Whether one commit is in another
 // is is-ancestor.mjs.
 import { gitRunner } from './lib.mjs';
-
 /** The best common ancestor of commits `a` and `b` (a sha), or null when they share none or a ref does not resolve. */
 export const mergeBase = (cwd, a, b, { git = null } = {}) => {
-  const r = gitRunner(git)(['merge-base', a, b], { cwd });
-  return r.ok && r.stdout ? r.stdout : null;
+    const r = gitRunner(git)(['merge-base', a, b], { cwd });
+    return r.ok && r.stdout ? r.stdout : null;
 };

package/runtime/scripts/api/git/remote.d.mts

@@ -0,0 +1,3 @@
+import { type GitOptions, type GitResult } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git remote ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export declare const remote: (args?: readonly string[], options?: GitOptions) => GitResult;

package/runtime/scripts/api/git/remote.mjs

@@ -1,5 +1,4 @@
 // remote.mjs — `git remote <args>`: the configured remotes (get-url <name>).
 import { runGit } from './lib.mjs';
-
 /** The spawn result {status, stdout, stderr, error} of `git remote ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
 export const remote = (args = [], options = {}) => runGit(['remote', ...args], options);

package/runtime/scripts/api/git/rev-parse-query.d.mts

@@ -0,0 +1,3 @@
+import { type GitOptions, type GitResult } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git rev-parse ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export declare const revParseQuery: (args?: readonly string[], options?: GitOptions) => GitResult;

package/runtime/scripts/api/git/rev-parse-query.mjs

@@ -1,5 +1,4 @@
 // rev-parse-query.mjs — `git rev-parse <args>`: one rev-parse query (--show-toplevel, --git-common-dir, --git-path, a ref): the text it prints.
 import { runGit } from './lib.mjs';
-
 /** The spawn result {status, stdout, stderr, error} of `git rev-parse ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
 export const revParseQuery = (args = [], options = {}) => runGit(['rev-parse', ...args], options);

package/runtime/scripts/api/git/show.d.mts

@@ -0,0 +1,3 @@
+import { type GitOptions, type GitResult } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git show ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export declare const show: (args?: readonly string[], options?: GitOptions) => GitResult;

package/runtime/scripts/api/git/show.mjs

@@ -1,6 +1,5 @@
 // show.mjs — `git show <args>`: an object of a repository - a file at a revision (`<rev>:<path>`), or a commit's
 // header and message (-s --format=...).
 import { runGit } from './lib.mjs';
-
 /** The spawn result {status, stdout, stderr, error} of `git show ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
 export const show = (args = [], options = {}) => runGit(['show', ...args], options);

package/runtime/scripts/api/git/tag.d.mts

@@ -0,0 +1,3 @@
+import { type GitOptions, type GitResult } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git tag ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export declare const tag: (args?: readonly string[], options?: GitOptions) => GitResult;

package/runtime/scripts/api/git/tag.mjs

@@ -1,5 +1,4 @@
 // tag.mjs — `git tag <args>`: list or create tags (--points-at <rev>, -l <pattern>, -a <name> -m <message>).
 import { runGit } from './lib.mjs';
-
 /** The spawn result {status, stdout, stderr, error} of `git tag ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
 export const tag = (args = [], options = {}) => runGit(['tag', ...args], options);

package/runtime/scripts/api/git/update-ref.d.mts

@@ -0,0 +1,7 @@
+import { type GitRun, type GitRunnerFn } from './lib.mjs';
+/** {ok, stdout, stderr}. message: the reflog line; old: the sha the ref must still name. git: the caller's runner or null. */
+export declare function updateRef(repoRoot: string, ref: string, sha: string, { message, old, git }?: {
+    message?: string | null;
+    old?: string | null;
+    git?: GitRunnerFn | null;
+}): GitRun;

package/runtime/scripts/api/git/update-ref.mjs

@@ -1,8 +1,7 @@
 // update-ref.mjs — `git update-ref [-m <message>] <ref> <sha> [<old>]`: point a ref at a commit (a preserved worktree's
 // refs/heads/preserved/<name>); with `old`, a compare-and-swap that fails when the ref no longer names `old`.
 import { gitRunner } from './lib.mjs';
-
 /** {ok, stdout, stderr}. message: the reflog line; old: the sha the ref must still name. git: the caller's runner or null. */
 export function updateRef(repoRoot, ref, sha, { message = null, old = null, git = null } = {}) {
-  return gitRunner(git)(['update-ref', ...(message ? ['-m', message] : []), ref, sha, ...(old ? [old] : [])], { cwd: repoRoot });
+    return gitRunner(git)(['update-ref', ...(message ? ['-m', message] : []), ref, sha, ...(old ? [old] : [])], { cwd: repoRoot });
 }

package/runtime/scripts/api/git/write-tree.d.mts

@@ -0,0 +1,3 @@
+import { type GitOptions, type GitResult } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git write-tree ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export declare const writeTree: (args?: readonly string[], options?: GitOptions) => GitResult;

package/runtime/scripts/api/git/write-tree.mjs

@@ -1,5 +1,4 @@
 // write-tree.mjs — `git write-tree <args>`: a tree object written from the index (its sha on stdout).
 import { runGit } from './lib.mjs';
-
 /** The spawn result {status, stdout, stderr, error} of `git write-tree ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
 export const writeTree = (args = [], options = {}) => runGit(['write-tree', ...args], options);

package/runtime/scripts/api/node/lib.d.mts

@@ -0,0 +1,7 @@
+import { type ChildProcess, type ExecFileException, type ExecFileOptions, type SpawnOptions, type SpawnSyncOptions, type SpawnSyncReturns } from 'node:child_process';
+/** `node <args>` with this process's node binary, waited for; options pass through last (cwd, stdio, env, timeout, maxBuffer, input). */
+export declare const nodeSpawn: (args: readonly string[], options?: SpawnSyncOptions) => SpawnSyncReturns<string>;
+/** `node <args>` with this process's node binary, started and not waited for: the ChildProcess (detached, stdio, env pass through). */
+export declare const nodeStart: (args: readonly string[], options?: SpawnOptions) => ChildProcess;
+/** `node <args>` with this process's node binary, waited for without blocking the thread: callback(error, stdout, stderr). */
+export declare const nodeExecFile: (args: readonly string[], options: ExecFileOptions, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void) => ChildProcess;

package/runtime/scripts/api/node/lib.mjs

@@ -5,16 +5,26 @@ import { assertMutationFence } from '../../lib/mutation-fence.mjs';
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import { withTempEnv } from '../../../engine/temp-root.mjs';
 import { withoutTestRunner } from '../../lib/env.mjs';
-
 /** Whether `node <args>` starts the test runner (`--test`, `--test=...` before any script): its env must not carry an enclosing run's mark. THE one seam of every runtime child that runs specs. */
 const startsTestRunner = (args) => args.some((arg) => arg === '--test' || String(arg).startsWith('--test='));
 const forChild = (args, options) => (startsTestRunner(args) ? { ...options, env: withoutTestRunner(options?.env ?? process.env) } : options);
-
 /** `node <args>` with this process's node binary, waited for; options pass through last (cwd, stdio, env, timeout, maxBuffer, input). */
-export const nodeSpawn = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawnSync(process.execPath, args, withTempEnv({ encoding: 'utf8', windowsHide: true, ...forChild(args, options) })); };
-
+export const nodeSpawn = (args, options = {}) => {
+    assertMutationFence({ kind: 'node-effect', args });
+    // reason: utf8 is the default; a caller option that overrides encoding is the caller's explicit request for another output type
+    const spawnOptions = withTempEnv({ encoding: 'utf8', windowsHide: true, ...forChild(args, options) });
+    return spawnSync(process.execPath, args, spawnOptions);
+};
 /** `node <args>` with this process's node binary, started and not waited for: the ChildProcess (detached, stdio, env pass through). */
-export const nodeStart = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawn(process.execPath, args, withTempEnv({ windowsHide: true, ...forChild(args, options) })); };
-
+export const nodeStart = (args, options = {}) => {
+    assertMutationFence({ kind: 'node-effect', args });
+    const spawnOptions = withTempEnv({ windowsHide: true, ...forChild(args, options) });
+    return spawn(process.execPath, args, spawnOptions);
+};
 /** `node <args>` with this process's node binary, waited for without blocking the thread: callback(error, stdout, stderr). */
-export const nodeExecFile = (args, options, callback) => { assertMutationFence({ kind: 'node-effect', args }); return execFile(process.execPath, args, withTempEnv({ encoding: 'utf8', windowsHide: true, ...forChild(args, options) }), callback); };
+export const nodeExecFile = (args, options, callback) => {
+    assertMutationFence({ kind: 'node-effect', args });
+    // reason: utf8 is the default; a caller option that overrides encoding is the caller's explicit request for another output type
+    const execOptions = withTempEnv({ encoding: 'utf8', windowsHide: true, ...forChild(args, options) });
+    return execFile(process.execPath, args, execOptions, callback);
+};

package/runtime/scripts/api/node/run-node.d.mts

@@ -0,0 +1,3 @@
+import type { SpawnSyncOptions, SpawnSyncReturns } from 'node:child_process';
+/** Runs `node <args>`; options (cwd, env, timeout, input, maxBuffer, stdio) pass through. */
+export declare const runNode: (args: readonly string[], options?: SpawnSyncOptions) => SpawnSyncReturns<string>;

package/runtime/scripts/api/node/run-node.mjs

@@ -1,6 +1,3 @@
-// run-node.mjs — `node <args>` with this process's node binary, waited for: a runtime script (or `-e`/`--test`) as a child
-// whose output the caller reads. Returns the spawnSync result {status, stdout, stderr, error, signal} (utf8 text).
 import { nodeSpawn } from './lib.mjs';
-
 /** Runs `node <args>`; options (cwd, env, timeout, input, maxBuffer, stdio) pass through. */
 export const runNode = (args, options = {}) => nodeSpawn(args, options);

package/runtime/scripts/api/process/resolve-real-tool.d.mts

@@ -0,0 +1,12 @@
+/** The file-system seams a spec injects: stat (default fs.statSync) and realpath (default fs.realpathSync.native). */
+export interface RealToolOptions {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    platform?: NodeJS.Platform;
+    stat?: (path: string) => {
+        isFile(): boolean;
+    };
+    realpath?: (path: string) => string;
+}
+/** Resolve `program` from PATH while excluding <home>/.starci/bin by canonical directory identity. */
+export declare function resolveRealTool(program: unknown, { env, home, platform, stat, realpath }?: RealToolOptions): string | null;

package/runtime/scripts/api/process/resolve-real-tool.mjs

@@ -2,51 +2,59 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-
 const pathValue = (env) => {
-  const key = Object.keys(env ?? {}).find((name) => name.toLowerCase() === 'path');
-  return key ? String(env[key] ?? '') : '';
+    const key = Object.keys(env ?? {}).find((name) => name.toLowerCase() === 'path');
+    return key && env ? String(env[key] ?? '') : '';
 };
-
 const canonical = (value, { platform, realpath }) => {
-  let resolved = path.resolve(value);
-  try { resolved = realpath(resolved); } catch { /* a missing PATH entry stays comparable by its resolved spelling */ }
-  return platform === 'win32' ? resolved.toLowerCase() : resolved;
+    let resolved = path.resolve(value);
+    try {
+        resolved = realpath(resolved);
+    }
+    catch { /* a missing PATH entry stays comparable by its resolved spelling */ }
+    return platform === 'win32' ? resolved.toLowerCase() : resolved;
 };
-
 const executableNames = (program, { env, platform }) => {
-  if (platform !== 'win32' || path.extname(program)) return [program];
-  const extensions = String(env?.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
-  const names = [program];
-  for (const extension of extensions) names.push(`${program}${extension}`, `${program}${extension.toLowerCase()}`);
-  return [...new Set(names)];
+    if (platform !== 'win32' || path.extname(program))
+        return [program];
+    const extensions = String(env?.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+    const names = [program];
+    for (const extension of extensions)
+        names.push(`${program}${extension}`, `${program}${extension.toLowerCase()}`);
+    return [...new Set(names)];
 };
-
 const firstExecutableHit = (entry, names, stat, realpath) => {
-  for (const executable of names) {
-    const candidate = path.join(entry, executable);
-    try {
-      if (stat(candidate).isFile()) {
-        try { return realpath(candidate); } catch { return path.resolve(candidate); }
-      }
-    } catch { /* try the next executable spelling or PATH entry */ }
-  }
-  return null;
+    for (const executable of names) {
+        const candidate = path.join(entry, executable);
+        try {
+            if (stat(candidate).isFile()) {
+                try {
+                    return realpath(candidate);
+                }
+                catch {
+                    return path.resolve(candidate);
+                }
+            }
+        }
+        catch { /* try the next executable spelling or PATH entry */ }
+    }
+    return null;
 };
-
 /** Resolve `program` from PATH while excluding <home>/.starci/bin by canonical directory identity. */
-export function resolveRealTool(program, { env = process.env, home = os.homedir(), platform = process.platform,
-  stat = fs.statSync, realpath = fs.realpathSync.native } = {}) {
-  const name = String(program ?? '');
-  if (!name || path.basename(name) !== name) return null;
-  const delimiter = platform === 'win32' ? ';' : ':';
-  const shimKey = canonical(path.join(home, '.starci', 'bin'), { platform, realpath });
-  const names = executableNames(name, { env, platform });
-  for (const rawEntry of pathValue(env).split(delimiter).filter(Boolean)) {
-    const entry = rawEntry.replace(/^"(.*)"$/, '$1');
-    if (canonical(entry, { platform, realpath }) === shimKey) continue;
-    const hit = firstExecutableHit(entry, names, stat, realpath);
-    if (hit) return hit;
-  }
-  return null;
+export function resolveRealTool(program, { env = process.env, home = os.homedir(), platform = process.platform, stat = fs.statSync, realpath = fs.realpathSync.native } = {}) {
+    const name = String(program ?? '');
+    if (!name || path.basename(name) !== name)
+        return null;
+    const delimiter = platform === 'win32' ? ';' : ':';
+    const shimKey = canonical(path.join(home, '.starci', 'bin'), { platform, realpath });
+    const names = executableNames(name, { env, platform });
+    for (const rawEntry of pathValue(env).split(delimiter).filter(Boolean)) {
+        const entry = rawEntry.replace(/^"(.*)"$/, '$1');
+        if (canonical(entry, { platform, realpath }) === shimKey)
+            continue;
+        const hit = firstExecutableHit(entry, names, stat, realpath);
+        if (hit)
+            return hit;
+    }
+    return null;
 }

package/runtime/scripts/api/process/run-program.d.mts

@@ -0,0 +1,3 @@
+import { type SpawnSyncOptions, type SpawnSyncReturns } from 'node:child_process';
+/** Runs `file args`; options (cwd, env, timeout, stdio, input) pass through. */
+export declare const runProgram: (file: string, args: readonly string[], options?: SpawnSyncOptions) => SpawnSyncReturns<string>;

package/runtime/scripts/api/process/run-program.mjs

@@ -3,6 +3,9 @@
 // spawnSync result {status, stdout, stderr, error, signal} (utf8 text, a hidden window).
 import { spawnSync } from 'node:child_process';
 import { withTempEnv } from '../../../engine/temp-root.mjs';
-
 /** Runs `file args`; options (cwd, env, timeout, stdio, input) pass through. */
-export const runProgram = (file, args, options = {}) => spawnSync(file, args, withTempEnv({ encoding: 'utf8', windowsHide: true, ...options }));
+export const runProgram = (file, args, options = {}) => {
+    // reason: utf8 is the default; a caller option that overrides encoding is the caller's explicit request for another output type
+    const spawnOptions = withTempEnv({ encoding: 'utf8', windowsHide: true, ...options });
+    return spawnSync(file, args, spawnOptions);
+};

package/runtime/scripts/api/sops/decrypt.d.mts

@@ -0,0 +1,9 @@
+import { type RunSopsFileOptions, type SopsResult } from './lib.mjs';
+/**
+ * Decrypt one custody file from caller-supplied SOPS arguments; the shared file owner requires the caller's original identity selection.
+ * @param {string|null} bin Explicit SOPS executable, or null to use the selected environment's resolver.
+ * @param {string[]} args SOPS arguments forwarded unchanged to the file operation.
+ * @param {object} options Identity, invocation, environment and capture options owned by runSopsFile.
+ * @returns {{status: number|null, stdout: string|null, stderr: string|null, error: Error|null}} The observed child result or typed identity refusal.
+ */
+export declare function decrypt(bin: string | null, args: string[], options?: RunSopsFileOptions): SopsResult;

package/runtime/scripts/api/sops/decrypt.mjs

@@ -1,6 +1,5 @@
 // decrypt.mjs — the public SOPS file-decrypt call.
 import { runSopsFile } from './lib.mjs';
-
 /**
  * Decrypt one custody file from caller-supplied SOPS arguments; the shared file owner requires the caller's original identity selection.
  * @param {string|null} bin Explicit SOPS executable, or null to use the selected environment's resolver.
@@ -9,5 +8,5 @@ import { runSopsFile } from './lib.mjs';
  * @returns {{status: number|null, stdout: string|null, stderr: string|null, error: Error|null}} The observed child result or typed identity refusal.
  */
 export function decrypt(bin, args, options = {}) {
-  return runSopsFile(bin, args, 'decrypt', options);
+    return runSopsFile(bin, args, 'decrypt', options);
 }