blume 0.2.0 → 0.3.0

package/src/cli/commands/doctor.ts

@@ -4,16 +4,23 @@ import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
-import { logger, reportDiagnostics } from "../log.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { logger, reportDiagnostics, reportDiagnosticsJson } from "../log.ts";
 
 const MIN_NODE_MAJOR = 20;
 
 export const doctorCommand = defineCommand({
+  args: {
+    json: {
+      description: "Emit diagnostics as JSON on stdout (for CI/editors).",
+      type: "boolean",
+    },
+  },
   meta: {
     description: "Diagnose common configuration and content problems.",
     name: "doctor",
   },
-  async run() {
+  async run({ args }) {
     const root = process.cwd();
     const diagnostics: Diagnostic[] = [];
 
@@ -52,15 +59,25 @@ export const doctorCommand = defineCommand({
         });
       }
 
-      logger.info(`Pages: ${project.graph.pages.length}`);
-      logger.info(`Output: ${config.deployment.output}`);
-      logger.info(`Search: ${config.search.provider}`);
+      if (!args.json) {
+        logger.info(`Pages: ${project.graph.pages.length}`);
+        logger.info(`Output: ${config.deployment.output}`);
+        logger.info(`Search: ${config.search.provider}`);
+      }
     } catch (error) {
       if (error instanceof BlumeError) {
         diagnostics.push(error.diagnostic);
       } else {
-        throw error;
+        reportInternalError(error);
+        process.exit(1);
+      }
+    }
+
+    if (args.json) {
+      if (reportDiagnosticsJson(diagnostics, root)) {
+        process.exit(1);
       }
+      return;
     }
 
     const hadErrors = reportDiagnostics(diagnostics, root);

package/src/cli/commands/init.ts

@@ -5,6 +5,7 @@ import { defineCommand } from "citty";
 import { basename, dirname, join } from "pathe";
 
 import { getBlumeVersion } from "../../core/version.ts";
+import { eject } from "../../registry/eject.ts";
 import { logger } from "../log.ts";
 
 /**
@@ -32,25 +33,119 @@ const packageTemplate = (name: string, version: string): string => `{
 }
 `;
 
-const CONFIG_TEMPLATE = `import { defineConfig } from "blume";
+const TEMPLATES = ["docs", "api", "sdk", "changelog"] as const;
+type Template = (typeof TEMPLATES)[number];
+
+const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+
+/** A starter: the config plus seed content files (path is relative to root). */
+interface Starter {
+  config: string;
+  files: (contentDir: string) => { content: string; path: string }[];
+}
+
+const configFor = (
+  extra: string
+): string => `import { defineConfig } from "blume";
 
 export default defineConfig({
   title: "My Docs",
-  description: "Documentation powered by Blume.",
+  description: "Documentation powered by Blume.",${extra}
 });
 `;
 
-const INDEX_TEMPLATE = `---
-title: Introduction
-description: Welcome to your new Blume docs.
----
-
-# Introduction
+const page = (title: string, description: string, body: string): string =>
+  `---\ntitle: ${title}\ndescription: ${description}\n---\n\n${body}\n`;
 
-Welcome to **Blume** — markdown-first docs powered by Astro and Vite.
+const STARTERS: Record<Template, Starter> = {
+  api: {
+    config: configFor(`
+  openapi: {
+    enabled: true,
+    route: "/api",
+    sources: [
+      {
+        label: "Petstore",
+        spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+      },
+    ],
+  },`),
+    files: (dir) => [
+      {
+        content: page(
+          "API Reference",
+          "Explore the API.",
+          "# API Reference\n\nYour OpenAPI spec renders at [`/api`](/api). Point `openapi.sources` at your own spec in `blume.config.ts`."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+    ],
+  },
+  changelog: {
+    config: configFor(`
+  navigation: {
+    tabs: [
+      { label: "Docs", path: "/" },
+      { label: "Changelog", path: "/changelog" },
+    ],
+  },`),
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Welcome to your new Blume docs.",
+          "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+      {
+        content: `---\ntitle: v1.0.0\ntype: changelog\ndate: 2026-01-01\n---\n\nThe first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries beside it.\n`,
+        path: join(dir, "changelog", "v1-0-0.mdx"),
+      },
+    ],
+  },
+  docs: {
+    config: configFor(""),
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Welcome to your new Blume docs.",
+          `# Introduction\n\nWelcome to **Blume** — markdown-first docs powered by Astro and Vite.\n\nEdit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`
+        ),
+        path: join(dir, "index.mdx"),
+      },
+    ],
+  },
+  sdk: {
+    config: configFor(""),
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Get started with the SDK.",
+          "# Introduction\n\nInstall the SDK and make your first call. See [Installation](/installation)."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+      {
+        content: page(
+          "Installation",
+          "Install the SDK.",
+          "# Installation\n\n```package-install\nyour-sdk\n```"
+        ),
+        path: join(dir, "installation.mdx"),
+      },
+    ],
+  },
+};
 
-Edit \`docs/index.mdx\` to get started, then run \`blume dev\`.
-`;
+/** Install + dev commands to print for the chosen package manager. */
+const commandsFor = (pm: PackageManager): { dev: string; install: string } => ({
+  dev: pm === "npm" ? "npm run dev" : `${pm} dev`,
+  install: `${pm} install`,
+});
 
 const writeFileSafe = async (
   path: string,
@@ -73,6 +168,19 @@ export const initCommand = defineCommand({
       description: "Content directory.",
       type: "string",
     },
+    eject: {
+      description: "Eject to a standalone Astro project after scaffolding.",
+      type: "boolean",
+    },
+    "package-manager": {
+      description:
+        "Package manager for the next-steps hint (npm|pnpm|yarn|bun).",
+      type: "string",
+    },
+    template: {
+      description: "Starter template: docs | api | sdk | changelog.",
+      type: "string",
+    },
     yes: { description: "Skip prompts.", type: "boolean" },
   },
   meta: {
@@ -83,16 +191,56 @@ export const initCommand = defineCommand({
     const root = process.cwd();
     const contentDir = args["content-dir"] ?? "docs";
 
+    const template = (args.template ?? "docs") as Template;
+    if (!TEMPLATES.includes(template)) {
+      logger.error(
+        `Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`
+      );
+      process.exit(1);
+    }
+    const pm = (args["package-manager"] ?? "npm") as PackageManager;
+    if (!PACKAGE_MANAGERS.includes(pm)) {
+      logger.error(
+        `Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`
+      );
+      process.exit(1);
+    }
+
+    const starter = STARTERS[template];
     const createdPackage = await writeFileSafe(
       join(root, "package.json"),
       packageTemplate(toPackageName(basename(root)), getBlumeVersion())
     );
-    await writeFileSafe(join(root, "blume.config.ts"), CONFIG_TEMPLATE);
-    await writeFileSafe(join(root, contentDir, "index.mdx"), INDEX_TEMPLATE);
+    await writeFileSafe(join(root, "blume.config.ts"), starter.config);
+    await Promise.all(
+      starter
+        .files(contentDir)
+        .map((file) => writeFileSafe(join(root, file.path), file.content))
+    );
+
+    const commands = commandsFor(pm);
+
+    if (args.eject) {
+      // Eject only generates files (no Astro runtime), so it works right after
+      // scaffolding. The standalone app then runs with Astro directly.
+      try {
+        await eject(root);
+        logger.success("Ejected to a standalone Astro project.");
+        logger.box(`Next steps:\n\n  ${commands.install}\n  npx astro dev\n`);
+      } catch (error) {
+        logger.warn(
+          `Scaffolded, but eject failed: ${(error as Error).message}`
+        );
+        logger.box(
+          `Next steps:\n\n  ${commands.install}\n  blume eject --yes\n`
+        );
+      }
+      return;
+    }
 
     const nextSteps = createdPackage
-      ? "Next steps:\n\n  npm install\n  blume dev\n"
-      : "Next steps:\n\n  blume dev\n";
+      ? `Next steps:\n\n  ${commands.install}\n  ${commands.dev}\n`
+      : `Next steps:\n\n  ${commands.dev}\n`;
     logger.box(nextSteps);
   },
 });

package/src/cli/commands/validate.ts

@@ -7,7 +7,8 @@ import { BlumeError } from "../../core/diagnostics.ts";
 import { validateLinks } from "../../core/links.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { Diagnostic } from "../../core/types.ts";
-import { logger, reportDiagnostics } from "../log.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { logger, reportDiagnostics, reportDiagnosticsJson } from "../log.ts";
 
 export const validateCommand = defineCommand({
   args: {
@@ -15,6 +16,10 @@ export const validateCommand = defineCommand({
       description: "Check external (HTTP) links over the network.",
       type: "boolean",
     },
+    json: {
+      description: "Emit diagnostics as JSON on stdout (for CI/editors).",
+      type: "boolean",
+    },
     strict: {
       description: "Treat warnings as errors.",
       type: "boolean",
@@ -46,8 +51,17 @@ export const validateCommand = defineCommand({
       if (error instanceof BlumeError) {
         diagnostics.push(error.diagnostic);
       } else {
-        throw error;
+        reportInternalError(error);
+        process.exit(1);
+      }
+    }
+
+    if (args.json) {
+      const hadErrors = reportDiagnosticsJson(diagnostics, root);
+      if (hadErrors || (Boolean(args.strict) && diagnostics.length > 0)) {
+        process.exit(1);
       }
+      return;
     }
 
     const hadErrors = reportDiagnostics(diagnostics, root);

package/src/cli/index.ts

@@ -3,6 +3,7 @@ import { defineCommand, runMain } from "citty";
 import { getBlumeVersion } from "../core/version.ts";
 import { addCommand } from "./commands/add.ts";
 import { buildCommand } from "./commands/build.ts";
+import { checkCommand } from "./commands/check.ts";
 import { devCommand } from "./commands/dev.ts";
 import { doctorCommand } from "./commands/doctor.ts";
 import { ejectCommand } from "./commands/eject.ts";
@@ -12,6 +13,7 @@ import { previewCommand } from "./commands/preview.ts";
 import { syncCommand } from "./commands/sync.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { loadEnvFiles } from "./env.ts";
+import { reportInternalError } from "./internal-error.ts";
 
 const main = defineCommand({
   meta: {
@@ -22,6 +24,7 @@ const main = defineCommand({
   subCommands: {
     add: addCommand,
     build: buildCommand,
+    check: checkCommand,
     dev: devCommand,
     doctor: doctorCommand,
     eject: ejectCommand,
@@ -37,4 +40,16 @@ const main = defineCommand({
 // can read their tokens (e.g. `GITHUB_TOKEN`) during the content scan.
 loadEnvFiles(process.cwd());
 
+// Backstop for unexpected async failures that escape a command's own handling
+// (e.g. a rejected timer/watcher in `blume dev`), so even those report through
+// the stable internal-error contract rather than a bare stack trace.
+process.on("uncaughtException", (error) => {
+  reportInternalError(error);
+  process.exit(1);
+});
+process.on("unhandledRejection", (error) => {
+  reportInternalError(error);
+  process.exit(1);
+});
+
 runMain(main);

package/src/cli/internal-error.ts

@@ -0,0 +1,63 @@
+import { getBlumeVersion } from "../core/version.ts";
+
+const ESC = String.fromCodePoint(27);
+const DIM = `${ESC}[2m`;
+const RED = `${ESC}[31m`;
+const BOLD = `${ESC}[1m`;
+const RESET = `${ESC}[0m`;
+
+const ISSUES_URL = "https://github.com/haydenbleasel/blume/issues";
+
+// Absolute paths into the hidden generated runtime (`…/.blume/…`), including any
+// trailing `:line:col`, stopping at whitespace or a closing paren.
+const BLUME_FRAME = /(?<abs>\/[^\s()]*\/\.blume\/[^\s()]*)/gu;
+
+/**
+ * Rewrite `.blume/` frames in a stack so the generated runtime reads clearly:
+ * the machine-absolute prefix is dropped to a project-relative `.blume/…` path
+ * and tagged `(generated)`, keeping the reader oriented instead of staring at a
+ * long path into a hidden directory. Frames in the user's own source (custom
+ * pages keep their real location; wrappers import user files by their real path)
+ * are untouched, so the actionable frame stays intact.
+ */
+export const remapBlumeStack = (stack: string): string =>
+  stack.replaceAll(BLUME_FRAME, (match) => {
+    const marker = match.indexOf("/.blume/");
+    return `${match.slice(marker + 1)} (generated)`;
+  });
+
+/**
+ * Print an unexpected (non-{@link BlumeError}) failure in a stable, reportable
+ * shape instead of a bare stack trace: a fixed `BLUME_INTERNAL` code, the
+ * message, a trimmed stack, and an environment dump for bug reports. Callers
+ * exit after this — it doesn't exit itself, so it's testable.
+ */
+export const reportInternalError = (error: unknown): void => {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const lines = [
+    `${RED}${BOLD}BLUME_INTERNAL${RESET} An unexpected error occurred.`,
+    `  ${err.message}`,
+  ];
+
+  // A few frames are enough to locate the fault without burying the report;
+  // `.blume/` frames are relativized so the hidden runtime reads clearly.
+  const stack = remapBlumeStack(err.stack ?? "")
+    .split("\n")
+    .slice(1, 5)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (stack.length > 0) {
+    lines.push("", `${DIM}${stack.join("\n")}${RESET}`);
+  }
+
+  lines.push(
+    "",
+    "This is likely a bug in Blume. Please report it with the details below:",
+    `  ${DIM}Blume:    ${getBlumeVersion()}`,
+    `  Node:     ${process.version}`,
+    `  Platform: ${process.platform} ${process.arch}${RESET}`,
+    `  ${ISSUES_URL}`
+  );
+
+  process.stderr.write(`${lines.join("\n")}\n`);
+};

package/src/cli/log.ts

@@ -1,7 +1,9 @@
 import { consola } from "consola";
+import { relative } from "pathe";
 
 import {
   countBySeverity,
+  enrichDiagnostic,
   formatDiagnostic,
   hasErrors,
 } from "../core/diagnostics.ts";
@@ -9,6 +11,31 @@ import type { Diagnostic } from "../core/types.ts";
 
 export const logger = consola.withTag("blume");
 
+/**
+ * Print diagnostics as a JSON document on stdout for CI and editors: each is
+ * enriched with its `docsUrl` and its `file` made root-relative. Returns whether
+ * any were errors, matching {@link reportDiagnostics}.
+ */
+export const reportDiagnosticsJson = (
+  diagnostics: Diagnostic[],
+  root?: string
+): boolean => {
+  const enriched = diagnostics.map((diagnostic) => {
+    const withDocs = enrichDiagnostic(diagnostic);
+    return withDocs.file && root
+      ? { ...withDocs, file: relative(root, withDocs.file) }
+      : withDocs;
+  });
+  process.stdout.write(
+    `${JSON.stringify(
+      { diagnostics: enriched, summary: countBySeverity(diagnostics) },
+      null,
+      2
+    )}\n`
+  );
+  return hasErrors(diagnostics);
+};
+
 /** Print a batch of diagnostics and return whether any were errors. */
 export const reportDiagnostics = (
   diagnostics: Diagnostic[],
@@ -19,7 +46,9 @@ export const reportDiagnostics = (
   }
 
   for (const diagnostic of diagnostics) {
-    process.stderr.write(`${formatDiagnostic(diagnostic, root)}\n`);
+    process.stderr.write(
+      `${formatDiagnostic(enrichDiagnostic(diagnostic), root)}\n`
+    );
   }
 
   const counts = countBySeverity(diagnostics);

package/src/cli/prepare.ts

@@ -1,10 +1,16 @@
 import { generateRuntime } from "../astro/generate.ts";
 import { BlumeError, hasErrors } from "../core/diagnostics.ts";
 import { scanProject } from "../core/project-graph.ts";
-import type { BlumeProject, BuildMode } from "../core/project-graph.ts";
+import type {
+  BlumeProject,
+  BuildMode,
+  ConfigOverrides,
+} from "../core/project-graph.ts";
 import { serverFeatures } from "../core/server-features.ts";
 import { loadEnvFiles } from "./env.ts";
+import { reportInternalError } from "./internal-error.ts";
 import { logger, reportDiagnostics } from "./log.ts";
+import { checkRequiredSecrets } from "./required-secrets.ts";
 
 export interface PrepareOptions {
   root: string;
@@ -16,6 +22,8 @@ export interface PrepareOptions {
   preview?: boolean;
   /** Force remote sources to re-fetch instead of serving the cached snapshot. */
   refresh?: boolean;
+  /** CLI config overrides (e.g. `--output`, `--content-dir`). */
+  overrides?: ConfigOverrides;
 }
 
 /**
@@ -34,15 +42,17 @@ export const prepareProject = async (
     project = await scanProject(options.root, {
       devServerUrl: options.devServerUrl,
       mode: options.mode,
+      overrides: options.overrides,
       preview: options.preview,
       refresh: options.refresh,
     });
   } catch (error) {
     if (error instanceof BlumeError) {
       reportDiagnostics([error.diagnostic], options.root);
-      process.exit(1);
+    } else {
+      reportInternalError(error);
     }
-    throw error;
+    process.exit(1);
   }
 
   // Hard gate: server-only features cannot ship in a static build.
@@ -81,5 +91,9 @@ export const prepareProject = async (
   for (const warning of warnings) {
     logger.warn(warning);
   }
+
+  // Fail-fast on missing runtime secrets: warn now, not at the first request.
+  reportDiagnostics(checkRequiredSecrets(project.config), options.root);
+
   return project;
 };

package/src/cli/required-secrets.ts

@@ -0,0 +1,44 @@
+import { resolveAskBackend } from "../ai/ask.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { Diagnostic } from "../core/types.ts";
+
+/**
+ * Warn early when an enabled feature needs a secret env var that isn't set, so
+ * the failure surfaces at `blume dev`/`build` instead of at the first request in
+ * production. These are runtime secrets (the endpoint reads them on the server),
+ * so this warns rather than hard-fails — the value may live only in the deploy
+ * environment. Build-time secrets (search-index sync) already warn during sync.
+ */
+export const checkRequiredSecrets = (config: ResolvedConfig): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const requireSecret = (feature: string, env: string, note?: string): void => {
+    if (process.env[env]) {
+      return;
+    }
+    diagnostics.push({
+      code: "BLUME_MISSING_SECRET",
+      message: `${feature} is enabled but ${env} is not set${note ? ` (${note})` : ""}.`,
+      severity: "warning",
+      suggestion: `Set ${env} in .env.local for local dev, or in your host's environment for production.`,
+    });
+  };
+
+  if (config.ai.ask?.enabled) {
+    const backend = resolveAskBackend(config.ai.ask);
+    if (backend.kind === "gateway") {
+      requireSecret(
+        "Ask AI (AI Gateway)",
+        "AI_GATEWAY_API_KEY",
+        "on Vercel the gateway can also authenticate via OIDC"
+      );
+    } else {
+      requireSecret("Ask AI", backend.apiKeyEnv);
+    }
+  }
+
+  if (config.search.provider === "mixedbread") {
+    requireSecret("Mixedbread search", "MIXEDBREAD_API_KEY");
+  }
+
+  return diagnostics;
+};

package/src/components/BlumePage.astro

@@ -0,0 +1,107 @@
+---
+// Render a Blume content entry's body inside a custom page — e.g. to feature a
+// doc on a landing page, or build a bespoke index that still shows real content.
+//
+//   import BlumePage from "blume/components/BlumePage.astro";
+//   import data from "blume:data";
+//   import { getBlumeCollection } from "blume/runtime";
+//   const [intro] = getBlumeCollection(data, { prefix: "/docs" });
+//   ---
+//   <BlumePage id={intro.entryId} />
+//
+// Blume's built-in MDX components are wired in so callouts, cards, steps, etc.
+// render as they do on a normal page. Pass `components` to add your own overrides
+// or islands (which live in the generated runtime and aren't imported here). The
+// heavy, opt-in `<Math>` component is not included by default — pass it if the
+// embedded content uses math.
+import { getEntry, render } from "astro:content";
+
+import Icon from "./Icon.astro";
+import Accordion from "./content/Accordion.astro";
+import AccordionItem from "./content/AccordionItem.astro";
+import AutoTypeTable from "./content/AutoTypeTable.astro";
+import Badge from "./content/Badge.astro";
+import Callout from "./content/Callout.astro";
+import Card from "./content/Card.astro";
+import CardGroup from "./content/CardGroup.astro";
+import CodeBlock from "./content/CodeBlock.astro";
+import CodeGroup from "./content/CodeGroup.astro";
+import ColorItem from "./content/ColorItem.astro";
+import ColorRoot from "./content/Color.astro";
+import ColorRow from "./content/ColorRow.astro";
+import Column from "./content/Column.astro";
+import Columns from "./content/Columns.astro";
+import Component from "./content/Component.astro";
+import Diff from "./content/Diff.astro";
+import Expandable from "./content/Expandable.astro";
+import FileTree from "./content/FileTree.astro";
+import Frame from "./content/Frame.astro";
+import GithubInfo from "./content/GithubInfo.astro";
+import Panel from "./content/Panel.astro";
+import Prompt from "./content/Prompt.astro";
+import Step from "./content/Step.astro";
+import Steps from "./content/Steps.astro";
+import Tab from "./content/Tab.astro";
+import Tabs from "./content/Tabs.astro";
+import Tile from "./content/Tile.astro";
+import Tooltip from "./content/Tooltip.astro";
+import TreeRoot from "./content/Tree.astro";
+import TreeFile from "./content/TreeFile.astro";
+import TreeFolder from "./content/TreeFolder.astro";
+import TypeTable from "./content/TypeTable.astro";
+import Visibility from "./content/Visibility.astro";
+
+interface Props {
+  /** Astro collection the entry lives in. Defaults to `"docs"`. */
+  collection?: string;
+  /** Extra MDX components merged over Blume's built-ins (overrides, islands). */
+  components?: Record<string, unknown>;
+  /** Content entry id — e.g. a `BlumeRoute.entryId` from `getBlumeCollection`. */
+  id: string;
+}
+
+const { collection = "docs", components: extra = {}, id } = Astro.props;
+
+const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
+const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
+
+const components = {
+  Accordion,
+  AccordionItem,
+  AutoTypeTable,
+  Badge,
+  Callout,
+  Card,
+  CardGroup,
+  CodeBlock,
+  CodeGroup,
+  Color,
+  Column,
+  Columns,
+  Component,
+  Diff,
+  Expandable,
+  FileTree,
+  Frame,
+  GithubInfo,
+  Icon,
+  Panel,
+  Prompt,
+  Step,
+  Steps,
+  Tab,
+  Tabs,
+  Tile,
+  Tooltip,
+  Tree,
+  TypeTable,
+  Visibility,
+  ...extra,
+};
+
+const entry = await getEntry(collection, id);
+const rendered = entry ? await render(entry) : null;
+const Content = rendered?.Content ?? null;
+---
+
+{Content && <Content components={components} />}