blume 0.1.5 → 0.3.0

package/docs/content/sources.mdx

@@ -88,6 +88,49 @@ a remote source for changes instead, set `pollInterval` (seconds) on it — the
 dev server re-fetches on that interval and reloads only when the content
 actually changes. Leave it unset to avoid hitting the API while you work.
 
+## GitHub Releases
+
+The built-in `github-releases` source turns a repo's releases into a changelog:
+each release becomes a `type: changelog` entry, so your release notes _are_ your
+changelog — nothing to write twice. Combined with the generated
+[changelog timeline](/docs/advanced/changelog), publishing a GitHub release
+ships a changelog entry.
+
+```ts blume.config.ts
+import { defineConfig } from "blume";
+
+export default defineConfig({
+  content: {
+    sources: [
+      { type: "filesystem", root: "content" },
+      {
+        type: "github-releases",
+        prefix: "changelog",
+        owner: "acme",
+        repo: "sdk",
+        // prereleases: false,  // include prereleases (default off)
+        // drafts: false,       // include drafts (needs a write token)
+        // limit: 100,          // cap releases, newest-first
+      },
+    ],
+  },
+});
+```
+
+Each release maps to the changelog fields automatically: its name (or tag)
+becomes the title, its published date drives the timeline order, the tag becomes
+`changelog.version`, and prereleases are tagged `Prerelease` (others `Release`).
+The notes render as the entry body. Give the source a `prefix` so its release
+pages nest under a route like `/changelog/v1-2-0`.
+
+A private repo authenticates with the `GITHUB_TOKEN` environment variable — the
+same token the other GitHub features use, never inlined into your config. Like
+every remote source it's cached under `.blume/cache/<source>/` and served
+offline if the API is unreachable. Because a changelog is supplementary, a fetch
+failure with no cache (say a CI build without a token) degrades to an empty
+changelog with a warning rather than failing the build — set `GITHUB_TOKEN` in
+your CI and deploy environments to populate it.
+
 ## Sanity
 
 The built-in `sanity` source runs a GROQ query and maps each document's fields

package/docs/content/syntax.mdx

@@ -11,7 +11,7 @@ each.
 ## Headings
 
 Structure a page with headings. Blume renders your frontmatter `title` as the
-page heading, so start your content at `##` — `##` through `####` become entries
+page heading, so start your content at `##` — `##` and `###` become entries
 in the table of contents. Every `##`–`######` heading is also wrapped in a link
 to its own anchor, so readers can click a heading to copy, bookmark, or share a
 permalink straight to that section (hover to reveal the `#`). Turn this off with

package/docs/index.mdx

@@ -21,18 +21,9 @@ library — with no app boilerplate to write or maintain.
 
 ## Why Blume exists
 
-Blume is the answer to a problem I kept trying to solve at Vercel: documentation
-should be _fast_, _AI-ready_, and require _zero configuration_ — down to not
-needing a starter template at all.
+Docs should be fast, AI-ready and require zero configuration — down to not needing a starter template at all. Some docs tools hand you an entire codebase to maintain before you've written a word. Others build the template around your content, but lock you in to their managed service.
 
-Most docs tools hand you a project to own before you've written a word: an app to
-scaffold, a framework to learn, a template to keep in sync with upstream. Blume
-flips that around. The framework _is_ the template, so the only thing you ever
-touch is your content. When you outgrow the defaults, you add configuration one
-file at a time — and you can `blume eject` to a plain Astro project the day you
-want full control.
-
-— Hayden Bleasel
+Blume takes the best of both worlds. The framework is the template, so the only thing you ever touch is your content. When you want to customize, you can start replacing the built-in components, modifying the single configuration file or even ejecting if you want the Astro site directly.
 
 ## What makes Blume different
 
@@ -83,7 +74,7 @@ loosely-typed YAML.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
 - **Customization** — component overrides, React islands, custom pages, theme
   tokens, and a source-component registry via `blume add`.
-- **Migration** — `blume migrate mintlify | starlight | fumadocs`.
+- **Migration** — `blume migrate mintlify | starlight | nextra | fumadocs`.
 - **Eject** — `blume eject` produces a standalone Astro project that still uses
   the `blume` package.
 

package/docs/reference/cli.mdx

@@ -17,17 +17,65 @@ blume <command> [options]
 | `blume preview`        | Preview the last build.                                |
 | `blume add <item>`     | Install a source component from the registry.          |
 | `blume migrate <tool>` | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
+| `blume sync`           | Re-fetch remote content sources and regenerate.        |
 | `blume eject`          | Promote the runtime into a standalone Astro app.       |
+| `blume check`          | Type-check the site with `astro check`.                |
 | `blume doctor`         | Diagnose config and content problems.                  |
 | `blume validate`       | Validate links across your content.                    |
 
 ## Common flags
 
+- `blume init --content-dir <dir> --yes` — set the content folder (default `docs`) and skip prompts.
+- `blume init --template docs|api|sdk|changelog` — scaffold from a starter (API reference, SDK, or changelog instead of the plain docs seed).
+- `blume init --package-manager npm|pnpm|yarn|bun` — tailor the printed next-steps to your package manager.
+- `blume init --eject` — scaffold, then eject to a standalone Astro project (falls back to guiding you through `blume eject` when dependencies aren't installed yet).
 - `blume dev --host --port <n> --open`
-- `blume build --strict` — fail on diagnostics.
+- `blume dev --content-dir <dir>` — scan a different content folder without editing `blume.config.ts`.
+- `blume dev --debug` — verbose Astro/Vite logging for troubleshooting.
+- `blume dev --preview` / `blume build --preview` — include drafts and unpublished CMS content.
+- `blume build --strict` — fail the build on diagnostic errors (also works on `blume dev`).
+- `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
+- `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
+- `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.
+- `blume preview --host --port <n>` — bind the preview server.
+- `blume sync --force` — re-fetch remote sources, dropping the cached snapshot first.
+- `blume add <item> --force` — overwrite files that already exist.
+- `blume check --preview` — include drafts and unpublished CMS content when checking.
+- `blume check --strict` — fail on content diagnostics as well as type errors.
 - `blume eject --yes` — skip the confirmation prompt.
 - `blume validate --external` — also check external links over the network.
 - `blume validate --strict` — exit non-zero on warnings too.
+- `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on
+  stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI
+  and editor integrations.
+
+## Type-checking
+
+`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check)
+over your project. It regenerates the `.blume` runtime, syncs Astro's content
+types, then reports any TypeScript errors — in your `blume.config.ts`, in custom
+`.astro` pages, and in the components they import. It exits non-zero when there
+are errors, so it works as a `typecheck` step in CI:
+
+```json title="package.json"
+{
+  "scripts": {
+    "typecheck": "blume check"
+  }
+}
+```
+
+Add a `tsconfig.json` extending Astro's config to your project root so authored
+pages resolve `blume/*` imports and virtual modules like `blume:data`:
+
+```json title="tsconfig.json"
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
+}
+```
+
+Without a project `tsconfig.json`, only the generated runtime is checked.
 
 ## Validating links
 

package/docs/reference/frontmatter.mdx

@@ -24,6 +24,11 @@ Every page accepts the following frontmatter. All fields are optional.
       default: "false",
       description: "Exclude from production builds.",
     },
+    lastModified: {
+      type: "string",
+      description:
+        'Pin the page\'s "last updated" date (ISO or YAML date); overrides the git-derived date.',
+    },
   }}
 />
 
@@ -33,7 +38,8 @@ Every page accepts the following frontmatter. All fields are optional.
 sidebar:
   label: Install
   order: 2
-  icon: Download
+  icon: download
+  badge: New
   hidden: false
 ```
 
@@ -42,7 +48,9 @@ sidebar:
 ```yaml lineNumbers
 seo:
   title: Install Blume
+  description: Install Blume and scaffold your first project.
   image: /og/install.png
+  canonical: https://acme.com/install
   noindex: false
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -43,6 +43,7 @@
       "default": "./src/core/schema.ts"
     },
     "./runtime": "./src/runtime/index.ts",
+    "./hooks": "./src/components/islands/hooks.ts",
     "./astro": "./src/astro/index.ts",
     "./og": "./src/og/index.ts",
     "./markdown": "./src/markdown/index.ts",
@@ -62,6 +63,7 @@
     "typecheck": "tsgo --noEmit && tsgo -p test/tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@astrojs/check": "^0.9.0",
     "@astrojs/markdown-satteri": "^0.3.2",
     "@astrojs/mdx": "^7.0.0",
     "@astrojs/node": "^11.0.0",

package/src/ai/ask-context.ts

@@ -0,0 +1,131 @@
+import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
+import type { OramaDoc } from "../search/orama-index.ts";
+
+/** A chat message as posted by the Ask AI island (`{ role, content }`). */
+export interface AskMessage {
+  content: string;
+  role: string;
+}
+
+/** The current-page hint the island forwards so the endpoint can prioritize it. */
+export interface AskPage {
+  path?: string;
+}
+
+/**
+ * The self-contained snapshot the grounded Ask AI endpoint imports. Bundles the
+ * search documents so retrieval works regardless of the configured search
+ * provider and needs no filesystem access at request time. Serialized to
+ * `generated/ask-data.json` and built by {@link buildAskData}.
+ */
+export interface AskData {
+  documents: OramaDoc[];
+  site: string | null;
+}
+
+/** Documents retrieved per question and injected into the system prompt. */
+const MAX_RESULTS = 6;
+/** Characters kept per injected excerpt. */
+const EXCERPT_CHARS = 1500;
+/** Overall cap on injected documentation characters. */
+const CONTEXT_BUDGET = 8000;
+
+/**
+ * The grounding preamble. The model is told to answer strictly from the injected
+ * excerpts and to cite the pages it used, so answers stay tied to the docs.
+ */
+const BASE_INSTRUCTION =
+  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. If the answer is not covered by them, say you don't know and suggest where in the docs to look — do not invent details. Cite the page titles you drew from.";
+
+/** Normalize a page path to a document `route` (`/`, `/a/b`, no trailing slash). */
+const normalizeRoute = (input: string): string => {
+  const noTrailing = input.trim().replace(/\/+$/u, "");
+  const withSlash = noTrailing.startsWith("/") ? noTrailing : `/${noTrailing}`;
+  return withSlash === "" ? "/" : withSlash;
+};
+
+/** The most recent non-empty user message, used as the retrieval query. */
+const lastUserMessage = (messages: AskMessage[]): string => {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    if (message?.role === "user" && message.content?.trim()) {
+      return message.content.trim();
+    }
+  }
+  return "";
+};
+
+/** Trim a document body to `max` characters, marking truncation with an ellipsis. */
+const excerpt = (content: string, max: number): string => {
+  const trimmed = content.trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+};
+
+/**
+ * Build the request-time grounding function for the Ask AI endpoint.
+ *
+ * Lexical retrieval over Orama (the same index/ranking the search dialog and MCP
+ * server use). The index is built once and memoized across requests. Returns a
+ * grounded system prompt — the retrieved excerpts plus the page the user is
+ * viewing — or `undefined` when there is nothing to ground on, so the endpoint
+ * can fall back to its plain prompt.
+ */
+export const createAskContext = (
+  data: AskData
+): ((
+  messages: AskMessage[],
+  page?: AskPage
+) => Promise<string | undefined>) => {
+  let dbPromise: Promise<Awaited<ReturnType<typeof buildOramaIndex>>> | null =
+    null;
+  const index = () => {
+    dbPromise ??= buildOramaIndex(data.documents);
+    return dbPromise;
+  };
+  const byRoute = new Map(data.documents.map((doc) => [doc.route, doc]));
+
+  return async (messages, page) => {
+    const list = Array.isArray(messages) ? messages : [];
+    const query = lastUserMessage(list);
+    if (!query) {
+      return;
+    }
+
+    // The current page anchors retrieval to its locale and is injected first.
+    const current = page?.path
+      ? byRoute.get(normalizeRoute(page.path))
+      : undefined;
+    const db = await index();
+    const hits = await queryOramaIndex(
+      db,
+      query,
+      MAX_RESULTS,
+      current?.locale || undefined
+    );
+
+    const seen = new Set<string>();
+    const sections: string[] = [];
+    let budget = CONTEXT_BUDGET;
+    const push = (doc: OramaDoc, label: string) => {
+      if (seen.has(doc.route) || budget <= 0) {
+        return;
+      }
+      seen.add(doc.route);
+      const body = excerpt(doc.content, Math.min(EXCERPT_CHARS, budget));
+      budget -= body.length;
+      sections.push(`## ${doc.title} (${doc.route})${label}\n${body}`);
+    };
+
+    if (current) {
+      push(current, " — the page the user is currently viewing");
+    }
+    for (const hit of hits) {
+      push(hit, "");
+    }
+
+    if (sections.length === 0) {
+      return;
+    }
+    return `${BASE_INSTRUCTION}\n\n<docs>\n${sections.join("\n\n")}\n</docs>`;
+  };
+};

package/src/ai/ask-data.ts

@@ -0,0 +1,25 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import { buildSearchDocuments } from "../search/documents.ts";
+import type { AskData } from "./ask-context.ts";
+
+/**
+ * Build the grounding snapshot the Ask AI endpoint serves. Like the MCP server,
+ * Ask AI is independent of on-page search, so documents are indexed even when the
+ * search provider is `none` (`includeWhenDisabled`). `locale` is kept (unlike the
+ * MCP snapshot) so retrieval can be filtered to the current page's language.
+ */
+export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
+  const documents = await buildSearchDocuments(project, {
+    includeWhenDisabled: true,
+  });
+  return {
+    documents: documents.map((doc) => ({
+      content: doc.content,
+      description: doc.description,
+      locale: doc.locale,
+      route: doc.route,
+      title: doc.title,
+    })),
+    site: project.config.deployment.site ?? null,
+  };
+};

package/src/astro/component-slots.ts

@@ -0,0 +1,165 @@
+import type {
+  ComponentOverrideAnalysis,
+  NormalizedOverride,
+  OverrideFramework,
+} from "../core/component-overrides.ts";
+
+/**
+ * Turn analyzed `components.ts` overrides into the generated `components.ts`
+ * module plus per-override hydration wrappers.
+ *
+ * The runtime overrides object already holds bare imported identifiers, so those
+ * (when not hydrated) ride through a plain spread. Everything else needs a static
+ * import Vite can see: path-string overrides import the file directly, while
+ * hydrated overrides get a wrapper `.astro` that applies the `client:*` directive
+ * (Astro directives must be written statically). The `islands` group is folded
+ * into the MDX component map — it is just `mdx` with a default `client: "visible"`.
+ */
+
+export interface ComponentSlotWrapper {
+  content: string;
+  /** File name (no extension) under `.blume/src/generated/component-slots/`. */
+  name: string;
+}
+
+export interface ComponentSlotPlan {
+  /** Frameworks used by resolved overrides; enable the matching Astro renderer. */
+  frameworks: Set<OverrideFramework>;
+  /** Contents of `.blume/src/generated/components.ts`. */
+  module: string;
+  wrappers: ComponentSlotWrapper[];
+}
+
+const EMPTY_MODULE = `// Generated by Blume. Do not edit.
+export const mdxComponents = {};
+export const layoutOverrides = {};
+`;
+
+/** Astro client directive for a hydrated override. */
+const directiveFor = (override: NormalizedOverride): string => {
+  const framework = override.source?.framework;
+  switch (override.client) {
+    case "idle": {
+      return "client:idle";
+    }
+    case "visible": {
+      return "client:visible";
+    }
+    case "media": {
+      return override.media
+        ? `client:media="${override.media}"`
+        : "client:load";
+    }
+    case "only": {
+      return framework ? `client:only="${framework}"` : "client:load";
+    }
+    default: {
+      return "client:load";
+    }
+  }
+};
+
+const importClause = (variable: string, name: string, path: string): string =>
+  name === "default"
+    ? `import ${variable} from ${JSON.stringify(path)};`
+    : `import { ${name} as ${variable} } from ${JSON.stringify(path)};`;
+
+/** A wrapper `.astro` that statically imports a component and hydrates it. */
+const wrapperContent = (override: NormalizedOverride): string => {
+  const { name, path } = override.source as NonNullable<
+    NormalizedOverride["source"]
+  >;
+  const clause =
+    name === "default"
+      ? `import Component from ${JSON.stringify(path)};`
+      : `import { ${name} as Component } from ${JSON.stringify(path)};`;
+  return `---
+// Generated by Blume. Do not edit.
+${clause}
+---
+<Component ${directiveFor(override)} {...Astro.props}><slot /></Component>
+`;
+};
+
+const sanitize = (value: string): string =>
+  value.replaceAll(/[^A-Za-z0-9]/gu, "_");
+
+export const planComponentSlots = (
+  componentsFile: string | null,
+  analysis: ComponentOverrideAnalysis | null
+): ComponentSlotPlan => {
+  const frameworks = new Set<OverrideFramework>();
+  if (!componentsFile) {
+    return { frameworks, module: EMPTY_MODULE, wrappers: [] };
+  }
+  if (!analysis) {
+    return {
+      frameworks,
+      module: `// Generated by Blume. Do not edit.
+import overrides from ${JSON.stringify(componentsFile)};
+export const mdxComponents = overrides.mdx ?? {};
+export const layoutOverrides = overrides.layout ?? {};
+`,
+      wrappers: [],
+    };
+  }
+
+  const wrappers: ComponentSlotWrapper[] = [];
+  const importLines: string[] = [];
+  // Explicit `key: Variable` map entries, per surface.
+  const mdxEntries: string[] = [];
+  const layoutEntries: string[] = [];
+  let counter = 0;
+
+  // Islands are MDX components hydrated by default, so plan them alongside `mdx`.
+  const mdxOverrides = [...analysis.mdx, ...analysis.islands];
+
+  const plan = (
+    override: NormalizedOverride,
+    group: "mdx" | "layout",
+    entries: string[]
+  ): void => {
+    const { source } = override;
+    if (source?.framework) {
+      frameworks.add(source.framework);
+    }
+    // Bare identifier, not hydrated: the runtime object already has it.
+    if (override.identifier && !override.client) {
+      return;
+    }
+    if (!source) {
+      // Unresolved (already warned): leave it on the runtime object.
+      return;
+    }
+    const variable = `__blumeSlot${counter}`;
+    counter += 1;
+    if (override.client) {
+      const name = `${group}-${sanitize(override.key)}`;
+      wrappers.push({ content: wrapperContent(override), name });
+      importLines.push(
+        importClause(variable, "default", `./component-slots/${name}.astro`)
+      );
+    } else {
+      importLines.push(importClause(variable, source.name, source.path));
+    }
+    entries.push(`${JSON.stringify(override.key)}: ${variable}`);
+  };
+
+  for (const override of mdxOverrides) {
+    plan(override, "mdx", mdxEntries);
+  }
+  for (const override of analysis.layout) {
+    plan(override, "layout", layoutEntries);
+  }
+
+  // `overrides.islands` is not spread: every valid island is hydrated, so it is
+  // emitted as an explicit wrapper entry above (raw spreads only carry bare,
+  // non-hydrated identifiers from `mdx`/`layout`).
+  const moduleSource = `// Generated by Blume. Do not edit.
+import overrides from ${JSON.stringify(componentsFile)};
+${importLines.join("\n")}${importLines.length ? "\n" : ""}export const mdxComponents = { ...(overrides.mdx ?? {})${mdxEntries.length ? `, ${mdxEntries.join(", ")}` : ""} };
+export const layoutOverrides = { ...(overrides.layout ?? {})${layoutEntries.length ? `, ${layoutEntries.join(", ")}` : ""} };
+`;
+
+  return { frameworks, module: moduleSource, wrappers };
+};