fix(core): consolidate spawn-safe into nerve-core

Move spawnSafe, nerveCommandEnv, and related types to @uncaged/nerve-core.

Update adapter-cursor, adapter-hermes, and workflow-utils to consume from core.

Refs #247

Made-with: Cursor

packages/core/src/__tests__/spawn-safe.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import { spawnSafe } from "../spawn-safe.js";
+
+describe("spawnSafe", () => {
+  it("passes argv literally without shell interpretation (injection-safe)", async () => {
+    const injection = "$(echo BAD)";
+    const result = await spawnSafe(
+      process.execPath,
+      ["-e", "process.stdout.write(process.argv[1] ?? '')", injection],
+      { cwd: null, env: null, timeoutMs: 10_000, abortSignal: null },
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value.stdout).toBe(injection);
+    expect(result.value.exitCode).toBe(0);
+  });
+
+  it("returns err on non-zero exit", async () => {
+    const result = await spawnSafe(process.execPath, ["-e", "process.exit(7)"], {
+      cwd: null,
+      env: null,
+      timeoutMs: 10_000,
+      abortSignal: null,
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.kind).toBe("non_zero_exit");
+    if (result.error.kind !== "non_zero_exit") {
+      return;
+    }
+    expect(result.error.exitCode).toBe(7);
+  });
+
+  it("dryRun skips spawn and returns a zero-exit stub", async () => {
+    const result = await spawnSafe(process.execPath, ["-e", "process.exit(1)"], {
+      cwd: null,
+      env: null,
+      timeoutMs: 10_000,
+      dryRun: true,
+      abortSignal: null,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual({
+      stdout: "[dryRun] skipped",
+      stderr: "",
+      exitCode: 0,
+      signal: null,
+    });
+  });
+});

packages/core/src/index.ts

@@ -33,6 +33,14 @@ export type { Schema, ExtractFn } from "./extract-layer.js";
 export { ExtractError } from "./extract-layer.js";
 export type { Result } from "./result.js";
 export { ok, err } from "./result.js";
+export {
+  nerveCommandEnv,
+  spawnSafe,
+  type SpawnEnv,
+  type SpawnError,
+  type SpawnResult,
+  type SpawnSafeOptions,
+} from "./spawn-safe.js";
 export { parseNerveConfig } from "./parse-nerve-config.js";
 export type { KnowledgeConfig } from "./knowledge-config.js";
 export { parseKnowledgeYaml } from "./knowledge-config.js";

packages/core/src/spawn-safe.ts

@@ -0,0 +1,195 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { type Result, err, ok } from "./result.js";
+
+/** Compatible with `process.env` for `child_process.spawn`. */
+export type SpawnEnv = Record<string, string | undefined>;
+
+export type SpawnResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  /** OS signal name (e.g. `"SIGTERM"`) when terminated by signal; otherwise `null`. */
+  signal: string | null;
+};
+
+export type SpawnError =
+  | {
+      kind: "non_zero_exit";
+      stdout: string;
+      stderr: string;
+      exitCode: number;
+      signal: string | null;
+    }
+  | { kind: "timeout"; stdout: string; stderr: string }
+  | { kind: "spawn_failed"; message: string }
+  | { kind: "aborted" };
+
+export type SpawnSafeOptions = {
+  cwd: string | null;
+  /** When null, merges {@link nerveCommandEnv} over `process.env`. When set, merges over that default. */
+  env: SpawnEnv | null;
+  timeoutMs: number | null;
+  dryRun: boolean;
+  /** When non-null, child is terminated on abort; if `timeoutMs` is also null, no internal wall-clock timer is used. */
+  abortSignal: AbortSignal | null;
+};
+
+type SpawnSafeOptionsInput = SpawnSafeOptions | Omit<SpawnSafeOptions, "dryRun">;
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+/**
+ * PATH and PNPM_HOME for running `pnpm` and `nerve` from workflow roles.
+ * Uses the pnpm store home only (no npm user bin); binaries must resolve via PATH.
+ */
+export function nerveCommandEnv(): SpawnEnv {
+  const home = homedir();
+  const pnpmHome = join(home, ".local/share/pnpm");
+  return {
+    ...process.env,
+    PNPM_HOME: pnpmHome,
+    PATH: `${pnpmHome}:${process.env.PATH ?? ""}`,
+  };
+}
+
+function mergeEnv(user: SpawnEnv | null): SpawnEnv {
+  const base = nerveCommandEnv();
+  if (user === null) {
+    return base;
+  }
+  return { ...base, ...user };
+}
+
+/** Internal timer duration; `null` means rely on abort or process exit only. */
+function resolveWallClockMs(
+  timeoutMs: number | null,
+  abortSignal: AbortSignal | null,
+): number | null {
+  if (timeoutMs === null) {
+    if (abortSignal !== null) {
+      return null;
+    }
+    return DEFAULT_TIMEOUT_MS;
+  }
+  return timeoutMs;
+}
+
+function resolveDryRun(options: SpawnSafeOptionsInput): boolean {
+  return "dryRun" in options ? options.dryRun : false;
+}
+
+function normalizeAbortSignal(options: SpawnSafeOptionsInput): AbortSignal | null {
+  return "abortSignal" in options ? options.abortSignal : null;
+}
+
+/**
+ * Spawn a process with `shell: false` (argv only), default {@link nerveCommandEnv}, and optional timeout.
+ * Returns `ok` only when the process exits with code 0.
+ */
+export function spawnSafe(
+  command: string,
+  args: ReadonlyArray<string>,
+  options: SpawnSafeOptionsInput,
+): Promise<Result<SpawnResult, SpawnError>> {
+  const dryRun = resolveDryRun(options);
+  if (dryRun) {
+    return Promise.resolve(
+      ok({
+        stdout: "[dryRun] skipped",
+        stderr: "",
+        exitCode: 0,
+        signal: null,
+      }),
+    );
+  }
+
+  const abortSignal = normalizeAbortSignal(options);
+  if (abortSignal?.aborted) {
+    return Promise.resolve(err({ kind: "aborted" }));
+  }
+
+  return new Promise((resolve) => {
+    const cwd = options.cwd === null ? process.cwd() : options.cwd;
+    const env = mergeEnv(options.env);
+    const wallClockMs = resolveWallClockMs(options.timeoutMs, abortSignal);
+
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (outcome: Result<SpawnResult, SpawnError>) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      if (abortSignal !== null) {
+        abortSignal.removeEventListener("abort", onAbort);
+      }
+      resolve(outcome);
+    };
+
+    function onAbort() {
+      child.kill("SIGTERM");
+      finish(err({ kind: "aborted" }));
+    }
+
+    if (abortSignal !== null) {
+      abortSignal.addEventListener("abort", onAbort);
+    }
+
+    if (wallClockMs !== null) {
+      timer = setTimeout(() => {
+        child.kill("SIGTERM");
+        finish(err({ kind: "timeout", stdout, stderr }));
+      }, wallClockMs);
+    }
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    });
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      stderr += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    });
+
+    child.on("error", (cause: Error) => {
+      finish(err({ kind: "spawn_failed", message: cause.message }));
+    });
+
+    child.on("close", (code, signal) => {
+      const exitCode = code ?? 1;
+      const sig = signal === undefined || signal === null ? null : String(signal);
+      const result: SpawnResult = {
+        stdout: stdout.trimEnd(),
+        stderr: stderr.trimEnd(),
+        exitCode,
+        signal: sig,
+      };
+      if (exitCode !== 0) {
+        finish(
+          err({
+            kind: "non_zero_exit",
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode,
+            signal: sig,
+          }),
+        );
+        return;
+      }
+      finish(ok(result));
+    });
+  });
+}