@shaferllc/keel 0.66.0 → 0.68.0

package/AGENTS.md

@@ -0,0 +1,167 @@
+# AGENTS.md — working in Keel with an AI agent
+
+Guidance for AI coding agents (Claude Code, Cursor, …) editing **Keel** — the
+house framework for Node.js — or an app built on it. Humans: this is also a fast
+orientation. For prose guides see [`docs/`](./docs); for a machine-readable
+surface, run the [MCP server](#mcp-server-recommended).
+
+> **The fastest path:** connect the Keel MCP server (below) and call
+> `keel_overview` first. It returns conventions, the folder map, every doc
+> topic, and the generators. Then `keel_search_docs` / `keel_read_doc` for
+> depth, `keel_search_api` to find exports, `keel_scaffold` to generate code.
+
+---
+
+## What Keel is
+
+A small, legible MVC framework: a real **service container**, **service
+providers**, dot-notation **config**, expressive **routing**, active-record
+**models**, a **queue**, **auth**, and a code-generating **console**.
+[Hono](https://hono.dev) powers HTTP; everything above it is Keel's. The whole
+core is a few hundred lines per file in `src/core/` — read it, nothing is magic.
+
+## The one import rule
+
+Everything userland comes from a single entry point:
+
+```ts
+import { Router, Model, config, ServiceProvider } from "@shaferllc/keel/core";
+```
+
+- **In a consuming app** (the `keel-app` starter, or your own): use
+  `@shaferllc/keel/core`. This is what generated stubs emit.
+- **Inside this framework repo's example app** (`app/`, `routes/`, `bootstrap/`):
+  the code uses the `@keel/core` tsconfig **path alias** that points at
+  `src/core/`. Match the file you're editing — don't "fix" `@keel/core` to the
+  package name inside this repo.
+
+Never deep-import `@shaferllc/keel/core/model.js`. If a symbol isn't exported
+from `/core`, that's intentional. Find exports with `keel_search_api` or read
+`src/core/index.ts`.
+
+## Folder layout of a Keel app
+
+| Path | What lives there |
+|------|------------------|
+| `app/Controllers/` | Controller classes (resolved from the container → DI) |
+| `app/Providers/` | Service providers (`register()` then `boot()`) |
+| `app/Http/Middleware/` | Hono middleware handlers |
+| `app/Http/Kernel.ts` | The HTTP kernel — global middleware, error handling |
+| `app/Models/` | Active-record models extending `Model` |
+| `app/Jobs/`, `app/Notifications/`, `app/Transformers/` | Queue jobs, notifications, API serializers |
+| `config/*.ts` | Config files; read via `config("app.name")` |
+| `routes/web.ts` | Route definitions — default export receives the `Router` |
+| `database/factories/`, `database/seeders/`, `database/migrations/` | Data tooling |
+| `bootstrap/app.ts` | Assembles the `Application`, boots providers, loads routes |
+| `.env` | Environment, loaded into `env(...)` and config |
+
+## Core mental model
+
+1. **Container.** Every service is registered in and resolved out of the
+   container. `bind` (transient), `singleton` (once), `instance` (existing
+   value), `make(Token)` (resolve). Constructor injection: a controller/service
+   with `constructor(private app: Container)` gets it automatically.
+2. **Providers.** `register()` binds things into the container; `boot()` runs
+   after all providers registered, to wire things together. Register providers
+   in `bootstrap/providers.ts`.
+3. **Config.** `config("app.port", 3000)` reads `config/app.ts` merged with
+   `.env`. Dot-notation, with a default.
+4. **Routing.** `router.get("/x", [Controller, "method"])` or a closure. Name
+   routes with `.name()`, group with `.group()`, constrain params with
+   `.where()`, build URLs with `router.url("name", params)`.
+5. **Request context.** Inside a handler, `param()`, `query()`, `body()`,
+   `json()`, `text()` read/write the current request via async-local context —
+   no need to thread `c` everywhere (though the Hono `Ctx` is available).
+
+## How to add things (prefer the generators)
+
+Use `keel_scaffold` (MCP) or the console — both emit the correct stub with the
+right imports and target path. Then wire it up.
+
+| Goal | Command | Then |
+|------|---------|------|
+| Controller | `keel make:controller Post` (`-r` for REST) | add a route in `routes/web.ts` |
+| Provider | `keel make:provider Billing` | register in `bootstrap/providers.ts` |
+| Middleware | `keel make:middleware Auth` | attach in `app/Http/Kernel.ts` or per-route |
+| Model | *(no generator — extend `Model`)* | set `static table`; add relations |
+| Factory | `keel make:factory User` | reference the model |
+| Seeder | `keel make:seeder Database` | call factories in `run()` |
+| Job | `keel make:job SendWelcome` | `dispatch(new SendWelcomeJob())` |
+| Notification | `keel make:notification Paid` | `notify(user, new PaidNotification())` |
+| Transformer | `keel make:transformer User` | return it from a controller |
+
+**Scaffolding does not write files** via MCP — it returns code + path; you write
+it. The console (`keel make:*`) does write, and refuses to overwrite.
+
+A minimal controller and route:
+
+```ts
+// app/Controllers/PostController.ts
+import type { Ctx } from "@shaferllc/keel/core";
+export class PostController {
+  index(c: Ctx) { return c.json({ ok: true }); }
+}
+
+// routes/web.ts
+router.get("/posts", [PostController, "index"]).name("posts.index");
+```
+
+## Commands
+
+```bash
+npm run dev            # example app on http://localhost:3000 (tsx watch)
+npm run serve          # keel serve
+npm run keel -- routes # list registered routes
+npm run keel -- make:controller Foo
+npm run mcp            # start the MCP server over stdio (dev)
+npm test               # node --test over tests/*.test.ts
+npm run typecheck      # tsc --noEmit — run before you finish
+npm run build          # regenerate AI artifacts + compile to dist/
+npm run build:ai       # regenerate llms.txt, llms-full.txt, docs/ai-manifest.json
+```
+
+## Conventions & guardrails
+
+- **TypeScript, strict, ESM.** `.js` extensions in relative imports (NodeNext).
+  No default exports except where the pattern already uses them (routes).
+- **Match the surrounding file** — comment density, naming, idioms. Keel prizes
+  legibility; write code that reads like `src/core/`.
+- **Test with the real thing.** `TestClient`/`testClient` drives the HTTP stack
+  in-process; `hash.fake()`, `fakeDisk()`, `ArrayTransport`, `MemoryDriver`, and
+  `EventBuffer` make side-effecting subsystems deterministic. See
+  [`docs/testing.md`](./docs/testing.md).
+- **Run `npm run typecheck` before finishing.** The whole framework is typed end
+  to end; a green `tsc` is the bar.
+- **After editing docs or the export surface, run `npm run build:ai`** so
+  `llms.txt`, `llms-full.txt`, and `docs/ai-manifest.json` stay in sync (the MCP
+  server reads the manifest).
+
+## MCP server (recommended)
+
+Keel ships an MCP server exposing its docs, the full public API surface, the
+generators, and framework conventions to any MCP-capable agent.
+
+**Claude Code:**
+```bash
+claude mcp add keel -- npx -y keel-mcp        # in an app that depends on @shaferllc/keel
+```
+Or, hacking on the framework itself:
+```bash
+claude mcp add keel -- npm --prefix /path/to/keel run mcp
+```
+
+**`.mcp.json` / Cursor / other clients:**
+```json
+{ "mcpServers": { "keel": { "command": "npx", "args": ["-y", "keel-mcp"] } } }
+```
+
+Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
+`keel_list_generators`, `keel_scaffold`. Resources: `keel://overview`,
+`keel://llms-full`, `keel://docs/<slug>`. See [`docs/ai.md`](./docs/ai.md).
+
+## Where to read next
+
+- [`docs/getting-started.md`](./docs/getting-started.md) — a guided first hour
+- [`docs/architecture.md`](./docs/architecture.md) — a request from socket to response
+- [`docs/container.md`](./docs/container.md) — the DI core everything rests on
+- [`llms-full.txt`](./llms-full.txt) — every guide in one file, for a fresh context

package/README.md

@@ -108,11 +108,38 @@ npm run keel serve --port 8080      # start the server on a chosen port
 npm run keel make:controller Post   # -> app/Controllers/PostController.ts
 npm run keel make:provider Billing  # -> app/Providers/BillingServiceProvider.ts
 npm run keel make:middleware Auth   # -> app/Http/Middleware/authMiddleware.ts
+npm run keel mcp                    # start the MCP server (docs + API for AI agents)
 ```
 
 Under the hood the console binary is `bin/keel.ts`; the npm scripts wrap it with
 `tsx`.
 
+## Built for AI ⚓🤖
+
+Keel is designed to be **written with an AI agent**. Alongside the human docs it
+ships a machine-readable surface that stays generated-in-sync, never stale:
+
+- **An MCP server.** `keel-mcp` exposes Keel's docs, its full public API (380+
+  exports), the generators, and its conventions to any [MCP](https://modelcontextprotocol.io)
+  client. Connect it in Claude Code:
+  ```bash
+  claude mcp add keel -- npx -y keel-mcp
+  ```
+  Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
+  `keel_list_generators`, `keel_scaffold`. Resources: `keel://overview`,
+  `keel://llms-full`, `keel://docs/<slug>`.
+- **[`AGENTS.md`](./AGENTS.md).** The agent playbook — the one import rule, the
+  folder map, the container/provider model, a "how to add X" table, and the
+  guardrails. `CLAUDE.md` points to it.
+- **[`llms.txt`](./llms.txt) + [`llms-full.txt`](./llms-full.txt).** A
+  [spec-compliant](https://llmstxt.org) doc index and a one-file concatenation of
+  every guide, both shipped in the npm package for drop-in context.
+- **Generators an agent can drive.** `keel_scaffold` (or `keel make:*`) emits the
+  correct stub with the right imports and path for every construct.
+
+Full guide: **[docs/ai.md](./docs/ai.md)**. Regenerate the surface after doc or
+export changes with `npm run build:ai` (also runs automatically on `npm run build`).
+
 ## Project layout
 
 ```
@@ -191,7 +218,8 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Redis](./docs/redis.md) | Pluggable client, memory driver, cache adapter |
 | [Logger](./docs/logger.md) | Structured logging, per-request `reqId`, redaction |
 | [Static Files](./docs/static-files.md) | serveStatic(), caching, dot-file safety |
-| [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), edge-safe |
+| [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), signed URLs, direct uploads |
+| [Health Checks](./docs/health.md) | `/health/live` + `/health/ready`, pluggable checks |
 | [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
 | [Templates](./docs/templates.md) | `{{ }}` + `@`-tag templating engine, edge-safe |
 | [Middleware](./docs/middleware.md) | Global middleware, writing your own |
@@ -205,6 +233,7 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [The Console](./docs/console.md) | `serve`, `routes`, `make:*` generators |
 | [Architecture](./docs/architecture.md) | Container, kernel, request lifecycle |
 | [Built on Hono](./docs/hono.md) | The Hono layer underneath, and using it directly |
+| [Building with AI](./docs/ai.md) | MCP server, `AGENTS.md`, `llms.txt`, agent workflow |
 
 ## Testing
 

package/bin/keel-mcp.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Published entry for the Keel MCP server. Registered as the `keel-mcp` bin,
+// so an installed app can wire it up with `npx keel-mcp` (see docs/ai.md).
+import { runMcpServer } from "../dist/mcp/server.js";
+
+runMcpServer().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/core/application.d.ts

@@ -12,7 +12,7 @@ import { Config, type ConfigData } from "./config.js";
 import { Router } from "./http/router.js";
 import { View } from "./view.js";
 import { type ProviderClass } from "./provider.js";
-import type { Listener } from "./events.js";
+import type { Listener, EventName, EmitArgs, Resolve } from "./events.js";
 /** A configurator: a plain function that sets the app up and may return anything. */
 export type Configurator = (app: Application) => unknown;
 export interface BootOptions {
@@ -58,13 +58,13 @@ export declare class Application extends Container {
      * `app.on(...)` and the global `listen()` helper reach the same emitter.
      * Returns an unsubscribe function.
      */
-    on<T = unknown>(event: string, listener: Listener<T>): () => void;
+    on<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Subscribe for a single emission. Returns an unsubscribe function. */
-    once<T = unknown>(event: string, listener: Listener<T>): () => void;
+    once<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Unsubscribe a listener registered with `on()`/`once()`. */
-    off<T = unknown>(event: string, listener: Listener<T>): this;
+    off<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): this;
     /** Emit an app event, awaiting every listener in registration order. */
-    emit<T = unknown>(event: string, payload?: T): Promise<void>;
+    emit<T = unknown, E extends EventName = EventName>(event: E, ...args: EmitArgs<Resolve<T, E>>): Promise<void>;
     /** Merge a config object into the repository under its top-level keys. */
     private mergeConfig;
     /** Load .env via dotenv (Node only; no-op elsewhere). */

package/dist/core/application.js

@@ -95,8 +95,8 @@ export class Application extends Container {
         return this;
     }
     /** Emit an app event, awaiting every listener in registration order. */
-    async emit(event, payload) {
-        await this.make(Events).emit(event, payload);
+    async emit(event, ...args) {
+        await this.make(Events).emit(event, ...args);
     }
     /** Merge a config object into the repository under its top-level keys. */
     mergeConfig(data) {

package/dist/core/cache.d.ts

@@ -5,6 +5,23 @@
  * the global `cache()` helper.
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
+ *
+ * Features borrowed from bentocache (AdonisJS' cache), kept inside keel's
+ * single-store, edge-safe model:
+ *
+ *   - Stampede protection — concurrent `remember()` calls for the same cold key
+ *     run the factory ONCE and share the result, instead of dog-piling.
+ *   - Grace / stale-on-error — with a `grace` window, an expired value is kept
+ *     a little longer and served if the refreshing factory throws.
+ *   - Tags — group entries and invalidate them together with `deleteByTag()`.
+ *   - Namespaces — `namespace("users")` scopes keys under a prefix, and its
+ *     `flush()` clears only that namespace.
+ *
+ * Tag and namespace invalidation use version stamps, not a key index: each tag
+ * carries a counter, every entry records the counter values it was written at,
+ * and invalidation just bumps the counter — so an entry whose tag has moved on
+ * reads as a miss. O(1) invalidation, no key-set bookkeeping, works on any
+ * `CacheStore`.
  */
 export interface CacheStore {
     get(key: string): Promise<unknown> | unknown;
@@ -20,22 +37,82 @@ export declare class MemoryStore implements CacheStore {
     delete(key: string): void;
     clear(): void;
 }
+/** Options for `put`/`add`. */
+export interface PutOptions {
+    /** Tags to associate with this entry, for `deleteByTag` invalidation. */
+    tags?: string[];
+}
+/** Options for the `remember` family. */
+export interface RememberOptions extends PutOptions {
+    /**
+     * Grace window in seconds. After the value's TTL lapses, keep it this much
+     * longer and serve it if the refreshing factory throws (stale-on-error).
+     */
+    grace?: number;
+}
 export declare class Cache {
     private store;
     constructor(store?: CacheStore);
+    private prefix;
+    private nsTag?;
+    private inflight;
+    /** Apply this cache's namespace prefix to a logical key. */
+    private k;
+    private tagKey;
+    private tagVersion;
+    /** Snapshot the current version of each tag, to stamp onto a new entry. */
+    private stampTags;
+    /** True if any recorded tag version is behind the live one (invalidated). */
+    private tagsInvalidated;
+    /**
+     * Read the raw envelope for a key. Returns undefined when absent OR when a tag
+     * has invalidated it — tag/namespace invalidation is a hard miss (not grace-
+     * eligible). TTL freshness is left to callers, so grace can still see a stale
+     * entry.
+     */
+    private entry;
+    private write;
     get<T = unknown>(key: string, fallback?: T): Promise<T>;
-    /** Store a value, optionally expiring after `ttlSeconds`. */
-    put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /** Store a value, optionally expiring after `ttlSeconds`, with optional tags. */
+    put(key: string, value: unknown, ttlSeconds?: number, options?: PutOptions): Promise<void>;
+    /** Store a value only if the key is absent. Returns whether it was written. */
+    add(key: string, value: unknown, ttlSeconds?: number, options?: PutOptions): Promise<boolean>;
     has(key: string): Promise<boolean>;
+    /** The inverse of `has` — true when the key is absent or expired. */
+    missing(key: string): Promise<boolean>;
     forget(key: string): Promise<void>;
+    /** Forget several keys at once. */
+    forgetMany(keys: string[]): Promise<void>;
     /** Read and remove a value. */
     pull<T = unknown>(key: string, fallback?: T): Promise<T>;
     flush(): Promise<void>;
+    /**
+     * Invalidate every entry carrying any of these tags by bumping the tag's
+     * version — entries stamped with the old version then read as a miss. O(#tags),
+     * no key scan; invalidated entries fall out on their own TTL.
+     */
+    deleteByTag(tags: string[]): Promise<void>;
+    /**
+     * A cache scoped under a key prefix. Keys written through it live at
+     * `name:key`, and its `flush()` clears only this namespace (via an implicit
+     * tag) — the rest of the store is untouched. Namespaces nest.
+     *
+     *   const users = cache().namespace("users");
+     *   await users.put("1", user);   // stored at "users:1"
+     *   await users.flush();          // clears only the users namespace
+     */
+    namespace(name: string): Cache;
     /**
      * Return the cached value, or compute it with `factory`, cache it for
      * `ttlSeconds`, and return it.
+     *
+     * Concurrent calls for the same cold key share one factory run (stampede
+     * protection). With `{ grace }`, an expired value is retained that many extra
+     * seconds and served if the refreshing factory throws (stale-on-error). With
+     * `{ tags }`, the cached value joins those tags for `deleteByTag`.
      */
-    remember<T>(key: string, ttlSeconds: number, factory: () => T | Promise<T>): Promise<T>;
-    /** Like remember(), but cached forever (no TTL). */
-    rememberForever<T>(key: string, factory: () => T | Promise<T>): Promise<T>;
+    remember<T>(key: string, ttlSeconds: number, factory: () => T | Promise<T>, options?: RememberOptions): Promise<T>;
+    /** Like remember(), but cached forever (no TTL). Also stampede-protected. */
+    rememberForever<T>(key: string, factory: () => T | Promise<T>, options?: PutOptions): Promise<T>;
+    private resolve;
 }

package/dist/core/cache.js

@@ -5,6 +5,23 @@
  * the global `cache()` helper.
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
+ *
+ * Features borrowed from bentocache (AdonisJS' cache), kept inside keel's
+ * single-store, edge-safe model:
+ *
+ *   - Stampede protection — concurrent `remember()` calls for the same cold key
+ *     run the factory ONCE and share the result, instead of dog-piling.
+ *   - Grace / stale-on-error — with a `grace` window, an expired value is kept
+ *     a little longer and served if the refreshing factory throws.
+ *   - Tags — group entries and invalidate them together with `deleteByTag()`.
+ *   - Namespaces — `namespace("users")` scopes keys under a prefix, and its
+ *     `flush()` clears only that namespace.
+ *
+ * Tag and namespace invalidation use version stamps, not a key index: each tag
+ * carries a counter, every entry records the counter values it was written at,
+ * and invalidation just bumps the counter — so an entry whose tag has moved on
+ * reads as a miss. O(1) invalidation, no key-set bookkeeping, works on any
+ * `CacheStore`.
  */
 /** The default in-memory store. */
 export class MemoryStore {
@@ -29,24 +46,109 @@ export class MemoryStore {
         this.data.clear();
     }
 }
+function isEntry(x) {
+    return typeof x === "object" && x !== null && x.__keelCache === 1;
+}
+// The store key that holds a tag's version counter. Never namespaced, never
+// expired — a bump must outlive every entry that recorded the old version.
+const TAG_VERSION_PREFIX = "\u0000keel:tagv:";
 export class Cache {
     store;
     constructor(store = new MemoryStore()) {
         this.store = store;
     }
+    // Key prefix + implicit tag for a namespaced cache (empty on the root).
+    prefix = "";
+    nsTag;
+    // Stampede protection: in-flight factory promises, keyed by prefixed key.
+    inflight = new Map();
+    /** Apply this cache's namespace prefix to a logical key. */
+    k(key) {
+        return this.prefix + key;
+    }
+    tagKey(tag) {
+        return TAG_VERSION_PREFIX + tag;
+    }
+    async tagVersion(tag) {
+        const v = await this.store.get(this.tagKey(tag));
+        return typeof v === "number" ? v : 0;
+    }
+    /** Snapshot the current version of each tag, to stamp onto a new entry. */
+    async stampTags(tags) {
+        const out = {};
+        for (const tag of tags)
+            out[tag] = await this.tagVersion(tag);
+        return out;
+    }
+    /** True if any recorded tag version is behind the live one (invalidated). */
+    async tagsInvalidated(recorded) {
+        for (const [tag, ver] of Object.entries(recorded)) {
+            if ((await this.tagVersion(tag)) > ver)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Read the raw envelope for a key. Returns undefined when absent OR when a tag
+     * has invalidated it — tag/namespace invalidation is a hard miss (not grace-
+     * eligible). TTL freshness is left to callers, so grace can still see a stale
+     * entry.
+     */
+    async entry(key) {
+        const raw = await this.store.get(this.k(key));
+        if (raw === undefined)
+            return undefined;
+        const e = isEntry(raw) ? raw : { __keelCache: 1, v: raw, e: 0 };
+        if (e.t && (await this.tagsInvalidated(e.t)))
+            return undefined;
+        return e;
+    }
+    async write(key, value, ttlSeconds, graceSeconds = 0, tags = []) {
+        const allTags = this.nsTag ? [this.nsTag, ...tags] : tags;
+        const now = Date.now();
+        const e = ttlSeconds ? now + ttlSeconds * 1000 : 0;
+        const storeTtlMs = ttlSeconds ? (ttlSeconds + graceSeconds) * 1000 : undefined;
+        const t = allTags.length ? await this.stampTags(allTags) : undefined;
+        const entry = { __keelCache: 1, v: value, e };
+        if (t)
+            entry.t = t;
+        await this.store.set(this.k(key), entry, storeTtlMs);
+    }
     async get(key, fallback) {
-        const value = await this.store.get(key);
-        return (value === undefined ? fallback : value);
+        const entry = await this.entry(key);
+        if (!entry)
+            return fallback;
+        if (entry.e && entry.e < Date.now())
+            return fallback; // expired (grace-retained)
+        return entry.v;
+    }
+    /** Store a value, optionally expiring after `ttlSeconds`, with optional tags. */
+    async put(key, value, ttlSeconds, options) {
+        await this.write(key, value, ttlSeconds, 0, options?.tags ?? []);
     }
-    /** Store a value, optionally expiring after `ttlSeconds`. */
-    async put(key, value, ttlSeconds) {
-        await this.store.set(key, value, ttlSeconds ? ttlSeconds * 1000 : undefined);
+    /** Store a value only if the key is absent. Returns whether it was written. */
+    async add(key, value, ttlSeconds, options) {
+        if (await this.has(key))
+            return false;
+        await this.put(key, value, ttlSeconds, options);
+        return true;
     }
     async has(key) {
-        return (await this.store.get(key)) !== undefined;
+        const entry = await this.entry(key);
+        if (!entry)
+            return false;
+        return !(entry.e && entry.e < Date.now());
+    }
+    /** The inverse of `has` — true when the key is absent or expired. */
+    async missing(key) {
+        return !(await this.has(key));
     }
     async forget(key) {
-        await this.store.delete(key);
+        await this.store.delete(this.k(key));
+    }
+    /** Forget several keys at once. */
+    async forgetMany(keys) {
+        await Promise.all(keys.map((k) => this.store.delete(this.k(k))));
     }
     /** Read and remove a value. */
     async pull(key, fallback) {
@@ -55,27 +157,83 @@ export class Cache {
         return value;
     }
     async flush() {
-        await this.store.clear();
+        // A namespace clears itself by moving its tag version on; the root wipes the
+        // whole store.
+        if (this.nsTag)
+            await this.deleteByTag([this.nsTag]);
+        else
+            await this.store.clear();
+    }
+    /**
+     * Invalidate every entry carrying any of these tags by bumping the tag's
+     * version — entries stamped with the old version then read as a miss. O(#tags),
+     * no key scan; invalidated entries fall out on their own TTL.
+     */
+    async deleteByTag(tags) {
+        for (const tag of tags) {
+            const current = await this.tagVersion(tag);
+            await this.store.set(this.tagKey(tag), current + 1); // no TTL — must persist
+        }
+    }
+    /**
+     * A cache scoped under a key prefix. Keys written through it live at
+     * `name:key`, and its `flush()` clears only this namespace (via an implicit
+     * tag) — the rest of the store is untouched. Namespaces nest.
+     *
+     *   const users = cache().namespace("users");
+     *   await users.put("1", user);   // stored at "users:1"
+     *   await users.flush();          // clears only the users namespace
+     */
+    namespace(name) {
+        const child = new Cache(this.store);
+        child.prefix = `${this.prefix}${name}:`;
+        child.nsTag = `\u0000keel:ns:${this.prefix}${name}`;
+        return child;
     }
     /**
      * Return the cached value, or compute it with `factory`, cache it for
      * `ttlSeconds`, and return it.
+     *
+     * Concurrent calls for the same cold key share one factory run (stampede
+     * protection). With `{ grace }`, an expired value is retained that many extra
+     * seconds and served if the refreshing factory throws (stale-on-error). With
+     * `{ tags }`, the cached value joins those tags for `deleteByTag`.
      */
-    async remember(key, ttlSeconds, factory) {
-        const existing = await this.store.get(key);
-        if (existing !== undefined)
-            return existing;
-        const value = await factory();
-        await this.put(key, value, ttlSeconds);
-        return value;
+    remember(key, ttlSeconds, factory, options) {
+        return this.resolve(key, ttlSeconds, factory, options?.grace ?? 0, options?.tags ?? []);
     }
-    /** Like remember(), but cached forever (no TTL). */
-    async rememberForever(key, factory) {
-        const existing = await this.store.get(key);
-        if (existing !== undefined)
-            return existing;
-        const value = await factory();
-        await this.put(key, value);
-        return value;
+    /** Like remember(), but cached forever (no TTL). Also stampede-protected. */
+    rememberForever(key, factory, options) {
+        return this.resolve(key, undefined, factory, 0, options?.tags ?? []);
+    }
+    async resolve(key, ttlSeconds, factory, graceSeconds, tags) {
+        const entry = await this.entry(key);
+        const fresh = entry && (!entry.e || entry.e > Date.now());
+        if (fresh)
+            return entry.v;
+        // Stampede protection: join an in-flight computation for this key.
+        const pending = this.inflight.get(key);
+        if (pending)
+            return pending;
+        const run = (async () => {
+            try {
+                // Defer to a microtask so a synchronously-throwing factory rejects the
+                // shared promise only after every joiner has attached its handler.
+                const value = await Promise.resolve().then(factory);
+                await this.write(key, value, ttlSeconds, graceSeconds, tags);
+                return value;
+            }
+            catch (err) {
+                // Grace: a stale-but-retained value rescues a failing refresh.
+                if (entry && graceSeconds > 0)
+                    return entry.v;
+                throw err;
+            }
+            finally {
+                this.inflight.delete(key);
+            }
+        })();
+        this.inflight.set(key, run);
+        return run;
     }
 }

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

@@ -0,0 +1,12 @@
+/** Code-generation templates for `keel make:*`. */
+export declare function controllerStub(name: string): string;
+export declare function resourceControllerStub(name: string): string;
+export declare function providerStub(name: string): string;
+export declare function middlewareStub(name: string): string;
+/** `name` is the model class (e.g. "User") the factory builds. */
+export declare function factoryStub(model: string): string;
+export declare function seederStub(name: string): string;
+export declare function jobStub(name: string): string;
+export declare function notificationStub(name: string): string;
+/** `name` is the class (e.g. "UserTransformer"); `model` is the value it maps. */
+export declare function transformerStub(name: string, model: string): string;