@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/fixtures/task-store-provisioning-cassette.json

@@ -0,0 +1,85 @@
+{
+  "mintToken_success": {
+    "status": 201,
+    "body": { "id": "tok_abc123", "rawToken": "sts_raw_test_token_value" }
+  },
+  "mintToken_success_with_agentId": {
+    "status": 201,
+    "body": { "id": "tok_def456", "rawToken": "sts_raw_test_token_agent_scoped" }
+  },
+  "mintToken_500": {
+    "status": 500,
+    "body": { "error": "internal server error" }
+  },
+  "revokeToken_success": {
+    "status": 204,
+    "body": {}
+  },
+  "revokeToken_404": {
+    "status": 404,
+    "body": { "error": "not found" }
+  },
+  "revokeToken_500": {
+    "status": 500,
+    "body": { "error": "internal server error" }
+  },
+  "listTokens_mixedAgents": {
+    "status": 200,
+    "body": [
+      {
+        "id": "tok_agent1_a",
+        "label": "agent-1 token a",
+        "agentId": "agent-1",
+        "createdAt": "2026-01-01T00:00:00.000Z"
+      },
+      {
+        "id": "tok_agent2_a",
+        "label": "agent-2 token",
+        "agentId": "agent-2",
+        "createdAt": "2026-01-01T00:00:00.000Z"
+      },
+      {
+        "id": "tok_agent1_b",
+        "label": "agent-1 token b",
+        "agentId": "agent-1",
+        "createdAt": "2026-01-02T00:00:00.000Z"
+      },
+      {
+        "id": "tok_admin_noagent",
+        "label": "admin token",
+        "createdAt": "2026-01-01T00:00:00.000Z"
+      },
+      {
+        "id": "tok_agent1_revoked",
+        "label": "agent-1 already revoked",
+        "agentId": "agent-1",
+        "createdAt": "2026-01-01T00:00:00.000Z",
+        "revokedAt": "2026-01-03T00:00:00.000Z"
+      }
+    ]
+  },
+  "listTokens_noMatches": {
+    "status": 200,
+    "body": [
+      {
+        "id": "tok_agent2_a",
+        "label": "agent-2 token",
+        "agentId": "agent-2",
+        "createdAt": "2026-01-01T00:00:00.000Z"
+      },
+      {
+        "id": "tok_admin_noagent",
+        "label": "admin token",
+        "createdAt": "2026-01-01T00:00:00.000Z"
+      }
+    ]
+  },
+  "listTokens_empty": {
+    "status": 200,
+    "body": []
+  },
+  "listTokens_500": {
+    "status": 500,
+    "body": { "error": "internal server error" }
+  }
+}

package/src/github-app-provisioning-client.integration.test.ts

@@ -0,0 +1,149 @@
+/**
+ * admin/src/github-app-provisioning-client.integration.test.ts
+ * Integration tests for HttpGithubAppProvisioningClient against recorded
+ * GitHub API fixtures.
+ *
+ * Drives the client through an INJECTED fetchFn that replays canned Responses
+ * from a cassette keyed by scenario — no live API server, no global.fetch
+ * override, no mock.module(). Mirrors the pattern in
+ * slack-provisioning-client.integration.test.ts.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { HttpGithubAppProvisioningClient } from "./github-app-provisioning-client.ts";
+
+// ─── Cassette ───────────────────────────────────────────────────────────────
+
+interface CassetteEntry {
+  status: number;
+  body: unknown;
+}
+
+const CASSETTE_PATH = new URL(
+  "./fixtures/github-app-manifest-cassette.json",
+  import.meta.url,
+).pathname;
+
+const cassette: Record<string, CassetteEntry> = JSON.parse(
+  readFileSync(CASSETTE_PATH, "utf-8"),
+);
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+  headers: Headers;
+  body?: string;
+}
+
+/**
+ * Build an injected fetchFn that returns the cassette entry for `key`.
+ * Records the last request so tests can assert URL/method/headers/body.
+ */
+function cassetteFetch(key: string): {
+  fetchFn: typeof fetch;
+  lastRequest: () => RecordedRequest;
+} {
+  let last: RecordedRequest | undefined;
+  const entry = cassette[key];
+  if (!entry) throw new Error(`cassette key not found: ${key}`);
+
+  const fetchFn = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    last = {
+      url,
+      method: init?.method ?? "GET",
+      headers: new Headers(init?.headers),
+      body: typeof init?.body === "string" ? init.body : undefined,
+    };
+    return new Response(JSON.stringify(entry.body), {
+      status: entry.status,
+      statusText: `status-${entry.status}`,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as typeof fetch;
+
+  return {
+    fetchFn,
+    lastRequest: () => {
+      if (!last) throw new Error("fetchFn was not called");
+      return last;
+    },
+  };
+}
+
+function makeClient(key: string): {
+  client: HttpGithubAppProvisioningClient;
+  lastRequest: () => RecordedRequest;
+} {
+  const { fetchFn, lastRequest } = cassetteFetch(key);
+  const client = new HttpGithubAppProvisioningClient({ fetchFn });
+  return { client, lastRequest };
+}
+
+// ─── exchangeManifestCode ────────────────────────────────────────────────────
+
+describe("HttpGithubAppProvisioningClient — exchangeManifestCode", () => {
+  it("POSTs unauthenticated to app-manifests/{code}/conversions and returns narrowed fields", async () => {
+    const { client, lastRequest } = makeClient("exchangeManifestCode_success");
+    const result = await client.exchangeManifestCode("test-code");
+
+    const req = lastRequest();
+    expect(req.method).toBe("POST");
+    expect(req.url).toBe(
+      "https://api.github.com/app-manifests/test-code/conversions",
+    );
+    expect(req.headers.get("authorization")).toBeNull();
+
+    expect(result).toEqual({
+      appId: "123456",
+      slug: "test-agent-app",
+      pem: "-----BEGIN RSA PRIVATE KEY-----\ntestpemcontents\n-----END RSA PRIVATE KEY-----\n",
+      clientId: "Iv1.testclientid1234",
+      clientSecret: "test-client-secret-value",
+    });
+  });
+
+  it("never stores or returns webhook_secret", async () => {
+    const { client } = makeClient("exchangeManifestCode_success");
+    const result = await client.exchangeManifestCode("test-code");
+
+    expect(result).not.toHaveProperty("webhookSecret");
+    expect(result).not.toHaveProperty("webhook_secret");
+    expect(Object.keys(result)).not.toContain("webhookSecret");
+    expect(JSON.stringify(result)).not.toContain("test-webhook-secret");
+  });
+
+  it("throws a descriptive error on a 404 (bad/expired code)", async () => {
+    const { client } = makeClient("exchangeManifestCode_not_found");
+    await expect(client.exchangeManifestCode("bad-code")).rejects.toThrow(
+      /GitHub app-manifests conversion HTTP error: 404/,
+    );
+  });
+
+  it("throws a descriptive error on a 422 (validation failed)", async () => {
+    const { client } = makeClient("exchangeManifestCode_unprocessable");
+    await expect(client.exchangeManifestCode("bad-code")).rejects.toThrow(
+      /GitHub app-manifests conversion HTTP error: 422/,
+    );
+  });
+
+  it("throws a descriptive error when required fields are missing from an ok response", async () => {
+    const { client } = makeClient("exchangeManifestCode_missing_fields");
+    await expect(client.exchangeManifestCode("test-code")).rejects.toThrow(
+      /response missing/,
+    );
+  });
+});
+
+// ─── Default construction (no opts) ─────────────────────────────────────────
+
+describe("HttpGithubAppProvisioningClient — default construction", () => {
+  it("can be constructed with no arguments (defaults apiBase and fetchFn)", () => {
+    expect(() => new HttpGithubAppProvisioningClient()).not.toThrow();
+  });
+
+  it("can be constructed with empty opts", () => {
+    expect(() => new HttpGithubAppProvisioningClient({})).not.toThrow();
+  });
+});

package/src/github-app-provisioning-client.ts

@@ -0,0 +1,161 @@
+/**
+ * admin/src/github-app-provisioning-client.ts
+ * GithubAppProvisioningClient interface and HttpGithubAppProvisioningClient
+ * implementation.
+ *
+ * Used during the one-time agent provisioning flow:
+ *   1. Redirect the user through GitHub's "create a GitHub App from a
+ *      manifest" flow (https://docs.github.com/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest)
+ *   2. GitHub redirects back with a one-time `code`.
+ *   3. exchangeManifestCode(code) — POST app-manifests/{code}/conversions
+ *      (unauthenticated) — returns the new app's credentials directly.
+ *
+ * The conversion response also includes a `webhook_secret` field. This
+ * codebase has no webhook receiver, so it is intentionally discarded — never
+ * stored, never returned.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * GitHub's manifest flow requires a top-level `url` (the app's homepage) —
+ * every agent/org gets the same value, no per-agent plumbing needed.
+ */
+const AGENT_APP_HOMEPAGE_URL = "https://shipwrightharness.com";
+
+interface GithubAppManifest {
+  name: string;
+  public: boolean;
+  default_permissions: {
+    contents: "write";
+    pull_requests: "write";
+    actions: "read";
+    workflows: "write";
+  };
+  url: string;
+  redirect_url?: string;
+  setup_url?: string;
+}
+
+// ─── Interface ────────────────────────────────────────────────────────────────
+
+export interface GithubAppProvisioningClient {
+  /**
+   * Call POST app-manifests/{code}/conversions with the one-time code GitHub
+   * redirected back with after the manifest-based app creation flow.
+   * Unauthenticated per GitHub's docs. Returns the new app's ID, slug, and
+   * credentials — `webhook_secret` is discarded, never returned.
+   */
+  exchangeManifestCode(code: string): Promise<{
+    appId: string;
+    slug: string;
+    pem: string;
+    clientId: string;
+    clientSecret: string;
+  }>;
+}
+
+// ─── Agent manifest ───────────────────────────────────────────────────────────
+
+/**
+ * Builds the GitHub App manifest for a Shipwright agent.
+ *
+ * Used during the manifest-based app creation flow. `redirectUri` is where
+ * GitHub sends the user after app creation (manifest flow's `redirect_url`,
+ * distinct from the OAuth `callback_urls`). `setupUrl` is where the user
+ * lands after installing the app (`setup_url`). Both are omitted when not
+ * provided. `public` (default false) makes the App installable on other
+ * orgs besides the one that owns it.
+ *
+ * No `hook_attributes` is set — no webhook receiver exists in this codebase.
+ */
+export function buildAgentAppManifest(
+  appName: string,
+  opts?: { redirectUri?: string; setupUrl?: string; public?: boolean },
+): GithubAppManifest {
+  return {
+    name: appName,
+    public: opts?.public === true,
+    default_permissions: {
+      contents: "write",
+      pull_requests: "write",
+      actions: "read",
+      workflows: "write",
+    },
+    url: AGENT_APP_HOMEPAGE_URL,
+    ...(opts?.redirectUri !== undefined
+      ? { redirect_url: opts.redirectUri }
+      : {}),
+    ...(opts?.setupUrl !== undefined ? { setup_url: opts.setupUrl } : {}),
+  };
+}
+
+// ─── HTTP implementation ──────────────────────────────────────────────────────
+
+/**
+ * Production implementation — calls the real GitHub API.
+ *
+ * The constructor takes optional apiBase/fetchFn overrides for testability.
+ */
+export class HttpGithubAppProvisioningClient
+  implements GithubAppProvisioningClient
+{
+  private readonly apiBase: string;
+  private readonly fetchFn: typeof fetch;
+
+  constructor(opts?: { apiBase?: string; fetchFn?: typeof fetch }) {
+    this.apiBase = opts?.apiBase ?? "https://api.github.com";
+    this.fetchFn = opts?.fetchFn ?? fetch;
+  }
+
+  async exchangeManifestCode(code: string): Promise<{
+    appId: string;
+    slug: string;
+    pem: string;
+    clientId: string;
+    clientSecret: string;
+  }> {
+    const url = `${this.apiBase}/app-manifests/${code}/conversions`;
+
+    // Unauthenticated per GitHub's docs — no Authorization header.
+    const resp = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        Accept: "application/vnd.github+json",
+      },
+    });
+
+    if (!resp.ok) {
+      throw new Error(
+        `GitHub app-manifests conversion HTTP error: ${resp.status} ${resp.statusText}`,
+      );
+    }
+
+    const data = (await resp.json()) as {
+      id?: number;
+      slug?: string;
+      pem?: string;
+      client_id?: string;
+      client_secret?: string;
+      // Present in GitHub's real response but intentionally never read —
+      // no webhook receiver exists in this codebase, so webhook_secret must
+      // never be stored or returned.
+      webhook_secret?: string;
+    };
+    const { id, slug, pem, client_id, client_secret } = data;
+
+    if (id === undefined || !slug || !pem || !client_id || !client_secret) {
+      throw new Error(
+        "GitHub app-manifests conversion response missing one or more required fields (id, slug, pem, client_id, client_secret)",
+      );
+    }
+
+    return {
+      appId: String(id),
+      slug,
+      pem,
+      clientId: client_id,
+      clientSecret: client_secret,
+    };
+  }
+}

package/src/github-app-provisioning-client.unit.test.ts

@@ -0,0 +1,114 @@
+/**
+ * admin/src/github-app-provisioning-client.unit.test.ts
+ * Unit tests for buildAgentAppManifest. No I/O, no network — shape assertions only.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { buildAgentAppManifest } from "./github-app-provisioning-client.ts";
+
+const NAME = "test-agent";
+const REDIRECT = "https://shipwright.example.com/admin/provision/complete";
+const SETUP_URL = "https://shipwright.example.com/admin/provision/setup";
+
+describe("buildAgentAppManifest", () => {
+  describe("without redirectUri/setupUrl (unit)", () => {
+    const manifest = buildAgentAppManifest(NAME);
+
+    it("locks in exactly the four required permission scopes, no extras", () => {
+      expect(manifest.default_permissions).toEqual({
+        contents: "write",
+        pull_requests: "write",
+        actions: "read",
+        workflows: "write",
+      });
+      expect(Object.keys(manifest.default_permissions).sort()).toEqual(
+        ["actions", "contents", "pull_requests", "workflows"].sort(),
+      );
+    });
+
+    it("sets public: false", () => {
+      expect(manifest.public).toBe(false);
+    });
+
+    it("uses appName in the manifest name field", () => {
+      expect(manifest.name).toBe(NAME);
+    });
+
+    it("omits redirect_url when no redirectUri provided", () => {
+      expect(manifest.redirect_url).toBeUndefined();
+    });
+
+    it("omits setup_url when no setupUrl provided", () => {
+      expect(manifest.setup_url).toBeUndefined();
+    });
+
+    it("does not add hook_attributes (no webhook receiver exists)", () => {
+      expect(manifest).not.toHaveProperty("hook_attributes");
+    });
+
+    it("sets url to the agent app homepage URL", () => {
+      expect(manifest.url).toBe("https://shipwrightharness.com");
+    });
+  });
+
+  describe("public option", () => {
+    it("emits public: true only when the option is on", () => {
+      expect(buildAgentAppManifest(NAME, { public: true }).public).toBe(true);
+    });
+
+    it("emits public: false when the option is false or omitted", () => {
+      expect(buildAgentAppManifest(NAME, { public: false }).public).toBe(false);
+      expect(
+        buildAgentAppManifest(NAME, { redirectUri: REDIRECT }).public,
+      ).toBe(false);
+    });
+  });
+
+  describe("provisioning (with redirectUri and setupUrl)", () => {
+    const manifest = buildAgentAppManifest(NAME, {
+      redirectUri: REDIRECT,
+      setupUrl: SETUP_URL,
+    });
+
+    it("wires redirectUri into redirect_url", () => {
+      expect(manifest.redirect_url).toBe(REDIRECT);
+    });
+
+    it("wires setupUrl into setup_url", () => {
+      expect(manifest.setup_url).toBe(SETUP_URL);
+    });
+
+    it("still locks in exactly the four required permission scopes", () => {
+      expect(manifest.default_permissions).toEqual({
+        contents: "write",
+        pull_requests: "write",
+        actions: "read",
+        workflows: "write",
+      });
+    });
+
+    it("still sets public: false", () => {
+      expect(manifest.public).toBe(false);
+    });
+
+    it("sets url to the agent app homepage URL", () => {
+      expect(manifest.url).toBe("https://shipwrightharness.com");
+    });
+  });
+
+  describe("provisioning with only redirectUri", () => {
+    const manifest = buildAgentAppManifest(NAME, { redirectUri: REDIRECT });
+
+    it("sets redirect_url", () => {
+      expect(manifest.redirect_url).toBe(REDIRECT);
+    });
+
+    it("omits setup_url", () => {
+      expect(manifest.setup_url).toBeUndefined();
+    });
+
+    it("sets url to the agent app homepage URL", () => {
+      expect(manifest.url).toBe("https://shipwrightharness.com");
+    });
+  });
+});