@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/lib/machine-id.test.ts

@@ -1,231 +0,0 @@
-/**
- * Machine-ID resolver tests. Pins the four-tier fallback contract so a
- * regression in tier ordering, the migration-forward behavior, or the
- * "unknown sentinel is no longer reachable" invariant is caught at build
- * time rather than re-litigating it on a user's Lightsail outpost.
- */
-
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { getOrCreateMachineId, readShortMachineId } from "./machine-id.js";
-
-function freshTmp(prefix: string): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
-}
-
-describe("getOrCreateMachineId (four-tier resolver)", () => {
-  let originalHome: string | undefined;
-let originalUserProfile: string | undefined;
-  let originalEnvId: string | undefined;
-  let tmpHome: string;
-  let tmpHqRoot: string;
-
-  beforeEach(() => {
-    originalHome = process.env.HOME;
-  originalUserProfile = process.env.USERPROFILE;
-    originalEnvId = process.env.HQ_MACHINE_ID;
-    delete process.env.HQ_MACHINE_ID;
-    tmpHome = freshTmp("hq-machineid-home-");
-    tmpHqRoot = freshTmp("hq-machineid-root-");
-    process.env.HOME = tmpHome;
-  process.env.USERPROFILE = tmpHome;
-  });
-
-  afterEach(() => {
-    if (originalHome) process.env.HOME = originalHome;
-    else delete process.env.HOME;
-    if (originalUserProfile) process.env.USERPROFILE = originalUserProfile;
-    else delete process.env.USERPROFILE;
-    if (originalEnvId !== undefined) process.env.HQ_MACHINE_ID = originalEnvId;
-    else delete process.env.HQ_MACHINE_ID;
-    fs.rmSync(tmpHome, { recursive: true, force: true });
-    fs.rmSync(tmpHqRoot, { recursive: true, force: true });
-  });
-
-  // ── tier 1: HQ_MACHINE_ID env override ────────────────────────────────
-  it("tier 1: returns HQ_MACHINE_ID env when set, ignoring lower tiers", () => {
-    process.env.HQ_MACHINE_ID = "env-override-id";
-    // Even if a persisted file exists, env wins.
-    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
-    fs.writeFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "persisted\n");
-    expect(getOrCreateMachineId(tmpHqRoot)).toBe("env-override-id");
-    // Env-only resolution must not clobber the on-disk source-of-truth.
-    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(
-      "persisted",
-    );
-  });
-
-  // ── tier 2: <hqRoot>/.hq/machine-id ───────────────────────────────────
-  it("tier 2: returns the trimmed contents of <hqRoot>/.hq/machine-id", () => {
-    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
-    fs.writeFileSync(
-      path.join(tmpHqRoot, ".hq", "machine-id"),
-      "  abc-123-persisted  \n\n",
-    );
-    expect(getOrCreateMachineId(tmpHqRoot)).toBe("abc-123-persisted");
-  });
-
-  it("tier 2: empty machine-id file falls through to autogen", () => {
-    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
-    fs.writeFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "");
-    const id = getOrCreateMachineId(tmpHqRoot);
-    // UUID v4 shape.
-    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-    // Persisted on disk for next call.
-    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(id);
-  });
-
-  // ── tier 3: ~/.hq/menubar.json (legacy, migrated forward) ─────────────
-  it("tier 3: reads menubar.json AND migrates the value into <hqRoot>/.hq/machine-id", () => {
-    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
-    fs.writeFileSync(
-      path.join(tmpHome, ".hq", "menubar.json"),
-      JSON.stringify({ machineId: "menubar-legacy-id" }),
-    );
-    expect(getOrCreateMachineId(tmpHqRoot)).toBe("menubar-legacy-id");
-    // Migrated forward — subsequent calls now hit tier 2.
-    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(
-      "menubar-legacy-id",
-    );
-  });
-
-  it("tier 3: malformed menubar.json falls through to autogen", () => {
-    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
-    fs.writeFileSync(path.join(tmpHome, ".hq", "menubar.json"), "{not-json");
-    const id = getOrCreateMachineId(tmpHqRoot);
-    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-  });
-
-  it("tier 3: menubar.json without a machineId field falls through to autogen", () => {
-    fs.mkdirSync(path.join(tmpHome, ".hq"), { recursive: true });
-    fs.writeFileSync(
-      path.join(tmpHome, ".hq", "menubar.json"),
-      JSON.stringify({ telemetryEnabled: true }),
-    );
-    const id = getOrCreateMachineId(tmpHqRoot);
-    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-  });
-
-  // ── tier 4: autogen + persist ─────────────────────────────────────────
-  it("tier 4: generates a UUID and persists it for the next call", () => {
-    const id = getOrCreateMachineId(tmpHqRoot);
-    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-    expect(fs.readFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "utf-8").trim()).toBe(id);
-    // Stable across calls.
-    expect(getOrCreateMachineId(tmpHqRoot)).toBe(id);
-  });
-
-  it("tier 4: stays in-process even if hqRoot is read-only (best-effort persist)", () => {
-    // Pre-create .hq as a regular dir, then strip write perms.
-    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
-    fs.chmodSync(path.join(tmpHqRoot, ".hq"), 0o500); // r-x only
-    try {
-      const id = getOrCreateMachineId(tmpHqRoot);
-      expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-    } finally {
-      fs.chmodSync(path.join(tmpHqRoot, ".hq"), 0o700);
-    }
-  });
-
-  // ── invariant: "unknown" sentinel is unreachable ──────────────────────
-  it("never returns the legacy 'unknown' sentinel — every host gets a real id", () => {
-    // No env, no persisted file, no menubar.json — pure tier-4 path.
-    const id = getOrCreateMachineId(tmpHqRoot);
-    expect(id).not.toBe("unknown");
-    expect(id.length).toBeGreaterThan(6);
-  });
-});
-
-describe("readShortMachineId", () => {
-  let originalHome: string | undefined;
-let originalUserProfile: string | undefined;
-  let originalEnvId: string | undefined;
-  let tmpHome: string;
-  let tmpHqRoot: string;
-
-  beforeEach(() => {
-    originalHome = process.env.HOME;
-  originalUserProfile = process.env.USERPROFILE;
-    originalEnvId = process.env.HQ_MACHINE_ID;
-    delete process.env.HQ_MACHINE_ID;
-    tmpHome = freshTmp("hq-machineid-short-home-");
-    tmpHqRoot = freshTmp("hq-machineid-short-root-");
-    process.env.HOME = tmpHome;
-  process.env.USERPROFILE = tmpHome;
-  });
-
-  afterEach(() => {
-    if (originalHome) process.env.HOME = originalHome;
-    else delete process.env.HOME;
-    if (originalUserProfile) process.env.USERPROFILE = originalUserProfile;
-    else delete process.env.USERPROFILE;
-    if (originalEnvId !== undefined) process.env.HQ_MACHINE_ID = originalEnvId;
-    else delete process.env.HQ_MACHINE_ID;
-    fs.rmSync(tmpHome, { recursive: true, force: true });
-    fs.rmSync(tmpHqRoot, { recursive: true, force: true });
-  });
-
-  it("returns the first 6 chars when the resolved id has a hex prefix", () => {
-    process.env.HQ_MACHINE_ID = "deadbeefcafe1234567890";
-    expect(readShortMachineId(tmpHqRoot)).toBe("deadbe");
-  });
-
-  it("returns the first 6 chars of an autogenerated UUID", () => {
-    const short = readShortMachineId(tmpHqRoot);
-    expect(short).toHaveLength(6);
-    expect(short).toMatch(/^[0-9a-f]{6}$/);
-    expect(short).not.toBe("unknow"); // legacy "unknown" prefix — must not reappear
-  });
-
-  it("reads the same hex prefix from <hqRoot>/.hq/machine-id when persisted", () => {
-    fs.mkdirSync(path.join(tmpHqRoot, ".hq"), { recursive: true });
-    fs.writeFileSync(path.join(tmpHqRoot, ".hq", "machine-id"), "abcdef-rest-can-be-anything");
-    expect(readShortMachineId(tmpHqRoot)).toBe("abcdef");
-  });
-
-  // ── normalization invariant: short token is ALWAYS [a-f0-9]{6} ────────
-  //
-  // Regression coverage for the Codex-flagged P2 — without this, a
-  // non-hex `HQ_MACHINE_ID` or legacy menubar value (e.g. "ci-runner-42",
-  // "menubar-legacy-id") would slice to a non-hex 6-char prefix, the
-  // conflict filename would carry that non-hex token, and the
-  // `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts` (which only accepts
-  // `[a-f0-9]+` or the literal `unknown`) would refuse it, restoring the
-  // exact litter-ratchet loop this module exists to close.
-  it.each([
-    // Tier-1 env override with non-hex characters.
-    ["ci-runner-42"],
-    ["env-override-id"],
-    // Tier-3 legacy menubar value with non-hex characters.
-    ["menubar-legacy-id"],
-    // Mixed-case that contains non-hex letters in the first 6 chars.
-    ["Gabc12-rest"],
-    // First 6 chars are hex but contain uppercase (regex is case-sensitive).
-    ["ABCDEF-rest"],
-  ])("normalizes non-hex source ids to a hex token: %s", (sourceId) => {
-    process.env.HQ_MACHINE_ID = sourceId;
-    const short = readShortMachineId(tmpHqRoot);
-    expect(short).toMatch(/^[a-f0-9]{6}$/);
-    expect(short).toHaveLength(6);
-  });
-
-  it("normalization is deterministic — same source id always yields same short token", () => {
-    process.env.HQ_MACHINE_ID = "menubar-legacy-id";
-    const a = readShortMachineId(tmpHqRoot);
-    const b = readShortMachineId(tmpHqRoot);
-    expect(a).toBe(b);
-    expect(a).toMatch(/^[a-f0-9]{6}$/);
-  });
-
-  it("normalization distinguishes different source ids", () => {
-    process.env.HQ_MACHINE_ID = "menubar-legacy-id";
-    const a = readShortMachineId(tmpHqRoot);
-    process.env.HQ_MACHINE_ID = "ci-runner-42";
-    const b = readShortMachineId(tmpHqRoot);
-    expect(a).not.toBe(b);
-    expect(a).toMatch(/^[a-f0-9]{6}$/);
-    expect(b).toMatch(/^[a-f0-9]{6}$/);
-  });
-});

package/src/lib/machine-id.ts

@@ -1,175 +0,0 @@
-/**
- * Machine-ID provisioning — owns the per-host identity used to attribute
- * conflict mirrors, telemetry rows, and `.hq-conflicts/index.json` entries.
- *
- * Historically the menubar app (`indigoai-us/hq-sync`) was the sole writer
- * of `machineId` via `~/.hq/menubar.json`, and every other sync caller
- * best-effort read from there. That arrangement is backwards: hq-cloud is
- * the engine that runs on every sync host (macOS-with-menubar, macOS CLI,
- * Linux HQ Pro Outposts, future Windows), while the menubar is an optional
- * macOS-only UI. Linux outposts therefore had no menubar.json, so
- * `readShortMachineId()` returned the literal string `"unknown"` and
- * every conflict file on those hosts was tagged `-unknown` (which then
- * also slipped past `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts` — see
- * Fix 2 — and rode S3 round-trips as a regular file).
- *
- * This module flips ownership: hq-cloud provisions a UUID on first call
- * and persists it to `<hqRoot>/.hq/machine-id` (one line, plain text).
- * Every subsequent call hits the persisted file. Existing macOS installs
- * with menubar-written IDs are migrated forward on first call: tier 3
- * picks up the menubar.json value, writes it to `<hqRoot>/.hq/machine-id`,
- * and returns it — so the id is stable across the migration window.
- *
- * Resolution order (first hit wins, every miss falls through):
- *   1. `process.env.HQ_MACHINE_ID` — explicit override for CI / tests.
- *   2. `<hqRoot>/.hq/machine-id` — source-of-truth on the host.
- *   3. `~/.hq/menubar.json` `machineId` field — back-compat for existing
- *      macOS installs; migrated forward to tier 2 on first read.
- *   4. Autogen — write a fresh UUID to `<hqRoot>/.hq/machine-id` and return.
- *
- * Concurrent autogen race is benign: two writers each pick a fresh UUID,
- * last-writer-wins on disk, both processes re-read the now-stable file on
- * their next call. The window is narrow (single sync run startup) and the
- * downside (one extra conflict-file rename across a single race window) is
- * trivial compared to the litter-ratchet bug it replaces.
- */
-
-import { createHash, randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-/**
- * Path to `~/.hq/menubar.json`. Evaluated lazily at call time (not module
- * load) so tests overriding `HOME` post-import see the right file. Going
- * through `os.homedir()` rather than `process.env.HOME` keeps the Windows
- * USERPROFILE fallback intact.
- */
-function menubarJsonPath(): string {
-  return path.join(os.homedir(), ".hq", "menubar.json");
-}
-
-/**
- * Path to `<hqRoot>/.hq/machine-id` — the source-of-truth file.
- */
-function hqRootMachineIdPath(hqRoot: string): string {
-  return path.join(hqRoot, ".hq", "machine-id");
-}
-
-/**
- * Read the persisted id from `<hqRoot>/.hq/machine-id`, or undefined if
- * absent/unreadable/empty. Trims trailing whitespace so manual edits with
- * a final newline don't break attribution.
- */
-function readHqRootMachineId(hqRoot: string): string | undefined {
-  try {
-    const raw = fs.readFileSync(hqRootMachineIdPath(hqRoot), "utf-8").trim();
-    return raw.length > 0 ? raw : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Read the menubar-written id from `~/.hq/menubar.json`, or undefined if
- * the file is missing / unreadable / doesn't contain a string `machineId`.
- */
-function readMenubarMachineId(): string | undefined {
-  try {
-    const raw = fs.readFileSync(menubarJsonPath(), "utf-8");
-    const parsed = JSON.parse(raw) as { machineId?: unknown };
-    if (typeof parsed.machineId === "string" && parsed.machineId.length > 0) {
-      return parsed.machineId;
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Persist `id` to `<hqRoot>/.hq/machine-id`. Best-effort — failures are
- * silent so a read-only hqRoot (e.g. a CI mount) still gets a working id
- * for the current process, even if it can't be persisted for the next run.
- */
-function persistMachineId(hqRoot: string, id: string): void {
-  try {
-    fs.mkdirSync(path.join(hqRoot, ".hq"), { recursive: true });
-    fs.writeFileSync(hqRootMachineIdPath(hqRoot), `${id}\n`);
-  } catch {
-    // Read-only filesystem or permission issue — caller gets the id back
-    // anyway. Next sync run will retry the persist.
-  }
-}
-
-/**
- * Resolve or provision the machine id for this host, persisting it to
- * `<hqRoot>/.hq/machine-id` so the result is stable across sync runs.
- *
- * Returns the full id (UUID-shaped on first generation, free-form when
- * migrated from a menubar.json that wrote something non-UUID). Use
- * {@link readShortMachineId} for the 6-char prefix used in conflict
- * filenames.
- */
-export function getOrCreateMachineId(hqRoot: string): string {
-  // Tier 1: env override.
-  const fromEnv = process.env.HQ_MACHINE_ID;
-  if (fromEnv && fromEnv.length > 0) return fromEnv;
-
-  // Tier 2: persisted source-of-truth.
-  const persisted = readHqRootMachineId(hqRoot);
-  if (persisted) return persisted;
-
-  // Tier 3: back-compat read of menubar.json. Migrate forward on first hit
-  // so subsequent calls take tier 2 and the menubar dependency drops out.
-  const fromMenubar = readMenubarMachineId();
-  if (fromMenubar) {
-    persistMachineId(hqRoot, fromMenubar);
-    return fromMenubar;
-  }
-
-  // Tier 4: autogen + persist.
-  const fresh = randomUUID();
-  persistMachineId(hqRoot, fresh);
-  return fresh;
-}
-
-/**
- * Short form (six hex chars) for use in conflict filenames. The short
- * token is what gets stamped into `<orig>.conflict-<ts>-<short>.<ext>` —
- * see `buildConflictPath` in `./conflict-file.ts`.
- *
- * **Always returns `[a-f0-9]{6}`** so the resulting filename matches the
- * `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts`. Tier 1 (`HQ_MACHINE_ID`)
- * and tier 3 (legacy menubar values) can return arbitrary non-hex strings
- * — e.g. an env override of `"ci-runner-42"` or a menubar-written
- * `"menubar-legacy-id"`. Slicing those raw would produce `ci-run` or
- * `menuba`, which the ephemeral filter would refuse and the push walker
- * would round-trip to S3 — the exact litter-ratchet bug this module
- * exists to close.
- *
- * Normalization: if the first 6 chars of the resolved id are all hex
- * (the typical UUID / hex-id case), use them as-is so the short token
- * remains an intuitive prefix of the full id. Otherwise derive a
- * deterministic SHA-1 hash of the full id and take the first 6 chars —
- * stable across calls, attributable to the same machine, always hex.
- */
-export function readShortMachineId(hqRoot: string): string {
-  const full = getOrCreateMachineId(hqRoot);
-  const head = full.slice(0, 6);
-  if (/^[a-f0-9]{6}$/.test(head)) return head;
-  return createHash("sha1").update(full).digest("hex").slice(0, 6);
-}
-
-/**
- * Test-only exports. Mirrors the `_testing` namespace pattern used by
- * `src/cli/share.ts` so regression-critical helpers can be pinned by
- * direct unit tests without round-tripping through the public API.
- */
-export const _testing = {
-  menubarJsonPath,
-  hqRootMachineIdPath,
-  readHqRootMachineId,
-  readMenubarMachineId,
-  persistMachineId,
-};

package/src/lib/net-errors.test.ts

@@ -1,65 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { isTransientNetworkError, TRANSIENT_NETWORK_EXIT } from "./net-errors.js";
-
-describe("isTransientNetworkError", () => {
-  it("treats undici's canonical `fetch failed` TypeError as transient", () => {
-    // This is the exact shape the runner's discovery step sees in production
-    // (HQ-SYNC-1W): `{"type":"error","message":"fetch failed","path":"(discovery)"}`.
-    expect(isTransientNetworkError(new TypeError("fetch failed"))).toBe(true);
-  });
-
-  it("treats direct transport `.code`s as transient", () => {
-    for (const code of ["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ETIMEDOUT"]) {
-      const err = Object.assign(new Error("boom"), { code });
-      expect(isTransientNetworkError(err)).toBe(true);
-    }
-  });
-
-  it("walks the .cause chain (fetch failed wrapping a DNS error)", () => {
-    const cause = Object.assign(new Error("getaddrinfo ENOTFOUND api"), {
-      code: "ENOTFOUND",
-    });
-    const err = Object.assign(new TypeError("fetch failed"), { cause });
-    expect(isTransientNetworkError(err)).toBe(true);
-  });
-
-  it("walks an AWS SDK UnknownError cause chain to the underlying DNS error", () => {
-    const cause = Object.assign(
-      new Error("getaddrinfo ENOTFOUND hq-vault-prs-test.s3.us-east-1.amazonaws.com"),
-      { code: "ENOTFOUND", syscall: "getaddrinfo" },
-    );
-    const err = Object.assign(new Error("UnknownError"), {
-      name: "UnknownError",
-      cause,
-    });
-    expect(isTransientNetworkError(err)).toBe(true);
-  });
-
-  it("walks AggregateError.errors (happy-eyeballs)", () => {
-    const agg = Object.assign(new AggregateError([
-      Object.assign(new Error("v4"), { code: "ECONNREFUSED" }),
-      Object.assign(new Error("v6"), { code: "EHOSTUNREACH" }),
-    ], "all attempts failed"), {});
-    expect(isTransientNetworkError(agg)).toBe(true);
-  });
-
-  it("is conservative: an arbitrary error is NOT transient", () => {
-    // A bare message like "network down" (no code, not the canonical undici
-    // message) must not be misclassified — only real transport shapes qualify.
-    expect(isTransientNetworkError(new Error("network down"))).toBe(false);
-    expect(isTransientNetworkError(new Error("boom"))).toBe(false);
-    expect(isTransientNetworkError("fetch failed")).toBe(false);
-    expect(isTransientNetworkError(undefined)).toBe(false);
-  });
-
-  it("does not infinite-loop on a self-referential cause", () => {
-    const err = new Error("weird") as Error & { cause?: unknown };
-    err.cause = err;
-    expect(isTransientNetworkError(err)).toBe(false);
-  });
-
-  it("exposes a distinct exit code off the runner's other codes", () => {
-    expect(TRANSIENT_NETWORK_EXIT).toBe(75);
-    expect([0, 1, 2, 17]).not.toContain(TRANSIENT_NETWORK_EXIT);
-  });
-});

package/src/lib/net-errors.ts

@@ -1,86 +0,0 @@
-/**
- * Transient network-failure classification for the sync runner.
- *
- * The auto-sync watcher runs an unattended poll loop. At the top of every pass
- * it calls `GET /membership/me` to resolve which companies to sync, then it
- * runs a per-company fanout. When the machine is briefly offline (wifi drop,
- * waking from sleep, a DNS blip, the vault API or a vault S3 endpoint
- * momentarily unreachable), either boundary can fail at the transport layer —
- * Node's `fetch` throws `TypeError: fetch failed` with the real cause (an
- * `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` / … Error) on `.cause`.
- *
- * This is NOT a crash: the next poll (~30s later) succeeds once the network is
- * back. But the runner used to `return 1` for it, the watch loop propagated
- * that non-zero exit, the process exited, and the menubar supervisor reported
- * "auto-sync watcher exited unexpectedly (code=Some(1))" for every blip — the
- * HQ-SYNC-1W cluster. A company-leg failure was also previously counted as an
- * exit-2 partial sync, producing the HQ-SYNC-X symptom even though it was just
- * retryable DNS/transport loss. We classify both boundaries so the watch loop
- * can stay alive and retry instead of surfacing a false crash, while a one-shot
- * `hq sync` still exits non-zero so a human running it by hand sees the failure.
- */
-
-/**
- * Distinct runner exit code for a transient network failure. The watch loop
- * treats it as "stay alive, retry next tick" (never a crash); a one-shot run
- * still exits non-zero so the failure is visible to a human/script. Value 75 =
- * `EX_TEMPFAIL` from sysexits.h ("temporary failure; retry"). Kept off the
- * codes already in use by the runner (0 ok, 1 error, 2 partial, 17 op-locked).
- */
-export const TRANSIENT_NETWORK_EXIT = 75;
-
-/**
- * Node/undici error `code`s that mean "the request never completed at the
- * transport layer" — the machine could not reach the host. All are transient:
- * a later attempt from the same machine can succeed unchanged.
- */
-const TRANSIENT_CODES = new Set<string>([
-  "ECONNREFUSED",
-  "ECONNRESET",
-  "ENOTFOUND",
-  "EAI_AGAIN",
-  "ETIMEDOUT",
-  "EPIPE",
-  "EHOSTUNREACH",
-  "EHOSTDOWN",
-  "ENETUNREACH",
-  "ENETDOWN",
-  "ECONNABORTED",
-  // undici's own timeout/socket failures
-  "UND_ERR_CONNECT_TIMEOUT",
-  "UND_ERR_HEADERS_TIMEOUT",
-  "UND_ERR_BODY_TIMEOUT",
-  "UND_ERR_SOCKET",
-]);
-
-/**
- * True when `err` is (or wraps) a transient network-transport failure. Walks the
- * `.cause` chain and `AggregateError.errors` (undici's happy-eyeballs raises the
- * latter), matching either undici's canonical `TypeError: fetch failed` message
- * or a known transient `.code`. Conservative by design: an arbitrary
- * `new Error("network down")` with no code and a non-canonical message is NOT
- * treated as transient, so only real transport-failure shapes qualify.
- */
-export function isTransientNetworkError(err: unknown, depth = 0): boolean {
-  if (depth > 8 || !(err instanceof Error)) return false;
-
-  // undici's transport failure surfaces as exactly this message.
-  if (err.message === "fetch failed") return true;
-
-  const code = (err as { code?: unknown }).code;
-  if (typeof code === "string" && TRANSIENT_CODES.has(code)) return true;
-
-  // AggregateError (e.g. happy-eyeballs) stashes the per-attempt errors here.
-  const aggregated = (err as { errors?: unknown }).errors;
-  if (Array.isArray(aggregated)) {
-    for (const inner of aggregated) {
-      if (isTransientNetworkError(inner, depth + 1)) return true;
-    }
-  }
-
-  const cause = (err as { cause?: unknown }).cause;
-  if (cause !== undefined && cause !== err) {
-    return isTransientNetworkError(cause, depth + 1);
-  }
-  return false;
-}

package/src/lib/readlink-safe.test.ts

@@ -1,43 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { readlinkOrNull } from "./readlink-safe.js";
-
-function errnoError(code: string): NodeJS.ErrnoException {
-  const err = new Error(`${code}: scripted readlink failure`) as NodeJS.ErrnoException;
-  err.code = code;
-  return err;
-}
-
-describe("readlinkOrNull", () => {
-  it("uses the filesystem reader by default", () => {
-    expect(readlinkOrNull(`/hq-cloud-missing-link-${process.pid}`)).toBeNull();
-  });
-
-  it("returns the target string verbatim when readlink succeeds", () => {
-    expect(readlinkOrNull("/test/link", () => "../target with spaces")).toBe(
-      "../target with spaces",
-    );
-  });
-
-  it.each(["EINVAL", "ENOENT", "EPERM"])("returns null for %s", (code) => {
-    expect(readlinkOrNull("/test/link", () => {
-      throw errnoError(code);
-    })).toBeNull();
-  });
-
-  it("rethrows non-filesystem failures", () => {
-    const defect = new Error("unexpected test defect");
-
-    expect(() => readlinkOrNull("/test/link", () => {
-      throw defect;
-    })).toThrow(defect);
-  });
-
-  it("rethrows code-bearing programming errors", () => {
-    const defect = new TypeError("path must be a string") as TypeError & { code: string };
-    defect.code = "ERR_INVALID_ARG_TYPE";
-
-    expect(() => readlinkOrNull("/test/link", () => {
-      throw defect;
-    })).toThrow(defect);
-  });
-});

package/src/lib/readlink-safe.ts

@@ -1,29 +0,0 @@
-import * as fs from "fs";
-
-/**
- * Read a link target without turning an expected filesystem race or an
- * unsupported link shape into a caller-wide failure.
- *
- * A `null` result is deliberately distinct from an empty target string: it
- * means the caller must preserve the link boundary and choose its conservative
- * skip/defer path. Non-filesystem exceptions still propagate so programming
- * errors cannot be mistaken for an unreadable link.
- */
-export function readlinkOrNull(
-  linkPath: string,
-  readlink: (path: string) => string = (path) => fs.readlinkSync(path, "utf8"),
-): string | null {
-  try {
-    return readlink(linkPath);
-  } catch (err: unknown) {
-    const code =
-      err && typeof err === "object" && "code" in err
-        ? (err as { code?: unknown }).code
-        : undefined;
-    // Node system errors use POSIX-style errno names such as EINVAL and
-    // ENOENT. Runtime/programming errors use ERR_* codes; those must remain
-    // loud rather than being misclassified as an unreadable link.
-    if (typeof code === "string" && /^E[A-Z0-9]+$/.test(code)) return null;
-    throw err;
-  }
-}