@fusengine/harness 0.1.90 → 0.1.91

package/src/tracking/track-lock-sync.ts

@@ -0,0 +1,83 @@
+/**
+ * Synchronous twin of {@link withTrackLock} for lifecycle paths that CANNOT
+ * float async work (the SubagentStop dispatch runs synchronously in a
+ * short-lived hook process — an async write could be dropped before exit,
+ * see `evidence-harvest-io.ts`). Same semantics: `wx` lockfile, bounded total
+ * retry, named skipped write on contention, stale reclamation. The wait uses
+ * `Atomics.wait` (allowed on the main thread in both Node and Bun).
+ */
+import { closeSync, mkdirSync, openSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { LOCK_FAILED, LOCK_RETRY_TOTAL_MS, LOCK_TTL_MS } from "./track-lock";
+
+export { LOCK_FAILED } from "./track-lock";
+
+/** Block the thread for `ms` (bounded by the caller's total budget). */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** True when the lockfile is older than the TTL (orphaned by a dead process). */
+function isStale(lock: string): boolean {
+  try { return Date.now() - statSync(lock).mtimeMs > LOCK_TTL_MS; } catch { return false; }
+}
+
+/**
+ * Run `fn` under the track lock of `dir`, synchronously.
+ * @param dir - The track state directory (lockfile lives inside).
+ * @param fn - The protected read-modify-write.
+ * @returns `fn`'s result, or {@link LOCK_FAILED} when the lock stayed busy.
+ */
+export function withTrackLockSync<T>(dir: string, fn: () => T): T | typeof LOCK_FAILED {
+  mkdirSync(dir, { recursive: true });
+  const lock = join(dir, "track.lock");
+  const deadline = Date.now() + LOCK_RETRY_TOTAL_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lock, "wx");
+      closeSync(fd);
+      break;
+    } catch {
+      if (isStale(lock)) { try { unlinkSync(lock); } catch { /* raced */ } continue; }
+      if (Date.now() >= deadline) {
+        process.stderr.write(`harness: track lock busy, write skipped (${lock})\n`);
+        return LOCK_FAILED;
+      }
+      sleepSync(8);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(lock); } catch { /* best-effort release */ }
+  }
+}
+
+/**
+ * Blocking twin of {@link withTrackLockSync}: NEVER skips — spins (1 ms step)
+ * until the lock is acquired. Used by the journal append path (track-journal
+ * `appendEvent`): an append must wait out an in-flight compaction (same
+ * `track.lock`), never race its rename/fold/unlink, never be skipped — a lost
+ * write is not an option. The stale-lock TTL (dead-process reclamation) is the
+ * only anti-deadlock guard. Do NOT use on paths that may already hold the lock.
+ */
+export function withTrackLockSyncBlocking<T>(dir: string, fn: () => T): T {
+  mkdirSync(dir, { recursive: true });
+  const lock = join(dir, "track.lock");
+  for (;;) {
+    try {
+      const fd = openSync(lock, "wx");
+      closeSync(fd);
+      break;
+    } catch {
+      if (isStale(lock)) { try { unlinkSync(lock); } catch { /* raced */ } }
+      sleepSync(1);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(lock); } catch { /* best-effort release */ }
+  }
+}
+

package/src/tracking/track-lock.ts

@@ -0,0 +1,67 @@
+/**
+ * Cross-process lock for session-track read-modify-write. The ~11-hook
+ * fan-out races plain `loadTrack → mutate → saveTrack` (writes silently
+ * lost — `refsRead` was the only mitigated channel, via its journal). This
+ * lockfile (`wx`, atomic create) serializes the whole RMW:
+ * - retry is bounded in TOTAL time (400 ms, far under any hook timeout);
+ * - after the budget, NEVER crash: stderr is logged and the caller skips the
+ *   write — a named lost write beats a fail-open crash (hook fail-open
+ *   semantics preserved);
+ * - an orphaned lockfile (dead process) is reclaimed after a 10 s TTL, so a
+ *   crash mid-write never blocks a project forever.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+/** Orphaned lockfile lifetime before reclamation. */
+export const LOCK_TTL_MS = 10_000;
+/** Total bounded retry budget before the write is skipped (fail-open). */
+export const LOCK_RETRY_TOTAL_MS = 400;
+/** Delay between two lock acquisition attempts. */
+const RETRY_STEP_MS = 8;
+
+/** Sentinel returned by {@link withTrackLock} when the lock could not be taken. */
+export const LOCK_FAILED: unique symbol = Symbol("track-lock-failed");
+
+/** True when the lockfile is older than the TTL (orphaned by a dead process). */
+function isStale(lock: string): boolean {
+  try { return Date.now() - statSync(lock).mtimeMs > LOCK_TTL_MS; } catch { return false; }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Run `fn` under the track lock of `dir`, or skip with a stderr note.
+ * @param dir - The track state directory (lockfile lives inside).
+ * @param fn - The protected read-modify-write.
+ * @returns `fn`'s result, or {@link LOCK_FAILED} when the lock stayed busy.
+ */
+export async function withTrackLock<T>(dir: string, fn: () => Promise<T>): Promise<T | typeof LOCK_FAILED> {
+  mkdirSync(dir, { recursive: true });
+  const lock = join(dir, "track.lock");
+  const deadline = Date.now() + LOCK_RETRY_TOTAL_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lock, "wx");
+      closeSync(fd);
+      break;
+    } catch {
+      if (isStale(lock)) { try { unlinkSync(lock); } catch { /* raced */ } continue; }
+      if (Date.now() >= deadline) {
+        process.stderr.write(`harness: track lock busy, write skipped (${lock})\n`);
+        return LOCK_FAILED;
+      }
+      await sleep(RETRY_STEP_MS);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    try { unlinkSync(lock); } catch { /* best-effort release */ }
+  }
+}
+
+/** Test helper: true when a lockfile currently exists in `dir`. */
+export function trackLockExists(dir: string): boolean {
+  return existsSync(join(dir, "track.lock"));
+}

package/src/util/compact-json.ts

@@ -0,0 +1,23 @@
+/**
+ * Compact JSON serializer for cache/state files.
+ * Top-level keys are indented one per line; nested objects/arrays render inline.
+ * Behaviour preserved from the fusengine hooks.
+ */
+export function compactJson(data: unknown): string {
+  if (typeof data !== "object" || data === null) return `${JSON.stringify(data)}\n`;
+  if (Array.isArray(data)) {
+    if (data.length === 0) return "[]\n";
+    const items = data.map((item) => `  ${JSON.stringify(item)}`);
+    return `[\n${items.join(",\n")}\n]\n`;
+  }
+  const lines: string[] = [];
+  for (const [key, val] of Object.entries(data as Record<string, unknown>)) {
+    if (Array.isArray(val) && val.length > 0) {
+      const items = val.map((item) => `    ${JSON.stringify(item)}`);
+      lines.push(`  "${key}": [\n${items.join(",\n")}\n  ]`);
+    } else {
+      lines.push(`  "${key}": ${JSON.stringify(val)}`);
+    }
+  }
+  return `{\n${lines.join(",\n")}\n}\n`;
+}

package/src/util/index.ts

@@ -0,0 +1,2 @@
+export * from "./compact-json";
+export * from "./project-root";

package/src/util/json-io.ts

@@ -0,0 +1,47 @@
+import { mkdir } from "node:fs/promises";
+import {
+  chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { compactJson } from "./compact-json";
+
+/** Atomically write `data` to `path` (temp + rename, 0o600). Cross-FS safe on macOS/Linux. */
+export function atomicWrite(path: string, data: string): void {
+  const parent = dirname(path);
+  mkdirSync(parent, { recursive: true });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, data, { encoding: "utf8" });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* noop */ }
+    throw err;
+  }
+}
+
+/** Ensure a directory exists. */
+export async function ensureDir(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+}
+
+/** Read & JSON-parse a file; null on missing/corrupt. */
+export async function readJsonFile<T>(path: string): Promise<T | null> {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Atomically write JSON (compact form when `compact`). */
+export async function writeJsonFile(path: string, data: unknown, compact = false): Promise<void> {
+  atomicWrite(path, compact ? compactJson(data) : JSON.stringify(data, null, 2));
+}
+
+/** 8-char MD5 of text (cache key; non-cryptographic). Portable Node+Bun. */
+export function hashText(text: string): string {
+  return createHash("md5").update(text).digest("hex").slice(0, 8);
+}

package/src/util/project-root.ts

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/** Source-code file extensions worth tracking as "code was written". */
+const CODE_EXT =
+  /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java|vue|svelte|astro|css|kt|dart|cpp|c)$/;
+/** Generated/vendored directories that never count as code. */
+const SKIP_DIRS = /(node_modules|vendor|dist|build|\.next|DerivedData|\.git)/;
+
+/** True for a source-code file outside generated/vendored directories. */
+export function isCodeFile(p: string): boolean {
+  return CODE_EXT.test(p) && !SKIP_DIRS.test(p);
+}
+
+/**
+ * Walk up from `dir` to the nearest ancestor directory containing `marker`.
+ * @param dir - Starting directory.
+ * @param marker - Sibling file/dir name to look for at each level.
+ * @returns The ancestor holding `marker`, or `null` at filesystem root.
+ */
+export function walkUpFor(dir: string, marker: string): string | null {
+  let current = resolve(dir);
+  while (current !== "/") {
+    if (existsSync(`${current}/${marker}`)) return current;
+    current = dirname(current);
+  }
+  return null;
+}
+
+/**
+ * Resolve the project root, preferring the repo boundary (`.git`) over a
+ * nested `package.json` — avoids false roots in monorepos. Null if none found.
+ */
+export function projectRootOrNull(dir: string): string | null {
+  return walkUpFor(dir, ".git") ?? walkUpFor(dir, "package.json");
+}
+
+/** Like {@link projectRootOrNull} but falls back to `process.cwd()`. */
+export function projectRoot(dir: string): string {
+  return projectRootOrNull(dir) ?? process.cwd();
+}

package/src/util/runtime-io.ts

@@ -0,0 +1,85 @@
+/**
+ * Cross-runtime I/O helpers (Node + Bun). The published CLI ships a `node`
+ * shebang and is invoked via `npx`/`npm`/`bunx`/`bun`; using only `node:*` APIs
+ * here keeps the bundle runnable under EVERY runtime — replacing the Bun-only
+ * `Bun.file/write/spawn/sleep/stdin` calls and the `bun` `Glob` import that made
+ * the package crash with `Cannot find package 'bun'` under plain Node.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, type Dirent } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+/** Read a file as UTF-8 text (throws on missing/unreadable — callers catch). */
+export function readText(path: string): string {
+  return readFileSync(path, "utf8");
+}
+
+/** True when `path` exists. */
+export function pathExists(path: string): boolean {
+  return existsSync(path);
+}
+
+/** Write `data` to `path`, creating parent dirs (mirrors `Bun.write`). */
+export function writeText(path: string, data: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, data, { encoding: "utf8" });
+}
+
+/** Resolve after `ms` milliseconds (`Bun.sleep` replacement). */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Run `cmd args` in `cwd` and capture stdout text ("" on failure/non-zero). */
+export function spawnCapture(cmd: string, args: string[], cwd: string): string {
+  try {
+    const r = spawnSync(cmd, args, { cwd, encoding: "utf8" });
+    return r.status === 0 ? (r.stdout ?? "") : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Read the full process stdin as UTF-8 text (works under Node and Bun).
+ * Synchronous fd-0 read — never `for await (const c of process.stdin)` —
+ * because Bun has a confirmed Linux-only bug where merely adding a new
+ * top-level module import shifts stdin's internal init order and makes
+ * that async iterator silently yield zero bytes (oven-sh/bun#25320,
+ * #27849): exactly what broke every `harness hook` invocation on CI the
+ * moment `figures` became this package's first runtime dependency.
+ * `readFileSync(0)` bypasses that stream/ownership machinery entirely and
+ * is well-supported for piped (non-TTY) stdin under both runtimes.
+ */
+export async function readStdin(): Promise<string> {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Recursively collect files under `dir` whose extension is in `exts`, skipping
+ * `node_modules` and dot-dirs, capped at `cap`. `Bun.Glob().scan()` replacement.
+ * @param dir - Directory to walk.
+ * @param exts - Allowed extensions including the dot (e.g. `.ts`).
+ * @param out - Accumulator (mutated in place).
+ * @param cap - Max files to collect.
+ */
+export function collectFiles(dir: string, exts: ReadonlySet<string>, out: string[], cap: number): void {
+  if (out.length >= cap) return;
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (out.length >= cap) return;
+    if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) collectFiles(full, exts, out, cap);
+    else if (exts.has(e.name.slice(e.name.lastIndexOf(".")))) out.push(full);
+  }
+}

package/src/util/semver.ts

@@ -0,0 +1,30 @@
+/**
+ * Dependency-free semver ordering. `Array.prototype.sort()` compares strings
+ * lexicographically — `"1.0.9" > "1.0.23"` — so versioned directories (plugin
+ * caches) must be ordered with a numeric, segment-by-segment comparison.
+ */
+
+/**
+ * Compare two dotted version strings numerically, segment by segment
+ * (shorter version wins when a prefix is equal: `1.0` < `1.0.1`). A segment
+ * that is not a plain integer (prerelease tag like `0-beta`) falls back to
+ * lexicographic comparison of that segment — never NaN, so `sort()` stays
+ * defined; identical strings compare 0.
+ * @returns Negative when `a < b`, positive when `a > b`, 0 when equal.
+ */
+export function compareSemver(a: string, b: string): number {
+  const pa = a.split("."), pb = b.split(".");
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const sa = pa[i] ?? "0", sb = pb[i] ?? "0";
+    if (sa === sb) continue;
+    const na = Number(sa), nb = Number(sb);
+    if (Number.isInteger(na) && Number.isInteger(nb) && na !== nb) return na - nb;
+    return sa < sb ? -1 : 1;
+  }
+  return 0;
+}
+
+/** The highest version of the list, or null when empty. */
+export function maxSemver(versions: string[]): string | null {
+  return versions.length === 0 ? null : versions.reduce((a, b) => (compareSemver(a, b) >= 0 ? a : b));
+}