@shaferllc/keel 0.68.0 → 0.74.0

package/docs/api-resources.md

@@ -0,0 +1,118 @@
+# 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
+from `@shaferllc/keel/api`.
+
+```ts
+import { apiResource } from "@shaferllc/keel/api";
+import { Post } from "../app/Models/Post.js";
+import { z } from "zod";
+
+export default function routes(router) {
+  apiResource(router, Post, {
+    filter: ["status", "authorId"],
+    sort: ["createdAt", "title"],
+    body: z.object({ title: z.string(), body: z.string(), status: z.string() }),
+    access: { read: true, write: (c) => isEditor(c) },
+  });
+}
+```
+
+That registers five routes:
+
+| Method | Path | Action |
+|--------|------|--------|
+| `GET` | `/posts` | list (filtered, sorted, paginated) |
+| `GET` | `/posts/:id` | read one |
+| `POST` | `/posts` | create |
+| `PUT` / `PATCH` | `/posts/:id` | update |
+| `DELETE` | `/posts/:id` | delete |
+
+They're real routes, so [`@shaferllc/keel/openapi`](./openapi.md) documents them
+automatically, and writes go through the model's mass-assignment guard and your
+Zod schema.
+
+## Access is deny-by-default
+
+An auto-generated API that's open by default is a footgun. Every action whose
+access you don't declare returns **403**. You opt routes open — never shut.
+
+```ts
+access: {
+  read: true,                    // list + read: anyone
+  write: (c) => auth().check(),  // create + update + delete: signed-in only
+}
+```
+
+Rules resolve per action: the action's own key (`list`, `get`, `create`,
+`update`, `delete`), then the `read` / `write` shorthand, then `all`, then denied.
+Each rule is a boolean or a `(c) => boolean | Promise<boolean>` predicate.
+
+## Filtering, sorting, pagination — allow-listed
+
+The list endpoint reads the query string, but **only** columns you allow-list:
+
+- `filter: ["status"]` → `GET /posts?status=published` filters; `?secret=x` is
+  ignored. Nothing reaches SQL unless it's on the list.
+- `sort: ["title", "createdAt"]` → `GET /posts?sort=title,-createdAt` (a `-`
+  prefix is descending); unknown columns are dropped.
+- `GET /posts?page=2&perPage=20` paginates. `perPage` is clamped to `maxPerPage`
+  (default 100) — the guard against "give me everything".
+
+The response is a paginated envelope:
+
+```json
+{ "data": [ … ], "meta": { "total": 42, "perPage": 20, "currentPage": 2, "lastPage": 3 } }
+```
+
+## Row-level security with `scope`
+
+`scope` constrains the base query for **every** row operation — list, read,
+update, delete. A row outside the scope reads as 404, so it can't be fetched,
+changed, or removed:
+
+```ts
+apiResource(router, Post, {
+  access: { read: true, write: true },
+  scope: (q, c) => q.where("authorId", currentUserId(c)), // only your own posts
+});
+```
+
+## Shaping input and output
+
+- **`body` / `createBody` / `updateBody`** — a Zod schema validating writes
+  (a failure is a 422). It also becomes the request-body schema in the OpenAPI
+  docs.
+- **`beforeWrite(data, c, action)`** — mutate the write payload (stamp an owner
+  id, a timestamp) before it's saved.
+- **`transform`** — shape the output: a `(model, c) => …` function, or a Keel
+  [Transformer](./transformers.md) (its `item`/`collection` are used).
+
+## Options reference
+
+| Option | Purpose |
+|--------|---------|
+| `path` | Base path (default: the model's table). |
+| `name` | Route-name prefix (default: the path). |
+| `only` / `except` | Restrict which of the five actions are generated. |
+| `filter` / `sort` | Allow-listed columns for `?filter` and `?sort`. |
+| `perPage` / `maxPerPage` | Page-size default and ceiling. |
+| `body` / `createBody` / `updateBody` | Write validation schemas. |
+| `access` | Per-action access rules (deny by default). |
+| `scope` | Row-level query constraint for every operation. |
+| `transform` | Output shaping. |
+| `beforeWrite` | Mutate the payload before save. |
+| `tags` | OpenAPI tags for the routes. |
+
+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
+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/configuration.md

@@ -55,6 +55,80 @@ string. Pass a fallback of the type you expect and the type follows it.
 Use `env()` **only inside config files**, not scattered through your app. That
 keeps all environment coupling in one layer.
 
+## Validating the environment
+
+`env("DATABASE_URL")` hands back whatever is — or isn't — in `process.env`. A
+missing variable is `undefined`, the app boots looking perfectly healthy, and then
+dies on the first request that actually needs it. In production. At night.
+
+`defineEnv()` checks the whole environment **at boot** and refuses to start
+otherwise:
+
+```ts
+// config/env.ts
+import { defineEnv, envVar } from "@shaferllc/keel/core";
+
+export const env = defineEnv({
+  APP_KEY: envVar.string({ required: true, description: "32+ random characters" }),
+  PORT: envVar.number({ default: 3000 }),
+  NODE_ENV: envVar.enum(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: envVar.url({ required: true }),
+  SENTRY_DSN: envVar.string(), // optional
+});
+```
+
+```ts
+env.PORT; // number — not "3000"
+env.NODE_ENV; // "development" | "test" | "production" — not string
+env.SENTRY_DSN; // string | undefined
+```
+
+The types are **inferred from the rules**. A `number` rule gives you a `number`; an
+`enum` gives you the union, not `string`; anything optional without a default is
+`| undefined`, so you can't forget to handle it.
+
+### It reports every problem at once
+
+```
+The environment is not valid:
+
+  • APP_KEY is required but not set (32+ random characters).
+  • PORT must be a number, got "eighty".
+  • NODE_ENV must be one of development, test, production, got "staging".
+  • DATABASE_URL must be a valid URL, got "not a url".
+
+Set these in your .env (or your host's environment) and start again.
+```
+
+Not the first problem — **all** of them. Fixing a deploy one missing variable per
+restart is its own small hell.
+
+### Rules
+
+| Rule | Value | Notes |
+|------|-------|-------|
+| `envVar.string()` | `string` | |
+| `envVar.number()` | `number` | rejects `"eighty"` |
+| `envVar.boolean()` | `boolean` | accepts `true/false/1/0/yes/no/on/off` |
+| `envVar.enum([...])` | the union | typed as the literal union |
+| `envVar.url()` | `string` | must parse as a URL — catches a truncated connection string |
+
+Each takes `required`, `default`, `description` (shown in the error, so they know
+what to set), and `validate` for anything else:
+
+```ts
+APP_KEY: envVar.string({
+  required: true,
+  validate: (value) => (value.length >= 32 ? true : "must be at least 32 characters"),
+});
+```
+
+**An empty string counts as absent.** `PORT=` in a `.env` file is a typo, not a
+deliberate empty port.
+
+The returned object is frozen, so nothing can quietly reassign your config at
+runtime.
+
 ## Config files
 
 Each file in `config/` exports a default object and is loaded under its

package/docs/console.md

@@ -336,21 +336,201 @@ write the stub, confirming with:
 
 Delete the existing file first if you truly mean to regenerate it.
 
-## Adding your own commands
+## Writing your own commands
 
-Commands are defined with [commander](https://github.com/tj/commander.js) in
-[`src/core/cli/index.ts`](../src/core/cli/index.ts). Register a new one on the
-`program`:
+`keel make:command greet` scaffolds `app/Commands/greet.ts`. Everything in
+`app/Commands` is discovered automatically — no registration step.
 
 ```ts
-program
-  .command("cache:clear")
-  .description("Clear the application cache")
-  .action(async () => {
-    const app = await createApplication();
-    // ...your logic, with full access to the container
-  });
+import { defineCommand, arg, flag } from "@shaferllc/keel/core";
+
+export const greet = defineCommand({
+  name: "greet",
+  description: "Greet someone",
+
+  args: { name: arg.string({ description: "who to greet" }) },
+  flags: { loud: flag.boolean({ alias: "l", description: "SHOUT IT" }) },
+
+  async run({ args, flags, ui }) {
+    const message = `Hello, ${args.name}!`;
+    ui.success(flags.loud ? message.toUpperCase() : message);
+  },
+});
+```
+
+```bash
+keel greet Ada --loud     # ✔ HELLO, ADA!
+keel greet --help         # generated usage, args, and options
+```
+
+**`args.name` is a `string` and `flags.loud` is a `boolean` — inferred, not cast.**
+That's the point of declaring them: the parsing is generated from the types, so the
+two can't drift apart. Make an arg optional and its type becomes
+`string | undefined`; give it a default and it's a `string` again.
+
+Commands run with the application booted, so they get the same container, config,
+and providers your HTTP requests do.
+
+### Arguments
+
+Positional, in declaration order. Required by default.
+
+| Builder | Value |
+|---------|-------|
+| `arg.string()` | `string` |
+| `arg.number()` | `number` — rejected with a clear error if it isn't one |
+| `arg.spread()` | `string[]` — swallows the rest; must be last |
+
+Options: `description`, `required: false`, `default`, `parse`.
+
+### Flags
+
+| Builder | Value |
+|---------|-------|
+| `flag.boolean()` | `boolean` — defaults to `false`, so it's never `undefined` |
+| `flag.string()` | `string \| undefined` |
+| `flag.number()` | `number \| undefined` |
+| `flag.array()` | `string[]` — repeatable, defaults to `[]` |
+
+Options: `description`, `alias` (a single letter), `required`, `default`, `parse`.
+
+The parser understands `--flag value`, `--flag=value`, `--no-flag`, `-f value`,
+bundled shorthands (`-lt 5`), and `--`, after which everything is passed through
+untouched in `rest`.
+
+An **unknown flag is an error**, not a shrug — a typo'd `--forse` should tell you,
+not silently do nothing. Set `allowUnknownFlags: true` if a command genuinely needs
+to pass flags on to something else.
+
+### Exit codes
+
+Return a number to set the exit code; return nothing for `0`. A thrown error is
+caught, reported, and exits `1` — a console is a bad place to show a user a stack
+trace because they mistyped a flag. A **usage** error (missing arg, bad flag) prints
+what's wrong *and the command's help*.
+
+## Terminal UI
+
+Every command gets a `ui`:
+
+```ts
+ui.info("Checking…");
+ui.success("Migrated 3 tables");
+ui.warning("Nothing to do");
+ui.error("Failed"); // stderr
+ui.debug("verbose detail");
+
+ui.action("create", "app/Models/User.ts"); // CREATE  app/Models/User.ts
+ui.action("skip", "app/Models/Post.ts", "skipped");
+
+ui.table(["Name", "Rows"]).row(["users", "42"]).row(["orgs", "7"]).render();
+
+ui.sticker(["http://localhost:3000"], "Server running");
+ui.instructions(["cd my-app", "npm install", "keel serve"], "Next steps");
+
+ui.colors("green", "done"); // paint a string yourself
+```
+
+### Tasks
+
+For a command that does several things in a row:
+
+```ts
+await ui
+  .tasks()
+  .add("Install dependencies", async (task) => {
+    task.update("resolving…");
+    return "42 packages";
+  })
+  .add("Run migrations", async () => "3 tables")
+  .run();
 ```
 
-Because commands boot the application, they get the same container, config, and
-providers your HTTP requests do.
+It **stops at the first failure**, because the tasks after it almost certainly
+depended on it and a cascade of red tells you nothing new. `run()` resolves to
+`false` if anything failed.
+
+## Prompts
+
+```ts
+const name = await prompt.ask("Project name?", { default: "my-app" });
+const secret = await prompt.secure("API key?");
+const ok = await prompt.confirm("Delete everything?");
+const driver = await prompt.choice("Database?", ["sqlite", "postgres"]);
+const features = await prompt.multiple("Features?", ["auth", "queue", "mail"]);
+```
+
+`ask` re-asks on a failed `validate` rather than dying — a typo shouldn't cost
+someone the whole command. Every prompt takes `default`, `hint`, `validate`, and
+`result`.
+
+## Testing a command
+
+A command that asks questions is normally a command you can't test. So prompts can
+be **trapped**: script the answers up front, and nothing touches the terminal.
+
+```ts
+import { ConsoleKernel, createUi, createPrompt } from "@shaferllc/keel/core";
+
+const ui = createUi({ raw: true }); // buffer the output, drop the colors
+const prompt = createPrompt({ trap: true });
+const kernel = new ConsoleKernel({ ui, prompt }).register(setup);
+
+prompt.trap("Project name?").replyWith("keel-app");
+prompt.trap("Database?").chooseOption(1);
+prompt.trap("Write the config?").accept();
+
+const code = await kernel.run(["setup"]);
+
+assert.equal(code, 0);
+assert.match(ui.logs.join("\n"), /keel-app on postgres/);
+prompt.assertAllTrapsUsed(); // every scripted question was actually asked
+```
+
+An **untrapped prompt throws** instead of hanging. That matters more than it
+sounds: without it, the test would block forever on stdin no test will ever
+provide, and your suite would simply stop — with no failure to read.
+
+A trap can also assert the prompt's own validation:
+
+```ts
+prompt
+  .trap("Email?")
+  .assertFails("", "Email is required")
+  .assertPasses("ada@example.com")
+  .replyWith("ada@example.com");
+```
+
+`ui.logs` and `ui.errors` hold every line written, colorless, so you can assert on
+exactly what the command said.
+
+## The REPL
+
+```bash
+keel repl
+```
+
+An interactive shell with the **application booted** — the container is up, the
+providers have run, and the helpers are in scope:
+
+```
+keel > await db("users").where("active", 1).get()
+keel > make(Router).all()
+keel > await cache().get("stats")
+keel > .ls        # what's in scope
+keel > .exit
+```
+
+Poking at a model in a REPL is the fastest debugging loop there is, and it
+shouldn't cost you a throwaway script to get one. History persists in
+`.keel_repl_history`.
+
+---
+
+## A note on the built-ins
+
+The commands *above* (`serve`, `routes`, `make:*`, `migrate:*`) still run through
+Keel's original console wrapper, and package-contributed commands do too. Your
+commands — anything in `app/Commands` — run on the system documented here, and take
+precedence over a built-in of the same name. Migrating the built-ins across is
+mechanical and will happen; nothing about the API here changes when it does.

package/docs/database.md

@@ -178,6 +178,107 @@ SQL — so it's injection-safe by construction. Writes return a `WriteResult`;
 > matches the current `where` clause — with no `where`, that's the whole table.
 > Always scope a write with `where` unless you truly mean to touch every row.
 
+## Transactions
+
+Two related writes should either both land or neither should. `transaction()`
+commits when your callback returns and **rolls back if it throws**:
+
+```ts
+import { transaction, db } from "@shaferllc/keel/core";
+
+await transaction(async () => {
+  await db("orders").insert(order);
+  await db("stock").where("id", id).decrement("count"); // a throw here undoes the insert
+});
+```
+
+The error still reaches you — it's rethrown after the rollback. Nothing is
+swallowed.
+
+### Queries inside are ambient
+
+You don't have to thread a transaction object through your code. `db()`, models,
+and relations all pick up the open transaction automatically:
+
+```ts
+await transaction(async () => {
+  const user = await User.create({ email }); // the model is in the transaction
+  await user.related("posts").create({ title }); // so is the relation
+  await db("audit").insert({ userId: user.id }); // and the raw builder
+});
+```
+
+That works because the transaction lives in `AsyncLocalStorage`, not a module
+global — so two requests running transactions at the same time can't steal each
+other's connection.
+
+If you'd rather be explicit, the callback gets a handle:
+
+```ts
+await transaction(async (tx) => {
+  await tx.table("orders").insert(order);
+  await tx.write("UPDATE stock SET count = count - 1 WHERE id = ?", [id]);
+});
+```
+
+`tx.rollback()` abandons the transaction without committing. `inTransaction()`
+tells you whether one is open.
+
+### Nesting uses savepoints
+
+A `transaction()` inside another doesn't open a second one — databases don't have
+those. It takes a **savepoint**, so an inner failure rolls back only the inner
+work and the outer transaction carries on:
+
+```ts
+await transaction(async () => {
+  await db("orders").insert(order); // survives
+
+  try {
+    await transaction(async () => {
+      await db("items").insert(item);
+      throw new Error("out of stock"); // only this is rolled back
+    });
+  } catch {
+    // handle it
+  }
+
+  await db("audit").insert(entry); // still in the outer transaction
+});
+
+// the outer transaction commits: the order and the audit row are both saved
+```
+
+Without savepoints, a nested helper's failure would silently abandon its caller's
+writes too — which is the sort of bug you find in production, months later.
+
+### Drivers and the pooling trap
+
+A transaction needs every statement to run on **one** connection. A connection
+*pool* hands each statement to whichever connection is free — so issuing `BEGIN`
+through a pool wraps nothing: the `INSERT` after it can land on a different
+connection entirely, the `COMMIT` commits nothing, and a failure half-writes.
+It looks like it works. It doesn't.
+
+So a pooled driver implements `begin()` on its `Connection`, checking one
+connection out and running the whole transaction on it. Keel's Postgres adapter
+does this automatically when you hand it a `Pool` (it checks for `connect()`), and
+releases the connection afterwards even if the `COMMIT` throws.
+
+| Driver | Transactions |
+|--------|--------------|
+| Postgres (`Pool`) | ✅ a dedicated connection is checked out |
+| Postgres (`Client`), SQLite, libSQL | ✅ `BEGIN` / `COMMIT` on the one connection they have |
+| **Cloudflare D1** | ❌ — no interactive transactions; use `database.batch([...])` |
+
+D1 can't hold a transaction open across awaits, so `transaction()` on it **throws
+a clear error** rather than letting a `BEGIN` fail cryptically. A transaction that
+quietly isn't one is far worse than one that refuses to start.
+
+Writing your own driver? Implement `begin(): Promise<TransactionConnection>` if it
+pools. If it owns a single connection, you can leave it out and Keel will use
+`BEGIN`/`COMMIT`/`ROLLBACK`.
+
 ## Typed rows
 
 Pass a row type for typed results — it flows through to `get()` and `first()`:

package/docs/examples/configuration.ts

@@ -79,3 +79,43 @@ const data: ConfigData = {
   app: { name: "Keel", port: 3000 },
 };
 export { data };
+
+/* --- Environment validation --- */
+
+import { defineEnv, envVar, EnvValidationError } from "@shaferllc/keel/core";
+
+export const validated = defineEnv({
+  APP_KEY: envVar.string({ required: true, description: "32+ random characters" }),
+  PORT: envVar.number({ default: 3000 }),
+  NODE_ENV: envVar.enum(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: envVar.url({ required: true }),
+  DEBUG: envVar.boolean({ default: false }),
+  SENTRY_DSN: envVar.string(),
+});
+
+export function typedValues() {
+  const key: string = validated.APP_KEY;
+  const port: number = validated.PORT;
+  const mode: "development" | "test" | "production" = validated.NODE_ENV;
+  const debug: boolean = validated.DEBUG;
+  const dsn: string | undefined = validated.SENTRY_DSN;
+  const url: string = validated.DATABASE_URL;
+
+  return { key, port, mode, debug, dsn, url };
+}
+
+export function withCustomValidation() {
+  return defineEnv(
+    {
+      APP_KEY: envVar.string({
+        required: true,
+        validate: (value) => (value.length >= 32 ? true : "must be at least 32 characters"),
+      }),
+    },
+    { source: { APP_KEY: "x".repeat(32) } },
+  );
+}
+
+export function handlingTheFailure(error: unknown): string[] {
+  return error instanceof EnvValidationError ? error.problems : [];
+}