@shaferllc/keel 0.68.0 → 0.77.0

package/AGENTS.md

@@ -89,6 +89,7 @@ right imports and target path. Then wire it up.
 | Job | `keel make:job SendWelcome` | `dispatch(new SendWelcomeJob())` |
 | Notification | `keel make:notification Paid` | `notify(user, new PaidNotification())` |
 | Transformer | `keel make:transformer User` | return it from a controller |
+| Package | `keel make:package billing` | a `PackageProvider` — see [`docs/packages.md`](./docs/packages.md) |
 
 **Scaffolding does not write files** via MCP — it returns code + path; you write
 it. The console (`keel make:*`) does write, and refuses to overwrite.
@@ -112,6 +113,7 @@ router.get("/posts", [PostController, "index"]).name("posts.index");
 npm run dev            # example app on http://localhost:3000 (tsx watch)
 npm run serve          # keel serve
 npm run keel -- routes # list registered routes
+npm run keel -- migrate # run pending app + package migrations (also migrate:status, migrate:rollback)
 npm run keel -- make:controller Foo
 npm run mcp            # start the MCP server over stdio (dev)
 npm test               # node --test over tests/*.test.ts

package/README.md

@@ -108,6 +108,9 @@ npm run keel serve --port 8080      # start the server on a chosen port
 npm run keel make:controller Post   # -> app/Controllers/PostController.ts
 npm run keel make:provider Billing  # -> app/Providers/BillingServiceProvider.ts
 npm run keel make:middleware Auth   # -> app/Http/Middleware/authMiddleware.ts
+npm run keel make:page users/[id]   # -> resources/pages/users/[id].tsx
+npm run keel make:command greet     # -> app/Commands/greet.ts
+npm run keel repl                   # a shell with the app booted
 npm run keel mcp                    # start the MCP server (docs + API for AI agents)
 ```
 
@@ -206,31 +209,38 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Models](./docs/models.md) | Active-record: find/create/save, casts, relations |
 | [Migrations](./docs/migrations.md) | Schema builder + migrator, dialect-aware |
 | [Factories & Seeders](./docs/factories.md) | Built-in Faker, model factories, seeders |
-| [Mail](./docs/mail.md) | Fluent mailer, pluggable transports, edge-safe |
-| [Queues & Jobs](./docs/queues.md) | Dispatch jobs, pluggable drivers, workers |
+| [Mail](./docs/mail.md) | Fluent mailer, pluggable transports, `sendLater()`, attachments |
+| [Queues & Jobs](./docs/queues.md) | Dispatch jobs, retries + backoff, dead-letter, workers |
 | [Task Scheduling](./docs/scheduling.md) | Cron-style recurring tasks, one trigger |
 | [Notifications](./docs/notifications.md) | Multi-channel (mail/db), queueable |
 | [Broadcasting](./docs/broadcasting.md) | Real-time channels, pluggable, presence auth |
+| [API Resources](./docs/api-resources.md) | CRUD REST API from a model; deny-by-default access, row-level scope |
 | [Transformers](./docs/transformers.md) | Shape models into API JSON; conditional fields, relations |
 | [Events](./docs/events.md) | Emit/listen decoupling, async listeners |
 | [Service Broker](./docs/broker.md) | Moleculer-style services, call/emit, pluggable transport |
 | [Cache](./docs/cache.md) | TTLs, the remember pattern, pluggable stores |
+| [Locks](./docs/locks.md) | Distributed locks with ownership + TTL, pluggable stores |
 | [Redis](./docs/redis.md) | Pluggable client, memory driver, cache adapter |
-| [Logger](./docs/logger.md) | Structured logging, per-request `reqId`, redaction |
+| [Logger](./docs/logger.md) | Structured logging, sinks, per-request `reqId`, redaction |
 | [Static Files](./docs/static-files.md) | serveStatic(), caching, dot-file safety |
 | [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), signed URLs, direct uploads |
 | [Health Checks](./docs/health.md) | `/health/live` + `/health/ready`, pluggable checks |
+| [Telemetry](./docs/telemetry.md) | Tracing, W3C context, OTLP export — no SDK |
+| [Internationalization](./docs/i18n.md) | ICU messages, `Intl` formatters, locale detection |
+| [Pages](./docs/pages.md) | Page-based routing — a file is a route |
+| [Packages](./docs/packages.md) | Redistributable slices of an app: routes, migrations, commands |
+| [Watch](./docs/watch.md) | Debug dashboard — requests, queries, jobs, logs at `/watch` |
 | [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
 | [Templates](./docs/templates.md) | `{{ }}` + `@`-tag templating engine, edge-safe |
 | [Middleware](./docs/middleware.md) | Global middleware, writing your own |
 | [Rate Limiting](./docs/rate-limiting.md) | rateLimiter() middleware, per-key buckets |
 | [Errors](./docs/errors.md) | HTTP exceptions, debug page, custom handlers |
-| [Testing](./docs/testing.md) | Inject requests, fluent response assertions |
+| [Testing](./docs/testing.md) | Inject requests, fakes, spies, time travel, db assertions |
 | [Debugging](./docs/debugging.md) | dump() and dd() (dump-and-die) |
 | [Validation](./docs/validation.md) | `validate()` with Zod, auto-422 field errors |
 | [Inertia](./docs/inertia.md) | Server-side Inertia.js adapter |
 | [Vite](./docs/vite.md) | Frontend build: HMR in dev, hashed manifest in prod |
-| [The Console](./docs/console.md) | `serve`, `routes`, `make:*` generators |
+| [The Console](./docs/console.md) | Typed commands, prompts, terminal UI, REPL, `make:*` |
 | [Architecture](./docs/architecture.md) | Container, kernel, request lifecycle |
 | [Built on Hono](./docs/hono.md) | The Hono layer underneath, and using it directly |
 | [Building with AI](./docs/ai.md) | MCP server, `AGENTS.md`, `llms.txt`, agent workflow |

package/dist/api/api.config.stub

@@ -0,0 +1,9 @@
+/**
+ * Keel API-resource defaults.
+ * Published with `keel vendor:publish --tag api-config`.
+ */
+export default {
+  // Default list page size, and the hard ceiling on ?perPage=.
+  perPage: 25,
+  maxPerPage: 100,
+};

package/dist/api/config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * API-resource defaults. Read off `config("api")`, so an app can set global
+ * pagination limits in `config/api.ts`; every `apiResource()` inherits them and
+ * can override per-resource.
+ */
+export interface ApiConfig {
+    /** Default page size for list endpoints. */
+    perPage: number;
+    /** Hard ceiling on `?perPage=` — the guard against "give me everything". */
+    maxPerPage: number;
+}
+export declare const defaultConfig: ApiConfig;
+export declare function apiDefaults(): ApiConfig;

package/dist/api/config.js

@@ -0,0 +1,14 @@
+/**
+ * API-resource defaults. Read off `config("api")`, so an app can set global
+ * pagination limits in `config/api.ts`; every `apiResource()` inherits them and
+ * can override per-resource.
+ */
+import { config } from "../core/helpers.js";
+export const defaultConfig = {
+    perPage: 25,
+    maxPerPage: 100,
+};
+export function apiDefaults() {
+    const raw = config("api", {});
+    return { ...defaultConfig, ...raw };
+}

package/dist/api/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Keel API resources — a full CRUD REST API from a model, imported from
+ * `@shaferllc/keel/api`.
+ *
+ *   import { apiResource } from "@shaferllc/keel/api";
+ *   apiResource(router, Post, { filter: ["status"], body: PostSchema, access: { read: true } });
+ *
+ * The generated routes are documented automatically by `@shaferllc/keel/openapi`.
+ */
+export { apiResource } from "./resource.js";
+export type { ApiResourceOptions, ApiAccess, Access, ApiAction, ApiTransform, ModelStatic, } from "./resource.js";
+export { ApiServiceProvider } from "./provider.js";
+export { defaultConfig, apiDefaults } from "./config.js";
+export type { ApiConfig } from "./config.js";
+export { parseListParams, applyListParams } from "./query.js";
+export type { ListParams, ListQueryOptions } from "./query.js";

package/dist/api/index.js

@@ -0,0 +1,13 @@
+/**
+ * Keel API resources — a full CRUD REST API from a model, imported from
+ * `@shaferllc/keel/api`.
+ *
+ *   import { apiResource } from "@shaferllc/keel/api";
+ *   apiResource(router, Post, { filter: ["status"], body: PostSchema, access: { read: true } });
+ *
+ * The generated routes are documented automatically by `@shaferllc/keel/openapi`.
+ */
+export { apiResource } from "./resource.js";
+export { ApiServiceProvider } from "./provider.js";
+export { defaultConfig, apiDefaults } from "./config.js";
+export { parseListParams, applyListParams } from "./query.js";

package/dist/api/provider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Optional provider for the API-resource layer. `apiResource()` works without it —
+ * it just reads sensible defaults. Register this to override the pagination
+ * defaults in `config/api.ts` and to publish that stub.
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class ApiServiceProvider extends PackageProvider {
+    readonly name = "api";
+    register(): void;
+}

package/dist/api/provider.js

@@ -0,0 +1,17 @@
+/**
+ * Optional provider for the API-resource layer. `apiResource()` works without it —
+ * it just reads sensible defaults. Register this to override the pagination
+ * defaults in `config/api.ts` and to publish that stub.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PackageProvider } from "../core/package.js";
+import { defaultConfig } from "./config.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export class ApiServiceProvider extends PackageProvider {
+    name = "api";
+    register() {
+        this.mergeConfig("api", defaultConfig);
+        this.publishes({ [join(here, "api.config.stub")]: "config/api.ts" }, "api-config");
+    }
+}

package/dist/api/query.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Turn the query string of a list request into filters, sorting, and a page —
+ * safely. The cardinal rule of an auto-generated API: **never** let the client
+ * filter or sort by an arbitrary column. Everything here is checked against an
+ * allow-list; anything not on it is silently ignored, not passed to SQL. That's
+ * what keeps `?password=…` or `?sort=secret_column` from doing anything.
+ */
+import type { Ctx } from "../core/http/router.js";
+import type { QueryBuilder } from "../core/database.js";
+export interface ListQueryOptions {
+    /** Columns a client may filter on (`?status=published`). */
+    filter: string[];
+    /** Columns a client may sort by (`?sort=title,-createdAt`). */
+    sort: string[];
+    /** Default page size. */
+    perPage: number;
+    /** Maximum `?perPage=`. */
+    maxPerPage: number;
+}
+export interface ListParams {
+    page: number;
+    perPage: number;
+    filters: Array<{
+        column: string;
+        value: string;
+    }>;
+    sort: Array<{
+        column: string;
+        direction: "asc" | "desc";
+    }>;
+}
+/** Parse (and allow-list) the list query params. */
+export declare function parseListParams(c: Ctx, opts: ListQueryOptions): ListParams;
+/** Apply parsed filters and sorting to a query builder. */
+export declare function applyListParams(query: QueryBuilder, params: ListParams): QueryBuilder;

package/dist/api/query.js

@@ -0,0 +1,42 @@
+/**
+ * Turn the query string of a list request into filters, sorting, and a page —
+ * safely. The cardinal rule of an auto-generated API: **never** let the client
+ * filter or sort by an arbitrary column. Everything here is checked against an
+ * allow-list; anything not on it is silently ignored, not passed to SQL. That's
+ * what keeps `?password=…` or `?sort=secret_column` from doing anything.
+ */
+/** Query keys that control pagination/sorting, never treated as filters. */
+const RESERVED = new Set(["page", "perPage", "per_page", "sort", "q", "limit", "offset"]);
+function toInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.trunc(n) : fallback;
+}
+/** Parse (and allow-list) the list query params. */
+export function parseListParams(c, opts) {
+    const q = c.req.query();
+    const page = Math.max(1, toInt(q.page, 1));
+    const perPage = Math.min(Math.max(1, toInt(q.perPage ?? q.per_page, opts.perPage)), opts.maxPerPage);
+    const allowFilter = new Set(opts.filter);
+    const filters = Object.entries(q)
+        .filter(([key]) => !RESERVED.has(key) && allowFilter.has(key))
+        .map(([column, value]) => ({ column, value }));
+    const allowSort = new Set(opts.sort);
+    const sort = (q.sort ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => s.startsWith("-")
+        ? { column: s.slice(1), direction: "desc" }
+        : { column: s, direction: "asc" })
+        .filter((s) => allowSort.has(s.column));
+    return { page, perPage, filters, sort };
+}
+/** Apply parsed filters and sorting to a query builder. */
+export function applyListParams(query, params) {
+    let q = query;
+    for (const f of params.filters)
+        q = q.where(f.column, f.value);
+    for (const s of params.sort)
+        q = q.orderBy(s.column, s.direction);
+    return q;
+}

package/dist/api/resource.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `apiResource(router, Model, options)` — a full CRUD REST API from a Keel model:
+ * explicit, server-side, and composed from pieces you already have. It registers
+ * real routes (so the OpenAPI package
+ * documents them for free), runs writes through the model's mass-assignment guard
+ * and your Zod schema, paginates and allow-list-filters reads, and gates every
+ * action.
+ *
+ *   apiResource(router, Post, {
+ *     filter: ["status", "authorId"],
+ *     sort: ["createdAt", "title"],
+ *     body: PostSchema,
+ *     access: { read: true, write: (c) => isEditor(c) },
+ *     scope: (q) => q.where("deleted", false),
+ *   });
+ *
+ * Access is **deny by default**: an action with no `access` rule returns 403.
+ * That's the safe default for a generated API — you opt routes open, never shut.
+ */
+import type { Router, Ctx } from "../core/http/router.js";
+import type { QueryBuilder, Row } from "../core/database.js";
+import type { Model } from "../core/model.js";
+import type { Schema } from "../core/validation.js";
+/** A Model subclass (the class itself, with its statics). */
+export type ModelStatic = typeof Model;
+/** A CRUD action. */
+export type ApiAction = "list" | "read" | "create" | "update" | "delete";
+/** An access rule: a flat allow/deny, or a per-request predicate. */
+export type Access = boolean | ((c: Ctx) => boolean | Promise<boolean>);
+/**
+ * Access rules per action, with shorthands. Resolution for an action prefers its
+ * own key, then the read/write shorthand, then `all`; absent → denied.
+ */
+export interface ApiAccess {
+    /** Fallback for every action. */
+    all?: Access;
+    /** Shorthand for `list` + `get`. */
+    read?: Access;
+    /** Shorthand for `create` + `update` + `delete`. */
+    write?: Access;
+    list?: Access;
+    /** The single-item read (GET /:id). */
+    get?: Access;
+    create?: Access;
+    update?: Access;
+    delete?: Access;
+}
+/** How a model is turned into API output — a function, or a Keel Transformer. */
+export type ApiTransform = ((model: Model, c: Ctx) => unknown) | {
+    item(value: Model): unknown;
+    collection(values: Model[]): unknown[];
+};
+export interface ApiResourceOptions {
+    /** Base path. Default: the model's table name. */
+    path?: string;
+    /** Route-name prefix. Default: the path. */
+    name?: string;
+    /** Only expose these actions. */
+    only?: ApiAction[];
+    /** Expose everything except these. */
+    except?: ApiAction[];
+    /** Columns clients may filter on. Empty = no filtering. */
+    filter?: string[];
+    /** Columns clients may sort by. Empty = no sorting. */
+    sort?: string[];
+    /** Default page size (overrides `config("api.perPage")`). */
+    perPage?: number;
+    /** Max page size (overrides `config("api.maxPerPage")`). */
+    maxPerPage?: number;
+    /** Zod (or Zod-like) schema validating create + update bodies. */
+    body?: Schema<unknown>;
+    /** Schema for create only (overrides `body`). */
+    createBody?: Schema<unknown>;
+    /** Schema for update only (overrides `body`). */
+    updateBody?: Schema<unknown>;
+    /** Access rules. Deny by default. */
+    access?: ApiAccess;
+    /**
+     * Constrain the base query for **every** row operation — list, read, update,
+     * delete. This is row-level security: a row outside the scope reads as 404, so
+     * it can't be fetched, changed, or removed.
+     */
+    scope?: (query: QueryBuilder, c: Ctx) => QueryBuilder | void;
+    /** Shape the output. Default: `model.toJSON()`. */
+    transform?: ApiTransform;
+    /** Mutate the write payload before it's saved (set an owner id, timestamps…). */
+    beforeWrite?: (data: Row, c: Ctx, action: "create" | "update") => Row | Promise<Row>;
+    /** OpenAPI tags for these routes. Default: `[path]`. */
+    tags?: string[];
+    /** Singular display name used in generated doc summaries. Default: the model's class name. */
+    label?: string;
+}
+export declare function apiResource(router: Router, model: ModelStatic, options?: ApiResourceOptions): void;

package/dist/api/resource.js

@@ -0,0 +1,185 @@
+/**
+ * `apiResource(router, Model, options)` — a full CRUD REST API from a Keel model:
+ * explicit, server-side, and composed from pieces you already have. It registers
+ * real routes (so the OpenAPI package
+ * documents them for free), runs writes through the model's mass-assignment guard
+ * and your Zod schema, paginates and allow-list-filters reads, and gates every
+ * action.
+ *
+ *   apiResource(router, Post, {
+ *     filter: ["status", "authorId"],
+ *     sort: ["createdAt", "title"],
+ *     body: PostSchema,
+ *     access: { read: true, write: (c) => isEditor(c) },
+ *     scope: (q) => q.where("deleted", false),
+ *   });
+ *
+ * Access is **deny by default**: an action with no `access` rule returns 403.
+ * That's the safe default for a generated API — you opt routes open, never shut.
+ */
+import { validate } from "../core/validation.js";
+import { ForbiddenException, NotFoundException } from "../core/exceptions.js";
+import { apiDefaults } from "./config.js";
+import { parseListParams, applyListParams } from "./query.js";
+/**
+ * The route-config key `@shaferllc/keel/openapi` reads operation docs from. It's
+ * declared here — not imported from openapi — so this package never depends on
+ * openapi: install the two together and routes are documented; install only api
+ * and the metadata is inert. Keep this value in sync with openapi's `OPENAPI_KEY`.
+ */
+const OPENAPI_CONFIG_KEY = "openapi";
+/** Wrap operation docs for a route's `.config()`, without importing openapi. */
+function openApiConfig(doc) {
+    return { [OPENAPI_CONFIG_KEY]: doc };
+}
+const ALL_ACTIONS = ["list", "read", "create", "update", "delete"];
+function resolveActions(options) {
+    let actions = options.only ?? ALL_ACTIONS;
+    if (options.except)
+        actions = actions.filter((a) => !options.except.includes(a));
+    return new Set(actions);
+}
+/** Resolve the access rule for an action; undefined (no rule) means deny. */
+function ruleFor(access, action) {
+    const a = access ?? {};
+    switch (action) {
+        case "list":
+            return a.list ?? a.read ?? a.all;
+        case "read":
+            return a.get ?? a.read ?? a.all;
+        case "create":
+            return a.create ?? a.write ?? a.all;
+        case "update":
+            return a.update ?? a.write ?? a.all;
+        case "delete":
+            return a.delete ?? a.write ?? a.all;
+    }
+}
+/** Evaluate access; throw 403 if denied. */
+async function authorize(access, action, c) {
+    const rule = ruleFor(access, action);
+    const ok = rule === undefined ? false : typeof rule === "boolean" ? rule : await rule(c);
+    if (!ok)
+        throw new ForbiddenException();
+}
+function transformOne(t, model, c) {
+    if (!t)
+        return model.toJSON();
+    return typeof t === "function" ? t(model, c) : t.item(model);
+}
+function transformMany(t, models, c) {
+    if (!t)
+        return models.map((m) => m.toJSON());
+    return typeof t === "function" ? models.map((m) => t(m, c)) : t.collection(models);
+}
+export function apiResource(router, model, options = {}) {
+    const defaults = apiDefaults();
+    const path = options.path ?? model.table;
+    const base = "/" + path.replace(/^\/|\/$/g, "");
+    const name = options.name ?? path;
+    const pk = model.primaryKey;
+    const label = options.label ?? model.name;
+    const tags = options.tags ?? [path];
+    const perPage = options.perPage ?? defaults.perPage;
+    const maxPerPage = options.maxPerPage ?? defaults.maxPerPage;
+    const actions = resolveActions(options);
+    /** The base query with any row-level scope applied. */
+    const scoped = (c) => {
+        const q = model.query();
+        if (!options.scope)
+            return q;
+        return options.scope(q, c) ?? q;
+    };
+    /** Find one row within scope, or 404. */
+    const findScoped = async (c) => {
+        const row = await scoped(c).where(pk, c.req.param("id")).first();
+        if (!row)
+            throw new NotFoundException(`${model.name} not found`);
+        return new model(row);
+    };
+    const readBody = async (c, schema) => {
+        const raw = (await c.req.json().catch(() => ({})));
+        return schema ? (await validate(schema, raw)) : raw;
+    };
+    if (actions.has("list")) {
+        router
+            .get(base, async (c) => {
+            await authorize(options.access, "list", c);
+            const params = parseListParams(c, {
+                filter: options.filter ?? [],
+                sort: options.sort ?? [],
+                perPage,
+                maxPerPage,
+            });
+            const query = applyListParams(scoped(c), params);
+            const result = await query.paginate(params.page, params.perPage);
+            const models = result.data.map((row) => new model(row));
+            return c.json({
+                data: transformMany(options.transform, models, c),
+                meta: {
+                    total: result.total,
+                    perPage: result.perPage,
+                    currentPage: result.currentPage,
+                    lastPage: result.lastPage,
+                },
+            });
+        })
+            .name(`${name}.list`)
+            .config(openApiConfig({ summary: `List ${path}`, tags }));
+    }
+    if (actions.has("read")) {
+        router
+            .get(`${base}/:id`, async (c) => {
+            await authorize(options.access, "read", c);
+            const found = await findScoped(c);
+            return c.json({ data: transformOne(options.transform, found, c) });
+        })
+            .name(`${name}.read`)
+            .config(openApiConfig({ summary: `Fetch ${label}`, tags }));
+    }
+    if (actions.has("create")) {
+        const schema = options.createBody ?? options.body;
+        router
+            .post(base, async (c) => {
+            await authorize(options.access, "create", c);
+            let data = await readBody(c, schema);
+            if (options.beforeWrite)
+                data = await options.beforeWrite(data, c, "create");
+            const created = await model.create(data);
+            return c.json({ data: transformOne(options.transform, created, c) }, 201);
+        })
+            .name(`${name}.create`)
+            .config(openApiConfig({
+            summary: `Create ${label}`,
+            tags,
+            ...(schema ? { request: { body: schema } } : {}),
+            responses: { 201: { description: `The created ${label}` } },
+        }));
+    }
+    if (actions.has("update")) {
+        const schema = options.updateBody ?? options.body;
+        router
+            .route(["PUT", "PATCH"], `${base}/:id`, async (c) => {
+            await authorize(options.access, "update", c);
+            const found = await findScoped(c);
+            let data = await readBody(c, schema);
+            if (options.beforeWrite)
+                data = await options.beforeWrite(data, c, "update");
+            await found.update(data);
+            return c.json({ data: transformOne(options.transform, found, c) });
+        })
+            .name(`${name}.update`)
+            .config(openApiConfig({ summary: `Update ${label}`, tags, ...(schema ? { request: { body: schema } } : {}) }));
+    }
+    if (actions.has("delete")) {
+        router
+            .delete(`${base}/:id`, async (c) => {
+            await authorize(options.access, "delete", c);
+            const found = await findScoped(c);
+            await found.delete();
+            return c.body(null, 204);
+        })
+            .name(`${name}.delete`)
+            .config(openApiConfig({ summary: `Delete ${label}`, tags, responses: { 204: { description: "Deleted" } } }));
+    }
+}

package/dist/core/application.js

@@ -14,6 +14,7 @@ import { View } from "./view.js";
 import { Events } from "./events.js";
 import { Cache } from "./cache.js";
 import { Logger } from "./logger.js";
+import { MigrationRegistry, CommandRegistry, PublishRegistry } from "./package.js";
 import { setApplication } from "./helpers.js";
 export class Application extends Container {
     basePath;
@@ -34,6 +35,11 @@ export class Application extends Container {
         this.singleton(View, () => new View());
         this.singleton(Events, () => new Events());
         this.singleton(Cache, () => new Cache());
+        // Package-system registries: what providers contribute for the console
+        // (`keel migrate`, `keel vendor:publish`) and the CLI to pick up after boot.
+        this.singleton(MigrationRegistry, () => new MigrationRegistry());
+        this.singleton(CommandRegistry, () => new CommandRegistry());
+        this.singleton(PublishRegistry, () => new PublishRegistry());
         this.singleton(Logger, (app) => new Logger({
             level: app.config().get("logger.level", "info"),
             pretty: Boolean(app.config().get("app.debug", false)),

package/dist/core/cache.d.ts

@@ -6,8 +6,7 @@
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
  *
- * Features borrowed from bentocache (AdonisJS' cache), kept inside keel's
- * single-store, edge-safe model:
+ * The resilience features, kept inside keel's single-store, edge-safe model:
  *
  *   - Stampede protection — concurrent `remember()` calls for the same cold key
  *     run the factory ONCE and share the result, instead of dog-piling.

package/dist/core/cache.js

@@ -6,8 +6,7 @@
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
  *
- * Features borrowed from bentocache (AdonisJS' cache), kept inside keel's
- * single-store, edge-safe model:
+ * The resilience features, kept inside keel's single-store, edge-safe model:
  *
  *   - Stampede protection — concurrent `remember()` calls for the same cold key
  *     run the factory ONCE and share the result, instead of dog-piling.
@@ -23,6 +22,7 @@
  * reads as a miss. O(1) invalidation, no key-set bookkeeping, works on any
  * `CacheStore`.
  */
+import { instrument, currentRequestId } from "./instrumentation.js";
 /** The default in-memory store. */
 export class MemoryStore {
     data = new Map();
@@ -116,6 +116,13 @@ export class Cache {
     }
     async get(key, fallback) {
         const entry = await this.entry(key);
+        const hit = !!entry && !(entry.e && entry.e < Date.now());
+        const requestId = currentRequestId();
+        instrument(hit ? "cache.hit" : "cache.miss", {
+            key,
+            store: this.store.constructor.name,
+            ...(requestId ? { requestId } : {}),
+        });
         if (!entry)
             return fallback;
         if (entry.e && entry.e < Date.now())

package/dist/core/cli/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The Keel console. `keel <command>`.
+ *
+ * Commands:
+ *   keel serve                 start the HTTP server
+ *   keel make:controller Foo   generate app/Controllers/FooController.ts
+ *   keel make:provider Foo      generate app/Providers/FooServiceProvider.ts
+ *   keel make:middleware Foo    generate app/Http/Middleware/foo.ts
+ *   keel make:factory User      generate database/factories/UserFactory.ts
+ *   keel make:seeder Database   generate database/seeders/DatabaseSeeder.ts
+ *   keel make:job SendWelcome   generate app/Jobs/SendWelcomeJob.ts
+ *   keel make:notification Paid generate app/Notifications/PaidNotification.ts
+ *   keel make:transformer User  generate app/Transformers/UserTransformer.ts
+ *   keel routes                 list registered routes
+ *   keel mcp                    start the MCP server (docs + API for AI agents)
+ */
+import type { Application } from "../application.js";
+/** What the console needs from your app: a way to build it. */
+export interface ConsoleOptions {
+    /**
+     * Build and boot the application. The console is handed this rather than
+     * importing it, because a framework that imports an *application* has its
+     * dependency pointing the wrong way — and that one import is what kept this
+     * file out of the published build for so long.
+     */
+    createApplication: () => Promise<Application>;
+}
+export declare function run(argv: string[], options: ConsoleOptions): Promise<void>;