blume 0.0.0 → 0.1.1

package/package.json

@@ -1,11 +1,155 @@
 {
   "name": "blume",
-  "version": "0.0.0",
-  "main": "index.js",
+  "version": "0.1.1",
+  "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",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./ai/*": "./src/ai/*",
+    "./schema": {
+      "types": "./dist/types/core/schema.d.ts",
+      "default": "./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",
+    "@pierre/diffs": "^1.2.11",
+    "@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",
+    "js-yaml": "^4.1.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/js-yaml": "^4.0.9",
+    "@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,64 @@
+import matter from "../core/frontmatter.ts";
+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,
+});