@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/api/fs/ensure-temp-root.mjs

@@ -0,0 +1,27 @@
+// ensure-temp-root.mjs — the temp root exists and takes writes before anything is placed in it or a child is started with TEMP/TMP/TMPDIR pointing at it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { tempRoot, TEMP_ROOT_ENV } from '../../../engine/temp-root.mjs';
+
+const TEMP_ROOT_UNUSABLE = 'TEMP_ROOT_UNUSABLE';
+const writable = new Set();
+
+const unusable = (root, reason) => Object.assign(new Error(`${TEMP_ROOT_UNUSABLE}: the temp root ${root} ${reason}; set roots.temp in config.yaml (or ${TEMP_ROOT_ENV}) to a directory the runtime can create and write - it is not replaced by the operating-system temp directory`), { code: TEMP_ROOT_UNUSABLE, root });
+
+/** Writes and removes one probe file in `root`: a directory that exists can still refuse writes. */
+function probeWritable(root) {
+  const probe = path.join(root, `.starci-write-probe-${process.pid}`);
+  fs.writeFileSync(probe, '');
+  fs.rmSync(probe, { force: true });
+}
+
+/** The temp root of `env`, created when it is missing. Throws an Error with code TEMP_ROOT_UNUSABLE when it cannot be created or written. */
+export function ensureTempRoot({ env = process.env } = {}) {
+  const root = tempRoot({ env });
+  try {
+    fs.mkdirSync(root, { recursive: true });
+    if (!writable.has(root)) probeWritable(root);
+  } catch (error) { throw unusable(root, `cannot be created or written (${error.code ?? error.message})`); }
+  writable.add(root);
+  return root;
+}

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

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { samePath } from '../../lib/path-key.mjs';
 import { realpathOr } from '../../lib/fs-kind.mjs';
+import { tempRoot } from '../../../engine/temp-root.mjs';
 
 const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
@@ -37,7 +38,7 @@ function strictlyInsideReal(p, root) {
 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],
+  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the configured temp root', tempRoot()], ['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;
   }

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

@@ -12,3 +12,9 @@ export function unlinkOnly(p) {
   try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* verified below */ } }
   try { fs.lstatSync(p); return false; } catch (error) { return error?.code === 'ENOENT'; }
 }
+
+/** Construct an archive-reader refusal with its existing error code. */
+export const zipRefuse = (message, code = 'zip-corrupt') => Object.assign(new Error(message), { code });
+
+/** Relative ZIP entry names exclude traversal, drive roots and control characters. */
+export const validZipName=name=>Boolean(name)&&!name.startsWith('/')&&!/^[A-Za-z]:/.test(name)&&!/[\0\r\n\\]/.test(name)&&!name.split('/').includes('..');

package/runtime/scripts/api/fs/make-temp-dir.mjs

@@ -0,0 +1,11 @@
+// make-temp-dir.mjs — a fresh temporary directory under the temp root (engine/temp-root.mjs tempRoot).
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureTempRoot } from './ensure-temp-root.mjs';
+
+/** A new directory `<prefix><random>` under `parent` (default the temp root, ensureTempRoot: TEMP_ROOT_UNUSABLE when it cannot be made), which is created when it is missing. */
+export function makeTempDir(prefix, { env = process.env, parent = undefined } = {}) {
+  const root = parent ?? ensureTempRoot({ env });
+  fs.mkdirSync(root, { recursive: true });
+  return fs.mkdtempSync(path.join(root, prefix));
+}

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

@@ -41,7 +41,7 @@ const retrying = (fn, retries) => {
 };
 const removeFile = (p, retries) => retrying(() => {
   try { fs.unlinkSync(p); } catch (error) {
-    if (WIN && (error?.code === 'EPERM' || error?.code === 'EACCES')) { fs.chmodSync(p, 0o666); fs.unlinkSync(p); } else throw error;
+    if (WIN && (error?.code === 'EPERM' || error?.code === 'EACCES')) { fs.chmodSync(p, 0o600); fs.unlinkSync(p); } else throw error;
   }
 }, retries);
 
@@ -65,40 +65,57 @@ export function safeRemove(root, { retries = 5, checkoutsUnder = null, hold } =
   // the root itself or strictly under the root's real path. A link is unlinked above (the link only); any other
   // entry that resolves outside the tree is refused, whatever made it look like a plain entry.
   const rootReal = realpathOr(target);
-  const insideRoot = (p) => { const real = realpathOr(p); if (!real || !rootReal) return false; if (same(real, rootReal)) return true;
-    const rel = path.relative(rootReal, real); return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel); };
-  const walk = (dir, st, parentReal) => {
-    if (isLinkLike(dir, { parentReal, stat: st })) {
-      if (unlinkOnly(dir)) { out.removed.links += 1; return true; }
-      fail(dir, { code: 'LINK_STUCK', message: 'a link could not be unlinked; nothing above it is removed' });
-      return false;
-    }
-    if (!insideRoot(dir)) {
-      fail(dir, { code: 'OUTSIDE_ROOT', message: `refusing to delete ${dir}: its real path ${realpathOr(dir) ?? '?'} is outside ${rootReal ?? target}` });
-      return false;
-    }
-    if (!st.isDirectory()) {
-      const error = removeFile(dir, retries);
-      if (error) { fail(dir, error); return false; }
-      out.removed.files += 1; return true;
-    }
-    const real = realpathOr(dir);
-    if (!real) { fail(dir, { code: 'REALPATH', message: 'cannot resolve the directory' }); return false; }
-    let entries;
-    try { entries = fs.readdirSync(dir); } catch (error) { fail(dir, error); return false; }
-    let clear = true;
-    for (const name of entries) {
-      const child = path.join(dir, name);
-      let childStat;
-      try { childStat = fs.lstatSync(child); } catch (error) { if (error?.code !== 'ENOENT') { fail(child, error); clear = false; } continue; }
-      if (!walk(child, childStat, real)) clear = false;
-    }
-    if (!clear) return false;
-    const error = retrying(() => fs.rmdirSync(dir), retries);
-    if (error) { fail(dir, error); return false; }
-    out.removed.dirs += 1; return true;
-  };
-  walk(target, st, null);
+  const ctx = { out, fail, retries, rootReal, target };
+  walk(ctx, target, st, null);
   out.ok = !fs.existsSync(target) && (() => { try { fs.lstatSync(target); return false; } catch { return true; } })();
   return out;
 }
+
+function insideRoot({ rootReal }, p) {
+  const real = realpathOr(p);
+  if (!real || !rootReal) return false;
+  if (same(real, rootReal)) return true;
+  const rel = path.relative(rootReal, real);
+  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Removes each child of `dir` (real path `real`); false when any child stays.
+function removeChildren(ctx, dir, entries, real) {
+  let clear = true;
+  for (const name of entries) {
+    const child = path.join(dir, name);
+    let childStat;
+    try { childStat = fs.lstatSync(child); } catch (error) { if (error?.code !== 'ENOENT') { ctx.fail(child, error); clear = false; } continue; }
+    if (!walk(ctx, child, childStat, real)) clear = false;
+  }
+  return clear;
+}
+
+function walkDirectory(ctx, dir) {
+  const { out, fail, retries } = ctx;
+  const real = realpathOr(dir);
+  if (!real) { fail(dir, { code: 'REALPATH', message: 'cannot resolve the directory' }); return false; }
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch (error) { fail(dir, error); return false; }
+  if (!removeChildren(ctx, dir, entries, real)) return false;
+  const error = retrying(() => fs.rmdirSync(dir), retries);
+  if (error) { fail(dir, error); return false; }
+  out.removed.dirs += 1; return true;
+}
+
+function walk(ctx, dir, st, parentReal) {
+  const { out, fail, retries, rootReal, target } = ctx;
+  if (isLinkLike(dir, { parentReal, stat: st })) {
+    if (unlinkOnly(dir)) { out.removed.links += 1; return true; }
+    fail(dir, { code: 'LINK_STUCK', message: 'a link could not be unlinked; nothing above it is removed' });
+    return false;
+  }
+  if (!insideRoot(ctx, dir)) {
+    fail(dir, { code: 'OUTSIDE_ROOT', message: `refusing to delete ${dir}: its real path ${realpathOr(dir) ?? '?'} is outside ${rootReal ?? target}` });
+    return false;
+  }
+  if (st.isDirectory()) return walkDirectory(ctx, dir);
+  const error = removeFile(dir, retries);
+  if (error) { fail(dir, error); return false; }
+  out.removed.files += 1; return true;
+}

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

@@ -6,8 +6,13 @@
 // 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 { assertMutationFence } from '../../lib/mutation-fence.mjs';
+import fs from 'node:fs';
+import os from 'node:os';
+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.
@@ -16,9 +21,11 @@ import { withoutGitLocalEnv } from '../../lib/git.mjs';
  * ERR_UNKNOWN_ENCODING, so it reaches spawnSync as encoding:null (Buffer output either way).
  */
 export const gitSpawn = (file, args, options = {}) => {
+  assertMutationFence({ kind: 'git-effect', args });
   const spawn = { encoding: 'utf8', windowsHide: true, ...options };
   if (spawn.encoding === 'buffer') spawn.encoding = null;
-  return spawnSync(file, args, spawn);
+  // 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));
 };
 
 /**
@@ -40,3 +47,31 @@ 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() };
 };
+
+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;
+};
+/**
+ * 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 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;
+};

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

@@ -0,0 +1,52 @@
+// resolve-real-tool.mjs - find the host executable behind a StarCi PATH wrapper without ever selecting that wrapper again.
+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 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;
+};
+
+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)];
+};
+
+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;
+};
+
+/** 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;
+}

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

@@ -0,0 +1,8 @@
+// run-program.mjs — run one declared program argv (`file args`, never a shell), waited for: a UAT policy command of an
+// assisted run (scripts/uat/assisted-runner.mjs), resolved to its file by scripts/uat/launch.mjs launchFor. Returns the
+// 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 }));

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

@@ -1,20 +1,13 @@
-// decrypt.mjs — one `sops` decryption: the custody reads (scripts/api/sops/exec-env.mjs execEnv) and the test
-// 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';
+// decrypt.mjs — the public SOPS file-decrypt call.
+import { runSopsFile } from './lib.mjs';
 
 /**
- * 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}.
+ * 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 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 };
+export function decrypt(bin, args, options = {}) {
+  return runSopsFile(bin, args, 'decrypt', options);
 }