@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/admin-ui-accounts.ts

@@ -0,0 +1,266 @@
+/**
+ * admin/src/admin-ui-accounts.ts
+ * GET/POST /admin/accounts[/:id] — platform-admin account management
+ * (SSP-5.2). Admin only (403 otherwise) and flag-gated (404 when self-serve
+ * is off). Status and trial edits go through AccountLifecycle (SSP-8.2), so
+ * suspend locks down the account's crons and reactivate restores them.
+ */
+
+import type { Context, Hono, MiddlewareHandler } from "hono";
+import { normalizeEmail } from "./account-email.ts";
+import type { AccountInviteService } from "./account-invites.ts";
+import type { AccountLifecycle } from "./account-lifecycle.ts";
+import {
+  AccountMemberNotFoundError,
+  type AccountMemberService,
+  LastOwnerError,
+} from "./account-members.ts";
+import type { AccountService } from "./accounts.ts";
+import type { AdminUIEnv } from "./admin-ui.ts";
+import {
+  type AccountAgentRef,
+  ADMIN_ACCOUNTS_PATH,
+  renderAccountDetailPage,
+  renderAccountsListPage,
+} from "./admin-ui-accounts-pages.ts";
+import { reconcileAgentAfterAccountChange } from "./agent-account-assignment.ts";
+import type { AgentProvisioner } from "./agent-provisioner.ts";
+import type { AgentService } from "./agents.ts";
+import { UnprocessableEntityError } from "./errors.ts";
+
+export interface AdminAccountsRouteDeps {
+  /** SHIPWRIGHT_SELF_SERVE_ENABLED === "enabled". */
+  enabled: boolean;
+  requireAuth: MiddlewareHandler<AdminUIEnv>;
+  accounts: Pick<
+    AccountService,
+    "listWithCounts" | "getWithCounts" | "listAgents"
+  >;
+  /** SSP-8.2: account edits + status transitions (cron lockdown/restore). */
+  lifecycle: Pick<AccountLifecycle, "update">;
+  members: Pick<
+    AccountMemberService,
+    "listByAccount" | "getByEmail" | "add" | "remove" | "promote" | "demote"
+  >;
+  invites: Pick<AccountInviteService, "listPending">;
+  /** SSP-5.3: assign/unassign agents (admin only). */
+  agents: Pick<AgentService, "getDetail" | "updateFields">;
+  provisioner: Pick<AgentProvisioner, "reconcile">;
+  html: (content: string, opts?: { status?: number }) => Response;
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const MAX_NAME_LENGTH = 100;
+
+export function registerAdminAccountsRoutes(
+  app: Hono<AdminUIEnv>,
+  deps: AdminAccountsRouteDeps,
+): void {
+  const notFound = () => new Response("Not Found", { status: 404 });
+  const forbidden = () => new Response("Forbidden", { status: 403 });
+
+  app.use(ADMIN_ACCOUNTS_PATH, async (_c, next) =>
+    deps.enabled ? next() : notFound(),
+  );
+  app.use(`${ADMIN_ACCOUNTS_PATH}/*`, async (_c, next) =>
+    deps.enabled ? next() : notFound(),
+  );
+
+  const requireAdmin: MiddlewareHandler<AdminUIEnv> = async (c, next) =>
+    c.var.isAdmin === true ? next() : forbidden();
+
+  app.get(ADMIN_ACCOUNTS_PATH, deps.requireAuth, requireAdmin, async (c) => {
+    const accounts = await deps.accounts.listWithCounts();
+    const owners = new Map<string, string[]>();
+    await Promise.all(
+      accounts.map(async (a) => {
+        const members = await deps.members.listByAccount(a.id);
+        owners.set(
+          a.id,
+          members.filter((m) => m.role === "owner").map((m) => m.email),
+        );
+      }),
+    );
+    return deps.html(
+      renderAccountsListPage({ userEmail: c.var.userEmail, accounts, owners }),
+    );
+  });
+
+  async function renderDetail(
+    c: Context<AdminUIEnv>,
+    id: string,
+    error?: string,
+    status = 200,
+  ): Promise<Response> {
+    const account = await deps.accounts.getWithCounts(id);
+    if (!account) return notFound();
+    const [agents, members, invites] = await Promise.all([
+      deps.accounts.listAgents(id),
+      deps.members.listByAccount(id),
+      deps.invites.listPending(id),
+    ]);
+    return deps.html(
+      renderAccountDetailPage({
+        userEmail: c.var.userEmail,
+        account,
+        agents: agents as AccountAgentRef[],
+        members,
+        invites,
+        error,
+      }),
+      { status },
+    );
+  }
+
+  app.get(`${ADMIN_ACCOUNTS_PATH}/:id`, deps.requireAuth, requireAdmin, (c) =>
+    renderDetail(c, c.req.param("id")),
+  );
+
+  /**
+   * Admin POST action: 404 for unknown account, runs `run` with the form,
+   * 302 back to the detail page on success, re-renders with the error on a
+   * known failure.
+   */
+  function action(
+    path: string,
+    run: (args: { id: string; form: FormData }) => Promise<string | undefined>,
+  ): void {
+    app.post(
+      `${ADMIN_ACCOUNTS_PATH}/:id/${path}`,
+      deps.requireAuth,
+      requireAdmin,
+      async (c) => {
+        const id = c.req.param("id");
+        if (!(await deps.accounts.getWithCounts(id))) return notFound();
+        let form = new FormData();
+        try {
+          form = await c.req.formData();
+        } catch {
+          // malformed body — treated as empty fields below
+        }
+        try {
+          const error = await run({ id, form });
+          if (error) return renderDetail(c, id, error, 400);
+        } catch (err) {
+          if (err instanceof LastOwnerError) {
+            return renderDetail(
+              c,
+              id,
+              "Cannot remove or demote the last owner of the account.",
+              400,
+            );
+          }
+          if (err instanceof AccountMemberNotFoundError) {
+            return renderDetail(c, id, "Member not found.", 404);
+          }
+          throw err;
+        }
+        return c.redirect(`${ADMIN_ACCOUNTS_PATH}/${id}`, 302);
+      },
+    );
+  }
+
+  const field = (form: FormData, name: string) =>
+    (form.get(name)?.toString() ?? "").trim();
+
+  action("update", async ({ id, form }) => {
+    const name = field(form, "name");
+    if (!name) return "Account name is required.";
+    if (name.length > MAX_NAME_LENGTH) {
+      return `Account name must be at most ${MAX_NAME_LENGTH} characters.`;
+    }
+    const maxRaw = field(form, "maxAgents");
+    const maxAgents = Number(maxRaw);
+    if (maxRaw === "" || !Number.isInteger(maxAgents) || maxAgents < 0) {
+      return "Max agents must be a non-negative integer.";
+    }
+    const trialRaw = field(form, "trialExpiresAt");
+    let trialExpiresAt: Date | null = null;
+    if (trialRaw) {
+      trialExpiresAt = new Date(trialRaw);
+      if (Number.isNaN(trialExpiresAt.getTime())) {
+        return "Trial expiry must be a valid date.";
+      }
+    }
+    await deps.lifecycle.update(id, {
+      name,
+      maxAgents,
+      plan: field(form, "plan") || null,
+      trialExpiresAt,
+    });
+    return undefined;
+  });
+
+  action("suspend", async ({ id }) => {
+    await deps.lifecycle.update(id, { status: "suspended" });
+    return undefined;
+  });
+
+  action("reactivate", async ({ id }) => {
+    try {
+      await deps.lifecycle.update(id, { status: "active" });
+    } catch (err) {
+      if (err instanceof UnprocessableEntityError) return err.message;
+      throw err;
+    }
+    return undefined;
+  });
+
+  /** SSP-5.3: set (accountId) or clear (null) Agent.accountId, then reconcile. */
+  async function setAgentAccount(
+    agentId: string,
+    accountId: string | null,
+  ): Promise<undefined> {
+    const updated = await deps.agents.updateFields(agentId, { accountId });
+    // The change is committed; a reconcile failure is logged, not surfaced as
+    // a form error (the next reconcile pass converges the workload).
+    const warning = await reconcileAgentAfterAccountChange(
+      deps.provisioner,
+      updated,
+    );
+    if (warning) console.warn(`[admin-accounts] ${agentId}: ${warning}`);
+    return undefined;
+  }
+
+  action("agents/assign", async ({ id, form }) => {
+    const agentId = field(form, "agentId");
+    if (!agentId) return "Agent ID is required.";
+    if (!(await deps.agents.getDetail(agentId))) {
+      return `Agent ${agentId} not found.`;
+    }
+    return setAgentAccount(agentId, id);
+  });
+
+  action("agents/unassign", async ({ id, form }) => {
+    const agentId = field(form, "agentId");
+    const agent = await deps.agents.getDetail(agentId);
+    if (!agent || agent.accountId !== id) {
+      return "Agent is not assigned to this account.";
+    }
+    return setAgentAccount(agentId, null);
+  });
+
+  action("members/add", async ({ id, form }) => {
+    const email = normalizeEmail(field(form, "email"));
+    if (!EMAIL_RE.test(email)) return "Enter a valid email address.";
+    if (await deps.members.getByEmail(email)) {
+      return "That email already belongs to an account.";
+    }
+    const role = field(form, "role") === "owner" ? "owner" : "member";
+    await deps.members.add(id, email, role);
+    return undefined;
+  });
+
+  action("members/remove", async ({ id, form }) => {
+    await deps.members.remove(id, field(form, "email"));
+    return undefined;
+  });
+  action("members/promote", async ({ id, form }) => {
+    await deps.members.promote(id, field(form, "email"));
+    return undefined;
+  });
+  action("members/demote", async ({ id, form }) => {
+    await deps.members.demote(id, field(form, "email"));
+    return undefined;
+  });
+}

package/src/admin-ui-layout.ts

@@ -0,0 +1,60 @@
+/**
+ * admin/src/admin-ui-layout.ts
+ * Shared admin page-head helper — a dumb string wrapper around the
+ * `<!DOCTYPE html>` boilerplate that every render*Page function in
+ * admin-ui-pages.ts needs: charset, a normalized viewport meta, an escaped
+ * title, a <style> tag combining baseStyles() with page-specific extra
+ * rules, and the <body> wrapper.
+ *
+ * Deliberately carries no toolbar logic — callers still invoke
+ * renderAdminToolbar() themselves as part of their `body` string (and
+ * renderLoginPage has no toolbar at all).
+ *
+ * Follows the same inline HTML template string pattern as
+ * metrics/src/dashboard/dashboard-page.ts.
+ */
+
+import { baseStyles, escapeHtml } from "./admin-ui-styles.ts";
+
+interface RenderAdminPageOptions {
+  /** Raw, unescaped page title — HTML-escaped internally before rendering. */
+  title: string;
+  /** Extra CSS rules appended inside <style> after baseStyles(). */
+  extraStyles?: string;
+  /** Extra markup appended inside <head>, after the <style> tag. */
+  headExtra?: string;
+  /** Optional class attribute for <body>. Omitted entirely when unset. */
+  bodyClass?: string;
+  /** Body markup — callers own toolbar calls, cards, forms, etc. */
+  body: string;
+  /** Markup appended after `body`, still inside <body> (e.g. a page-level <script>). */
+  bodyEnd?: string;
+}
+
+/**
+ * Renders the shared `<!DOCTYPE html>` document wrapper used by every admin
+ * page. The viewport meta is normalized to
+ * `width=device-width, initial-scale=1, viewport-fit=cover` —
+ * `viewport-fit=cover` is load-bearing: it's what makes
+ * `env(safe-area-inset-*)` return non-zero on iOS, which the sticky composer
+ * and standalone/PWA mode both need. Does not add `maximum-scale=1`, which
+ * would be an accessibility regression.
+ */
+export function renderAdminPage(opts: RenderAdminPageOptions): string {
+  const bodyTag = opts.bodyClass
+    ? `<body class="${opts.bodyClass}">`
+    : "<body>";
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+  <title>${escapeHtml(opts.title)}</title>
+  <style>${baseStyles()}${opts.extraStyles ?? ""}</style>${opts.headExtra ? `\n  ${opts.headExtra}` : ""}
+</head>
+${bodyTag}
+  ${opts.body}${opts.bodyEnd ? `\n  ${opts.bodyEnd}` : ""}
+</body>
+</html>`;
+}

package/src/admin-ui-layout.unit.test.ts

@@ -0,0 +1,140 @@
+/**
+ * admin/src/admin-ui-layout.unit.test.ts
+ * Pure unit tests for renderAdminPage() — the shared admin page-head helper.
+ *
+ * Strategy: call renderAdminPage() directly, assert on the returned HTML
+ * string. No I/O, no Hono, no HTTP — pure string → string.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { renderAdminPage } from "./admin-ui-layout.ts";
+
+describe("renderAdminPage", () => {
+  test("renders a full HTML document with DOCTYPE, head, and body", () => {
+    const html = renderAdminPage({
+      title: "My Page",
+      body: "<div>hello</div>",
+    });
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).toContain('<html lang="en">');
+    expect(html).toContain("</html>");
+    expect(html).toContain("<div>hello</div>");
+  });
+
+  test("escapes the title param", () => {
+    const html = renderAdminPage({
+      title: '<script>alert("xss")</script>',
+      body: "<div>hello</div>",
+    });
+    expect(html).not.toContain("<title><script>");
+    expect(html).toContain(
+      "<title>&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</title>",
+    );
+  });
+
+  test("normalizes the viewport meta to width=device-width, initial-scale=1, viewport-fit=cover", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div></div>" });
+    expect(html).toContain(
+      '<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />',
+    );
+    expect(html).not.toContain("maximum-scale=1");
+  });
+
+  test("renders exactly one DOCTYPE and one viewport meta tag", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div></div>" });
+    expect(html.match(/<!DOCTYPE html>/g)?.length).toBe(1);
+    expect(html.match(/<meta name="viewport"/g)?.length).toBe(1);
+  });
+
+  test("includes charset meta tag", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div></div>" });
+    expect(html).toContain('<meta charset="utf-8" />');
+  });
+
+  test("extraStyles content appears after baseStyles() inside the style tag", () => {
+    const html = renderAdminPage({
+      title: "Page",
+      extraStyles: ".my-extra-class { color: red; }",
+      body: "<div></div>",
+    });
+    const styleOpenIdx = html.indexOf("<style>");
+    const styleCloseIdx = html.indexOf("</style>");
+    const extraIdx = html.indexOf(".my-extra-class");
+    expect(styleOpenIdx).toBeGreaterThan(-1);
+    expect(extraIdx).toBeGreaterThan(styleOpenIdx);
+    expect(extraIdx).toBeLessThan(styleCloseIdx);
+
+    // baseStyles() output (e.g. the .page-header rule) must precede extraStyles.
+    const baseStylesIdx = html.indexOf(".page-header");
+    expect(baseStylesIdx).toBeGreaterThan(-1);
+    expect(baseStylesIdx).toBeLessThan(extraIdx);
+  });
+
+  test("without extraStyles, style tag still closes cleanly right after baseStyles()", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div></div>" });
+    expect(html).toContain("</style>");
+  });
+
+  test("headExtra content is included in the head, after the style tag", () => {
+    const html = renderAdminPage({
+      title: "Page",
+      headExtra: '<link rel="manifest" href="/manifest.json" />',
+      body: "<div></div>",
+    });
+    const styleCloseIdx = html.indexOf("</style>");
+    const headExtraIdx = html.indexOf("/manifest.json");
+    const headCloseIdx = html.indexOf("</head>");
+    expect(headExtraIdx).toBeGreaterThan(styleCloseIdx);
+    expect(headExtraIdx).toBeLessThan(headCloseIdx);
+  });
+
+  test("without headExtra, head still closes cleanly", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div></div>" });
+    expect(html).toContain("</head>");
+  });
+
+  test("bodyClass is applied to the body tag when provided", () => {
+    const html = renderAdminPage({
+      title: "Page",
+      bodyClass: "my-body-class",
+      body: "<div></div>",
+    });
+    expect(html).toContain('<body class="my-body-class">');
+  });
+
+  test("body has no class attribute when bodyClass is omitted", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div></div>" });
+    expect(html).toContain("<body>");
+    expect(html).not.toContain("<body class=");
+  });
+
+  test("bodyEnd content appears after body content and before </body>", () => {
+    const html = renderAdminPage({
+      title: "Page",
+      body: '<div id="main-body-marker">main</div>',
+      bodyEnd: '<script id="body-end-marker">console.log("end")</script>',
+    });
+    const bodyIdx = html.indexOf("main-body-marker");
+    const bodyEndIdx = html.indexOf("body-end-marker");
+    const bodyCloseIdx = html.indexOf("</body>");
+    expect(bodyIdx).toBeGreaterThan(-1);
+    expect(bodyEndIdx).toBeGreaterThan(bodyIdx);
+    expect(bodyEndIdx).toBeLessThan(bodyCloseIdx);
+  });
+
+  test("without bodyEnd, body closes cleanly right after body content", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div>content</div>" });
+    expect(html).toContain("<div>content</div>");
+    expect(html).toContain("</body>");
+  });
+
+  test("does not call renderAdminToolbar or inject any toolbar markup", () => {
+    const html = renderAdminPage({ title: "Page", body: "<div></div>" });
+    // baseStyles() legitimately contains `.vos-toolbar { ... }` and
+    // `.vos-signout-btn { ... }` CSS rules, but renderAdminPage itself must
+    // never inject the toolbar's actual <nav>/<button> markup — that's the
+    // caller's responsibility via body.
+    expect(html).not.toContain('<nav class="vos-toolbar"');
+    expect(html).not.toContain('class="vos-signout-btn"');
+  });
+});