@app-vitals/agent-admin 0.0.1 → 0.1.1

package/src/openapi-schemas.unit.test.ts

@@ -0,0 +1,348 @@
+/**
+ * admin/src/openapi-schemas.unit.test.ts
+ * Parse/reject tests for all Zod entity schemas in openapi-schemas.ts.
+ * Tests validate that good input parses cleanly and bad input produces typed errors.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { type AdminDeps, createAdminApp } from "./agents-api.ts";
+import { type AgentRuntimeDeps, createAgentRuntimeApp } from "./api.ts";
+import {
+  type AgentCronJob,
+  AgentCronJobSchema,
+  type AgentPlugin,
+  AgentPluginSchema,
+  type AgentToken,
+  AgentTokenSchema,
+  type AgentTool,
+  AgentToolSchema,
+  ErrorSchema,
+} from "./openapi-schemas.ts";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const now = new Date().toISOString();
+
+const validCronJob = {
+  id: "cuid2",
+  agentId: "cuid1",
+  schedule: "0 9 * * 1-5",
+  prompt: "Run the morning brief",
+  channel: "C01234567",
+  user: null,
+  silent: false,
+  enabled: true,
+  preCheck: null,
+  name: "morning-brief",
+  system: false,
+  parentCronId: null,
+  lockdownDisabledAt: null,
+  createdAt: now,
+  updatedAt: now,
+};
+
+const validTool = {
+  id: "cuid3",
+  agentId: "cuid1",
+  pattern: "Bash",
+  enabled: true,
+  createdAt: now,
+};
+
+const validToken = {
+  id: "cuid4",
+  agentId: "cuid1",
+  label: "ci-token",
+  createdAt: now,
+  revokedAt: null,
+};
+
+const validPlugin = {
+  id: "cuid5",
+  agentId: "cuid1",
+  name: "shipwright",
+  version: "1.0.0",
+  enabled: true,
+  createdAt: now,
+  updatedAt: now,
+};
+
+// ─── AgentCronJobSchema ───────────────────────────────────────────────────────
+
+describe("AgentCronJobSchema", () => {
+  test("parses valid cron job", () => {
+    const result = AgentCronJobSchema.safeParse(validCronJob);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const cron: AgentCronJob = result.data;
+      expect(cron.schedule).toBe("0 9 * * 1-5");
+      expect(cron.silent).toBe(false);
+      expect(cron.system).toBe(false);
+    }
+  });
+
+  test("parses cron job with user instead of channel", () => {
+    const userCron = { ...validCronJob, channel: null, user: "U01234567" };
+    const result = AgentCronJobSchema.safeParse(userCron);
+    expect(result.success).toBe(true);
+  });
+
+  test("parses cron job with all optional fields absent", () => {
+    const minimal = {
+      id: "cuid2",
+      agentId: "cuid1",
+      schedule: "0 9 * * *",
+      prompt: "Do something",
+      channel: null,
+      user: null,
+      silent: true,
+      enabled: true,
+      preCheck: null,
+      name: null,
+      system: false,
+      parentCronId: null,
+      lockdownDisabledAt: null,
+      createdAt: now,
+      updatedAt: now,
+    };
+    const result = AgentCronJobSchema.safeParse(minimal);
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects missing schedule", () => {
+    const { schedule: _, ...noSchedule } = validCronJob;
+    const result = AgentCronJobSchema.safeParse(noSchedule);
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects missing prompt", () => {
+    const { prompt: _, ...noPrompt } = validCronJob;
+    const result = AgentCronJobSchema.safeParse(noPrompt);
+    expect(result.success).toBe(false);
+  });
+
+  test("parses cron job with a non-null parentCronId string", () => {
+    const parented = { ...validCronJob, parentCronId: "cuid-parent" };
+    const result = AgentCronJobSchema.safeParse(parented);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.parentCronId).toBe("cuid-parent");
+    }
+  });
+
+  test("rejects missing parentCronId (required-but-nullable, matching channel/user/preCheck/name)", () => {
+    const { parentCronId: _, ...noParentCronId } = validCronJob;
+    const result = AgentCronJobSchema.safeParse(noParentCronId);
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─── AgentToolSchema ──────────────────────────────────────────────────────────
+
+describe("AgentToolSchema", () => {
+  test("parses valid tool", () => {
+    const result = AgentToolSchema.safeParse(validTool);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const tool: AgentTool = result.data;
+      expect(tool.pattern).toBe("Bash");
+      expect(tool.enabled).toBe(true);
+    }
+  });
+
+  test("rejects missing pattern", () => {
+    const { pattern: _, ...noPattern } = validTool;
+    const result = AgentToolSchema.safeParse(noPattern);
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects missing agentId", () => {
+    const { agentId: _, ...noAgentId } = validTool;
+    const result = AgentToolSchema.safeParse(noAgentId);
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects non-boolean enabled", () => {
+    const result = AgentToolSchema.safeParse({ ...validTool, enabled: "yes" });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─── AgentTokenSchema ─────────────────────────────────────────────────────────
+
+describe("AgentTokenSchema", () => {
+  test("parses valid token metadata", () => {
+    const result = AgentTokenSchema.safeParse(validToken);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const token: AgentToken = result.data;
+      expect(token.label).toBe("ci-token");
+      expect(token.revokedAt).toBeNull();
+    }
+  });
+
+  test("parses token without label", () => {
+    const { label: _, ...noLabel } = validToken;
+    const result = AgentTokenSchema.safeParse(noLabel);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.label).toBeUndefined();
+    }
+  });
+
+  test("parses token with null label", () => {
+    const result = AgentTokenSchema.safeParse({ ...validToken, label: null });
+    expect(result.success).toBe(true);
+  });
+
+  test("parses revoked token with revokedAt set", () => {
+    const revoked = { ...validToken, revokedAt: now };
+    const result = AgentTokenSchema.safeParse(revoked);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.revokedAt).toBe(now);
+    }
+  });
+
+  test("does not expose token hash", () => {
+    const withHash = { ...validToken, token: "sha256hash" };
+    const result = AgentTokenSchema.safeParse(withHash);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect((result.data as Record<string, unknown>).token).toBeUndefined();
+    }
+  });
+
+  test("rejects missing id", () => {
+    const { id: _, ...noId } = validToken;
+    const result = AgentTokenSchema.safeParse(noId);
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─── AgentPluginSchema ────────────────────────────────────────────────────────
+
+describe("AgentPluginSchema", () => {
+  test("parses valid plugin", () => {
+    const result = AgentPluginSchema.safeParse(validPlugin);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const plugin: AgentPlugin = result.data;
+      expect(plugin.name).toBe("shipwright");
+      expect(plugin.version).toBe("1.0.0");
+    }
+  });
+
+  test("parses plugin without version", () => {
+    const { version: _, ...noVersion } = validPlugin;
+    const result = AgentPluginSchema.safeParse(noVersion);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.version).toBeUndefined();
+    }
+  });
+
+  test("parses plugin with null version (latest)", () => {
+    const result = AgentPluginSchema.safeParse({
+      ...validPlugin,
+      version: null,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects missing name", () => {
+    const { name: _, ...noName } = validPlugin;
+    const result = AgentPluginSchema.safeParse(noName);
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects non-boolean enabled", () => {
+    const result = AgentPluginSchema.safeParse({ ...validPlugin, enabled: 1 });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─── ErrorSchema ─────────────────────────────────────────────────────────────
+
+describe("ErrorSchema", () => {
+  test("parses valid error response", () => {
+    const result = ErrorSchema.safeParse({ error: "Not found" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.error).toBe("Not found");
+    }
+  });
+
+  test("rejects missing error string", () => {
+    const result = ErrorSchema.safeParse({});
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─── OpenAPI route metadata (summary/description on every createRoute) ────────
+//
+// Builds both OpenAPIHono apps with minimal stub deps — same pattern as
+// scripts/generate-admin-spec.ts — and walks the generated spec's operations.
+// No handler is ever invoked (we never call app.request()), only route
+// registration + getOpenAPI31Document(), so the stub deps only need to satisfy
+// the type checker, not behave correctly. Hard-cast via `unknown` rather than
+// filling in every service method — this test asserts on route *metadata*,
+// not handler behavior (that's covered by the smoke tests).
+
+function collectUndocumentedOperations(
+  paths: unknown,
+  label: string,
+): string[] {
+  const issues: string[] = [];
+  const pathEntries = Object.entries(
+    (paths ?? {}) as Record<string, Record<string, unknown>>,
+  );
+  for (const [path, methods] of pathEntries) {
+    for (const [method, operation] of Object.entries(methods)) {
+      const op = operation as { summary?: unknown; description?: unknown };
+      const summary = typeof op.summary === "string" ? op.summary.trim() : "";
+      const description =
+        typeof op.description === "string" ? op.description.trim() : "";
+      if (!summary || !description) {
+        issues.push(`[${label}] ${method.toUpperCase()} ${path}`);
+      }
+    }
+  }
+  return issues;
+}
+
+describe("OpenAPI route metadata", () => {
+  test("every admin + runtime route has a non-empty summary and description", () => {
+    const runtimeApp = createAgentRuntimeApp({} as unknown as AgentRuntimeDeps);
+    const adminApp = createAdminApp({} as unknown as AdminDeps);
+
+    const runtimeDoc = runtimeApp.getOpenAPI31Document({
+      openapi: "3.1.0",
+      info: { title: "runtime (test)", version: "0.0.0" },
+    });
+    const adminDoc = adminApp.getOpenAPI31Document({
+      openapi: "3.1.0",
+      info: { title: "admin (test)", version: "0.0.0" },
+    });
+
+    const issues = [
+      ...collectUndocumentedOperations(adminDoc.paths, "admin"),
+      ...collectUndocumentedOperations(runtimeDoc.paths, "runtime"),
+    ];
+
+    const totalOperations = [adminDoc, runtimeDoc].reduce(
+      (sum, doc) =>
+        sum +
+        Object.values(
+          (doc.paths ?? {}) as Record<string, Record<string, unknown>>,
+        ).reduce((n, methods) => n + Object.keys(methods).length, 0),
+      0,
+    );
+    // Sanity check that this test is actually walking a non-trivial number of
+    // routes (brief cites ~38 createRoute calls across both files) — guards
+    // against the assertion silently checking zero operations.
+    expect(totalOperations).toBeGreaterThan(30);
+
+    expect(issues).toEqual([]);
+  });
+});

package/src/per-agent-identity.fixtures.ts

@@ -0,0 +1,305 @@
+/**
+ * admin/src/per-agent-identity.fixtures.ts
+ * Test support for per-agent identity provisioning (never imported by
+ * production code):
+ *
+ *   - FakeAnthropicIdentityClient: an in-memory AnthropicIdentityClient that
+ *     keeps service accounts and federation rules, enforces live-name
+ *     uniqueness (409 → AnthropicConflictError) like the Admin API, and can
+ *     fail any call once on demand.
+ *   - InMemoryAgentIdentityStore: the AgentAnthropicIdentityService get/set
+ *     contract plus the name allocator's allocate(), over a Map, with
+ *     injectable save failures.
+ *   - FaultyKubernetesClient: wraps a RecordedKubernetesClient so any method
+ *     can fail once, and logs every call.
+ *
+ * All three append to an optional shared `events` log so tests can assert the
+ * cross-system call order.
+ */
+
+import type {
+  AgentAnthropicIdentity,
+  AgentAnthropicIdentityUpdate,
+} from "./agent-anthropic-identity.ts";
+import {
+  type AddServiceAccountToWorkspaceInput,
+  AnthropicApiError,
+  AnthropicConflictError,
+  type AnthropicFederationRule,
+  type AnthropicIdentityClient,
+  type AnthropicServiceAccount,
+  type AnthropicWorkspaceMember,
+  type CreateFederationRuleInput,
+  type CreateServiceAccountInput,
+} from "./anthropic-identity-client.ts";
+import { identityBaseName, identityName } from "./anthropic-identity-name.ts";
+import { NotFoundError } from "./errors.ts";
+import type {
+  KubernetesClient,
+  RecordedKubernetesClient,
+} from "./kubernetes-client.ts";
+
+const ARCHIVED_AT = "2026-10-01T00:00:00Z";
+
+// ─── Anthropic identity client fake ───────────────────────────────────────────
+
+export type AnthropicIdentityOperation = keyof AnthropicIdentityClient;
+
+export interface FakeServiceAccount extends AnthropicServiceAccount {
+  workspaces: string[];
+}
+
+export interface FakeFederationRule extends AnthropicFederationRule {
+  input: CreateFederationRuleInput;
+}
+
+export class FakeAnthropicIdentityClient implements AnthropicIdentityClient {
+  readonly serviceAccounts = new Map<string, FakeServiceAccount>();
+  readonly rules = new Map<string, FakeFederationRule>();
+  readonly calls: Array<{ op: AnthropicIdentityOperation; arg: unknown }> = [];
+  private readonly failures = new Map<AnthropicIdentityOperation, Error>();
+  private nextId = 1;
+
+  constructor(private readonly events: string[] = []) {}
+
+  /** Make the next call to `op` throw (default: a 500 AnthropicApiError). */
+  failNext(op: AnthropicIdentityOperation, err?: Error): void {
+    this.failures.set(op, err ?? new AnthropicApiError(op, 500));
+  }
+
+  liveServiceAccounts(): FakeServiceAccount[] {
+    return [...this.serviceAccounts.values()].filter((s) => !s.archivedAt);
+  }
+
+  liveRules(): FakeFederationRule[] {
+    return [...this.rules.values()].filter((r) => !r.archivedAt);
+  }
+
+  callsTo(op: AnthropicIdentityOperation): unknown[] {
+    return this.calls.filter((c) => c.op === op).map((c) => c.arg);
+  }
+
+  /** Seed a live service account (e.g. one whose ID write was lost). */
+  seedServiceAccount(name: string): FakeServiceAccount {
+    const sa = { id: this.id("svac"), name, archivedAt: null, workspaces: [] };
+    this.serviceAccounts.set(sa.id, sa);
+    return sa;
+  }
+
+  /** Seed a live federation rule (e.g. one whose ID write was lost). */
+  seedRule(input: CreateFederationRuleInput): FakeFederationRule {
+    const rule = {
+      id: this.id("fdrl"),
+      name: input.name,
+      archivedAt: null,
+      input,
+    };
+    this.rules.set(rule.id, rule);
+    return rule;
+  }
+
+  async createServiceAccount(
+    input: CreateServiceAccountInput,
+  ): Promise<AnthropicServiceAccount> {
+    this.enter("createServiceAccount", input);
+    if (this.liveServiceAccounts().some((s) => s.name === input.name)) {
+      throw new AnthropicConflictError("createServiceAccount");
+    }
+    const { workspaces: _w, ...sa } = this.seedServiceAccount(input.name);
+    return sa;
+  }
+
+  async addServiceAccountToWorkspace(
+    input: AddServiceAccountToWorkspaceInput,
+  ): Promise<AnthropicWorkspaceMember> {
+    this.enter("addServiceAccountToWorkspace", input);
+    const sa = this.serviceAccounts.get(input.serviceAccountId);
+    if (!sa || sa.archivedAt) {
+      throw new AnthropicApiError("addServiceAccountToWorkspace", 404);
+    }
+    if (sa.workspaces.includes(input.workspaceId)) {
+      throw new AnthropicConflictError("addServiceAccountToWorkspace");
+    }
+    sa.workspaces.push(input.workspaceId);
+    return {
+      serviceAccountId: sa.id,
+      workspaceId: input.workspaceId,
+      workspaceRole: input.workspaceRole ?? "workspace_developer",
+    };
+  }
+
+  async createFederationRule(
+    input: CreateFederationRuleInput,
+  ): Promise<AnthropicFederationRule> {
+    this.enter("createFederationRule", input);
+    if (this.liveRules().some((r) => r.name === input.name)) {
+      throw new AnthropicConflictError("createFederationRule");
+    }
+    const { input: _i, ...rule } = this.seedRule(input);
+    return rule;
+  }
+
+  async archiveFederationRule(
+    ruleId: string,
+  ): Promise<AnthropicFederationRule> {
+    this.enter("archiveFederationRule", ruleId);
+    const rule = this.rules.get(ruleId);
+    if (!rule) throw new AnthropicApiError("archiveFederationRule", 404);
+    rule.archivedAt = ARCHIVED_AT;
+    return { id: rule.id, name: rule.name, archivedAt: rule.archivedAt };
+  }
+
+  async archiveServiceAccount(
+    serviceAccountId: string,
+  ): Promise<AnthropicServiceAccount> {
+    this.enter("archiveServiceAccount", serviceAccountId);
+    const sa = this.serviceAccounts.get(serviceAccountId);
+    if (!sa) throw new AnthropicApiError("archiveServiceAccount", 404);
+    sa.archivedAt = ARCHIVED_AT;
+    return { id: sa.id, name: sa.name, archivedAt: sa.archivedAt };
+  }
+
+  async findServiceAccountByName(
+    name: string,
+  ): Promise<AnthropicServiceAccount | null> {
+    this.enter("findServiceAccountByName", name);
+    const sa = this.liveServiceAccounts().find((s) => s.name === name);
+    return sa ? { id: sa.id, name: sa.name, archivedAt: null } : null;
+  }
+
+  async findFederationRuleByName(
+    name: string,
+  ): Promise<AnthropicFederationRule | null> {
+    this.enter("findFederationRuleByName", name);
+    const rule = this.liveRules().find((r) => r.name === name);
+    return rule ? { id: rule.id, name: rule.name, archivedAt: null } : null;
+  }
+
+  private id(prefix: string): string {
+    return `${prefix}_fake${this.nextId++}`;
+  }
+
+  private enter(op: AnthropicIdentityOperation, arg: unknown): void {
+    this.calls.push({ op, arg });
+    this.events.push(`anthropic.${op}`);
+    const err = this.failures.get(op);
+    if (err) {
+      this.failures.delete(op);
+      throw err;
+    }
+  }
+}
+
+// ─── Agent identity store fake ────────────────────────────────────────────────
+
+const EMPTY_IDENTITY: AgentAnthropicIdentity = {
+  ownerEmail: null,
+  anthropicIdentityName: null,
+  anthropicServiceAccountId: null,
+  anthropicFederationRuleId: null,
+  k8sServiceAccountName: null,
+};
+
+/**
+ * In-memory stand-in for AgentAnthropicIdentityService (get/set) and
+ * AnthropicIdentityNameAllocator (allocate). Names follow the real allocator's
+ * pure naming rules.
+ */
+export class InMemoryAgentIdentityStore {
+  readonly rows = new Map<string, AgentAnthropicIdentity>();
+  private readonly setFailures = new Map<keyof AgentAnthropicIdentity, Error>();
+
+  constructor(
+    private readonly events: string[] = [],
+    private readonly suffix?: string,
+  ) {}
+
+  addAgent(
+    agentId: string,
+    identity: Partial<AgentAnthropicIdentity> = {},
+  ): void {
+    this.rows.set(agentId, { ...EMPTY_IDENTITY, ...identity });
+  }
+
+  /** Make the next set() that writes `field` throw. */
+  failNextSetOf(field: keyof AgentAnthropicIdentity, err?: Error): void {
+    this.setFailures.set(field, err ?? new Error(`lost write of ${field}`));
+  }
+
+  async get(agentId: string): Promise<AgentAnthropicIdentity | null> {
+    const row = this.rows.get(agentId);
+    return row ? { ...row } : null;
+  }
+
+  async set(
+    agentId: string,
+    update: AgentAnthropicIdentityUpdate,
+  ): Promise<AgentAnthropicIdentity> {
+    const fields = (
+      Object.keys(update) as (keyof AgentAnthropicIdentity)[]
+    ).filter((k) => update[k] !== undefined);
+    this.events.push(`store.set(${fields.join(",")})`);
+    for (const field of fields) {
+      const err = this.setFailures.get(field);
+      if (err) {
+        this.setFailures.delete(field);
+        throw err;
+      }
+    }
+    const row = this.rows.get(agentId);
+    if (!row) throw new NotFoundError(`Agent ${agentId} not found`);
+    for (const field of fields) row[field] = update[field] ?? null;
+    return { ...row };
+  }
+
+  async allocate(agentId: string, ownerEmail: string): Promise<string> {
+    this.events.push("store.allocate");
+    const row = this.rows.get(agentId);
+    if (!row) throw new NotFoundError(`Agent ${agentId} not found`);
+    if (row.anthropicIdentityName) return row.anthropicIdentityName;
+    const base = identityBaseName(ownerEmail, this.suffix);
+    let n = 1;
+    const taken = new Set(
+      [...this.rows.values()].map((r) => r.anthropicIdentityName),
+    );
+    while (taken.has(identityName(base, n, this.suffix))) n++;
+    row.anthropicIdentityName = identityName(base, n, this.suffix);
+    return row.anthropicIdentityName;
+  }
+}
+
+// ─── Kubernetes client wrapper ────────────────────────────────────────────────
+
+/**
+ * A KubernetesClient that forwards to a RecordedKubernetesClient, logs each
+ * call as `k8s.<method>` and can fail any method once.
+ */
+export function faultyKubernetesClient(
+  inner: RecordedKubernetesClient,
+  events: string[] = [],
+): KubernetesClient & {
+  failNext(method: keyof KubernetesClient, err?: Error): void;
+} {
+  const failures = new Map<string, Error>();
+  const failNext = (method: keyof KubernetesClient, err?: Error) => {
+    failures.set(method, err ?? new Error(`k8s ${method} failed`));
+  };
+  return new Proxy(inner, {
+    get(target, prop, receiver) {
+      if (prop === "failNext") return failNext;
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== "function") return value;
+      return async (...args: unknown[]) => {
+        events.push(`k8s.${String(prop)}`);
+        const err = failures.get(String(prop));
+        if (err) {
+          failures.delete(String(prop));
+          throw err;
+        }
+        return value.apply(target, args);
+      };
+    },
+  }) as unknown as KubernetesClient & {
+    failNext(method: keyof KubernetesClient, err?: Error): void;
+  };
+}

package/src/platform-doc-route.ts

@@ -0,0 +1,40 @@
+/**
+ * admin/src/platform-doc-route.ts
+ * Optional GET /doc route serving the platform OpenAPI 3.1 document.
+ *
+ * Mounted only when SHIPWRIGHT_ADMIN_DOC_ENABLED === "enabled"; otherwise the
+ * route is absent (Hono 404, identical to a build without this module). It
+ * serves buildPlatformAdminSpec() only — never extension (coding) paths — so
+ * the body matches the committed admin/openapi.platform.json byte-for-byte.
+ */
+
+import type { Hono, MiddlewareHandler } from "hono";
+import { buildPlatformAdminSpec } from "./admin-spec.ts";
+
+export const DOC_ENABLED_ENV = "SHIPWRIGHT_ADMIN_DOC_ENABLED";
+
+export function isPlatformDocEnabled(
+  env: Record<string, string | undefined>,
+): boolean {
+  return env[DOC_ENABLED_ENV] === "enabled";
+}
+
+/** Mounts GET /doc behind `auth` when the flag is on; a no-op otherwise. */
+export function mountPlatformDoc(
+  // biome-ignore lint/suspicious/noExplicitAny: the root app carries arbitrary Env generics
+  root: Hono<any>,
+  deps: {
+    env: Record<string, string | undefined>;
+    auth: MiddlewareHandler;
+  },
+): void {
+  if (!isPlatformDocEnabled(deps.env)) return;
+  // Same serialization as the committed spec file (2-space JSON + newline).
+  const body = `${JSON.stringify(buildPlatformAdminSpec(), null, 2)}\n`;
+  root.get("/doc", deps.auth, (c) =>
+    c.body(body, 200, {
+      "Content-Type": "application/json; charset=UTF-8",
+      "Cache-Control": "no-store",
+    }),
+  );
+}