@shaferllc/keel 0.66.0 → 0.74.0

package/dist/core/testing.js

@@ -12,6 +12,13 @@
  */
 import { Application } from "./application.js";
 import { HttpKernel } from "./http/kernel.js";
+import { db, connection } from "./database.js";
+import { hash } from "./crypto.js";
+import { events, cache, hasApplication } from "./helpers.js";
+import { restoreDisk } from "./storage.js";
+import { restoreQueue, setQueue, SyncDriver } from "./queue.js";
+import { restoreMail } from "./mail.js";
+import { setLockStore, MemoryLockStore } from "./lock.js";
 function deepEqual(a, b) {
     if (a === b)
         return true;
@@ -89,15 +96,180 @@ export class TestResponse {
             this.assertHeader("location", location);
         return this;
     }
+    /* --------------------------- status shorthands -------------------------- */
+    assertCreated() {
+        return this.assertStatus(201);
+    }
+    assertNoContent() {
+        return this.assertStatus(204);
+    }
+    assertBadRequest() {
+        return this.assertStatus(400);
+    }
+    assertUnauthorized() {
+        return this.assertStatus(401);
+    }
+    assertForbidden() {
+        return this.assertStatus(403);
+    }
+    assertNotFound() {
+        return this.assertStatus(404);
+    }
+    /** 422 — the status a failed `validate()` returns. */
+    assertUnprocessable() {
+        return this.assertStatus(422);
+    }
+    assertServerError() {
+        if (this.status < 500)
+            throw new Error(`Expected a 5xx status, got ${this.status}.`);
+        return this;
+    }
+    /* --------------------------------- body --------------------------------- */
+    /**
+     * Assert the JSON body *contains* `expected` — a subset match, so a test can
+     * pin the fields it cares about without breaking every time an unrelated one
+     * is added.
+     *
+     *   res.assertJsonContains({ user: { email: "a@b.com" } });
+     */
+    assertJsonContains(expected) {
+        const actual = this.json();
+        if (!contains(actual, expected)) {
+            throw new Error(`JSON body does not contain the expected subset.\n` +
+                `  expected: ${JSON.stringify(expected)}\n  actual:   ${JSON.stringify(actual)}`);
+        }
+        return this;
+    }
+    /** Assert the body contains `text` anywhere. */
+    assertSee(text) {
+        if (!this.bodyText.includes(text)) {
+            throw new Error(`Expected the body to contain "${text}". Body: ${this.bodyText}`);
+        }
+        return this;
+    }
+    /** Assert the body does *not* contain `text`. */
+    assertDontSee(text) {
+        if (this.bodyText.includes(text)) {
+            throw new Error(`Expected the body not to contain "${text}". Body: ${this.bodyText}`);
+        }
+        return this;
+    }
+    /* ------------------------------ validation ------------------------------ */
+    /**
+     * Assert a 422 carrying an error on each named field. With no fields, it just
+     * asserts that validation failed.
+     *
+     *   res.assertValidationErrors("email", "password");
+     */
+    assertValidationErrors(...fields) {
+        this.assertStatus(422);
+        const errors = this.json().errors ?? {};
+        for (const field of fields) {
+            if (!errors[field]?.length) {
+                throw new Error(`Expected a validation error on "${field}". Fields with errors: ${JSON.stringify(Object.keys(errors))}`);
+            }
+        }
+        return this;
+    }
+    /** Assert there is *no* validation error on `field`. */
+    assertNoValidationError(field) {
+        const errors = this.json().errors;
+        if (errors?.[field]?.length) {
+            throw new Error(`Expected no validation error on "${field}", got: ${JSON.stringify(errors[field])}`);
+        }
+        return this;
+    }
+    /* -------------------------- headers and cookies ------------------------- */
+    assertHeaderMissing(name) {
+        const actual = this.header(name);
+        if (actual !== null)
+            throw new Error(`Expected no ${name} header, got "${actual}".`);
+        return this;
+    }
+    /** The cookies this response set, by name. */
+    cookies() {
+        return cookiesOf(this.raw);
+    }
+    /** Assert the response set a cookie — with `value`, if you give one. */
+    assertCookie(name, value) {
+        const cookies = this.cookies();
+        if (!(name in cookies)) {
+            throw new Error(`Expected a "${name}" cookie. Got: ${JSON.stringify(Object.keys(cookies))}`);
+        }
+        if (value !== undefined && cookies[name] !== value) {
+            throw new Error(`Expected cookie "${name}" to be "${value}", got "${cookies[name]}".`);
+        }
+        return this;
+    }
+    assertCookieMissing(name) {
+        if (name in this.cookies())
+            throw new Error(`Expected no "${name}" cookie, but one was set.`);
+        return this;
+    }
+    /* --------------------------------- debug -------------------------------- */
+    /** Print status, headers, and body — for when a test fails and you're stuck. */
+    dump() {
+        console.log(`\n--- ${this.status} ---`);
+        console.log(Object.fromEntries(this.raw.headers.entries()));
+        console.log(this.bodyText);
+        return this;
+    }
 }
 /** Injects requests into an app and returns `TestResponse`s. */
 export class TestClient {
     target;
-    constructor(target) {
+    defaults;
+    constructor(target, defaults = { headers: {}, cookies: {} }) {
         this.target = target;
+        this.defaults = defaults;
+    }
+    /* ---------------------------- request building -------------------------- */
+    /** A copy of this client with extra default headers. */
+    withHeaders(headers) {
+        return new TestClient(this.target, {
+            ...this.defaults,
+            headers: { ...this.defaults.headers, ...headers },
+        });
+    }
+    withHeader(name, value) {
+        return this.withHeaders({ [name]: value });
+    }
+    /** A copy of this client that sends these cookies. */
+    withCookies(cookies) {
+        return new TestClient(this.target, {
+            ...this.defaults,
+            cookies: { ...this.defaults.cookies, ...cookies },
+        });
+    }
+    withCookie(name, value) {
+        return this.withCookies({ [name]: value });
+    }
+    /** Send `Authorization: Bearer <token>` — the shorthand for an API test. */
+    withToken(token) {
+        return this.withHeader("authorization", `Bearer ${token}`);
+    }
+    /** Send HTTP basic credentials. */
+    withBasicAuth(username, password) {
+        return this.withHeader("authorization", `Basic ${btoa(`${username}:${password}`)}`);
+    }
+    /** Ask for JSON back — sets `Accept: application/json`. */
+    acceptJson() {
+        return this.withHeader("accept", "application/json");
+    }
+    /** Merge the client's defaults into one request's init. */
+    init(init) {
+        const headers = {
+            ...this.defaults.headers,
+            ...(init.headers ?? {}),
+        };
+        const cookies = Object.entries(this.defaults.cookies);
+        if (cookies.length && !headers.cookie) {
+            headers.cookie = cookies.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("; ");
+        }
+        return { ...init, headers };
     }
     async request(path, init = {}) {
-        const res = await this.target.request(path, init);
+        const res = await this.target.request(path, this.init(init));
         const text = await res.text();
         return new TestResponse(res, text);
     }
@@ -116,6 +288,24 @@ export class TestClient {
     patch(path, body, init) {
         return this.request(path, withJson("PATCH", body, init));
     }
+    /** POST a URL-encoded form, the way a browser would. */
+    form(path, fields, init = {}) {
+        const body = new URLSearchParams(Object.entries(fields).map(([k, v]) => [k, String(v)])).toString();
+        return this.request(path, {
+            ...init,
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", ...init.headers },
+            body,
+        });
+    }
+    /** POST a multipart form — for file uploads. */
+    multipart(path, fields, init = {}) {
+        const form = new FormData();
+        for (const [key, value] of Object.entries(fields))
+            form.append(key, value);
+        // No content-type header: the runtime sets it, with the multipart boundary.
+        return this.request(path, { ...init, method: "POST", body: form });
+    }
 }
 function withJson(method, body, init = {}) {
     if (body === undefined)
@@ -139,3 +329,315 @@ export function testClient(target) {
         return new TestClient(target.build());
     return new TestClient(target);
 }
+/* ==========================================================================
+ * Below: the rest of the testing toolkit — a richer request builder, more
+ * response assertions, database assertions, state reset between tests, time
+ * control, spies, and console-command testing.
+ * ========================================================================== */
+/* ---------------------------- deep subset match --------------------------- */
+/** Whether `actual` contains everything in `expected` (recursively). */
+function contains(actual, expected) {
+    if (deepEqual(actual, expected))
+        return true;
+    if (typeof expected !== "object" || expected === null)
+        return false;
+    if (typeof actual !== "object" || actual === null)
+        return false;
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual))
+            return false;
+        // Every expected element must appear somewhere in actual.
+        return expected.every((want) => actual.some((got) => contains(got, want)));
+    }
+    return Object.entries(expected).every(([key, want]) => contains(actual[key], want));
+}
+/** Parse `Set-Cookie` headers into a name -> value map. */
+function cookiesOf(res) {
+    const out = {};
+    // getSetCookie() is the standard way to read repeated Set-Cookie headers.
+    const raw = typeof res.headers.getSetCookie === "function"
+        ? res.headers.getSetCookie()
+        : [res.headers.get("set-cookie")].filter(Boolean);
+    for (const line of raw) {
+        const [pair] = line.split(";");
+        const index = (pair ?? "").indexOf("=");
+        if (index > 0)
+            out[pair.slice(0, index).trim()] = decodeURIComponent(pair.slice(index + 1).trim());
+    }
+    return out;
+}
+/* ------------------------------ state reset ------------------------------- */
+/**
+ * Put the framework's global state back the way it was, so one test can't leak
+ * into the next. Call it in an `afterEach`.
+ *
+ *   afterEach(() => resetState());
+ *
+ * It restores every fake (disk, queue, mail, hash, time), drops event listeners,
+ * empties the cache, and gives you a fresh lock store. It does **not** touch the
+ * database — see `refreshDatabase()`.
+ */
+export function resetState() {
+    restoreDisk();
+    restoreQueue();
+    restoreMail();
+    restoreTime();
+    hash.restore();
+    setQueue(new SyncDriver());
+    setLockStore(new MemoryLockStore());
+    // These live on the application, so they only exist if one was booted.
+    if (hasApplication()) {
+        events().clearAll();
+        void cache().flush();
+    }
+}
+/* ------------------------------ time control ------------------------------ */
+const RealDate = Date;
+let frozenAt;
+/** Whether time is currently frozen. */
+export function timeIsFrozen() {
+    return frozenAt !== undefined;
+}
+function installFakeDate() {
+    if (globalThis.Date !== RealDate)
+        return;
+    class FakeDate extends RealDate {
+        constructor(...args) {
+            if (args.length === 0)
+                super(frozenAt ?? RealDate.now());
+            else
+                super(...args);
+        }
+        static now() {
+            return frozenAt ?? RealDate.now();
+        }
+    }
+    globalThis.Date = FakeDate;
+}
+/**
+ * Freeze the clock, so anything that reads the time sees the same instant —
+ * which is how you test a token that expires in an hour without waiting an hour.
+ *
+ *   freezeTime("2026-07-11T12:00:00Z");
+ *   timeTravel(3600_000);            // an hour later
+ *   restoreTime();
+ *
+ * Mocks `Date` and `Date.now()`. It does **not** mock timers: a `setTimeout` still
+ * fires on the real clock.
+ */
+export function freezeTime(at = RealDate.now()) {
+    frozenAt = at instanceof RealDate ? at.getTime() : new RealDate(at).getTime();
+    installFakeDate();
+    return frozenAt;
+}
+/** Move the frozen clock forward (or back, with a negative value) by milliseconds. */
+export function timeTravel(ms) {
+    if (frozenAt === undefined)
+        freezeTime();
+    frozenAt = frozenAt + ms;
+    return frozenAt;
+}
+/** Hand the real clock back. */
+export function restoreTime() {
+    frozenAt = undefined;
+    globalThis.Date = RealDate;
+}
+/* --------------------------- database assertions -------------------------- */
+/** Rows in `table` matching every column in `where`. */
+async function matching(table, where) {
+    let query = db(table);
+    for (const [column, value] of Object.entries(where))
+        query = query.where(column, value);
+    return query.get();
+}
+/** Assert at least one row in `table` matches `where` (an exact `count` if given). */
+export async function assertDatabaseHas(table, where, count) {
+    const rows = await matching(table, where);
+    if (count !== undefined) {
+        if (rows.length !== count) {
+            throw new Error(`Expected ${count} row(s) in "${table}" matching ${JSON.stringify(where)}, found ${rows.length}.`);
+        }
+        return;
+    }
+    if (!rows.length) {
+        const total = (await db(table).get()).length;
+        throw new Error(`Expected a row in "${table}" matching ${JSON.stringify(where)}, but found none. ` +
+            `The table has ${total} row(s).`);
+    }
+}
+/** Assert no row in `table` matches `where`. */
+export async function assertDatabaseMissing(table, where) {
+    const rows = await matching(table, where);
+    if (rows.length) {
+        throw new Error(`Expected no row in "${table}" matching ${JSON.stringify(where)}, but found ${rows.length}.`);
+    }
+}
+/** Assert `table` holds exactly `count` rows. */
+export async function assertDatabaseCount(table, count) {
+    const rows = await db(table).get();
+    if (rows.length !== count) {
+        throw new Error(`Expected "${table}" to hold ${count} row(s), found ${rows.length}.`);
+    }
+}
+/** Assert `table` is empty. */
+export function assertDatabaseEmpty(table) {
+    return assertDatabaseCount(table, 0);
+}
+/**
+ * Empty tables between tests. Order matters when foreign keys do — pass children
+ * before parents.
+ *
+ *   afterEach(() => truncate("comments", "posts", "users"));
+ *
+ * This deletes rows; it doesn't roll back a transaction, so it works on every
+ * driver (D1, Postgres, libSQL) rather than only the ones with savepoints.
+ */
+export async function truncate(...tables) {
+    for (const table of tables)
+        await connection().write(`DELETE FROM ${table}`);
+}
+/**
+ * A function that records how it was called — the smallest useful test double.
+ *
+ *   const send = spy<[string], void>();
+ *   notify(send);
+ *   assert.equal(send.callCount, 1);
+ *   assert.ok(send.calledWith("hello"));
+ */
+export function spy(implementation) {
+    const calls = [];
+    let impl = implementation;
+    const fn = ((...args) => {
+        calls.push(args);
+        return impl ? impl(...args) : undefined;
+    });
+    Object.defineProperties(fn, {
+        calls: { get: () => calls },
+        callCount: { get: () => calls.length },
+        called: { get: () => calls.length > 0 },
+    });
+    fn.calledWith = (...args) => calls.some((call) => deepEqual(call, args));
+    fn.returns = (value) => {
+        impl = () => value;
+        return fn;
+    };
+    fn.reset = () => {
+        calls.length = 0;
+    };
+    return fn;
+}
+/**
+ * Replace a method on an object with a spy, and hand back a `restore()`.
+ *
+ *   const charge = spyOn(stripe, "charge").returns(Promise.resolve(receipt));
+ *   …
+ *   restoreSpies();
+ */
+const spied = [];
+export function spyOn(target, method) {
+    const original = target[method];
+    const replacement = spy((...args) => typeof original === "function" ? original.apply(target, args) : undefined);
+    target[method] = replacement;
+    spied.push(() => {
+        target[method] = original;
+    });
+    return replacement;
+}
+/** Undo every `spyOn()`. */
+export function restoreSpies() {
+    for (const restore of spied.splice(0))
+        restore();
+}
+/* ------------------------------ console tests ----------------------------- */
+/** What a command did: its output, its error output, and its exit code. */
+export class CommandResult {
+    stdout;
+    stderr;
+    exitCode;
+    constructor(stdout, stderr, exitCode) {
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.exitCode = exitCode;
+    }
+    /** Everything written to stdout, joined. */
+    output() {
+        return this.stdout.join("\n");
+    }
+    assertExitCode(expected) {
+        if (this.exitCode !== expected) {
+            throw new Error(`Expected exit code ${expected}, got ${this.exitCode}.\n${this.output()}\n${this.stderr.join("\n")}`);
+        }
+        return this;
+    }
+    /** Exit code 0. */
+    assertSucceeded() {
+        return this.assertExitCode(0);
+    }
+    /** A non-zero exit code. */
+    assertFailed() {
+        if (this.exitCode === 0) {
+            throw new Error(`Expected the command to fail, but it exited 0.\n${this.output()}`);
+        }
+        return this;
+    }
+    /** Assert a line of output contains `text`. */
+    assertOutputContains(text) {
+        if (!this.output().includes(text)) {
+            throw new Error(`Expected the output to contain "${text}".\nOutput:\n${this.output()}`);
+        }
+        return this;
+    }
+    assertOutputMatches(pattern) {
+        if (!pattern.test(this.output())) {
+            throw new Error(`Expected the output to match ${pattern}.\nOutput:\n${this.output()}`);
+        }
+        return this;
+    }
+    assertErrorContains(text) {
+        const stderr = this.stderr.join("\n");
+        if (!stderr.includes(text)) {
+            throw new Error(`Expected stderr to contain "${text}".\nstderr:\n${stderr}`);
+        }
+        return this;
+    }
+}
+/**
+ * Run a console command in-process and capture what it printed and the exit code
+ * it set — no subprocess, so it's fast and you can assert on it.
+ *
+ * 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
+ *
+ *   const result = await runCommand(() => run(["node", "keel", "routes"]));
+ *   result.assertSucceeded().assertOutputContains("GET  /users");
+ *
+ * `console.log`/`warn` are captured as stdout, `console.error` as stderr, and
+ * `process.exitCode` is read and then restored.
+ */
+export async function runCommand(command) {
+    const stdout = [];
+    const stderr = [];
+    const real = { log: console.log, error: console.error, warn: console.warn };
+    const previousExit = process.exitCode;
+    process.exitCode = 0;
+    console.log = (...args) => stdout.push(args.map(String).join(" "));
+    console.warn = (...args) => stdout.push(args.map(String).join(" "));
+    console.error = (...args) => stderr.push(args.map(String).join(" "));
+    try {
+        await command();
+    }
+    catch (error) {
+        // A command that throws is a command that failed — record it, don't blow up
+        // the test with an unrelated stack.
+        stderr.push(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+    finally {
+        Object.assign(console, real);
+    }
+    const exitCode = Number(process.exitCode ?? 0);
+    process.exitCode = previousExit;
+    return new CommandResult(stdout, stderr, exitCode);
+}

package/dist/db/d1.js

@@ -22,5 +22,18 @@ export function d1Connection(database) {
             const { meta } = await database.prepare(sql).bind(...bindings).run();
             return { rowsAffected: meta.changes ?? 0, insertId: meta.last_row_id };
         },
+        /**
+         * D1 has no interactive transactions — it can't hold one open across awaits
+         * over its HTTP protocol, and a `BEGIN` sent through `prepare()` is rejected.
+         *
+         * So say that, rather than letting the generic BEGIN fallback fire and fail
+         * with something cryptic from the driver. A transaction that quietly isn't one
+         * is far worse than a transaction that refuses to start.
+         */
+        async begin() {
+            throw new Error("D1 does not support interactive transactions. Use `database.batch([...])` for an " +
+                "atomic group of statements, or run transactional work against a database that " +
+                "supports them (Postgres, libSQL, SQLite).");
+        },
     };
 }

package/dist/db/pg.d.ts

@@ -24,6 +24,19 @@ export interface PgLike {
         rows: Row[];
         rowCount: number | null;
     }>;
+    /**
+     * Check a single connection out of the pool. Present on a `Pool`, absent on a
+     * bare `Client` — which is exactly how this adapter tells the two apart.
+     */
+    connect?(): Promise<PgClientLike>;
+}
+/** A checked-out client. `release()` hands it back to the pool. */
+export interface PgClientLike {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Row[];
+        rowCount: number | null;
+    }>;
+    release(): void;
 }
 /** Build a `Connection` backed by a node-postgres-compatible client. */
 export declare function pgConnection(client: PgLike): Connection;

package/dist/db/pg.js

@@ -17,17 +17,59 @@
  * has a `RETURNING` clause. This adapter surfaces `rows[0].id` when present;
  * otherwise `insertId` is `undefined` (so `insertGetId()` needs a `RETURNING id`).
  */
+function toWriteResult(result) {
+    const insertId = result.rows?.[0]?.id;
+    return { rowsAffected: result.rowCount ?? 0, insertId };
+}
 /** Build a `Connection` backed by a node-postgres-compatible client. */
 export function pgConnection(client) {
-    return {
+    const conn = {
         async select(sql, bindings) {
             const { rows } = await client.query(sql, bindings);
             return rows;
         },
         async write(sql, bindings) {
-            const { rows, rowCount } = await client.query(sql, bindings);
-            const insertId = rows?.[0]?.id;
-            return { rowsAffected: rowCount ?? 0, insertId };
+            return toWriteResult(await client.query(sql, bindings));
         },
     };
+    /**
+     * A pool hands each statement to whichever connection is free, so running
+     * `BEGIN` through it would wrap *nothing* — the INSERT after it could land on a
+     * different connection entirely. So when the client can check one out, the
+     * whole transaction runs on that single connection, and it goes back to the
+     * pool afterwards whatever happens.
+     *
+     * A bare `Client` has no `connect()`, and doesn't need one: it *is* a single
+     * connection. Keel falls back to BEGIN/COMMIT on it.
+     */
+    if (typeof client.connect === "function") {
+        conn.begin = async () => {
+            const checkout = await client.connect();
+            await checkout.query("BEGIN");
+            let done = false;
+            const finish = async (sql) => {
+                if (done)
+                    return;
+                done = true;
+                try {
+                    await checkout.query(sql);
+                }
+                finally {
+                    checkout.release(); // never leak the connection, even if COMMIT throws
+                }
+            };
+            return {
+                async select(sql, bindings) {
+                    const { rows } = await checkout.query(sql, bindings);
+                    return rows;
+                },
+                async write(sql, bindings) {
+                    return toWriteResult(await checkout.query(sql, bindings));
+                },
+                commit: () => finish("COMMIT"),
+                rollback: () => finish("ROLLBACK"),
+            };
+        };
+    }
+    return conn;
 }

package/dist/mcp/server.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Keel MCP server. Exposes Keel's documentation, public API surface, and
+ * code generators to AI agents (Claude Code, Cursor, …) over stdio, so an agent
+ * editing a Keel app can look things up and scaffold code without guessing.
+ *
+ * Run it with `keel mcp` (dev) or the shipped `keel-mcp` bin (consumers).
+ * Tools:
+ *   keel_overview          framework facts, conventions, folder layout
+ *   keel_search_docs       full-text search across the guides
+ *   keel_read_doc          a full guide (optionally with its runnable example)
+ *   keel_search_api        search the public export surface
+ *   keel_list_generators   the `keel make:*` generators
+ *   keel_scaffold          generate a controller/provider/job/… stub (no write)
+ * Resources: keel://overview, keel://llms-full, and keel://docs/<slug> per guide.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): Promise<McpServer>;
+/** Boot the server on stdio. Called by the `keel-mcp` bin and `keel mcp`. */
+export declare function runMcpServer(): Promise<void>;