@shaferllc/keel 0.66.0 → 0.74.0

package/dist/mcp/server.js

@@ -0,0 +1,355 @@
+/**
+ * The Keel MCP server. Exposes Keel's documentation, public API surface, and
+ * code generators to AI agents (Claude Code, Cursor, …) over stdio, so an agent
+ * editing a Keel app can look things up and scaffold code without guessing.
+ *
+ * Run it with `keel mcp` (dev) or the shipped `keel-mcp` bin (consumers).
+ * Tools:
+ *   keel_overview          framework facts, conventions, folder layout
+ *   keel_search_docs       full-text search across the guides
+ *   keel_read_doc          a full guide (optionally with its runnable example)
+ *   keel_search_api        search the public export surface
+ *   keel_list_generators   the `keel make:*` generators
+ *   keel_scaffold          generate a controller/provider/job/… stub (no write)
+ * Resources: keel://overview, keel://llms-full, and keel://docs/<slug> per guide.
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+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";
+async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Walk up from this module until we find the package root (the dir holding docs/). */
+async function findRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        if (await exists(join(dir, "docs")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fall back to two levels up (…/mcp/server.js -> package root).
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+/** Load the generated manifest, or reconstruct a minimal one by scanning docs/. */
+async function loadManifest(root) {
+    const manifestPath = join(root, "docs", "ai-manifest.json");
+    if (await exists(manifestPath)) {
+        return JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    // Fallback: scan docs so the server still works before `npm run build:ai`.
+    const docsDir = join(root, "docs");
+    const files = (await readdir(docsDir)).filter((f) => f.endsWith(".md")).sort();
+    const docs = [];
+    for (const file of files) {
+        const md = await readFile(join(docsDir, file), "utf8");
+        const title = md.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? file;
+        docs.push({ slug: file.replace(/\.md$/, ""), title, summary: "", path: `docs/${file}`, example: null });
+    }
+    let pkg = { name: "@shaferllc/keel", version: "0.0.0", description: "The house framework for Node.js." };
+    try {
+        pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    }
+    catch {
+        /* use defaults */
+    }
+    return {
+        name: pkg.name,
+        version: pkg.version,
+        description: pkg.description,
+        repo: "https://github.com/shaferllc/keel",
+        docs,
+        api: [],
+        generators: [],
+    };
+}
+// ---- generators ------------------------------------------------------------
+/** Normalize "foo" / "FooController" into a canonical suffixed class name. */
+function className(name, suffix) {
+    const base = name.replace(new RegExp(`${suffix}$`, "i"), "");
+    const pascal = base.charAt(0).toUpperCase() + base.slice(1);
+    return `${pascal}${suffix}`;
+}
+const GENERATOR_KINDS = [
+    "controller",
+    "provider",
+    "middleware",
+    "factory",
+    "seeder",
+    "job",
+    "notification",
+    "transformer",
+];
+/** Build a stub for a `make:*` kind. Pure — returns the code and target path, never writes. */
+function scaffold(kind, name, opts) {
+    switch (kind) {
+        case "controller": {
+            const cls = className(name, "Controller");
+            return {
+                path: `app/Controllers/${cls}.ts`,
+                code: opts.resource ? resourceControllerStub(cls) : controllerStub(cls),
+            };
+        }
+        case "provider": {
+            const cls = className(name, "ServiceProvider");
+            return { path: `app/Providers/${cls}.ts`, code: providerStub(cls) };
+        }
+        case "middleware": {
+            const cls = className(name, "Middleware");
+            const file = cls.charAt(0).toLowerCase() + cls.slice(1);
+            return { path: `app/Http/Middleware/${file}.ts`, code: middlewareStub(cls) };
+        }
+        case "factory": {
+            const cls = className(name, "");
+            return { path: `database/factories/${cls}Factory.ts`, code: factoryStub(cls) };
+        }
+        case "seeder": {
+            const cls = className(name, "Seeder");
+            return { path: `database/seeders/${cls}.ts`, code: seederStub(cls) };
+        }
+        case "job": {
+            const cls = className(name, "Job");
+            return { path: `app/Jobs/${cls}.ts`, code: jobStub(cls) };
+        }
+        case "notification": {
+            const cls = className(name, "Notification");
+            return { path: `app/Notifications/${cls}.ts`, code: notificationStub(cls) };
+        }
+        case "transformer": {
+            const cls = className(name, "Transformer");
+            const model = opts.model ? className(opts.model, "") : cls.replace(/Transformer$/, "");
+            return { path: `app/Transformers/${cls}.ts`, code: transformerStub(cls, model) };
+        }
+    }
+}
+// ---- search ----------------------------------------------------------------
+function snippet(body, query) {
+    const idx = body.toLowerCase().indexOf(query.toLowerCase());
+    if (idx === -1)
+        return body.slice(0, 200).replace(/\s+/g, " ").trim();
+    const start = Math.max(0, idx - 80);
+    const end = Math.min(body.length, idx + query.length + 120);
+    return (start > 0 ? "…" : "") + body.slice(start, end).replace(/\s+/g, " ").trim() + (end < body.length ? "…" : "");
+}
+// ---- server ----------------------------------------------------------------
+export async function createServer() {
+    const root = await findRoot();
+    const manifest = await loadManifest(root);
+    const docBySlug = new Map(manifest.docs.map((d) => [d.slug, d]));
+    // Which doc guide, if any, documents a given source module (e.g. "queue" -> "queues").
+    const moduleToDoc = (module) => {
+        for (const cand of [module, `${module}s`, module.replace(/s$/, "")]) {
+            if (docBySlug.has(cand))
+                return cand;
+        }
+        return undefined;
+    };
+    const server = new McpServer({ name: "keel", version: manifest.version });
+    const overviewText = () => [
+        `# ${manifest.name} v${manifest.version}`,
+        "",
+        manifest.description,
+        "",
+        "Keel is a small, legible MVC framework for Node.js. Hono powers HTTP; everything",
+        "above it is Keel's. Userland imports everything from `@shaferllc/keel/core`.",
+        "",
+        "## Conventions",
+        "- Import surface: `import { Router, Model, config } from \"@shaferllc/keel/core\";`",
+        "- Everything resolves through the service container (`bind`/`singleton`/`make`).",
+        "- Service providers (`register()` then `boot()`) wire the app together.",
+        "- Config is dot-notation: `config(\"app.name\")`, sourced from `config/*.ts` + `.env`.",
+        "",
+        "## Folder layout (a Keel app)",
+        "- `app/Controllers`, `app/Providers`, `app/Http/Middleware`, `app/Models`, `app/Jobs`, …",
+        "- `config/*.ts` — configuration files",
+        "- `routes/web.ts` — route definitions (default export receives the Router)",
+        "- `database/factories`, `database/seeders`, `database/migrations`",
+        "- `bootstrap/app.ts` — assembles the Application and its providers",
+        "",
+        `## Guides (${manifest.docs.length}) — read with keel_read_doc`,
+        ...manifest.docs.map((d) => `- ${d.slug}: ${d.summary || d.title}`),
+        "",
+        "## Generators — use keel_scaffold or `keel make:*`",
+        ...manifest.generators.map((g) => `- ${g.command} → ${g.produces}`),
+    ].join("\n");
+    // ---- tools ----
+    server.registerTool("keel_overview", {
+        title: "Keel overview",
+        description: "Start here. Returns Keel's version, conventions, folder layout, the full list of doc topics, and the available code generators. Call this first when working in a Keel app.",
+        inputSchema: {},
+    }, async () => ({ content: [{ type: "text", text: overviewText() }] }));
+    server.registerTool("keel_search_docs", {
+        title: "Search Keel docs",
+        description: "Full-text search across all Keel guides. Returns the best-matching guides with a snippet and slug; follow up with keel_read_doc to read one in full.",
+        inputSchema: {
+            query: z.string().describe("What to look for, e.g. 'rate limit middleware' or 'belongsToMany'"),
+            limit: z.number().int().min(1).max(20).optional().describe("Max results (default 6)"),
+        },
+    }, async ({ query, limit }) => {
+        const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+        const first = terms[0] ?? query.toLowerCase();
+        const scored = [];
+        for (const doc of manifest.docs) {
+            const body = await readFile(join(root, doc.path), "utf8");
+            const hay = body.toLowerCase();
+            const title = doc.title.toLowerCase();
+            let score = 0;
+            for (const t of terms) {
+                if (title.includes(t))
+                    score += 10;
+                if (doc.slug.includes(t))
+                    score += 8;
+                const matches = hay.split(t).length - 1;
+                score += Math.min(matches, 8);
+            }
+            if (score > 0)
+                scored.push({ doc, score, body });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const top = scored.slice(0, limit ?? 6);
+        if (top.length === 0) {
+            return { content: [{ type: "text", text: `No Keel docs matched "${query}".` }] };
+        }
+        const text = top
+            .map(({ doc, body }) => `## ${doc.title}  (slug: ${doc.slug})\n${snippet(body, first)}\n→ keel_read_doc { slug: "${doc.slug}" }`)
+            .join("\n\n");
+        return { content: [{ type: "text", text }] };
+    });
+    server.registerTool("keel_read_doc", {
+        title: "Read a Keel doc",
+        description: "Return a full Keel guide by slug (e.g. 'routing', 'models', 'queues'). Optionally append its runnable, type-checked example. Use keel_search_docs or keel_overview to find slugs.",
+        inputSchema: {
+            slug: z.string().describe("Doc slug, e.g. 'routing' or 'getting-started'"),
+            include_example: z.boolean().optional().describe("Append the guide's example source if it has one (default false)"),
+        },
+    }, async ({ slug, include_example }) => {
+        const doc = docBySlug.get(slug);
+        if (!doc) {
+            const near = manifest.docs
+                .filter((d) => d.slug.includes(slug) || slug.includes(d.slug))
+                .map((d) => d.slug);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No doc "${slug}".${near.length ? ` Did you mean: ${near.join(", ")}?` : ""} Use keel_overview to list all slugs.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        let text = await readFile(join(root, doc.path), "utf8");
+        if (include_example && doc.example && (await exists(join(root, doc.example)))) {
+            const ex = await readFile(join(root, doc.example), "utf8");
+            text += `\n\n---\n\n## Example — ${doc.example}\n\n\`\`\`ts\n${ex}\n\`\`\`\n`;
+        }
+        return { content: [{ type: "text", text }] };
+    });
+    server.registerTool("keel_search_api", {
+        title: "Search Keel's public API",
+        description: "Search the public export surface of `@shaferllc/keel/core` (382+ symbols). Returns matching value/type exports, the source module each lives in, and the guide that documents it.",
+        inputSchema: {
+            query: z.string().describe("A symbol or fragment, e.g. 'Router', 'cache', 'hasMany', 'Exception'"),
+            limit: z.number().int().min(1).max(50).optional().describe("Max results (default 20)"),
+        },
+    }, async ({ query, limit }) => {
+        if (manifest.api.length === 0) {
+            return { content: [{ type: "text", text: "API index unavailable — run `npm run build:ai`." }] };
+        }
+        const q = query.toLowerCase();
+        const hits = manifest.api
+            .map((e) => {
+            const name = e.name.toLowerCase();
+            let score = 0;
+            if (name === q)
+                score = 100;
+            else if (name.startsWith(q))
+                score = 50;
+            else if (name.includes(q))
+                score = 25;
+            else if (e.module.includes(q))
+                score = 5;
+            return { e, score };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => b.score - a.score || a.e.name.localeCompare(b.e.name))
+            .slice(0, limit ?? 20);
+        if (hits.length === 0) {
+            return { content: [{ type: "text", text: `No exports matched "${query}".` }] };
+        }
+        const text = hits
+            .map(({ e }) => {
+            const doc = moduleToDoc(e.module);
+            return `- ${e.kind === "type" ? "type " : ""}${e.name}  (module: ${e.module}${doc ? `, doc: ${doc}` : ""})`;
+        })
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Import from "@shaferllc/keel/core":\n\n${text}\n\nRead a module's guide with keel_read_doc.`,
+                },
+            ],
+        };
+    });
+    server.registerTool("keel_list_generators", {
+        title: "List Keel generators",
+        description: "List the `keel make:*` code generators, what each produces, and their flags. Use keel_scaffold to generate one.",
+        inputSchema: {},
+    }, async () => {
+        const text = manifest.generators
+            .map((g) => `- ${g.command}\n    → ${g.produces}${g.flags.length ? `\n    flags: ${g.flags.join(", ")}` : ""}\n    ${g.note}`)
+            .join("\n\n");
+        return { content: [{ type: "text", text: text || "No generator metadata — run `npm run build:ai`." }] };
+    });
+    server.registerTool("keel_scaffold", {
+        title: "Scaffold Keel code",
+        description: "Generate the stub for a Keel construct (controller, provider, middleware, factory, seeder, job, notification, transformer) and return the code plus its target path. Does NOT write to disk — write the returned code yourself. Mirrors `keel make:*`.",
+        inputSchema: {
+            kind: z.enum(GENERATOR_KINDS).describe("What to generate"),
+            name: z.string().describe("Base name, e.g. 'User', 'SendWelcome' — suffixes are normalized"),
+            resource: z.boolean().optional().describe("controller only: scaffold all seven RESTful actions"),
+            model: z.string().optional().describe("transformer only: the model it maps, e.g. 'User'"),
+        },
+    }, async ({ kind, name, resource, model }) => {
+        const { path, code } = scaffold(kind, name, { resource, model });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Target: ${path}\n\n\`\`\`ts\n${code}\`\`\`\n\nWrite this file, then register/import it where appropriate (see keel_read_doc { slug: "${moduleToDoc(kind) ?? kind}" }).`,
+                },
+            ],
+        };
+    });
+    // ---- resources ----
+    server.registerResource("overview", "keel://overview", { title: "Keel overview", description: "Conventions, layout, topics, generators", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, text: overviewText() }] }));
+    const llmsFull = join(root, "llms-full.txt");
+    if (await exists(llmsFull)) {
+        server.registerResource("llms-full", "keel://llms-full", { title: "All Keel docs", description: "Every guide concatenated", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, text: await readFile(llmsFull, "utf8") }] }));
+    }
+    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") }] }));
+    }
+    return server;
+}
+/** Boot the server on stdio. Called by the `keel-mcp` bin and `keel mcp`. */
+export async function runMcpServer() {
+    const server = await createServer();
+    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");
+}

package/dist/openapi/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OpenAPI configuration. Defaults live here and are merged under
+ * `config("openapi")` by the provider; an app overrides them in
+ * `config/openapi.ts` (publish it with `keel vendor:publish --tag openapi-config`).
+ */
+export interface OpenApiConfig {
+    /** Master switch. Off → no docs routes and the spec 404s. */
+    enabled: boolean;
+    /** URL prefix the docs UI and spec mount under. Default: "docs". */
+    path: string;
+    /** The API title. Defaults to `config("app.name")`. */
+    title: string;
+    /** The API version string shown in the spec. */
+    version: string;
+    /** A longer description (Markdown) for the spec's `info`. */
+    description?: string;
+    /** Server URLs the API is served from (OpenAPI `servers`). */
+    servers: string[];
+    /** Serve the docs in production too. Off by default — docs expose your surface. */
+    public: boolean;
+    /** Swagger UI asset base (a CDN, or your own copy). Pin it to a version you trust. */
+    cdn: string;
+    /** Route path prefixes to leave out of the spec (the docs' own are always skipped). */
+    ignorePaths: string[];
+}
+export declare const defaultConfig: OpenApiConfig;
+/** Read the effective OpenAPI config, filling gaps (title falls back to app name). */
+export declare function resolveConfig(): OpenApiConfig;

package/dist/openapi/config.js

@@ -0,0 +1,25 @@
+/**
+ * OpenAPI configuration. Defaults live here and are merged under
+ * `config("openapi")` by the provider; an app overrides them in
+ * `config/openapi.ts` (publish it with `keel vendor:publish --tag openapi-config`).
+ */
+import { config } from "../core/helpers.js";
+export const defaultConfig = {
+    enabled: true,
+    path: "docs",
+    title: "",
+    version: "1.0.0",
+    servers: [],
+    public: false,
+    cdn: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14",
+    ignorePaths: [],
+};
+/** Read the effective OpenAPI config, filling gaps (title falls back to app name). */
+export function resolveConfig() {
+    const raw = config("openapi", {});
+    return {
+        ...defaultConfig,
+        ...raw,
+        title: raw.title || config("app.name", "API"),
+    };
+}

package/dist/openapi/doc.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Route documentation metadata. Attach it to a route with `.config(apiDoc(...))`
+ * and the generator turns it into a rich OpenAPI operation — request/response
+ * schemas, summary, tags. Request schemas reuse Keel's `RequestSchemas` shape, so
+ * the very object you hand `validateRequest({ body })` also documents the route.
+ *
+ *   router
+ *     .post("/users", [Users, "store"])
+ *     .config(apiDoc({ summary: "Create a user", request: { body: NewUser }, tags: ["users"] }))
+ *     .middleware([validateRequest({ body: NewUser })]);
+ */
+import type { RequestSchemas } from "../core/validation.js";
+/** The key under which docs metadata lives in a route's `config`. */
+export declare const OPENAPI_KEY = "openapi";
+/** One response's documentation: a description and an optional body schema. */
+export interface ResponseDoc {
+    description?: string;
+    /** A Zod schema or a plain JSON Schema object for the response body. */
+    schema?: unknown;
+}
+/** Everything a route can say about itself for the spec. */
+export interface OperationDoc {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    /** Overrides the generated operationId (default: the route name). */
+    operationId?: string;
+    deprecated?: boolean;
+    /** Request body/query/params schemas — Zod or plain JSON Schema. */
+    request?: RequestSchemas;
+    /** Responses keyed by status code, e.g. `{ 200: { schema: User }, 404: {} }`. */
+    responses?: Record<string | number, ResponseDoc>;
+    /** Leave this route out of the spec entirely. */
+    hidden?: boolean;
+}
+/**
+ * Wrap operation docs for a route's `.config()`. Returns `{ openapi: doc }`, which
+ * the generator reads off `RouteDefinition.config`.
+ */
+export declare function apiDoc(doc: OperationDoc): Record<string, unknown>;

package/dist/openapi/doc.js

@@ -0,0 +1,20 @@
+/**
+ * Route documentation metadata. Attach it to a route with `.config(apiDoc(...))`
+ * and the generator turns it into a rich OpenAPI operation — request/response
+ * schemas, summary, tags. Request schemas reuse Keel's `RequestSchemas` shape, so
+ * the very object you hand `validateRequest({ body })` also documents the route.
+ *
+ *   router
+ *     .post("/users", [Users, "store"])
+ *     .config(apiDoc({ summary: "Create a user", request: { body: NewUser }, tags: ["users"] }))
+ *     .middleware([validateRequest({ body: NewUser })]);
+ */
+/** The key under which docs metadata lives in a route's `config`. */
+export const OPENAPI_KEY = "openapi";
+/**
+ * Wrap operation docs for a route's `.config()`. Returns `{ openapi: doc }`, which
+ * the generator reads off `RouteDefinition.config`.
+ */
+export function apiDoc(doc) {
+    return { [OPENAPI_KEY]: doc };
+}

package/dist/openapi/export.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `keel openapi:export [--out openapi.json]` — write the spec to a file, for CI,
+ * client generation, or committing it. Contributed as a package command.
+ */
+import type { PackageCommand } from "../core/package.js";
+import type { Router } from "../core/http/router.js";
+import type { OpenApiConfig } from "./config.js";
+export declare function exportCommand(getRouter: () => Router, config: OpenApiConfig, base: string): PackageCommand;

package/dist/openapi/export.js

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

package/dist/openapi/gate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Who may see the docs. A spec advertises your whole API surface, so it's gated
+ * shut in production by default — open only when `app.debug` is on, outside
+ * production, or when you set `public: true`. Override with `OpenApi.auth()`.
+ */
+import type { Ctx } from "../core/http/router.js";
+import type { OpenApiConfig } from "./config.js";
+export type OpenApiGate = (c: Ctx) => boolean | Promise<boolean>;
+export declare const OpenApi: {
+    /** Restrict docs access. Return true to allow the request. */
+    auth(fn: OpenApiGate): void;
+    /** Remove a custom gate, reverting to the default. */
+    clearAuth(): void;
+};
+export declare function passesGate(c: Ctx, cfg: OpenApiConfig): Promise<boolean>;

package/dist/openapi/gate.js

@@ -0,0 +1,27 @@
+/**
+ * Who may see the docs. A spec advertises your whole API surface, so it's gated
+ * shut in production by default — open only when `app.debug` is on, outside
+ * production, or when you set `public: true`. Override with `OpenApi.auth()`.
+ */
+import { config } from "../core/helpers.js";
+let gate;
+export const OpenApi = {
+    /** Restrict docs access. Return true to allow the request. */
+    auth(fn) {
+        gate = fn;
+    },
+    /** Remove a custom gate, reverting to the default. */
+    clearAuth() {
+        gate = undefined;
+    },
+};
+function defaultGate(cfg) {
+    if (cfg.public)
+        return true;
+    if (config("app.debug", false))
+        return true;
+    return config("app.env", "production") !== "production";
+}
+export async function passesGate(c, cfg) {
+    return gate ? gate(c) : defaultGate(cfg);
+}

package/dist/openapi/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Keel OpenAPI — spec generation + Swagger UI for Keel apps, imported from
+ * `@shaferllc/keel/openapi`.
+ *
+ *   import { OpenApiServiceProvider } from "@shaferllc/keel/openapi";
+ *   app.register(OpenApiServiceProvider);      // serves /docs and /docs/openapi.json
+ *
+ * Document a route with `apiDoc()`; lock the docs down with `OpenApi.auth()`.
+ */
+export { OpenApiServiceProvider } from "./provider.js";
+export { OpenApi } from "./gate.js";
+export type { OpenApiGate } from "./gate.js";
+export { apiDoc, OPENAPI_KEY } from "./doc.js";
+export type { OperationDoc, ResponseDoc } from "./doc.js";
+export { buildSpec } from "./spec.js";
+export type { OpenApiDocument } from "./spec.js";
+export { toJsonSchema } from "./zod.js";
+export { resolveConfig, defaultConfig } from "./config.js";
+export type { OpenApiConfig } from "./config.js";

package/dist/openapi/index.js

@@ -0,0 +1,15 @@
+/**
+ * Keel OpenAPI — spec generation + Swagger UI for Keel apps, imported from
+ * `@shaferllc/keel/openapi`.
+ *
+ *   import { OpenApiServiceProvider } from "@shaferllc/keel/openapi";
+ *   app.register(OpenApiServiceProvider);      // serves /docs and /docs/openapi.json
+ *
+ * Document a route with `apiDoc()`; lock the docs down with `OpenApi.auth()`.
+ */
+export { OpenApiServiceProvider } from "./provider.js";
+export { OpenApi } from "./gate.js";
+export { apiDoc, OPENAPI_KEY } from "./doc.js";
+export { buildSpec } from "./spec.js";
+export { toJsonSchema } from "./zod.js";
+export { resolveConfig, defaultConfig } from "./config.js";

package/dist/openapi/openapi.config.stub

@@ -0,0 +1,29 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Keel OpenAPI — spec + Swagger UI configuration.
+ * Published with `keel vendor:publish --tag openapi-config`.
+ */
+export default {
+  enabled: env("OPENAPI_ENABLED", true),
+
+  // Docs UI at http://localhost:3000/docs, spec at /docs/openapi.json
+  path: "docs",
+
+  // Shown in the spec's `info`. Title defaults to config("app.name").
+  title: "",
+  version: "1.0.0",
+  description: undefined,
+
+  // Where the API is served (OpenAPI `servers`), e.g. ["https://api.example.com"].
+  servers: [],
+
+  // Serve the docs in production too. Off by default — a spec advertises your API.
+  public: env("OPENAPI_PUBLIC", false),
+
+  // Swagger UI assets. Pin the version, or point at a copy you host.
+  cdn: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14",
+
+  // Route path prefixes to leave out of the spec.
+  ignorePaths: ["/watch"],
+};

package/dist/openapi/provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Keel OpenAPI — generate an OpenAPI 3 spec from your routes and serve Swagger UI,
+ * shipped as a Keel package. One line turns it on:
+ *
+ *   app.register(OpenApiServiceProvider);
+ *
+ * The spec is built from Keel's own route table plus whatever each route attaches
+ * with `.config(apiDoc(...))`. Nothing is scraped or guessed: paths and methods
+ * are always right, and schemas are as rich as the metadata a route provides.
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class OpenApiServiceProvider extends PackageProvider {
+    readonly name = "openapi";
+    private config;
+    private base;
+    register(): void;
+    boot(): void;
+}