@starci/hfs 4.0.8 → 4.0.9

package/runtime/scripts/api/fs/forbidden-root.mjs

@@ -0,0 +1,51 @@
+// forbidden-root.mjs — the paths the runtime must never remove whole (safe-remove.mjs safeRemove refuses them before it
+// deletes anything; scripts/machine/worktree-git.mjs asks it before a worktree removal).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { samePath } from '../../lib/path-key.mjs';
+import { realpathOr } from '../../lib/fs-kind.mjs';
+
+const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/**
+ * True when `p` sits strictly below `root` by real path: no link on the way, not `root` itself. The one place a
+ * primary checkout may be removed is a disposable fixture a caller names by its temp root (hk-tmp).
+ */
+function strictlyInsideReal(p, root) {
+  if (!root) return false;
+  const rel = path.relative(path.resolve(root), path.resolve(p));
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  const real = realpathOr(p);
+  const rootReal = realpathOr(root);
+  // Its real path must be the same relative place under the root's real path: no link between them.
+  return Boolean(real && rootReal) && samePath(real, path.join(rootReal, rel));
+}
+
+/**
+ * A path the runtime must never remove whole: a filesystem root, the home or temp directory, the runtime, the
+ * repository that hosts it, the repositories root, or a primary git checkout (its .git is a directory; the
+ * scratch trees the runtime removes are temp directories and linked worktrees, whose .git is a file).
+ * `checkoutsUnder` names a disposable root (hk-tmp's temp root): a checkout strictly inside it by real path
+ * is a spec fixture, not a live repository, and is not refused for its .git. Every other refusal stands.
+ * `hold(path)` is the caller's artifact-hold check (scripts/machine/artifact-hold.mjs artifactHoldReason: a tree holding
+ * an indexed job artifact, or inside an evidence directory holding one, whatever the workflow's phase), its refusal line
+ * or null. It is required: without one every path is refused (fail closed); a caller that removes only a scratch tree
+ * it made itself, outside every ledger's repository, says so with `hold: () => null`.
+ */
+export function forbiddenRoot(p, { checkoutsUnder = null, hold } = {}) {
+  const resolved = path.resolve(p);
+  if (path.parse(resolved).root === resolved || samePath(path.dirname(resolved), resolved)) return 'a filesystem root';
+  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the runtime', SKILL_ROOT],
+    ['the repository hosting the runtime', path.dirname(SKILL_ROOT)], ['the repositories root', path.dirname(path.dirname(SKILL_ROOT))]]) {
+    if (dir && samePath(path.resolve(dir), resolved)) return name;
+  }
+  if (typeof hold !== 'function') return 'a tree no artifact-hold check cleared (pass hold)';
+  const held = hold(resolved);
+  if (held) return held;
+  let checkout = false;
+  try { checkout = fs.lstatSync(path.join(resolved, '.git')).isDirectory(); } catch { /* no .git directory */ }
+  if (checkout && !strictlyInsideReal(resolved, checkoutsUnder)) return 'a git checkout';
+  return null;
+}

package/runtime/scripts/api/fs/is-link-like.mjs

@@ -0,0 +1,25 @@
+// is-link-like.mjs — whether a path is a link of any kind (a symlink, a junction, or another reparse point that
+// redirects it), read with lstat, readlink and real paths. Every tree walk of the runtime asks it before it enters a
+// directory (safe-remove.mjs, links-under.mjs, the housekeeping collectors), so no walk ever follows a link
+// (inc-c8fbf76aa499).
+import fs from 'node:fs';
+import path from 'node:path';
+import { samePath } from '../../lib/path-key.mjs';
+import { realpathOr } from '../../lib/fs-kind.mjs';
+
+/**
+ * True when `p` is a link of any kind: a symlink, a junction, or another reparse point that redirects it.
+ * `parentReal` (the real path of p's parent, when the caller walked to it through real directories) lets the
+ * real-path test catch a reparse point lstat and readlink do not report. A missing path is not a link.
+ */
+export function isLinkLike(p, { parentReal = null, stat = null } = {}) {
+  let st = stat;
+  if (!st) { try { st = fs.lstatSync(p); } catch { return false; } }
+  if (st.isSymbolicLink()) return true;
+  if (!st.isDirectory()) return false;
+  try { fs.readlinkSync(p); return true; } catch { /* not a link readlink can read */ }
+  const parent = parentReal ?? realpathOr(path.dirname(p));
+  const real = realpathOr(p);
+  if (!parent || !real) return true; // cannot prove it is a plain directory: treat it as a link
+  return !samePath(real, path.join(parent, path.basename(p)));
+}

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

@@ -1,6 +1,14 @@
 // scripts/api/fs/lib.mjs — what the fs call files beside it share: the error codes Windows returns while another
-// process holds a path open. The call files (safe-remove.mjs, rename-over.mjs, rmdir-link.mjs, zip-write.mjs) each
-// name one filesystem use.
+// process holds a path open, and the verified unlink of one link. The call files (safe-remove.mjs, remove-links-under.mjs,
+// rename-over.mjs, zip-write.mjs, ...) each name one filesystem use.
+import fs from 'node:fs';
 
 /** The rename and unlink errors Windows returns while another process holds the target open: retried, never final. */
 export const FS_BUSY = Object.freeze(['EPERM', 'EBUSY', 'EACCES']);
+
+/** Remove a link itself, never its target. True when nothing is left at `p`. */
+export function unlinkOnly(p) {
+  try { fs.lstatSync(p); } catch (error) { return error?.code === 'ENOENT'; }
+  try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* verified below */ } }
+  try { fs.lstatSync(p); return false; } catch (error) { return error?.code === 'ENOENT'; }
+}

package/runtime/scripts/api/fs/safe-remove.mjs

@@ -1,75 +1,35 @@
-// safe-remove.mjs — the ONE way the runtime deletes a directory tree (nivo-fe inc-c8fbf76aa499).
+// safe-remove.mjs — the ONE way the runtime deletes a directory tree.
 //
-// At 05:47 on 2026-09-25 D:/Repositories/nivo-fe lost 674 tracked working-tree files and its node_modules: a
+// A product repository once lost 674 tracked working-tree files and its node_modules: a
 // recursive delete of a scratch tree followed directory links (Windows junctions) into the live repository.
 // Git for Windows' `git worktree remove --force` follows a junction inside the worktree and empties its target
 // (proven on this host, git 2.52), and a PowerShell/cmd/third-party recursive delete may do the same. A tree
 // that holds links to live checkouts is exactly what the runtime makes (node_modules junctions in land and
 // worker staging checkouts, push-mains scratch worktrees, dependency mirrors).
 //
-// safeRemoveTree walks the tree itself with lstat and NEVER descends into a link: every symlink, junction or
+// safeRemove walks the tree itself with lstat and NEVER descends into a link: every symlink, junction or
 // other reparse point is unlinked as a link (the link only, never what it points at) and verified gone. A
 // directory counts as a link when lstat says so, when readlink resolves it, or when its real path is not
 // its own path under its parent's real path (any name-surrogate reparse point). A link that cannot be
 // unlinked stops the removal of everything above it; nothing is ever deleted through it.
 //
 // A worktree's removal composes this with git (scripts/machine/worktree-git.mjs safeRemoveWorktree, the Orca home in
-// scripts/machine/worktree-orca.mjs): every link removed as a link first (removeLinksUnder), zero asserted, only then git
-// or Orca. Whether a tree holds an indexed job artifact is the caller's decision (`hold`: scripts/machine/artifact-hold.mjs
-// artifactHoldReason), taken before anything is deleted.
+// scripts/machine/worktree-orca.mjs): every link removed as a link first (remove-links-under.mjs), zero asserted, only then
+// git or Orca. The link test is is-link-like.mjs, the refused roots forbidden-root.mjs. Whether a tree holds an indexed
+// job artifact is the caller's decision (`hold`: scripts/machine/artifact-hold.mjs artifactHoldReason), taken before
+// anything is deleted.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { sleepSync } from '../../lib/sleep-sync.mjs';
 import { samePath } from '../../lib/path-key.mjs';
-import { rmdirLink } from './rmdir-link.mjs';
-import { FS_BUSY } from './lib.mjs';
 import { realpathOr } from '../../lib/fs-kind.mjs';
+import { FS_BUSY, unlinkOnly } from './lib.mjs';
+import { isLinkLike } from './is-link-like.mjs';
+import { forbiddenRoot } from './forbidden-root.mjs';
 
 const WIN = process.platform === 'win32';
 const same = samePath;
 
-/**
- * True when `p` is a link of any kind: a symlink, a junction, or another reparse point that redirects it.
- * `parentReal` (the real path of p's parent, when the caller walked to it through real directories) lets the
- * real-path test catch a reparse point lstat and readlink do not report. A missing path is not a link.
- */
-export function isLinkLike(p, { parentReal = null, stat = null } = {}) {
-  let st = stat;
-  if (!st) { try { st = fs.lstatSync(p); } catch { return false; } }
-  if (st.isSymbolicLink()) return true;
-  if (!st.isDirectory()) return false;
-  try { fs.readlinkSync(p); return true; } catch { /* not a link readlink can read */ }
-  const parent = parentReal ?? realpathOr(path.dirname(p));
-  const real = realpathOr(p);
-  if (!parent || !real) return true; // cannot prove it is a plain directory: treat it as a link
-  return !same(real, path.join(parent, path.basename(p)));
-}
-
-/** Remove a link itself, never its target. True when nothing is left at `p`. */
-/** Every link (symlink, junction, other reparse point) under root, found with lstat; the walk never enters one. */
-export function linksUnder(root) {
-  const found = [];
-  const visit = (p, parentReal) => {
-    let stat;
-    try { stat = fs.lstatSync(p); } catch { return; }
-    if (isLinkLike(p, { parentReal, stat })) { found.push(p); return; }
-    if (!stat.isDirectory()) return;
-    let real, names;
-    try { real = fs.realpathSync.native(p); names = fs.readdirSync(p); } catch { return; }
-    for (const name of names) visit(path.join(p, name), real);
-  };
-  visit(path.resolve(root), null);
-  return found;
-}
-
-export function unlinkOnly(p) {
-  try { fs.lstatSync(p); } catch (error) { return error?.code === 'ENOENT'; }
-  try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* verified below */ } }
-  try { fs.lstatSync(p); return false; } catch (error) { return error?.code === 'ENOENT'; }
-}
-
 const retrying = (fn, retries) => {
   for (let attempt = 0; ; attempt += 1) {
     try { fn(); return null; } catch (error) {
@@ -85,54 +45,12 @@ const removeFile = (p, retries) => retrying(() => {
   }
 }, retries);
 
-const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
-/**
- * True when `p` sits strictly below `root` by real path: no link on the way, not `root` itself. The one place a
- * primary checkout may be removed is a disposable fixture a caller names by its temp root (hk-tmp).
- */
-export function strictlyInsideReal(p, root) {
-  if (!root) return false;
-  const rel = path.relative(path.resolve(root), path.resolve(p));
-  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
-  const real = realpathOr(p);
-  const rootReal = realpathOr(root);
-  // Its real path must be the same relative place under the root's real path: no link between them.
-  return Boolean(real && rootReal) && same(real, path.join(rootReal, rel));
-}
-
-/**
- * A path the runtime must never remove whole: a filesystem root, the home or temp directory, the runtime, the
- * repository that hosts it, the repositories root, or a primary git checkout (its .git is a directory; the
- * scratch trees the runtime removes are temp directories and linked worktrees, whose .git is a file).
- * `checkoutsUnder` names a disposable root (hk-tmp's temp root): a checkout strictly inside it by real path
- * is a spec fixture, not a live repository, and is not refused for its .git. Every other refusal stands.
- * `hold(path)` is the caller's artifact-hold check (scripts/machine/artifact-hold.mjs artifactHoldReason: a tree holding
- * an indexed job artifact, or inside an evidence directory holding one, whatever the workflow's phase), its refusal line
- * or null. It is required: without one every path is refused (fail closed); a caller that removes only a scratch tree
- * it made itself, outside every ledger's repository, says so with `hold: () => null`.
- */
-export function forbiddenRoot(p, { checkoutsUnder = null, hold } = {}) {
-  const resolved = path.resolve(p);
-  if (path.parse(resolved).root === resolved || same(path.dirname(resolved), resolved)) return 'a filesystem root';
-  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the runtime', SKILL_ROOT],
-    ['the repository hosting the runtime', path.dirname(SKILL_ROOT)], ['the repositories root', path.dirname(path.dirname(SKILL_ROOT))]]) {
-    if (dir && same(path.resolve(dir), resolved)) return name;
-  }
-  if (typeof hold !== 'function') return 'a tree no artifact-hold check cleared (pass hold)';
-  const held = hold(resolved);
-  if (held) return held;
-  let checkout = false;
-  try { checkout = fs.lstatSync(path.join(resolved, '.git')).isDirectory(); } catch { /* no .git directory */ }
-  if (checkout && !strictlyInsideReal(resolved, checkoutsUnder)) return 'a git checkout';
-  return null;
-}
-
 /**
  * Remove `root` and everything under it without ever following a link. Links are unlinked (the link only);
- * plain files and directories are deleted bottom-up. `checkoutsUnder` and `hold` (required) are forbiddenRoot's. Returns {ok, root, removed: {files, dirs, links},
+ * plain files and directories are deleted bottom-up. `checkoutsUnder` and `hold` (required) are forbidden-root.mjs forbiddenRoot's. Returns {ok, root, removed: {files, dirs, links},
  * errors: [{path, code, message}]}; ok is true only when `root` is gone. A missing root is ok.
  */
-export function safeRemoveTree(root, { retries = 5, checkoutsUnder = null, hold } = {}) {
+export function safeRemove(root, { retries = 5, checkoutsUnder = null, hold } = {}) {
   const target = path.resolve(String(root ?? ''));
   const out = { ok: false, root: target, removed: { files: 0, dirs: 0, links: 0 }, errors: [] };
   const fail = (p, error) => { out.errors.push({ path: p, code: error?.code ?? 'ERROR', message: String(error?.message ?? error) }); };
@@ -184,41 +102,3 @@ export function safeRemoveTree(root, { retries = 5, checkoutsUnder = null, hold
   out.ok = !fs.existsSync(target) && (() => { try { fs.lstatSync(target); return false; } catch { return true; } })();
   return out;
 }
-
-/** Remove one link as a link, never its target: `cmd /c rmdir <link>` on Windows (no /s), then unlinkOnly. */
-export function removeLink(p) {
-  if (WIN) {
-    let st = null;
-    try { st = fs.lstatSync(p); } catch { return true; }
-    if (st.isDirectory() || st.isSymbolicLink()) rmdirLink(p);
-  }
-  return unlinkOnly(p);
-}
-
-/**
- * The link step of every worktree removal (scripts/machine/worktree-git.mjs safeRemoveWorktree, worktree-orca.mjs removeOrcaWorktree): every link
- * under `target` found WITHOUT following one (linksUnder), each removed as a link (removeLink: `cmd /c rmdir <link>`, never
- * /s), outermost first, then a re-scan that must find ZERO. {ok, links, errors: [{path, code, message}]}; ok false: a link
- * is stuck and the caller removes nothing.
- */
-export function removeLinksUnder(target) {
-  const out = { ok: false, links: 0, errors: [] };
-  if (!fs.existsSync(target)) { out.ok = true; return out; }
-  for (const link of linksUnder(target)) { if (removeLink(link)) out.links += 1; else out.errors.push({ path: link, code: 'LINK_STUCK', message: 'a link could not be removed' }); }
-  for (const l of linksUnder(target)) if (!out.errors.some((e) => e.path === l)) out.errors.push({ path: l, code: 'LINK_STUCK', message: 'a link is still there after removal' });
-  out.ok = out.errors.length === 0;
-  return out;
-}
-
-/**
- * Unlink `<dir>/node_modules` when it is a link (one an older runtime made; no runtime code makes one, RT_NODE_MODULES_LINK).
- * true when no link is left there; a real directory is left alone (true: it is the checkout's own).
- */
-export function unlinkNodeModulesLink(dir) {
-  const nm = path.join(dir, 'node_modules');
-  let st;
-  try { st = fs.lstatSync(nm); } catch { return true; }
-  if (!st.isSymbolicLink()) return true;
-  try { fs.unlinkSync(nm); } catch { try { fs.rmdirSync(nm); } catch { /* checked below */ } }
-  try { fs.lstatSync(nm); return false; } catch { return true; }
-}

package/runtime/scripts/api/git/config-get.mjs

@@ -0,0 +1,10 @@
+// config-get.mjs — `git config [--local] --get <key>`: one configuration value of a checkout (empty when unset).
+import { gitRunner } from './lib.mjs';
+
+/**
+ * {ok, stdout, stderr}; `local` reads the repository's own config only; `env` replaces the process env (a caller drops
+ * git's repository-local variables). git: the caller's runner or null.
+ */
+export function configGet(cwd, key, { local = false, env = undefined, git = null } = {}) {
+  return gitRunner(git)(['config', ...(local ? ['--local'] : []), '--get', key], env ? { cwd, env } : { cwd });
+}

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

@@ -0,0 +1,5 @@
+// diff.mjs — `git diff <args>`: the changes between commits, the index and the working tree.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git diff ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const diff = (args = [], options = {}) => runGit(['diff', ...args], options);

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

@@ -1,12 +1,13 @@
 // scripts/api/git/lib.mjs — the one place the runtime spawns git (RT_EXTERNAL_OWNER of scripts/hfs/runtime-rules/external-owner.mjs enforces it).
 //
 // Every caller spelt the same options by hand - encoding:'utf8', windowsHide:true, sometimes a timeout - with two shapes:
-// `git args` in a cwd and `git -C dir args`. gitOutput is the throwing shape (stdout text, or an Error on a non-zero exit).
-// gitSpawn keeps the spawnSync(file, args, options) signature so an injected runner or a spec's fake takes the same three
-// arguments; runGit is the `-C` convenience; gitResult folds the result into the {ok, stdout, error} envelope; gitRunner
-// folds any caller's runner into {ok, stdout, stderr}. The call files beside this one (worktree-*.mjs, rev-parse.mjs, ...)
-// each name one git verb.
+// `git args` in a cwd and `git -C dir args`. gitSpawn keeps the spawnSync(file, args, options) signature so an injected
+// runner or a spec's fake takes the same three arguments; runGit is the `-C` / `-c` convenience; gitRunner folds any
+// caller's runner into {ok, stdout, stderr}. Only the call files beside this one import it: each names one git verb
+// (diff.mjs, ls-files.mjs, worktree-*.mjs, ...), and a caller folds the spawn result it gets back with the pure
+// helpers of scripts/lib/git.mjs (gitResultOf, gitOutputOf).
 import { spawnSync } from 'node:child_process';
+import { withoutGitLocalEnv } from '../../lib/git.mjs';
 
 /**
  * Spawn `file` (the git binary) once with `args`: utf8 text, a hidden window, never a shell.
@@ -20,27 +21,16 @@ export const gitSpawn = (file, args, options = {}) => {
   return spawnSync(file, args, spawn);
 };
 
-/** `git args` in `cwd`, or `git -C dir args` when `dir` is given. `git` overrides the binary. */
-export const runGit = (args, { cwd = null, dir = null, git = 'git', ...options } = {}) =>
-  gitSpawn(git, [...(dir ? ['-C', dir] : []), ...args], cwd ? { cwd, ...options } : options);
-
-/** runGit's stdout as text; throws the spawn error, or an Error carrying git's stderr and exit status, unless git exits 0. */
-export function gitOutput(args, options = {}) {
-  const r = runGit(args, options);
-  if (r.error) throw r.error;
-  if (r.status !== 0) throw Object.assign(new Error(`git ${args.join(' ')} exited ${r.status}: ${(r.stderr ?? '').trim()}`), { status: r.status, stderr: r.stderr });
-  return r.stdout;
-}
-
-/** runGit's result as {ok, stdout, error}: ok only on a clean exit, error from stderr or the spawn. */
-export function gitResult(args, options = {}) {
-  const r = runGit(args, options);
-  return {
-    ok: !r.error && r.status === 0,
-    stdout: r.stdout ?? '',
-    error: (r.stderr ?? '').trim() || String(r.error?.message ?? (r.status == null ? 'timed out' : `exit ${r.status}`)),
-  };
-}
+/**
+ * `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], {
+    ...(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}) ->

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

@@ -0,0 +1,5 @@
+// log.mjs — `git log <args>`: the commit history in a caller-chosen format.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git log ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const log = (args = [], options = {}) => runGit(['log', ...args], options);

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

@@ -0,0 +1,6 @@
+// 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.mjs

@@ -0,0 +1,5 @@
+// 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.mjs

@@ -0,0 +1,9 @@
+// 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;
+};

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

@@ -0,0 +1,5 @@
+// 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.mjs

@@ -0,0 +1,5 @@
+// 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.mjs

@@ -0,0 +1,6 @@
+// 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/sops/decrypt.mjs

@@ -1,15 +1,19 @@
 // decrypt.mjs — one `sops` decryption: the custody reads (scripts/api/sops/exec-env.mjs execEnv) and the test
-// secrets (scripts/lib/test-secrets.mjs testSecret). The plaintext stays in this process's memory (stdout over a pipe).
+// secrets (scripts/uat/test-secret.mjs testSecret). The plaintext stays in this process's memory (stdout over a pipe).
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { resolveSops } from './lib.mjs';
 
 /**
- * Run `<bin> <args>` with SOPS_AGE_KEY_FILE defaulted to ~/.starci/master.identity. {status, stdout, stderr, error}.
+ * Run `<bin> <args>` (bin null: the sops resolveSops finds) with SOPS_AGE_KEY_FILE defaulted to ~/.starci/master.identity.
+ * {status, stdout, stderr, error}; a missing sops is {status: null, error: SOPS_MISSING}.
  */
-export function sopsDecrypt(bin, args, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024 } = {}) {
-  const r = spawnSync(bin, args, {
-    cwd, encoding: 'utf8', windowsHide: true, maxBuffer,
+export function decrypt(bin, args, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
+  const exe = bin ?? resolveSops(env);
+  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+  const r = spawnSync(exe, args, {
+    cwd, encoding: 'utf8', windowsHide: true, maxBuffer, timeout,
     env: { ...env, SOPS_AGE_KEY_FILE: env.SOPS_AGE_KEY_FILE || path.join(os.homedir(), '.starci', 'master.identity') },
   });
   return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };

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

@@ -0,0 +1,35 @@
+// scripts/api/sops/lib.mjs — what the sops call files beside it share: the input type a custody file's name states.
+// Custody members are committed as `<name>.<fmt>.enc`; sops infers a format from the LAST extension, so `.enc` reads as
+// binary and every read states the format (--input-type). The call files (decrypt.mjs, encrypt.mjs, exec-env.mjs) each
+// name one sops use.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FORMATS = { yaml: 'yaml', yml: 'yaml', json: 'json', env: 'dotenv', dotenv: 'dotenv' };
+
+/** The sops input type `<name>.<format>.enc` states, or the explicit override. Throws when neither names one. */
+export function custodyInputType(file, override) {
+  if (override) {
+    if (!Object.values(FORMATS).includes(override)) throw new Error(`unsupported --input-type ${override}`);
+    return override;
+  }
+  const match = /\.([a-z]+)\.enc$/iu.exec(String(file));
+  const type = match ? FORMATS[match[1].toLowerCase()] : undefined;
+  if (!type) throw new Error(`${file}: name it <name>.<yaml|json|env>.enc or pass --input-type`);
+  return type;
+}
+
+/** The sops binary: PATH, then winget's Links and Packages (spawn without a shell ignores PATHEXT). */
+export function resolveSops(env = process.env) {
+  const win = process.platform === 'win32';
+  const names = win ? ['sops.exe', 'sops'] : ['sops'];
+  const dirs = String(env.PATH ?? '').split(win ? ';' : ':').filter(Boolean);
+  if (win && env.LOCALAPPDATA) {
+    const winget = path.join(env.LOCALAPPDATA, 'Microsoft', 'WinGet');
+    dirs.push(path.join(winget, 'Links'));
+    const packages = path.join(winget, 'Packages');
+    try { for (const e of fs.readdirSync(packages)) if (/sops/i.test(e)) dirs.push(path.join(packages, e)); } catch { /* none */ }
+  }
+  for (const dir of dirs) for (const n of names) { const f = path.join(dir, n); try { if (fs.statSync(f).isFile()) return f; } catch { /* next */ } }
+  return null;
+}

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

@@ -0,0 +1,18 @@
+// seal.mjs - one `sops encrypt` of a plaintext document held in memory: the canon command `starci app secret set` and `starci app secret gen`
+// (scripts/hfs/secret.mjs). The plaintext travels on the child's stdin and never on its argument list, so it is not visible in a
+// process listing; the ciphertext comes back on stdout.
+import { spawnSync } from 'node:child_process';
+import { resolveSops } from './lib.mjs';
+
+/**
+ * Run `<bin> encrypt` (bin null: the sops resolveSops finds) over `plaintext` of format `inputType` (json, yaml or dotenv). Sops reads stdin only with a `--filename-override`, the path the sealed
+ * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. {status, stdout, stderr, error}.
+ */
+export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride }, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  const args = ['encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
+  if (recipients.length) args.push('--age', recipients.join(','));
+  const exe = bin ?? resolveSops(env);
+  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+  const r = spawnSync(exe, args, { cwd, env, input: plaintext, encoding: 'utf8', windowsHide: true, maxBuffer });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+}