@shaferllc/keel 0.66.0 → 0.68.0

package/docs/ai.md

@@ -0,0 +1,128 @@
+# Building Keel apps with AI
+
+Keel is built to be **written with an AI agent**. This page is the map of the
+AI-facing surface: an MCP server, machine-readable docs (`llms.txt` /
+`llms-full.txt`), an agent playbook (`AGENTS.md`), and code generators an agent
+can drive directly.
+
+If you only read one thing: point your agent at the [MCP server](#the-mcp-server)
+and have it call `keel_overview` first.
+
+## Why this exists
+
+An agent working in a Keel app needs three things: to know the **conventions**
+(where things live, what imports to use), to **look up APIs and guides** without
+hallucinating, and to **generate correct boilerplate**. Keel provides each as a
+first-class, always-current surface — generated from the same source as the
+human docs, so they never drift.
+
+## The MCP server
+
+Keel ships an [MCP](https://modelcontextprotocol.io) server that exposes its
+documentation, the full public API surface (380+ exports), the generators, and
+its conventions to any MCP-capable client.
+
+### Connect it
+
+**Claude Code**, in an app that depends on `@shaferllc/keel`:
+
+```bash
+claude mcp add keel -- npx -y keel-mcp
+```
+
+Hacking on the framework repo itself:
+
+```bash
+claude mcp add keel -- npm --prefix /path/to/keel run mcp
+```
+
+**`.mcp.json`, Cursor, Windsurf, or any client** that reads the standard config:
+
+```json
+{
+  "mcpServers": {
+    "keel": { "command": "npx", "args": ["-y", "keel-mcp"] }
+  }
+}
+```
+
+The server speaks over stdio and prints its banner to **stderr** (stdout is the
+protocol channel). It resolves docs from the installed `@shaferllc/keel`
+package, so it always matches your installed version.
+
+### Tools
+
+| Tool | What it does |
+|------|--------------|
+| `keel_overview` | Version, conventions, folder layout, every doc topic, and the generators. **Call this first.** |
+| `keel_search_docs` | Full-text search across all guides; returns snippets + slugs. |
+| `keel_read_doc` | A full guide by slug, optionally with its runnable example appended. |
+| `keel_search_api` | Search the public export surface; returns each symbol's module and its guide. |
+| `keel_list_generators` | The `keel make:*` generators, what they produce, and their flags. |
+| `keel_scaffold` | Generate a controller/provider/middleware/factory/seeder/job/notification/transformer stub. Returns code + target path — it does **not** write to disk. |
+
+### Resources
+
+- `keel://overview` — the same orientation text as `keel_overview`
+- `keel://llms-full` — every guide concatenated (drop into a fresh context)
+- `keel://docs/<slug>` — one resource per guide (e.g. `keel://docs/routing`)
+
+### A typical agent loop
+
+1. `keel_overview` → learn the conventions and topic list.
+2. `keel_search_docs { query: "belongsToMany pivot" }` → find the right guide.
+3. `keel_read_doc { slug: "models", include_example: true }` → read it in full.
+4. `keel_scaffold { kind: "controller", name: "Post", resource: true }` → get the stub.
+5. Write the file, add the route, run `npm run typecheck`.
+
+## `llms.txt` and `llms-full.txt`
+
+At the package root:
+
+- **[`llms.txt`](../llms.txt)** — the [llms.txt-spec](https://llmstxt.org) index:
+  a titled, summarized, linked list of every guide and example. Good for AI
+  crawlers and "add this URL as context" flows.
+- **[`llms-full.txt`](../llms-full.txt)** — every guide concatenated into one
+  file (~17k lines), ordered from getting-started outward. Paste it into a fresh
+  context window when you want the agent to have all of Keel at once.
+
+Both are generated by `npm run build:ai` from `docs/` and shipped in the npm
+package, so they're available at `node_modules/@shaferllc/keel/llms-full.txt`.
+
+## `AGENTS.md`
+
+[`AGENTS.md`](../AGENTS.md) at the repo root is the agent playbook: the one
+import rule, the folder map, the container/provider mental model, a "how to add
+X" table, the commands, and the guardrails (typecheck before finishing, rerun
+`build:ai` after doc changes). It follows the emerging cross-tool `AGENTS.md`
+convention and is shipped in the package. `CLAUDE.md` points to it.
+
+## Generators
+
+Everything scaffoldable is available three ways, all emitting the same stubs:
+
+- **MCP:** `keel_scaffold` (returns code; you write it)
+- **Console:** `keel make:controller Post -r` (writes the file, won't overwrite)
+- **By hand:** copy from `keel_read_doc` examples
+
+See [the console guide](./console.md) for the full command list.
+
+## Keeping it current
+
+The AI surface is generated, not hand-maintained:
+
+```bash
+npm run build:ai   # regenerates llms.txt, llms-full.txt, docs/ai-manifest.json
+```
+
+`npm run build` runs it automatically before compiling. After you add or edit a
+doc, or change the public exports in `src/core/index.ts`, run `build:ai` so the
+manifest the MCP server reads stays in sync. `docs/ai-manifest.json` is the
+single machine-readable index (docs + API + generators); treat it as generated
+output.
+
+## See also
+
+- [Getting Started](./getting-started.md) — the human first-hour guide
+- [Architecture](./architecture.md) — how a request flows through Keel
+- [The Console](./console.md) — the `keel` command and generators

package/docs/architecture.md

@@ -0,0 +1,331 @@
+# Architecture
+
+Keel is small on purpose. This page maps the pieces and traces a request from
+socket to response. Nothing here is magic — every layer is a short, readable file
+in `src/core/`, and this guide is mostly a reading order for it.
+
+## The layers
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  bin/keel.ts            console entry (serve, make:*, …)  │
+├─────────────────────────────────────────────────────────┤
+│  bootstrap/app.ts       createApplication()              │
+│    └─ boots providers, binds HTTP kernel, loads routes   │
+├─────────────────────────────────────────────────────────┤
+│  Application  (extends Container)                        │
+│    ├─ loads .env + config/*.ts                           │
+│    └─ provider register() → boot() lifecycle             │
+├─────────────────────────────────────────────────────────┤
+│  Container    bind / singleton / instance / make        │
+├─────────────────────────────────────────────────────────┤
+│  HttpKernel   global middleware → compiles routes → Hono │
+├─────────────────────────────────────────────────────────┤
+│  @hono/node-server   the actual HTTP server              │
+└─────────────────────────────────────────────────────────┘
+```
+
+Read it top to bottom as the flow of control at boot, and bottom to top as the
+flow of a request. The console and the server both enter through
+`createApplication()` — the difference is only what they do with the app once
+it's booted (serve it, or run a command against it).
+
+## Core building blocks
+
+- **`Container`** ([container.ts](../src/core/container.ts)) — the dependency
+  registry. Two maps (bindings, cached instances) and a `make()` resolver.
+- **`Application`** ([application.ts](../src/core/application.ts)) — a
+  `Container` with a lifecycle: load env, auto-load config, register and boot
+  providers.
+- **`Config`** ([config.ts](../src/core/config.ts)) — a dot-notation repository
+  plus the `env()` coercion helper.
+- **`ServiceProvider`** ([provider.ts](../src/core/provider.ts)) — the
+  `register()` / `boot()` contract.
+- **`Router`** ([http/router.ts](../src/core/http/router.ts)) — collects route
+  definitions; resolves controller tuples out of the container.
+- **`HttpKernel`** ([http/kernel.ts](../src/core/http/kernel.ts)) — holds global
+  middleware and compiles the router onto a Hono instance.
+
+## The container is the center
+
+Everything else hangs off the container. `Application` **is** a `Container` — it
+extends it — so the same `bind` / `singleton` / `instance` / `make` surface that
+registers a service also holds `Config`, `Router`, `View`, the `Logger`, and
+your own controllers.
+
+```ts
+app.singleton(Router, (a) => new Router(a));   // registered at construction
+const router = app.make(Router);               // resolved anywhere later
+```
+
+Two properties make this the spine of the framework:
+
+- **Everything resolves through one place.** A controller doesn't `new` its
+  dependencies — it receives the container in its constructor and pulls what it
+  needs, so tests can swap any binding for a fake without touching the code under
+  test.
+- **Classes auto-resolve.** `make(SomeClass)` builds `SomeClass` even with no
+  explicit binding, handing its constructor the container. You only register a
+  binding when construction needs configuration or should be shared.
+
+`bind` gives a fresh value each resolve; `singleton` caches after the first;
+`instance` stores an already-built value. The global helpers (`make()`,
+`bind()`, `config()`, `app()`) are thin wrappers that resolve against the active
+application, so you rarely thread the container by hand. See
+[The Service Container](./container.md) for the full API and resolution rules.
+
+## Service providers wire it up
+
+Providers are the seams where your services enter the container. Each has two
+phases, and the split matters:
+
+```ts
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    // Bind only. Nothing else is guaranteed registered yet.
+    bind("clock", () => new Date().toISOString());
+  }
+
+  boot(): void {
+    // Every provider has registered — safe to resolve and wire things.
+  }
+}
+```
+
+`Application.boot()` runs **all** providers' `register()` before **any**
+provider's `boot()`. That ordering is the whole point: `register()` may only
+add bindings, so `boot()` can safely depend on anything any provider bound,
+regardless of order. Reaching for another service inside `register()` is the
+classic bug — the binding may not exist yet. [Service Providers](./providers.md)
+goes deeper.
+
+## Boot sequence
+
+When `keel serve` runs:
+
+1. **`createApplication()`** constructs the `Application` with the project root.
+2. The constructor registers the active application (for global helpers) and
+   binds core services (`Config`, `Router`, `View`, `Events`, `Cache`,
+   `Logger`).
+3. **`app.boot(providers)`**:
+   - loads `.env`, then every `config/*.ts` file into the `Config` repository,
+   - runs each provider's **`register()`** (bind-only phase),
+   - runs each provider's **`boot()`** (wire-up phase).
+4. The HTTP kernel (`app/Http/Kernel.ts`) is bound as a singleton.
+5. `routes/web.ts` registers routes on the `Router`.
+6. `HttpKernel.build()` returns a Hono app; `@hono/node-server` serves it.
+
+Steps 1–3 are identical whether you're serving or running a console command —
+`createApplication()` is the single door in. Only steps 4–6 are HTTP-specific.
+
+## The application object
+
+`Application` is Keel's central object — the [container](./container.md) plus a
+lifecycle. Beyond `register()`/`boot()`, it carries a small ergonomic surface
+modelled on the classic service-app pattern (Feathers' `app`): a settings store,
+an inline plugin hook, and app-level events.
+
+**Configure with a plain function.** `register(Provider)` gives you the
+two-phase register/boot lifecycle; `configure(fn)` is the one-shot alternative
+for inline setup — call a function with the app, chain the next:
+
+```ts
+app
+  .configure((a) => a.set("mail.from", "hi@keel.dev"))
+  .configure(installBilling); // (app) => { … }
+```
+
+**Store app-wide values.** `set`/`get` are a thin façade over the `Config`
+repository, so `app.set("db.url", …)` and `config().get("db.url")` read the same
+store — no second bag to keep in sync:
+
+```ts
+app.set("db.url", process.env.DATABASE_URL);
+const url = app.get<string>("db.url");
+const port = app.get("port", 3000); // typed fallback
+```
+
+**Emit and listen at the app level.** `on`/`once`/`off`/`emit` delegate to the
+[`Events`](./events.md) singleton, so `app.on(...)` and the global `listen()`
+helper share one emitter. Listeners may be async; `emit` awaits them in order:
+
+```ts
+const off = app.on("user.registered", (user) => sendWelcome(user));
+await app.emit("user.registered", user);
+off(); // unsubscribe
+```
+
+### API reference
+
+#### `app.configure(fn)`
+
+Run a `Configurator` — `(app) => unknown` — against the app and return the app
+for chaining. The lightweight alternative to a `ServiceProvider` when you don't
+need the register/boot split.
+
+```ts
+app.configure((a) => a.router().get("/health", () => "ok"));
+```
+
+Notes: runs immediately and synchronously in call order. Its return value is
+ignored (return-for-chaining is the app, not the fn's result). For anything that
+must bind before another service boots, use a provider instead.
+
+#### `app.set(key, value)` / `app.get(key, fallback?)`
+
+Write and read an app-wide value. Both use dot-notation and are backed by
+`Config`, so values set here are visible to `config()` and vice-versa. `set`
+returns the app (chainable); `get` takes an optional typed fallback.
+
+```ts
+app.set("app.name", "Keel");
+config().get("app.name"); // "Keel"
+app.get("app.name"); // "Keel"
+app.get("app.locale", "en"); // fallback when unset
+```
+
+Notes: because the store is shared with `Config`, prefer namespaced keys
+(`"mail.from"`, not `"from"`) to avoid collisions with `config/*.ts` files.
+
+#### `app.on(event, listener)` / `app.once(event, listener)`
+
+Subscribe to an app event; `once` auto-unsubscribes after the first emission.
+Both return an **unsubscribe function**. Delegates to the `Events` singleton.
+
+```ts
+const off = app.on<Order>("order.paid", (o) => fulfil(o));
+```
+
+Notes: the listener signature is `(payload) => void | Promise<void>`. Identical
+to `app.make(Events).on(...)` — the method is sugar so you rarely resolve
+`Events` by hand.
+
+#### `app.off(event, listener)`
+
+Remove a listener registered with `on`/`once`. Returns the app (chainable). Pass
+the *same* function reference used to subscribe.
+
+#### `app.emit(event, payload?)`
+
+Emit an app event, awaiting every listener in registration order. Returns a
+`Promise<void>`. An async listener that rejects propagates out of `emit`.
+
+```ts
+await app.emit("cache.cleared", { at: Date.now() });
+```
+
+## Request lifecycle
+
+For each incoming request:
+
+```
+request
+  → Hono matches the route
+  → contextStorage() stashes the context for the request helpers
+  → context middleware sets c.get("app") = the container
+  → global middleware stack (e.g. requestLogger) runs, in order
+  → the route handler runs:
+        • a closure           → called with (c)
+        • a [Controller, m]   → controller resolved from the container,
+                                 then method(c) is called (DI in the ctor)
+  → the handler's return value becomes the response
+        (a string is wrapped as HTML; a Response passes through)
+  → middleware unwinds on the way back out
+response
+```
+
+A few details worth knowing:
+
+- **The context is stashed per request.** Before your middleware runs, the
+  kernel enables Hono's `contextStorage()`. That's what lets the [request
+  helpers](./request-response.md) (`request`, `param()`, `json()`) reach the
+  current request without you passing `c` around.
+- **Controllers are resolved lazily, per request.** The router turns a
+  `[Controller, method]` tuple into a function that resolves the controller from
+  the container when the route fires — so constructor DI runs against the live
+  app. Tuples may also be `() => import(...)` loaders for code-splitting.
+- **Errors funnel through the kernel.** A thrown `HttpException` renders at its
+  status; anything else is a 500. The kernel content-negotiates — HTML for
+  browsers, JSON otherwise — and hides internals unless `app.debug` is on.
+  Unmatched routes go through the same path as a `NotFoundException`.
+
+[Middleware](./middleware.md) covers the stack in detail, and [Routing](./routing.md)
+covers how handlers are declared and matched.
+
+## Edge-safe by design
+
+Keel's core imports **no** Node built-ins at module load. `fs`, `path`, `url`,
+and `dotenv` are pulled in **dynamically**, and only when filesystem
+discovery is enabled:
+
+```ts
+// application.ts — dynamic, guarded, optional
+const { readdir } = await import("node:fs/promises");
+```
+
+The payoff is that the same `Application`, `Router`, `View`, and query builder
+run unchanged on Cloudflare Workers, Deno, and Bun — anywhere with web-standard
+`fetch`, `Request`, `Response`, and Web Crypto. On Workers, where there's no
+filesystem to scan, you skip discovery and pass config inline:
+
+```ts
+await app.boot(providers, { discoverConfig: false, config: { app: { name: "Keel" } } });
+```
+
+The second argument is `BootOptions`: `discoverConfig` (skip filesystem config
+discovery — the default on the edge) and `config` (an inline config object merged
+in). Together they let the app boot with no filesystem at all.
+
+Everything that would normally reach for a platform API is designed around this
+seam: the [database](./database.md) layer talks to a `Connection` you provide
+rather than importing a driver; signed URLs use Web Crypto's `crypto.subtle`;
+views render to strings with no filesystem. The rule is simple — the core owns
+logic, the platform owns I/O, and the two meet at an interface you supply.
+
+## Two repos: library and starter
+
+Keel is distributed like most frameworks — a **library** you install plus an
+**app** that depends on it:
+
+| Repo | Role |
+|------|------|
+| `shaferllc/keel` | The framework. Published as `@shaferllc/keel`; userland imports `@shaferllc/keel/core`. |
+| `shaferllc/keel-app` | The starter app — clone it to build something. Picks up core updates via `npm update`. |
+
+The split mirrors the classic application-vs-library separation. Your code lives
+in `app/` (controllers, providers, middleware); the framework lives behind the
+package boundary. Because the two are versioned separately, a framework upgrade
+is an ordinary dependency bump — your `app/` doesn't move. [Getting
+Started](./getting-started.md#install) walks through both install paths.
+
+## Design principles
+
+- **One container, resolved everywhere.** Testability and composition follow
+  from routing every dependency through it.
+- **Convention over configuration.** Fixed folders (`app/`, `config/`,
+  `routes/`, `bootstrap/`) mean no manual wiring for the common case.
+- **Thin over clever.** The framework is a few hundred readable lines. When in
+  doubt, open the source — there is no hidden magic.
+- **Wrap the best, own the surface.** Hono does HTTP; Keel owns the developer-
+  facing API so the underlying library can change without breaking your app.
+  [Built on Hono](./hono.md) draws that line precisely.
+- **Edge-safe, driver-agnostic.** The core imports no database driver, no mail
+  SDK, no socket. Every backend — [database](./database.md), [mail](./mail.md),
+  [redis](./redis.md), [queues](./queues.md), [storage](./storage.md),
+  [broadcasting](./broadcasting.md) — plugs in behind a small interface, so the
+  same app runs on Node and on the edge. You bring the driver; Keel brings the
+  ergonomics.
+- **Explicit over implicit.** No hidden runtime magic: body parsing is a method
+  you call, [templates](./templates.md) interpret rather than `eval`, and
+  providers register into one predictable global scope. Boring and predictable
+  beats clever and surprising.
+
+## Extending Keel
+
+The MVP core is deliberately small. Natural extension points:
+
+- **New services** → a service provider that binds them into the container.
+- **New console commands** → add to [cli/index.ts](../src/core/cli/index.ts).
+- **New subsystems** (ORM, queues, mail) → a provider that registers the
+  subsystem plus a `config/*.ts` file for its settings. This is exactly how the
+  roadmap items will land.