@app-vitals/agent-runtime 0.0.1 → 0.1.1

package/setup-github-auth.ts

@@ -0,0 +1,297 @@
+/**
+ * agent/src/runtime/setup-github-auth.ts
+ *
+ * Wires GitHub authentication on agent startup.
+ *
+ * - GitHub App path (GH_APP_ID + GH_APP_PRIVATE_KEY): engages only if the
+ *   GH_APP_INSTALLATION_ID pin is set or installation discovery finds at
+ *   least one usable in-scope installation. Mints the default installation's
+ *   token into the token file (plus a per-owner file for every
+ *   usable installation, even a single one), configures the git credential helper + author identity, and
+ *   starts exactly one background refresh.
+ * - PAT path: runs `gh auth setup-git` (legacy flow preserved) whenever App
+ *   auth did not engage.
+ * - Neither: skips; the caller retries on its next tick.
+ *
+ * Resolves true iff App auth activated. Not safely re-invokable after it
+ * resolves true — each activation starts its own refresh interval — so
+ * callers gate repeat calls on that result (github-auth-startup.ts).
+ */
+
+import type { TokenFilesInput } from "./gh-token-files.ts";
+import type { BotIdentity } from "./github-app-auth.ts";
+import type { InstallationsSnapshot } from "./github-installations.ts";
+
+interface TokenManagerLike {
+  getToken(): Promise<string>;
+  startBackgroundRefresh(onRefresh: (token: string) => Promise<void>): void;
+}
+
+export interface GitHubAuthDeps {
+  env: Record<string, string | undefined>;
+  createTokenManager: () => TokenManagerLike;
+  getBotIdentity: () => Promise<BotIdentity>;
+  spawnSync: (
+    cmd: string,
+    args: string[],
+    opts: {
+      stdio: "inherit" | "pipe" | "ignore";
+      env: Record<string, string | undefined>;
+    },
+  ) => { status: number | null };
+  writeToken: (token: string) => void;
+  tokenPath: string;
+  credentialHelperPath: string;
+  logger?: { error: (...args: unknown[]) => void };
+  /**
+   * Installation discovery. When absent, App auth requires the
+   * GH_APP_INSTALLATION_ID pin and uses the single-installation token
+   * manager (the pre-discovery behavior).
+   */
+  installations?: GitHubInstallationsDeps;
+}
+
+/** The slice of GitHubInstallationsManager setupGitHubAuth drives. */
+interface InstallationsManagerLike {
+  reconcile(scopeOwners: string[] | null): Promise<void>;
+  getState(): InstallationsSnapshot;
+  getToken(installationId: number): Promise<string>;
+  start(): void;
+}
+
+export interface GitHubInstallationsDeps {
+  /**
+   * Builds a manager; it must call `onTokensChanged` whenever a token may
+   * have changed (mint, or installation set/health change).
+   */
+  createManager: (onTokensChanged: () => void) => InstallationsManagerLike;
+  /** Scoped repo owners, or null while scope is unsynced (pinned-only). */
+  getScopeOwners: () => string[] | null;
+  writeTokenFiles: (input: TokenFilesInput) => void;
+  /** Called once with the manager App auth activated with. */
+  onActivated?: (manager: InstallationsManagerLike) => void;
+}
+
+function runOrWarn(
+  spawnSync: GitHubAuthDeps["spawnSync"],
+  cmd: string,
+  args: string[],
+  env: Record<string, string | undefined>,
+  logger: { error: (...args: unknown[]) => void } = console,
+): void {
+  const { status } = spawnSync(cmd, args, { stdio: "inherit", env });
+  if (status !== 0) {
+    logger.error(
+      `[entrypoint] ${cmd} ${args.join(" ")} exited with status ${status} — git auth may be broken`,
+    );
+  }
+}
+
+export async function setupGitHubAuth(deps: GitHubAuthDeps): Promise<boolean> {
+  const { env, spawnSync, logger } = deps;
+
+  // Repos on the PVC may be owned by root (uid 0) while the agent runs as uid 1000.
+  // Set safe.directory unconditionally so git can operate on them regardless of auth path.
+  runOrWarn(
+    spawnSync,
+    "git",
+    ["config", "--global", "safe.directory", "*"],
+    env,
+    logger,
+  );
+
+  const appId = env.GH_APP_ID;
+  const installationId = env.GH_APP_INSTALLATION_ID;
+  const privateKey = env.GH_APP_PRIVATE_KEY;
+
+  if (appId && privateKey) {
+    if (deps.installations) {
+      const pending = await prepareInstallations(deps, deps.installations);
+      if (pending) {
+        const identity = await configureAppGit(deps);
+        // Started only after git config succeeded, so a failed setup (retried
+        // next tick) never leaves a refresh interval behind.
+        pending.start();
+        logAppConfigured(identity);
+        return true;
+      }
+    }
+    if (installationId) {
+      await setupPinnedTokenManager(deps);
+      return true;
+    }
+  }
+
+  if (env.GH_TOKEN) {
+    runOrWarn(spawnSync, "gh", ["auth", "setup-git"], env, logger);
+    console.log(
+      "[entrypoint] GitHub PAT auth configured — git credential helper installed",
+    );
+    return false;
+  }
+
+  console.log(
+    "[entrypoint] No usable GitHub credentials — skipping GitHub setup",
+  );
+  return false;
+}
+
+/** Points git at the token file and sets the App bot as commit author. */
+async function configureAppGit(deps: GitHubAuthDeps): Promise<AppIdentity> {
+  const { env, spawnSync, tokenPath, credentialHelperPath, logger } = deps;
+  env.GH_TOKEN_FILE = tokenPath;
+  runOrWarn(
+    spawnSync,
+    "git",
+    [
+      "config",
+      "--global",
+      "credential.https://github.com.helper",
+      `!${credentialHelperPath}`,
+    ],
+    env,
+    logger,
+  );
+  // Makes git send the repo path to the helper so it can pick the per-owner
+  // token. Host-scoped only; the helper ignores it unless gh-token.d exists.
+  runOrWarn(
+    spawnSync,
+    "git",
+    ["config", "--global", "credential.https://github.com.useHttpPath", "true"],
+    env,
+    logger,
+  );
+
+  const { slug, userId } = await deps.getBotIdentity();
+  const botEmail = `${userId}+${slug}[bot]@users.noreply.github.com`;
+  runOrWarn(
+    spawnSync,
+    "git",
+    ["config", "--global", "user.name", `${slug}[bot]`],
+    env,
+    logger,
+  );
+  runOrWarn(
+    spawnSync,
+    "git",
+    ["config", "--global", "user.email", botEmail],
+    env,
+    logger,
+  );
+  return { slug, userId };
+}
+
+type AppIdentity = Pick<BotIdentity, "slug" | "userId">;
+
+function logAppConfigured({ slug, userId }: AppIdentity): void {
+  console.log(
+    `[entrypoint] GitHub App auth configured as ${slug}[bot] (user ${userId}), background refresh started`,
+  );
+}
+
+/** Single pinned installation via its own token manager (pre-discovery path). */
+async function setupPinnedTokenManager(deps: GitHubAuthDeps): Promise<void> {
+  console.log(
+    "[entrypoint] GitHub App credentials detected — initializing token manager",
+  );
+  const manager = deps.createTokenManager();
+  deps.writeToken(await manager.getToken());
+  const identity = await configureAppGit(deps);
+  manager.startBackgroundRefresh(async (refreshedToken) => {
+    deps.writeToken(refreshedToken);
+  });
+  logAppConfigured(identity);
+}
+
+/**
+ * Discovers installations and, if the pin or at least one in-scope
+ * installation is usable, writes the token files and returns a `start`
+ * handle that begins the manager's single refresh timer and publishes it via
+ * `onActivated`. Returns null (nothing written or started) otherwise.
+ */
+async function prepareInstallations(
+  deps: GitHubAuthDeps,
+  inst: GitHubInstallationsDeps,
+): Promise<{ start: () => void } | null> {
+  let active = false;
+  let writing: Promise<unknown> = Promise.resolve();
+  const manager = inst.createManager(() => {
+    if (!active) return;
+    writing = writing.then(() => writeInstallationTokens(manager, inst, deps));
+  });
+
+  await manager.reconcile(inst.getScopeOwners());
+  const { installations } = manager.getState();
+  if (!installations.some((i) => i.health !== "broken")) return null;
+
+  console.log(
+    `[entrypoint] GitHub App credentials detected — ${installations.length} installation(s) selected`,
+  );
+  if (!(await writeInstallationTokens(manager, inst, deps, true))) return null;
+
+  return {
+    start: () => {
+      active = true;
+      manager.start();
+      inst.onActivated?.(manager);
+    },
+  };
+}
+
+/**
+ * Writes `gh-token` (default installation) and per-owner tokens for every
+ * installation that mints. Returns false if no default token could be minted.
+ * Never throws unless `throwOnError` — refresh-time failures keep the last
+ * good files.
+ */
+async function writeInstallationTokens(
+  manager: InstallationsManagerLike,
+  inst: GitHubInstallationsDeps,
+  deps: GitHubAuthDeps,
+  throwOnError = false,
+): Promise<boolean> {
+  try {
+    const { installations, defaultId } = manager.getState();
+    const ownerTokens: Record<string, string> = {};
+    const tokenById = new Map<number, string>();
+    const failedOwners: string[] = [];
+    for (const i of installations) {
+      if (i.health === "broken") continue;
+      try {
+        const token = await manager.getToken(i.id);
+        tokenById.set(i.id, token);
+        if (i.owner) ownerTokens[i.owner] = token;
+      } catch {
+        // a failed mint never blocks the others; refresh keeps its last good file
+        if (i.owner) failedOwners.push(i.owner);
+      }
+    }
+    const defaultMinted =
+      defaultId !== null ? tokenById.get(defaultId) : undefined;
+    // Boot falls back to any minted token; refresh never substitutes another
+    // installation's token for the default.
+    const defaultToken = throwOnError
+      ? (defaultMinted ?? tokenById.values().next().value)
+      : defaultMinted;
+    if (throwOnError) {
+      if (defaultToken === undefined) return false;
+      inst.writeTokenFiles({ defaultToken, ownerTokens });
+      return true;
+    }
+    if (defaultToken === undefined && tokenById.size === 0) return false;
+    for (const owner of failedOwners) {
+      console.log(
+        `[github-auth] mint failed for ${owner} — keeping last good token file`,
+      );
+    }
+    inst.writeTokenFiles({ defaultToken, ownerTokens, failedOwners });
+    return true;
+  } catch (err) {
+    if (throwOnError) throw err;
+    (deps.logger ?? console).error(
+      "[github-auth] token file write failed:",
+      err instanceof Error ? err.message : String(err),
+    );
+    return false;
+  }
+}

package/setup.fixture.integration.test.ts

@@ -0,0 +1,109 @@
+/**
+ * AGR-1.9 — the platform seeds workspaces without any product specialty.
+ *
+ * Real temp dirs, no mocks. The fixture specialty under fixtures/specialties/
+ * stands in for a product specialty; nothing here reads a coding template.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { ensureAgentHome, resolveTemplatesDir } from "./setup.ts";
+
+// Beside the runtime source in the extracted layout, one level up in the monorepo.
+const FIXTURE_SPECIALTIES = [
+  join(import.meta.dir, "fixtures", "specialties"),
+  join(import.meta.dir, "..", "fixtures", "specialties"),
+].find((dir) => existsSync(dir)) as string;
+const FIXTURE_TEMPLATES = join(FIXTURE_SPECIALTIES, "fixture", "templates");
+const ENV = {
+  SHIPWRIGHT_SPECIALTIES_DIR: FIXTURE_SPECIALTIES,
+  SHIPWRIGHT_DEFAULT_AGENT_TYPE: "fixture",
+};
+
+let root: string;
+let home: string;
+let ws: string;
+
+beforeEach(() => {
+  root = `/tmp/test-agr19-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  home = join(root, "home");
+  ws = join(home, "workspace");
+  mkdirSync(home, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+const read = (...p: string[]) => readFileSync(join(...p), "utf8");
+
+describe("fixture specialty templates", () => {
+  it("resolves the fixture templates from the manifest without a warning", () => {
+    const warnings: string[] = [];
+    const dir = resolveTemplatesDir(
+      "fixture",
+      root,
+      (m) => warnings.push(m),
+      ENV,
+    );
+    expect(dir).toBe(FIXTURE_TEMPLATES);
+    expect(warnings).toEqual([]);
+  });
+
+  it("falls back to the configured default type when none is requested", () => {
+    const dir = resolveTemplatesDir(undefined, root, () => {}, ENV);
+    expect(dir).toBe(FIXTURE_TEMPLATES);
+  });
+
+  it("seeds a new workspace from the fixture templates", () => {
+    const dir = resolveTemplatesDir("fixture", root, () => {}, ENV);
+    ensureAgentHome(home, "fixture", dir);
+
+    for (const name of ["CLAUDE", "SOUL", "IDENTITY"]) {
+      expect(read(ws, `${name}.md`)).toBe(
+        read(FIXTURE_TEMPLATES, `${name}.md.template`),
+      );
+    }
+    expect(read(ws, "CLAUDE.md")).toContain("@SOUL.md");
+    expect(existsSync(join(ws, "RUNTIME.md"))).toBe(true);
+    expect(existsSync(join(ws, "state", "reviews"))).toBe(true);
+  });
+
+  it("never rewrites CLAUDE/SOUL/IDENTITY on a later boot but refreshes RUNTIME.md", () => {
+    const dir = resolveTemplatesDir("fixture", root, () => {}, ENV);
+    ensureAgentHome(home, "fixture", dir);
+    for (const n of ["CLAUDE", "SOUL", "IDENTITY"])
+      writeFileSync(join(ws, `${n}.md`), "mine\n");
+    writeFileSync(join(ws, "RUNTIME.md"), "stale\n");
+
+    ensureAgentHome(home, "fixture", dir);
+
+    for (const n of ["CLAUDE", "SOUL", "IDENTITY"])
+      expect(read(ws, `${n}.md`)).toBe("mine\n");
+    expect(read(ws, "RUNTIME.md")).not.toBe("stale\n");
+  });
+});
+
+describe("no default specialty configured", () => {
+  it("names the env vars when the default specialty's templates cannot be found", () => {
+    const emptyDir = join(root, "empty-templates");
+    mkdirSync(emptyDir, { recursive: true });
+    // An unresolvable default with no built-in templates to fall back to.
+    let message = "";
+    try {
+      ensureAgentHome(home, "absent", emptyDir);
+    } catch (err) {
+      message = (err as Error).message;
+    }
+    expect(message).toContain("Missing workspace template");
+    expect(message).toContain("SHIPWRIGHT_SPECIALTIES_DIR");
+    expect(message).toContain("SHIPWRIGHT_DEFAULT_AGENT_TYPE");
+  });
+});