@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/admin-spec.smoke.test.ts

@@ -0,0 +1,96 @@
+/**
+ * admin/src/admin-spec.smoke.test.ts
+ *
+ * Smoke tests for the platform OpenAPI document served at GET /doc.
+ * The route is flag-gated: SHIPWRIGHT_ADMIN_DOC_ENABLED="enabled" mounts it
+ * (see platform-doc-route.ts, wired in admin-boot.ts) behind the admin auth
+ * middleware; with the flag off the route is not mounted at all (404).
+ * Uses app.request() — no real server, no real DB.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { Hono } from "hono";
+import { buildPlatformAdminSpec } from "./admin-spec.ts";
+import { createAdminAuthMiddleware, parseAdminApiKeys } from "./api-auth.ts";
+import { mountPlatformDoc } from "./platform-doc-route.ts";
+
+function buildApp(env: Record<string, string | undefined>) {
+  const root = new Hono();
+  root.get("/health", (c) => c.json({ status: "ok" }));
+  mountPlatformDoc(root, {
+    env,
+    auth: createAdminAuthMiddleware({
+      sessionSecret: "test-secret-32chars-for-doc-route!",
+      agentTokenService: { validate: async () => null },
+      adminApiKeys: parseAdminApiKeys(
+        "root:tok-admin:*,ro:tok-read:platform.read,ops:tok-ops:platform.ops,bot:tok-agent:agent-1",
+      ),
+    }),
+  });
+  return root;
+}
+
+// The auth middleware and the handler both register under /doc; dedupe.
+const routes = (app: Hono) => [
+  ...new Set(app.routes.map((r) => `${r.method} ${r.path}`)),
+];
+const bearer = (t: string) => ({ headers: { Authorization: `Bearer ${t}` } });
+
+describe("GET /doc", () => {
+  it("flag off: route is not mounted and returns 404", async () => {
+    const off = buildApp({});
+    expect((await off.request("/doc")).status).toBe(404);
+    expect((await off.request("/doc", bearer("tok-admin"))).status).toBe(404);
+    expect(routes(off)).toEqual(
+      routes(buildApp({ SHIPWRIGHT_ADMIN_DOC_ENABLED: "disabled" })),
+    );
+    expect(routes(off).some((r) => r.endsWith("/doc"))).toBe(false);
+  });
+
+  it("flag on adds exactly one route", () => {
+    const on = routes(buildApp({ SHIPWRIGHT_ADMIN_DOC_ENABLED: "enabled" }));
+    expect(on.filter((r) => !routes(buildApp({})).includes(r))).toEqual([
+      "GET /doc",
+    ]);
+  });
+
+  it("flag on: no credential -> 401", async () => {
+    const app = buildApp({ SHIPWRIGHT_ADMIN_DOC_ENABLED: "enabled" });
+    expect((await app.request("/doc")).status).toBe(401);
+    expect((await app.request("/doc", bearer("nope"))).status).toBe(401);
+  });
+
+  it("flag on: platform.read serves the platform spec byte-for-byte", async () => {
+    const app = buildApp({ SHIPWRIGHT_ADMIN_DOC_ENABLED: "enabled" });
+    const res = await app.request("/doc", bearer("tok-read"));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Cache-Control")).toBe("no-store");
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+    const text = await res.text();
+    expect(text).toBe(`${JSON.stringify(buildPlatformAdminSpec(), null, 2)}\n`);
+    const doc = JSON.parse(text) as {
+      openapi: string;
+      paths: Record<string, unknown>;
+    };
+    expect(doc.openapi.startsWith("3.1")).toBe(true);
+    expect(Object.keys(doc.paths).some((p) => p.startsWith("/coding"))).toBe(
+      false,
+    );
+  });
+
+  it("flag on: *, platform.ops and agent keys succeed", async () => {
+    const app = buildApp({ SHIPWRIGHT_ADMIN_DOC_ENABLED: "enabled" });
+    for (const t of ["tok-admin", "tok-ops", "tok-agent"]) {
+      expect((await app.request("/doc", bearer(t))).status).toBe(200);
+    }
+  });
+
+  it("matches the committed platform spec file", async () => {
+    const app = buildApp({ SHIPWRIGHT_ADMIN_DOC_ENABLED: "enabled" });
+    const res = await app.request("/doc", bearer("tok-read"));
+    const committed = await Bun.file(
+      new URL("../openapi.platform.json", import.meta.url),
+    ).text();
+    expect(await res.text()).toBe(committed);
+  });
+});

package/src/admin-spec.ts

@@ -0,0 +1,186 @@
+/**
+ * admin/src/admin-spec.ts
+ * Builds the platform-only OpenAPI 3.1 document of the admin service.
+ *
+ * Instantiates the admin CRUD app and the agent runtime app in-process with
+ * minimal stubs (no real DB, no real services — only route definitions matter),
+ * then:
+ *   1. Calls getOpenAPI31Document() on each sub-app independently.
+ *   2. Rewrites the runtime app's Hono-style path params (`:id`) to OpenAPI
+ *      style (`{id}`) and prefixes them with `/agents`.
+ *   3. Merges both specs' paths and component schemas into a single document.
+ *
+ * The result is committed as admin/openapi.platform.json and feeds the
+ * platform half of the generated admin types (lib/admin-types.ts). Consumers
+ * that compose admin extensions fold the extensions' OpenAPI contributions in
+ * on top (applyOpenApiContributions) — Shipwright does so in
+ * scripts/generate-admin-spec.ts to produce the composed admin/openapi.json.
+ */
+
+import { NoopAgentProvisioner } from "./agent-provisioner.ts";
+import {
+  type AdminDeps,
+  createAdminApp,
+  parseAdminApiKeys,
+} from "./agents-api.ts";
+import { createAgentRuntimeApp } from "./api.ts";
+
+/** The admin OpenAPI document shape the spec builders and generators share. */
+export interface AdminOpenApiDocument {
+  openapi: string;
+  info: { title: string; version: string; description?: string };
+  paths: Record<string, Record<string, unknown>>;
+  components?: { schemas?: Record<string, unknown>; [key: string]: unknown };
+  [key: string]: unknown;
+}
+
+/** Builds the platform-only admin OpenAPI document (no extension routes). */
+export function buildPlatformAdminSpec(): AdminOpenApiDocument {
+  // Stub deps — only route definitions matter for spec generation.
+  const SESSION_SECRET = "dummy-secret-32chars-for-spec-gen";
+  const adminApiKeys = parseAdminApiKeys("codegen:codegen-key:*");
+
+  const runtimeApp = createAgentRuntimeApp({
+    agentEnvService: {
+      async getConfigBundle() {
+        return null;
+      },
+    },
+    agentCronJobService: {
+      async list() {
+        return [];
+      },
+    },
+    agentService: {
+      async getById() {
+        return null;
+      },
+    },
+    agentPluginService: {
+      async listEnabled() {
+        return [];
+      },
+    },
+    adminApiKeys,
+    agentTokenService: { validate: async () => null },
+    sessionSecret: SESSION_SECRET,
+  });
+
+  const adminApp = createAdminApp({
+    agentEnvService: {
+      upsert: async () => {},
+      patch: async () => {},
+      getByAgentId: async () => null,
+      deleteKey: async () => {},
+    },
+    agentCronJobService: {
+      list: async () => [],
+      listWithRunSummary: async () => [],
+      create: async () => ({}) as never,
+      update: async () => ({}) as never,
+      delete: async () => {},
+      get: async () => ({}) as never,
+      setEnabled: async () => ({}) as never,
+      updatePreCheck: async () => ({}) as never,
+      reconcileSystemCrons: async () => ({
+        created: 0,
+        updated: 0,
+        deleted: 0,
+      }),
+    },
+    agentToolService: {
+      list: async () => [],
+      add: async () => ({}) as never,
+      remove: async () => {},
+      toggle: async () => ({}) as never,
+    },
+    agentTokenService: {
+      create: async () => ({}) as never,
+      listForAgent: async () => [],
+      revoke: async () => ({}) as never,
+      validate: async () => null,
+    },
+    agentPluginService: {
+      list: async () => [],
+      add: async () => ({}) as never,
+      remove: async () => {},
+      removeByName: async () => {},
+    },
+    prisma: {
+      agent: {
+        create: async () => ({}) as never,
+        findUnique: async () => null,
+        findMany: async () => [],
+        delete: async () => ({}) as never,
+      },
+    } as never,
+    provisioner: new NoopAgentProvisioner(),
+    sessionSecret: SESSION_SECRET,
+    adminApiKeys,
+    // Partial on purpose: route registration never calls the services, so only
+    // the deps a factory reads at construction time are stubbed.
+  } as unknown as AdminDeps);
+
+  const docInfo = {
+    openapi: "3.1.0" as const,
+    info: {
+      title: "Shipwright Admin API",
+      version: "0.1.0",
+      description:
+        "REST API for the Shipwright admin service — CRUD for agents, env vars, cron jobs, tokens, tools, and plugins, plus the agent runtime polling endpoints.",
+    },
+    servers: [{ url: "http://localhost:3457", description: "Local dev" }],
+  };
+
+  // Admin app spec (uses OpenAPI {id} path notation)
+  const adminSpec = adminApp.getOpenAPI31Document(docInfo);
+
+  // Runtime app spec (uses Hono :id notation — paths are relative to sub-app root)
+  const runtimeSpec = runtimeApp.getOpenAPI31Document({
+    openapi: "3.1.0",
+    info: { title: "runtime (internal)", version: "0.1.0" },
+  });
+
+  // The runtime app's routes are defined as `/:id/config` and `/:id/crons`.
+  // When the spec is generated standalone, these appear as `/:id/config` etc.
+  // We rewrite Hono colon params to OpenAPI curly brace params, then prefix
+  // with `/agents` to match the root-mounted path.
+
+  // Build runtime paths with OpenAPI notation and /agents prefix.
+  // Merge at the method level so paths shared between admin and runtime
+  // (e.g. /agents/{id}/crons has both POST from admin and GET from runtime)
+  // keep all their HTTP methods.
+  const adminPaths = (adminSpec.paths ?? {}) as Record<
+    string,
+    Record<string, unknown>
+  >;
+  const mergedPaths: Record<string, Record<string, unknown>> = {
+    ...adminPaths,
+  };
+
+  for (const [path, def] of Object.entries(runtimeSpec.paths ?? {})) {
+    const openApiPath = `/agents${path.replace(/:(\w+)/g, "{$1}")}`;
+    if (mergedPaths[openApiPath]) {
+      // Merge methods — runtime GET on /agents/{id}/crons must coexist with
+      // admin POST on the same path.
+      mergedPaths[openApiPath] = {
+        ...mergedPaths[openApiPath],
+        ...(def as Record<string, unknown>),
+      };
+    } else {
+      mergedPaths[openApiPath] = def as Record<string, unknown>;
+    }
+  }
+
+  return {
+    ...adminSpec,
+    paths: mergedPaths,
+    components: {
+      ...(adminSpec.components ?? {}),
+      schemas: {
+        ...(adminSpec.components?.schemas ?? {}),
+        ...(runtimeSpec.components?.schemas ?? {}),
+      },
+    },
+  };
+}

package/src/admin-ui-account-nav.ts

@@ -0,0 +1,20 @@
+/**
+ * admin/src/admin-ui-account-nav.ts
+ * Per-request "show the Account nav entry" flag (SSP-3.2). renderAdminToolbar()
+ * is called from dozens of page renderers; rather than thread a parameter
+ * through all of them, an admin-ui middleware wraps each /admin/* request in
+ * runWithAccountNav() and the toolbar reads the flag back. Outside any
+ * context (tests, other services) the entry is hidden.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const storage = new AsyncLocalStorage<{ showAccount: boolean }>();
+
+export function runWithAccountNav<T>(showAccount: boolean, fn: () => T): T {
+  return storage.run({ showAccount }, fn);
+}
+
+export function shouldShowAccountNav(): boolean {
+  return storage.getStore()?.showAccount === true;
+}

package/src/admin-ui-account-pages.ts

@@ -0,0 +1,131 @@
+/**
+ * admin/src/admin-ui-account-pages.ts
+ * Render functions for the self-serve account page and the zero-quota notice
+ * (SSP-3.2). Pure string -> string; routes live in admin-ui-account.ts.
+ */
+
+import type { AccountInvite } from "./account-invites.ts";
+import type { AccountMember } from "./account-members.ts";
+import type { Account } from "./accounts.ts";
+import { renderAdminPage } from "./admin-ui-layout.ts";
+import { escapeHtml, renderAdminToolbar } from "./admin-ui-styles.ts";
+
+export const ACCOUNT_PATH = "/admin/account";
+
+interface AccountPageOpts {
+  userEmail: string;
+  account: Account;
+  agentCount: number;
+  members: AccountMember[];
+  invites: AccountInvite[];
+  /** True when the viewer is an owner; members get a read-only page. */
+  isOwner: boolean;
+  error?: string;
+}
+
+function emailForm(
+  action: string,
+  email: string,
+  label: string,
+  danger = false,
+): string {
+  return `<form method="POST" action="${ACCOUNT_PATH}/${action}" style="display:inline;margin:0">
+    <input type="hidden" name="email" value="${escapeHtml(email)}" />
+    <button type="submit" class="btn ${danger ? "btn-danger" : "btn-secondary"}" style="font-size:12px;padding:4px 10px">${label}</button>
+  </form>`;
+}
+
+function renderMemberRow(m: AccountMember, isOwner: boolean): string {
+  const actions = isOwner
+    ? [
+        m.role === "owner"
+          ? emailForm("members/demote", m.email, "Demote")
+          : emailForm("members/promote", m.email, "Make owner"),
+        emailForm("members/remove", m.email, "Remove", true),
+      ].join(" ")
+    : "";
+  return `<tr>
+    <td>${escapeHtml(m.email)}</td>
+    <td><span class="badge ${m.role === "owner" ? "badge-purple" : "badge-gray"}">${escapeHtml(m.role)}</span></td>
+    ${isOwner ? `<td style="text-align:right">${actions}</td>` : ""}
+  </tr>`;
+}
+
+function renderInviteRow(i: AccountInvite, isOwner: boolean): string {
+  return `<tr>
+    <td>${escapeHtml(i.email)}</td>
+    <td>${escapeHtml(i.invitedBy)}</td>
+    ${isOwner ? `<td style="text-align:right">${emailForm("invites/revoke", i.email, "Revoke", true)}</td>` : ""}
+  </tr>`;
+}
+
+export function renderAccountPage(opts: AccountPageOpts): string {
+  const { account, isOwner } = opts;
+  const errorHtml = opts.error
+    ? `<div class="alert alert-error">${escapeHtml(opts.error)}</div>`
+    : "";
+  const actionTh = isOwner ? "<th></th>" : "";
+
+  const memberRows = opts.members
+    .map((m) => renderMemberRow(m, isOwner))
+    .join("\n");
+  const inviteRows =
+    opts.invites.length === 0
+      ? `<tr><td colspan="${isOwner ? 3 : 2}" class="empty-state">No pending invites.</td></tr>`
+      : opts.invites.map((i) => renderInviteRow(i, isOwner)).join("\n");
+
+  const renameForm = isOwner
+    ? `<form method="POST" action="${ACCOUNT_PATH}/rename" style="display:flex;gap:8px;margin-top:12px">
+        <input name="name" class="form-input" maxlength="100" required value="${escapeHtml(account.name)}" style="max-width:280px" />
+        <button type="submit" class="btn btn-secondary">Rename</button>
+      </form>`
+    : "";
+  const inviteForm = isOwner
+    ? `<form method="POST" action="${ACCOUNT_PATH}/invite" style="display:flex;gap:8px;margin-top:12px">
+        <input name="email" type="email" class="form-input" required placeholder="teammate@example.com" style="max-width:280px" />
+        <button type="submit" class="btn btn-primary">Invite</button>
+      </form>`
+    : "";
+
+  return renderAdminPage({
+    title: "Account — Shipwright Admin",
+    body: `${renderAdminToolbar(opts.userEmail, ACCOUNT_PATH)}
+  <div class="vos-page">
+    <div class="page-header">
+      <h1 class="page-title">${escapeHtml(account.name)}</h1>
+    </div>
+    ${errorHtml}
+    <div class="card">
+      <div class="card-title">Account</div>
+      <p>Agents: <strong>${opts.agentCount} / ${account.maxAgents}</strong></p>
+      ${renameForm}
+    </div>
+    <div class="card">
+      <div class="card-title">Members</div>
+      <div class="data-table-wrapper">
+        <table class="data-table">
+          <thead><tr><th>Email</th><th>Role</th>${actionTh}</tr></thead>
+          <tbody>${memberRows}</tbody>
+        </table>
+      </div>
+    </div>
+    <div class="card">
+      <div class="card-title">Pending invites</div>
+      <div class="data-table-wrapper">
+        <table class="data-table">
+          <thead><tr><th>Email</th><th>Invited by</th>${actionTh}</tr></thead>
+          <tbody>${inviteRows}</tbody>
+        </table>
+      </div>
+      ${inviteForm}
+    </div>
+  </div>`,
+  });
+}
+
+/** Shown on /admin/agents in place of the create button when maxAgents = 0. */
+export function renderZeroQuotaNotice(contactEmail: string): string {
+  const email = escapeHtml(contactEmail);
+  return `<div class="alert alert-warning" id="zero-quota-notice">Email ${email} to request a trial</div>
+    <button type="button" class="btn btn-primary" disabled aria-disabled="true">+ New agent</button>`;
+}

package/src/admin-ui-account-pages.unit.test.ts

@@ -0,0 +1,112 @@
+/**
+ * admin/src/admin-ui-account-pages.unit.test.ts
+ * Pure render tests for the account page fragments (SSP-3.2).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  renderAccountPage,
+  renderZeroQuotaNotice,
+} from "./admin-ui-account-pages.ts";
+import { renderAdminToolbar } from "./admin-ui-styles.ts";
+import { runWithAccountNav } from "./admin-ui-account-nav.ts";
+
+const d = new Date("2026-01-01T00:00:00Z");
+const account = {
+  id: "a1",
+  name: "Acme <Co>",
+  status: "active",
+  maxAgents: 3,
+  plan: null,
+  trialExpiresAt: null,
+  trialExpiryWarnedAt: null,
+  createdAt: d,
+  updatedAt: d,
+};
+const members = [
+  { id: "m1", accountId: "a1", email: "o@x.com", role: "owner", createdAt: d },
+  { id: "m2", accountId: "a1", email: "m@x.com", role: "member", createdAt: d },
+];
+const invites = [
+  {
+    id: "i1",
+    accountId: "a1",
+    email: "new@x.com",
+    invitedBy: "o@x.com",
+    acceptedAt: null,
+    createdAt: d,
+  },
+];
+
+function render(isOwner: boolean, error?: string) {
+  return renderAccountPage({
+    userEmail: isOwner ? "o@x.com" : "m@x.com",
+    // biome-ignore lint/suspicious/noExplicitAny: partial fixture
+    account: account as any,
+    agentCount: 2,
+    // biome-ignore lint/suspicious/noExplicitAny: partial fixture
+    members: members as any,
+    // biome-ignore lint/suspicious/noExplicitAny: partial fixture
+    invites: invites as any,
+    isOwner,
+    error,
+  });
+}
+
+describe("renderAccountPage", () => {
+  test("shows escaped name, quota used/max, members and pending invites", () => {
+    const html = render(true);
+    expect(html).toContain("Acme &lt;Co&gt;");
+    expect(html).not.toContain("Acme <Co>");
+    expect(html).toContain("2 / 3");
+    expect(html).toContain("o@x.com");
+    expect(html).toContain("new@x.com");
+  });
+
+  test("owner sees management forms", () => {
+    const html = render(true);
+    expect(html).toContain('action="/admin/account/invite"');
+    expect(html).toContain('action="/admin/account/invites/revoke"');
+    expect(html).toContain('action="/admin/account/members/remove"');
+    expect(html).toContain('action="/admin/account/members/promote"');
+    expect(html).toContain('action="/admin/account/members/demote"');
+    expect(html).toContain('action="/admin/account/rename"');
+  });
+
+  test("member sees read-only page", () => {
+    const html = render(false);
+    expect(html).not.toContain('action="/admin/account/');
+    expect(html).toContain("m@x.com");
+  });
+
+  test("renders an escaped error", () => {
+    expect(render(true, "bad <b>")).toContain("bad &lt;b&gt;");
+  });
+});
+
+describe("renderZeroQuotaNotice", () => {
+  test("shows request-a-trial message with escaped contact address", () => {
+    const html = renderZeroQuotaNotice("dan@app-vitals.com");
+    expect(html).toContain("Email dan@app-vitals.com to request a trial");
+  });
+});
+
+describe("renderAdminToolbar account nav", () => {
+  test("no Account entry outside the account-nav context", () => {
+    expect(renderAdminToolbar("u", "/admin/agents")).not.toContain(
+      "/admin/account",
+    );
+  });
+  test("Account entry inside the context", () => {
+    const html = runWithAccountNav(true, () =>
+      renderAdminToolbar("u", "/admin/agents"),
+    );
+    expect(html).toContain('href="/admin/account"');
+  });
+  test("no entry when context says false", () => {
+    const html = runWithAccountNav(false, () =>
+      renderAdminToolbar("u", "/admin/agents"),
+    );
+    expect(html).not.toContain("/admin/account");
+  });
+});