@nathapp/nax 0.75.2 → 0.75.3

package/flows/nax-finish/exec.ts

@@ -14,7 +14,20 @@
  *
  * Both cap wall-clock time: an unbounded gate would hang `acpx flow run`, and
  * the post-run plugin awaits that subprocess.
+ *
+ * ## Why `node:child_process` and not `Bun.spawn`
+ *
+ * The rest of nax is Bun-native (see `.claude/rules/project-conventions.md`),
+ * but this module is **not** loaded by nax. `acpx flow run` loads it, in acpx's
+ * own process, and the published `acpx` binary is a Node program
+ * (`#!/usr/bin/env node`). Under Node the `Bun` global does not exist, so
+ * `Bun.spawn` threw `ReferenceError: Bun is not defined` on the flow's very
+ * first git call — aborting the flow before any node completed and before the
+ * result file was written. Everything under `flows/` must therefore stay on
+ * Node built-ins; `Bun.*` is banned here and only here, enforced by
+ * `scripts/check-flows-no-bun.ts`.
  */
+import { spawn } from "node:child_process";
 import type { RunResult } from "./types";
 
 /** Fallbacks used when the plugin passes no explicit budget in the flow input. */
@@ -28,35 +41,71 @@ export interface ExecOptions {
   timeoutMs?: number;
 }
 
-async function spawnCapture(cmd: string[], opts: ExecOptions): Promise<RunResult> {
-  const proc = Bun.spawn(cmd, { cwd: opts.cwd, stdout: "pipe", stderr: "pipe" });
-  let timedOut = false;
-  // setTimeout (not Bun.sleep) because the handle must be cancellable the moment
-  // the process exits — the documented exception in forbidden-patterns.md.
-  const timer =
-    opts.timeoutMs && opts.timeoutMs > 0
-      ? setTimeout(() => {
-          timedOut = true;
-          proc.kill();
-        }, opts.timeoutMs)
-      : undefined;
-  try {
-    const [exitCode, stdout, stderr] = await Promise.all([
-      proc.exited,
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    return timedOut
-      ? {
-          exitCode: exitCode === 0 ? 124 : exitCode,
-          stdout,
-          stderr: `${stderr}\n[nax-finish] killed after ${opts.timeoutMs}ms timeout`,
-          timedOut: true,
-        }
-      : { exitCode, stdout, stderr };
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
+/** Exit code reported when the wall-clock cap kills the process, matching `timeout(1)`. */
+const TIMEOUT_EXIT_CODE = 124;
+/** Exit code reported when the binary is missing, matching a shell's "command not found". */
+const NOT_FOUND_EXIT_CODE = 127;
+
+function spawnCapture(cmd: string[], opts: ExecOptions): Promise<RunResult> {
+  return new Promise<RunResult>((resolve) => {
+    const [file, ...args] = cmd;
+    const proc = spawn(file as string, args, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+
+    proc.stdout.setEncoding("utf8");
+    proc.stderr.setEncoding("utf8");
+    proc.stdout.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    proc.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+
+    // setTimeout (not a sleep) because the handle must be cancellable the moment
+    // the process exits — the documented exception in forbidden-patterns.md.
+    const timer =
+      opts.timeoutMs && opts.timeoutMs > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            proc.kill();
+          }, opts.timeoutMs)
+        : undefined;
+
+    const settle = (result: RunResult): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+
+    // A missing binary (`gh`/`glab` not installed) surfaces as an `error` event
+    // under Node, where `Bun.spawn` used to throw. Resolving with 127 instead of
+    // rejecting keeps it a readable gate failure the flow can route on, rather
+    // than an exception that kills `acpx flow run` with no result file.
+    proc.on("error", (err: Error) => {
+      settle({ exitCode: NOT_FOUND_EXIT_CODE, stdout, stderr: `${stderr}${err.message}`, timedOut });
+    });
+
+    // `close` (not `exit`) so both pipes are fully drained before we read them.
+    // `code` is null when the process died from a signal — including our own
+    // timeout kill — so it maps to a non-zero code rather than a false green.
+    proc.on("close", (code: number | null) => {
+      const exitCode = code ?? (timedOut ? TIMEOUT_EXIT_CODE : 1);
+      settle(
+        timedOut
+          ? {
+              exitCode: exitCode === 0 ? TIMEOUT_EXIT_CODE : exitCode,
+              stdout,
+              stderr: `${stderr}\n[nax-finish] killed after ${opts.timeoutMs}ms timeout`,
+              timedOut: true,
+            }
+          : { exitCode, stdout, stderr },
+      );
+    });
+  });
 }
 
 /** Spawn an argv array directly — no shell. For flow-constructed commands. */

package/flows/nax-finish/steps/quality.ts

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { FinishError } from "../errors";
 import { DEFAULT_GATE_TIMEOUT_MS, runShell } from "../exec";
 import type { ShellRunFn } from "../types";
@@ -12,9 +13,17 @@ export interface QualityCommands {
 
 export const _qualityDeps: { runShell: ShellRunFn; readText: (path: string) => Promise<string | null> } = {
   runShell,
+  // node:fs, not Bun.file — this module runs inside acpx's Node process, where
+  // the `Bun` global does not exist (see the header of `../exec.ts`). A single
+  // read that treats ENOENT as "absent" also avoids the exists()-then-read race
+  // the Bun version had.
   readText: async (path) => {
-    const file = Bun.file(path);
-    return (await file.exists()) ? await file.text() : null;
+    try {
+      return await readFile(path, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw err;
+    }
   },
 };
 

package/flows/nax-finish/steps/result.ts

@@ -1,3 +1,5 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import type { FinishResult } from "../types";
 
 export function resultPath(repoRoot: string): string {
@@ -5,8 +7,14 @@ export function resultPath(repoRoot: string): string {
 }
 
 export const _resultDeps: { writeText: (p: string, s: string) => Promise<void> } = {
+  // node:fs, not Bun.write — this module runs inside acpx's Node process, where
+  // the `Bun` global does not exist (see the header of `../exec.ts`). The mkdir
+  // is not redundant: Bun.write creates missing parent directories implicitly,
+  // writeFile does not, and this is the one artifact the plugin needs on disk to
+  // report an outcome at all.
   writeText: async (p, s) => {
-    await Bun.write(p, s);
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, s, "utf8");
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.75.2",
+  "version": "0.75.3",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
@@ -11,9 +11,10 @@
     "dev": "bun run bin/nax.ts",
     "build": "bun build bin/nax.ts --outdir dist --target bun --define \"GIT_COMMIT=\\\"$(git rev-parse --short HEAD)\\\"\"",
     "typecheck": "bun x tsc --noEmit && bun x tsc --noEmit -p tsconfig.contracts.json",
-    "lint": "bun x biome check src/ bin/ flows/ && bun run check:no-real-global-nax && bun run check:alias-internals && bun run check:deep-relatives && bun run check:nax-error && bun run check:logger-storyid && bun run check:log-format-layering && bun run check:file-sizes",
+    "lint": "bun x biome check src/ bin/ flows/ && bun run check:flows-no-bun && bun run check:no-real-global-nax && bun run check:alias-internals && bun run check:deep-relatives && bun run check:nax-error && bun run check:logger-storyid && bun run check:log-format-layering && bun run check:file-sizes",
     "lint:json": "bun x biome check src/ bin/ flows/ --reporter json && bun run check:nax-error 1>&2 && bun run check:logger-storyid 1>&2",
     "lint:fix": "bun x biome check --write src/ bin/ flows/",
+    "check:flows-no-bun": "bun run scripts/check-flows-no-bun.ts",
     "check:no-real-global-nax": "bun run scripts/check-no-real-global-nax.ts",
     "check:alias-internals": "bun run scripts/check-alias-internals.ts",
     "check:deep-relatives": "bun run scripts/check-deep-relatives.ts",