@app-vitals/agent-admin 0.0.1 → 0.1.1

package/src/pwa.unit.test.ts

@@ -0,0 +1,321 @@
+/**
+ * admin/src/pwa.unit.test.ts
+ * Unit tests for the PWA shell's pure functions: manifest building, service
+ * worker body generation, the precache allowlist, and the shouldCache
+ * predicate. No I/O — everything here takes plain inputs and returns data.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  buildManifest,
+  buildOfflinePageHtml,
+  buildServiceWorkerBody,
+  getPrecacheList,
+  PWA_ICONS,
+  renderPwaHeadTags,
+  sanitizeStartUrl,
+  shouldCachePwaRequest,
+} from "./pwa.ts";
+import tokens from "./theme-tokens.json";
+
+describe("getPrecacheList", () => {
+  it("is exactly the offline page plus the six icons — nothing else", () => {
+    const list = getPrecacheList();
+    const expected = [
+      "/admin/offline.html",
+      ...PWA_ICONS.map((icon) => `/admin/icons/${icon.filename}`),
+    ];
+    expect(list.sort()).toEqual(expected.sort());
+    expect(list.length).toBe(7);
+  });
+
+  it("contains no HTML document routes other than the offline fallback", () => {
+    const list = getPrecacheList();
+    const nonOfflineHtml = list.filter(
+      (url) => url.endsWith(".html") && url !== "/admin/offline.html",
+    );
+    expect(nonOfflineHtml).toEqual([]);
+  });
+
+  it("contains no .json routes", () => {
+    const list = getPrecacheList();
+    expect(list.some((url) => url.endsWith(".json"))).toBe(false);
+  });
+
+  it("contains nothing under /admin/chat/", () => {
+    const list = getPrecacheList();
+    expect(list.some((url) => url.startsWith("/admin/chat/"))).toBe(false);
+  });
+});
+
+describe("shouldCachePwaRequest", () => {
+  it("allows GET requests for precached icon paths", () => {
+    expect(shouldCachePwaRequest("/admin/icons/icon-192.png", "GET")).toBe(
+      true,
+    );
+  });
+
+  it("allows GET for the offline fallback page", () => {
+    expect(shouldCachePwaRequest("/admin/offline.html", "GET")).toBe(true);
+  });
+
+  it("never caches document navigations (other HTML paths)", () => {
+    expect(shouldCachePwaRequest("/admin/agents", "GET")).toBe(false);
+    expect(shouldCachePwaRequest("/admin/agents/abc123", "GET")).toBe(false);
+    expect(shouldCachePwaRequest("/admin/login", "GET")).toBe(false);
+  });
+
+  it("never caches any .json route", () => {
+    expect(shouldCachePwaRequest("/admin/manifest.webmanifest", "GET")).toBe(
+      false,
+    );
+    expect(shouldCachePwaRequest("/agents/config.json", "GET")).toBe(false);
+  });
+
+  it("never caches anything under /admin/chat/", () => {
+    expect(shouldCachePwaRequest("/admin/chat/", "GET")).toBe(false);
+    expect(shouldCachePwaRequest("/admin/chat/thread-1", "GET")).toBe(false);
+    expect(shouldCachePwaRequest("/admin/chat/thread-1/messages", "GET")).toBe(
+      false,
+    );
+  });
+
+  it("never caches non-GET requests, even for allowlisted paths", () => {
+    expect(shouldCachePwaRequest("/admin/icons/icon-192.png", "POST")).toBe(
+      false,
+    );
+    expect(shouldCachePwaRequest("/admin/offline.html", "PUT")).toBe(false);
+    expect(shouldCachePwaRequest("/admin/offline.html", "DELETE")).toBe(false);
+    expect(shouldCachePwaRequest("/admin/offline.html", "HEAD")).toBe(false);
+  });
+
+  it("never caches an arbitrary unknown path", () => {
+    expect(shouldCachePwaRequest("/admin/some-random-thing", "GET")).toBe(
+      false,
+    );
+  });
+});
+
+describe("PWA_ICONS", () => {
+  it("declares exactly six icons", () => {
+    expect(PWA_ICONS.length).toBe(6);
+  });
+
+  it("includes at least one maskable icon and the apple-touch-icon", () => {
+    expect(PWA_ICONS.some((i) => i.purpose === "maskable")).toBe(true);
+    expect(PWA_ICONS.some((i) => i.filename === "apple-touch-icon.png")).toBe(
+      true,
+    );
+  });
+});
+
+describe("buildManifest", () => {
+  it("sets scope /admin/, start_url /admin/chat, and display standalone", () => {
+    const manifest = buildManifest();
+    expect(manifest.scope).toBe("/admin/");
+    expect(manifest.start_url).toBe("/admin/chat");
+    expect(manifest.display).toBe("standalone");
+  });
+
+  it("sources theme_color and background_color from brand/tokens.json", () => {
+    const manifest = buildManifest();
+    expect(manifest.theme_color).toBe(tokens.color.brand.default);
+    expect(manifest.background_color).toBe(tokens.color.bg.base);
+  });
+
+  it("declares icons entries with any + maskable purposes and correct src paths", () => {
+    const manifest = buildManifest();
+    expect(manifest.icons.length).toBe(
+      PWA_ICONS.filter((i) => i.purpose !== "apple-touch-icon").length,
+    );
+    for (const icon of manifest.icons) {
+      expect(icon.src.startsWith("/admin/icons/")).toBe(true);
+      expect(["any", "maskable"]).toContain(icon.purpose);
+    }
+  });
+
+  it("uses a caller-supplied startUrl as start_url (PWA-1.1)", () => {
+    const manifest = buildManifest("/admin/tasks");
+    expect(manifest.start_url).toBe("/admin/tasks");
+  });
+
+  it("still defaults to /admin/chat when startUrl is omitted (backward compatible)", () => {
+    const manifest = buildManifest(undefined);
+    expect(manifest.start_url).toBe("/admin/chat");
+  });
+});
+
+describe("sanitizeStartUrl (PWA-1.1)", () => {
+  it("falls back to /admin/chat for null, undefined, and empty input", () => {
+    expect(sanitizeStartUrl(null)).toBe("/admin/chat");
+    expect(sanitizeStartUrl(undefined)).toBe("/admin/chat");
+    expect(sanitizeStartUrl("")).toBe("/admin/chat");
+  });
+
+  it("passes through same-origin /admin/... paths unchanged", () => {
+    expect(sanitizeStartUrl("/admin/chat")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/tasks")).toBe("/admin/tasks");
+    expect(sanitizeStartUrl("/admin/agents/123")).toBe("/admin/agents/123");
+  });
+
+  it("rejects bare /admin with no trailing in-scope content", () => {
+    expect(sanitizeStartUrl("/admin")).toBe("/admin/chat");
+  });
+
+  it("rejects external absolute URLs", () => {
+    expect(sanitizeStartUrl("https://evil.com")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("http://evil.com/admin/chat")).toBe("/admin/chat");
+  });
+
+  it("rejects protocol-relative URLs", () => {
+    expect(sanitizeStartUrl("//evil.com/x")).toBe("/admin/chat");
+  });
+
+  it("rejects javascript: URLs", () => {
+    expect(sanitizeStartUrl("javascript:alert(1)")).toBe("/admin/chat");
+  });
+
+  it("rejects path traversal, raw and encoded", () => {
+    expect(sanitizeStartUrl("/admin/../etc/passwd")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/tasks/../../etc/passwd")).toBe(
+      "/admin/chat",
+    );
+    expect(sanitizeStartUrl("/admin/%2e%2e/etc/passwd")).toBe("/admin/chat");
+  });
+
+  it("rejects malformed percent-encoding instead of throwing", () => {
+    expect(sanitizeStartUrl("/admin/%zz")).toBe("/admin/chat");
+  });
+
+  it("rejects a path not under /admin/", () => {
+    expect(sanitizeStartUrl("/tasks")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/")).toBe("/admin/chat");
+  });
+
+  it("rejects the PWA shell's own non-navigable asset routes", () => {
+    expect(sanitizeStartUrl("/admin/manifest.webmanifest")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/sw.js")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/offline.html")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/icons/icon-192.png")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/icons/apple-touch-icon.png")).toBe(
+      "/admin/chat",
+    );
+  });
+
+  it("rejects the PWA shell's own auth routes", () => {
+    expect(sanitizeStartUrl("/admin/login")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/logout")).toBe("/admin/chat");
+  });
+
+  it("rejects OAuth callback routes for every provider", () => {
+    expect(sanitizeStartUrl("/admin/auth/callback")).toBe("/admin/chat");
+    expect(sanitizeStartUrl("/admin/auth/okta/callback")).toBe("/admin/chat");
+    expect(
+      sanitizeStartUrl("/admin/agents/abc123/connect-slack/callback"),
+    ).toBe("/admin/chat");
+    expect(
+      sanitizeStartUrl("/admin/agents/abc123/connect-github/callback"),
+    ).toBe("/admin/chat");
+  });
+});
+
+describe("buildServiceWorkerBody", () => {
+  it("interpolates the version into the cache name", () => {
+    const body = buildServiceWorkerBody("1.200.0", getPrecacheList());
+    expect(body).toContain("shipwright-admin-pwa-v1.200.0");
+  });
+
+  it("embeds exactly the precache list, not an arbitrary superset", () => {
+    const precache = getPrecacheList();
+    const body = buildServiceWorkerBody("1.200.0", precache);
+    for (const url of precache) {
+      expect(body).toContain(JSON.stringify(url));
+    }
+  });
+
+  it("is a pure function — repeated calls with the same input are identical", () => {
+    const precache = getPrecacheList();
+    const a = buildServiceWorkerBody("1.200.0", precache);
+    const b = buildServiceWorkerBody("1.200.0", precache);
+    expect(a).toBe(b);
+  });
+
+  it("different versions bust the cache name", () => {
+    const precache = getPrecacheList();
+    const a = buildServiceWorkerBody("1.200.0", precache);
+    const b = buildServiceWorkerBody("1.201.0", precache);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("buildServiceWorkerBody — push + notificationclick (CFB-4.2)", () => {
+  it("registers a push listener that shows a notification", () => {
+    const body = buildServiceWorkerBody("1.200.0", getPrecacheList());
+    expect(body).toContain('addEventListener("push"');
+    expect(body).toContain("showNotification");
+  });
+
+  it("registers a notificationclick listener that focuses/opens the thread", () => {
+    const body = buildServiceWorkerBody("1.200.0", getPrecacheList());
+    expect(body).toContain('addEventListener("notificationclick"');
+    expect(body).toContain("clients.openWindow");
+  });
+
+  it("reads the deep-link url from the notification payload data", () => {
+    const body = buildServiceWorkerBody("1.200.0", getPrecacheList());
+    // The push payload is JSON {title, body, url}; the SW must parse it.
+    expect(body).toContain("event.data");
+    expect(body).toContain(".url");
+  });
+
+  it("reads payload.tag for the notification tag, falling back to the shipwright-agent-reply default (SESH-7.3)", () => {
+    const body = buildServiceWorkerBody("1.200.0", getPrecacheList());
+    // A session-scoped payload (tag: "shipwright-session-x") must produce a
+    // distinctly-tagged notification so two session payloads never coalesce;
+    // a tagless chat payload must still fall back to the existing default.
+    expect(body).toContain("payload.tag");
+    expect(body).toContain('tag: payload.tag || "shipwright-agent-reply"');
+  });
+});
+
+describe("buildOfflinePageHtml", () => {
+  it("renders a self-contained document with no external requests", () => {
+    const html = buildOfflinePageHtml();
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).not.toContain("<script");
+    expect(html).not.toContain("<link");
+    expect(html).not.toContain("<img");
+  });
+
+  it("is a pure function — deterministic output", () => {
+    expect(buildOfflinePageHtml()).toBe(buildOfflinePageHtml());
+  });
+});
+
+describe("renderPwaHeadTags", () => {
+  it("includes the manifest link and SW registration script for an https appBaseUrl", () => {
+    const head = renderPwaHeadTags("https://admin.example.com");
+    expect(head).toContain('rel="manifest"');
+    expect(head).toContain("/admin/manifest.webmanifest");
+    expect(head).toContain("serviceWorker");
+    expect(head).toContain("/admin/sw.js");
+  });
+
+  it("is suppressed entirely for a plain-http appBaseUrl (home-lab operators)", () => {
+    const head = renderPwaHeadTags("http://localhost:3001");
+    expect(head).toBe("");
+  });
+
+  it("is suppressed for a malformed/empty appBaseUrl", () => {
+    expect(renderPwaHeadTags("")).toBe("");
+  });
+
+  it("gives the manifest link a stable id and rewrites its href to the current pathname on load (PWA-1.1)", () => {
+    const head = renderPwaHeadTags("https://admin.example.com");
+    expect(head).toContain('id="pwa-manifest-link"');
+    expect(head).toContain("getElementById('pwa-manifest-link')");
+    expect(head).toContain("location.pathname");
+    expect(head).toContain("?start=");
+    expect(head).toContain("encodeURIComponent");
+  });
+});

package/src/schema.unit.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Reads the schema file and asserts it uses the postgresql provider and the namespaced env var.
+// This test is intentionally narrow — it guards against accidental provider regression.
+
+// The admin schema is a Prisma multi-file schema folder (prisma/schema/):
+// schema.prisma holds the generator/datasource + shared models, coding.prisma
+// the coding-owned models. Assertions run against the concatenation.
+const schemaDir = join(import.meta.dir, "../prisma/schema");
+const schema = readdirSync(schemaDir)
+  .filter((f) => f.endsWith(".prisma"))
+  .sort()
+  .map((f) => readFileSync(join(schemaDir, f), "utf-8"))
+  .join("\n");
+
+const configPath = join(import.meta.dir, "../prisma.config.ts");
+const config = readFileSync(configPath, "utf-8");
+
+describe("admin/prisma/schema/", () => {
+  test('datasource provider is "postgresql"', () => {
+    expect(schema).toContain('provider = "postgresql"');
+  });
+
+  test('generator provider is "prisma-client"', () => {
+    // Prisma 7 replaced the `prisma-client-js` generator with `prisma-client`;
+    // regressing to the old one would also silently re-break every
+    // `../prisma/client/client.ts` import.
+    expect(schema).toContain('provider = "prisma-client"');
+  });
+
+  test("datasource block declares no url (Prisma 7 moved it to prisma.config.ts)", () => {
+    expect(schema).toMatch(/datasource db \{\s*provider = "postgresql"\s*\}/);
+    expect(schema).not.toContain("url      = env(");
+  });
+
+  test("prisma.config.ts sources the url from DATABASE_URL_SHIPWRIGHT_ADMIN", () => {
+    expect(config).toContain("process.env.DATABASE_URL_SHIPWRIGHT_ADMIN");
+  });
+
+  describe("AgentCronRun model", () => {
+    test("model AgentCronRun exists in schema", () => {
+      expect(schema).toContain("model AgentCronRun");
+    });
+
+    test("id field is String @id @default(cuid())", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?id\s+String\s+@id\s+@default\(cuid\(\)\)/,
+      );
+    });
+
+    test("cronId field with @relation to AgentCronJob and onDelete: Cascade", () => {
+      expect(schema).toMatch(/model AgentCronRun \{[\s\S]*?cronId\s+String/);
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?@relation\(fields: \[cronId\], references: \[id\], onDelete: Cascade\)/,
+      );
+    });
+
+    test("agentId field is String (denormalized)", () => {
+      expect(schema).toMatch(/model AgentCronRun \{[\s\S]*?agentId\s+String/);
+    });
+
+    test("startedAt field is DateTime", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?startedAt\s+DateTime/,
+      );
+    });
+
+    test("completedAt field is DateTime? (nullable)", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?completedAt\s+DateTime\?/,
+      );
+    });
+
+    test("skipped field is Boolean @default(false)", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?skipped\s+Boolean\s+@default\(false\)/,
+      );
+    });
+
+    test("skipReason field is String? (nullable)", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?skipReason\s+String\?/,
+      );
+    });
+
+    test("outcome field is String? (nullable)", () => {
+      expect(schema).toMatch(/model AgentCronRun \{[\s\S]*?outcome\s+String\?/);
+    });
+
+    test("error field is String? (nullable)", () => {
+      expect(schema).toMatch(/model AgentCronRun \{[\s\S]*?error\s+String\?/);
+    });
+
+    test("createdAt field is DateTime @default(now())", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?createdAt\s+DateTime\s+@default\(now\(\)\)/,
+      );
+    });
+
+    test("@@index([cronId]) present", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?@@index\(\[cronId\]\)/,
+      );
+    });
+
+    test("@@index([agentId, startedAt]) present", () => {
+      expect(schema).toMatch(
+        /model AgentCronRun \{[\s\S]*?@@index\(\[agentId, startedAt\]\)/,
+      );
+    });
+  });
+
+  describe("AgentCronJob back-relation", () => {
+    test("AgentCronJob has runs AgentCronRun[] back-relation", () => {
+      expect(schema).toMatch(
+        /model AgentCronJob \{[\s\S]*?runs\s+AgentCronRun\[\]/,
+      );
+    });
+  });
+});

package/src/self-serve-config.ts

@@ -0,0 +1,52 @@
+/**
+ * admin/src/self-serve-config.ts
+ *
+ * Pure parser for the self-serve agent provisioning env config. Takes an
+ * injected env object (no process.env reads) so it is deterministically
+ * unit-testable; admin/src/main.ts reads it once at startup and injects the
+ * resolved config as deps.
+ */
+
+export const DEFAULT_SELF_SERVE_CONTACT_EMAIL = "dan@app-vitals.com";
+
+/** Structural env shape — accepts `process.env` or a plain test object. */
+type SelfServeEnv = Readonly<Record<string, string | undefined>>;
+
+export interface SelfServeConfig {
+  /** True only when SHIPWRIGHT_SELF_SERVE_ENABLED === "enabled". */
+  enabled: boolean;
+  /** Default per-account agent quota (integer >= 0). */
+  defaultMaxAgents: number;
+  /** Contact address shown when a user needs more quota. */
+  contactEmail: string;
+}
+
+/**
+ * Resolve the self-serve config from env. Invalid DEFAULT_MAX_AGENTS values
+ * (negative, non-integer, non-numeric) fall back to 0 and log a warning via
+ * the injected `warn` (defaults to console.warn).
+ */
+export function parseSelfServeConfig(
+  env: SelfServeEnv,
+  warn: (message: string) => void = console.warn,
+): SelfServeConfig {
+  const enabled = env.SHIPWRIGHT_SELF_SERVE_ENABLED === "enabled";
+
+  let defaultMaxAgents = 0;
+  const raw = env.SHIPWRIGHT_SELF_SERVE_DEFAULT_MAX_AGENTS?.trim();
+  if (raw) {
+    if (/^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))) {
+      defaultMaxAgents = Number(raw);
+    } else {
+      warn(
+        `[admin] invalid SHIPWRIGHT_SELF_SERVE_DEFAULT_MAX_AGENTS=${JSON.stringify(raw)} (expected integer >= 0) — falling back to 0`,
+      );
+    }
+  }
+
+  const contactEmail =
+    env.SHIPWRIGHT_SELF_SERVE_CONTACT_EMAIL?.trim() ||
+    DEFAULT_SELF_SERVE_CONTACT_EMAIL;
+
+  return { enabled, defaultMaxAgents, contactEmail };
+}

package/src/self-serve-config.unit.test.ts

@@ -0,0 +1,79 @@
+/**
+ * admin/src/self-serve-config.unit.test.ts
+ *
+ * Unit tests for the self-serve env config parser. Pure logic over an
+ * injected env object — no process.env reads, no I/O.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { parseSelfServeConfig } from "./self-serve-config.ts";
+
+function parse(env: Record<string, string | undefined>) {
+  const warnings: string[] = [];
+  const config = parseSelfServeConfig(env, (m) => warnings.push(m));
+  return { config, warnings };
+}
+
+describe("parseSelfServeConfig", () => {
+  it("defaults to off, 0 agents, and the default contact when env is empty", () => {
+    const { config, warnings } = parse({});
+    expect(config).toEqual({
+      enabled: false,
+      defaultMaxAgents: 0,
+      contactEmail: "dan@app-vitals.com",
+    });
+    expect(warnings).toEqual([]);
+  });
+
+  it("enables only on the exact value 'enabled'", () => {
+    expect(
+      parse({ SHIPWRIGHT_SELF_SERVE_ENABLED: "enabled" }).config.enabled,
+    ).toBe(true);
+    for (const v of ["true", "1", "ENABLED", "", "disabled"]) {
+      expect(parse({ SHIPWRIGHT_SELF_SERVE_ENABLED: v }).config.enabled).toBe(
+        false,
+      );
+    }
+  });
+
+  it("parses a valid DEFAULT_MAX_AGENTS without warning", () => {
+    const { config, warnings } = parse({
+      SHIPWRIGHT_SELF_SERVE_DEFAULT_MAX_AGENTS: "3",
+    });
+    expect(config.defaultMaxAgents).toBe(3);
+    expect(warnings).toEqual([]);
+  });
+
+  it("accepts an explicit 0", () => {
+    const { config, warnings } = parse({
+      SHIPWRIGHT_SELF_SERVE_DEFAULT_MAX_AGENTS: "0",
+    });
+    expect(config.defaultMaxAgents).toBe(0);
+    expect(warnings).toEqual([]);
+  });
+
+  it.each(["-1", "1.5", "abc", "1e3", "99999999999999999999"])(
+    "falls back to 0 and warns for invalid DEFAULT_MAX_AGENTS %p",
+    (value) => {
+      const { config, warnings } = parse({
+        SHIPWRIGHT_SELF_SERVE_DEFAULT_MAX_AGENTS: value,
+      });
+      expect(config.defaultMaxAgents).toBe(0);
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0]).toContain("SHIPWRIGHT_SELF_SERVE_DEFAULT_MAX_AGENTS");
+    },
+  );
+
+  it("uses a custom contact email, trimmed", () => {
+    expect(
+      parse({ SHIPWRIGHT_SELF_SERVE_CONTACT_EMAIL: " ops@example.com " }).config
+        .contactEmail,
+    ).toBe("ops@example.com");
+  });
+
+  it("falls back to the default contact when blank", () => {
+    expect(
+      parse({ SHIPWRIGHT_SELF_SERVE_CONTACT_EMAIL: "  " }).config.contactEmail,
+    ).toBe("dan@app-vitals.com");
+  });
+});