@shaferllc/keel 0.66.0 → 0.68.0

package/docs/configuration.md

@@ -0,0 +1,311 @@
+# Configuration
+
+Keel loads configuration from two sources: environment variables (`.env`) and
+config files (`config/*.ts`). Config files read env vars; your app reads config.
+
+## Environment variables
+
+`.env` holds environment-specific values and secrets. It ships with:
+
+```
+APP_NAME=Keel
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+APP_PORT=3000
+```
+
+`.env` is git-ignored. Commit a `.env.example` with safe defaults so teammates
+know what to set.
+
+### The `env()` helper
+
+Read env vars with `env()`, which coerces obvious types:
+
+```ts
+import { env } from "@shaferllc/keel/core";
+
+env("APP_NAME");                 // "Keel"
+env("APP_DEBUG", false);         // true  (string "true" -> boolean)
+env("APP_PORT", 3000);           // 3000  (coerced to number when the fallback is a number)
+env("MISSING", "default");       // "default"
+```
+
+Coercion follows two rules, and they don't behave the same way:
+
+- **Booleans are always coerced.** The literal strings `"true"` and `"false"`
+  become `true` / `false` regardless of the fallback — even with no fallback at
+  all. So `env("APP_DEBUG")` on `APP_DEBUG=true` returns the boolean `true`, not
+  the string `"true"`.
+- **Numbers are coerced only when the fallback is a number.** `env("APP_PORT", 3000)`
+  returns the number `3000`, but `env("APP_PORT")` returns the *string* `"3000"` —
+  without a numeric fallback there's nothing to signal that a number was wanted.
+  An empty string is never treated as a number.
+
+```ts
+env("APP_PORT");        // "3000"  (string — no numeric fallback)
+env("APP_PORT", 0);     // 3000    (number — fallback is numeric)
+env("APP_DEBUG");       // true    (boolean, even with no fallback)
+```
+
+The generic defaults to `string`, but the return is asserted to `T` at the
+boundary — the runtime value can be a boolean or number even where the type says
+string. Pass a fallback of the type you expect and the type follows it.
+
+Use `env()` **only inside config files**, not scattered through your app. That
+keeps all environment coupling in one layer.
+
+## Config files
+
+Each file in `config/` exports a default object and is loaded under its
+filename. `config/app.ts` becomes the `app` namespace:
+
+```ts
+// config/app.ts
+import { env } from "@shaferllc/keel/core";
+
+export default {
+  name: env("APP_NAME", "Keel"),
+  env: env("APP_ENV", "local"),
+  debug: env("APP_DEBUG", true),
+  url: env("APP_URL", "http://localhost:3000"),
+  port: env("APP_PORT", 3000),
+};
+```
+
+Add more files freely — `config/services.ts`, `config/mail.ts` — and they're
+auto-loaded at boot. No registration needed.
+
+## Reading config
+
+The quickest way is the global `config()` helper — no container needed:
+
+```ts
+import { config } from "@shaferllc/keel/core";
+
+config("app.name");          // "Keel"
+config("app.port", 3000);    // with a fallback
+config("services.stripe.key"); // nested access
+```
+
+It resolves against the active application (registered automatically when the
+`Application` is created). There is a matching `app()` helper that returns the
+container:
+
+```ts
+import { app } from "@shaferllc/keel/core";
+
+app().make(SomeService);
+```
+
+Both `config()` and `app()` throw if no application has been bootstrapped yet —
+`config()` reaches the repository *through* `app()`, so the error is the same
+`No Keel application has been bootstrapped…`. In a normal single-app process the
+`Application` constructor registers itself, so this only bites in tests or
+scripts that skip the bootstrap.
+
+### The long form
+
+Under the hood, `config()` is sugar for resolving the `Config` repository and
+reading with dot notation. You can still do that explicitly:
+
+```ts
+import { Config, app } from "@shaferllc/keel/core";
+
+const config = app().make(Config);
+
+config.get("app.name");                    // "Keel"
+config.get("app.port", 3000);              // with a fallback
+config.get("services.stripe.key");         // nested access
+config.set("app.debug", false);            // override at runtime
+config.all();                              // the whole tree
+```
+
+Note `app()` is a function — call it, then reach into the container
+(`app().make(...)`), not `app.make(...)`.
+
+From within the `Application` there's a shortcut:
+
+```ts
+app().config().get("app.name");
+```
+
+There is **no `has()` method** on `Config`. To check for a key, read it with a
+sentinel fallback and compare, or pass the fallback you'd want anyway:
+
+```ts
+const config = app().make(Config);
+if (config.get("services.stripe.key") !== undefined) {
+  // configured
+}
+```
+
+### Missing keys and fallbacks
+
+`get()` walks the key segment by segment. If any segment is missing — or a
+segment isn't an object it can descend into — it returns the fallback (or
+`undefined` when you gave none) rather than throwing:
+
+```ts
+config("services.stripe.key", "");   // "" when unset — never throws
+config("nope.at.all");               // undefined
+```
+
+`set()` creates intermediate objects as it goes, so you can write a deep key
+into an empty tree; and `all()` returns the repository's live object by
+reference — mutating it mutates the config. Treat `all()` as read-only.
+
+## How loading works
+
+At boot, `Application`:
+
+1. Loads `.env` via `dotenv`.
+2. Reads every `*.ts` / `*.js` file in `config/`.
+3. Registers each under its filename in the `Config` repository.
+
+So `config/mail.ts` is reachable at `config('mail.*')` with zero wiring. On
+Workers (no filesystem) skip discovery and pass a config object inline —
+`boot(providers, { discoverConfig: false, config })` — and it's merged under its
+top-level keys the same way. See
+[`src/core/application.ts`](../src/core/application.ts) (`loadConfig`) and
+[`src/core/config.ts`](../src/core/config.ts).
+
+---
+
+## API reference
+
+### `env(key, fallback?)`
+
+`env<T = string>(key: string, fallback?: T): T`
+
+Reads `process.env[key]`, coercing `"true"`/`"false"` to booleans and numeric
+strings to numbers, with a typed fallback when the variable is unset.
+
+```ts
+const debug = env("APP_DEBUG", false); // boolean
+const port = env("APP_PORT", 3000);    // number
+const name = env("APP_NAME", "Keel");  // string
+```
+
+**Notes:** returns the fallback (or `undefined`) when the var is not set.
+Boolean coercion always happens; number coercion happens **only when `fallback`
+is a number** and the raw value is non-empty and numeric. Otherwise the raw
+string is returned. The result is asserted to `T`, so at runtime the value may
+not match the declared type unless your fallback matches the intended type.
+
+### `config(key, fallback?)`
+
+`config<T = unknown>(key: string, fallback?: T): T`
+
+Global helper: resolves the `Config` repository from the active application and
+reads `key` with dot notation.
+
+```ts
+config("app.name");            // unknown -> narrow or cast
+config<number>("app.port", 3000);
+config("services.stripe.key", "");
+```
+
+**Notes:** thin sugar for `app().make(Config).get(key, fallback)`. Throws
+`No Keel application has been bootstrapped…` if there is no active application.
+Returns the fallback (or `undefined`) for any missing key; never throws on a
+missing key.
+
+### `app()`
+
+`app(): Application`
+
+Returns the active application container — the one registered by the most recent
+`Application` constructor.
+
+```ts
+app().make(Config);
+app().config().get("app.name");
+```
+
+**Notes:** throws `No Keel application has been bootstrapped…` when no
+`Application` has been created. `app` is a function; call it before reaching into
+the container. In a single-app process the current application is set
+automatically at construction, so you rarely register it by hand.
+
+### `Config`
+
+The dot-notation config repository. You normally resolve it from the container
+(`app().make(Config)`) rather than constructing it, but the constructor is public
+for tests and standalone use.
+
+#### `new Config(items?)`
+
+`new Config(items?: ConfigData)`
+
+Creates a repository over the given data (default `{}`).
+
+```ts
+const repo = new Config({ app: { name: "Keel", port: 3000 } });
+repo.get("app.port"); // 3000
+```
+
+**Notes:** the object is held by reference, not cloned — later `set()` calls and
+`all()` operate on the same object you passed in.
+
+#### `get(key, fallback?)`
+
+`get<T = unknown>(key: string, fallback?: T): T`
+
+Reads a value by dot-notation key, descending one segment at a time.
+
+```ts
+repo.get("app.name");             // value
+repo.get("app.port", 3000);       // fallback if unset
+repo.get<string>("services.key"); // typed read
+```
+
+**Notes:** returns `fallback` (or `undefined`) if any segment is missing or a
+segment isn't an object it can descend into. Never throws for a missing key. The
+value is asserted to `T` — no runtime validation.
+
+#### `set(key, value)`
+
+`set(key: string, value: unknown): void`
+
+Writes a value at a dot-notation key, creating intermediate objects as needed.
+
+```ts
+repo.set("app.debug", false);
+repo.set("services.stripe.key", "sk_test_…"); // creates `services` on the way
+```
+
+**Notes:** mutates the repository in place. If an intermediate segment exists but
+isn't an object (or is `null`), it's overwritten with a fresh object.
+
+#### `all()`
+
+`all(): ConfigData`
+
+Returns the entire config tree.
+
+```ts
+const tree = repo.all();
+```
+
+**Notes:** returns the live internal object **by reference**, not a copy —
+mutating the result mutates the repository. Treat it as read-only.
+
+> There is no `has()` method. Check presence with `get(key) !== undefined`, or
+> pass the fallback you want when the key is absent.
+
+### Interfaces & types
+
+#### `ConfigData`
+
+`type ConfigData = Record<string, unknown>`
+
+The shape of the config tree: a plain string-keyed object, nested arbitrarily.
+Use it to type a config object you build and merge in yourself (for example, the
+inline config passed to `boot({ discoverConfig: false, config })` on Workers).
+
+```ts
+const data: ConfigData = {
+  app: { name: "Keel", port: 3000 },
+};
+```

package/docs/console.md

@@ -0,0 +1,356 @@
+# The Console
+
+Keel ships with a console for running the server and generating code. The binary
+is `bin/keel.ts`; npm scripts wrap it with `tsx`.
+
+```bash
+npm run keel <command> [args]
+# e.g.
+npm run keel routes
+```
+
+You can also invoke it directly: `npx tsx bin/keel.ts <command>`.
+
+Every command boots the full application first — the same container, config, and
+providers your HTTP requests get. The `serve` and `routes` commands use that
+booted app; the `make:*` generators don't need it, they just stamp files onto
+disk. Commands are wired up with [commander](https://github.com/tj/commander.js)
+in [`src/core/cli/index.ts`](../src/core/cli/index.ts), and the code-generation
+templates live in [`src/core/cli/stubs.ts`](../src/core/cli/stubs.ts).
+
+## Command reference
+
+| Command | Argument | Generates / does |
+| --- | --- | --- |
+| `serve` | `--port <n>` | Start the HTTP server |
+| `routes` | — | List every registered route |
+| `make:controller` | `<name>` `[-r]` | `app/Controllers/<Name>Controller.ts` |
+| `make:provider` | `<name>` | `app/Providers/<Name>ServiceProvider.ts` |
+| `make:middleware` | `<name>` | `app/Http/Middleware/<name>Middleware.ts` |
+| `make:factory` | `<model>` | `database/factories/<Model>Factory.ts` |
+| `make:seeder` | `<name>` | `database/seeders/<Name>Seeder.ts` |
+| `make:job` | `<name>` | `app/Jobs/<Name>Job.ts` |
+| `make:notification` | `<name>` | `app/Notifications/<Name>Notification.ts` |
+| `make:transformer` | `<name>` `[-m <model>]` | `app/Transformers/<Name>Transformer.ts` |
+| `mcp` | — | Start the [MCP server](./ai.md) for AI agents (stdio) |
+
+Every generator normalizes the name you pass and refuses to overwrite an existing
+file (see [Generator safety](#generator-safety)).
+
+## Runtime commands
+
+### `serve`
+
+Start the HTTP server.
+
+```bash
+npm run keel serve
+npm run keel serve --port 8080     # override the port
+```
+
+`serve` builds the [`HttpKernel`](./controllers.md) (reusing a container-bound
+one if you've registered your own, otherwise constructing a fresh one), hands its
+Hono app to `@hono/node-server`, and listens. On boot it prints:
+
+```
+⚓ Keel listening on http://localhost:3000
+```
+
+The port resolves in this order: the `--port` flag, then `config('app.port')`
+(from the `APP_PORT` env var), then `3000`. The app name in the banner comes from
+`config('app.name')`, defaulting to `Keel`. For a watch-mode dev server that
+restarts on change, use `npm run dev` (which is `serve` under `tsx watch`).
+
+### `routes`
+
+List every registered route, its method(s), and its handler.
+
+```bash
+npm run keel routes
+```
+
+```
+GET          /                        HomeController@index
+GET          /users/:id               HomeController@show  (users.show)
+GET|POST     /form                    Closure
+GET          /favicon.ico             Static
+```
+
+Each row is `methods`, `path`, then the resolved handler. The handler column
+reflects how the route was registered:
+
+- **`Controller@method`** — a `[Controller, "method"]` handler tuple.
+- **`Closure`** — an inline function handler.
+- **`Static`** — a pre-built `Response` served directly.
+
+A trailing `(name)` appears for [named routes](./routing.md). Multiple verbs on
+one path are joined with `|`. If nothing is registered, it prints
+`No routes registered.` instead.
+
+### `mcp`
+
+Start the Model Context Protocol server over stdio, exposing Keel's docs, public
+API, and generators to AI agents:
+
+```bash
+npm run keel mcp        # or the shipped `keel-mcp` bin in a consuming app
+```
+
+See [Building with AI](./ai.md) for how to connect it to Claude Code, Cursor, or
+any MCP client, and the tools it provides.
+
+## Generators
+
+Each `make:*` command normalizes the name you give it and writes a single file.
+Name normalization is suffix-aware and case-insensitive: it strips a trailing
+suffix if present, PascalCases the base, then re-appends the canonical suffix.
+So `Post`, `post`, and `PostController` all yield `PostController` — you can pass
+whichever form reads naturally.
+
+Generated stubs import their base classes and types from `@shaferllc/keel/core`
+— the published package's core entry point — so they resolve out of the box in a
+project that has `@shaferllc/keel` installed.
+
+### `make:controller`
+
+Generate a controller in `app/Controllers/`.
+
+```bash
+npm run keel make:controller Post
+# -> app/Controllers/PostController.ts
+```
+
+The name is normalized: `Post`, `post`, and `PostController` all produce
+`PostController`. The default stub is a single `index` action:
+
+```ts
+import type { Ctx } from "@shaferllc/keel/core";
+
+export class PostController {
+  index(c: Ctx) {
+    return c.json({ controller: "PostController", action: "index" });
+  }
+}
+```
+
+Pass `-r` / `--resource` for a full RESTful resource controller with the seven
+standard actions (`index`, `create`, `store`, `show`, `edit`, `update`,
+`destroy`):
+
+```bash
+npm run keel make:controller Post --resource
+# -> app/Controllers/PostController.ts
+```
+
+```ts
+import type { Ctx } from "@shaferllc/keel/core";
+
+export class PostController {
+  index(c: Ctx) {
+    return c.json({ action: "index" });
+  }
+
+  create(c: Ctx) {
+    return c.json({ action: "create" });
+  }
+
+  // ...store, show, edit, update, destroy
+}
+```
+
+Wire it up with `Route.resource(...)` — see [Controllers](./controllers.md).
+
+### `make:provider`
+
+Generate a service provider in `app/Providers/`.
+
+```bash
+npm run keel make:provider Billing
+# -> app/Providers/BillingServiceProvider.ts
+```
+
+```ts
+import { ServiceProvider } from "@shaferllc/keel/core";
+
+export class BillingServiceProvider extends ServiceProvider {
+  register(): void {
+    // Bind services into the container here.
+  }
+
+  boot(): void {
+    // Resolve and wire things up here.
+  }
+}
+```
+
+Remember to add it to `bootstrap/providers.ts` — generation doesn't register it
+for you. See [Service Providers](./providers.md).
+
+### `make:middleware`
+
+Generate an HTTP middleware in `app/Http/Middleware/`.
+
+```bash
+npm run keel make:middleware Auth
+# -> app/Http/Middleware/authMiddleware.ts
+```
+
+The class name is normalized to `AuthMiddleware`, but the **file** and the
+exported constant are camelCased (`authMiddleware`). The stub is a Hono
+`MiddlewareHandler` with before/after seams around `next()`:
+
+```ts
+import type { MiddlewareHandler } from "hono";
+
+export const authMiddleware: MiddlewareHandler = async (c, next) => {
+  // ...before
+  await next();
+  // ...after
+};
+```
+
+This is the one stub that imports from `hono` rather than the Keel core. See
+[Middleware](./middleware.md).
+
+### `make:factory`
+
+Generate a model factory in `database/factories/`.
+
+```bash
+npm run keel make:factory User
+# -> database/factories/UserFactory.ts
+```
+
+`make:factory` takes a **model** name (no suffix stripped) and generates a
+`<Model>Factory.ts`. The stub imports the model and exports a lowercase-named
+factory built with the `factory()` helper:
+
+```ts
+import { factory } from "@shaferllc/keel/core";
+import { User } from "../../app/Models/User.js";
+
+export const userFactory = factory(User, (f) => ({
+  // Describe one User's attributes; `f` is a Faker.
+  name: f.name(),
+  email: f.email(),
+}));
+```
+
+It assumes a matching model at `app/Models/<Model>.ts` — create that first. See
+[Factories & Seeders](./factories.md).
+
+### `make:seeder`
+
+Generate a database seeder in `database/seeders/`.
+
+```bash
+npm run keel make:seeder Database
+# -> database/seeders/DatabaseSeeder.ts
+```
+
+```ts
+import { Seeder } from "@shaferllc/keel/core";
+
+export class DatabaseSeeder extends Seeder {
+  async run(): Promise<void> {
+    // Populate the database, e.g.:
+    // await userFactory.count(10).create();
+  }
+}
+```
+
+See [Factories & Seeders](./factories.md) for running them.
+
+### `make:job`
+
+Generate a queued job in `app/Jobs/`.
+
+```bash
+npm run keel make:job SendWelcome
+# -> app/Jobs/SendWelcomeJob.ts
+```
+
+```ts
+import { Job } from "@shaferllc/keel/core";
+
+export class SendWelcomeJob extends Job {
+  constructor(/* pass the data this job needs */) {
+    super();
+  }
+
+  async handle(): Promise<void> {
+    // Do the background work here.
+  }
+}
+```
+
+The `handle()` method holds the work; the constructor takes whatever data the
+job needs to carry onto the queue. See [Queues & Jobs](./queues.md) for
+dispatching them.
+
+### `make:notification`
+
+Generate a notification in `app/Notifications/`.
+
+```bash
+npm run keel make:notification InvoicePaid
+# -> app/Notifications/InvoicePaidNotification.ts
+```
+
+```ts
+import { Notification, type Notifiable, type MailContent } from "@shaferllc/keel/core";
+
+export class InvoicePaidNotification extends Notification {
+  via(_notifiable: Notifiable): string[] {
+    return ["mail"];
+  }
+
+  toMail(_notifiable: Notifiable): MailContent {
+    return {
+      subject: "InvoicePaidNotification",
+      text: "Notification body.",
+    };
+  }
+}
+```
+
+`via()` returns the channels to deliver on; `toMail()` builds the message for the
+mail channel. See [Notifications](./notifications.md) for sending them.
+
+## Generator safety
+
+Generators never clobber your work. Before writing, each one checks whether the
+target file already exists; if it does, it prints an error, sets a non-zero exit
+code, and writes nothing:
+
+```
+✗ Controller already exists: app/Controllers/PostController.ts
+```
+
+Only when the path is free does it create any missing parent directories and
+write the stub, confirming with:
+
+```
+✓ Created Controller: app/Controllers/PostController.ts
+```
+
+Delete the existing file first if you truly mean to regenerate it.
+
+## Adding your own commands
+
+Commands are defined with [commander](https://github.com/tj/commander.js) in
+[`src/core/cli/index.ts`](../src/core/cli/index.ts). Register a new one on the
+`program`:
+
+```ts
+program
+  .command("cache:clear")
+  .description("Clear the application cache")
+  .action(async () => {
+    const app = await createApplication();
+    // ...your logic, with full access to the container
+  });
+```
+
+Because commands boot the application, they get the same container, config, and
+providers your HTTP requests do.