@shaferllc/keel 0.83.3 → 0.83.4

package/README.md

@@ -206,6 +206,7 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Sessions](./docs/sessions.md) | Cookie-backed sessions, flash messages |
 | [Authentication](./docs/authentication.md) | Session auth, guards, user provider |
 | [Gates](./docs/gates.md) | Signup gating — invite codes & email allowlist |
+| [Hosting](./docs/hosting.md) | Cloudflare, SQL dump, secrets for hosted Workers |
 | [Authorization](./docs/authorization.md) | Ability gates & policies, `can`/`authorize` |
 | [Database](./docs/database.md) | Driver-agnostic query builder |
 | [Models](./docs/models.md) | Active-record: find/create/save, casts, relations |
@@ -269,29 +270,8 @@ lines / ~91% branches**.
 
 ## Roadmap
 
-Keel's first release is the **MVP core**: container, routing, middleware,
-config, and the console. On deck:
-
-- [x] View / templating layer (Hono JSX) — **v0.2.0**
-- [x] Cloudflare Workers–safe core — **v0.2.0**
-- [x] Global helpers: `config()`, `app()`, `view()` — **v0.3.0 / v0.4.0**
-- [x] Error & exception handling — **v0.5.0**
-- [x] Request/response + container helpers — **v0.6.0–v0.9.0**
-- [x] Validation (Zod-compatible) — **v0.10.0**
-- [x] First-class routing (groups, resources, named routes) — **v0.11.0**
-- [x] Domain routing, matchers, Inertia adapter — **v0.12.0**
-- [x] Test suite (~99% coverage)
-- [x] Query builder (driver-agnostic) — **v0.28.0**
-- [x] Active-record Model layer — **v0.29.0**
-- [x] Migrations (schema builder) — **v0.30.0**
-- [x] Model relationships (hasMany / belongsTo / belongsToMany) — **v0.31.0**
-- [x] Factories & seeders (built-in Faker) — **v0.32.0**
-- [x] Model attribute casts + mass-assignment guarding — **v0.33.0**
-- [x] Mail (fluent mailer, pluggable transports) — **v0.34.0**
-- [x] Queues / background jobs (pluggable drivers) — **v0.35.0**
-- [x] Notifications (multi-channel, queueable) — **v0.36.0**
-- [ ] Publish `src/core` as the `@keel/core` package
-
+The MVP core and the major subsystems are shipped. Recent focus is Keel Cloud
+support (gates, hosting, MCP Cloud tools, billing portal) and starter kits.
 See [CHANGELOG.md](./CHANGELOG.md) for release history.
 
 ## Contributing

package/dist/billing/billable.d.ts

@@ -67,6 +67,7 @@ export interface BillableInstance {
     checkout(prices: string | PriceRef | (string | PriceRef)[], options?: ProductCheckoutOptions): Promise<CheckoutSession>;
     createSetupIntent(): Promise<SetupIntent>;
     paymentMethods(): Promise<PaymentMethod[]>;
+    billingPortal(returnUrl: string): Promise<import("./gateway.js").BillingPortalSession>;
 }
 /**
  * The class a `Billable(Base)` call returns: billing instances plus all of

package/dist/billing/billable.js

@@ -171,6 +171,14 @@ export function Billable(Base) {
                 return [];
             return gateway.paymentMethods(this.billing_customer_id);
         }
+        /** Open the hosted customer portal (manage card / cancel). */
+        async billingPortal(returnUrl) {
+            const gateway = this.billingGateway();
+            if (!gateway.createBillingPortalSession) {
+                throw new BillingError(`The "${gateway.name}" gateway does not support a billing portal.`, gateway.name);
+            }
+            return gateway.createBillingPortalSession(await this.getCustomerId(), returnUrl);
+        }
     }
     return BillableModel;
 }

package/dist/billing/drivers/fake.d.ts

@@ -42,6 +42,10 @@ export declare class FakeGateway implements BillingGateway {
     refund(params: RefundParams): Promise<GatewayRefund>;
     listInvoices(customer: string): Promise<GatewayInvoice[]>;
     createCheckoutSession(params: CheckoutParams): Promise<CheckoutSession>;
+    createBillingPortalSession(customer: string, returnUrl: string): Promise<{
+        id: string;
+        url: string;
+    }>;
     createSetupIntent(customer: string): Promise<SetupIntent>;
     paymentMethods(customer: string): Promise<PaymentMethod[]>;
     verifyWebhook(rawBody: string, headers: HeaderBag, secret: string): Promise<import("../gateway.js").WebhookEvent | null>;

package/dist/billing/drivers/fake.js

@@ -129,6 +129,11 @@ export class FakeGateway {
         const id = this.id("cs");
         return { id, url: `https://fake.checkout/${id}`, clientToken: `ctok_${id}` };
     }
+    async createBillingPortalSession(customer, returnUrl) {
+        this.record("createBillingPortalSession", customer, returnUrl);
+        const id = this.id("bps");
+        return { id, url: `https://fake.portal/${id}?return=${encodeURIComponent(returnUrl)}` };
+    }
     async createSetupIntent(customer) {
         this.record("createSetupIntent", customer);
         const id = this.id("seti");

package/dist/billing/drivers/stripe.d.ts

@@ -28,6 +28,7 @@ export declare class StripeGateway implements BillingGateway {
     createCheckoutSession(params: CheckoutParams): Promise<CheckoutSession>;
     createSetupIntent(customer: string): Promise<SetupIntent>;
     paymentMethods(customer: string): Promise<PaymentMethod[]>;
+    createBillingPortalSession(customer: string, returnUrl: string): Promise<import("../gateway.js").BillingPortalSession>;
     verifyWebhook(rawBody: string, headers: HeaderBag, secret: string): Promise<WebhookEvent | null>;
     private normalize;
 }

package/dist/billing/drivers/stripe.js

@@ -219,6 +219,13 @@ export class StripeGateway {
             };
         });
     }
+    async createBillingPortalSession(customer, returnUrl) {
+        const session = await this.call("POST", "/billing_portal/sessions", {
+            customer,
+            return_url: returnUrl,
+        });
+        return { id: String(session.id), url: String(session.url ?? "") };
+    }
     /* ------------------------------ webhooks ------------------------------- */
     async verifyWebhook(rawBody, headers, secret) {
         const header = headers("stripe-signature");

package/dist/billing/gateway.d.ts

@@ -162,6 +162,13 @@ export interface BillingGateway {
     verifyWebhook(rawBody: string, headers: HeaderBag, secret: string): Promise<WebhookEvent | null>;
     createSetupIntent?(customer: string): Promise<SetupIntent>;
     paymentMethods?(customer: string): Promise<PaymentMethod[]>;
+    /** Hosted customer portal (manage card / cancel). Stripe-style. */
+    createBillingPortalSession?(customer: string, returnUrl: string): Promise<BillingPortalSession>;
+}
+/** A hosted billing-portal redirect. */
+export interface BillingPortalSession {
+    id: string;
+    url: string;
 }
 /** Raised for gateway/config problems and unsupported-capability calls. */
 export declare class BillingError extends Error {

package/dist/billing/index.d.ts

@@ -16,7 +16,7 @@ export type { BillableTarget, CheckoutOptions } from "./builder.js";
 export { BillingManager, billing, setBilling } from "./manager.js";
 export type { GatewayFactory } from "./manager.js";
 export { BillingError } from "./gateway.js";
-export type { BillingGateway, HeaderBag, CustomerDetails, GatewayCustomer, PriceRef, CreateSubscriptionParams, GatewaySubscription, GatewaySubscriptionItem, SwapParams, CancelParams, ChargeParams, GatewayCharge, RefundParams, GatewayRefund, GatewayInvoice, CheckoutParams, CheckoutSession, SetupIntent, PaymentMethod, WebhookEvent, } from "./gateway.js";
+export type { BillingGateway, HeaderBag, CustomerDetails, GatewayCustomer, PriceRef, CreateSubscriptionParams, GatewaySubscription, GatewaySubscriptionItem, SwapParams, CancelParams, ChargeParams, GatewayCharge, RefundParams, GatewayRefund, GatewayInvoice, CheckoutParams, CheckoutSession, SetupIntent, PaymentMethod, BillingPortalSession, WebhookEvent, } from "./gateway.js";
 export { registerDefaultGateways, StripeGateway, PaddleGateway, FakeGateway } from "./drivers/index.js";
 export type { FakeCall } from "./drivers/index.js";
 export { handleWebhook, resolveBillableUsing } from "./webhooks.js";

package/dist/core/index.d.ts

@@ -102,7 +102,7 @@ export { Session, session, sessionMiddleware } from "./session.js";
 export type { SessionOptions } from "./session.js";
 export { Auth, auth, authGuard, bearerAuth, basicAuth, tokenAuth, token, tokenCan, setUserProvider } from "./auth.js";
 export type { UserProvider, BasicVerifier } from "./auth.js";
-export { createToken, verifyToken, revokeToken, revokeTokens, listTokens, tokenAllows, tokenDenies, setTokensTable, } from "./tokens.js";
+export { createToken, verifyToken, revokeToken, revokeTokens, listTokens, tokenAllows, tokenDenies, setTokensTable, tokensMigration, } from "./tokens.js";
 export type { AccessToken, CreateTokenOptions, IssuedToken } from "./tokens.js";
 export { social, github, google, discord, oauthDriver, oauthState, OAuthDriver, OAuthError, twitter, oauth1Driver, oauth1Signature, OAuth1Driver, } from "./social.js";
 export type { SocialUser, OAuthToken, OAuthConfig, ProviderSpec, RedirectOptions, OAuth1Config, OAuth1Token, OAuth1ProviderSpec, } from "./social.js";

package/dist/core/index.js

@@ -54,7 +54,7 @@ export { HttpException, BadRequestException, UnauthorizedException, PaymentRequi
 export { validate, validateRequest, validated } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
 export { Auth, auth, authGuard, bearerAuth, basicAuth, tokenAuth, token, tokenCan, setUserProvider } from "./auth.js";
-export { createToken, verifyToken, revokeToken, revokeTokens, listTokens, tokenAllows, tokenDenies, setTokensTable, } from "./tokens.js";
+export { createToken, verifyToken, revokeToken, revokeTokens, listTokens, tokenAllows, tokenDenies, setTokensTable, tokensMigration, } from "./tokens.js";
 export { social, github, google, discord, oauthDriver, oauthState, OAuthDriver, OAuthError, twitter, oauth1Driver, oauth1Signature, OAuth1Driver, } from "./social.js";
 export { define, policy, gateBefore, gateAfter, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
 export { Transformer } from "./transformer.js";

package/dist/core/tokens.d.ts

@@ -72,3 +72,5 @@ export declare function revokeToken(selector: string, connection?: string): Prom
 export declare function revokeTokens(tokenableId: string | number, connection?: string): Promise<void>;
 /** List an entity's tokens (metadata only — the secret is never stored). */
 export declare function listTokens(tokenableId: string | number, connection?: string): Promise<AccessToken[]>;
+/** Schema for personal access tokens (SQLite-friendly; works on Postgres with minor tweaks). */
+export declare function tokensMigration(tableName?: string): import("./migrations.js").Migration;

package/dist/core/tokens.js

@@ -153,3 +153,27 @@ function parseAbilities(value) {
         return ["*"];
     }
 }
+/** Schema for personal access tokens (SQLite-friendly; works on Postgres with minor tweaks). */
+export function tokensMigration(tableName = "personal_access_tokens") {
+    return {
+        name: `tokens_00_${tableName}`,
+        async up(schema) {
+            await schema.raw(`
+        CREATE TABLE IF NOT EXISTS ${tableName} (
+          selector TEXT NOT NULL UNIQUE,
+          hash TEXT NOT NULL,
+          tokenable_id TEXT NOT NULL,
+          name TEXT,
+          abilities TEXT,
+          last_used_at INTEGER,
+          expires_at INTEGER,
+          created_at INTEGER
+        )
+      `);
+            await schema.raw(`CREATE INDEX IF NOT EXISTS idx_${tableName}_tokenable ON ${tableName} (tokenable_id)`);
+        },
+        async down(schema) {
+            await schema.dropTable(tableName).catch(() => { });
+        },
+    };
+}

package/dist/mcp/cloud.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Keel Cloud MCP tools — registered only when KEEL_CLOUD_TOKEN is set.
+ *
+ * Talks to a Keel Cloud control plane over HTTP (Bearer token). Agents use these
+ * to create sites, preview/publish, and manage secrets without leaving the IDE.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Register Cloud tools on an existing MCP server when a Cloud token is present. */
+export declare function registerCloudTools(server: McpServer): boolean;

package/dist/mcp/cloud.js

@@ -0,0 +1,179 @@
+/**
+ * Keel Cloud MCP tools — registered only when KEEL_CLOUD_TOKEN is set.
+ *
+ * Talks to a Keel Cloud control plane over HTTP (Bearer token). Agents use these
+ * to create sites, preview/publish, and manage secrets without leaving the IDE.
+ */
+import { z } from "zod";
+const PRESETS = ["minimal", "api", "app", "saas"];
+function cloudConfig() {
+    const token = String(process.env.KEEL_CLOUD_TOKEN ?? "").trim();
+    if (!token)
+        return null;
+    const url = String(process.env.KEEL_CLOUD_URL ?? "http://localhost:3000").replace(/\/$/, "");
+    return { url, token };
+}
+async function cloudFetch(path, init = {}) {
+    const cfg = cloudConfig();
+    if (!cfg)
+        throw new Error("KEEL_CLOUD_TOKEN is not set");
+    const response = await fetch(`${cfg.url}${path}`, {
+        ...init,
+        headers: {
+            authorization: `Bearer ${cfg.token}`,
+            accept: "application/json",
+            ...(init.body ? { "content-type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+        },
+    });
+    const text = await response.text();
+    let body = text;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        /* keep text */
+    }
+    return { ok: response.ok, status: response.status, body };
+}
+function jsonText(data, isError = false) {
+    return {
+        content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+/** Register Cloud tools on an existing MCP server when a Cloud token is present. */
+export function registerCloudTools(server) {
+    if (!cloudConfig())
+        return false;
+    server.registerTool("keel_cloud_me", {
+        title: "Keel Cloud — who am I",
+        description: "Return the Keel Cloud user authenticated by KEEL_CLOUD_TOKEN.",
+        inputSchema: {},
+    }, async () => {
+        const res = await cloudFetch("/api/v1/me");
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_list_sites", {
+        title: "Keel Cloud — list sites",
+        description: "List sites on the current Keel Cloud team. Includes storage_path for local editing and hostnames.",
+        inputSchema: {},
+    }, async () => {
+        const res = await cloudFetch("/api/v1/sites");
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_get_site", {
+        title: "Keel Cloud — get site",
+        description: "Fetch one Keel Cloud site by id (paths, hostnames, status).",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id from keel_cloud_list_sites"),
+        },
+    }, async ({ site_id }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}`);
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_create_site", {
+        title: "Keel Cloud — create site",
+        description: "Create a new Keel Cloud site from a preset (minimal|api|app|saas). Scaffolds source under storage/sites/{slug} and returns storage_path for editing.",
+        inputSchema: {
+            name: z.string().min(1).describe("Human-readable site name"),
+            preset: z.enum(PRESETS).optional().describe("Keel preset (default minimal)"),
+        },
+    }, async ({ name, preset }) => {
+        const res = await cloudFetch("/api/v1/sites", {
+            method: "POST",
+            body: JSON.stringify({ name, preset: preset ?? "minimal" }),
+        });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_preview", {
+        title: "Keel Cloud — deploy preview",
+        description: "Deploy the site's preview Worker (and attach preview hostname when Cloudflare is configured). Safe to call freely while iterating.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+        },
+    }, async ({ site_id }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/preview`, { method: "POST", body: "{}" });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_publish", {
+        title: "Keel Cloud — publish production",
+        description: "Publish the site to its production Worker/hostname. Requires confirm=true (explicit user approval).",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+            confirm: z
+                .boolean()
+                .describe("Must be true to publish — ask the user before setting this"),
+        },
+    }, async ({ site_id, confirm }) => {
+        if (!confirm) {
+            return jsonText({
+                error: "Publish requires confirm=true. Ask the user to confirm before calling again.",
+            }, true);
+        }
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/publish`, {
+            method: "POST",
+            body: JSON.stringify({ confirm: true }),
+        });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_deploys", {
+        title: "Keel Cloud — deploy history",
+        description: "List recent preview/production deploys and logs for a site.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+        },
+    }, async ({ site_id }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/deploys`);
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_set_secret", {
+        title: "Keel Cloud — set secret",
+        description: "Store a secret in the site vault (never in git). Injected into the Worker on the next preview/publish.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+            key: z.string().min(1).describe("Env-style key, e.g. STRIPE_SECRET_KEY"),
+            value: z.string().describe("Secret value (will not be echoed by the dashboard)"),
+        },
+    }, async ({ site_id, key, value }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/secrets`, {
+            method: "PUT",
+            body: JSON.stringify({ key, value }),
+        });
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_export", {
+        title: "Keel Cloud — export manifest",
+        description: "Return the site's export manifest (paths, hostnames, Keel version, SQL dump URLs). Use storage_path / git_url for code; use keel_cloud_export_sql for data.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+        },
+    }, async ({ site_id }) => {
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/export`);
+        return jsonText(res.body, !res.ok);
+    });
+    server.registerTool("keel_cloud_export_sql", {
+        title: "Keel Cloud — export SQL dump",
+        description: "Download a portable .sql dump for local sqlite, preview D1, or production D1. Prefer production after publish for a full escape hatch.",
+        inputSchema: {
+            site_id: z.number().int().describe("Site id"),
+            env: z
+                .enum(["local", "preview", "production"])
+                .optional()
+                .describe("Which database to dump (default local)"),
+        },
+    }, async ({ site_id, env }) => {
+        const environment = env ?? "local";
+        const res = await cloudFetch(`/api/v1/sites/${site_id}/export/sql?env=${environment}`);
+        if (!res.ok)
+            return jsonText(res.body, true);
+        const sql = typeof res.body === "string" ? res.body : JSON.stringify(res.body);
+        return jsonText({
+            site_id,
+            env: environment,
+            sql,
+            hint: "Write this to a .sql file and restore with sqlite3 / D1 import on a real Keel app.",
+        });
+    });
+    return true;
+}

package/dist/mcp/server.d.ts

@@ -11,6 +11,8 @@
  *   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)
+ * When KEEL_CLOUD_TOKEN is set, also:
+ *   keel_cloud_*           create/list/preview/publish sites on Keel Cloud
  * Resources: keel://overview, keel://llms-full, and keel://docs/<slug> per guide.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/mcp/server.js

@@ -11,6 +11,8 @@
  *   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)
+ * When KEEL_CLOUD_TOKEN is set, also:
+ *   keel_cloud_*           create/list/preview/publish sites on Keel Cloud
  * Resources: keel://overview, keel://llms-full, and keel://docs/<slug> per guide.
  */
 import { readFile, readdir, stat } from "node:fs/promises";
@@ -20,6 +22,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { controllerStub, resourceControllerStub, providerStub, middlewareStub, factoryStub, seederStub, jobStub, notificationStub, transformerStub, } from "../core/cli/stubs.js";
+import { registerCloudTools } from "./cloud.js";
 async function exists(p) {
     try {
         await stat(p);
@@ -183,6 +186,18 @@ export async function createServer() {
         "",
         "## Generators — use keel_scaffold or `keel make:*`",
         ...manifest.generators.map((g) => `- ${g.command} → ${g.produces}`),
+        ...(process.env.KEEL_CLOUD_TOKEN?.trim()
+            ? [
+                "",
+                "## Keel Cloud (token detected)",
+                "Cloud tools are enabled. Typical loop:",
+                "1. keel_cloud_create_site { name, preset }",
+                "2. Edit files at the returned storage_path (real Keel app)",
+                "3. keel_cloud_preview { site_id }",
+                "4. keel_cloud_publish { site_id, confirm: true } after user approval",
+                "Also: keel_cloud_list_sites, keel_cloud_get_site, keel_cloud_set_secret, keel_cloud_deploys, keel_cloud_export.",
+            ]
+            : []),
     ].join("\n");
     // ---- tools ----
     server.registerTool("keel_overview", {
@@ -343,6 +358,7 @@ export async function createServer() {
     for (const doc of manifest.docs) {
         server.registerResource(`doc:${doc.slug}`, `keel://docs/${doc.slug}`, { title: doc.title, description: doc.summary || doc.title, mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, text: await readFile(join(root, doc.path), "utf8") }] }));
     }
+    registerCloudTools(server);
     return server;
 }
 /** Boot the server on stdio. Called by the `keel-mcp` bin and `keel mcp`. */
@@ -351,5 +367,8 @@ export async function runMcpServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // stdout is the protocol channel — log to stderr only.
-    console.error("⚓ Keel MCP server running on stdio");
+    const cloud = Boolean(process.env.KEEL_CLOUD_TOKEN?.trim());
+    console.error(cloud
+        ? "⚓ Keel MCP server running on stdio (Cloud tools enabled)"
+        : "⚓ Keel MCP server running on stdio");
 }

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.3",
+  "version": "0.83.4",
   "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",
@@ -208,6 +208,13 @@
       "path": "docs/hooks.md",
       "example": "docs/examples/hooks.ts"
     },
+    {
+      "slug": "hosting",
+      "title": "Hosting",
+      "summary": "Keel Hosting is a small toolkit for hosted Workers / D1 apps: a Cloudflare REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped secret encryption.",
+      "path": "docs/hosting.md",
+      "example": "docs/examples/hosting.ts"
+    },
     {
       "slug": "i18n",
       "title": "Internationalization",
@@ -3084,6 +3091,11 @@
       "kind": "value",
       "module": "tokens"
     },
+    {
+      "name": "tokensMigration",
+      "kind": "value",
+      "module": "tokens"
+    },
     {
       "name": "TooManyRequestsException",
       "kind": "value",

package/docs/ai.md

@@ -61,6 +61,35 @@ package, so it always matches your installed version.
 | `keel_list_generators` | The `keel make:*` generators, what they produce, and their flags. |
 | `keel_scaffold` | Generate a controller/provider/middleware/factory/seeder/job/notification/transformer stub. Returns code + target path — it does **not** write to disk. |
 
+When `KEEL_CLOUD_TOKEN` (and optional `KEEL_CLOUD_URL`) is set, Cloud tools are
+also registered:
+
+| Tool | What it does |
+|------|--------------|
+| `keel_cloud_me` | Authenticated Cloud user |
+| `keel_cloud_list_sites` / `keel_cloud_get_site` | List or fetch a site (includes `storage_path`) |
+| `keel_cloud_create_site` | Create from preset (`minimal` \| `api` \| `app` \| `saas`) |
+| `keel_cloud_preview` | Deploy preview Worker |
+| `keel_cloud_publish` | Publish production — requires `confirm: true` |
+| `keel_cloud_set_secret` | Vault a secret (injected on next deploy) |
+| `keel_cloud_deploys` / `keel_cloud_export` | Deploy history and export manifest |
+| `keel_cloud_export_sql` | Portable `.sql` dump (`local` \| `preview` \| `production`) |
+
+```json
+{
+  "mcpServers": {
+    "keel": {
+      "command": "npx",
+      "args": ["-y", "keel-mcp"],
+      "env": {
+        "KEEL_CLOUD_TOKEN": "kc_…",
+        "KEEL_CLOUD_URL": "https://app.keeljs.cloud"
+      }
+    }
+  }
+}
+```
+
 ### Resources
 
 - `keel://overview` — the same orientation text as `keel_overview`
@@ -75,6 +104,13 @@ package, so it always matches your installed version.
 4. `keel_scaffold { kind: "controller", name: "Post", resource: true }` → get the stub.
 5. Write the file, add the route, run `npm run typecheck`.
 
+### A typical Keel Cloud loop
+
+1. `keel_cloud_create_site { name: "Acme", preset: "app" }`
+2. Edit the returned `storage_path` (real Keel app + git)
+3. `keel_cloud_preview { site_id }`
+4. `keel_cloud_publish { site_id, confirm: true }` after the user approves
+
 ## `llms.txt` and `llms-full.txt`
 
 At the package root:

package/docs/billing.md

@@ -157,6 +157,15 @@ const intent = await user.createSetupIntent();  // return intent.clientSecret to
 const methods = await user.paymentMethods();
 ```
 
+### Customer portal (Stripe)
+
+Send the customer to Stripe's hosted portal to update their card or cancel:
+
+```ts
+const portal = await user.billingPortal("https://app.example.com/billing");
+// redirect to portal.url
+```
+
 These are Stripe-only capabilities; calling them on the Paddle gateway throws a
 `BillingError` (Paddle collects cards in its own hosted checkout).
 
@@ -251,7 +260,7 @@ real gateway from `config/billing.ts` and `.env`.
 |---------|--------|--------|
 | Create a subscription server-side | `create(pmId)` | Not supported — use `checkout()`; the webhook creates the local row |
 | One-off `charge()` | Confirms a PaymentIntent | Not supported — use `checkout({ mode })` / transactions |
-| SetupIntent / `paymentMethods()` | Supported | Throws `BillingError` (hosted checkout) |
+| SetupIntent / `paymentMethods()` / `billingPortal()` | Supported | Throws `BillingError` (hosted checkout) |
 | Checkout handle | `session.url` (redirect) | `session.clientToken` (overlay/inline) |
 | Webhook signature | `Stripe-Signature: t=…,v1=…` | `Paddle-Signature: ts=…;h1=…` |
 

package/docs/changelog.md

@@ -4,6 +4,23 @@ All notable changes to Keel are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
 adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.83.4] — 2026-07-13
+
+### Added
+
+- **MCP Cloud tools** (`keel_cloud_*`) — when `KEEL_CLOUD_TOKEN` is set,
+  `keel-mcp` registers create/list/preview/publish/secrets/export tools against
+  a Keel Cloud control plane. Documented in [Building with AI](./docs/ai.md).
+- **`tokensMigration()`** — personal access tokens schema helper for apps that
+  need the table via `keel migrate`.
+- **Billing customer portal** — `user.billingPortal(returnUrl)` (Stripe + Fake
+  gateway); opens the hosted portal to manage card / cancel.
+- **Hosting guide** — [`docs/hosting.md`](./docs/hosting.md) + example harness
+  for `@shaferllc/keel/hosting`.
+- **Tests** for gates, hosting, billing portal, and `tokensMigration`.
+
+[0.83.4]: https://github.com/shaferllc/keel/releases/tag/v0.83.4
+
 ## [0.83.3] — 2026-07-12
 
 ### Added

package/docs/examples/hosting.ts

@@ -0,0 +1,37 @@
+// Type-check harness for docs/hosting.md. Compile-only — never executed.
+import type { Connection } from "@shaferllc/keel/core";
+import {
+  CloudflareClient,
+  cloudflareConfigured,
+  normalizeHostname,
+  isValidHostname,
+  zoneCandidates,
+  dumpConnection,
+  normalizeSecretKey,
+  encryptSecretValue,
+  decryptSecretValue,
+  resolveSecretRows,
+} from "@shaferllc/keel/hosting";
+
+export function client() {
+  const creds = { accountId: "acct", apiToken: "tok" };
+  if (!cloudflareConfigured(creds)) throw new Error("missing");
+  return new CloudflareClient(creds);
+}
+
+export function hostnames(raw: string) {
+  const host = normalizeHostname(raw);
+  return { host, valid: isValidHostname(host), zones: zoneCandidates(host) };
+}
+
+export async function dump(conn: Connection) {
+  return dumpConnection(conn, "Acme local D1", { generatedBy: "Keel Cloud" });
+}
+
+export async function vault(secret: string) {
+  const key = normalizeSecretKey("stripe-secret-key");
+  const encrypted = await encryptSecretValue(secret, "app-secret");
+  const plain = await decryptSecretValue(encrypted, "app-secret");
+  const env = await resolveSecretRows([{ key, value_encrypted: encrypted }], "app-secret");
+  return { key, plain, env };
+}

package/docs/hosting.md

@@ -0,0 +1,97 @@
+# Hosting
+
+Keel Hosting is a small toolkit for **hosted Workers / D1 apps**: a Cloudflare
+REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped
+secret encryption. It ships as `@shaferllc/keel/hosting`.
+
+This is infrastructure — not a control plane. Site orchestration, plans, and
+deploy loops live in your app (for example Keel Cloud).
+
+## Install
+
+```ts
+import {
+  CloudflareClient,
+  cloudflareConfigured,
+  normalizeHostname,
+  isValidHostname,
+  zoneCandidates,
+  dumpConnection,
+  normalizeSecretKey,
+  encryptSecretValue,
+  decryptSecretValue,
+  resolveSecretRows,
+} from "@shaferllc/keel/hosting";
+```
+
+No service provider — import what you need.
+
+## Cloudflare
+
+```ts
+const creds = {
+  accountId: process.env.CF_ACCOUNT_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+};
+
+if (!cloudflareConfigured(creds)) {
+  throw new Error("Cloudflare credentials missing");
+}
+
+const cf = new CloudflareClient(creds);
+const db = await cf.createD1Database("kc-acme");
+```
+
+Credentials are constructor args — no app config coupling. Optional
+`pinnedZoneId` / `pinnedZoneName` skip a zone lookup when you already know the
+primary zone.
+
+## Hostnames
+
+```ts
+const host = normalizeHostname("https://App.Example.com/"); // "app.example.com"
+isValidHostname(host); // true
+zoneCandidates(host);  // ["app.example.com", "example.com"]
+```
+
+`zoneCandidates` walks from most-specific to apex — useful when attaching a
+Workers Custom Domain and you need to find which zone owns the name.
+
+## SQL dump
+
+Dump any SQLite-compatible `Connection` to a portable `.sql` script (schema +
+data). Useful for export / escape hatches:
+
+```ts
+import { db } from "@shaferllc/keel/core";
+import { dumpConnection } from "@shaferllc/keel/hosting";
+
+const sql = await dumpConnection(db(), "Acme local D1", { generatedBy: "Keel Cloud" });
+// write sql to a .sql file; restore with sqlite3 / D1 import
+```
+
+## Secrets
+
+Encrypt vault values with Keel's purpose-scoped encryption (`config('app.key')`
+must be set). Keys are normalized to `ENV_STYLE` identifiers:
+
+```ts
+const key = normalizeSecretKey("stripe-secret-key"); // "STRIPE_SECRET_KEY"
+const encrypted = await encryptSecretValue(secret, "app-secret");
+const plain = await decryptSecretValue(encrypted, "app-secret");
+
+const env = await resolveSecretRows(
+  [{ key: "STRIPE_SECRET_KEY", value_encrypted: encrypted }],
+  "app-secret",
+);
+// { STRIPE_SECRET_KEY: "…" }
+```
+
+Your app owns the table of rows (`owner_id`, `key`, `value_encrypted`); hosting
+only encrypts and decrypts.
+
+## Related
+
+- [Gates](./gates.md) — private-alpha signup gating used by hosted control planes
+- [Starter kits](./starter-kits.md) — presets Cloud scaffolds from
+- [Building with AI](./ai.md) — MCP Cloud tools (`keel_cloud_*`) that drive hosting

package/llms-full.txt

@@ -4725,6 +4725,35 @@ package, so it always matches your installed version.
 | `keel_list_generators` | The `keel make:*` generators, what they produce, and their flags. |
 | `keel_scaffold` | Generate a controller/provider/middleware/factory/seeder/job/notification/transformer stub. Returns code + target path — it does **not** write to disk. |
 
+When `KEEL_CLOUD_TOKEN` (and optional `KEEL_CLOUD_URL`) is set, Cloud tools are
+also registered:
+
+| Tool | What it does |
+|------|--------------|
+| `keel_cloud_me` | Authenticated Cloud user |
+| `keel_cloud_list_sites` / `keel_cloud_get_site` | List or fetch a site (includes `storage_path`) |
+| `keel_cloud_create_site` | Create from preset (`minimal` \| `api` \| `app` \| `saas`) |
+| `keel_cloud_preview` | Deploy preview Worker |
+| `keel_cloud_publish` | Publish production — requires `confirm: true` |
+| `keel_cloud_set_secret` | Vault a secret (injected on next deploy) |
+| `keel_cloud_deploys` / `keel_cloud_export` | Deploy history and export manifest |
+| `keel_cloud_export_sql` | Portable `.sql` dump (`local` \| `preview` \| `production`) |
+
+```json
+{
+  "mcpServers": {
+    "keel": {
+      "command": "npx",
+      "args": ["-y", "keel-mcp"],
+      "env": {
+        "KEEL_CLOUD_TOKEN": "kc_…",
+        "KEEL_CLOUD_URL": "https://app.keeljs.cloud"
+      }
+    }
+  }
+}
+```
+
 ### Resources
 
 - `keel://overview` — the same orientation text as `keel_overview`
@@ -4739,6 +4768,13 @@ package, so it always matches your installed version.
 4. `keel_scaffold { kind: "controller", name: "Post", resource: true }` → get the stub.
 5. Write the file, add the route, run `npm run typecheck`.
 
+### A typical Keel Cloud loop
+
+1. `keel_cloud_create_site { name: "Acme", preset: "app" }`
+2. Edit the returned `storage_path` (real Keel app + git)
+3. `keel_cloud_preview { site_id }`
+4. `keel_cloud_publish { site_id, confirm: true }` after the user approves
+
 ## `llms.txt` and `llms-full.txt`
 
 At the package root:
@@ -5716,6 +5752,15 @@ const intent = await user.createSetupIntent();  // return intent.clientSecret to
 const methods = await user.paymentMethods();
 ```
 
+### Customer portal (Stripe)
+
+Send the customer to Stripe's hosted portal to update their card or cancel:
+
+```ts
+const portal = await user.billingPortal("https://app.example.com/billing");
+// redirect to portal.url
+```
+
 These are Stripe-only capabilities; calling them on the Paddle gateway throws a
 `BillingError` (Paddle collects cards in its own hosted checkout).
 
@@ -5810,7 +5855,7 @@ real gateway from `config/billing.ts` and `.env`.
 |---------|--------|--------|
 | Create a subscription server-side | `create(pmId)` | Not supported — use `checkout()`; the webhook creates the local row |
 | One-off `charge()` | Confirms a PaymentIntent | Not supported — use `checkout({ mode })` / transactions |
-| SetupIntent / `paymentMethods()` | Supported | Throws `BillingError` (hosted checkout) |
+| SetupIntent / `paymentMethods()` / `billingPortal()` | Supported | Throws `BillingError` (hosted checkout) |
 | Checkout handle | `session.url` (redirect) | `session.clientToken` (overlay/inline) |
 | Webhook signature | `Stripe-Signature: t=…,v1=…` | `Paddle-Signature: ts=…;h1=…` |
 
@@ -10679,6 +10724,110 @@ The signature of `onReady` / `onShutdown` hooks.
 
 
 
+---
+
+<!-- source: docs/hosting.md -->
+
+# Hosting
+
+Keel Hosting is a small toolkit for **hosted Workers / D1 apps**: a Cloudflare
+REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped
+secret encryption. It ships as `@shaferllc/keel/hosting`.
+
+This is infrastructure — not a control plane. Site orchestration, plans, and
+deploy loops live in your app (for example Keel Cloud).
+
+## Install
+
+```ts
+import {
+  CloudflareClient,
+  cloudflareConfigured,
+  normalizeHostname,
+  isValidHostname,
+  zoneCandidates,
+  dumpConnection,
+  normalizeSecretKey,
+  encryptSecretValue,
+  decryptSecretValue,
+  resolveSecretRows,
+} from "@shaferllc/keel/hosting";
+```
+
+No service provider — import what you need.
+
+## Cloudflare
+
+```ts
+const creds = {
+  accountId: process.env.CF_ACCOUNT_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+};
+
+if (!cloudflareConfigured(creds)) {
+  throw new Error("Cloudflare credentials missing");
+}
+
+const cf = new CloudflareClient(creds);
+const db = await cf.createD1Database("kc-acme");
+```
+
+Credentials are constructor args — no app config coupling. Optional
+`pinnedZoneId` / `pinnedZoneName` skip a zone lookup when you already know the
+primary zone.
+
+## Hostnames
+
+```ts
+const host = normalizeHostname("https://App.Example.com/"); // "app.example.com"
+isValidHostname(host); // true
+zoneCandidates(host);  // ["app.example.com", "example.com"]
+```
+
+`zoneCandidates` walks from most-specific to apex — useful when attaching a
+Workers Custom Domain and you need to find which zone owns the name.
+
+## SQL dump
+
+Dump any SQLite-compatible `Connection` to a portable `.sql` script (schema +
+data). Useful for export / escape hatches:
+
+```ts
+import { db } from "@shaferllc/keel/core";
+import { dumpConnection } from "@shaferllc/keel/hosting";
+
+const sql = await dumpConnection(db(), "Acme local D1", { generatedBy: "Keel Cloud" });
+// write sql to a .sql file; restore with sqlite3 / D1 import
+```
+
+## Secrets
+
+Encrypt vault values with Keel's purpose-scoped encryption (`config('app.key')`
+must be set). Keys are normalized to `ENV_STYLE` identifiers:
+
+```ts
+const key = normalizeSecretKey("stripe-secret-key"); // "STRIPE_SECRET_KEY"
+const encrypted = await encryptSecretValue(secret, "app-secret");
+const plain = await decryptSecretValue(encrypted, "app-secret");
+
+const env = await resolveSecretRows(
+  [{ key: "STRIPE_SECRET_KEY", value_encrypted: encrypted }],
+  "app-secret",
+);
+// { STRIPE_SECRET_KEY: "…" }
+```
+
+Your app owns the table of rows (`owner_id`, `key`, `value_encrypted`); hosting
+only encrypts and decrypts.
+
+## Related
+
+- [Gates](./gates.md) — private-alpha signup gating used by hosted control planes
+- [Starter kits](./starter-kits.md) — presets Cloud scaffolds from
+- [Building with AI](./ai.md) — MCP Cloud tools (`keel_cloud_*`) that drive hosting
+
+
+
 ---
 
 <!-- source: docs/i18n.md -->

package/llms.txt

@@ -37,6 +37,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Helpers](https://github.com/shaferllc/keel/blob/main/docs/helpers.md): Keel gives you a handful of global helper functions so you can reach the running application from anywhere — a route handler, a model, a plain function — without threading a container reference through every call.
 - [Built on Hono](https://github.com/shaferllc/keel/blob/main/docs/hono.md): Keel's HTTP layer is Hono — an ultrafast, web-standard router that runs on Node, Cloudflare Workers, Deno, Bun, and more.
 - [Lifecycle Hooks](https://github.com/shaferllc/keel/blob/main/docs/hooks.md): Tap into the application lifecycle — run code once the app is ready, clean up on shutdown, and observe route registration.
+- [Hosting](https://github.com/shaferllc/keel/blob/main/docs/hosting.md): Keel Hosting is a small toolkit for hosted Workers / D1 apps: a Cloudflare REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped secret encryption.
 - [Internationalization](https://github.com/shaferllc/keel/blob/main/docs/i18n.md): Translations with ICU message formatting, plus the Intl formatters that go with them.
 - [Inertia](https://github.com/shaferllc/keel/blob/main/docs/inertia.md): Keel ships a server-side Inertia.js adapter.
 - [Locks](https://github.com/shaferllc/keel/blob/main/docs/locks.md): "Only one of you may do this at a time" — across processes, across nodes.
@@ -104,6 +105,7 @@ Every topic has a runnable, type-checked example:
 - [Helpers example](https://github.com/shaferllc/keel/blob/main/docs/examples/helpers.ts)
 - [Built on Hono example](https://github.com/shaferllc/keel/blob/main/docs/examples/hono.ts)
 - [Lifecycle Hooks example](https://github.com/shaferllc/keel/blob/main/docs/examples/hooks.ts)
+- [Hosting example](https://github.com/shaferllc/keel/blob/main/docs/examples/hosting.ts)
 - [Internationalization example](https://github.com/shaferllc/keel/blob/main/docs/examples/i18n.ts)
 - [Inertia example](https://github.com/shaferllc/keel/blob/main/docs/examples/inertia.ts)
 - [Locks example](https://github.com/shaferllc/keel/blob/main/docs/examples/locks.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.3",
+  "version": "0.83.4",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",