@app-vitals/agent-runtime 0.0.0-stage → 0.1.0

package/gh-helpers.unit.test.ts

@@ -0,0 +1,253 @@
+/**
+ * agent/src/runtime/gh-helpers.unit.test.ts
+ *
+ * Unit tests for getCurrentUser("acme") and ghGraphql() in gh-helpers.ts
+ * (relocated from check-helpers.unit.test.ts, ARD-4.1).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  chmodSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  getCurrentUser,
+  ghGraphql,
+  ghJson,
+  ghRun,
+  ownerOfRepo,
+} from "./gh-helpers.ts";
+
+/**
+ * Write a fake `gh` binary into dir that returns the given GraphQL viewer
+ * response JSON. Returns the path to the fake binary.
+ *
+ * The fake binary is added to PATH by the test beforeEach/afterEach helpers.
+ */
+function writeFakeGhBinary(dir: string, viewerLogin: string): string {
+  const binPath = join(dir, "gh");
+  const response = JSON.stringify({ data: { viewer: { login: viewerLogin } } });
+  // A minimal shell script that ignores all args and prints the baked response.
+  writeFileSync(binPath, `#!/bin/sh\nprintf '%s\\n' '${response}'\n`);
+  chmodSync(binPath, 0o755);
+  return binPath;
+}
+
+/** Write a fake `gh` binary that always fails with a given exit code. */
+function writeFailingGhBinary(
+  dir: string,
+  exitCode: number,
+  stderr: string,
+): string {
+  const binPath = join(dir, "gh");
+  writeFileSync(
+    binPath,
+    `#!/bin/sh\nprintf '%s\\n' '${stderr}' >&2\nexit ${exitCode}\n`,
+  );
+  chmodSync(binPath, 0o755);
+  return binPath;
+}
+
+describe("getCurrentUser", () => {
+  let tmpDir: string;
+  let savedPath: string | undefined;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "get-current-user-test-"));
+    savedPath = process.env.PATH;
+  });
+
+  afterEach(() => {
+    if (savedPath !== undefined) {
+      process.env.PATH = savedPath;
+    }
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns login as-is for a regular PAT user", async () => {
+    writeFakeGhBinary(tmpDir, "dmcaulay");
+    process.env.PATH = `${tmpDir}:${savedPath}`;
+    const result = await getCurrentUser("acme");
+    expect(result).toBe("dmcaulay");
+  });
+
+  test("normalises [bot] suffix to app/ prefix for GitHub App identity", async () => {
+    writeFakeGhBinary(tmpDir, "my-app[bot]");
+    process.env.PATH = `${tmpDir}:${savedPath}`;
+    const result = await getCurrentUser("acme");
+    expect(result).toBe("app/my-app");
+  });
+
+  test("handles hyphenated app name in [bot] normalisation", async () => {
+    writeFakeGhBinary(tmpDir, "example-repo-agent[bot]");
+    process.env.PATH = `${tmpDir}:${savedPath}`;
+    const result = await getCurrentUser("acme");
+    expect(result).toBe("app/example-repo-agent");
+  });
+
+  test("throws when gh exits non-zero", async () => {
+    writeFailingGhBinary(tmpDir, 1, "not authenticated");
+    process.env.PATH = `${tmpDir}:${savedPath}`;
+    await expect(getCurrentUser("acme")).rejects.toThrow(
+      "gh api graphql failed",
+    );
+  });
+});
+
+describe("ghGraphql retry", () => {
+  let tmpDir: string;
+  let savedPath: string | undefined;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gh-graphql-retry-test-"));
+    savedPath = process.env.PATH;
+    process.env.PATH = `${tmpDir}:${savedPath}`;
+  });
+
+  afterEach(() => {
+    if (savedPath !== undefined) {
+      process.env.PATH = savedPath;
+    }
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  /** Fake gh that fails `failures` times with `stderr`, then succeeds. Counts calls. */
+  function writeFlakyGh(failures: number, stderr: string): string {
+    const counter = join(tmpDir, "count");
+    writeFileSync(counter, "0");
+    writeFileSync(
+      join(tmpDir, "gh"),
+      `#!/bin/sh
+n=$(cat "${counter}"); n=$((n+1)); echo $n > "${counter}"
+if [ $n -le ${failures} ]; then printf '%s\\n' '${stderr}' >&2; exit 1; fi
+printf '%s\\n' '{"ok":true}'
+`,
+    );
+    chmodSync(join(tmpDir, "gh"), 0o755);
+    return counter;
+  }
+
+  const calls = (counter: string) => Number(readFileSync(counter, "utf8"));
+
+  test("retries a transient 504 and succeeds", async () => {
+    const counter = writeFlakyGh(2, "gh: HTTP 504");
+    const result = await ghGraphql<{ ok: boolean }>("query {}", "acme", {
+      baseDelayMs: 1,
+    });
+    expect(result).toEqual({ ok: true });
+    expect(calls(counter)).toBe(3);
+  });
+
+  test("throws the standard error after exhausting retries", async () => {
+    const counter = writeFlakyGh(99, "gh: HTTP 504");
+    await expect(
+      ghGraphql("query {}", "acme", { baseDelayMs: 1 }),
+    ).rejects.toThrow("gh api graphql failed (exit 1): gh: HTTP 504");
+    expect(calls(counter)).toBe(3);
+  });
+
+  test("does not retry a non-transient failure", async () => {
+    const counter = writeFlakyGh(99, "gh: HTTP 401 bad credentials");
+    await expect(
+      ghGraphql("query {}", "acme", { baseDelayMs: 1 }),
+    ).rejects.toThrow("gh api graphql failed");
+    expect(calls(counter)).toBe(1);
+  });
+});
+
+describe("ghGraphql owner hint", () => {
+  let tmpDir: string;
+  let savedPath: string | undefined;
+  let savedOwner: string | undefined;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "gh-graphql-owner-test-"));
+    savedPath = process.env.PATH;
+    savedOwner = process.env.SHIPWRIGHT_GH_OWNER;
+    delete process.env.SHIPWRIGHT_GH_OWNER;
+    process.env.PATH = `${tmpDir}:${savedPath}`;
+    // Fake gh echoing the owner hint it was spawned with.
+    writeFileSync(
+      join(tmpDir, "gh"),
+      `#!/bin/sh\nprintf '{"owner":"%s"}\\n' "$SHIPWRIGHT_GH_OWNER"\n`,
+    );
+    chmodSync(join(tmpDir, "gh"), 0o755);
+  });
+
+  afterEach(() => {
+    if (savedPath !== undefined) process.env.PATH = savedPath;
+    if (savedOwner === undefined) delete process.env.SHIPWRIGHT_GH_OWNER;
+    else process.env.SHIPWRIGHT_GH_OWNER = savedOwner;
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("ghGraphql sets SHIPWRIGHT_GH_OWNER in the spawned env", async () => {
+    const result = await ghGraphql<{ owner: string }>("query {}", "acme");
+    expect(result.owner).toBe("acme");
+  });
+
+  test("ghJson sets SHIPWRIGHT_GH_OWNER in the spawned env", async () => {
+    const result = await ghJson<{ owner: string }>(["api", "x"], "acme");
+    expect(result.owner).toBe("acme");
+  });
+
+  test("ghRun sets SHIPWRIGHT_GH_OWNER in the spawned env", async () => {
+    const out = join(tmpDir, "run-owner");
+    writeFileSync(
+      join(tmpDir, "gh"),
+      `#!/bin/sh\nprintf '%s' "$SHIPWRIGHT_GH_OWNER" > "${out}"\n`,
+    );
+    chmodSync(join(tmpDir, "gh"), 0o755);
+    await ghRun(["api", "x"], "acme");
+    expect(readFileSync(out, "utf8")).toBe("acme");
+  });
+
+  test("the explicit owner overrides an ambient SHIPWRIGHT_GH_OWNER", async () => {
+    process.env.SHIPWRIGHT_GH_OWNER = "ambient";
+    const result = await ghGraphql<{ owner: string }>("query {}", "acme");
+    expect(result.owner).toBe("acme");
+  });
+
+  test("getCurrentUser forwards its owner to the gh env", async () => {
+    writeFileSync(
+      join(tmpDir, "gh"),
+      `#!/bin/sh\nprintf '{"data":{"viewer":{"login":"%s"}}}\\n' "$SHIPWRIGHT_GH_OWNER"\n`,
+    );
+    chmodSync(join(tmpDir, "gh"), 0o755);
+    expect(await getCurrentUser("acme")).toBe("acme");
+  });
+
+  test("does not mutate the parent process env", async () => {
+    await ghGraphql("query {}", "acme");
+    expect(process.env.SHIPWRIGHT_GH_OWNER).toBeUndefined();
+  });
+
+  test("owner is required at the type level", () => {
+    const never = async () => {
+      // @ts-expect-error owner is required
+      await ghJson<unknown>(["api", "x"]);
+      // @ts-expect-error owner is required
+      await ghRun(["api", "x"]);
+      // @ts-expect-error owner is required
+      await ghGraphql("query {}");
+      // @ts-expect-error owner is required
+      await getCurrentUser();
+    };
+    expect(typeof never).toBe("function");
+  });
+});
+
+describe("ownerOfRepo", () => {
+  test("returns the org half of org/repo", () => {
+    expect(ownerOfRepo("acme/widgets")).toBe("acme");
+  });
+
+  test("throws rather than guessing when there is no org", () => {
+    expect(() => ownerOfRepo("widgets")).toThrow("Cannot derive GitHub owner");
+  });
+});

package/gh-token-files.integration.test.ts

@@ -0,0 +1,143 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeFileAtomic, writeTokenFiles } from "./gh-token-files.ts";
+
+let home: string;
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "gh-token-files-"));
+});
+afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+describe("writeTokenFiles", () => {
+  test("single installation writes gh-token and its per-owner file", () => {
+    writeTokenFiles(home, { defaultToken: "t1", ownerTokens: { Acme: "t1" } });
+    expect(readFileSync(join(home, "gh-token"), "utf8")).toBe("t1");
+    expect(readFileSync(join(home, "gh-token.d", "acme"), "utf8")).toBe("t1");
+    expect(readdirSync(home).sort()).toEqual(["gh-token", "gh-token.d"]);
+  });
+
+  test("files are mode 0600", () => {
+    writeTokenFiles(home, { defaultToken: "t1" });
+    expect(statSync(join(home, "gh-token")).mode & 0o777).toBe(0o600);
+    writeTokenFiles(home, { defaultToken: "t2" }); // overwrite keeps mode
+    expect(statSync(join(home, "gh-token")).mode & 0o777).toBe(0o600);
+  });
+
+  test("multiple installations write lowercase per-owner files", () => {
+    writeTokenFiles(home, {
+      defaultToken: "a",
+      ownerTokens: { Acme: "a", Other: "b" },
+    });
+    expect(readFileSync(join(home, "gh-token.d", "acme"), "utf8")).toBe("a");
+    expect(readFileSync(join(home, "gh-token.d", "other"), "utf8")).toBe("b");
+    expect(statSync(join(home, "gh-token.d", "other")).mode & 0o777).toBe(
+      0o600,
+    );
+  });
+
+  test("stale per-owner files are removed; the directory is kept", () => {
+    writeTokenFiles(home, {
+      defaultToken: "a",
+      ownerTokens: { acme: "a", other: "b", third: "c" },
+    });
+    writeTokenFiles(home, {
+      defaultToken: "a",
+      ownerTokens: { acme: "a", other: "b" },
+    });
+    expect(readdirSync(join(home, "gh-token.d")).sort()).toEqual([
+      "acme",
+      "other",
+    ]);
+    writeTokenFiles(home, { defaultToken: "a", ownerTokens: { acme: "a" } });
+    expect(readdirSync(join(home, "gh-token.d"))).toEqual(["acme"]);
+  });
+
+  test("failedOwners keep their last good file", () => {
+    writeTokenFiles(home, {
+      defaultToken: "a",
+      ownerTokens: { acme: "a", other: "b" },
+    });
+    writeTokenFiles(home, {
+      defaultToken: "a2",
+      ownerTokens: { acme: "a2" },
+      failedOwners: ["Other"],
+    });
+    expect(readFileSync(join(home, "gh-token"), "utf8")).toBe("a2");
+    expect(readFileSync(join(home, "gh-token.d", "acme"), "utf8")).toBe("a2");
+    expect(readFileSync(join(home, "gh-token.d", "other"), "utf8")).toBe("b");
+  });
+
+  test("owners neither minted nor failed are still cleaned up; the dir is kept with one owner", () => {
+    writeTokenFiles(home, {
+      defaultToken: "a",
+      ownerTokens: { acme: "a", other: "b", third: "c" },
+    });
+    writeTokenFiles(home, {
+      defaultToken: "a",
+      ownerTokens: { acme: "a" },
+      failedOwners: ["other"],
+    });
+    expect(readdirSync(join(home, "gh-token.d")).sort()).toEqual([
+      "acme",
+      "other",
+    ]);
+    writeTokenFiles(home, { defaultToken: "a", ownerTokens: { acme: "a" } });
+    expect(readdirSync(join(home, "gh-token.d"))).toEqual(["acme"]);
+  });
+
+  test("never logs a removal or token values when the owner set shrinks", () => {
+    const logSpy = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      writeTokenFiles(home, {
+        defaultToken: "secret-a",
+        ownerTokens: { acme: "secret-a", other: "secret-b" },
+      });
+      writeTokenFiles(home, {
+        defaultToken: "secret-a",
+        ownerTokens: { acme: "secret-a" },
+      });
+      expect(logSpy).not.toHaveBeenCalled();
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  test("absent defaultToken leaves gh-token untouched", () => {
+    writeTokenFiles(home, { defaultToken: "keep" });
+    writeTokenFiles(home, { ownerTokens: { acme: "a", other: "b" } });
+    expect(readFileSync(join(home, "gh-token"), "utf8")).toBe("keep");
+  });
+
+  test("path-traversal owner is rejected before anything is written", () => {
+    expect(() =>
+      writeTokenFiles(home, {
+        defaultToken: "a",
+        ownerTokens: { "../x": "a", ok: "b" },
+      }),
+    ).toThrow();
+    expect(readdirSync(home)).toEqual([]);
+  });
+});
+
+describe("writeFileAtomic", () => {
+  test("leaves no temp files and never exposes a torn file under racing writers", async () => {
+    const path = join(home, "gh-token");
+    const values = ["a".repeat(4096), "b".repeat(4096)];
+    writeFileAtomic(path, values[0]);
+    await Promise.all(
+      Array.from({ length: 50 }, async (_, i) => {
+        writeFileAtomic(path, values[i % 2]);
+        expect(values).toContain(readFileSync(path, "utf8"));
+      }),
+    );
+    expect(readdirSync(home)).toEqual(["gh-token"]);
+  });
+});

package/gh-token-files.ts

@@ -0,0 +1,92 @@
+/**
+ * agent/src/runtime/gh-token-files.ts
+ *
+ * Atomic token-file layer. `gh-token` always holds the default installation's
+ * token; `gh-token.d/<lowercase-owner>` always holds per-owner tokens for
+ * every usable installation, even when only one is usable (App auth only —
+ * PAT auth never reaches this module). Two processes (entrypoint-main and
+ * index.ts) write the same files, so every write is temp file + rename —
+ * readers never observe a torn file.
+ */
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/** GitHub owner (user/org) login: alphanumerics and single hyphens, max 39, no leading/trailing hyphen. */
+const GITHUB_OWNER_PATTERN = /^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i;
+
+export function validateOwner(owner: string): string {
+  if (!GITHUB_OWNER_PATTERN.test(owner)) {
+    throw new Error(`Invalid GitHub owner name: ${JSON.stringify(owner)}`);
+  }
+  return owner.toLowerCase();
+}
+
+/** Write via a unique temp file in the same directory, then rename over the target (mode 0600). */
+export function writeFileAtomic(path: string, content: string): void {
+  const tmp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, content, { mode: 0o600 });
+    chmodSync(tmp, 0o600); // mode above is masked by umask and ignored on overwrite
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+export interface TokenFilesInput {
+  /** Default installation's token, written to `gh-token`. Absent → `gh-token` is left as is. */
+  defaultToken?: string;
+  /** Per-owner tokens for every usable installation (including the default's owner). */
+  ownerTokens?: Record<string, string>;
+  /**
+   * Owners whose mint failed transiently. Their existing per-owner files are
+   * left untouched and are not pruned.
+   */
+  failedOwners?: string[];
+}
+
+/**
+ * Write `gh-token` and the per-owner files (dir mode 0700, files 0600), then
+ * prune per-owner entries that are neither minted nor failed. The directory is
+ * kept even when only one installation remains.
+ */
+export function writeTokenFiles(
+  agentHome: string,
+  input: TokenFilesInput,
+): void {
+  const dir = join(agentHome, "gh-token.d");
+  const owners = Object.entries(input.ownerTokens ?? {}).map(
+    ([owner, token]) => [validateOwner(owner), token] as const,
+  );
+
+  const failed = (input.failedOwners ?? []).map(validateOwner);
+
+  if (input.defaultToken !== undefined) {
+    writeFileAtomic(join(agentHome, "gh-token"), input.defaultToken);
+  }
+
+  // Nothing to track (e.g. a default-token-only write): don't create an empty
+  // directory, which would make the credential helper deny every owner.
+  if (owners.length === 0 && failed.length === 0 && !existsSync(dir)) return;
+
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  for (const [owner, token] of owners) writeFileAtomic(join(dir, owner), token);
+
+  const keep = new Set([...owners.map(([owner]) => owner), ...failed]);
+  for (const name of readdirSync(dir)) {
+    if (!keep.has(name) && !name.endsWith(".tmp")) {
+      rmSync(join(dir, name), { force: true });
+    }
+  }
+}

package/gh-token-files.unit.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { validateOwner, writeTokenFiles } from "./gh-token-files.ts";
+
+describe("validateOwner", () => {
+  test("lowercases valid owners", () => {
+    expect(validateOwner("App-Vitals")).toBe("app-vitals");
+    expect(validateOwner("a")).toBe("a");
+  });
+  test.each([
+    "../x",
+    "a/b",
+    "",
+    "-a",
+    "a-",
+    "a--b",
+    "a.b",
+    "x".repeat(40),
+    "a\0b",
+  ])("rejects %p", (bad) => {
+    expect(() => validateOwner(bad)).toThrow();
+  });
+});
+
+describe("writeTokenFiles — single installation", () => {
+  let home: string;
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "gh-token-files-unit-"));
+  });
+  afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+  test("writes the lowercase owner file (0600) in a 0700 directory", () => {
+    writeTokenFiles(home, { defaultToken: "t1", ownerTokens: { Acme: "t1" } });
+    expect(readFileSync(join(home, "gh-token"), "utf8")).toBe("t1");
+    expect(readFileSync(join(home, "gh-token.d", "acme"), "utf8")).toBe("t1");
+    expect(statSync(join(home, "gh-token.d", "acme")).mode & 0o777).toBe(0o600);
+    expect(statSync(join(home, "gh-token.d")).mode & 0o777).toBe(0o700);
+  });
+
+  test("the directory is kept when only one installation remains; stale owners are pruned", () => {
+    writeTokenFiles(home, {
+      defaultToken: "a",
+      ownerTokens: { acme: "a", other: "b" },
+    });
+    writeTokenFiles(home, { defaultToken: "a", ownerTokens: { acme: "a" } });
+    expect(existsSync(join(home, "gh-token.d"))).toBe(true);
+    expect(readdirSync(join(home, "gh-token.d"))).toEqual(["acme"]);
+  });
+
+  test("a default-token-only write creates no gh-token.d", () => {
+    writeTokenFiles(home, { defaultToken: "t1" });
+    expect(readdirSync(home)).toEqual(["gh-token"]);
+  });
+});