@app-vitals/agent-lib 0.0.1 → 0.1.1

package/github-login.unit.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { isGithubLogin } from "./github-login.ts";
+
+describe("isGithubLogin — valid strings", () => {
+  test("returns true for a simple login", () => {
+    expect(isGithubLogin("octocat")).toBe(true);
+  });
+
+  test("returns true for a login with hyphens and numbers", () => {
+    expect(isGithubLogin("my-org-1")).toBe(true);
+  });
+
+  test("returns true for a single character login", () => {
+    expect(isGithubLogin("a")).toBe(true);
+  });
+
+  test("returns true for a login at the max length of 39 characters", () => {
+    expect(isGithubLogin("a".repeat(39))).toBe(true);
+  });
+
+  test("returns true for app/renovate bot login", () => {
+    expect(isGithubLogin("app/renovate")).toBe(true);
+  });
+
+  test("returns true for app/dependabot bot login", () => {
+    expect(isGithubLogin("app/dependabot")).toBe(true);
+  });
+
+  test("returns true for app/<slug> with hyphens", () => {
+    expect(isGithubLogin("app/my-bot-name")).toBe(true);
+  });
+});
+
+describe("isGithubLogin — invalid strings", () => {
+  test("returns false for an empty string", () => {
+    expect(isGithubLogin("")).toBe(false);
+  });
+
+  test("returns false for a login over 39 characters", () => {
+    expect(isGithubLogin("a".repeat(40))).toBe(false);
+  });
+
+  test("returns false for a login with a leading hyphen", () => {
+    expect(isGithubLogin("-octocat")).toBe(false);
+  });
+
+  test("returns false for a login with a trailing hyphen", () => {
+    expect(isGithubLogin("octocat-")).toBe(false);
+  });
+
+  test("returns false for a login with consecutive hyphens", () => {
+    expect(isGithubLogin("octo--cat")).toBe(false);
+  });
+
+  test("returns false for a login containing an underscore", () => {
+    expect(isGithubLogin("octo_cat")).toBe(false);
+  });
+
+  test("returns false for a login containing a space", () => {
+    expect(isGithubLogin("octo cat")).toBe(false);
+  });
+
+  test("returns false for a login containing a slash", () => {
+    expect(isGithubLogin("octo/cat")).toBe(false);
+  });
+
+  test("returns false for app/ with no slug", () => {
+    expect(isGithubLogin("app/")).toBe(false);
+  });
+
+  test("returns false for app/<slug> with leading hyphen in slug", () => {
+    expect(isGithubLogin("app/-bad")).toBe(false);
+  });
+
+  test("returns false for app/<slug> with double slash", () => {
+    expect(isGithubLogin("app//x")).toBe(false);
+  });
+});

package/graceful-shutdown.ts

@@ -0,0 +1,143 @@
+/**
+ * lib/graceful-shutdown.ts
+ *
+ * Wires SIGTERM/SIGINT into a coordinated shutdown for a `Bun.serve()`-backed
+ * service: stop accepting new connections (letting in-flight requests
+ * finish), run ordered cleanup (e.g. `prisma.$disconnect()`), then exit.
+ *
+ * A hard deadline forces a non-graceful `server.stop(true)` + `exit(1)` so a
+ * stuck cleanup fn can never outlive the pod's terminationGracePeriod (30s in
+ * the Helm chart — see DBE-1.x/DBE-3.1, out of scope here).
+ *
+ * Every I/O-adjacent collaborator — the server, the signal source, the exit
+ * call, and the deadline timer — is injectable so this is unit-testable with
+ * fakes: no real signals sent, no real waiting, no `mock.module()` / global
+ * overrides (see CLAUDE.md's test isolation rule).
+ */
+
+/** Below the pod's terminationGracePeriod (30s) so a stuck cleanup can't outlive it. */
+const DEFAULT_HARD_DEADLINE_MS = 20_000;
+
+/** Mirrors Bun.serve()'s return value: stop() waits for in-flight requests, stop(true) force-closes. */
+interface ShutdownServer {
+  stop(closeActiveConnections?: boolean): unknown;
+}
+
+/** Run in order on shutdown; a throw is logged and does not block later cleanup fns or the final exit. */
+type CleanupFn = () => Promise<void>;
+
+/** Narrowed to the one method this module needs — satisfied by the real `process`. */
+interface SignalSource {
+  on(event: "SIGTERM" | "SIGINT", listener: () => void): unknown;
+}
+
+interface GracefulShutdownLogger {
+  log: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+interface GracefulShutdownOptions {
+  /** The Bun.serve() return value (or anything shaped like it). */
+  server: ShutdownServer;
+  /** Cleanup fns run sequentially, in order, after the server stops accepting new work. */
+  cleanup: CleanupFn[];
+  /** Forces stop(true) + exit(1) if the graceful path hasn't finished by then. Default 20s. */
+  hardDeadlineMs?: number;
+  /** Defaults to the real `process.exit`. */
+  exit?: (code: number) => void;
+  /** Defaults to the real global `setTimeout`. Injectable so tests can trigger the deadline manually. */
+  setTimeoutFn?: (fn: () => void, ms: number) => unknown;
+  /** Defaults to the real global `clearTimeout`. */
+  clearTimeoutFn?: (handle: unknown) => void;
+  /** Defaults to the real `process`. Injectable so tests can fire signals without touching the real process. */
+  process?: SignalSource;
+  logger?: GracefulShutdownLogger;
+  /** Used only to prefix log lines, e.g. "admin", "task-store", "chat". */
+  serviceName?: string;
+}
+
+interface GracefulShutdown {
+  /** True once a shutdown signal has been received — gate readiness probes on this. */
+  isShuttingDown: () => boolean;
+}
+
+export function registerGracefulShutdown(
+  options: GracefulShutdownOptions,
+): GracefulShutdown {
+  const {
+    server,
+    cleanup,
+    hardDeadlineMs = DEFAULT_HARD_DEADLINE_MS,
+    exit = process.exit.bind(process),
+    // Wrapped (rather than assigned the raw global) so the interface can
+    // stay in terms of `unknown` for the timer handle without TypeScript
+    // narrowing these bindings to the global setTimeout/clearTimeout
+    // overloads' own parameter types.
+    setTimeoutFn = (fn: () => void, ms: number): unknown => setTimeout(fn, ms),
+    clearTimeoutFn = (handle: unknown): void =>
+      clearTimeout(handle as Parameters<typeof clearTimeout>[0]),
+    process: signalSource = process,
+    logger = console,
+    serviceName = "service",
+  } = options;
+
+  let shuttingDown = false;
+  let settled = false;
+
+  // Declared via `let` (not inline in the setTimeoutFn call) so a fake
+  // setTimeoutFn that invokes its callback synchronously never hits a
+  // temporal-dead-zone reference to this variable.
+  let deadlineHandle: unknown;
+
+  const finish = (code: number) => {
+    if (settled) return;
+    settled = true;
+    clearTimeoutFn(deadlineHandle);
+    exit(code);
+  };
+
+  const handleSignal = (signal: string) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    logger.log(`[${serviceName}] received ${signal}, shutting down gracefully`);
+
+    deadlineHandle = setTimeoutFn(() => {
+      logger.error(
+        `[${serviceName}] graceful shutdown exceeded ${hardDeadlineMs}ms — forcing stop`,
+      );
+      try {
+        server.stop(true);
+      } catch (err) {
+        logger.error(`[${serviceName}] error force-stopping server:`, err);
+      }
+      finish(1);
+    }, hardDeadlineMs);
+
+    void (async () => {
+      try {
+        await server.stop();
+      } catch (err) {
+        logger.error(`[${serviceName}] error stopping server:`, err);
+      }
+
+      for (const fn of cleanup) {
+        try {
+          await fn();
+        } catch (err) {
+          logger.error(`[${serviceName}] cleanup fn failed:`, err);
+        }
+      }
+
+      logger.log(`[${serviceName}] graceful shutdown complete`);
+      finish(0);
+    })();
+  };
+
+  signalSource.on("SIGTERM", () => handleSignal("SIGTERM"));
+  signalSource.on("SIGINT", () => handleSignal("SIGINT"));
+
+  return {
+    isShuttingDown: () => shuttingDown,
+  };
+}

package/graceful-shutdown.unit.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, test } from "bun:test";
+import { registerGracefulShutdown } from "./graceful-shutdown.ts";
+
+/** Records signal listeners without touching the real `process` object. */
+function fakeSignalSource() {
+  const listeners: Record<string, () => void> = {};
+  return {
+    on(event: "SIGTERM" | "SIGINT", listener: () => void) {
+      listeners[event] = listener;
+    },
+    listeners,
+  };
+}
+
+/** Fake server.stop() — records the `closeActiveConnections` arg per call and resolves immediately. */
+function fakeServer(calls: string[]) {
+  return {
+    stop(closeActiveConnections?: boolean) {
+      calls.push(closeActiveConnections ? "stop(true)" : "stop()");
+      return Promise.resolve();
+    },
+  };
+}
+
+/** Fake setTimeout — never fires on its own; the test triggers it manually via `fire()`. */
+function fakeTimeout() {
+  let scheduled: { fn: () => void; ms: number } | undefined;
+  return {
+    setTimeoutFn: (fn: () => void, ms: number) => {
+      scheduled = { fn, ms };
+      return "handle";
+    },
+    clearTimeoutFn: () => {
+      scheduled = undefined;
+    },
+    fire: () => scheduled?.fn(),
+    ms: () => scheduled?.ms,
+  };
+}
+
+/** Fake process.exit() that also resolves a promise so tests can await shutdown completion. */
+function fakeExit() {
+  const calls: number[] = [];
+  let resolve!: () => void;
+  const settled = new Promise<void>((r) => {
+    resolve = r;
+  });
+  return {
+    exit: (code: number) => {
+      calls.push(code);
+      resolve();
+    },
+    calls,
+    settled,
+  };
+}
+
+const NOOP_LOGGER = { log: () => {}, error: () => {} };
+
+/**
+ * Builds a fresh set of fakes and registers a shutdown handler against them.
+ * Every test shares this same wiring — only `cleanup` and `hardDeadlineMs`
+ * vary — so the fixture construction lives here once instead of being
+ * repeated per test.
+ */
+function harness(
+  overrides: {
+    cleanup?: Array<() => Promise<void>>;
+    hardDeadlineMs?: number;
+  } = {},
+) {
+  const calls: string[] = [];
+  const server = fakeServer(calls);
+  const signal = fakeSignalSource();
+  const timeout = fakeTimeout();
+  const exit = fakeExit();
+
+  const handle = registerGracefulShutdown({
+    server,
+    cleanup: overrides.cleanup ?? [async () => {}],
+    ...(overrides.hardDeadlineMs !== undefined
+      ? { hardDeadlineMs: overrides.hardDeadlineMs }
+      : {}),
+    process: signal,
+    setTimeoutFn: timeout.setTimeoutFn,
+    clearTimeoutFn: timeout.clearTimeoutFn,
+    exit: exit.exit,
+    logger: NOOP_LOGGER,
+  });
+
+  return { calls, signal, timeout, exit, handle };
+}
+
+describe("registerGracefulShutdown", () => {
+  test("calls server.stop() before running cleanup fns", async () => {
+    const { calls, signal, exit } = harness({
+      cleanup: [
+        async () => {
+          calls.push("cleanup:0");
+        },
+      ],
+    });
+
+    signal.listeners.SIGTERM();
+    await exit.settled;
+
+    expect(calls).toEqual(["stop()", "cleanup:0"]);
+  });
+
+  test("runs cleanup fns in the given order", async () => {
+    const { calls, signal, exit } = harness({
+      cleanup: [
+        async () => {
+          calls.push("cleanup:a");
+        },
+        async () => {
+          calls.push("cleanup:b");
+        },
+        async () => {
+          calls.push("cleanup:c");
+        },
+      ],
+    });
+
+    signal.listeners.SIGTERM();
+    await exit.settled;
+
+    expect(calls).toEqual(["stop()", "cleanup:a", "cleanup:b", "cleanup:c"]);
+  });
+
+  test("exits with code 0 on clean successful shutdown", async () => {
+    const { signal, exit } = harness();
+
+    signal.listeners.SIGTERM();
+    await exit.settled;
+
+    expect(exit.calls).toEqual([0]);
+  });
+
+  test("hard deadline forces server.stop(true) and exit(1) when cleanup never resolves", async () => {
+    const { calls, signal, timeout, exit } = harness({
+      cleanup: [
+        () =>
+          new Promise<void>(() => {
+            // never resolves — simulates a stuck cleanup fn
+          }),
+      ],
+      hardDeadlineMs: 20_000,
+    });
+
+    signal.listeners.SIGTERM();
+
+    // Let the graceful stop() + cleanup kick-off settle onto the stuck promise
+    // before manually firing the deadline (no real waiting involved).
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(timeout.ms()).toBe(20_000);
+    timeout.fire();
+    await exit.settled;
+
+    expect(calls).toContain("stop(true)");
+    expect(exit.calls).toEqual([1]);
+  });
+
+  test("a second SIGTERM after the first is a no-op", async () => {
+    const { calls, signal, exit } = harness({
+      cleanup: [
+        async () => {
+          calls.push("cleanup:0");
+        },
+      ],
+    });
+
+    signal.listeners.SIGTERM();
+    await exit.settled;
+
+    signal.listeners.SIGTERM();
+    // Flush microtasks so a (bugged) second invocation would have had a chance to run.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(calls).toEqual(["stop()", "cleanup:0"]);
+    expect(exit.calls).toEqual([0]);
+  });
+
+  test("SIGINT triggers the same shutdown sequence as SIGTERM", async () => {
+    const { calls, signal, exit } = harness({
+      cleanup: [
+        async () => {
+          calls.push("cleanup:0");
+        },
+      ],
+    });
+
+    signal.listeners.SIGINT();
+    await exit.settled;
+
+    expect(calls).toEqual(["stop()", "cleanup:0"]);
+    expect(exit.calls).toEqual([0]);
+  });
+
+  test("exposes a readable shuttingDown flag, set synchronously on signal", async () => {
+    const { signal, exit, handle } = harness();
+
+    expect(handle.isShuttingDown()).toBe(false);
+
+    signal.listeners.SIGTERM();
+
+    // True immediately, before the async stop/cleanup chain has settled.
+    expect(handle.isShuttingDown()).toBe(true);
+
+    await exit.settled;
+    expect(handle.isShuttingDown()).toBe(true);
+  });
+
+  test("a cleanup fn that throws does not prevent later cleanup fns or process.exit", async () => {
+    const { calls, signal, exit } = harness({
+      cleanup: [
+        async () => {
+          calls.push("cleanup:a");
+          throw new Error("boom");
+        },
+        async () => {
+          calls.push("cleanup:b");
+        },
+      ],
+    });
+
+    signal.listeners.SIGTERM();
+    await exit.settled;
+
+    expect(calls).toEqual(["stop()", "cleanup:a", "cleanup:b"]);
+    expect(exit.calls).toEqual([0]);
+  });
+});

package/http.ts

@@ -0,0 +1,14 @@
+/** Parses a request body as a JSON object, returning `{}` on any error or non-object shape. */
+export async function readJson(c: {
+  req: { json: () => Promise<unknown> };
+}): Promise<Record<string, unknown>> {
+  try {
+    const body = await c.req.json();
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+      return body as Record<string, unknown>;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}

package/http.unit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { readJson } from "./http.ts";
+
+describe("readJson — valid bodies", () => {
+  test("returns the parsed object when the body is a plain object", async () => {
+    const c = { req: { json: async () => ({ foo: "bar" }) } };
+    expect(await readJson(c)).toEqual({ foo: "bar" });
+  });
+
+  test("returns an empty object when the body is an empty object", async () => {
+    const c = { req: { json: async () => ({}) } };
+    expect(await readJson(c)).toEqual({});
+  });
+});
+
+describe("readJson — invalid bodies", () => {
+  test("returns {} when the body is an array", async () => {
+    const c = { req: { json: async () => [1, 2, 3] } };
+    expect(await readJson(c)).toEqual({});
+  });
+
+  test("returns {} when the body is a string primitive", async () => {
+    const c = { req: { json: async () => "not an object" } };
+    expect(await readJson(c)).toEqual({});
+  });
+
+  test("returns {} when the body is null", async () => {
+    const c = { req: { json: async () => null } };
+    expect(await readJson(c)).toEqual({});
+  });
+
+  test("returns {} when req.json() throws", async () => {
+    const c = {
+      req: {
+        json: async () => {
+          throw new Error("invalid JSON");
+        },
+      },
+    };
+    expect(await readJson(c)).toEqual({});
+  });
+});

package/org-repo.ts

@@ -0,0 +1,9 @@
+/** Returns true when `s` is a valid "org/repo" string with non-empty org and repo parts. */
+export function isOrgRepo(s: string): boolean {
+  const parts = s.split("/");
+  return (
+    parts.length === 2 &&
+    parts[0].trim().length > 0 &&
+    parts[1].trim().length > 0
+  );
+}

package/org-repo.unit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { isOrgRepo } from "./org-repo.ts";
+
+describe("isOrgRepo — valid strings", () => {
+  test("returns true for a simple org/repo string", () => {
+    expect(isOrgRepo("app-vitals/shipwright")).toBe(true);
+  });
+
+  test("returns true when org and repo contain hyphens and numbers", () => {
+    expect(isOrgRepo("my-org-1/my-repo-2")).toBe(true);
+  });
+});
+
+describe("isOrgRepo — invalid strings", () => {
+  test("returns false for a string with no slash", () => {
+    expect(isOrgRepo("shipwright")).toBe(false);
+  });
+
+  test("returns false for a string with more than one slash", () => {
+    expect(isOrgRepo("app-vitals/shipwright/extra")).toBe(false);
+  });
+
+  test("returns false when the org part is empty", () => {
+    expect(isOrgRepo("/shipwright")).toBe(false);
+  });
+
+  test("returns false when the repo part is empty", () => {
+    expect(isOrgRepo("app-vitals/")).toBe(false);
+  });
+
+  test("returns false when the org part is only whitespace", () => {
+    expect(isOrgRepo("   /shipwright")).toBe(false);
+  });
+
+  test("returns false when the repo part is only whitespace", () => {
+    expect(isOrgRepo("app-vitals/   ")).toBe(false);
+  });
+
+  test("returns false for an empty string", () => {
+    expect(isOrgRepo("")).toBe(false);
+  });
+});

package/package-exports.unit.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import pkg from "./package.json" with { type: "json" };
+
+describe("lib/package.json exports", () => {
+  for (const [subpath, target] of Object.entries(pkg.exports)) {
+    if (target.includes("*")) continue;
+    test(`${subpath} target exists on disk`, () => {
+      expect(existsSync(join(import.meta.dir, target))).toBe(true);
+    });
+  }
+
+  test("every non-wildcard export imports cleanly", async () => {
+    for (const [, target] of Object.entries(pkg.exports)) {
+      if (target.includes("*")) continue;
+      const mod = await import(join(import.meta.dir, target));
+      expect(typeof mod).toBe("object");
+    }
+  });
+});

package/package.json

@@ -1,8 +1,40 @@
 {
   "name": "@app-vitals/agent-lib",
-  "version": "0.0.1",
-  "description": "Placeholder reserving the package name. The real release is published from github.com/app-vitals/agent.",
+  "version": "0.1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/app-vitals/agent.git",
+    "directory": "lib"
+  },
   "license": "MIT",
-  "repository": {"type": "git", "url": "git+https://github.com/app-vitals/agent.git"},
-  "publishConfig": {"access": "public"}
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    "./admin-types": "./admin-types.ts",
+    "./chat-notify": "./chat-notify.ts",
+    "./claim-ttl": "./claim-ttl.ts",
+    "./claude-timeout": "./claude-timeout.ts",
+    "./cli-flags": "./cli-flags.ts",
+    "./clone-plan": "./clone-plan.ts",
+    "./github-login": "./github-login.ts",
+    "./graceful-shutdown": "./graceful-shutdown.ts",
+    "./http": "./http.ts",
+    "./org-repo": "./org-repo.ts",
+    "./pg-sslmode": "./pg-sslmode.ts",
+    "./pool-observability": "./pool-observability.ts",
+    "./pricing": "./pricing.ts",
+    "./progress-phases": "./progress-phases.ts",
+    "./request-context": "./request-context.ts",
+    "./secret-env-vars": "./secret-env-vars.ts",
+    "./default-account": "./default-account.ts",
+    "./default-agent-env": "./default-agent-env.ts",
+    "./sentry": "./sentry.ts",
+    "./task-store-types": "./task-store-types.ts",
+    "./web/*": "./web/*"
+  },
+  "dependencies": {
+    "@sentry/bun": "^10.63.0"
+  }
 }