npm - @shaferllc/keel - Versions diffs - 0.66.0 → 0.74.0 - Mend

@shaferllc/keel 0.66.0 → 0.74.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (239) hide show

package/AGENTS.md +169 -0
package/README.md +44 -6
package/bin/keel-mcp.mjs +9 -0
package/dist/api/api.config.stub +9 -0
package/dist/api/config.d.ts +13 -0
package/dist/api/config.js +14 -0
package/dist/api/index.d.ts +16 -0
package/dist/api/index.js +13 -0
package/dist/api/provider.d.ts +10 -0
package/dist/api/provider.js +17 -0
package/dist/api/query.d.ts +35 -0
package/dist/api/query.js +42 -0
package/dist/api/resource.d.ts +91 -0
package/dist/api/resource.js +188 -0
package/dist/core/application.d.ts +5 -5
package/dist/core/application.js +8 -2
package/dist/core/cache.d.ts +81 -5
package/dist/core/cache.js +188 -23
package/dist/core/cli/stubs.d.ts +26 -0
package/dist/core/cli/stubs.js +225 -0
package/dist/core/console-prompt.d.ts +79 -0
package/dist/core/console-prompt.js +239 -0
package/dist/core/console-ui.d.ts +96 -0
package/dist/core/console-ui.js +187 -0
package/dist/core/console.d.ts +188 -0
package/dist/core/console.js +395 -0
package/dist/core/database.d.ts +70 -1
package/dist/core/database.js +174 -15
package/dist/core/env.d.ts +96 -0
package/dist/core/env.js +140 -0
package/dist/core/events.d.ts +129 -5
package/dist/core/events.js +165 -7
package/dist/core/health.d.ts +141 -0
package/dist/core/health.js +226 -0
package/dist/core/helpers.d.ts +9 -3
package/dist/core/helpers.js +11 -3
package/dist/core/http/kernel.d.ts +2 -0
package/dist/core/http/kernel.js +48 -0
package/dist/core/http/router.d.ts +5 -5
package/dist/core/http/router.js +5 -5
package/dist/core/i18n.d.ts +162 -0
package/dist/core/i18n.js +472 -0
package/dist/core/index.d.ts +39 -13
package/dist/core/index.js +19 -6
package/dist/core/instrumentation.d.ts +113 -0
package/dist/core/instrumentation.js +52 -0
package/dist/core/lock.d.ts +139 -0
package/dist/core/lock.js +215 -0
package/dist/core/logger.d.ts +89 -4
package/dist/core/logger.js +167 -22
package/dist/core/mail.d.ts +128 -7
package/dist/core/mail.js +264 -16
package/dist/core/notification.js +10 -1
package/dist/core/package.d.ts +120 -0
package/dist/core/package.js +169 -0
package/dist/core/pages.d.ts +108 -0
package/dist/core/pages.js +199 -0
package/dist/core/queue.d.ts +134 -9
package/dist/core/queue.js +325 -14
package/dist/core/repl.d.ts +33 -0
package/dist/core/repl.js +88 -0
package/dist/core/scheduler.js +6 -0
package/dist/core/social.d.ts +4 -4
package/dist/core/social.js +4 -4
package/dist/core/storage.d.ts +159 -6
package/dist/core/storage.js +299 -7
package/dist/core/telemetry.d.ts +208 -0
package/dist/core/telemetry.js +383 -0
package/dist/core/template.d.ts +2 -3
package/dist/core/template.js +2 -3
package/dist/core/testing.d.ts +170 -1
package/dist/core/testing.js +504 -2
package/dist/db/d1.js +13 -0
package/dist/db/pg.d.ts +13 -0
package/dist/db/pg.js +46 -4
package/dist/mcp/server.d.ts +19 -0
package/dist/mcp/server.js +355 -0
package/dist/openapi/config.d.ts +28 -0
package/dist/openapi/config.js +25 -0
package/dist/openapi/doc.d.ts +40 -0
package/dist/openapi/doc.js +20 -0
package/dist/openapi/export.d.ts +8 -0
package/dist/openapi/export.js +19 -0
package/dist/openapi/gate.d.ts +15 -0
package/dist/openapi/gate.js +27 -0
package/dist/openapi/index.d.ts +19 -0
package/dist/openapi/index.js +15 -0
package/dist/openapi/openapi.config.stub +29 -0
package/dist/openapi/provider.d.ts +18 -0
package/dist/openapi/provider.js +35 -0
package/dist/openapi/routes.d.ts +9 -0
package/dist/openapi/routes.js +23 -0
package/dist/openapi/spec.d.ts +23 -0
package/dist/openapi/spec.js +132 -0
package/dist/openapi/ui.d.ts +8 -0
package/dist/openapi/ui.js +31 -0
package/dist/openapi/zod.d.ts +12 -0
package/dist/openapi/zod.js +46 -0
package/dist/watch/config.d.ts +33 -0
package/dist/watch/config.js +38 -0
package/dist/watch/entry.d.ts +53 -0
package/dist/watch/entry.js +105 -0
package/dist/watch/gate.d.ts +20 -0
package/dist/watch/gate.js +32 -0
package/dist/watch/index.d.ts +21 -0
package/dist/watch/index.js +17 -0
package/dist/watch/migration.d.ts +7 -0
package/dist/watch/migration.js +20 -0
package/dist/watch/provider.d.ts +22 -0
package/dist/watch/provider.js +58 -0
package/dist/watch/prune.d.ts +11 -0
package/dist/watch/prune.js +20 -0
package/dist/watch/recorder.d.ts +24 -0
package/dist/watch/recorder.js +39 -0
package/dist/watch/routes.d.ts +13 -0
package/dist/watch/routes.js +55 -0
package/dist/watch/store.d.ts +54 -0
package/dist/watch/store.js +158 -0
package/dist/watch/ui/dist/watch.css +1 -0
package/dist/watch/ui/dist/watch.js +555 -0
package/dist/watch/ui-shell.d.ts +12 -0
package/dist/watch/ui-shell.js +24 -0
package/dist/watch/watch.config.stub +47 -0
package/dist/watch/watchers.d.ts +12 -0
package/dist/watch/watchers.js +156 -0
package/docs/ai-manifest.json +3206 -0
package/docs/ai.md +128 -0
package/docs/api-resources.md +118 -0
package/docs/architecture.md +331 -0
package/docs/authentication.md +453 -0
package/docs/authorization.md +167 -0
package/docs/broadcasting.md +137 -0
package/docs/broker.md +500 -0
package/docs/cache.md +558 -0
package/docs/configuration.md +385 -0
package/docs/console.md +536 -0
package/docs/container.md +467 -0
package/docs/controllers.md +265 -0
package/docs/cors.md +51 -0
package/docs/database.md +631 -0
package/docs/debugging.md +129 -0
package/docs/decorators.md +127 -0
package/docs/errors.md +395 -0
package/docs/events.md +496 -0
package/docs/examples/architecture-app.ts +27 -0
package/docs/examples/authentication.ts +61 -0
package/docs/examples/authorization.ts +79 -0
package/docs/examples/broadcasting.ts +60 -0
package/docs/examples/broker-cache-validate.ts +34 -0
package/docs/examples/broker-fault-tolerance.ts +29 -0
package/docs/examples/broker-middleware.ts +27 -0
package/docs/examples/broker.ts +203 -0
package/docs/examples/cache.ts +222 -0
package/docs/examples/configuration.ts +121 -0
package/docs/examples/console.ts +134 -0
package/docs/examples/container.ts +134 -0
package/docs/examples/controllers.ts +86 -0
package/docs/examples/database.ts +208 -0
package/docs/examples/debugging.ts +41 -0
package/docs/examples/decorators.ts +40 -0
package/docs/examples/errors.ts +121 -0
package/docs/examples/events.ts +204 -0
package/docs/examples/factories.ts +84 -0
package/docs/examples/hashing.ts +71 -0
package/docs/examples/health.ts +94 -0
package/docs/examples/helpers.ts +171 -0
package/docs/examples/hooks.ts +54 -0
package/docs/examples/i18n.ts +117 -0
package/docs/examples/inertia.ts +81 -0
package/docs/examples/locks.ts +120 -0
package/docs/examples/logger.ts +166 -0
package/docs/examples/mail.ts +263 -0
package/docs/examples/middleware.ts +119 -0
package/docs/examples/migrations.ts +126 -0
package/docs/examples/models.ts +239 -0
package/docs/examples/notification.ts +124 -0
package/docs/examples/pages.ts +82 -0
package/docs/examples/providers.ts +123 -0
package/docs/examples/queues.ts +254 -0
package/docs/examples/rate-limiting.ts +42 -0
package/docs/examples/redis.ts +99 -0
package/docs/examples/request-response.ts +197 -0
package/docs/examples/routing.ts +186 -0
package/docs/examples/scheduling.ts +62 -0
package/docs/examples/sessions.ts +102 -0
package/docs/examples/static-files.ts +63 -0
package/docs/examples/storage.ts +132 -0
package/docs/examples/telemetry.ts +127 -0
package/docs/examples/templates.ts +58 -0
package/docs/examples/testing.ts +215 -0
package/docs/examples/transformer.ts +141 -0
package/docs/examples/transformers.ts +49 -0
package/docs/examples/url-builder.ts +86 -0
package/docs/examples/validation.ts +102 -0
package/docs/examples/views.tsx +62 -0
package/docs/examples/vite.ts +106 -0
package/docs/factories.md +166 -0
package/docs/getting-started.md +290 -0
package/docs/hashing.md +259 -0
package/docs/health.md +225 -0
package/docs/helpers.md +347 -0
package/docs/hono.md +186 -0
package/docs/hooks.md +118 -0
package/docs/i18n.md +302 -0
package/docs/inertia.md +241 -0
package/docs/locks.md +323 -0
package/docs/logger.md +436 -0
package/docs/mail.md +751 -0
package/docs/middleware.md +425 -0
package/docs/migrations.md +476 -0
package/docs/models.md +810 -0
package/docs/notifications.md +474 -0
package/docs/openapi.md +111 -0
package/docs/packages.md +118 -0
package/docs/pages.md +217 -0
package/docs/providers.md +363 -0
package/docs/queues.md +679 -0
package/docs/rate-limiting.md +155 -0
package/docs/redis.md +178 -0
package/docs/request-response.md +953 -0
package/docs/routing.md +804 -0
package/docs/scheduling.md +110 -0
package/docs/security.md +85 -0
package/docs/sessions.md +354 -0
package/docs/social-auth.md +174 -0
package/docs/static-files.md +211 -0
package/docs/storage.md +452 -0
package/docs/telemetry.md +263 -0
package/docs/templates.md +314 -0
package/docs/testing.md +376 -0
package/docs/transformers.md +381 -0
package/docs/url-builder.md +295 -0
package/docs/validation.md +288 -0
package/docs/views.md +267 -0
package/docs/vite.md +434 -0
package/docs/watch.md +118 -0
package/llms-full.txt +19816 -0
package/llms.txt +127 -0
package/package.json +42 -7

package/docs/vite.md ADDED Viewed

@@ -0,0 +1,434 @@
+# Vite
+Wire a modern frontend build — bundling, hashed filenames, hot module reload —
+to Keel's server-rendered HTML, the way modern full-stack frameworks do. There are two
+halves:
+- **`keelVite()`** — a plugin for `vite.config.ts` (from `@shaferllc/keel/vite`).
+  It configures the build and, while the dev server runs, writes a `public/hot`
+  marker file.
+- **`Vite`** — a server service (from `@shaferllc/keel/core`) that renders the
+  `<script>`/`<link>` tags for your entrypoints and resolves asset URLs.
+The service switches modes automatically. When the dev server is running the
+`hot` file exists, so tags point at it with HMR; otherwise it reads the build
+manifest and emits hashed, split, preloaded production tags. Tag generation is
+pure string work, so it runs on Node and on the edge alike — only reading the
+manifest from disk touches the filesystem.
+## Setup
+Install Vite (it's an optional peer dependency):
+```bash
+npm install -D vite
+```
+Add `vite.config.ts` at your project root and register the plugin with your
+entrypoints:
+```ts
+import { defineConfig } from "vite";
+import { keelVite } from "@shaferllc/keel/vite";
+export default defineConfig({
+  plugins: [
+    keelVite({
+      entrypoints: ["resources/js/app.ts"],
+      // Optional: full-reload the browser when a server view changes.
+      reload: ["resources/views/**/*.tsx"],
+    }),
+  ],
+});
+```
+Create the entrypoint (and import your CSS from it so Vite bundles it):
+```ts
+// resources/js/app.ts
+import "../css/app.css";
+console.log("⚓ Keel + Vite");
+```
+Bind the `Vite` service in a provider and load the manifest/hot file once at
+boot:
+```ts
+import { ServiceProvider, singleton, Vite } from "@shaferllc/keel/core";
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    singleton(Vite, () => new Vite({ entrypoints: ["resources/js/app.ts"] }));
+  }
+  async boot(): Promise<void> {
+    await this.app.make(Vite).loadFromDisk();
+  }
+}
+```
+Add the client scripts and ignore the build artifacts:
+```jsonc
+// package.json
+"scripts": {
+  "dev:client": "vite",         // dev server with HMR (writes public/hot)
+  "build:client": "vite build"  // production build → public/assets + manifest
+}
+```
+```gitignore
+public/hot
+public/assets/
+```
+## Rendering the tags
+Drop the helpers into your JSX layout's `<head>`. `viteReactRefresh()` comes
+first (it's a no-op unless you use React); `viteTags()` renders the entrypoint:
+```tsx
+import { viteTags, viteReactRefresh } from "@shaferllc/keel/core";
+export const Layout = ({ title, children }) => (
+  <html>
+    <head>
+      <title>{title}</title>
+      {viteReactRefresh()}
+      {viteTags("resources/js/app.ts")}
+    </head>
+    <body>{children}</body>
+  </html>
+);
+```
+Both return raw HTML (a Hono `HtmlEscapedString`), so they render unescaped in
+JSX. For an asset that isn't imported by your JS — an image or font referenced
+straight from a template — use `viteAsset()`, which returns the dev-server URL in
+development and the hashed URL in production:
+```tsx
+<img src={viteAsset("resources/images/logo.png")} alt="Logo" />
+```
+## Dev vs. production
+Run **two** processes in development — the Vite dev server and the Keel server:
+```bash
+npm run dev:client   # terminal 1 — Vite + HMR, writes public/hot
+npm run dev          # terminal 2 — the Keel app
+```
+With `public/hot` present, `viteTags()` renders the Vite client plus a module
+script pointing at the dev server:
+```html
+<script type="module" src="http://localhost:5173/@vite/client"></script>
+<script type="module" src="http://localhost:5173/resources/js/app.ts"></script>
+```
+For production, build once — `vite build` writes hashed files and
+`public/assets/.vite/manifest.json` — and the same call renders the manifest's
+output, with the CSS extracted to a `<link>` and imported chunks preloaded:
+```html
+<link rel="stylesheet" href="/assets/app-ghi789.css">
+<link rel="modulepreload" href="/assets/vendor-def456.js">
+<script type="module" src="/assets/app-abc123.js"></script>
+```
+Serve those built files with the [static middleware](./static-files.md) pointed
+at `public/` (Keel's default) — a request for `/assets/app-abc123.js` maps to
+`public/assets/app-abc123.js`:
+```ts
+this.use(serveStatic({ root: "./public" }));
+```
+## Multiple entrypoints
+Each entrypoint produces its own bundle. List them in the config and tag whichever
+a page needs — shared vendor chunks are preloaded once, deduplicated:
+```ts
+keelVite({ entrypoints: ["resources/js/app.ts", "resources/js/admin.ts"] });
+```
+```tsx
+{viteTags(["resources/js/app.ts", "resources/js/admin.ts"])}
+```
+## React (and other frameworks)
+Add the React plugin to `vite.config.ts` and keep `viteReactRefresh()` before
+`viteTags()` in your layout — it injects the Fast Refresh preamble in
+development and renders nothing in production:
+```ts
+import react from "@vitejs/plugin-react";
+export default defineConfig({
+  plugins: [keelVite({ entrypoints: ["resources/js/app.tsx"] }), react()],
+});
+```
+This is exactly what the [Inertia](./inertia.md) adapter's root view uses to load
+its client bundle.
+## Serving from a CDN
+Set `assetsUrl` to your CDN base in **both** the plugin and the service, then
+upload `public/assets` after building:
+```ts
+keelVite({ entrypoints: ["resources/js/app.ts"], assetsUrl: "https://cdn.example.com" });
+new Vite({ entrypoints: ["resources/js/app.ts"], assetsUrl: "https://cdn.example.com" });
+```
+Production tags then point at `https://cdn.example.com/app-abc123.js`.
+## Custom tag attributes
+Pass `scriptAttributes` / `styleAttributes` to add attributes to the generated
+tags — as a static object, or a function that decides per asset:
+```ts
+new Vite({
+  entrypoints: ["resources/js/app.ts"],
+  scriptAttributes: { defer: true, crossorigin: "anonymous" },
+  styleAttributes: ({ src }) =>
+    src.includes("admin") ? { "data-turbo-track": "reload" } : undefined,
+});
+```
+A `true` value renders a bare attribute (`defer`); `false`/`undefined` drops it.
+## On the edge
+There's no filesystem on Workers, so skip `loadFromDisk` and hand the bundled
+manifest straight in — bundle `manifest.json` as a JSON import and pass it to
+`useManifest`:
+```ts
+import manifest from "../public/assets/.vite/manifest.json";
+singleton(Vite, () => new Vite({ entrypoints: ["resources/js/app.ts"] }).useManifest(manifest));
+```
+Tag generation from there is pure and edge-safe.
+## Related
+Vite pairs with [views](./views.md) (the JSX layout that renders the tags),
+[static files](./static-files.md) (serving the build in production), and
+[Inertia](./inertia.md) (whose root view loads the client bundle through it).
+---
+## API reference
+### `keelVite(options)` — `@shaferllc/keel/vite`
+`keelVite(options: KeelViteOptions): Plugin[]`
+The build-time plugin for `vite.config.ts`. Configures the manifest, output
+directory, entrypoints, and `base`, and manages the `public/hot` dev marker.
+```ts
+export default defineConfig({
+  plugins: [keelVite({ entrypoints: ["resources/js/app.ts"] })],
+});
+```
+**Notes:** returns an array (spread into `plugins`). Sets `build.manifest`,
+`build.outDir` (= `buildDirectory`), a flat `build.assetsDir`, and
+`rollupOptions.input`; `base` is `assetsUrl` for a build and `/` for the dev
+server. It leaves any of these alone if you set them yourself. Throws if
+`entrypoints` is empty.
+#### `KeelViteOptions`
+```ts
+interface KeelViteOptions {
+  entrypoints: string | string[]; // required — one bundle per entry
+  buildDirectory?: string;        // default "public/assets" (match the service)
+  hotFile?: string;               // default "public/hot"
+  assetsUrl?: string;             // default "/assets" (or a CDN base)
+  reload?: string[];              // globs that trigger a full page reload
+}
+```
+`reload` globs support `*`, `**`, and `?`. A change to a matching file sends a
+`full-reload` to the browser — useful for server-rendered views Vite doesn't
+otherwise watch.
+### `Vite` — `@shaferllc/keel/core`
+The server service. Bind it as a singleton, `loadFromDisk()` at boot, and render
+its tags from your views (usually through the `viteTags` helper).
+```ts
+const vite = await new Vite({ entrypoints: ["resources/js/app.ts"] }).loadFromDisk();
+```
+#### `new Vite(options?)`
+`new Vite(options?: ViteOptions)`
+Constructs the service. All options are optional; sensible defaults match the
+plugin.
+```ts
+new Vite({ entrypoints: ["resources/js/app.ts"], assetsUrl: "/assets" });
+```
+#### `loadFromDisk()`
+`loadFromDisk(): Promise<this>`
+Reads the hot file (dev) or the build manifest (prod) from disk. Node only —
+imports `node:fs` dynamically. Call once at boot.
+```ts
+async boot() { await this.app.make(Vite).loadFromDisk(); }
+```
+**Notes:** if neither a hot file nor a manifest exists yet, it resolves anyway;
+the clear error is raised later, when tags are actually generated. In dev it
+re-checks the hot file on each render, so starting the dev server after the app
+still works.
+#### `useManifest(manifest)`
+`useManifest(manifest: Manifest): this`
+Injects a manifest directly instead of reading disk — the edge path.
+```ts
+new Vite({ … }).useManifest(manifest);
+```
+#### `useHotUrl(url)`
+`useHotUrl(url: string | null): this`
+Forces the dev-server URL (or `null` for production), bypassing the hot file.
+```ts
+new Vite({ … }).useHotUrl("http://localhost:5173");
+```
+#### `generateEntryPointsTags(entrypoints?)`
+`generateEntryPointsTags(entrypoints?: string | string[]): HtmlEscapedString`
+The `<script>`/`<link>` tags for the given entrypoints (or the constructor's).
+Dev-server tags with HMR while developing; hashed, preloaded tags in production.
+```ts
+vite.generateEntryPointsTags("resources/js/app.ts");
+```
+**Notes:** the `viteTags()` helper wraps this. Throws if an entrypoint is missing
+from the manifest, or if neither a hot file nor a manifest is available.
+#### `assetPath(asset)`
+`assetPath(asset: string): string`
+The public URL for one asset — the dev-server URL in development, the hashed
+manifest URL in production.
+```ts
+vite.assetPath("resources/images/logo.png");
+```
+**Notes:** the `viteAsset()` helper wraps this. Throws in production if the asset
+isn't in the manifest.
+#### `reactHMR()`
+`reactHMR(): HtmlEscapedString`
+The React Fast Refresh preamble (dev only; empty in production). Render it before
+your entry script when using `@vitejs/plugin-react`.
+```ts
+vite.reactHMR();
+```
+**Notes:** the `viteReactRefresh()` helper wraps this.
+#### `hot()`
+`hot(): string | null`
+The dev-server URL when Vite is running, else `null`. A loaded manifest always
+means production.
+#### `manifest()`
+`manifest(): Manifest`
+The parsed production manifest. Throws a helpful error if no build has been
+loaded.
+### Helpers — `@shaferllc/keel/core`
+Free functions that resolve the app's bound `Vite` instance — use them in views
+without threading the container through.
+```ts
+viteTags(entrypoints?: string | string[]): HtmlEscapedString
+viteAsset(asset: string): string
+viteReactRefresh(): HtmlEscapedString
+```
+Each throws a configuration error if `Vite` isn't bound in a provider.
+### Types
+#### `ViteOptions`
+```ts
+interface ViteOptions {
+  entrypoints?: string | string[];
+  hotFile?: string;         // default "public/hot"
+  buildDirectory?: string;  // default "public/assets"
+  manifestFile?: string;    // default "<buildDirectory>/.vite/manifest.json"
+  assetsUrl?: string;       // default "/assets"
+  scriptAttributes?: ViteAttributes;
+  styleAttributes?: ViteAttributes;
+}
+```
+#### `ViteAttributes`
+```ts
+type ViteAttributes =
+  | Record<string, string | boolean | null | undefined>
+  | ((asset: { src: string; url: string }) => Record<string, AttrValue> | undefined);
+```
+Attributes for generated tags. `true` → a bare attribute; `false`/`null`/
+`undefined` → omitted; a string → `key="value"` (HTML-escaped).
+#### `Manifest` / `ManifestChunk`
+```ts
+type Manifest = Record<string, ManifestChunk>;
+interface ManifestChunk {
+  file: string;
+  name?: string;
+  src?: string;
+  isEntry?: boolean;
+  isDynamicEntry?: boolean;
+  imports?: string[];
+  dynamicImports?: string[];
+  css?: string[];
+  assets?: string[];
+}
+```
+Vite's `manifest.json`, as produced by the build. You rarely touch it directly —
+`generateEntryPointsTags` and `assetPath` read it for you.

package/docs/watch.md ADDED Viewed

@@ -0,0 +1,118 @@
+# Watch
+Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
+scheduled tasks flowing through your app, and shows them in a single-page UI at
+`/watch`, with every request linked to the queries and logs it produced.
+It ships as a Keel [package](./packages.md) and is its reference implementation:
+one `register()` turns it on, and its watchers observe the framework's
+instrumentation event stream — they patch nothing, so installing Watch changes no
+behaviour, only visibility.
+## Install
+```ts
+// bootstrap/providers.ts
+import { WatchServiceProvider } from "@shaferllc/keel/watch";
+export const providers = [AppServiceProvider, WatchServiceProvider];
+```
+Publish the config and create the table:
+```bash
+keel vendor:publish --tag watch-config   # writes config/watch.ts
+keel migrate                             # creates watch_entries
+```
+Then open `http://localhost:3000/watch`.
+> Watch exposes requests, payloads, and stack traces. It is gated shut in
+> production by default (see [Access](#access)) — keep it that way, or lock it
+> down with your own check.
+## What it records
+A tab per type, each behind an on/off switch:
+| Watcher | Records |
+|---------|---------|
+| Requests | method, path, status, duration, headers (auth/cookies redacted) |
+| Queries | SQL, bindings, duration, connection; slow queries are tagged |
+| Exceptions | class, message, stack, the request that threw |
+| Logs | every log line, at any level |
+| Mail | sent messages (subject, recipients, body) |
+| Jobs | queued jobs as they complete or fail |
+| Notifications | deliveries and their channels |
+| Cache | hits and misses *(off by default — noisy)* |
+| Events | app events *(off by default — noisy)* |
+| Schedule | scheduled tasks as they run |
+Clicking any entry shows its full detail and **everything else in its batch** —
+the request it belonged to and every query, log, and exception that request
+produced.
+## Configuration
+`config/watch.ts` (publish it, then edit):
+```ts
+export default {
+  enabled: env("WATCH_ENABLED", true),
+  path: "watch",                 // the dashboard mounts at /watch
+  storage: "database",           // "database" persists; "memory" is a per-process ring
+  connection: undefined,         // which DB connection (default when omitted)
+  table: "watch_entries",
+  limit: 100,                    // API page size; the memory ring is 10× this
+  sampling: 1,                   // record this fraction of entries (0–1)
+  slowQueryMs: 100,              // queries at/above this are tagged "slow"
+  ignorePaths: [],               // request paths to skip
+  retentionHours: 24,            // keel watch:prune deletes entries older than this
+  watchers: { cache: false, event: false /* … the rest default on */ },
+};
+```
+### Storage
+- **`database`** (default) — a `watch_entries` table via any registered
+  connection. Survives restarts, shared across processes; needs `keel migrate`.
+- **`memory`** — a per-process ring buffer. Zero setup, great for a single dev
+  process or the edge; entries vanish on restart and aren't shared.
+## Access
+By default the dashboard is open only when `app.debug` is on or the app isn't in
+production. Anywhere else, lock it to your own check:
+```ts
+import { Watch } from "@shaferllc/keel/watch";
+import { auth } from "@shaferllc/keel/core";
+Watch.auth(() => auth().check() && Boolean(auth().user()?.isAdmin));
+```
+The gate guards the JSON API too, so entries can't be read by anyone the
+dashboard wouldn't show them to.
+## Pruning
+With database storage, keep the table small:
+```bash
+keel watch:prune            # delete entries older than retentionHours
+keel watch:prune --hours=6
+```
+Schedule it (see [Scheduling](./scheduling.md)) to run it automatically.
+## How it works
+Watch never wraps or monkey-patches the framework. The core emits a typed
+[instrumentation event stream](./packages.md#observing-the-framework) —
+`db.query`, `request.handled`, `exception`, `job.*`, and so on — and each watcher
+is just a listener that turns an event into a stored entry, stamped with the
+current request id so related entries group into one batch. Recording is
+fire-and-forget: it never blocks or breaks the request it's watching, and the
+store's own queries are filtered out so it never records itself.
+```