@forwardimpact/libutil 0.1.84 → 0.1.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libutil",
-  "version": "0.1.84",
+  "version": "0.1.85",
   "description": "Cross-cutting utilities: retry, hashing, token counting, and project discovery.",
   "keywords": [
     "util",
@@ -21,6 +21,9 @@
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./runtime": "./src/runtime.js",
+    "./git-client": "./src/git-client.js",
+    "./gh-client": "./src/gh-client.js",
     "./bin/fit-download-bundle.js": "./bin/fit-download-bundle.js",
     "./bin/fit-tiktoken.js": "./bin/fit-tiktoken.js"
   },

package/src/calendar.js

@@ -0,0 +1,84 @@
+// Pure calendar arithmetic on explicit date inputs.
+//
+// Every `new Date(...)` here operates only on a value the caller passed (a ms
+// timestamp, a `Date`, or an ISO string) — never the ambient wall clock, which
+// lives behind `runtime.clock.now()`. That is why this module is allow-listed
+// in `scripts/check-ambient-deps.allow.yml` for the same reason `runtime.js`
+// is: it produces deterministic time values from its arguments rather than
+// reaching for an ambient dependency. Consumers read "now" from
+// `runtime.clock.now()` and pass the result here when they need a formatted or
+// shifted calendar value.
+
+/**
+ * Normalise an input into a `Date`. Accepts a `Date`, a ms timestamp, or any
+ * string `Date` understands (notably an ISO `YYYY-MM-DD` date).
+ * @param {Date|number|string} input
+ * @returns {Date}
+ */
+function toDate(input) {
+  return input instanceof Date ? input : new Date(input);
+}
+
+/**
+ * Format an input as an ISO calendar date (`YYYY-MM-DD`, UTC).
+ * @param {Date|number|string} input
+ * @returns {string}
+ */
+export function isoDate(input) {
+  return toDate(input).toISOString().slice(0, 10);
+}
+
+/**
+ * Compute the ISO 8601 year-week for an input. `year` is the ISO week-year
+ * (not necessarily the calendar year for edge weeks).
+ * @param {Date|number|string} input
+ * @returns {{year: number, week: number}}
+ */
+export function isoWeek(input) {
+  const date = toDate(input);
+  // Anchor on Thursday of the week: ISO weeks belong to the year of their
+  // Thursday.
+  const d = new Date(
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+  );
+  const day = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - day);
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((d - yearStart) / 86400000 + 1) / 7);
+  return { year: d.getUTCFullYear(), week };
+}
+
+/**
+ * Format an input as `YYYY-Www` (e.g. `2026-W22`).
+ * @param {Date|number|string} input
+ * @returns {string}
+ */
+export function isoWeekString(input) {
+  const { year, week } = isoWeek(input);
+  return `${year}-W${String(week).padStart(2, "0")}`;
+}
+
+/**
+ * Format an input as `YYYY-Mmm` (e.g. `2026-M05`, UTC month).
+ * @param {Date|number|string} input
+ * @returns {string}
+ */
+export function yearMonth(input) {
+  const d = toDate(input);
+  const yyyy = d.getUTCFullYear();
+  const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+  return `${yyyy}-M${mm}`;
+}
+
+/**
+ * Shift an input by `n` whole days (UTC) and return the ISO calendar date.
+ * Negative `n` moves backward. The input is never mutated.
+ * @param {Date|number|string} input
+ * @param {number} n - Days to add (may be negative).
+ * @returns {string}
+ */
+export function addDays(input, n) {
+  const d = new Date(toDate(input).getTime());
+  d.setUTCDate(d.getUTCDate() + n);
+  return d.toISOString().slice(0, 10);
+}

package/src/finder.js

@@ -1,43 +1,95 @@
-import fs from "fs";
-import fsAsync from "fs/promises";
+import nodeFsSync from "node:fs";
+import nodeFsPromises from "node:fs/promises";
 import path from "path";
 import { createRequire } from "node:module";
 
+const NOOP_LOGGER = { debug() {} };
+
 /**
- * Finder class for project path resolution and symlink management
- * Handles filesystem operations for linking generated code to packages
+ * Detect the new collaborator-config constructor form. The legacy positional
+ * form passes an fs module as the first argument (which carries `readFile`);
+ * the new form passes `{ fs, fsSync?, proc, logger? }`.
+ * @param {*} arg - The first constructor argument.
+ * @returns {boolean}
+ */
+function isRuntimeConfig(arg) {
+  return (
+    arg != null &&
+    typeof arg === "object" &&
+    !Array.isArray(arg) &&
+    (arg.proc !== undefined ||
+      arg.fsSync !== undefined ||
+      (arg.fs !== undefined && typeof arg.readFile !== "function"))
+  );
+}
+
+/**
+ * Finder class for project path resolution and symlink management.
+ * Handles filesystem operations for linking generated code to packages.
+ *
+ * Two constructor forms are supported during the ambient-to-injected migration:
+ *
+ * - Collaborator config (canonical): `new Finder({ fs, fsSync?, proc, logger? })`.
+ *   The injected `fs` (async) and `fsSync` (sync, for existence checks) flow
+ *   through to every internal call — the spec-flagged dead-`fs` bug is fixed.
+ * - Legacy positional (deprecated, one migration cycle):
+ *   `new Finder(fs, logger, process)`. Preserved byte-for-byte so existing
+ *   call sites stay green until their per-unit migration PRs convert them.
  */
 export class Finder {
+  #fs;
+  #existsSync;
   #logger;
-  #process;
+  #proc;
 
   /**
-   * Creates a new Finder instance
-   * @param {object} fs - Filesystem module (fs/promises)
-   * @param {object} logger - Logger instance for debug output
-   * @param {object} process - Process environment access (for testing)
+   * @param {object} fsOrConfig - Either `{ fs, fsSync?, proc, logger? }` (new)
+   *   or the async fs module (legacy positional first argument).
+   * @param {object} [logger] - Legacy positional logger.
+   * @param {object} [proc] - Legacy positional process (cwd provider).
    */
-  constructor(fs, logger, process = global.process) {
-    if (!fs) throw new Error("fs is required");
+  constructor(fsOrConfig, logger, proc = global.process) {
+    if (isRuntimeConfig(fsOrConfig)) {
+      // Finder is the one module that legitimately bridges the sync and async
+      // fs surfaces (existence checks vs. symlink ops), so it reads both fields
+      // by property access rather than a single `{ fs, fsSync }` destructure
+      // (which design Decision 7 reserves for consumer modules).
+      const fs = fsOrConfig.fs;
+      const fsSync = fsOrConfig.fsSync;
+      const procArg = fsOrConfig.proc;
+      if (!fs) throw new Error("fs is required");
+      if (!procArg) throw new Error("proc is required");
+      this.#fs = fs;
+      const existsTarget = fsSync ?? fs;
+      this.#existsSync = existsTarget.existsSync.bind(existsTarget);
+      this.#proc = procArg;
+      this.#logger = fsOrConfig.logger ?? NOOP_LOGGER;
+      return;
+    }
+    // Legacy positional form: behavior identical to the pre-1370 Finder —
+    // every fs operation routes through the module-level node:fs imports
+    // (the historical dead-`fs` behavior callers depend on).
+    if (!fsOrConfig) throw new Error("fs is required");
     if (!logger) throw new Error("logger is required");
-    if (!process) throw new Error("process is required");
-
+    if (!proc) throw new Error("process is required");
+    this.#fs = nodeFsPromises;
+    this.#existsSync = (p) => nodeFsSync.existsSync(p);
     this.#logger = logger;
-    this.#process = process;
+    this.#proc = proc;
   }
 
   /**
-   * Searches upward from one or more roots for a target file or directory.
+   * Searches upward from a root for a target file or directory.
    * @param {string} root - Starting directory to search from
    * @param {string} relativePath - Relative path to append while traversing upward
-   * @param {number} maxDepth - Maximum parent levels to check
+   * @param {number} [maxDepth=3] - Maximum parent levels to check
    * @returns {string|null} Found absolute path or null
    */
   findUpward(root, relativePath, maxDepth = 3) {
     let current = root;
     for (let depth = 0; depth < maxDepth; depth++) {
       const candidate = path.join(current, relativePath);
-      if (fs.existsSync(candidate)) {
+      if (this.#existsSync(candidate)) {
         return candidate;
       }
       const parent = path.dirname(current);
@@ -54,12 +106,12 @@ export class Finder {
    * @returns {string} Absolute path to found directory
    */
   findData(baseName, homeDir) {
-    const cwd = this.#process.cwd();
+    const cwd = this.#proc.cwd();
     const found = this.findUpward(cwd, baseName);
     if (found) return found;
 
     const homePath = path.join(homeDir, ".fit", baseName);
-    if (fs.existsSync(homePath)) return homePath;
+    if (this.#existsSync(homePath)) return homePath;
 
     throw new Error(
       `No ${baseName} directory found from ${cwd} or ${homePath}.`,
@@ -67,7 +119,7 @@ export class Finder {
   }
 
   /**
-   * Find the project root directory
+   * Find the project root directory.
    * @param {string} startPath - Starting directory path
    * @returns {string} Project root directory path
    */
@@ -81,8 +133,8 @@ export class Finder {
   }
 
   /**
-   * Resolve the actual filesystem path to a package
-   * Works both in monorepo (./packages) and when installed as dependency
+   * Resolve the actual filesystem path to a package.
+   * Works both in monorepo (./packages) and when installed as dependency.
    * @param {string} projectRoot - Project root directory path
    * @param {"libtype"|"librpc"} packageName - Package name without scope
    * @returns {string} Absolute path to package directory
@@ -93,7 +145,7 @@ export class Finder {
     // First try local monorepo structures
     for (const dir of ["libraries", "packages"]) {
       const localPath = path.join(projectRoot, dir, packageName);
-      if (fs.existsSync(localPath)) {
+      if (this.#existsSync(localPath)) {
         return localPath;
       }
     }
@@ -107,7 +159,7 @@ export class Finder {
   }
 
   /**
-   * Resolve the generated directory path for a package
+   * Resolve the generated directory path for a package.
    * @param {string} projectRoot - Project root directory path
    * @param {"libtype"|"librpc"} packageName - Package name without scope
    * @returns {string} Absolute path to package's generated directory
@@ -118,32 +170,32 @@ export class Finder {
   }
 
   /**
-   * Create symlink from source to target directory
+   * Create symlink from source to target directory.
    * @param {string} sourcePath - Source directory path
    * @param {string} targetPath - Target directory path
    * @returns {Promise<void>}
    */
   async createSymlink(sourcePath, targetPath) {
     // Ensure the source directory exists
-    await fsAsync.mkdir(sourcePath, { recursive: true });
+    await this.#fs.mkdir(sourcePath, { recursive: true });
 
     // Remove the existing target if it exists
     try {
-      const stats = await fsAsync.lstat(targetPath);
+      const stats = await this.#fs.lstat(targetPath);
       if (stats.isSymbolicLink()) {
-        await fsAsync.unlink(targetPath);
+        await this.#fs.unlink(targetPath);
       } else {
-        await fsAsync.rm(targetPath, { recursive: true, force: true });
+        await this.#fs.rm(targetPath, { recursive: true, force: true });
       }
     } catch {
       // Target doesn't exist, which is fine
     }
 
     // Ensure the target's parent directory exists before symlinking
-    await fsAsync.mkdir(path.dirname(targetPath), { recursive: true });
+    await this.#fs.mkdir(path.dirname(targetPath), { recursive: true });
 
     // Create the symlink
-    await fsAsync.symlink(sourcePath, targetPath, "dir");
+    await this.#fs.symlink(sourcePath, targetPath, "dir");
     this.#logger.debug("Finder", "Created symlink", {
       source_path: sourcePath,
       target_path: targetPath,
@@ -151,13 +203,14 @@ export class Finder {
   }
 
   /**
-   * Create symlinks to the generated directory for standard packages
-   * Attempts to find project root and create symlinks, but won't fail in test environments
+   * Create symlinks to the generated directory for standard packages.
+   * Attempts to find project root and create symlinks, but won't fail in
+   * test environments.
    * @param {string} generatedPath - Path to generated code directory
    * @returns {Promise<void>}
    */
   async createPackageSymlinks(generatedPath) {
-    const projectRoot = this.findProjectRoot(this.#process.cwd());
+    const projectRoot = this.findProjectRoot(this.#proc.cwd());
     const packageNames = ["libtype", "librpc"];
 
     const promises = packageNames.map(async (packageName) => {

package/src/gh-client.js

@@ -0,0 +1,79 @@
+/**
+ * Error thrown when a `gh` subcommand exits non-zero.
+ */
+export class GhError extends Error {
+  /**
+   * @param {string} subcmd - The gh subcommand that failed.
+   * @param {{stdout: string, stderr: string, exitCode: number}} result
+   */
+  constructor(subcmd, result) {
+    super(
+      `gh ${subcmd} failed (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`,
+    );
+    this.name = "GhError";
+    this.exitCode = result.exitCode;
+    this.stdout = result.stdout;
+    this.stderr = result.stderr;
+  }
+}
+
+/**
+ * Typed wrapper over the `gh` CLI. Shelling-out flows through the injected
+ * `runtime.subprocess` so callers never import `node:child_process` and tests
+ * inject `createMockSubprocess`.
+ */
+export class GhClient {
+  #runtime;
+
+  /**
+   * @param {object} options
+   * @param {import('./runtime.js').Runtime} options.runtime - The runtime bag.
+   */
+  constructor({ runtime }) {
+    if (!runtime) throw new Error("runtime is required");
+    this.#runtime = runtime;
+  }
+
+  /** Create a pull request. Returns the new PR URL (stdout). */
+  async prCreate({ cwd, title, body, base, head } = {}) {
+    const args = ["pr", "create"];
+    if (title) args.push("--title", title);
+    if (body) args.push("--body", body);
+    if (base) args.push("--base", base);
+    if (head) args.push("--head", head);
+    const result = await this.#run(args, { cwd });
+    return result.stdout.trim();
+  }
+
+  /** Merge a pull request. */
+  async prMerge(number, { cwd, method = "squash" } = {}) {
+    return this.#run(["pr", "merge", String(number), `--${method}`], { cwd });
+  }
+
+  /** GET an API path; returns parsed JSON. */
+  async apiGet(path, { cwd } = {}) {
+    const result = await this.#run(["api", path], { cwd });
+    return result.stdout.trim() ? JSON.parse(result.stdout) : null;
+  }
+
+  /** POST to an API path with `fields`; returns parsed JSON. */
+  async apiPost(path, fields = {}, { cwd } = {}) {
+    const args = ["api", "--method", "POST", path];
+    for (const [k, v] of Object.entries(fields)) {
+      args.push("-f", `${k}=${v}`);
+    }
+    const result = await this.#run(args, { cwd });
+    return result.stdout.trim() ? JSON.parse(result.stdout) : null;
+  }
+
+  async #run(args, { cwd } = {}) {
+    const result = await this.#runtime.subprocess.run("gh", args, {
+      cwd,
+      env: this.#runtime.proc.env,
+    });
+    if (result.exitCode !== 0) {
+      throw new GhError(args.join(" "), result);
+    }
+    return result;
+  }
+}

package/src/git-client.js

@@ -0,0 +1,169 @@
+/**
+ * Error thrown when a git subcommand exits non-zero.
+ */
+export class GitError extends Error {
+  /**
+   * @param {string} subcmd - The git subcommand that failed.
+   * @param {{stdout: string, stderr: string, exitCode: number}} result
+   */
+  constructor(subcmd, result) {
+    super(
+      `git ${subcmd} failed (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`,
+    );
+    this.name = "GitError";
+    this.exitCode = result.exitCode;
+    this.stdout = result.stdout;
+    this.stderr = result.stderr;
+  }
+}
+
+/**
+ * Typed wrapper over the `git` CLI. All shelling-out flows through the
+ * injected `runtime.subprocess`, so callers never import `node:child_process`
+ * and tests inject `createMockSubprocess`. Methods resolve to the
+ * raw `{ stdout, stderr, exitCode }` result; `#run` throws a {@link GitError}
+ * on a non-zero exit unless `allowFailure` is set.
+ */
+export class GitClient {
+  #runtime;
+  #token;
+
+  /**
+   * @param {object} options
+   * @param {import('./runtime.js').Runtime} options.runtime - The runtime bag.
+   * @param {string} [options.token] - Optional auth token threaded into env.
+   */
+  constructor({ runtime, token }) {
+    if (!runtime) throw new Error("runtime is required");
+    this.#runtime = runtime;
+    this.#token = token;
+  }
+
+  /** Clone `url` into `dir`. */
+  async clone(url, dir, opts = {}) {
+    return this.#run("clone", [url, dir, ...this.#flagOpts(opts)]);
+  }
+
+  /** Initialise a repository at `dir`. */
+  async init(dir) {
+    return this.#run("init", [dir]);
+  }
+
+  /** Fetch `refspec` from `remote`. */
+  async fetch(remote = "origin", refspec, { cwd } = {}) {
+    const args = ["fetch", remote];
+    if (refspec) args.push(refspec);
+    return this.#runRaw(args, { cwd });
+  }
+
+  /** Return `git status --porcelain` output. */
+  async status({ cwd }) {
+    return this.#runRaw(["status", "--porcelain"], { cwd });
+  }
+
+  /** Rebase the current branch onto `upstream`, optionally with a merge strategy. */
+  async rebase(upstream, { cwd, strategy } = {}) {
+    const args = ["rebase"];
+    if (strategy) args.push("-X", strategy);
+    args.push(upstream);
+    return this.#runRaw(args, { cwd, allowFailure: true });
+  }
+
+  /** Abort an in-progress rebase, leaving the working tree at its pre-rebase state. */
+  async rebaseAbort({ cwd } = {}) {
+    return this.#runRaw(["rebase", "--abort"], { cwd, allowFailure: true });
+  }
+
+  /** Merge `ref` into the current branch resolving conflicts with `-X ours`. */
+  async mergeOursStrategy({ cwd, ref }) {
+    return this.#runRaw(["merge", "-X", "ours", "--no-edit", ref], { cwd });
+  }
+
+  /** Stage all changes and commit with `message`. */
+  async commitAll(message, { cwd, author } = {}) {
+    await this.#runRaw(["add", "-A"], { cwd });
+    const args = ["commit", "-m", message];
+    if (author) args.push("--author", author);
+    return this.#runRaw(args, { cwd });
+  }
+
+  /** Push `branch` to `remote`. */
+  async push(remote = "origin", branch, { cwd, force = false } = {}) {
+    const args = ["push", remote];
+    if (branch) args.push(branch);
+    if (force) args.push("--force-with-lease");
+    return this.#runRaw(args, { cwd });
+  }
+
+  /** Count commits in `range` (`git rev-list --count`). */
+  async revListCount(range, { cwd }) {
+    const result = await this.#runRaw(["rev-list", "--count", range], { cwd });
+    return Number.parseInt(result.stdout.trim(), 10);
+  }
+
+  /** Read a config `key`. */
+  async configGet(key, { cwd } = {}) {
+    const result = await this.#runRaw(["config", "--get", key], {
+      cwd,
+      allowFailure: true,
+    });
+    return result.stdout.trim();
+  }
+
+  /** Set a config `key` to `value`. */
+  async configSet(key, value, { cwd } = {}) {
+    return this.#runRaw(["config", key, value], { cwd });
+  }
+
+  /** Count commits the current branch is ahead of `upstream`. */
+  async aheadCount({ cwd, upstream = "@{upstream}" } = {}) {
+    return this.revListCount(`${upstream}..HEAD`, { cwd });
+  }
+
+  /** Read the URL configured for `remote`. */
+  async remoteGetUrl(remote = "origin", { cwd }) {
+    const result = await this.#runRaw(["remote", "get-url", remote], { cwd });
+    return result.stdout.trim();
+  }
+
+  /** Return a new client that threads `token` into the git env. */
+  withAuth(token) {
+    return new GitClient({ runtime: this.#runtime, token });
+  }
+
+  #flagOpts(opts) {
+    const flags = [];
+    if (opts.depth) flags.push("--depth", String(opts.depth));
+    if (opts.branch) flags.push("--branch", opts.branch);
+    if (opts.bare) flags.push("--bare");
+    return flags;
+  }
+
+  #run(subcmd, args, { cwd, allowFailure = false } = {}) {
+    return this.#runRaw([subcmd, ...args], { cwd, allowFailure });
+  }
+
+  async #runRaw(args, { cwd, allowFailure = false } = {}) {
+    // Authenticate over HTTPS by injecting a per-invocation Basic auth header
+    // via git's `-c` config (the `-c http.extraHeader` must precede the
+    // subcommand). GitHub's git-over-HTTPS expects the token as the password in
+    // HTTP Basic auth (username `x-access-token`); a `bearer` scheme is rejected
+    // for PAT/OAuth tokens and only works for App installation tokens, so Basic
+    // is the broadly-compatible choice. No-op when the client carries no token.
+    const fullArgs = this.#token
+      ? [
+          "-c",
+          `http.extraHeader=Authorization: Basic ${Buffer.from(`x-access-token:${this.#token}`).toString("base64")}`,
+          ...args,
+        ]
+      : args;
+    const result = await this.#runtime.subprocess.run("git", fullArgs, {
+      cwd,
+      env: this.#runtime.proc.env,
+    });
+    if (!allowFailure && result.exitCode !== 0) {
+      throw new GitError(args.join(" "), result);
+    }
+    return result;
+  }
+}

package/src/index.js

@@ -157,6 +157,21 @@ export function execLine(shift, deps) {
 }
 
 export { Finder } from "./finder.js";
+export {
+  createDefaultRuntime,
+  createDefaultProc,
+  createDefaultSubprocess,
+  createDefaultClock,
+} from "./runtime.js";
+export {
+  isoDate,
+  isoWeek,
+  isoWeekString,
+  yearMonth,
+  addDays,
+} from "./calendar.js";
+export { GitClient } from "./git-client.js";
+export { GhClient } from "./gh-client.js";
 export { BundleDownloader } from "./downloader.js";
 export { TarExtractor, ZipExtractor } from "./extractor.js";
 export { ProcessorBase } from "./processor.js";

package/src/runtime.js

@@ -0,0 +1,226 @@
+import { spawn as nodeSpawn, execFile, spawnSync } from "node:child_process";
+import nodeFsSync from "node:fs";
+import nodeFs from "node:fs/promises";
+import { Finder } from "./finder.js";
+
+/**
+ * @typedef {Object} Runtime
+ *
+ * The single bag of ambient collaborators threaded from every binary's
+ * entry point through `ctx.deps` into every constructor and factory
+ * Production wires the bag from `createDefaultRuntime`; tests
+ * wire it from libmock's `createTestRuntime`. A module destructures the
+ * fields it actually uses and never imports `node:fs` / `node:child_process`
+ * or reads `Date.now` / `process.*` directly.
+ *
+ * @property {Object} fs
+ *   Async filesystem surface (the `node:fs/promises` shape): `readFile`,
+ *   `writeFile`, `readdir`, `stat`, `mkdir`, `access`, `copyFile`, `cp`, `rm`,
+ *   `lstat`, `unlink`, `symlink`, `utimes`, `chmod`. A module destructures
+ *   `fs` xor `fsSync`, never both (design Decision 7).
+ * @property {Object} fsSync
+ *   Sync filesystem surface (the `node:fs` shape): `existsSync`,
+ *   `readFileSync`, `writeFileSync`, `mkdirSync`, `readdirSync`, `statSync`,
+ *   `openSync`, `closeSync`, `unlinkSync`.
+ * @property {Object} proc
+ *   Process surface: `cwd()`, `env`, `argv`, `stdin`, `stdout.write`,
+ *   `stderr.write`, `exit(code)`, `kill(pid, signal)` (a negative `pid`
+ *   signals the process group, e.g. for daemon teardown), and an `exitCode`
+ *   accessor.
+ * @property {Object} clock
+ *   Time surface: `now()`, `sleep(ms)`, `setTimeout(fn, ms)`,
+ *   `clearTimeout(handle)`.
+ * @property {Object} subprocess
+ *   Subprocess surface: `run(cmd, args, opts) -> Promise<{stdout, stderr,
+ *   exitCode}>` (async, buffered), `runSync(cmd, args, opts) -> {stdout,
+ *   stderr, exitCode}` (synchronous, buffered — for the rare caller that
+ *   cannot go async, e.g. a sync config accessor shelling to `gh auth
+ *   token`), and `spawn(cmd, args, opts) -> {stdout, stderr, exitCode, kill}`
+ *   where `stdout`/`stderr` are AsyncIterables and `exitCode` a Promise.
+ * @property {Object} finder
+ *   A constructed `Finder` (project path resolution + symlink management).
+ */
+
+/**
+ * Build the process surface over a `process`-like source. The returned
+ * object is intentionally not frozen — `exitCode` is defined as an accessor
+ * with a setter, which `Object.freeze` would strip.
+ *
+ * @param {object} [options]
+ * @param {object} [options.source=process] - The backing process handle.
+ * @param {Record<string,string>} [options.env=source.env] - Backing env map
+ *   the `env` Proxy reads through to on every access.
+ * @returns {object} The `proc` collaborator.
+ */
+export function createDefaultProc({ source = process, env = source.env } = {}) {
+  const proc = {
+    cwd: () => source.cwd(),
+    env: new Proxy(env, {
+      get: (t, k) => t[k],
+      has: (t, k) => k in t,
+      set: (t, k, v) => {
+        t[k] = v;
+        return true;
+      },
+      deleteProperty: (t, k) => {
+        delete t[k];
+        return true;
+      },
+      ownKeys: (t) => Reflect.ownKeys(t),
+      getOwnPropertyDescriptor: (t, k) =>
+        Reflect.getOwnPropertyDescriptor(t, k) ?? {
+          configurable: true,
+          enumerable: true,
+          value: t[k],
+          writable: true,
+        },
+    }),
+    argv: Object.freeze([...source.argv]),
+    stdin: lineIterator(source.stdin),
+    stdout: { write: (s) => source.stdout.write(s) },
+    stderr: { write: (s) => source.stderr.write(s) },
+    exit: (code) => source.exit(code),
+    kill: (pid, signal) => source.kill(pid, signal),
+  };
+  Object.defineProperty(proc, "exitCode", {
+    enumerable: true,
+    get: () => source.exitCode,
+    set: (v) => {
+      source.exitCode = v;
+    },
+  });
+  return proc;
+}
+
+/**
+ * Adapt a readable stream into an `AsyncIterable<string>` of UTF-8 lines.
+ * @param {object} stream - A Node readable stream (e.g. `process.stdin`).
+ * @returns {AsyncIterable<string>}
+ */
+function lineIterator(stream) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      let buffer = "";
+      for await (const chunk of stream) {
+        buffer += chunk.toString("utf8");
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+          yield buffer.slice(0, nl);
+          buffer = buffer.slice(nl + 1);
+        }
+      }
+      if (buffer.length > 0) yield buffer;
+    },
+  };
+}
+
+/**
+ * Build the clock surface backed by real timers.
+ * @returns {{now: () => number, sleep: (ms: number) => Promise<void>, setTimeout: Function, clearTimeout: Function}}
+ */
+export function createDefaultClock() {
+  return {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+  };
+}
+
+/**
+ * Build the subprocess surface over `node:child_process`. `run` buffers the
+ * full output; `runSync` is its synchronous sibling; `spawn` exposes streaming
+ * AsyncIterables plus an exit Promise.
+ * @returns {{run: Function, runSync: Function, spawn: Function}}
+ */
+export function createDefaultSubprocess() {
+  const runSync = (cmd, args = [], opts = {}) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", ...opts });
+    // `error` is set on spawn failure (e.g. ENOENT); mirror run()'s mapping:
+    // numeric status, 128 for a signal-kill, 127 for a spawn failure.
+    let exitCode = 0;
+    if (r.error) exitCode = 127;
+    else if (typeof r.status === "number") exitCode = r.status;
+    else if (r.signal) exitCode = 128;
+    return {
+      stdout: r.stdout ?? "",
+      stderr: r.stderr ?? "",
+      exitCode,
+      signal: r.signal ?? null,
+    };
+  };
+
+  const run = (cmd, args = [], opts = {}) =>
+    new Promise((resolve) => {
+      execFile(
+        cmd,
+        args,
+        { encoding: "utf8", ...opts },
+        (err, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            // Always numeric: child code on normal exit, 128 for a signal-kill
+            // (err.code null, err.signal set), 127 for a spawn failure
+            // (err.code is a string like "ENOENT").
+            exitCode: normalizeExitCode(err),
+            signal: err?.signal ?? null,
+          });
+        },
+      );
+    });
+
+  const spawn = (cmd, args = [], opts = {}) => {
+    const child = nodeSpawn(cmd, args, opts);
+    return {
+      stdout: child.stdout ?? emptyAsyncIterable(),
+      stderr: child.stderr ?? emptyAsyncIterable(),
+      exitCode: new Promise((resolve) => {
+        child.on("close", (code) => resolve(code ?? 0));
+      }),
+      kill: (signal) => child.kill(signal),
+    };
+  };
+
+  return { run, runSync, spawn };
+}
+
+/**
+ * Map an `execFile` error to a numeric exit code.
+ * @param {Error & {code?: number|string, signal?: string}} [err]
+ * @returns {number}
+ */
+function normalizeExitCode(err) {
+  if (!err) return 0;
+  if (typeof err.code === "number") return err.code;
+  if (err.signal) return 128;
+  return 127;
+}
+
+function emptyAsyncIterable() {
+  return {
+    [Symbol.asyncIterator]() {
+      return { next: async () => ({ done: true, value: undefined }) };
+    },
+  };
+}
+
+/**
+ * Build the production runtime bag. Two-phase: phase 1 assembles the leaf
+ * collaborators, phase 2 constructs the `Finder` from them, then the whole
+ * bag is frozen and returned.
+ *
+ * @param {object} [options]
+ * @param {Record<string,string>} [options.env=process.env] - Backing env.
+ * @returns {Readonly<Runtime>}
+ */
+export function createDefaultRuntime({ env = process.env } = {}) {
+  const fs = nodeFs;
+  const fsSync = nodeFsSync;
+  const proc = createDefaultProc({ source: process, env });
+  const clock = createDefaultClock();
+  const subprocess = createDefaultSubprocess();
+  // Finder needs the sync existence surface plus the async fs ops; pass both.
+  const finder = new Finder({ fs, fsSync, proc });
+  return Object.freeze({ fs, fsSync, proc, clock, subprocess, finder });
+}