@shaferllc/keel 0.66.0 → 0.74.0

package/dist/watch/migration.js

@@ -0,0 +1,20 @@
+/**
+ * The `watch_entries` table. Contributed by the provider via `this.migrations()`
+ * and run by `keel migrate` alongside the app's own — the same path any package
+ * ships schema on.
+ */
+export function watchMigration(table = "watch_entries") {
+    return {
+        name: `watch_00_create_${table}`,
+        up: (schema) => schema.createTable(table, (t) => {
+            t.string("uuid").unique();
+            t.string("batch_id");
+            t.string("type", 32);
+            t.string("family_hash").nullable();
+            t.text("content");
+            t.text("tags");
+            t.bigInteger("created_at");
+        }),
+        down: (schema) => schema.dropTable(table),
+    };
+}

package/dist/watch/provider.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Keel Watch — a Telescope-style debug dashboard, shipped as a Keel package.
+ *
+ * One line in `bootstrap/providers.ts` turns it on:
+ *   app.register(WatchServiceProvider)
+ *
+ * It's the reference consumer of the package system: it merges its own config,
+ * contributes a migration, mounts routes and a bundled SPA, and adds a console
+ * command — all through `PackageProvider` helpers, touching no framework
+ * internals. The watchers observe the instrumentation event stream; they patch
+ * nothing, so installing Watch changes no behaviour, only visibility.
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class WatchServiceProvider extends PackageProvider {
+    readonly name = "watch";
+    private config;
+    private store;
+    private teardown?;
+    register(): void;
+    boot(): void;
+    shutdown(): void;
+}

package/dist/watch/provider.js

@@ -0,0 +1,58 @@
+/**
+ * Keel Watch — a Telescope-style debug dashboard, shipped as a Keel package.
+ *
+ * One line in `bootstrap/providers.ts` turns it on:
+ *   app.register(WatchServiceProvider)
+ *
+ * It's the reference consumer of the package system: it merges its own config,
+ * contributes a migration, mounts routes and a bundled SPA, and adds a console
+ * command — all through `PackageProvider` helpers, touching no framework
+ * internals. The watchers observe the instrumentation event stream; they patch
+ * nothing, so installing Watch changes no behaviour, only visibility.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PackageProvider } from "../core/package.js";
+import { resolveConfig, defaultConfig } from "./config.js";
+import { MemoryStore, DatabaseStore } from "./store.js";
+import { watchMigration } from "./migration.js";
+import { Recorder } from "./recorder.js";
+import { installWatchers } from "./watchers.js";
+import { registerWatchRoutes } from "./routes.js";
+import { pruneCommand } from "./prune.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export class WatchServiceProvider extends PackageProvider {
+    name = "watch";
+    config;
+    store;
+    teardown;
+    register() {
+        this.mergeConfig("watch", defaultConfig);
+        this.config = resolveConfig();
+        this.store =
+            this.config.storage === "memory"
+                ? new MemoryStore(this.config.limit * 10)
+                : new DatabaseStore(this.config.table, this.config.connection);
+        // Schema (run by `keel migrate`), a publishable config stub, and the CLI.
+        this.migrations([watchMigration(this.config.table)]);
+        this.publishes({ [join(here, "watch.config.stub")]: "config/watch.ts" }, "watch-config");
+        this.commands([pruneCommand(this.store, this.config)]);
+    }
+    boot() {
+        if (!this.config.enabled)
+            return;
+        // Observe the instrumentation stream.
+        this.teardown = installWatchers(new Recorder(this.store, this.config), this.config);
+        // Serve the dashboard: the bundled SPA, the JSON API, and the shell.
+        const base = "/" + this.config.path.replace(/^\/|\/$/g, "");
+        const assetsUrl = `${base}/assets`;
+        this.assets(`${this.config.path}/assets`, join(here, "ui/dist"), { maxAge: 3600 });
+        this.routes((r) => registerWatchRoutes(r, this.store, this.config, { base, assetsUrl }), {
+            prefix: this.config.path,
+            as: "watch",
+        });
+    }
+    shutdown() {
+        this.teardown?.();
+    }
+}

package/dist/watch/prune.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `keel watch:prune` — drop entries past the retention window. Contributed as a
+ * package command; schedule it (or run it from cron) to keep the table small.
+ * Note it only reaches persisted storage: with the in-memory store the ring
+ * buffer bounds itself per process, so there's nothing for a separate CLI
+ * process to prune.
+ */
+import type { PackageCommand } from "../core/package.js";
+import type { EntryStore } from "./store.js";
+import type { WatchConfig } from "./config.js";
+export declare function pruneCommand(store: EntryStore, config: WatchConfig): PackageCommand;

package/dist/watch/prune.js

@@ -0,0 +1,20 @@
+/**
+ * `keel watch:prune` — drop entries past the retention window. Contributed as a
+ * package command; schedule it (or run it from cron) to keep the table small.
+ * Note it only reaches persisted storage: with the in-memory store the ring
+ * buffer bounds itself per process, so there's nothing for a separate CLI
+ * process to prune.
+ */
+export function pruneCommand(store, config) {
+    return {
+        name: "watch:prune",
+        description: "Delete Watch entries older than the retention window",
+        configure: (cmd) => cmd.option("--hours <hours>", "override the retention window (hours)"),
+        action: async (opts) => {
+            const hours = opts.hours ? Number(opts.hours) : config.retentionHours;
+            const before = Date.now() - hours * 3_600_000;
+            const removed = await store.prune(before);
+            console.log(`Pruned ${removed} Watch entr${removed === 1 ? "y" : "ies"} older than ${hours}h.`);
+        },
+    };
+}

package/dist/watch/recorder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The recorder turns a watcher's observation into a stored `Entry`. It applies
+ * the config gates (enabled, per-type toggle, sampling), stamps the entry with
+ * the current request/batch id, makes the content JSON-safe, and persists it —
+ * fire-and-forget, so recording never blocks or breaks the thing it's watching.
+ */
+import type { EntryType } from "./entry.js";
+import type { EntryStore } from "./store.js";
+import type { WatchConfig } from "./config.js";
+export interface RecordOptions {
+    /** Force the batch id (else the current request id, else a fresh one). */
+    batchId?: string;
+    /** Group this entry with like ones. */
+    familyHash?: string;
+}
+export declare class Recorder {
+    private store;
+    private config;
+    constructor(store: EntryStore, config: WatchConfig);
+    /** Whether a given entry type should be recorded at all. */
+    enabledFor(type: EntryType): boolean;
+    /** Record one entry. A no-op when the type is disabled or sampled out. */
+    record(type: EntryType, content: Record<string, unknown>, tags?: string[], options?: RecordOptions): void;
+}

package/dist/watch/recorder.js

@@ -0,0 +1,39 @@
+/**
+ * The recorder turns a watcher's observation into a stored `Entry`. It applies
+ * the config gates (enabled, per-type toggle, sampling), stamps the entry with
+ * the current request/batch id, makes the content JSON-safe, and persists it —
+ * fire-and-forget, so recording never blocks or breaks the thing it's watching.
+ */
+import { currentRequestId } from "../core/instrumentation.js";
+import { newUuid, jsonSafe } from "./entry.js";
+export class Recorder {
+    store;
+    config;
+    constructor(store, config) {
+        this.store = store;
+        this.config = config;
+    }
+    /** Whether a given entry type should be recorded at all. */
+    enabledFor(type) {
+        return this.config.enabled && this.config.watchers[type];
+    }
+    /** Record one entry. A no-op when the type is disabled or sampled out. */
+    record(type, content, tags = [], options = {}) {
+        if (!this.enabledFor(type))
+            return;
+        if (this.config.sampling < 1 && Math.random() > this.config.sampling)
+            return;
+        const entry = {
+            uuid: newUuid(),
+            batchId: options.batchId ?? currentRequestId() ?? newUuid(),
+            type,
+            ...(options.familyHash ? { familyHash: options.familyHash } : {}),
+            content: jsonSafe(content),
+            tags,
+            createdAt: Date.now(),
+        };
+        void Promise.resolve(this.store.record([entry])).catch(() => {
+            // Persistence failures must never surface into the watched request.
+        });
+    }
+}

package/dist/watch/routes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The dashboard's HTTP surface: a small JSON API the SPA polls, and the SPA
+ * shell itself. Every route is behind the gate — the API included, so entries
+ * can't be read by anyone the dashboard wouldn't show them to.
+ *
+ * Registered under the configured prefix by the provider, so paths here are
+ * relative to it ("/", "/api/entries", …).
+ */
+import type { Router } from "../core/http/router.js";
+import type { EntryStore } from "./store.js";
+import type { WatchConfig } from "./config.js";
+import { type ShellOptions } from "./ui-shell.js";
+export declare function registerWatchRoutes(r: Router, store: EntryStore, config: WatchConfig, shell: ShellOptions): void;

package/dist/watch/routes.js

@@ -0,0 +1,55 @@
+/**
+ * The dashboard's HTTP surface: a small JSON API the SPA polls, and the SPA
+ * shell itself. Every route is behind the gate — the API included, so entries
+ * can't be read by anyone the dashboard wouldn't show them to.
+ *
+ * Registered under the configured prefix by the provider, so paths here are
+ * relative to it ("/", "/api/entries", …).
+ */
+import { passesGate } from "./gate.js";
+import { dashboardHtml } from "./ui-shell.js";
+export function registerWatchRoutes(r, store, config, shell) {
+    /** Wrap a JSON handler in the gate. */
+    const guarded = (handler) => async (c) => {
+        if (!(await passesGate(c)))
+            return c.json({ error: "Forbidden" }, 403);
+        return handler(c);
+    };
+    // Per-type counts for the tab badges.
+    r.get("/api/counts", guarded(async (c) => c.json({ counts: await store.counts() }))).name("counts");
+    // A page of entries, filtered by type/tag and keyset-paginated by `before`.
+    r.get("/api/entries", guarded(async (c) => {
+        const type = c.req.query("type");
+        const tag = c.req.query("tag") || undefined;
+        const before = c.req.query("before") ? Number(c.req.query("before")) : undefined;
+        const limit = c.req.query("limit") ? Number(c.req.query("limit")) : config.limit;
+        const entries = await store.list({
+            ...(type ? { type } : {}),
+            ...(tag ? { tag } : {}),
+            ...(before ? { before } : {}),
+            limit,
+        });
+        return c.json({ entries });
+    })).name("entries");
+    // One entry, plus the other entries in its batch (the request it belonged to).
+    r.get("/api/entries/:uuid", guarded(async (c) => {
+        const entry = await store.get(c.req.param("uuid"));
+        if (!entry)
+            return c.json({ error: "Not found" }, 404);
+        const related = (await store.batch(entry.batchId)).filter((e) => e.uuid !== entry.uuid);
+        return c.json({ entry, related });
+    })).name("entry");
+    // Every entry in a batch — a request and all it produced.
+    r.get("/api/batch/:batchId", guarded(async (c) => c.json({ entries: await store.batch(c.req.param("batchId")) }))).name("batch");
+    // Wipe the store from the dashboard's "Clear" button.
+    r.delete("/api/entries", guarded(async (c) => {
+        await store.clear();
+        return c.json({ ok: true });
+    })).name("clear");
+    // The SPA shell. Deep links are hash-based, so this one route serves them all.
+    r.get("/", async (c) => {
+        if (!(await passesGate(c)))
+            return c.text("Forbidden", 403);
+        return c.html(dashboardHtml(shell));
+    }).name("dashboard");
+}

package/dist/watch/store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Where recorded entries live. Two implementations behind one interface:
+ *
+ *   - `MemoryStore` — a per-process ring buffer. Zero setup, great for a single
+ *     dev process or the edge; entries vanish on restart.
+ *   - `DatabaseStore` — a `watch_entries` table via any registered connection.
+ *     Survives restarts and is shared across processes; needs `keel migrate`.
+ *
+ * The store's own reads and writes hit the database like anything else, so they
+ * would show up in the Query watcher — an infinite hall of mirrors. The watcher
+ * filters them out by table name (see `watchers.ts`); the store just does its job.
+ */
+import type { Entry, EntryFilter, EntryType } from "./entry.js";
+export interface EntryStore {
+    /** Persist a batch of entries. */
+    record(entries: Entry[]): Promise<void>;
+    /** One entry by id. */
+    get(uuid: string): Promise<Entry | undefined>;
+    /** Entries matching a filter, newest first. */
+    list(filter: EntryFilter): Promise<Entry[]>;
+    /** Every entry in one batch (a request and its children), newest first. */
+    batch(batchId: string): Promise<Entry[]>;
+    /** How many entries of each type — for the dashboard's tab counts. */
+    counts(): Promise<Record<EntryType, number>>;
+    /** Delete entries created before `timestamp`. Returns how many. */
+    prune(timestamp: number): Promise<number>;
+    /** Delete everything. */
+    clear(): Promise<void>;
+}
+export declare class MemoryStore implements EntryStore {
+    private cap;
+    private entries;
+    constructor(cap?: number);
+    record(entries: Entry[]): Promise<void>;
+    get(uuid: string): Promise<Entry | undefined>;
+    list(filter: EntryFilter): Promise<Entry[]>;
+    batch(batchId: string): Promise<Entry[]>;
+    counts(): Promise<Record<EntryType, number>>;
+    prune(timestamp: number): Promise<number>;
+    clear(): Promise<void>;
+}
+export declare class DatabaseStore implements EntryStore {
+    private table;
+    private connectionName?;
+    constructor(table: string, connectionName?: string | undefined);
+    private conn;
+    record(entries: Entry[]): Promise<void>;
+    get(uuid: string): Promise<Entry | undefined>;
+    list(filter: EntryFilter): Promise<Entry[]>;
+    batch(batchId: string): Promise<Entry[]>;
+    counts(): Promise<Record<EntryType, number>>;
+    prune(timestamp: number): Promise<number>;
+    clear(): Promise<void>;
+}

package/dist/watch/store.js

@@ -0,0 +1,158 @@
+/**
+ * Where recorded entries live. Two implementations behind one interface:
+ *
+ *   - `MemoryStore` — a per-process ring buffer. Zero setup, great for a single
+ *     dev process or the edge; entries vanish on restart.
+ *   - `DatabaseStore` — a `watch_entries` table via any registered connection.
+ *     Survives restarts and is shared across processes; needs `keel migrate`.
+ *
+ * The store's own reads and writes hit the database like anything else, so they
+ * would show up in the Query watcher — an infinite hall of mirrors. The watcher
+ * filters them out by table name (see `watchers.ts`); the store just does its job.
+ */
+import { connection } from "../core/database.js";
+import { ENTRY_TYPES } from "./entry.js";
+/* -------------------------------- memory ---------------------------------- */
+export class MemoryStore {
+    cap;
+    entries = [];
+    constructor(cap = 1000) {
+        this.cap = cap;
+    }
+    async record(entries) {
+        // newest first; trim the oldest past the cap
+        this.entries.unshift(...entries);
+        if (this.entries.length > this.cap)
+            this.entries.length = this.cap;
+    }
+    async get(uuid) {
+        return this.entries.find((e) => e.uuid === uuid);
+    }
+    async list(filter) {
+        let rows = this.entries;
+        if (filter.type)
+            rows = rows.filter((e) => e.type === filter.type);
+        if (filter.tag)
+            rows = rows.filter((e) => e.tags.includes(filter.tag));
+        if (filter.batchId)
+            rows = rows.filter((e) => e.batchId === filter.batchId);
+        if (filter.before != null)
+            rows = rows.filter((e) => e.createdAt < filter.before);
+        return rows.slice(0, filter.limit ?? 100);
+    }
+    async batch(batchId) {
+        return this.entries.filter((e) => e.batchId === batchId);
+    }
+    async counts() {
+        const counts = emptyCounts();
+        for (const e of this.entries)
+            counts[e.type]++;
+        return counts;
+    }
+    async prune(timestamp) {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((e) => e.createdAt >= timestamp);
+        return before - this.entries.length;
+    }
+    async clear() {
+        this.entries = [];
+    }
+}
+export class DatabaseStore {
+    table;
+    connectionName;
+    constructor(table, connectionName) {
+        this.table = table;
+        this.connectionName = connectionName;
+    }
+    conn() {
+        return connection(this.connectionName);
+    }
+    async record(entries) {
+        const conn = this.conn();
+        for (const e of entries) {
+            await conn.write(`INSERT INTO ${this.table} (uuid, batch_id, type, family_hash, content, tags, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+                e.uuid,
+                e.batchId,
+                e.type,
+                e.familyHash ?? null,
+                JSON.stringify(e.content),
+                // tags stored comma-wrapped (",a,b,") so `LIKE '%,tag,%'` matches exactly
+                e.tags.length ? `,${e.tags.join(",")},` : "",
+                e.createdAt,
+            ]);
+        }
+    }
+    async get(uuid) {
+        const rows = (await this.conn().select(`SELECT * FROM ${this.table} WHERE uuid = ? LIMIT 1`, [uuid]));
+        return rows[0] ? hydrate(rows[0]) : undefined;
+    }
+    async list(filter) {
+        const where = [];
+        const bindings = [];
+        if (filter.type) {
+            where.push("type = ?");
+            bindings.push(filter.type);
+        }
+        if (filter.batchId) {
+            where.push("batch_id = ?");
+            bindings.push(filter.batchId);
+        }
+        if (filter.tag) {
+            where.push("tags LIKE ?");
+            bindings.push(`%,${filter.tag},%`);
+        }
+        if (filter.before != null) {
+            where.push("created_at < ?");
+            bindings.push(filter.before);
+        }
+        const clause = where.length ? `WHERE ${where.join(" AND ")}` : "";
+        const rows = (await this.conn().select(`SELECT * FROM ${this.table} ${clause} ORDER BY created_at DESC LIMIT ${Number(filter.limit ?? 100)}`, bindings));
+        return rows.map(hydrate);
+    }
+    async batch(batchId) {
+        const rows = (await this.conn().select(`SELECT * FROM ${this.table} WHERE batch_id = ? ORDER BY created_at ASC`, [batchId]));
+        return rows.map(hydrate);
+    }
+    async counts() {
+        const rows = (await this.conn().select(`SELECT type, COUNT(*) AS n FROM ${this.table} GROUP BY type`, []));
+        const counts = emptyCounts();
+        for (const r of rows) {
+            if (r.type in counts)
+                counts[r.type] = Number(r.n);
+        }
+        return counts;
+    }
+    async prune(timestamp) {
+        const result = await this.conn().write(`DELETE FROM ${this.table} WHERE created_at < ?`, [timestamp]);
+        return result.rowsAffected;
+    }
+    async clear() {
+        await this.conn().write(`DELETE FROM ${this.table}`, []);
+    }
+}
+/* -------------------------------- helpers --------------------------------- */
+function emptyCounts() {
+    return Object.fromEntries(ENTRY_TYPES.map((t) => [t, 0]));
+}
+/** Turn a stored row back into an Entry. */
+function hydrate(row) {
+    return {
+        uuid: row.uuid,
+        batchId: row.batch_id,
+        type: row.type,
+        ...(row.family_hash ? { familyHash: row.family_hash } : {}),
+        content: safeParse(row.content),
+        tags: row.tags ? row.tags.split(",").filter(Boolean) : [],
+        createdAt: Number(row.created_at),
+    };
+}
+function safeParse(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return { raw: json };
+    }
+}

package/dist/watch/ui/dist/watch.css

@@ -0,0 +1 @@
+:root{--bg: #f7f8fa;--panel: #ffffff;--panel-2: #f0f2f5;--border: #e2e6ec;--text: #1e2430;--muted: #6b7686;--accent: #2563eb;--accent-soft: #dbe6ff;--ok: #16a34a;--warn: #d97706;--err: #dc2626;--chip: #eef1f6;--mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace}@media(prefers-color-scheme:dark){:root{--bg: #0b0f17;--panel: #121824;--panel-2: #0e131d;--border: #222b3a;--text: #e6eaf1;--muted: #8a94a6;--accent: #5b8dff;--accent-soft: #1b2740;--ok: #34d399;--warn: #fbbf24;--err: #f87171;--chip: #1a2333}}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:14px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}.app{display:grid;grid-template-columns:232px 1fr;min-height:100vh}.sidebar{background:var(--panel);border-right:1px solid var(--border);display:flex;flex-direction:column;padding:16px 12px;gap:4px;position:sticky;top:0;height:100vh}.brand{font-weight:700;font-size:16px;padding:4px 8px 14px;letter-spacing:.2px}.brand .anchor{margin-right:4px}.sidebar nav{display:flex;flex-direction:column;gap:2px;flex:1}.tab{display:flex;align-items:center;justify-content:space-between;border:0;background:transparent;color:var(--muted);padding:8px 10px;border-radius:8px;cursor:pointer;font-size:13.5px;text-align:left}.tab:hover{background:var(--panel-2);color:var(--text)}.tab.active{background:var(--accent-soft);color:var(--accent);font-weight:600}.count{font-variant-numeric:tabular-nums;font-size:12px;background:var(--chip);color:var(--muted);border-radius:999px;padding:1px 8px;min-width:22px;text-align:center}.tab.active .count{background:var(--accent);color:#fff}.controls{display:flex;align-items:center;justify-content:space-between;padding:12px 8px 2px;border-top:1px solid var(--border);margin-top:8px}.live{display:flex;align-items:center;gap:6px;color:var(--muted);font-size:13px;cursor:pointer}.clear{border:1px solid var(--border);background:var(--panel-2);color:var(--muted);border-radius:7px;padding:5px 12px;cursor:pointer;font-size:12.5px}.clear:hover{color:var(--err);border-color:var(--err)}.content{padding:22px 26px;min-width:0}.head{display:flex;align-items:center;gap:12px;margin-bottom:16px}.head h1{font-size:18px;margin:0;font-weight:650;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.back,.chip.removable{border:1px solid var(--border);background:var(--panel);color:var(--muted);border-radius:7px;padding:5px 11px;cursor:pointer;font-size:13px}.back:hover{color:var(--accent);border-color:var(--accent)}.empty{color:var(--muted);padding:40px 4px}.list{width:100%;border-collapse:collapse;background:var(--panel);border:1px solid var(--border);border-radius:10px;overflow:hidden}.list tr{border-bottom:1px solid var(--border);cursor:pointer}.list tr:last-child{border-bottom:0}.list tr:hover{background:var(--panel-2)}.list td{padding:10px 14px;vertical-align:middle}.summary{display:flex;flex-direction:column;gap:5px;min-width:0}.summary .text{font-family:var(--mono);font-size:12.5px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:62vw}.tags{display:flex;gap:5px;flex-wrap:wrap}.chip{background:var(--chip);color:var(--muted);border-radius:999px;padding:1px 9px;font-size:11px;cursor:pointer;white-space:nowrap}.chip:hover{color:var(--accent)}.metacol,.timecol{text-align:right;color:var(--muted);font-size:12px;font-variant-numeric:tabular-nums;white-space:nowrap}.badge{color:var(--accent);font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.4px;white-space:nowrap;width:1%}.detailtags{margin-bottom:14px}.json{background:var(--panel-2);border:1px solid var(--border);border-radius:10px;padding:16px;font-family:var(--mono);font-size:12.5px;line-height:1.6;overflow-x:auto;white-space:pre-wrap;word-break:break-word}.related{margin-top:24px}.related h2{font-size:13px;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:0 0 10px}@media(max-width:720px){.app{grid-template-columns:1fr}.sidebar{position:static;height:auto;flex-direction:row;flex-wrap:wrap;align-items:center}.sidebar nav{flex-direction:row;flex-wrap:wrap}.summary .text{max-width:70vw}}