@shaferllc/keel 0.74.0 → 0.77.0

package/README.md

@@ -214,6 +214,7 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [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 |

package/dist/api/resource.d.ts

@@ -1,7 +1,7 @@
 /**
- * `apiResource(router, Model, options)` — a full CRUD REST API from a Keel model,
- * the Remult idea done the Keel way: explicit, server-side, and composed from
- * pieces you already have. It registers real routes (so the OpenAPI package
+ * `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.
@@ -87,5 +87,7 @@ export interface ApiResourceOptions {
     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

@@ -1,7 +1,7 @@
 /**
- * `apiResource(router, Model, options)` — a full CRUD REST API from a Keel model,
- * the Remult idea done the Keel way: explicit, server-side, and composed from
- * pieces you already have. It registers real routes (so the OpenAPI package
+ * `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.
@@ -72,16 +72,13 @@ function transformMany(t, models, c) {
         return models.map((m) => m.toJSON());
     return typeof t === "function" ? models.map((m) => t(m, c)) : t.collection(models);
 }
-function singular(word) {
-    return word.endsWith("s") ? word.slice(0, -1) : word;
-}
 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 one = singular(path);
+    const label = options.label ?? model.name;
     const tags = options.tags ?? [path];
     const perPage = options.perPage ?? defaults.perPage;
     const maxPerPage = options.maxPerPage ?? defaults.maxPerPage;
@@ -138,7 +135,7 @@ export function apiResource(router, model, options = {}) {
             return c.json({ data: transformOne(options.transform, found, c) });
         })
             .name(`${name}.read`)
-            .config(openApiConfig({ summary: `Fetch a ${one}`, tags }));
+            .config(openApiConfig({ summary: `Fetch ${label}`, tags }));
     }
     if (actions.has("create")) {
         const schema = options.createBody ?? options.body;
@@ -153,10 +150,10 @@ export function apiResource(router, model, options = {}) {
         })
             .name(`${name}.create`)
             .config(openApiConfig({
-            summary: `Create a ${one}`,
+            summary: `Create ${label}`,
             tags,
             ...(schema ? { request: { body: schema } } : {}),
-            responses: { 201: { description: `The created ${one}` } },
+            responses: { 201: { description: `The created ${label}` } },
         }));
     }
     if (actions.has("update")) {
@@ -172,7 +169,7 @@ export function apiResource(router, model, options = {}) {
             return c.json({ data: transformOne(options.transform, found, c) });
         })
             .name(`${name}.update`)
-            .config(openApiConfig({ summary: `Update a ${one}`, tags, ...(schema ? { request: { body: schema } } : {}) }));
+            .config(openApiConfig({ summary: `Update ${label}`, tags, ...(schema ? { request: { body: schema } } : {}) }));
     }
     if (actions.has("delete")) {
         router
@@ -183,6 +180,6 @@ export function apiResource(router, model, options = {}) {
             return c.body(null, 204);
         })
             .name(`${name}.delete`)
-            .config(openApiConfig({ summary: `Delete a ${one}`, tags, responses: { 204: { description: "Deleted" } } }));
+            .config(openApiConfig({ summary: `Delete ${label}`, tags, responses: { 204: { description: "Deleted" } } }));
     }
 }

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>;

package/dist/core/cli/index.js

@@ -0,0 +1,427 @@
+/**
+ * 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 { mkdir, writeFile, access, readdir, stat, copyFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ConsoleKernel, defineCommand, arg, flag } from "../console.js";
+import { HttpKernel } from "../http/kernel.js";
+import { Router } from "../http/router.js";
+import { getConnection } from "../database.js";
+import { Migrator } from "../migrations.js";
+import { MigrationRegistry, CommandRegistry, PublishRegistry } from "../package.js";
+import { controllerStub, resourceControllerStub, providerStub, middlewareStub, factoryStub, seederStub, jobStub, notificationStub, transformerStub, packageProviderStub, pageStub, commandStub, } from "./stubs.js";
+const basePath = process.cwd();
+async function generate(relPath, contents, label, ui) {
+    const full = join(basePath, relPath);
+    try {
+        await access(full);
+        // Never clobber a file someone has written code in.
+        ui.error(`${label} already exists: ${relPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    catch {
+        // does not exist — proceed
+    }
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, contents);
+    ui.action("create", relPath);
+}
+/** Normalize "foo" / "FooController" into a canonical suffixed class name. */
+function className(name, suffix) {
+    const base = name.replace(new RegExp(`${suffix}$`, "i"), "");
+    const pascal = base.charAt(0).toUpperCase() + base.slice(1);
+    return `${pascal}${suffix}`;
+}
+/** Load every migration under database/migrations/, in filename order. */
+async function discoverMigrations() {
+    const dir = join(basePath, "database/migrations");
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch {
+        return []; // no migrations directory — fine
+    }
+    const out = [];
+    for (const file of files.sort()) {
+        if (!/\.(ts|js|mjs)$/.test(file))
+            continue;
+        const mod = await import(pathToFileURL(join(dir, file)).href);
+        const def = (mod.default ?? mod.migration ?? mod);
+        if (Array.isArray(def))
+            out.push(...def);
+        else if (def && typeof def.up === "function")
+            out.push(def);
+    }
+    return out;
+}
+/** Every migration to run: the app's discovered ones, then package-contributed. */
+async function collectMigrations(app) {
+    return [...(await discoverMigrations()), ...app.make(MigrationRegistry).all()];
+}
+/** A `Migrator` on the default connection, or a friendly error if none is set. */
+function migratorFor() {
+    const { connection, dialect } = getConnection(); // throws if no connection registered
+    return new Migrator(connection, dialect);
+}
+/** Copy a published file/dir into the app, skipping existing files unless forced. */
+async function publishPath(from, toRel, force, ui) {
+    const dest = join(basePath, toRel);
+    const s = await stat(from).catch(() => null);
+    if (!s) {
+        ui.error(`Source not found: ${from}`);
+        return;
+    }
+    if (s.isDirectory()) {
+        for (const item of await readdir(from)) {
+            await publishPath(join(from, item), join(toRel, item), force, ui);
+        }
+        return;
+    }
+    let exists = false;
+    try {
+        await access(dest);
+        exists = true;
+    }
+    catch {
+        // destination is free
+    }
+    if (exists && !force) {
+        ui.action("skip", `${toRel} (exists; pass --force to overwrite)`, "skipped");
+        return;
+    }
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(from, dest);
+    ui.action("publish", toRel);
+}
+export async function run(argv, options) {
+    // Boot the app once so commands share it, and so package providers get a
+    // chance to contribute migrations, commands, and publishables. Scaffolding
+    // commands (`make:*`) don't need it, so a boot failure isn't fatal — it's
+    // surfaced only when a command that needs the app actually runs.
+    let app = null;
+    let bootError;
+    try {
+        app = await options.createApplication();
+    }
+    catch (err) {
+        bootError = err;
+    }
+    const requireApp = () => {
+        if (!app) {
+            console.error("✗ Could not boot the application:");
+            console.error(bootError);
+            process.exit(1);
+        }
+        return app;
+    };
+    /**
+     * Commands your app defines with `defineCommand()`, discovered from
+     * `app/Commands`. They register alongside the built-ins — same kernel, same
+     * typed args and flags — and an app command of the same name wins, so you can
+     * override one.
+     */
+    async function appCommands() {
+        const dir = join(basePath, "app/Commands");
+        const found = [];
+        const files = await readdir(dir).catch(() => null);
+        if (!files)
+            return found; // no app/Commands — the only thing we swallow
+        for (const file of files) {
+            if (!/\.(ts|js|mjs)$/.test(file))
+                continue;
+            let module;
+            try {
+                module = (await import(pathToFileURL(join(dir, file)).href));
+            }
+            catch (error) {
+                // A command file that won't load is a bug you need to see, not a command
+                // that quietly doesn't exist.
+                console.error(`✗ Could not load app/Commands/${file}:`);
+                console.error(error instanceof Error ? error.message : error);
+                process.exitCode = 1;
+                continue;
+            }
+            // Any export that looks like a command counts, so one file can hold several.
+            for (const value of Object.values(module)) {
+                const candidate = value;
+                if (candidate &&
+                    typeof candidate === "object" &&
+                    typeof candidate.name === "string" &&
+                    typeof candidate.run === "function") {
+                    found.push(candidate);
+                }
+            }
+        }
+        return found;
+    }
+    /* ------------------------------- the built-ins ------------------------------ */
+    const serve = defineCommand({
+        name: "serve",
+        description: "Start the HTTP server",
+        flags: { port: flag.number({ alias: "p", description: "port to listen on" }) },
+        async run({ flags, ui }) {
+            const application = requireApp();
+            const kernel = application.bound(HttpKernel)
+                ? application.make(HttpKernel)
+                : new HttpKernel(application);
+            const hono = kernel.build();
+            const port = flags.port ?? Number(application.config().get("app.port", 3000));
+            // Imported here, not at the top: the Node server is only needed to *serve*,
+            // and the console must still load on a machine (or a Worker) that has no
+            // reason to install it.
+            const { serve: listen } = await import("@hono/node-server").catch(() => {
+                throw new Error("`keel serve` needs @hono/node-server. Install it: npm i @hono/node-server");
+            });
+            const server = listen({ fetch: hono.fetch, port }, (info) => {
+                ui.success(`${application.config().get("app.name", "Keel")} listening on http://localhost:${info.port}`);
+            });
+            // Graceful shutdown: stop accepting connections, run the app's shutdown
+            // hooks (and every provider's shutdown()), then exit. `once` so a second
+            // signal isn't swallowed if cleanup hangs — hit Ctrl-C again to force it.
+            const shutdown = async (signal) => {
+                ui.write(`\n${signal} received — shutting down…`);
+                server.close();
+                try {
+                    await application.terminate();
+                }
+                catch (err) {
+                    ui.error(`Error during shutdown: ${String(err)}`);
+                    process.exit(1);
+                }
+                process.exit(0);
+            };
+            process.once("SIGINT", () => void shutdown("SIGINT"));
+            process.once("SIGTERM", () => void shutdown("SIGTERM"));
+            // `serve` stays alive on purpose — the server is the command.
+            await new Promise(() => { });
+        },
+    });
+    const repl = defineCommand({
+        name: "repl",
+        description: "An interactive shell with the application booted",
+        async run() {
+            const { startRepl } = await import("../repl.js");
+            await startRepl(requireApp());
+        },
+    });
+    const mcp = defineCommand({
+        name: "mcp",
+        description: "Start the MCP server (Keel's docs, API, and generators, over stdio)",
+        async run() {
+            const { runMcpServer } = await import("../../mcp/server.js");
+            await runMcpServer();
+        },
+    });
+    const routes = defineCommand({
+        name: "routes",
+        description: "List registered routes",
+        run({ ui }) {
+            const rows = requireApp().make(Router).all();
+            if (!rows.length)
+                return void ui.info("No routes registered.");
+            const table = ui.table(["Method", "Path", "Handler", "Name"]);
+            for (const r of rows) {
+                const handler = Array.isArray(r.handler)
+                    ? `${r.handler[0].name}@${r.handler[1]}`
+                    : r.handler instanceof Response
+                        ? "Static"
+                        : "Closure";
+                table.row([r.methods.join("|"), r.path, handler, r.name ?? ""]);
+            }
+            table.render();
+        },
+    });
+    /* -------------------------------- generators -------------------------------- */
+    const makeController = defineCommand({
+        name: "make:controller",
+        description: "Generate a controller",
+        args: { name: arg.string({ description: "e.g. Post" }) },
+        flags: { resource: flag.boolean({ alias: "r", description: "a RESTful resource controller" }) },
+        async run({ args, flags, ui }) {
+            const cls = className(args.name, "Controller");
+            const stub = flags.resource ? resourceControllerStub(cls) : controllerStub(cls);
+            await generate(`app/Controllers/${cls}.ts`, stub, "Controller", ui);
+        },
+    });
+    const makeProvider = defineCommand({
+        name: "make:provider",
+        description: "Generate a service provider",
+        args: { name: arg.string() },
+        async run({ args, ui }) {
+            const cls = className(args.name, "ServiceProvider");
+            await generate(`app/Providers/${cls}.ts`, providerStub(cls), "Provider", ui);
+        },
+    });
+    const makeMiddleware = defineCommand({
+        name: "make:middleware",
+        description: "Generate an HTTP middleware",
+        args: { name: arg.string() },
+        async run({ args, ui }) {
+            const cls = className(args.name, "Middleware");
+            const file = cls.charAt(0).toLowerCase() + cls.slice(1);
+            await generate(`app/Http/Middleware/${file}.ts`, middlewareStub(cls), "Middleware", ui);
+        },
+    });
+    const makeFactory = defineCommand({
+        name: "make:factory",
+        description: "Generate a model factory",
+        args: { model: arg.string({ description: "e.g. User" }) },
+        async run({ args, ui }) {
+            const cls = className(args.model, "");
+            await generate(`database/factories/${cls}Factory.ts`, factoryStub(cls), "Factory", ui);
+        },
+    });
+    const makeSeeder = defineCommand({
+        name: "make:seeder",
+        description: "Generate a database seeder",
+        args: { name: arg.string() },
+        async run({ args, ui }) {
+            const cls = className(args.name, "Seeder");
+            await generate(`database/seeders/${cls}.ts`, seederStub(cls), "Seeder", ui);
+        },
+    });
+    const makeJob = defineCommand({
+        name: "make:job",
+        description: "Generate a queued job",
+        args: { name: arg.string() },
+        async run({ args, ui }) {
+            const cls = className(args.name, "Job");
+            await generate(`app/Jobs/${cls}.ts`, jobStub(cls), "Job", ui);
+        },
+    });
+    const makePage = defineCommand({
+        name: "make:page",
+        description: "Generate a page — its path is its URL: make:page users/[id]",
+        args: { path: arg.string({ description: "e.g. users/[id]" }) },
+        async run({ args, ui }) {
+            // The path IS the route, so it's used verbatim — no class-name munging.
+            const file = args.path.replace(/^\/+/, "").replace(/\.(tsx|jsx)$/, "");
+            await generate(`resources/pages/${file}.tsx`, pageStub(file), "Page", ui);
+        },
+    });
+    const makeCommand = defineCommand({
+        name: "make:command",
+        description: "Generate a console command (typed args + flags, prompts, UI)",
+        args: { name: arg.string() },
+        async run({ args, ui }) {
+            const file = args.name.replace(/[^a-zA-Z0-9:_-]/g, "");
+            await generate(`app/Commands/${file.replace(/:/g, "-")}.ts`, commandStub(file), "Command", ui);
+        },
+    });
+    const makeNotification = defineCommand({
+        name: "make:notification",
+        description: "Generate a notification",
+        args: { name: arg.string() },
+        async run({ args, ui }) {
+            const cls = className(args.name, "Notification");
+            await generate(`app/Notifications/${cls}.ts`, notificationStub(cls), "Notification", ui);
+        },
+    });
+    const makeTransformer = defineCommand({
+        name: "make:transformer",
+        description: "Generate an API transformer",
+        args: { name: arg.string() },
+        flags: { model: flag.string({ alias: "m", description: "the value it maps (e.g. User)" }) },
+        async run({ args, flags, ui }) {
+            const cls = className(args.name, "Transformer");
+            const model = flags.model ? className(flags.model, "") : cls.replace(/Transformer$/, "");
+            await generate(`app/Transformers/${cls}.ts`, transformerStub(cls, model), "Transformer", ui);
+        },
+    });
+    const makePackage = defineCommand({
+        name: "make:package",
+        description: "Scaffold a Keel package (a PackageProvider skeleton)",
+        args: { name: arg.string() },
+        async run({ args, ui }) {
+            const slug = args.name.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+            const cls = slug.charAt(0).toUpperCase() + slug.slice(1);
+            await generate(`packages/${slug}/${cls}ServiceProvider.ts`, packageProviderStub(slug), "Package", ui);
+        },
+    });
+    /* -------------------------------- migrations -------------------------------- */
+    const migrate = defineCommand({
+        name: "migrate",
+        description: "Run pending database migrations (app + package)",
+        async run({ ui }) {
+            const applied = await migratorFor().up(await collectMigrations(requireApp()));
+            if (!applied.length)
+                return void ui.info("Nothing to migrate.");
+            for (const name of applied)
+                ui.success(`Migrated ${name}`);
+        },
+    });
+    const migrateRollback = defineCommand({
+        name: "migrate:rollback",
+        description: "Roll back the most recent batch of migrations",
+        async run({ ui }) {
+            const rolled = await migratorFor().down(await collectMigrations(requireApp()));
+            if (!rolled.length)
+                return void ui.info("Nothing to roll back.");
+            for (const name of rolled)
+                ui.success(`Rolled back ${name}`);
+        },
+    });
+    const migrateStatus = defineCommand({
+        name: "migrate:status",
+        description: "Show which migrations have run and which are pending",
+        async run({ ui }) {
+            const migrator = migratorFor();
+            const ran = new Set(await migrator.ran());
+            const migrations = await collectMigrations(requireApp());
+            if (!migrations.length)
+                return void ui.info("No migrations found.");
+            const table = ui.table(["Status", "Migration"]);
+            for (const m of migrations)
+                table.row([ran.has(m.name) ? "ran" : "pending", m.name]);
+            table.render();
+        },
+    });
+    const vendorPublish = defineCommand({
+        name: "vendor:publish",
+        description: "Copy package-published files (config, assets) into this app",
+        flags: {
+            tag: flag.string({ description: "only publish files under this tag" }),
+            force: flag.boolean({ description: "overwrite files that already exist" }),
+        },
+        async run({ flags, ui }) {
+            const registry = requireApp().make(PublishRegistry);
+            const entries = registry.all(flags.tag);
+            if (!entries.length) {
+                ui.info(flags.tag ? `Nothing published under tag "${flags.tag}".` : "Nothing to publish.");
+                const tags = registry.tags();
+                if (!flags.tag && tags.length)
+                    ui.info(`Available tags: ${tags.join(", ")}`);
+                return;
+            }
+            for (const entry of entries) {
+                for (const [from, to] of Object.entries(entry.files)) {
+                    await publishPath(from, to, flags.force, ui);
+                }
+            }
+        },
+    });
+    /* ---------------------------------- dispatch -------------------------------- */
+    const kernel = new ConsoleKernel({ binary: "keel" }).register(serve, repl, mcp, routes, makeController, makeProvider, makeMiddleware, makeFactory, makeSeeder, makeJob, makePage, makeCommand, makeNotification, makeTransformer, makePackage, migrate, migrateRollback, migrateStatus, vendorPublish);
+    // Package-contributed commands (a package's `commands([...])`), then the app's —
+    // registered last, so an app command of the same name overrides anything above.
+    if (app)
+        kernel.register(...app.make(CommandRegistry).all());
+    kernel.register(...(await appCommands()));
+    process.exitCode = await kernel.run(argv.slice(2));
+}

package/dist/core/console.d.ts

@@ -80,19 +80,19 @@ type ArgValue<O, T> = Present<O, true> extends true ? T : T | undefined;
 type FlagValue<O, T> = Present<O, false> extends true ? T : T | undefined;
 /** Positional arguments: `keel greet <name>`. */
 export declare const arg: {
-    string<const O extends ArgOptions<string> = Record<never, never>>(options?: O): ArgSpec<ArgValue<O, string>>;
-    number<const O extends ArgOptions<number> = Record<never, never>>(options?: O): ArgSpec<ArgValue<O, number>>;
+    string<const O extends ArgOptions<string> = Record<never, never>>(options?: O & ArgOptions<string>): ArgSpec<ArgValue<O, string>>;
+    number<const O extends ArgOptions<number> = Record<never, never>>(options?: O & ArgOptions<number>): ArgSpec<ArgValue<O, number>>;
     /** Swallows every remaining value. Must be the last argument. */
-    spread<const O extends ArgOptions<string[]> = Record<never, never>>(options?: O): ArgSpec<ArgValue<O, string[]>>;
+    spread<const O extends ArgOptions<string[]> = Record<never, never>>(options?: O & ArgOptions<string[]>): ArgSpec<ArgValue<O, string[]>>;
 };
 /** Named options: `--force`, `-f`, `--name=Ada`. */
 export declare const flag: {
     /** `--force` / `-f`, and `--no-force`. Defaults to `false`, so it's never undefined. */
-    boolean<const O extends FlagOptions<boolean> = Record<never, never>>(options?: O): FlagSpec<boolean>;
-    string<const O extends FlagOptions<string> = Record<never, never>>(options?: O): FlagSpec<FlagValue<O, string>>;
-    number<const O extends FlagOptions<number> = Record<never, never>>(options?: O): FlagSpec<FlagValue<O, number>>;
+    boolean<const O extends FlagOptions<boolean> = Record<never, never>>(options?: O & FlagOptions<boolean>): FlagSpec<boolean>;
+    string<const O extends FlagOptions<string> = Record<never, never>>(options?: O & FlagOptions<string>): FlagSpec<FlagValue<O, string>>;
+    number<const O extends FlagOptions<number> = Record<never, never>>(options?: O & FlagOptions<number>): FlagSpec<FlagValue<O, number>>;
     /** Repeatable: `--tag a --tag b` gives `["a", "b"]`. Defaults to `[]`. */
-    array<const O extends FlagOptions<string[]> = Record<never, never>>(options?: O): FlagSpec<string[]>;
+    array<const O extends FlagOptions<string[]> = Record<never, never>>(options?: O & FlagOptions<string[]>): FlagSpec<string[]>;
 };
 export type ArgsSpec = Record<string, ArgSpec<unknown>>;
 export type FlagsSpec = Record<string, FlagSpec<unknown>>;

package/dist/core/package.d.ts

@@ -25,7 +25,7 @@
  * Application constructor) — routes are compiled onto the kernel later, at build.
  */
 import type { MiddlewareHandler } from "hono";
-import type { Command } from "commander";
+import type { AnyCommand } from "./console.js";
 import { ServiceProvider } from "./provider.js";
 import type { Application } from "./application.js";
 import type { Router, RouteGroup, MiddlewareRef } from "./http/router.js";
@@ -40,15 +40,12 @@ export declare class MigrationRegistry {
     all(): Migration[];
 }
 /** A console command a package adds to `keel`. */
-export interface PackageCommand {
-    /** The command name, e.g. `"watch:prune"`. */
-    name: string;
-    description?: string;
-    /** Add arguments/options to the commander command before its action. */
-    configure?: (cmd: Command) => void;
-    /** What the command does. Receives parsed options and the command. */
-    action: (opts: Record<string, unknown>, cmd: Command) => void | Promise<void>;
-}
+/**
+ * A command a package contributes to the console — the same `defineCommand()`
+ * shape an app uses, so a package's command gets typed args and flags, generated
+ * help, the terminal UI, and the prompt-trapping test story for free.
+ */
+export type PackageCommand = AnyCommand;
 /** Package-contributed console commands, mounted by the CLI after boot. */
 export declare class CommandRegistry {
     private list;

package/dist/core/testing.d.ts

@@ -211,9 +211,10 @@ export declare class CommandResult {
  * You pass the command in, because the console entry point belongs to your app
  * (it's the thing that knows how to build your application), not to the core:
  *
- *   import { run } from "@shaferllc/keel/core/cli";   // or your own bin
+ *   import { run } from "@shaferllc/keel/cli";
+ *   import { createApplication } from "../bootstrap/app.js";
  *
- *   const result = await runCommand(() => run(["node", "keel", "routes"]));
+ *   const result = await runCommand(() => run(["node", "keel", "routes"], { createApplication }));
  *   result.assertSucceeded().assertOutputContains("GET  /users");
  *
  * `console.log`/`warn` are captured as stdout, `console.error` as stderr, and

package/dist/core/testing.js

@@ -608,9 +608,10 @@ export class CommandResult {
  * You pass the command in, because the console entry point belongs to your app
  * (it's the thing that knows how to build your application), not to the core:
  *
- *   import { run } from "@shaferllc/keel/core/cli";   // or your own bin
+ *   import { run } from "@shaferllc/keel/cli";
+ *   import { createApplication } from "../bootstrap/app.js";
  *
- *   const result = await runCommand(() => run(["node", "keel", "routes"]));
+ *   const result = await runCommand(() => run(["node", "keel", "routes"], { createApplication }));
  *   result.assertSucceeded().assertOutputContains("GET  /users");
  *
  * `console.log`/`warn` are captured as stdout, `console.error` as stderr, and

package/dist/openapi/export.js

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

package/dist/watch/prune.js

@@ -5,16 +5,18 @@
  * buffer bounds itself per process, so there's nothing for a separate CLI
  * process to prune.
  */
+import { defineCommand, flag } from "../core/console.js";
 export function pruneCommand(store, config) {
-    return {
+    return defineCommand({
         name: "watch:prune",
         description: "Delete Watch entries older than the retention window",
-        configure: (cmd) => cmd.option("--hours <hours>", "override the retention window (hours)"),
-        action: async (opts) => {
-            const hours = opts.hours ? Number(opts.hours) : config.retentionHours;
-            const before = Date.now() - hours * 3_600_000;
-            const removed = await store.prune(before);
-            console.log(`Pruned ${removed} Watch entr${removed === 1 ? "y" : "ies"} older than ${hours}h.`);
+        flags: { hours: flag.number({ description: "override the retention window (hours)" }) },
+        async run({ flags, ui }) {
+            // A typed flag, so `--hours nonsense` is now a usage error rather than a NaN
+            // that silently prunes everything.
+            const hours = flags.hours ?? config.retentionHours;
+            const removed = await store.prune(Date.now() - hours * 3_600_000);
+            ui.success(`Pruned ${removed} Watch entr${removed === 1 ? "y" : "ies"} older than ${hours}h.`);
         },
-    };
+    });
 }

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.74.0",
+  "version": "0.77.0",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
@@ -15,9 +15,9 @@
     {
       "slug": "api-resources",
       "title": "API Resources",
-      "summary": "apiResource(router, Model, options) generates a full CRUD REST API from a Keel model — the Remult idea done the Keel way: explicit, server-side, and composed from pieces you already have.",
+      "summary": "apiResource(router, Model, options) generates a full CRUD REST API from a Keel model — explicit, server-side, and composed from pieces you already have.",
       "path": "docs/api-resources.md",
-      "example": null
+      "example": "docs/examples/api-resources.ts"
     },
     {
       "slug": "architecture",

package/docs/api-resources.md

@@ -1,8 +1,8 @@
 # API Resources
 
 `apiResource(router, Model, options)` generates a full CRUD REST API from a Keel
-[model](./models.md) — the [Remult](https://remult.dev) idea done the Keel way:
-explicit, server-side, and composed from pieces you already have. It's imported
+[model](./models.md) — explicit, server-side, and composed from pieces you already
+have. It's imported
 from `@shaferllc/keel/api`.
 
 ```ts
@@ -105,14 +105,15 @@ apiResource(router, Post, {
 | `transform` | Output shaping. |
 | `beforeWrite` | Mutate the payload before save. |
 | `tags` | OpenAPI tags for the routes. |
+| `label` | Singular name in doc summaries (default: the model's class name). |
 
 Global pagination defaults live in `config/api.ts` (register the optional
 `ApiServiceProvider`, then `keel vendor:publish --tag api-config`).
 
 ## What this isn't
 
-Remult also ships an isomorphic, type-safe **frontend** client that shares the
-model with the server. Keel deliberately stops at the server boundary: this
+There's no isomorphic frontend client here — no shared model object that runs on
+both sides of the wire. Keel deliberately stops at the server boundary: this
 generates a plain REST API you call however you like (fetch, your Inertia pages,
 a mobile app). That keeps the model server-only and the wire contract explicit —
 and it's exactly the contract the OpenAPI docs describe.

package/docs/console.md

@@ -336,6 +336,30 @@ write the stub, confirming with:
 
 Delete the existing file first if you truly mean to regenerate it.
 
+## Your console entry point
+
+The console ships in the package, and takes your application factory:
+
+```ts
+#!/usr/bin/env tsx
+// bin/keel.ts
+import { run } from "@shaferllc/keel/cli";
+import { createApplication } from "../bootstrap/app.js";
+
+run(process.argv, { createApplication }).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+It's handed `createApplication` 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 the console out of the published build until now.
+
+Commands that need the app (`serve`, `routes`, `migrate`) boot it once and share it.
+Scaffolding commands (`make:*`) don't, so a boot failure isn't fatal — it's surfaced
+only when a command that actually needs the app runs.
+
 ## Writing your own commands
 
 `keel make:command greet` scaffolds `app/Commands/greet.ts`. Everything in

package/docs/examples/api-resources.ts

@@ -0,0 +1,86 @@
+// Type-check harness for docs/api-resources.md. Compile-only — never executed.
+import { z } from "zod";
+
+import { apiResource, type ApiResourceOptions, type ApiAccess } from "@shaferllc/keel/api";
+import { Model, Router, make, type Ctx } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static override table = "posts";
+  static override fillable = ["title", "body", "status", "authorId"];
+  declare id: number;
+  declare title: string;
+  declare status: string;
+  declare authorId: number;
+}
+
+declare function isEditor(c: Ctx): boolean;
+declare function currentUserId(c: Ctx): number;
+
+const PostSchema = z.object({
+  title: z.string().min(1),
+  body: z.string(),
+  status: z.enum(["draft", "published"]),
+});
+
+export function basic() {
+  apiResource(make(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; these are the ways to open a route. */
+export function access(): ApiAccess[] {
+  return [
+    { all: true },
+    { read: true }, // list + get
+    { write: (c) => isEditor(c) }, // create + update + delete
+    { list: true, get: true, create: false, update: false, delete: false },
+  ];
+}
+
+/** Row-level security: a row outside the scope 404s for read, update and delete. */
+export function rowLevelSecurity() {
+  apiResource(make(Router), Post, {
+    access: { all: true },
+    scope: (q, c) => q.where("authorId", currentUserId(c)),
+  });
+}
+
+export function shapingInputAndOutput() {
+  apiResource(make(Router), Post, {
+    access: { all: true },
+    createBody: PostSchema,
+    updateBody: PostSchema.partial(),
+    beforeWrite: (data, c, action) => ({
+      ...data,
+      ...(action === "create" ? { authorId: currentUserId(c) } : {}),
+    }),
+    transform: (model) => ({ id: (model as Post).id, title: (model as Post).title }),
+  });
+}
+
+export function everyOption(): ApiResourceOptions {
+  return {
+    path: "articles",
+    name: "articles",
+    only: ["list", "read"],
+    except: ["delete"],
+    filter: ["status"],
+    sort: ["title"],
+    perPage: 25,
+    maxPerPage: 100,
+    body: PostSchema,
+    createBody: PostSchema,
+    updateBody: PostSchema.partial(),
+    access: { read: true },
+    scope: (q) => q.where("deleted", false),
+    transform: (model) => model.toJSON(),
+    beforeWrite: (data) => data,
+    tags: ["Posts"],
+    label: "Post",
+  };
+}

package/docs/examples/testing.ts

@@ -196,10 +196,11 @@ export async function databaseAssertions() {
   await assertDatabaseEmpty("sessions");
 }
 
-declare function run(argv: string[]): Promise<void>;
+declare function run(argv: string[], options: { createApplication: () => Promise<Application> }): Promise<void>;
+declare function createApplication(): Promise<Application>;
 
 export async function consoleTests(): Promise<CommandResult> {
-  const result = await runCommand(() => run(["node", "keel", "routes"]));
+  const result = await runCommand(() => run(["node", "keel", "routes"], { createApplication }));
 
   result
     .assertSucceeded()

package/docs/testing.md

@@ -290,9 +290,10 @@ Run a command in-process — no subprocess, so it's fast and you can assert on i
 
 ```ts
 import { runCommand } from "@shaferllc/keel/core";
-import { run } from "../bin/keel"; // your app's console entry point
+import { run } from "@shaferllc/keel/cli";
+import { createApplication } from "../bootstrap/app.js";
 
-const result = await runCommand(() => run(["node", "keel", "routes"]));
+const result = await runCommand(() => run(["node", "keel", "routes"], { createApplication }));
 
 result
   .assertSucceeded() // exit code 0
@@ -300,10 +301,10 @@ result
   .assertOutputMatches(/POST\s+\/users/);
 ```
 
-You pass the command **in**, because the console entry point belongs to your app —
-it's the thing that knows how to build your application — not to the core. Anything
-that prints and sets an exit code works, so it's equally good for testing a
-function you wrote yourself.
+You pass the command **in**, because a command needs an *application*, and only your
+app knows how to build one. That's also why `run()` takes a `createApplication`
+factory rather than importing one. Anything that prints and sets an exit code works,
+so this is equally good for testing a function you wrote yourself.
 
 `console.log`/`warn` are captured as stdout and `console.error` as stderr; a
 command that *throws* is recorded as a failure rather than blowing up the test.

package/llms-full.txt

@@ -4495,8 +4495,8 @@ output.
 # API Resources
 
 `apiResource(router, Model, options)` generates a full CRUD REST API from a Keel
-[model](./models.md) — the [Remult](https://remult.dev) idea done the Keel way:
-explicit, server-side, and composed from pieces you already have. It's imported
+[model](./models.md) — explicit, server-side, and composed from pieces you already
+have. It's imported
 from `@shaferllc/keel/api`.
 
 ```ts
@@ -4599,14 +4599,15 @@ apiResource(router, Post, {
 | `transform` | Output shaping. |
 | `beforeWrite` | Mutate the payload before save. |
 | `tags` | OpenAPI tags for the routes. |
+| `label` | Singular name in doc summaries (default: the model's class name). |
 
 Global pagination defaults live in `config/api.ts` (register the optional
 `ApiServiceProvider`, then `keel vendor:publish --tag api-config`).
 
 ## What this isn't
 
-Remult also ships an isomorphic, type-safe **frontend** client that shares the
-model with the server. Keel deliberately stops at the server boundary: this
+There's no isomorphic frontend client here — no shared model object that runs on
+both sides of the wire. Keel deliberately stops at the server boundary: this
 generates a plain REST API you call however you like (fetch, your Inertia pages,
 a mobile app). That keeps the model server-only and the wire contract explicit —
 and it's exactly the contract the OpenAPI docs describe.
@@ -6805,6 +6806,30 @@ write the stub, confirming with:
 
 Delete the existing file first if you truly mean to regenerate it.
 
+## Your console entry point
+
+The console ships in the package, and takes your application factory:
+
+```ts
+#!/usr/bin/env tsx
+// bin/keel.ts
+import { run } from "@shaferllc/keel/cli";
+import { createApplication } from "../bootstrap/app.js";
+
+run(process.argv, { createApplication }).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+It's handed `createApplication` 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 the console out of the published build until now.
+
+Commands that need the app (`serve`, `routes`, `migrate`) boot it once and share it.
+Scaffolding commands (`make:*`) don't, so a boot failure isn't fatal — it's surfaced
+only when a command that actually needs the app runs.
+
 ## Writing your own commands
 
 `keel make:command greet` scaffolds `app/Commands/greet.ts`. Everything in
@@ -17904,9 +17929,10 @@ Run a command in-process — no subprocess, so it's fast and you can assert on i
 
 ```ts
 import { runCommand } from "@shaferllc/keel/core";
-import { run } from "../bin/keel"; // your app's console entry point
+import { run } from "@shaferllc/keel/cli";
+import { createApplication } from "../bootstrap/app.js";
 
-const result = await runCommand(() => run(["node", "keel", "routes"]));
+const result = await runCommand(() => run(["node", "keel", "routes"], { createApplication }));
 
 result
   .assertSucceeded() // exit code 0
@@ -17914,10 +17940,10 @@ result
   .assertOutputMatches(/POST\s+\/users/);
 ```
 
-You pass the command **in**, because the console entry point belongs to your app —
-it's the thing that knows how to build your application — not to the core. Anything
-that prints and sets an exit code works, so it's equally good for testing a
-function you wrote yourself.
+You pass the command **in**, because a command needs an *application*, and only your
+app knows how to build one. That's also why `run()` takes a `createApplication`
+factory rather than importing one. Anything that prints and sets an exit code works,
+so this is equally good for testing a function you wrote yourself.
 
 `console.log`/`warn` are captured as stdout and `console.error` as stderr; a
 command that *throws* is recorded as a failure rather than blowing up the test.

package/llms.txt

@@ -10,7 +10,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 ## Docs
 
 - [Building Keel apps with AI](https://github.com/shaferllc/keel/blob/main/docs/ai.md): Keel is built to be written with an AI agent.
-- [API Resources](https://github.com/shaferllc/keel/blob/main/docs/api-resources.md): apiResource(router, Model, options) generates a full CRUD REST API from a Keel model — the Remult idea done the Keel way: explicit, server-side, and composed from pieces you already have.
+- [API Resources](https://github.com/shaferllc/keel/blob/main/docs/api-resources.md): apiResource(router, Model, options) generates a full CRUD REST API from a Keel model — explicit, server-side, and composed from pieces you already have.
 - [Architecture](https://github.com/shaferllc/keel/blob/main/docs/architecture.md): 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.
 - [Authentication](https://github.com/shaferllc/keel/blob/main/docs/authentication.md): Session-based auth built on the pieces you already have: sessions hold the login, hashing checks passwords.
 - [Authorization](https://github.com/shaferllc/keel/blob/main/docs/authorization.md): Where authentication answers who you are, authorization answers what you're allowed to do.
@@ -72,6 +72,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 
 Every topic has a runnable, type-checked example:
 
+- [API Resources example](https://github.com/shaferllc/keel/blob/main/docs/examples/api-resources.ts)
 - [Authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/authentication.ts)
 - [Authorization example](https://github.com/shaferllc/keel/blob/main/docs/examples/authorization.ts)
 - [Broadcasting example](https://github.com/shaferllc/keel/blob/main/docs/examples/broadcasting.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.74.0",
+  "version": "0.77.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -60,6 +60,10 @@
     "./api": {
       "types": "./dist/api/index.d.ts",
       "import": "./dist/api/index.js"
+    },
+    "./cli": {
+      "types": "./dist/core/cli/index.d.ts",
+      "import": "./dist/core/cli/index.js"
     }
   },
   "bin": {
@@ -81,7 +85,7 @@
     "serve": "tsx bin/keel.ts serve",
     "dev": "tsx watch bin/keel.ts serve",
     "mcp": "tsx bin/keel-mcp.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && npm run typecheck:tests",
     "typecheck:docs": "npm run build && tsc -p tsconfig.docs.json",
     "test": "node --import tsx --test tests/*.test.ts",
     "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude='tests/**' tests/*.test.ts",
@@ -91,7 +95,10 @@
     "build": "npm run build:ai && npm run build:watch-ui && rm -rf dist && tsc -p tsconfig.build.json && npm run build:watch-copy",
     "dev:client": "vite",
     "build:client": "vite build",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
+    "verify:release": "bash scripts/verify-release.sh",
+    "version": "npm run build:ai && git add docs/ai-manifest.json llms.txt llms-full.txt"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -100,18 +107,21 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "vite": "^5 || ^6 || ^7"
+    "vite": "^5 || ^6 || ^7",
+    "@hono/node-server": "^1.13.7"
   },
   "peerDependenciesMeta": {
     "vite": {
       "optional": true
+    },
+    "@hono/node-server": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.7",
     "@libsql/client": "^0.17.4",
     "@types/node": "^26.1.1",
-    "commander": "^12.1.0",
     "preact": "^10.29.7",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",