@app-vitals/agent-admin 1.13.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-admin",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.135.0",
-    "@app-vitals/agent-lib": "1.13.0",
+    "@app-vitals/agent-lib": "1.15.0",
     "@hono/zod-openapi": "^1.0.0",
     "@prisma/adapter-pg": "^7.10.0",
     "@prisma/client": "^7.10.0",

package/src/admin-boot.ts

@@ -99,6 +99,8 @@ import { CronRunNowService } from "./cron-run-now.ts";
 import { parseCronRunNowConfig } from "./cron-run-now-config.ts";
 import { CronRunTranscriptService } from "./cron-run-transcripts.ts";
 import { isDevAuthAllowed } from "./dev-auth-guard.ts";
+import { createGithubEnterpriseApp } from "./github-enterprise-api.ts";
+import { GitHubEnterpriseAppService } from "./github-enterprise-apps.ts";
 import { HttpGithubAppProvisioningClient } from "./github-app-provisioning-client.ts";
 import { HttpGoogleAuthClient } from "./google-auth-client.ts";
 import { HttpChatClient } from "./http-chat-client.ts";
@@ -113,7 +115,7 @@ import { parseSelfServeConfig } from "./self-serve-config.ts";
 import { HttpSlackProvisioningClient } from "./slack-provisioning-client.ts";
 import { SpecialtyTypes } from "./specialty-types.ts";
 import { runStartupPolicyReconcile } from "./startup-policy-reconcile.ts";
-import { makeTokenCrypto } from "./token-crypto.ts";
+import { makeStrictTokenCrypto, makeTokenCrypto } from "./token-crypto.ts";
 import { parseTranscriptConfig } from "./transcript-config.ts";
 import {
   resolveTrialExpirySweepIntervalMs,
@@ -530,6 +532,19 @@ export async function startAdmin(
     }),
   );
 
+  // 3b'. GitHub Enterprise Apps API — /github-enterprise/* — admin-only,
+  //      optional (GHE-1.3). With no rows configured it reports unconfigured
+  //      and does nothing else. Strict crypto: no plain-text key storage.
+  const githubEnterpriseApp = createGithubEnterpriseApp({
+    appService: new GitHubEnterpriseAppService(prisma, makeStrictTokenCrypto()),
+    agentService,
+    agentEnvService,
+    sessionSecret,
+    adminApiKeys,
+    agentTokenService,
+  });
+  root.route("/", githubEnterpriseApp);
+
   // 3c. Extension API routes — after every platform API, before the admin UI
   //     (same no-shadowing rule as the admin CRUD API above).
   mountRouteContributions(root, resolvedExtensions.apiRoutes);
@@ -594,6 +609,8 @@ export async function startAdmin(
       });
       return accountCreatedNotifier ? { accountCreatedNotifier } : {};
     })(),
+    githubEnterpriseApi: (path, init) =>
+      githubEnterpriseApp.request(path, init),
     accountServices: {
       accounts: new AccountService(prisma),
       members: new AccountMemberService(prisma),

package/src/admin-spec.ts

@@ -24,6 +24,7 @@ import {
   parseAdminApiKeys,
 } from "./agents-api.ts";
 import { createAgentRuntimeApp } from "./api.ts";
+import { createGithubEnterpriseApp } from "./github-enterprise-api.ts";
 
 /** The admin OpenAPI document shape the spec builders and generators share. */
 export interface AdminOpenApiDocument {
@@ -172,6 +173,23 @@ export function buildPlatformAdminSpec(): AdminOpenApiDocument {
     }
   }
 
+  // GHE-1.3: the /github-enterprise routes live in their own app (mounted at
+  // the root in admin-boot.ts); fold their paths and schemas in.
+  const gheSpec = createGithubEnterpriseApp({
+    appService: {} as never,
+    agentService: {} as never,
+    agentEnvService: {} as never,
+    sessionSecret: SESSION_SECRET,
+    adminApiKeys,
+    agentTokenService: { validate: async () => null },
+  }).getOpenAPI31Document({
+    openapi: "3.1.0",
+    info: { title: "github-enterprise (internal)", version: "0.1.0" },
+  });
+  for (const [path, def] of Object.entries(gheSpec.paths ?? {})) {
+    mergedPaths[path] = def as Record<string, unknown>;
+  }
+
   return {
     ...adminSpec,
     paths: mergedPaths,
@@ -180,6 +198,7 @@ export function buildPlatformAdminSpec(): AdminOpenApiDocument {
       schemas: {
         ...(adminSpec.components?.schemas ?? {}),
         ...(runtimeSpec.components?.schemas ?? {}),
+        ...(gheSpec.components?.schemas ?? {}),
       },
     },
   };

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

@@ -9,12 +9,29 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
-const storage = new AsyncLocalStorage<{ showAccount: boolean }>();
+interface NavFlags {
+  showAccount: boolean;
+  /** GHE-1.4: the admin-only "Settings" entry. */
+  showSettings: boolean;
+}
+
+const storage = new AsyncLocalStorage<NavFlags>();
 
 export function runWithAccountNav<T>(showAccount: boolean, fn: () => T): T {
-  return storage.run({ showAccount }, fn);
+  const showSettings = storage.getStore()?.showSettings === true;
+  return storage.run({ showAccount, showSettings }, fn);
 }
 
 export function shouldShowAccountNav(): boolean {
   return storage.getStore()?.showAccount === true;
 }
+
+/** Wrap a request so the toolbar shows (or hides) the admin Settings entry. */
+export function runWithSettingsNav<T>(showSettings: boolean, fn: () => T): T {
+  const showAccount = storage.getStore()?.showAccount === true;
+  return storage.run({ showAccount, showSettings }, fn);
+}
+
+export function shouldShowSettingsNav(): boolean {
+  return storage.getStore()?.showSettings === true;
+}

package/src/admin-ui-github-enterprise-pages.ts

@@ -0,0 +1,219 @@
+/**
+ * admin/src/admin-ui-github-enterprise-pages.ts
+ * Render function for the enterprise GitHub apps settings page (GHE-1.4).
+ * Pure string -> string; routes live in admin-ui-github-enterprise.ts.
+ *
+ * Credentials are paste-only: the forms accept the private key but the page
+ * never renders a key (the status API only reports `keySet`).
+ */
+
+import { renderAdminPage } from "./admin-ui-layout.ts";
+import { escapeHtml, renderAdminToolbar } from "./admin-ui-styles.ts";
+
+export const ADMIN_GITHUB_ENTERPRISE_PATH = "/admin/settings/github-enterprise";
+
+/** GithubEnterpriseApp shape returned by GET /github-enterprise/apps. */
+export interface GheApp {
+  role: string;
+  appId: string;
+  slug: string;
+  enterpriseSlug: string | null;
+  keySet: boolean;
+  lastValidationStatus: string | null;
+  lastValidatedAt: string | null;
+  lastValidationError: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface GheStatus {
+  configured: boolean;
+  installer: GheApp | null;
+  lookup: GheApp | null;
+}
+
+export interface GheOrg {
+  id: number;
+  login: string;
+  lookupAppInstalled: boolean | null;
+  agentAppInstalled: boolean | null;
+}
+
+export interface GheOrgs {
+  configured: boolean;
+  agentAppSlug?: string | null;
+  orgs: GheOrg[];
+}
+
+export interface GithubEnterpriseSettingsPageOpts {
+  userEmail: string;
+  status: GheStatus;
+  /** Present when the installer App is configured and the org list loaded. */
+  orgs?: GheOrgs;
+  /** Readable message when the org list could not be loaded. */
+  orgsError?: string;
+  /** Agent whose App the install actions target (carried via ?agentId=). */
+  agentId?: string;
+  error?: string;
+  notice?: string;
+}
+
+const BASE = ADMIN_GITHUB_ENTERPRISE_PATH;
+
+/** "2026-11-09T12:00:00.000Z" -> "2026-11-09 12:00 UTC". */
+function formatTime(iso: string): string {
+  return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+
+function validationBadge(status: string | null): string {
+  if (!status) return `<span class="badge badge-gray">Not validated yet</span>`;
+  const cls = status === "valid" ? "badge-green" : "badge-warning";
+  return `<span class="badge ${cls}">${escapeHtml(status)}</span>`;
+}
+
+const ROLE_COPY = {
+  installer: {
+    title: "Installer app",
+    help: "Installs agents' GitHub Apps on the enterprise's organizations. Needs the enterprise_organization_installations (write) permission.",
+  },
+  lookup: {
+    title: "Lookup app",
+    help: "Read-only App used to see which organizations the platform can look up. Needs the metadata (read) permission.",
+  },
+} as const;
+
+function statusLine(app: GheApp): string {
+  const validated = app.lastValidatedAt
+    ? ` &middot; ${escapeHtml(formatTime(app.lastValidatedAt))}`
+    : "";
+  const error = app.lastValidationError
+    ? `<div class="help-text" style="font-size:12px;margin-top:4px">${escapeHtml(app.lastValidationError)}</div>`
+    : "";
+  return `<div class="gh-ent-status">
+      <span class="badge badge-green">Configured</span>
+      <span class="badge ${app.keySet ? "badge-green" : "badge-warning"}">${app.keySet ? "Key set" : "Key not set"}</span>
+      ${validationBadge(app.lastValidationStatus)}${validated}
+      ${error}
+    </div>`;
+}
+
+function postButton(
+  action: string,
+  label: string,
+  cls = "btn-secondary",
+): string {
+  return `<form method="POST" action="${action}" style="display:inline;margin:0"><button type="submit" class="btn ${cls}" style="font-size:12px;padding:4px 10px">${label}</button></form>`;
+}
+
+function appCard(role: "installer" | "lookup", app: GheApp | null): string {
+  const copy = ROLE_COPY[role];
+  const action = `${BASE}/apps/${role}`;
+  const summary = app
+    ? `<p style="margin:8px 0">App ID <strong>${escapeHtml(app.appId)}</strong> &middot; slug <strong>${escapeHtml(app.slug)}</strong>${app.enterpriseSlug ? ` &middot; enterprise <strong>${escapeHtml(app.enterpriseSlug)}</strong>` : ""}</p>
+    ${statusLine(app)}
+    <div style="display:flex;gap:8px;margin:12px 0">${postButton(`${action}/validate`, "Validate")}${postButton(`${action}/delete`, "Delete", "btn-danger")}</div>`
+    : `<p class="help-text" style="font-size:12px;margin:8px 0">Not configured.</p>`;
+  const enterprise =
+    role === "installer"
+      ? `<label>Enterprise slug <input name="enterpriseSlug" class="form-input" required placeholder="my-enterprise" /></label>`
+      : "";
+  return `<div class="card">
+      <div class="card-title">${copy.title}</div>
+      <p class="help-text" style="font-size:12px">${copy.help}</p>
+      ${summary}
+      <form method="POST" action="${action}" style="display:grid;gap:8px;max-width:480px">
+        <label>App ID <input name="appId" class="form-input" required inputmode="numeric" pattern="[0-9]+" /></label>
+        <label>App slug <input name="slug" class="form-input" required /></label>
+        ${enterprise}
+        <label>Private key (PEM) <textarea name="privateKey" class="form-input" rows="4" required autocomplete="off" spellcheck="false" placeholder="Paste the private key. It is stored encrypted and never shown again."></textarea></label>
+        <div><button type="submit" class="btn btn-primary">${app ? "Replace credentials" : "Save credentials"}</button></div>
+      </form>
+    </div>`;
+}
+
+function installedCell(v: boolean | null): string {
+  if (v === null) return "&mdash;";
+  return v
+    ? `<span class="badge badge-green">Installed</span>`
+    : `<span class="badge badge-gray">Not installed</span>`;
+}
+
+function orgsCard(opts: GithubEnterpriseSettingsPageOpts): string {
+  const { status } = opts;
+  if (!status.installer) return "";
+  const agentId = opts.agentId ?? "";
+  const lookupSlug = status.lookup?.slug;
+
+  const filter = `<form method="GET" action="${BASE}" style="display:flex;gap:8px;margin:8px 0">
+        <input name="agentId" class="form-input" placeholder="Agent ID (to check its App)" value="${escapeHtml(agentId)}" style="max-width:280px" />
+        <button type="submit" class="btn btn-secondary">Check agent</button>
+      </form>`;
+
+  let body: string;
+  if (opts.orgsError) {
+    body = `<div class="alert alert-error">${escapeHtml(opts.orgsError)}</div>`;
+  } else {
+    const orgs = opts.orgs?.orgs ?? [];
+    const rows =
+      orgs.length === 0
+        ? `<tr><td colspan="4" class="empty-state">No installable organizations.</td></tr>`
+        : orgs
+            .map((o) => {
+              const login = escapeHtml(o.login);
+              const lookupAction = !lookupSlug
+                ? ""
+                : o.lookupAppInstalled
+                  ? ""
+                  : `<a class="btn btn-secondary" style="font-size:12px;padding:4px 10px" href="https://github.com/apps/${escapeHtml(lookupSlug)}/installations/new" target="_blank" rel="noopener noreferrer">Install lookup app</a>`;
+              const agentAction = `<form method="POST" action="${BASE}/orgs/${encodeURIComponent(o.login)}/install" style="display:inline-flex;gap:4px;margin:0">
+          <input name="agentId" class="form-input" required placeholder="Agent ID" value="${escapeHtml(agentId)}" style="max-width:160px;padding:4px 8px" />
+          <button type="submit" class="btn btn-primary" style="font-size:12px;padding:4px 10px">Install agent app</button>
+        </form>`;
+              return `<tr>
+      <td>${login}</td>
+      <td>${installedCell(o.lookupAppInstalled)}</td>
+      <td>${installedCell(o.agentAppInstalled)}</td>
+      <td style="text-align:right">${lookupAction} ${agentAction}</td>
+    </tr>`;
+            })
+            .join("\n");
+    body = `<table class="data-table">
+        <thead><tr><th>Organization</th><th>Lookup app</th><th>Agent app</th><th></th></tr></thead>
+        <tbody>${rows}</tbody>
+      </table>`;
+  }
+  return `<div class="card">
+      <div class="card-title">Organizations</div>
+      ${filter}
+      ${body}
+    </div>`;
+}
+
+export function renderGithubEnterpriseSettingsPage(
+  opts: GithubEnterpriseSettingsPageOpts,
+): string {
+  const { status } = opts;
+  const error = opts.error
+    ? `<div class="alert alert-error">${escapeHtml(opts.error)}</div>`
+    : "";
+  const notice = opts.notice
+    ? `<div class="alert alert-success">${escapeHtml(opts.notice)}</div>`
+    : "";
+  const emptyState = status.configured
+    ? ""
+    : `<div class="card"><div class="card-title">Not configured</div>
+      <p>This feature is optional. Without it, agents are provisioned exactly as before. Configure an installer app to install agents' GitHub Apps on your enterprise's organizations from here, and a lookup app to see which organizations are reachable. Paste the credentials of Apps you created in GitHub below.</p>
+    </div>`;
+
+  return renderAdminPage({
+    title: "GitHub Enterprise — Settings — Shipwright Admin",
+    body: `${renderAdminToolbar(opts.userEmail, BASE)}
+  <div class="vos-page">
+    <div class="page-header"><h1 class="page-title">GitHub Enterprise apps</h1></div>
+    ${error}${notice}${emptyState}
+    ${appCard("installer", status.installer)}
+    ${appCard("lookup", status.lookup)}
+    ${orgsCard(opts)}
+  </div>`,
+  });
+}

package/src/admin-ui-github-enterprise-pages.unit.test.ts

@@ -0,0 +1,183 @@
+/**
+ * admin/src/admin-ui-github-enterprise-pages.unit.test.ts
+ * Pure render tests for the enterprise GitHub apps settings page (GHE-1.4):
+ * empty, configured, validation-failed, and the never-render-the-key rule.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { runWithSettingsNav } from "./admin-ui-account-nav.ts";
+import {
+  type GheApp,
+  renderGithubEnterpriseSettingsPage,
+} from "./admin-ui-github-enterprise-pages.ts";
+import { renderAdminToolbar } from "./admin-ui-styles.ts";
+
+const PEM_MARKER = "-----BEGIN PRIVATE KEY-----";
+
+function app(over: Partial<GheApp> = {}): GheApp {
+  return {
+    role: "installer",
+    appId: "12345",
+    slug: "acme-installer",
+    enterpriseSlug: "acme",
+    keySet: true,
+    lastValidationStatus: "valid",
+    lastValidatedAt: "2026-11-09T12:00:00.000Z",
+    lastValidationError: null,
+    createdAt: "2026-11-09T11:00:00.000Z",
+    updatedAt: "2026-11-09T11:00:00.000Z",
+    ...over,
+  };
+}
+
+const base = { userEmail: "admin@x.com" };
+const empty = { configured: false, installer: null, lookup: null };
+
+describe("renderGithubEnterpriseSettingsPage", () => {
+  test("empty state explains the feature is optional and shows both paste forms", () => {
+    const html = renderGithubEnterpriseSettingsPage({ ...base, status: empty });
+    expect(html).toContain("optional");
+    expect(html).toContain("Installer app");
+    expect(html).toContain("Lookup app");
+    expect(html).toContain(
+      'action="/admin/settings/github-enterprise/apps/installer"',
+    );
+    expect(html).toContain(
+      'action="/admin/settings/github-enterprise/apps/lookup"',
+    );
+    expect(html).toContain('name="enterpriseSlug"');
+    expect(html).toContain('name="privateKey"');
+    expect(html).not.toContain("/validate");
+    expect(html).not.toContain("Organizations</div>");
+  });
+
+  test("only the installer form asks for an enterprise slug", () => {
+    const html = renderGithubEnterpriseSettingsPage({ ...base, status: empty });
+    expect(html.match(/name="enterpriseSlug"/g)?.length).toBe(1);
+  });
+
+  test("configured card shows status only: key set, result, time, no key", () => {
+    const html = renderGithubEnterpriseSettingsPage({
+      ...base,
+      status: { configured: true, installer: app(), lookup: null },
+    });
+    expect(html).toContain("acme-installer");
+    expect(html).toContain("12345");
+    expect(html).toContain("Key set");
+    expect(html).toContain("valid");
+    expect(html).toContain("2026-11-09 12:00");
+    expect(html).toContain("/apps/installer/validate");
+    expect(html).toContain("/apps/installer/delete");
+    expect(html).not.toContain(PEM_MARKER);
+    expect(html).not.toContain('type="password" value=');
+    expect(html).not.toMatch(/<textarea[^>]*>[^<]+<\/textarea>/);
+  });
+
+  test("never-validated app says so", () => {
+    const html = renderGithubEnterpriseSettingsPage({
+      ...base,
+      status: {
+        configured: true,
+        installer: app({ lastValidationStatus: null, lastValidatedAt: null }),
+        lookup: null,
+      },
+    });
+    expect(html).toContain("Not validated yet");
+  });
+
+  test("validation failure renders the stored error, escaped", () => {
+    const html = renderGithubEnterpriseSettingsPage({
+      ...base,
+      status: {
+        configured: true,
+        installer: app({
+          lastValidationStatus: "missing_permission",
+          lastValidationError: "the App does not hold <b>x</b>",
+        }),
+        lookup: null,
+      },
+    });
+    expect(html).toContain("missing_permission");
+    expect(html).toContain("the App does not hold &lt;b&gt;x&lt;/b&gt;");
+    expect(html).not.toContain("<b>x</b>");
+  });
+
+  test("key not set shows 'Key not set'", () => {
+    const html = renderGithubEnterpriseSettingsPage({
+      ...base,
+      status: {
+        configured: true,
+        installer: app({ keySet: false }),
+        lookup: null,
+      },
+    });
+    expect(html).toContain("Key not set");
+  });
+
+  test("org list renders install actions and lookup state", () => {
+    const html = renderGithubEnterpriseSettingsPage({
+      ...base,
+      agentId: "agent-1",
+      status: {
+        configured: true,
+        installer: app(),
+        lookup: app({
+          role: "lookup",
+          slug: "acme-lookup",
+          enterpriseSlug: null,
+        }),
+      },
+      orgs: {
+        configured: true,
+        agentAppSlug: "agent-app",
+        orgs: [
+          {
+            id: 1,
+            login: "org-a",
+            lookupAppInstalled: false,
+            agentAppInstalled: false,
+          },
+          {
+            id: 2,
+            login: "org-b",
+            lookupAppInstalled: true,
+            agentAppInstalled: true,
+          },
+        ],
+      },
+    });
+    expect(html).toContain("org-a");
+    expect(html).toContain("org-b");
+    expect(html).toContain(
+      "https://github.com/apps/acme-lookup/installations/new",
+    );
+    expect(html).toContain(
+      'action="/admin/settings/github-enterprise/orgs/org-a/install"',
+    );
+    expect(html).toContain('value="agent-1"');
+    expect(html).toContain("Install agent app");
+    expect(html).toContain("Installed");
+  });
+
+  test("org list failure and top-level error/notice are escaped messages", () => {
+    const html = renderGithubEnterpriseSettingsPage({
+      ...base,
+      status: { configured: true, installer: app(), lookup: null },
+      orgsError: "GitHub could not be reached <x>",
+      error: "bad <script>",
+      notice: "Saved.",
+    });
+    expect(html).toContain("GitHub could not be reached &lt;x&gt;");
+    expect(html).toContain("bad &lt;script&gt;");
+    expect(html).toContain("Saved.");
+    expect(html).not.toContain("<script>alert");
+  });
+});
+
+describe("toolbar Settings entry", () => {
+  test("hidden outside a settings-nav context, shown inside one", () => {
+    expect(renderAdminToolbar("a@x.com")).not.toContain("/admin/settings");
+    const html = runWithSettingsNav(true, () => renderAdminToolbar("a@x.com"));
+    expect(html).toContain('href="/admin/settings/github-enterprise"');
+  });
+});