@shaferllc/keel 0.68.0 → 0.77.0

package/dist/openapi/doc.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Route documentation metadata. Attach it to a route with `.config(apiDoc(...))`
+ * and the generator turns it into a rich OpenAPI operation — request/response
+ * schemas, summary, tags. Request schemas reuse Keel's `RequestSchemas` shape, so
+ * the very object you hand `validateRequest({ body })` also documents the route.
+ *
+ *   router
+ *     .post("/users", [Users, "store"])
+ *     .config(apiDoc({ summary: "Create a user", request: { body: NewUser }, tags: ["users"] }))
+ *     .middleware([validateRequest({ body: NewUser })]);
+ */
+import type { RequestSchemas } from "../core/validation.js";
+/** The key under which docs metadata lives in a route's `config`. */
+export declare const OPENAPI_KEY = "openapi";
+/** One response's documentation: a description and an optional body schema. */
+export interface ResponseDoc {
+    description?: string;
+    /** A Zod schema or a plain JSON Schema object for the response body. */
+    schema?: unknown;
+}
+/** Everything a route can say about itself for the spec. */
+export interface OperationDoc {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    /** Overrides the generated operationId (default: the route name). */
+    operationId?: string;
+    deprecated?: boolean;
+    /** Request body/query/params schemas — Zod or plain JSON Schema. */
+    request?: RequestSchemas;
+    /** Responses keyed by status code, e.g. `{ 200: { schema: User }, 404: {} }`. */
+    responses?: Record<string | number, ResponseDoc>;
+    /** Leave this route out of the spec entirely. */
+    hidden?: boolean;
+}
+/**
+ * Wrap operation docs for a route's `.config()`. Returns `{ openapi: doc }`, which
+ * the generator reads off `RouteDefinition.config`.
+ */
+export declare function apiDoc(doc: OperationDoc): Record<string, unknown>;

package/dist/openapi/doc.js

@@ -0,0 +1,20 @@
+/**
+ * Route documentation metadata. Attach it to a route with `.config(apiDoc(...))`
+ * and the generator turns it into a rich OpenAPI operation — request/response
+ * schemas, summary, tags. Request schemas reuse Keel's `RequestSchemas` shape, so
+ * the very object you hand `validateRequest({ body })` also documents the route.
+ *
+ *   router
+ *     .post("/users", [Users, "store"])
+ *     .config(apiDoc({ summary: "Create a user", request: { body: NewUser }, tags: ["users"] }))
+ *     .middleware([validateRequest({ body: NewUser })]);
+ */
+/** The key under which docs metadata lives in a route's `config`. */
+export const OPENAPI_KEY = "openapi";
+/**
+ * Wrap operation docs for a route's `.config()`. Returns `{ openapi: doc }`, which
+ * the generator reads off `RouteDefinition.config`.
+ */
+export function apiDoc(doc) {
+    return { [OPENAPI_KEY]: doc };
+}

package/dist/openapi/export.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `keel openapi:export [--out openapi.json]` — write the spec to a file, for CI,
+ * client generation, or committing it. Contributed as a package command.
+ */
+import type { PackageCommand } from "../core/package.js";
+import type { Router } from "../core/http/router.js";
+import type { OpenApiConfig } from "./config.js";
+export declare function exportCommand(getRouter: () => Router, config: OpenApiConfig, base: string): PackageCommand;

package/dist/openapi/export.js

@@ -0,0 +1,19 @@
+/**
+ * `keel openapi:export [--out openapi.json]` — write the spec to a file, for CI,
+ * client generation, or committing it. Contributed as a package command.
+ */
+import { defineCommand, flag } from "../core/console.js";
+import { buildSpec } from "./spec.js";
+export function exportCommand(getRouter, config, base) {
+    return defineCommand({
+        name: "openapi:export",
+        description: "Write the OpenAPI spec to a file",
+        flags: { out: flag.string({ description: "output path", default: "openapi.json" }) },
+        async run({ flags, ui }) {
+            const spec = buildSpec(getRouter().all(), config, base);
+            const { writeFile } = await import("node:fs/promises");
+            await writeFile(flags.out, JSON.stringify(spec, null, 2));
+            ui.success(`Wrote ${flags.out} (${Object.keys(spec.paths).length} paths)`);
+        },
+    });
+}

package/dist/openapi/gate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Who may see the docs. A spec advertises your whole API surface, so it's gated
+ * shut in production by default — open only when `app.debug` is on, outside
+ * production, or when you set `public: true`. Override with `OpenApi.auth()`.
+ */
+import type { Ctx } from "../core/http/router.js";
+import type { OpenApiConfig } from "./config.js";
+export type OpenApiGate = (c: Ctx) => boolean | Promise<boolean>;
+export declare const OpenApi: {
+    /** Restrict docs access. Return true to allow the request. */
+    auth(fn: OpenApiGate): void;
+    /** Remove a custom gate, reverting to the default. */
+    clearAuth(): void;
+};
+export declare function passesGate(c: Ctx, cfg: OpenApiConfig): Promise<boolean>;

package/dist/openapi/gate.js

@@ -0,0 +1,27 @@
+/**
+ * Who may see the docs. A spec advertises your whole API surface, so it's gated
+ * shut in production by default — open only when `app.debug` is on, outside
+ * production, or when you set `public: true`. Override with `OpenApi.auth()`.
+ */
+import { config } from "../core/helpers.js";
+let gate;
+export const OpenApi = {
+    /** Restrict docs access. Return true to allow the request. */
+    auth(fn) {
+        gate = fn;
+    },
+    /** Remove a custom gate, reverting to the default. */
+    clearAuth() {
+        gate = undefined;
+    },
+};
+function defaultGate(cfg) {
+    if (cfg.public)
+        return true;
+    if (config("app.debug", false))
+        return true;
+    return config("app.env", "production") !== "production";
+}
+export async function passesGate(c, cfg) {
+    return gate ? gate(c) : defaultGate(cfg);
+}

package/dist/openapi/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Keel OpenAPI — spec generation + Swagger UI for Keel apps, imported from
+ * `@shaferllc/keel/openapi`.
+ *
+ *   import { OpenApiServiceProvider } from "@shaferllc/keel/openapi";
+ *   app.register(OpenApiServiceProvider);      // serves /docs and /docs/openapi.json
+ *
+ * Document a route with `apiDoc()`; lock the docs down with `OpenApi.auth()`.
+ */
+export { OpenApiServiceProvider } from "./provider.js";
+export { OpenApi } from "./gate.js";
+export type { OpenApiGate } from "./gate.js";
+export { apiDoc, OPENAPI_KEY } from "./doc.js";
+export type { OperationDoc, ResponseDoc } from "./doc.js";
+export { buildSpec } from "./spec.js";
+export type { OpenApiDocument } from "./spec.js";
+export { toJsonSchema } from "./zod.js";
+export { resolveConfig, defaultConfig } from "./config.js";
+export type { OpenApiConfig } from "./config.js";

package/dist/openapi/index.js

@@ -0,0 +1,15 @@
+/**
+ * Keel OpenAPI — spec generation + Swagger UI for Keel apps, imported from
+ * `@shaferllc/keel/openapi`.
+ *
+ *   import { OpenApiServiceProvider } from "@shaferllc/keel/openapi";
+ *   app.register(OpenApiServiceProvider);      // serves /docs and /docs/openapi.json
+ *
+ * Document a route with `apiDoc()`; lock the docs down with `OpenApi.auth()`.
+ */
+export { OpenApiServiceProvider } from "./provider.js";
+export { OpenApi } from "./gate.js";
+export { apiDoc, OPENAPI_KEY } from "./doc.js";
+export { buildSpec } from "./spec.js";
+export { toJsonSchema } from "./zod.js";
+export { resolveConfig, defaultConfig } from "./config.js";

package/dist/openapi/openapi.config.stub

@@ -0,0 +1,29 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Keel OpenAPI — spec + Swagger UI configuration.
+ * Published with `keel vendor:publish --tag openapi-config`.
+ */
+export default {
+  enabled: env("OPENAPI_ENABLED", true),
+
+  // Docs UI at http://localhost:3000/docs, spec at /docs/openapi.json
+  path: "docs",
+
+  // Shown in the spec's `info`. Title defaults to config("app.name").
+  title: "",
+  version: "1.0.0",
+  description: undefined,
+
+  // Where the API is served (OpenAPI `servers`), e.g. ["https://api.example.com"].
+  servers: [],
+
+  // Serve the docs in production too. Off by default — a spec advertises your API.
+  public: env("OPENAPI_PUBLIC", false),
+
+  // Swagger UI assets. Pin the version, or point at a copy you host.
+  cdn: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14",
+
+  // Route path prefixes to leave out of the spec.
+  ignorePaths: ["/watch"],
+};

package/dist/openapi/provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Keel OpenAPI — generate an OpenAPI 3 spec from your routes and serve Swagger UI,
+ * shipped as a Keel package. One line turns it on:
+ *
+ *   app.register(OpenApiServiceProvider);
+ *
+ * The spec is built from Keel's own route table plus whatever each route attaches
+ * with `.config(apiDoc(...))`. Nothing is scraped or guessed: paths and methods
+ * are always right, and schemas are as rich as the metadata a route provides.
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class OpenApiServiceProvider extends PackageProvider {
+    readonly name = "openapi";
+    private config;
+    private base;
+    register(): void;
+    boot(): void;
+}

package/dist/openapi/provider.js

@@ -0,0 +1,35 @@
+/**
+ * Keel OpenAPI — generate an OpenAPI 3 spec from your routes and serve Swagger UI,
+ * shipped as a Keel package. One line turns it on:
+ *
+ *   app.register(OpenApiServiceProvider);
+ *
+ * The spec is built from Keel's own route table plus whatever each route attaches
+ * with `.config(apiDoc(...))`. Nothing is scraped or guessed: paths and methods
+ * are always right, and schemas are as rich as the metadata a route provides.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PackageProvider } from "../core/package.js";
+import { resolveConfig, defaultConfig } from "./config.js";
+import { registerOpenApiRoutes } from "./routes.js";
+import { exportCommand } from "./export.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export class OpenApiServiceProvider extends PackageProvider {
+    name = "openapi";
+    config;
+    base() {
+        return "/" + this.config.path.replace(/^\/|\/$/g, "");
+    }
+    register() {
+        this.mergeConfig("openapi", defaultConfig);
+        this.config = resolveConfig();
+        this.publishes({ [join(here, "openapi.config.stub")]: "config/openapi.ts" }, "openapi-config");
+        this.commands([exportCommand(() => this.app.router(), this.config, this.base())]);
+    }
+    boot() {
+        if (!this.config.enabled)
+            return;
+        this.routes((r) => registerOpenApiRoutes(r, this.config, this.app.router(), this.base()), { prefix: this.config.path, as: "openapi" });
+    }
+}

package/dist/openapi/routes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The docs HTTP surface: the generated spec at `/openapi.json` and the Swagger UI
+ * at the base path. The spec is built once, lazily, from the full route table
+ * (which is complete only after the app has loaded its routes) and cached.
+ * Both routes are behind the gate.
+ */
+import type { Router } from "../core/http/router.js";
+import type { OpenApiConfig } from "./config.js";
+export declare function registerOpenApiRoutes(r: Router, config: OpenApiConfig, router: Router, base: string): void;

package/dist/openapi/routes.js

@@ -0,0 +1,23 @@
+/**
+ * The docs HTTP surface: the generated spec at `/openapi.json` and the Swagger UI
+ * at the base path. The spec is built once, lazily, from the full route table
+ * (which is complete only after the app has loaded its routes) and cached.
+ * Both routes are behind the gate.
+ */
+import { buildSpec } from "./spec.js";
+import { swaggerHtml } from "./ui.js";
+import { passesGate } from "./gate.js";
+export function registerOpenApiRoutes(r, config, router, base) {
+    let cached;
+    const spec = () => (cached ??= buildSpec(router.all(), config, base));
+    r.get("/openapi.json", async (c) => {
+        if (!(await passesGate(c, config)))
+            return c.json({ error: "Forbidden" }, 403);
+        return c.json(spec());
+    }).name("spec");
+    r.get("/", async (c) => {
+        if (!(await passesGate(c, config)))
+            return c.text("Forbidden", 403);
+        return c.html(swaggerHtml(`${base}/openapi.json`, config));
+    }).name("ui");
+}

package/dist/openapi/spec.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build an OpenAPI 3.0 document from Keel's own route table. Every registered
+ * route already carries its methods, path, name, param constraints, and any
+ * `.config(apiDoc(...))` metadata — that's the whole input. Paths and methods
+ * come for free; request/response schemas come from the docs metadata a route
+ * chose to attach. A route with no metadata still appears, just bare.
+ */
+import type { RouteDefinition } from "../core/http/router.js";
+import type { OpenApiConfig } from "./config.js";
+export interface OpenApiDocument {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: {
+        url: string;
+    }[];
+    paths: Record<string, Record<string, unknown>>;
+}
+/** Assemble the whole document from the route table. */
+export declare function buildSpec(routes: RouteDefinition[], config: OpenApiConfig, base: string): OpenApiDocument;

package/dist/openapi/spec.js

@@ -0,0 +1,132 @@
+/**
+ * Build an OpenAPI 3.0 document from Keel's own route table. Every registered
+ * route already carries its methods, path, name, param constraints, and any
+ * `.config(apiDoc(...))` metadata — that's the whole input. Paths and methods
+ * come for free; request/response schemas come from the docs metadata a route
+ * chose to attach. A route with no metadata still appears, just bare.
+ */
+import { OPENAPI_KEY } from "./doc.js";
+import { toJsonSchema } from "./zod.js";
+/** `/users/:id` (and `:id?`) → `/users/{id}` — OpenAPI's path-template syntax. */
+function toTemplate(path) {
+    return path.replace(/:([A-Za-z0-9_]+)\??/g, "{$1}");
+}
+/** The `:param` names in a path, in order. */
+function paramNames(path) {
+    return [...path.matchAll(/:([A-Za-z0-9_]+)\??/g)].map((m) => m[1]);
+}
+/** An operationId that's stable and unique: the route name, else method + path. */
+function operationId(route, method) {
+    if (route.name)
+        return route.name;
+    const slug = route.path.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "");
+    return `${method.toLowerCase()}_${slug || "root"}`;
+}
+/** Path parameters — from the URL template, enriched by any `params` schema/`where`. */
+function pathParameters(route, doc) {
+    const paramsSchema = doc?.request?.params ? toJsonSchema(doc.request.params) : undefined;
+    const props = (paramsSchema?.properties ?? {});
+    return paramNames(route.path).map((name) => {
+        const schema = props[name] ?? { type: "string" };
+        // A `.where("id", /\d+/)` constraint becomes a pattern hint.
+        if (route.wheres[name] && !("pattern" in schema)) {
+            schema.pattern = `^${route.wheres[name]}$`;
+        }
+        return { name, in: "path", required: true, schema };
+    });
+}
+/** Query parameters — expanded from a `query` schema's top-level properties. */
+function queryParameters(doc) {
+    const schema = doc?.request?.query ? toJsonSchema(doc.request.query) : undefined;
+    if (!schema?.properties)
+        return [];
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties).map(([name, propSchema]) => ({
+        name,
+        in: "query",
+        required: required.has(name),
+        schema: propSchema,
+    }));
+}
+const HAS_BODY = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** Build one operation object for a (route, method) pair. */
+function buildOperation(route, method, doc) {
+    const op = {
+        operationId: doc?.operationId ?? operationId(route, method),
+        tags: doc?.tags ?? [defaultTag(route.path)],
+        parameters: [...pathParameters(route, doc), ...queryParameters(doc)],
+    };
+    if (doc?.summary)
+        op.summary = doc.summary;
+    if (doc?.description)
+        op.description = doc.description;
+    if (doc?.deprecated)
+        op.deprecated = true;
+    const body = doc?.request?.body ? toJsonSchema(doc.request.body) : undefined;
+    if (body && HAS_BODY.has(method)) {
+        op.requestBody = { required: true, content: { "application/json": { schema: body } } };
+    }
+    op.responses = buildResponses(doc);
+    return op;
+}
+/** Responses from the docs, or a sensible default, plus a 422 when input is validated. */
+function buildResponses(doc) {
+    const responses = {};
+    if (doc?.responses) {
+        for (const [status, res] of Object.entries(doc.responses)) {
+            const schema = res.schema ? toJsonSchema(res.schema) : undefined;
+            responses[status] = {
+                description: res.description ?? "",
+                ...(schema ? { content: { "application/json": { schema } } } : {}),
+            };
+        }
+    }
+    if (!Object.keys(responses).length)
+        responses["200"] = { description: "OK" };
+    // A documented request means validation can reject it.
+    if (doc?.request && !responses["422"]) {
+        responses["422"] = { description: "Validation failed" };
+    }
+    return responses;
+}
+/** The tag for an undocumented route: its first path segment. */
+function defaultTag(path) {
+    const seg = path.split("/").filter(Boolean)[0] ?? "default";
+    return seg.startsWith(":") ? "default" : seg;
+}
+/** Whether a route is left out of the spec. */
+function skip(route, config, base) {
+    const doc = route.config?.[OPENAPI_KEY];
+    if (doc?.hidden)
+        return true;
+    if (route.path.includes("*"))
+        return true; // wildcard/asset routes aren't API endpoints
+    if (route.path === base || route.path.startsWith(`${base}/`))
+        return true; // the docs' own routes
+    return config.ignorePaths.some((p) => route.path.startsWith(p));
+}
+/** Assemble the whole document from the route table. */
+export function buildSpec(routes, config, base) {
+    const paths = {};
+    for (const route of routes) {
+        if (skip(route, config, base))
+            continue;
+        const doc = route.config?.[OPENAPI_KEY];
+        const template = toTemplate(route.path);
+        for (const method of route.methods) {
+            if (method === "HEAD" || method === "OPTIONS")
+                continue;
+            (paths[template] ??= {})[method.toLowerCase()] = buildOperation(route, method, doc);
+        }
+    }
+    return {
+        openapi: "3.0.3",
+        info: {
+            title: config.title,
+            version: config.version,
+            ...(config.description ? { description: config.description } : {}),
+        },
+        ...(config.servers.length ? { servers: config.servers.map((url) => ({ url })) } : {}),
+        paths,
+    };
+}

package/dist/openapi/ui.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The docs UI: a Swagger UI shell pointed at the generated spec. Swagger UI's
+ * assets load from the configured `cdn` (pin it, or point it at a copy you host)
+ * — the one external dependency in this package, kept to the UI. The spec itself
+ * (`/openapi.json`) is generated with zero dependencies and works anywhere.
+ */
+import type { OpenApiConfig } from "./config.js";
+export declare function swaggerHtml(specUrl: string, cfg: OpenApiConfig): string;

package/dist/openapi/ui.js

@@ -0,0 +1,31 @@
+/**
+ * The docs UI: a Swagger UI shell pointed at the generated spec. Swagger UI's
+ * assets load from the configured `cdn` (pin it, or point it at a copy you host)
+ * — the one external dependency in this package, kept to the UI. The spec itself
+ * (`/openapi.json`) is generated with zero dependencies and works anywhere.
+ */
+import { escapeHtml } from "../core/template.js";
+export function swaggerHtml(specUrl, cfg) {
+    const cdn = cfg.cdn.replace(/\/+$/, "");
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(cfg.title)} — API docs</title>
+  <link rel="stylesheet" href="${cdn}/swagger-ui.css" />
+  <style>body { margin: 0; }</style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="${cdn}/swagger-ui-bundle.js" crossorigin></script>
+  <script>
+    window.ui = SwaggerUIBundle({
+      url: ${JSON.stringify(specUrl)},
+      dom_id: "#swagger-ui",
+      deepLinking: true,
+    });
+  </script>
+</body>
+</html>`;
+}

package/dist/openapi/zod.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Schema conversion. A route documents itself with the same Zod schemas it
+ * validates with; the spec needs JSON Schema. Zod 4 ships that conversion
+ * (`z.toJSONSchema`), so this is a thin, defensive wrapper: Zod schemas are
+ * converted (targeting OpenAPI 3.0's dialect), plain JSON Schema objects pass
+ * through untouched, and anything unrecognized yields `undefined` rather than
+ * throwing — a missing schema shouldn't sink the whole document.
+ */
+type JsonSchema = Record<string, unknown>;
+/** Convert a Zod schema or JSON Schema to an OpenAPI-flavoured JSON Schema. */
+export declare function toJsonSchema(schema: unknown): JsonSchema | undefined;
+export {};

package/dist/openapi/zod.js

@@ -0,0 +1,46 @@
+/**
+ * Schema conversion. A route documents itself with the same Zod schemas it
+ * validates with; the spec needs JSON Schema. Zod 4 ships that conversion
+ * (`z.toJSONSchema`), so this is a thin, defensive wrapper: Zod schemas are
+ * converted (targeting OpenAPI 3.0's dialect), plain JSON Schema objects pass
+ * through untouched, and anything unrecognized yields `undefined` rather than
+ * throwing — a missing schema shouldn't sink the whole document.
+ */
+import { z } from "zod";
+/** Duck-type a Zod (or Zod-like) schema. */
+function isZod(value) {
+    return (!!value &&
+        typeof value.parse === "function" &&
+        typeof value.safeParse === "function");
+}
+/** A value that already looks like a JSON Schema (or a `$ref`). */
+function isJsonSchema(value) {
+    if (!value || typeof value !== "object" || isZod(value))
+        return false;
+    const keys = ["type", "$ref", "properties", "items", "oneOf", "anyOf", "allOf", "enum"];
+    return keys.some((k) => k in value);
+}
+/** Convert a Zod schema or JSON Schema to an OpenAPI-flavoured JSON Schema. */
+export function toJsonSchema(schema) {
+    if (!schema)
+        return undefined;
+    if (isJsonSchema(schema))
+        return schema;
+    if (!isZod(schema))
+        return undefined;
+    const convert = z.toJSONSchema;
+    if (typeof convert !== "function")
+        return undefined;
+    try {
+        // OpenAPI 3.0 uses `nullable` and a few other divergences from raw JSON Schema.
+        return convert(schema, { target: "openapi-3.0", io: "input" });
+    }
+    catch {
+        try {
+            return convert(schema);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

package/dist/watch/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Watch configuration. Defaults live here and are merged under `config("watch")`
+ * by the provider; an app overrides any of them in `config/watch.ts` (publish it
+ * with `keel vendor:publish --tag watch-config`).
+ */
+import type { EntryType } from "./entry.js";
+export interface WatchConfig {
+    /** Master switch. Off → no watchers install and the dashboard 404s. */
+    enabled: boolean;
+    /** URL prefix the dashboard and API mount under. Default: "watch". */
+    path: string;
+    /** Where entries live. "database" persists them; "memory" is a per-process ring. */
+    storage: "database" | "memory";
+    /** The database connection to use (when storage is "database"). */
+    connection?: string;
+    /** The table entries are stored in. */
+    table: string;
+    /** Ring size for the memory store, and the default page size for the API. */
+    limit: number;
+    /** Record only this fraction of eligible entries (0–1). 1 records everything. */
+    sampling: number;
+    /** Tag queries slower than this (ms) with `slow`. */
+    slowQueryMs: number;
+    /** Request path prefixes to never record (the dashboard's own are always skipped). */
+    ignorePaths: string[];
+    /** Delete entries older than this many hours when `watch:prune` runs. */
+    retentionHours: number;
+    /** Per-type on/off switches. Noisy watchers (cache, event) default off. */
+    watchers: Record<EntryType, boolean>;
+}
+export declare const defaultConfig: WatchConfig;
+/** Read the effective Watch config off the application, filling any gaps. */
+export declare function resolveConfig(): WatchConfig;

package/dist/watch/config.js

@@ -0,0 +1,38 @@
+/**
+ * Watch configuration. Defaults live here and are merged under `config("watch")`
+ * by the provider; an app overrides any of them in `config/watch.ts` (publish it
+ * with `keel vendor:publish --tag watch-config`).
+ */
+import { config } from "../core/helpers.js";
+export const defaultConfig = {
+    enabled: true,
+    path: "watch",
+    storage: "database",
+    table: "watch_entries",
+    limit: 100,
+    sampling: 1,
+    slowQueryMs: 100,
+    ignorePaths: [],
+    retentionHours: 24,
+    watchers: {
+        request: true,
+        query: true,
+        exception: true,
+        log: true,
+        mail: true,
+        job: true,
+        notification: true,
+        cache: false,
+        event: false,
+        schedule: true,
+    },
+};
+/** Read the effective Watch config off the application, filling any gaps. */
+export function resolveConfig() {
+    const raw = config("watch", {});
+    return {
+        ...defaultConfig,
+        ...raw,
+        watchers: { ...defaultConfig.watchers, ...(raw.watchers ?? {}) },
+    };
+}