@app-vitals/agent-lib 0.0.0-stage → 0.1.0

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/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.json

@@ -1,6 +1,41 @@
 {
   "name": "@app-vitals/agent-lib",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/app-vitals/agent.git",
+    "directory": "lib"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    "./admin-types": "./admin-types.ts",
+    "./agent-default-tools": "./agent-default-tools.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"
+  }
+}

package/pg-sslmode.ts

@@ -0,0 +1,66 @@
+/**
+ * lib/pg-sslmode.ts
+ *
+ * Pins node-postgres's TLS behavior for a Postgres connection string.
+ *
+ * `pg` 8.x (via pg-connection-string 2.x) treats `sslmode=prefer`, `require`,
+ * and `verify-ca` as aliases for `verify-full` — the server certificate chain
+ * and hostname are both verified — and logs a SECURITY WARNING saying the next
+ * major (pg 9 / pg-connection-string 3) will switch them to libpq semantics,
+ * where `require` means "encrypt, verify nothing". Upgrading `pg` would then
+ * silently drop certificate verification for every deployment whose URL says
+ * `sslmode=require`.
+ *
+ * Rewriting those modes to `verify-full` in the string handed to `pg` keeps
+ * today's (verifying) behavior across that upgrade and silences the warning.
+ * It is applied only to the `pg.Pool` connection string — never to the env var
+ * itself — because the same URL is also read by the Prisma CLI
+ * (`prisma migrate deploy` via prisma.config.ts), whose engine recognises only
+ * `disable|prefer|require` and would read `verify-full` as `prefer`.
+ *
+ * Left untouched:
+ *   - URLs with no `sslmode`, or `disable` / `verify-full` / `no-verify`
+ *     (none of them warn, and none change meaning in pg 9);
+ *   - URLs that set `uselibpqcompat=true`: that is an explicit opt-in to libpq
+ *     semantics, which this must not override;
+ *   - strings that are not parseable as a URL (pg accepts other forms; pass
+ *     them through for pg to handle or reject).
+ */
+
+/** The sslmode values pg 8 aliases to `verify-full` (and warns about). */
+const LEGACY_VERIFY_FULL_ALIASES = new Set(["prefer", "require", "verify-ca"]);
+
+/**
+ * Returns `connectionString` with a legacy `sslmode` alias replaced by
+ * `verify-full`, or the input unchanged when no rewrite applies.
+ */
+export function pinPgSslMode(connectionString: string): string {
+  let url: URL;
+  try {
+    url = new URL(connectionString);
+  } catch {
+    return connectionString;
+  }
+
+  // Resolve the effective `sslmode` the same way pg-connection-string's
+  // parse() does: iterate every query param in document order and let later
+  // entries overwrite earlier ones (`config[entry[0]] = entry[1]`). A
+  // duplicate `sslmode` therefore resolves to its LAST occurrence — not the
+  // first, which is what `URLSearchParams#get()` would return — so this must
+  // not use `.get()` here.
+  let sslmode: string | null = null;
+  for (const [key, value] of url.searchParams) {
+    if (key === "sslmode") {
+      sslmode = value;
+    }
+  }
+  if (sslmode === null || !LEGACY_VERIFY_FULL_ALIASES.has(sslmode)) {
+    return connectionString;
+  }
+  if (url.searchParams.get("uselibpqcompat") === "true") {
+    return connectionString;
+  }
+
+  url.searchParams.set("sslmode", "verify-full");
+  return url.toString();
+}

package/pg-sslmode.unit.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { pinPgSslMode } from "./pg-sslmode.ts";
+
+const BASE = "postgresql://user:pass@db.example.test:5432/app";
+
+describe("pinPgSslMode — legacy aliases are pinned to verify-full", () => {
+  for (const mode of ["prefer", "require", "verify-ca"]) {
+    test(`rewrites sslmode=${mode} to sslmode=verify-full`, () => {
+      const pinned = new URL(pinPgSslMode(`${BASE}?sslmode=${mode}`));
+      expect(pinned.searchParams.get("sslmode")).toBe("verify-full");
+    });
+  }
+
+  test("preserves credentials, host, database, and other params", () => {
+    const pinned = new URL(
+      pinPgSslMode(`${BASE}?connection_limit=5&sslmode=require&schema=public`),
+    );
+    expect(pinned.username).toBe("user");
+    expect(pinned.password).toBe("pass");
+    expect(pinned.host).toBe("db.example.test:5432");
+    expect(pinned.pathname).toBe("/app");
+    expect(pinned.searchParams.get("connection_limit")).toBe("5");
+    expect(pinned.searchParams.get("schema")).toBe("public");
+  });
+
+  test("keeps a URL-encoded password byte-for-byte when rewriting", () => {
+    const pinned = pinPgSslMode(
+      "postgresql://user:p%40ss%2Fw@localhost:5432/app?sslmode=require",
+    );
+    expect(pinned).toBe(
+      "postgresql://user:p%40ss%2Fw@localhost:5432/app?sslmode=verify-full",
+    );
+  });
+
+  test("a duplicate sslmode resolves to the LAST occurrence, like pg-connection-string", () => {
+    // pg-connection-string's parse() iterates every query param and lets
+    // later entries overwrite earlier ones, so `pg` itself connects using
+    // the second `sslmode` here ("require"), not the first ("verify-full").
+    // Using URLSearchParams#get() (first-match) would wrongly see
+    // "verify-full" and skip the rewrite, leaving the string's final
+    // sslmode as the unrewritten legacy "require".
+    const pinned = new URL(
+      pinPgSslMode(`${BASE}?sslmode=verify-full&sslmode=require`),
+    );
+    expect(pinned.searchParams.getAll("sslmode")).toEqual(["verify-full"]);
+  });
+});
+
+describe("pinPgSslMode — inputs left untouched", () => {
+  test("a URL with no sslmode", () => {
+    expect(pinPgSslMode(BASE)).toBe(BASE);
+  });
+
+  for (const mode of ["disable", "verify-full", "no-verify"]) {
+    test(`sslmode=${mode}`, () => {
+      const input = `${BASE}?sslmode=${mode}`;
+      expect(pinPgSslMode(input)).toBe(input);
+    });
+  }
+
+  test("an explicit uselibpqcompat=true opt-in", () => {
+    const input = `${BASE}?uselibpqcompat=true&sslmode=require`;
+    expect(pinPgSslMode(input)).toBe(input);
+  });
+
+  test("a string that is not a URL", () => {
+    expect(pinPgSslMode("not a url")).toBe("not a url");
+  });
+
+  test("a URL-encoded password survives unchanged when no rewrite applies", () => {
+    const input = "postgresql://user:p%40ss%2Fw@localhost:5432/app";
+    expect(pinPgSslMode(input)).toBe(input);
+  });
+});

package/pool-observability.ts

@@ -0,0 +1,209 @@
+/**
+ * lib/pool-observability.ts
+ * Observability helpers for diagnosing pg pool starvation (Sentry SENTRY-5T).
+ *
+ * Observability only: nothing here changes pool or client behavior. Types are
+ * structural so this module needs no direct dependency on `pg` or `hono`.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Minimal Clock (matches the Clock interface used across services). */
+export interface Clock {
+  now(): Date;
+}
+
+export interface PoolLike {
+  totalCount: number;
+  idleCount: number;
+  waitingCount: number;
+  options?: { max?: number };
+}
+
+export interface PoolSnapshot {
+  total: number;
+  idle: number;
+  waiting: number;
+  max: number | null;
+}
+
+export type PoolLog = (message: string, data?: Record<string, unknown>) => void;
+
+type ReleaseFn = (err?: Error | boolean) => void;
+
+export interface CheckoutPool extends PoolLike {
+  // biome-ignore lint/suspicious/noExplicitAny: matches pg's overloaded connect()
+  connect: (...args: any[]) => any;
+}
+
+const systemClock: Clock = { now: () => new Date() };
+
+// ─── Snapshot / error detection ───────────────────────────────────────────────
+
+export function snapshotPool(pool: PoolLike): PoolSnapshot {
+  return {
+    total: pool.totalCount,
+    idle: pool.idleCount,
+    waiting: pool.waitingCount,
+    max: pool.options?.max ?? null,
+  };
+}
+
+/** True for Prisma P2028, "Unable to start a transaction", or pg connection timeouts. */
+export function isPoolTimeoutError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const { code, message } = err as { code?: unknown; message?: unknown };
+  if (code === "P2028") return true;
+  if (typeof message !== "string") return false;
+  return (
+    message.includes("Unable to start a transaction") ||
+    /timeout exceeded when trying to connect/i.test(message) ||
+    /connection timeout/i.test(message)
+  );
+}
+
+// ─── Monitor ──────────────────────────────────────────────────────────────────
+
+export interface PoolMonitorOptions {
+  intervalMs?: number;
+  log?: PoolLog;
+  setInterval?: (fn: () => void, ms: number) => unknown;
+  clearInterval?: (handle: unknown) => void;
+}
+
+/** Periodically logs the pool snapshot, only while clients are waiting. Returns a stop fn. */
+export function startPoolMonitor(
+  pool: PoolLike,
+  opts: PoolMonitorOptions = {},
+): () => void {
+  const {
+    intervalMs = 30_000,
+    log = (m, d) => console.warn(m, d),
+    setInterval: setIntervalFn = (fn, ms) => setInterval(fn, ms),
+    clearInterval: clearIntervalFn = (h) =>
+      clearInterval(h as ReturnType<typeof setInterval>),
+  } = opts;
+  const handle = setIntervalFn(() => {
+    const snap = snapshotPool(pool);
+    if (snap.waiting > 0) log("pg pool has waiting clients", { ...snap });
+  }, intervalMs);
+  return () => clearIntervalFn(handle);
+}
+
+// ─── Route context ────────────────────────────────────────────────────────────
+
+export interface RouteContext {
+  method: string;
+  route: string;
+}
+
+const routeStorage = new AsyncLocalStorage<RouteContext>();
+
+export function runWithRouteContext<T>(ctx: RouteContext, fn: () => T): T {
+  return routeStorage.run(ctx, fn);
+}
+
+export function currentRouteContext(): RouteContext | undefined {
+  return routeStorage.getStore();
+}
+
+interface HonoLikeContext {
+  req: {
+    method: string;
+    path: string;
+    matchedRoutes?: { path: string }[];
+  };
+}
+
+/**
+ * Hono middleware factory recording the request method and matched route
+ * pattern. The pattern is resolved lazily (at read time) so it reflects the
+ * handler route rather than the wildcard this middleware is mounted on.
+ */
+export function routeContextMiddleware() {
+  return async (c: HonoLikeContext, next: () => Promise<void>) => {
+    const ctx: RouteContext = {
+      method: c.req.method,
+      get route() {
+        const matched = c.req.matchedRoutes;
+        return matched?.length
+          ? (matched[matched.length - 1] as { path: string }).path
+          : c.req.path;
+      },
+    };
+    await runWithRouteContext(ctx, next);
+  };
+}
+
+// ─── Connection hold tracking ─────────────────────────────────────────────────
+
+export interface TrackHoldOptions {
+  thresholdMs?: number;
+  log?: PoolLog;
+  clock?: Clock;
+}
+
+/**
+ * Wraps `pool.connect()` so each checked-out client's `release` logs when the
+ * connection was held longer than `thresholdMs`. Release semantics are
+ * preserved exactly: args are forwarded untouched and the underlying release
+ * is invoked on every call (so pg's own double-release error still surfaces).
+ * Returns a function restoring the original `connect`.
+ */
+export function trackConnectionHold(
+  pool: CheckoutPool,
+  opts: TrackHoldOptions = {},
+): () => void {
+  const {
+    thresholdMs = 2000,
+    log = (m, d) => console.warn(m, d),
+    clock = systemClock,
+  } = opts;
+  const originalConnect = pool.connect;
+
+  const wrap = (client: { release: ReleaseFn }) => {
+    const checkedOutAt = clock.now().getTime();
+    const route = currentRouteContext();
+    const originalRelease = client.release;
+    let reported = false;
+    client.release = function (this: unknown, ...args: [(Error | boolean)?]) {
+      if (!reported) {
+        reported = true;
+        const heldMs = clock.now().getTime() - checkedOutAt;
+        if (heldMs > thresholdMs) {
+          log("pg connection held past threshold", {
+            route: route ? `${route.method} ${route.route}` : null,
+            heldMs,
+            pool: snapshotPool(pool),
+          });
+        }
+      }
+      return originalRelease.apply(client, args);
+    } as ReleaseFn;
+    return client;
+  };
+
+  pool.connect = function (this: unknown, ...args: unknown[]) {
+    const result = originalConnect.apply(pool, args);
+    // Callback-style connect(cb) is passed through untracked.
+    if (typeof args[0] === "function") return result;
+    return (result as Promise<{ release: ReleaseFn }>).then(wrap);
+  };
+
+  return () => {
+    pool.connect = originalConnect;
+  };
+}
+
+// ─── Sentry context ───────────────────────────────────────────────────────────
+
+/** Object to attach to Sentry events (e.g. `scope.setContext("pg_pool", ...)`). */
+export function poolErrorContext(pool: PoolLike): Record<string, unknown> {
+  const route = currentRouteContext();
+  return {
+    ...snapshotPool(pool),
+    route: route ? `${route.method} ${route.route}` : null,
+  };
+}