@wardby/cli 0.3.0 → 0.4.1

package/dist/viewer/api-schema.js

@@ -0,0 +1,165 @@
+/**
+ * The admin viewer API's contract (docs/viewer-api.md). Every response and
+ * live event the API sends is defined here; build-schemas.ts publishes them as
+ * JSON Schema under src/viewer/schemas/, which the viewer app generates its
+ * types from (it never imports server source). Change a shape here, run
+ * `npm run build:viewer-schemas`, and commit the regenerated files.
+ */
+import { z } from "zod";
+export const RunStatusSchema = z.enum([
+    "pending",
+    "running",
+    "succeeded",
+    "failed",
+    "refused",
+    "lost",
+    "budget_exhausted",
+    "cancelled",
+]);
+/** What started a run, resolved for display. A sub-agent run's cause is its parent (parentRunId). */
+export const RunTriggerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("manual") }),
+    z.object({ kind: z.literal("scheduled"), schedule: z.string().nullable() }),
+    z.object({ kind: z.literal("webhook") }),
+    z.object({ kind: z.literal("subagent") }),
+    z.object({
+        kind: z.literal("code_host"),
+        provider: z.string(),
+        repository: z.string(),
+        number: z.number().int().nullable(),
+        event: z.enum(["review", "mention"]),
+    }),
+    z.object({ kind: z.literal("issue"), provider: z.string(), issueKey: z.string() }),
+    z.object({ kind: z.literal("host_event") }),
+]);
+/** When the outcome happened (PR opened, comment last updated, check completed); null while a check is pending. */
+const OutcomeAtSchema = z.string().nullable();
+export const OutcomeSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("pull_request"),
+        provider: z.string(),
+        repository: z.string(),
+        number: z.number().int(),
+        url: z.string(),
+        state: z.string().nullable(),
+        at: OutcomeAtSchema,
+    }),
+    z.object({
+        kind: z.literal("code_host_comment"),
+        provider: z.string(),
+        repository: z.string(),
+        number: z.number().int(),
+        at: OutcomeAtSchema,
+    }),
+    z.object({ kind: z.literal("issue_comment"), provider: z.string(), issueKey: z.string(), at: OutcomeAtSchema }),
+    z.object({
+        kind: z.literal("check"),
+        provider: z.string(),
+        repository: z.string(),
+        number: z.number().int().nullable(),
+        completed: z.boolean(),
+        at: OutcomeAtSchema,
+    }),
+]);
+export const ServiceStatusSchema = z.object({
+    name: z.string(),
+    state: z.enum(["pending", "probing", "ready", "failed"]),
+    attempts: z.number().int().nullable(),
+    reason: z.string().nullable(),
+    readyAt: z.string().nullable(),
+    failedAt: z.string().nullable(),
+    createdAt: z.string(),
+});
+export const GraphRunSchema = z.object({
+    id: z.string(),
+    parentRunId: z.string().nullable(),
+    agentId: z.string(),
+    agentName: z.string(),
+    agentKind: z.enum(["native", "coding"]),
+    /** The coding run's model, else the agent's. */
+    model: z.string(),
+    /** The coding worker (e.g. `codex`, `claude-code`); null for native runs. */
+    codingProvider: z.string().nullable(),
+    status: RunStatusSchema,
+    trigger: RunTriggerSchema,
+    turns: z.number().int(),
+    tokensIn: z.number().int(),
+    tokensOut: z.number().int(),
+    costUsd: z.number(),
+    budgetUsd: z.number(),
+    startedAt: z.string(),
+    finishedAt: z.string().nullable(),
+    heartbeatAt: z.string().nullable(),
+    outcomes: z.array(OutcomeSchema),
+    /** The services a coding run was started with, recorded or not; empty for native runs. */
+    declaredServices: z.array(z.object({ name: z.string(), version: z.string() })),
+    /** Recorded readiness of the run's services (none before status tracking existed). */
+    services: z.array(ServiceStatusSchema),
+});
+export const BudgetGroupSpendSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    dailyBudgetUsd: z.number().nullable(),
+    spentTodayUsd: z.number(),
+});
+export const GraphSnapshotSchema = z.object({
+    generatedAt: z.string(),
+    since: z.string(),
+    limit: z.number().int(),
+    truncated: z.boolean(),
+    runs: z.array(GraphRunSchema),
+    spend: z.object({ todayUsd: z.number(), groups: z.array(BudgetGroupSpendSchema) }),
+});
+export const RunDetailSchema = GraphRunSchema.extend({
+    error: z.string().nullable(),
+    finalText: z.string().nullable(),
+    childRunIds: z.array(z.string()),
+    coding: z
+        .object({
+        provider: z.string(),
+        repository: z.string(),
+        baseRef: z.string(),
+        headRef: z.string(),
+        queuedAt: z.string().nullable(),
+        failureCategory: z.string().nullable(),
+        services: z.array(z.object({
+            name: z.string(),
+            version: z.string(),
+            image: z.string(),
+            envNames: z.array(z.string()),
+        })),
+    })
+        .nullable(),
+});
+export const ViewerEventSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("run"),
+        runId: z.string(),
+        parentRunId: z.string().nullable(),
+        agentId: z.string(),
+        status: RunStatusSchema,
+        turns: z.number().int(),
+        tokensIn: z.number().int(),
+        tokensOut: z.number().int(),
+        costUsd: z.number(),
+        finishedAt: z.string().nullable(),
+    }),
+    z.object({
+        kind: z.literal("service"),
+        runId: z.string(),
+        name: z.string(),
+        state: z.enum(["pending", "probing", "ready", "failed"]),
+        attempts: z.number().int().nullable(),
+    }),
+    z.object({
+        kind: z.literal("outcome"),
+        runId: z.string(),
+        /** Which table changed (the viewer NOTIFY trigger names them). */
+        source: z.enum(["pull_request", "host_status", "issue_status", "host_check"]),
+    }),
+]);
+export const VIEWER_SCHEMAS = {
+    "graph-snapshot": GraphSnapshotSchema,
+    "run-detail": RunDetailSchema,
+    "viewer-event": ViewerEventSchema,
+};

package/dist/viewer/build-schemas.d.ts

@@ -0,0 +1,2 @@
+export declare const SCHEMA_DIR: string;
+export declare function renderSchemas(): Record<string, string>;

package/dist/viewer/build-schemas.js

@@ -0,0 +1,18 @@
+/** Writes src/viewer/schemas/<name>.schema.json from VIEWER_SCHEMAS (npm run build:viewer-schemas). */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { VIEWER_SCHEMAS } from "./api-schema.js";
+export const SCHEMA_DIR = join(dirname(fileURLToPath(import.meta.url)), "schemas");
+export function renderSchemas() {
+    return Object.fromEntries(Object.entries(VIEWER_SCHEMAS).map(([name, schema]) => [
+        `${name}.schema.json`,
+        `${JSON.stringify(zodToJsonSchema(schema, { name, $refStrategy: "none" }), null, 2)}\n`,
+    ]));
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    await mkdir(SCHEMA_DIR, { recursive: true });
+    for (const [file, text] of Object.entries(renderSchemas()))
+        await writeFile(join(SCHEMA_DIR, file), text);
+}

package/dist/viewer/event-bus.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Viewer event bus: one raw Postgres connection per server replica that LISTENs
+ * on `wardby_viewer` (fed by the viewer NOTIFY triggers) and fans events out to
+ * in-process subscribers (the SSE layer).
+ *
+ * - Lazy: no connection until the first subscriber; closed when the last leaves.
+ * - Resilient: Cloud SQL maintenance and proxy restarts drop idle connections,
+ *   so the client uses TCP keepAlive (probing after 30 s idle) and a periodic
+ *   `SELECT 1` health check that catches a half-open socket; on error, end or a
+ *   failed check while anyone is subscribed, it reconnects on a backoff
+ *   schedule and re-LISTENs.
+ * - Subscribers are not told about gaps directly; `onState` reports every
+ *   transition to live (including the first LISTEN) and to down, so the SSE
+ *   layer can tell its clients to refetch whatever they may have missed.
+ */
+import pg from "pg";
+import { type ViewerEvent } from "./api-schema.js";
+export declare const VIEWER_CHANNEL = "wardby_viewer";
+export interface ViewerEventBus {
+    subscribe(listener: (event: ViewerEvent) => void): () => void;
+    /** True while the LISTEN connection is up (for the SSE "live" indicator). */
+    connected(): boolean;
+    /**
+     * Fires on every transition of the LISTEN connection: `true` once it is up
+     * and listening (the first connect and every reconnect), `false` when it is
+     * lost. Events between the last `false` (or subscribing) and `true` may
+     * have been missed.
+     */
+    onState(listener: (live: boolean) => void): () => void;
+    close(): Promise<void>;
+}
+export declare function createViewerEventBus(options: {
+    connectionString: string;
+    connect?: (connectionString: string) => pg.Client;
+    reconnectDelaysMs?: readonly number[];
+    healthCheckIntervalMs?: number;
+    healthCheckTimeoutMs?: number;
+}): ViewerEventBus;

package/dist/viewer/event-bus.js

@@ -0,0 +1,232 @@
+/**
+ * Viewer event bus: one raw Postgres connection per server replica that LISTENs
+ * on `wardby_viewer` (fed by the viewer NOTIFY triggers) and fans events out to
+ * in-process subscribers (the SSE layer).
+ *
+ * - Lazy: no connection until the first subscriber; closed when the last leaves.
+ * - Resilient: Cloud SQL maintenance and proxy restarts drop idle connections,
+ *   so the client uses TCP keepAlive (probing after 30 s idle) and a periodic
+ *   `SELECT 1` health check that catches a half-open socket; on error, end or a
+ *   failed check while anyone is subscribed, it reconnects on a backoff
+ *   schedule and re-LISTENs.
+ * - Subscribers are not told about gaps directly; `onState` reports every
+ *   transition to live (including the first LISTEN) and to down, so the SSE
+ *   layer can tell its clients to refetch whatever they may have missed.
+ */
+import pg from "pg";
+import { poolSettings } from "../core/db.js";
+import { logger } from "../core/logger.js";
+import { ViewerEventSchema } from "./api-schema.js";
+export const VIEWER_CHANNEL = "wardby_viewer";
+const DEFAULT_RECONNECT_DELAYS_MS = [500, 1000, 2000, 5000, 10_000];
+const WARN_INTERVAL_MS = 60_000;
+const KEEPALIVE_INITIAL_DELAY_MS = 30_000;
+const DEFAULT_HEALTH_CHECK_INTERVAL_MS = 60_000;
+const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 10_000;
+/** Upper bound on waiting for a graceful disconnect (a half-open socket never answers). */
+const END_TIMEOUT_MS = 2_000;
+export function createViewerEventBus(options) {
+    const healthIntervalMs = options.healthCheckIntervalMs ?? DEFAULT_HEALTH_CHECK_INTERVAL_MS;
+    const healthTimeoutMs = options.healthCheckTimeoutMs ?? DEFAULT_HEALTH_CHECK_TIMEOUT_MS;
+    const delays = options.reconnectDelaysMs?.length ? options.reconnectDelaysMs : DEFAULT_RECONNECT_DELAYS_MS;
+    const makeClient = options.connect ??
+        ((connectionString) => new pg.Client({
+            connectionString,
+            keepAlive: true,
+            keepAliveInitialDelayMillis: KEEPALIVE_INITIAL_DELAY_MS,
+            connectionTimeoutMillis: poolSettings(connectionString).connectionTimeoutMillis,
+        }));
+    const listeners = new Set();
+    const stateListeners = new Set();
+    let client = null; // the current attempt/connection
+    let isUp = false;
+    let closed = false;
+    let dropped = false; // a connection was lost (or failed) in this session
+    let attempt = 0;
+    let timer = null;
+    let healthTimer = null;
+    const lastWarn = new Map();
+    function warnThrottled(key, message, extra = {}) {
+        const now = Date.now();
+        if (now - (lastWarn.get(key) ?? -Infinity) < WARN_INTERVAL_MS)
+            return;
+        lastWarn.set(key, now);
+        logger.warn(extra, message);
+    }
+    function dispatch(payload) {
+        let parsed;
+        try {
+            parsed = JSON.parse(payload ?? "");
+        }
+        catch {
+            warnThrottled("invalid", "viewer event bus dropped a non-JSON notification");
+            return;
+        }
+        const result = ViewerEventSchema.safeParse(parsed);
+        if (!result.success) {
+            warnThrottled("invalid", "viewer event bus dropped an invalid notification");
+            return;
+        }
+        for (const listener of [...listeners]) {
+            try {
+                listener(result.data);
+            }
+            catch (err) {
+                warnThrottled("listener", "viewer event bus listener threw", { err });
+            }
+        }
+    }
+    function setLive(live) {
+        if (isUp === live)
+            return;
+        isUp = live;
+        for (const l of [...stateListeners]) {
+            try {
+                l(live);
+            }
+            catch (err) {
+                warnThrottled("listener", "viewer event bus state listener threw", { err });
+            }
+        }
+    }
+    /** Disconnect, bounded: `end()` waits for the server, which a half-open socket never answers. */
+    function endClient(c) {
+        // Never leave a client without an error handler: late errors must not crash.
+        c.on("error", () => { });
+        let bound;
+        return Promise.race([
+            c.end().catch(() => { }),
+            new Promise((resolve) => {
+                bound = setTimeout(resolve, END_TIMEOUT_MS);
+                bound.unref();
+            }),
+        ]).finally(() => clearTimeout(bound));
+    }
+    function discard(c) {
+        void endClient(c);
+    }
+    function stopHealthCheck() {
+        if (healthTimer)
+            clearInterval(healthTimer);
+        healthTimer = null;
+    }
+    /** Periodically prove the LISTEN connection still reaches the server. */
+    function startHealthCheck(c) {
+        stopHealthCheck();
+        let inFlight = false;
+        healthTimer = setInterval(() => {
+            if (inFlight || c !== client)
+                return;
+            inFlight = true;
+            let deadline;
+            Promise.race([
+                c.query("SELECT 1"),
+                new Promise((_, reject) => {
+                    deadline = setTimeout(() => reject(new Error("viewer event bus health check timed out")), healthTimeoutMs);
+                    deadline.unref();
+                }),
+            ])
+                .then(() => { }, (err) => drop(c, err))
+                .finally(() => {
+                clearTimeout(deadline);
+                inFlight = false;
+            });
+        }, healthIntervalMs);
+        healthTimer.unref();
+    }
+    function scheduleReconnect() {
+        if (closed || listeners.size === 0 || timer || client)
+            return;
+        const delay = delays[Math.min(attempt, delays.length - 1)];
+        attempt++;
+        timer = setTimeout(() => {
+            timer = null;
+            open();
+        }, delay);
+        timer.unref();
+    }
+    function drop(c, err) {
+        if (c !== client)
+            return; // stale: already replaced or stopped
+        client = null;
+        stopHealthCheck();
+        dropped = true;
+        warnThrottled("connection", "viewer event bus connection lost", err ? { err } : {});
+        setLive(false);
+        discard(c);
+        scheduleReconnect();
+    }
+    function open() {
+        if (closed || client || timer || listeners.size === 0)
+            return;
+        const c = makeClient(options.connectionString);
+        client = c;
+        c.on("notification", (msg) => {
+            if (c === client && msg.channel === VIEWER_CHANNEL)
+                dispatch(msg.payload);
+        });
+        c.on("error", (err) => drop(c, err));
+        c.on("end", () => drop(c));
+        void (async () => {
+            try {
+                await c.connect();
+                if (c !== client)
+                    return discard(c); // stopped while connecting
+                await c.query(`LISTEN ${VIEWER_CHANNEL}`);
+                if (c !== client)
+                    return discard(c);
+            }
+            catch (err) {
+                return drop(c, err);
+            }
+            attempt = 0;
+            if (dropped) {
+                dropped = false;
+                logger.info({ channel: VIEWER_CHANNEL }, "viewer event bus reconnected");
+            }
+            startHealthCheck(c);
+            setLive(true);
+        })();
+    }
+    /** Tear down the connection and any pending reconnect. */
+    async function stop() {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        stopHealthCheck();
+        const c = client;
+        client = null;
+        dropped = false;
+        attempt = 0;
+        setLive(false);
+        if (c)
+            await endClient(c);
+    }
+    return {
+        subscribe(listener) {
+            if (closed)
+                return () => { };
+            listeners.add(listener);
+            open();
+            return () => {
+                if (!listeners.delete(listener))
+                    return;
+                if (listeners.size === 0)
+                    void stop();
+            };
+        },
+        connected: () => isUp,
+        onState(listener) {
+            stateListeners.add(listener);
+            return () => {
+                stateListeners.delete(listener);
+            };
+        },
+        async close() {
+            closed = true;
+            listeners.clear();
+            stateListeners.clear();
+            await stop();
+        },
+    };
+}

package/dist/viewer/graph.d.ts

@@ -0,0 +1,40 @@
+/** The graph snapshot read model behind GET /admin/api/graph (docs/viewer-api.md). */
+import type { Prisma, PrismaClient } from "#prisma";
+import type { GraphRun, GraphSnapshot } from "./api-schema.js";
+export declare const DEFAULT_GRAPH_LIMIT = 500;
+export declare const MAX_GRAPH_LIMIT = 2000;
+/** Accepts "15m" | "1h" | "6h" | "24h" | "7d" or an ISO-8601 timestamp; null defaults to 1h. Throws otherwise. */
+export declare function parseSince(value: string | null, now: Date): Date;
+declare const runInclude: {
+    agent: true;
+    codingRun: {
+        select: {
+            result: true;
+            provider: true;
+            model: true;
+            services: true;
+        };
+    };
+    hostCheck: true;
+    hostStatus: true;
+    issueStatus: true;
+    serviceStatuses: {
+        orderBy: {
+            createdAt: "asc";
+        };
+    };
+};
+type RunRow = Prisma.RunGetPayload<{
+    include: typeof runInclude;
+}>;
+type PullRequestRow = Prisma.IssuePullRequestGetPayload<object>;
+/** The one row -> GraphRun mapping (also used by run detail). `pullRequests` are the IssuePullRequest rows this run opened. */
+export declare function toGraphRun(row: RunRow, pullRequests: readonly PullRequestRow[]): GraphRun;
+/** Loads the given runs as GraphRuns (shared with run detail); unknown ids are skipped. */
+export declare function loadGraphRuns(db: PrismaClient, runIds: readonly string[]): Promise<GraphRun[]>;
+export declare function loadGraph(db: PrismaClient, options: {
+    since: Date;
+    limit: number;
+    now?: Date;
+}): Promise<GraphSnapshot>;
+export {};