blume 0.0.0 → 0.1.0

package/package.json

@@ -1,11 +1,145 @@
 {
   "name": "blume",
-  "version": "0.0.0",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "Documentation that's fast, AI-ready, and zero-config.",
+  "keywords": [
+    "astro",
+    "docs",
+    "documentation",
+    "markdown",
+    "mdx",
+    "vite"
+  ],
+  "homepage": "https://github.com/haydenbleasel/blume#readme",
+  "bugs": {
+    "url": "https://github.com/haydenbleasel/blume/issues"
+  },
+  "license": "MIT",
+  "author": "Hayden Bleasel",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haydenbleasel/blume.git",
+    "directory": "packages/blume"
+  },
+  "bin": {
+    "blume": "./bin/blume.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "docs"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ai/*": "./src/ai/*",
+    "./schema": "./src/core/schema.ts",
+    "./runtime": "./src/runtime/index.ts",
+    "./astro": "./src/astro/index.ts",
+    "./og": "./src/og/index.ts",
+    "./markdown": "./src/markdown/index.ts",
+    "./components": "./src/components/index.ts",
+    "./components/*": "./src/components/*",
+    "./core/*": "./src/core/*",
+    "./sources/*": "./src/core/sources/*",
+    "./theme/*": "./src/theme/*",
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "bun run scripts/build.ts",
+    "bundle-docs": "node scripts/bundle-docs.mjs",
+    "prepack": "bun run scripts/build.ts && node scripts/bundle-docs.mjs",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsgo --noEmit && tsgo -p test/tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@astrojs/markdown-satteri": "^0.3.2",
+    "@astrojs/mdx": "^7.0.0",
+    "@astrojs/node": "^11.0.0",
+    "@astrojs/react": "^6.0.0",
+    "@astrojs/vercel": "^11.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@orama/orama": "^3.1.18",
+    "@scalar/astro": "^0.4.5",
+    "@shikijs/transformers": "^4.2.0",
+    "@shikijs/twoslash": "^4.2.0",
+    "@tailwindcss/typography": "^0.5.20",
+    "@tailwindcss/vite": "^4",
+    "@takumi-rs/core": "^1.8.7",
+    "@takumi-rs/helpers": "^1.8.7",
+    "@vercel/analytics": "^2.0.1",
+    "ai": "^5.0.0",
+    "astro": "^7.0.2",
+    "citty": "^0.1.6",
+    "consola": "^3.4.0",
+    "deepmerge": "^4.3.1",
+    "epub-gen-memory": "^1.1.2",
+    "github-slugger": "^2.0.0",
+    "gray-matter": "^4.0.3",
+    "jiti": "^2.4.0",
+    "katex": "^0.17.0",
+    "mermaid": "^11.15.0",
+    "pagefind": "^1.3.0",
+    "pathe": "^2.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "shiki": "^4.2.0",
+    "simple-icons": "^13.0.0",
+    "tailwindcss": "^4",
+    "tinyglobby": "^0.2.10",
+    "typescript": "^5.7.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260626.1",
+    "bun-types": "^1.3.14"
+  },
+  "peerDependencies": {
+    "@ai-sdk/openai-compatible": "^1.0.41",
+    "@mixedbread/sdk": "^0.76.0",
+    "@notionhq/client": "^2.2.15",
+    "@openrouter/ai-sdk-provider": "^1.5.4",
+    "@oramacloud/client": "^2.1.0",
+    "@sanity/client": "^6.21.0",
+    "algoliasearch": "^5.55.0",
+    "flexsearch": "^0.8.0",
+    "typesense": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/openai-compatible": {
+      "optional": true
+    },
+    "@mixedbread/sdk": {
+      "optional": true
+    },
+    "@openrouter/ai-sdk-provider": {
+      "optional": true
+    },
+    "@notionhq/client": {
+      "optional": true
+    },
+    "@oramacloud/client": {
+      "optional": true
+    },
+    "@sanity/client": {
+      "optional": true
+    },
+    "algoliasearch": {
+      "optional": true
+    },
+    "flexsearch": {
+      "optional": true
+    },
+    "typesense": {
+      "optional": true
+    }
   },
-  "author": "",
-  "license": "ISC",
-  "description": ""
+  "engines": {
+    "node": ">=22.12.0"
+  }
 }

package/src/ai/ask.ts

@@ -0,0 +1,93 @@
+import type { AskAiConfig } from "../core/schema.ts";
+
+/**
+ * The concrete backend the Ask AI endpoint is generated against. `gateway` uses
+ * the AI SDK core (`streamText({ model })`) and the Vercel AI Gateway;
+ * `openrouter` uses its dedicated provider; everything else streams through the
+ * AI SDK's OpenAI-compatible provider.
+ */
+export type AskBackend =
+  | { kind: "gateway"; model: string }
+  | { apiKeyEnv: string; kind: "openrouter"; model: string }
+  | {
+      apiKeyEnv: string;
+      baseUrl: string;
+      kind: "openai-compatible";
+      model: string;
+      name: string;
+    };
+
+interface AskPreset {
+  apiKeyEnv: string;
+  baseUrl?: string;
+  kind: "openai-compatible" | "openrouter";
+  name: string;
+  runtimeDep: string;
+}
+
+/**
+ * Connection presets for the named, non-gateway providers. OpenRouter has a
+ * dedicated AI SDK provider; LLMGateway and Inkeep are OpenAI-compatible
+ * endpoints with no dedicated provider, so they reuse `@ai-sdk/openai-compatible`.
+ */
+const ASK_PRESETS: Record<string, AskPreset> = {
+  inkeep: {
+    apiKeyEnv: "INKEEP_API_KEY",
+    baseUrl: "https://api.inkeep.com/v1",
+    kind: "openai-compatible",
+    name: "inkeep",
+    runtimeDep: "@ai-sdk/openai-compatible",
+  },
+  llmgateway: {
+    apiKeyEnv: "LLMGATEWAY_API_KEY",
+    baseUrl: "https://api.llmgateway.io/v1",
+    kind: "openai-compatible",
+    name: "llmgateway",
+    runtimeDep: "@ai-sdk/openai-compatible",
+  },
+  openrouter: {
+    apiKeyEnv: "OPENROUTER_API_KEY",
+    kind: "openrouter",
+    name: "openrouter",
+    runtimeDep: "@openrouter/ai-sdk-provider",
+  },
+};
+
+const DEFAULT_MODEL = "openai/gpt-5.5";
+
+/** Resolve the `ai.ask` config into the backend the endpoint is built against. */
+export const resolveAskBackend = (ask?: AskAiConfig): AskBackend => {
+  const provider = ask?.provider ?? "gateway";
+  const model = ask?.model ?? DEFAULT_MODEL;
+  if (provider === "gateway") {
+    return { kind: "gateway", model };
+  }
+  const preset = ASK_PRESETS[provider];
+  const apiKeyEnv = ask?.apiKeyEnv ?? preset?.apiKeyEnv ?? "API_KEY";
+  if (provider === "openrouter") {
+    return { apiKeyEnv, kind: "openrouter", model };
+  }
+  // `llmgateway`, `inkeep`, and the generic `openai-compatible` provider all
+  // stream through the AI SDK's OpenAI-compatible provider. The schema requires
+  // `baseUrl` for the generic case; the named providers fall back to a preset.
+  return {
+    apiKeyEnv,
+    baseUrl: ask?.baseUrl ?? preset?.baseUrl ?? "",
+    kind: "openai-compatible",
+    model,
+    name: preset?.name ?? "openai-compatible",
+  };
+};
+
+/**
+ * The provider SDK a project must install for the configured backend, or
+ * `undefined` for `gateway` (which only needs the core `ai` package). Declared
+ * in the generated runtime so a project pulls in exactly the backend it uses.
+ */
+export const askBackendRuntimeDep = (ask?: AskAiConfig): string | undefined => {
+  const provider = ask?.provider ?? "gateway";
+  if (provider === "gateway") {
+    return undefined;
+  }
+  return ASK_PRESETS[provider]?.runtimeDep ?? "@ai-sdk/openai-compatible";
+};

package/src/ai/llms.ts

@@ -0,0 +1,65 @@
+import matter from "gray-matter";
+
+import type { BlumeProject } from "../core/project-graph.ts";
+import { readEntryText } from "../core/sources/read.ts";
+import type { PageRecord } from "../core/types.ts";
+
+const pageUrl = (route: string, site?: string): string => {
+  if (!site) {
+    return route;
+  }
+  return `${site.replace(/\/$/u, "")}${route}`;
+};
+
+const orderedPages = (project: BlumeProject): PageRecord[] =>
+  [...project.graph.pages]
+    .filter((page) => !page.meta.draft)
+    .sort((a, b) => a.route.localeCompare(b.route));
+
+/** Build the compact `llms.txt` index: title, summary, and links per page. */
+const buildIndex = (project: BlumeProject): string => {
+  const { config } = project;
+  const { site } = config.deployment;
+  const lines = [`# ${config.title}`];
+  if (config.description) {
+    lines.push("", `> ${config.description}`);
+  }
+  lines.push("", "## Docs", "");
+
+  for (const page of orderedPages(project)) {
+    const url = pageUrl(page.route, site);
+    const summary = page.description ? `: ${page.description}` : "";
+    lines.push(`- [${page.title}](${url})${summary}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+};
+
+/** Build `llms-full.txt`: the full Markdown body of every page. */
+const buildFull = async (project: BlumeProject): Promise<string> => {
+  const { config } = project;
+  const pages = orderedPages(project);
+
+  const sections = await Promise.all(
+    pages.map(async (page) => {
+      const raw = await readEntryText(project, page);
+      const body = matter(raw).content.trim();
+      const url = pageUrl(page.route, config.deployment.site);
+      return [`# ${page.title}`, `Source: ${url}`, "", body].join("\n");
+    })
+  );
+
+  const header = config.description
+    ? `# ${config.title}\n\n> ${config.description}\n`
+    : `# ${config.title}\n`;
+
+  return `${header}\n${sections.join("\n\n---\n\n")}\n`;
+};
+
+/** Build both LLM text artifacts for a project. */
+export const buildLlmsFiles = async (
+  project: BlumeProject
+): Promise<{ index: string; full: string }> => ({
+  full: await buildFull(project),
+  index: buildIndex(project),
+});

package/src/ai/markdown.ts

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+
+import type { BlumeProject } from "../core/project-graph.ts";
+import { readEntryText } from "../core/sources/read.ts";
+import type { RouteManifestEntry } from "../core/types.ts";
+
+/**
+ * Map every route to its raw source Markdown. Powers the `<route>.md` and
+ * `<route>.mdx` endpoints, which serve the original source so AI tools — and
+ * readers — can fetch any page as plain Markdown.
+ */
+export const buildRawMarkdown = async (
+  project: BlumeProject
+): Promise<Record<string, string>> => {
+  const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
+
+  const readRoute = async (route: RouteManifestEntry): Promise<string> => {
+    const page = pageById.get(route.id);
+    if (page) {
+      return await readEntryText(project, page);
+    }
+    return route.sourcePath ? await readFile(route.sourcePath, "utf-8") : "";
+  };
+
+  const entries = await Promise.all(
+    project.manifest.routes.map(
+      async (route) => [route.path, await readRoute(route)] as const
+    )
+  );
+  return Object.fromEntries(entries);
+};

package/src/ai/mcp/data.ts

@@ -0,0 +1,74 @@
+import type { BlumeProject } from "../../core/project-graph.ts";
+import type { Navigation } from "../../core/types.ts";
+import { buildSearchDocuments } from "../../search/documents.ts";
+import type { OramaDoc } from "../../search/orama-index.ts";
+import { buildRawMarkdown } from "../markdown.ts";
+
+/** A page entry surfaced by the `list_pages` MCP tool. */
+export interface McpRoute {
+  contentType: string;
+  description?: string;
+  indexable: boolean;
+  lastModified: string | null;
+  route: string;
+  title: string;
+}
+
+/**
+ * The self-contained snapshot the generated MCP endpoint serves. Bundles the
+ * search documents, raw page Markdown, route list, and navigation so the server
+ * works regardless of the configured search provider and needs no filesystem
+ * access at request time. Serialized to `generated/mcp-data.json`.
+ */
+export interface McpData {
+  documents: OramaDoc[];
+  instructions?: string;
+  name: string;
+  navigation: Navigation;
+  pages: Record<string, string>;
+  routes: McpRoute[];
+  site: string | null;
+  version: string;
+}
+
+/** Build the MCP data snapshot from a resolved project. */
+export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
+  const { config, graph, manifest } = project;
+  const [documents, pages] = await Promise.all([
+    // The MCP server is independent of on-page search, so index docs even when
+    // the search provider is `none`.
+    buildSearchDocuments(project, { includeWhenDisabled: true }),
+    buildRawMarkdown(project),
+  ]);
+
+  const descriptionById = new Map(
+    graph.pages.map((page) => [page.id, page.description])
+  );
+
+  const routes: McpRoute[] = manifest.routes
+    .filter((route) => !route.hidden)
+    .map((route) => ({
+      contentType: route.contentType,
+      description: descriptionById.get(route.id),
+      indexable: route.indexable,
+      lastModified: route.lastModified ?? null,
+      route: route.path,
+      title: route.title,
+    }));
+
+  return {
+    documents: documents.map((doc) => ({
+      content: doc.content,
+      description: doc.description,
+      route: doc.route,
+      title: doc.title,
+    })),
+    instructions: config.mcp.instructions,
+    name: config.mcp.name ?? config.title,
+    navigation: graph.navigation,
+    pages,
+    routes,
+    site: config.deployment.site ?? null,
+    version: manifest.blumeVersion,
+  };
+};

package/src/ai/mcp/discovery.ts

@@ -0,0 +1,49 @@
+import { MCP_TOOLS } from "./tools.ts";
+
+/** Inputs needed to describe the MCP server in discovery documents. */
+export interface McpDiscoveryInput {
+  name: string;
+  route: string;
+  site: string | null;
+  version: string;
+}
+
+/** The MCP server's address — absolute when a site is configured. */
+const serverUrl = (input: McpDiscoveryInput): string =>
+  input.site ? new URL(input.route, input.site).href : input.route;
+
+/**
+ * The `/.well-known/mcp.json` discovery document: the minimal pointer agents use
+ * to find the server and its transport.
+ */
+export const buildMcpDiscovery = (
+  input: McpDiscoveryInput
+): Record<string, unknown> => ({
+  servers: [
+    {
+      name: input.name,
+      transport: "streamable-http",
+      url: serverUrl(input),
+    },
+  ],
+});
+
+/**
+ * The `/.well-known/mcp/server-card.json` document: richer metadata including
+ * the advertised tool set (full input schemas are served live via `tools/list`).
+ */
+export const buildMcpServerCard = (
+  input: McpDiscoveryInput
+): Record<string, unknown> => ({
+  description: `Model Context Protocol server for the ${input.name} documentation.`,
+  name: input.name,
+  tools: MCP_TOOLS.map((tool) => ({
+    annotations: tool.annotations,
+    description: tool.description,
+    name: tool.name,
+    title: tool.title,
+  })),
+  transport: "streamable-http",
+  url: serverUrl(input),
+  version: input.version,
+});

package/src/ai/mcp/server.ts

@@ -0,0 +1,225 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { buildOramaIndex, queryOramaIndex } from "../../search/orama-index.ts";
+import type { OramaDoc } from "../../search/orama-index.ts";
+import type { McpData } from "./data.ts";
+import { MCP_TOOLS } from "./tools.ts";
+
+/**
+ * The low-level SDK `Server` is used (rather than the high-level `McpServer`)
+ * because the latter's `registerTool` is generic over the caller's Zod version;
+ * Blume pins Zod 3 while the SDK resolves Zod 4, so their types don't unify.
+ * Hand-written JSON Schema and the SDK's own request schemas avoid that entirely.
+ */
+
+/** Default and maximum number of hits returned by `search_docs`. */
+const DEFAULT_SEARCH_LIMIT = 8;
+const MAX_SEARCH_LIMIT = 20;
+/** Excerpt length when a page has no description. */
+const EXCERPT_LENGTH = 200;
+
+const CORS_HEADERS: Record<string, string> = {
+  "Access-Control-Allow-Headers":
+    "Content-Type, Mcp-Session-Id, Mcp-Protocol-Version",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Expose-Headers": "Mcp-Session-Id",
+};
+
+/** JSON Schema for each tool's input, keyed by tool name. */
+const INPUT_SCHEMAS: Record<string, Record<string, unknown>> = {
+  get_navigation: { properties: {}, type: "object" },
+  get_page: {
+    properties: {
+      route: {
+        description: "The page route, e.g. `/guides/install`.",
+        type: "string",
+      },
+    },
+    required: ["route"],
+    type: "object",
+  },
+  list_pages: { properties: {}, type: "object" },
+  search_docs: {
+    properties: {
+      limit: {
+        description: `Maximum hits to return (default ${DEFAULT_SEARCH_LIMIT}).`,
+        maximum: MAX_SEARCH_LIMIT,
+        minimum: 1,
+        type: "integer",
+      },
+      query: { description: "The search query.", type: "string" },
+    },
+    required: ["query"],
+    type: "object",
+  },
+};
+
+/** The `tools/list` payload, derived from shared metadata + input schemas. */
+const TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
+  annotations: tool.annotations,
+  description: tool.description,
+  inputSchema: INPUT_SCHEMAS[tool.name],
+  name: tool.name,
+  title: tool.title,
+}));
+
+const asString = (value: unknown): string =>
+  typeof value === "string" ? value : "";
+
+const asLimit = (value: unknown): number => {
+  const num = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(num)) {
+    return DEFAULT_SEARCH_LIMIT;
+  }
+  return Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT);
+};
+
+/** Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix). */
+const normalizeRoute = (input: string): string => {
+  const noTrailing = input.trim().replace(/\/+$/u, "");
+  const noSuffix = noTrailing.replace(/\.mdx?$/u, "");
+  const withSlash = noSuffix.startsWith("/") ? noSuffix : `/${noSuffix}`;
+  return withSlash === "" ? "/" : withSlash;
+};
+
+/** Build the absolute (or root-relative) URL for a route. */
+const urlFor = (route: string, site: string | null): string =>
+  site ? new URL(route, site).href : route;
+
+const text = (value: string, isError = false) => ({
+  content: [{ text: value, type: "text" as const }],
+  ...(isError ? { isError: true } : {}),
+});
+
+/** Construct a fresh MCP server with Blume's read-only docs tools registered. */
+const buildServer = (
+  data: McpData,
+  index: () => Promise<Awaited<ReturnType<typeof buildOramaIndex>>>
+): Server => {
+  const server = new Server(
+    { name: data.name, version: data.version },
+    {
+      capabilities: { tools: {} },
+      ...(data.instructions ? { instructions: data.instructions } : {}),
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: TOOL_DEFINITIONS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { arguments: args = {}, name } = request.params;
+
+    if (name === "search_docs") {
+      const db = await index();
+      const hits = await queryOramaIndex(
+        db,
+        asString(args.query),
+        asLimit(args.limit)
+      );
+      const results = hits.map((doc: OramaDoc) => ({
+        excerpt:
+          doc.description || `${doc.content.slice(0, EXCERPT_LENGTH)}…`.trim(),
+        title: doc.title,
+        url: urlFor(doc.route, data.site),
+      }));
+      return text(JSON.stringify(results, null, 2));
+    }
+
+    if (name === "get_page") {
+      const key = normalizeRoute(asString(args.route));
+      const markdown = data.pages[key];
+      if (markdown === undefined) {
+        return text(
+          `No page found at "${key}". Use list_pages or search_docs to find valid routes.`,
+          true
+        );
+      }
+      return text(markdown);
+    }
+
+    if (name === "list_pages") {
+      return text(
+        JSON.stringify(
+          data.routes.map((route) => ({
+            contentType: route.contentType,
+            description: route.description,
+            lastModified: route.lastModified,
+            route: route.route,
+            title: route.title,
+            url: urlFor(route.route, data.site),
+          })),
+          null,
+          2
+        )
+      );
+    }
+
+    if (name === "get_navigation") {
+      return text(JSON.stringify(data.navigation, null, 2));
+    }
+
+    return text(`Unknown tool: ${name}`, true);
+  });
+
+  return server;
+};
+
+/**
+ * Build a stateless Streamable-HTTP MCP request handler from a data snapshot.
+ *
+ * The Orama index is built once and reused; a fresh `Server` and transport are
+ * created per request (required by the SDK's stateless mode, which skips session
+ * tracking). `enableJsonResponse` makes each call a plain request/response — no
+ * SSE — which suits read-only docs tools and runs on any adapter (Node, Vercel,
+ * Netlify, Cloudflare). CORS is added so browser-based connectors (e.g.
+ * claude.ai) can reach the endpoint.
+ */
+export const createMcpFetchHandler = (
+  data: McpData
+): ((request: Request) => Promise<Response>) => {
+  let dbPromise: Promise<Awaited<ReturnType<typeof buildOramaIndex>>> | null =
+    null;
+  const index = () => {
+    dbPromise ??= buildOramaIndex(data.documents);
+    return dbPromise;
+  };
+
+  return async (request: Request): Promise<Response> => {
+    if (request.method === "OPTIONS") {
+      return new Response(null, { headers: CORS_HEADERS, status: 204 });
+    }
+    if (request.method === "GET") {
+      // No server-initiated streams are needed for read-only tools.
+      return new Response("Method Not Allowed", {
+        headers: { ...CORS_HEADERS, Allow: "POST, OPTIONS" },
+        status: 405,
+      });
+    }
+
+    const server = buildServer(data, index);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      enableJsonResponse: true,
+      sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    const response = await transport.handleRequest(request);
+
+    const headers = new Headers(response.headers);
+    for (const [key, value] of Object.entries(CORS_HEADERS)) {
+      headers.set(key, value);
+    }
+    return new Response(response.body, {
+      headers,
+      status: response.status,
+      statusText: response.statusText,
+    });
+  };
+};