blume 2.0.3 → 2.1.1

package/src/cli/build-failure.ts

@@ -20,8 +20,31 @@ const buildErrorSchema = z.looseObject({
     .optional(),
 });
 
+/**
+ * The diagnostic a `BlumeError` thrown inside the build carries, such as a
+ * failed hosted search sync in `astro:build:done`. The hook runs Blume's
+ * source rather than the CLI bundle, so its error is another copy of the class
+ * that the command's `instanceof BlumeError` doesn't recognize.
+ */
+const blumeErrorSchema = z.looseObject({
+  diagnostic: z.object({
+    code: z.string(),
+    column: z.number().optional(),
+    docsUrl: z.string().optional(),
+    file: z.string().optional(),
+    line: z.number().optional(),
+    message: z.string(),
+    severity: z.enum(["error", "info", "warning"]),
+    suggestion: z.string().optional(),
+  }),
+});
+
 /** One failure as a diagnostic at the file (and position) it names. */
 const failureDiagnostic = (error: Error): Diagnostic => {
+  const raised = blumeErrorSchema.safeParse(error);
+  if (raised.success) {
+    return raised.data.diagnostic;
+  }
   const parsed = buildErrorSchema.safeParse(error);
   const { id, loc } = parsed.success ? parsed.data : {};
   // A named error (`MDXError`, `CompilerError`) says which step failed.

package/src/cli/command-meta.ts

@@ -62,6 +62,11 @@ export const commandMeta = {
     description: "Preview the last production build.",
     name: "preview",
   },
+  skill: {
+    description:
+      "Write the docs site's agent skill with a coding agent, in place of the generated one.",
+    name: "skill",
+  },
   sync: {
     description: "Re-fetch remote content sources and regenerate the runtime.",
     name: "sync",

package/src/cli/commands/audit.ts

@@ -15,6 +15,7 @@ import { isHttpUrl } from "../../audit/url.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { DiagnosticSeverity } from "../../core/types.ts";
+import { parseIgnoreFlag } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger, reportDiagnostics } from "../log.ts";
@@ -103,6 +104,12 @@ export const auditCommand = defineCommand({
         "Exit non-zero at this severity or above: error | warning | info. Defaults to error.",
       type: "string",
     },
+    ignore: {
+      description:
+        'With --external, skip outbound links whose URL matches this glob (e.g. "https://example.com/**"). Repeat it for more; internal links are always checked.',
+      type: "string",
+      valueHint: "glob",
+    },
     json: {
       description: "Emit the report as JSON on stdout (for CI/editors).",
       type: "boolean",
@@ -134,7 +141,7 @@ export const auditCommand = defineCommand({
     },
   },
   meta: commandMeta.audit,
-  async run({ args }) {
+  async run({ args, rawArgs }) {
     if (args["list-checks"]) {
       process.stdout.write(formatCatalog());
       return;
@@ -172,6 +179,7 @@ export const auditCommand = defineCommand({
     const only = splitTerms(args.only);
     const skip = splitTerms(args.skip);
     rejectUnknownTerms([...only, ...skip]);
+    const ignore = parseIgnoreFlag(rawArgs);
     let result: AuditResult;
     try {
       // `scanProject`, not `prepareProject`: the audit reads the *existing*
@@ -180,6 +188,7 @@ export const auditCommand = defineCommand({
       const project = await scanProject(root, { mode: "build" });
       result = await runAudit({
         external: args.external,
+        ignore,
         only,
         origin: args.url,
         project,

package/src/cli/commands/dev.ts

@@ -11,7 +11,9 @@ import {
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { resolveRuntimeDir } from "../../core/project.ts";
+import { referenceSpecFiles } from "../../openapi/references.ts";
 import { parsePort } from "../args.ts";
+import { astroBuildDiagnostics } from "../build-failure.ts";
 import { commandMeta } from "../command-meta.ts";
 import {
   acquireDevLock,
@@ -140,7 +142,19 @@ export const devCommand = defineCommand({
         server: { host: normalizeHost(args.host), open, port: listenPort },
       });
 
-    let server = await createServer(explicitPort, args.open ?? false);
+    let server: Awaited<ReturnType<typeof createServer>>;
+    try {
+      server = await createServer(explicitPort, args.open ?? false);
+    } catch (error) {
+      // Astro's first content sync rejects on a page it can't load (front
+      // matter that isn't valid YAML): report it at the file it names, as
+      // `blume build` does, not as an internal error blaming Blume.
+      if (error instanceof BlumeError || !(error instanceof Error)) {
+        throw error;
+      }
+      reportDiagnostics(astroBuildDiagnostics(error), root);
+      process.exit(1);
+    }
 
     // Vite bumps to the next free port when the default is taken, so record
     // the port the server actually bound — the lock's URL is what a refused
@@ -229,7 +243,8 @@ export const devCommand = defineCommand({
 
     // Content is watched per source (filesystem uses fs.watch; remote sources
     // are frozen for the session). The remaining project inputs — user pages,
-    // config, theme, and component overrides — are watched directly.
+    // config, theme, component overrides, and the local specs and overlays API
+    // references read — are watched directly.
     const dirTargets = [project.context.pagesRoot].filter(
       (target) => target !== null
     );
@@ -237,6 +252,7 @@ export const devCommand = defineCommand({
       project.context.configFile,
       project.context.themeFile,
       project.context.componentsFile,
+      ...referenceSpecFiles(project.config, root),
     ].filter((target) => target !== null);
 
     // chokidar handles what raw fs.watch made us hand-roll: recursive

package/src/cli/commands/doctor.ts

@@ -5,15 +5,20 @@ import { defineCommand } from "citty";
 import { join } from "pathe";
 import { satisfies } from "semver";
 
+import { discoverExamples } from "../../astro/examples.ts";
 import { discoverIslands } from "../../astro/islands.ts";
+import { discoverPages, navTargetRoutes } from "../../astro/pages.ts";
 import { missingDependencyDiagnostic } from "../../astro/runtime-deps.ts";
+import { missingExampleDiagnostics } from "../../core/component-diagnostics.ts";
 import {
   analyzeComponentOverrides,
   ComponentOverridesError,
 } from "../../core/component-overrides.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
+import { validateNavTargets } from "../../core/nav-diagnostics.ts";
 import { packageRoot } from "../../core/package-root.ts";
 import { scanProject } from "../../core/project-graph.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { unregisteredSnapshotDiagnostics } from "../../core/version-cut.ts";
@@ -34,23 +39,24 @@ const FALLBACK_NODE_RANGE = ">=22.12.0";
  * Plan `components.ts` the way `blume dev`/`build` do, reporting each override
  * that can't be planned — a non-static form, or an import of a file that
  * doesn't exist — with its own line. The scan alone never reads the file, so
- * without this doctor would pass a project whose build fails.
+ * without this doctor would pass a project whose build fails. Also returns
+ * the MDX tags the file overrides.
  */
 const componentsDiagnostics = async (
   componentsFile: string | null
-): Promise<Diagnostic[]> => {
+): Promise<{ issues: Diagnostic[]; mdx: string[] }> => {
   if (!componentsFile) {
-    return [];
+    return { issues: [], mdx: [] };
   }
   try {
-    analyzeComponentOverrides(
+    const { mdx } = analyzeComponentOverrides(
       await readFile(componentsFile, "utf-8"),
       componentsFile
     );
-    return [];
+    return { issues: [], mdx: mdx.map((entry) => entry.key) };
   } catch (error) {
     if (error instanceof ComponentOverridesError) {
-      return error.issues;
+      return { issues: error.issues, mdx: [] };
     }
     throw error;
   }
@@ -71,6 +77,25 @@ const supportedNodeRange = (): string => {
   }
 };
 
+/** The adapters a project runs, one line per kind, for the doctor summary. */
+const integrationSummary = (config: ResolvedConfig): string[] => {
+  const { assistant } = config.ai;
+  let assistantSummary = "off";
+  if (assistant?.enabled) {
+    assistantSummary = assistant.endpoint
+      ? "external endpoint"
+      : assistant.provider.kind;
+  }
+  return [
+    `References: ${config.reference.map((adapter) => adapter.kind).join(", ") || "none"}`,
+    `Analytics: ${config.analytics.map((adapter) => adapter.kind).join(", ") || "none"}`,
+    `Consent: ${config.consent?.kind ?? "none"}`,
+    `Rate limiting: ${config.rateLimit?.kind ?? "off"}`,
+    `Sources: ${config.content.sources.map((source) => source.kind).join(", ")}`,
+    `Assistant: ${assistantSummary}`,
+  ];
+};
+
 export const doctorCommand = defineCommand({
   args: {
     json: {
@@ -97,15 +122,33 @@ export const doctorCommand = defineCommand({
     loadEnvFiles(root);
 
     try {
-      const project = await scanProject(root, { mode: "build" });
+      const project = await scanProject(root, {
+        // A missing secret fails at the first request. Checked before the
+        // sources fetch, so it's still reported when one of them fails the
+        // scan for want of it.
+        beforeSources: (config) => {
+          diagnostics.push(...checkRequiredSecrets(config));
+        },
+        mode: "build",
+      });
+      // Tabs, selector items, and featured links can point at custom pages
+      // and generated routes too, so they're checked against every route
+      // the site serves, as `blume dev`/`build` check them.
+      const userPages = project.context.pagesRoot
+        ? await discoverPages(project.context.pagesRoot)
+        : [];
       diagnostics.push(
         ...project.diagnostics,
-        ...unregisteredSnapshotDiagnostics(project)
+        ...unregisteredSnapshotDiagnostics(project),
+        ...validateNavTargets(
+          project.graph.navigation,
+          navTargetRoutes(project, userPages)
+        )
       );
 
       const { config } = project;
-      // The packages and secrets a build would need: an adapter's missing SDK
-      // fails the build, and a missing secret fails at the first request.
+      // The packages a build would need: an adapter's missing SDK fails the
+      // build.
       const { islands } = await discoverIslands(root);
       const dependencies = await missingDependencyDiagnostic(
         config,
@@ -116,9 +159,19 @@ export const doctorCommand = defineCommand({
       if (dependencies) {
         diagnostics.push(dependencies);
       }
+      const overrides = await componentsDiagnostics(
+        project.context.componentsFile
+      );
       diagnostics.push(
-        ...(await componentsDiagnostics(project.context.componentsFile)),
-        ...checkRequiredSecrets(config)
+        ...overrides.issues,
+        // A `<Component path>` naming no example renders a "No example
+        // found" box, which dev and build warn about too.
+        ...missingExampleDiagnostics(
+          project.graph.pages,
+          await discoverExamples(root, config.examples.source),
+          root,
+          new Set([...islands.map((island) => island.name), ...overrides.mdx])
+        )
       );
       const features = serverFeatures(config);
       if (
@@ -144,23 +197,9 @@ export const doctorCommand = defineCommand({
         logger.info(`Output: ${config.deployment.options.output}`);
         logger.info(`Adapter: ${config.deployment.kind}`);
         logger.info(`Search: ${config.search.provider.kind}`);
-        logger.info(
-          `References: ${config.reference.map((adapter) => adapter.kind).join(", ") || "none"}`
-        );
-        logger.info(
-          `Analytics: ${config.analytics.map((adapter) => adapter.kind).join(", ") || "none"}`
-        );
-        logger.info(
-          `Sources: ${config.content.sources.map((source) => source.kind).join(", ")}`
-        );
-        const { assistant } = config.ai;
-        let assistantSummary = "off";
-        if (assistant?.enabled) {
-          assistantSummary = assistant.endpoint
-            ? "external endpoint"
-            : assistant.provider.kind;
+        for (const line of integrationSummary(config)) {
+          logger.info(line);
         }
-        logger.info(`Assistant: ${assistantSummary}`);
       }
     } catch (error) {
       if (error instanceof BlumeError) {

package/src/cli/commands/eval.ts

@@ -104,12 +104,37 @@ const parseFlags = (args: EvalFlags) => {
   return { agent: args.agent, threshold, timeoutS };
 };
 
+/** A shell word for the rerun command, single-quoted only when it has to be. */
+const shellWord = (value: string): string =>
+  /^[\w./:@%+=,-]+$/u.test(value)
+    ? value
+    : `'${value.replaceAll("'", String.raw`'\''`)}'`;
+
+/**
+ * The command a `--fix` agent reruns to verify its edits. It carries the run's
+ * own flags: a bare `blume eval` would fall back to Codex and `evals.yaml`,
+ * grading a different file with a different agent than the run it's fixing.
+ */
+const rerunCommand = (
+  args: EvalFlags,
+  { agent, threshold, timeoutS }: ReturnType<typeof parseFlags>
+): string =>
+  [
+    `blume eval --agent ${agent}`,
+    args.file === DEFAULT_FILE ? "" : `--file ${shellWord(args.file)}`,
+    args.threshold === undefined ? "" : `--threshold ${threshold}`,
+    args.timeout === undefined ? "" : `--timeout ${timeoutS}`,
+  ]
+    .filter((part) => part !== "")
+    .join(" ");
+
 /** `blume eval --fix`: hand the failing report to the interactive agent. */
 const runFixHandoff = async (
   agent: AgentKind,
   result: EvalResult,
   root: string,
-  threshold: number
+  threshold: number,
+  command: string
 ): Promise<void> => {
   const count = result.counts.fail + result.counts.error;
   if (count === 0) {
@@ -120,7 +145,7 @@ const runFixHandoff = async (
   process.stderr.write(
     `  Handing ${count} failed question${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
   );
-  const code = await launchAgentCode(agent, evalFixPrompt(report));
+  const code = await launchAgentCode(agent, evalFixPrompt(report, command));
   if (code !== 0) {
     process.exit(code);
   }
@@ -184,7 +209,8 @@ export const evalCommand = defineCommand({
   meta: commandMeta.eval,
   async run({ args }) {
     const root = process.cwd();
-    const { agent, threshold, timeoutS } = parseFlags(args);
+    const flags = parseFlags(args);
+    const { agent, threshold, timeoutS } = flags;
     if (args.action === "init") {
       await runInit(agent, args.file);
       return;
@@ -259,7 +285,13 @@ export const evalCommand = defineCommand({
     if (args.fix) {
       // The gate is a CI concern; a handoff run succeeds when the agent
       // session does, not when the docs already passed.
-      await runFixHandoff(agent, result, root, threshold);
+      await runFixHandoff(
+        agent,
+        result,
+        root,
+        threshold,
+        rerunCommand(args, flags)
+      );
       return;
     }
 

package/src/cli/commands/init.ts

@@ -272,14 +272,16 @@ export const initCommand = defineCommand({
     // which `init` leaves alone; say what it still needs before installing.
     const note = workspaceNote(root, answers, env);
 
-    // Keep installed dependencies, Blume's generated runtime (`.blume/`), and
-    // build output (`dist/`) out of version control. Idempotent: creates
-    // `.gitignore` when absent and skips entries already present
-    // (trailing-slash agnostic).
+    // Keep installed dependencies, Blume's generated runtime (`.blume/`),
+    // build output (`dist/`), and local secrets (`.env.local`, where every
+    // missing-secret warning says to put them) out of version control.
+    // Idempotent: creates `.gitignore` when absent and skips entries already
+    // present (trailing-slash agnostic).
     const ignored = await ensureGitignore(root, [
       "node_modules/",
       ".blume/",
       "dist/",
+      ".env.local",
     ]);
     if (ignored.length > 0) {
       sink.success(`Added ${ignored.join(", ")} to .gitignore`);

package/src/cli/commands/skill.ts

@@ -0,0 +1,96 @@
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import {
+  planSkill,
+  WRITE_SKILL_DIR,
+  writeSkillPrompt,
+} from "../../ai/write-skill.ts";
+import { AGENTS, launchInstalledAgent } from "../../audit/agent.ts";
+import type { AgentKind } from "../../audit/agent.ts";
+import { BlumeError } from "../../core/diagnostics.ts";
+import { packageRoot } from "../../core/package-root.ts";
+import { scanProject } from "../../core/project-graph.ts";
+import { getBlumeVersion } from "../../core/version.ts";
+import { commandMeta } from "../command-meta.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { logger, reportDiagnostics } from "../log.ts";
+
+/**
+ * `blume skill` — write the docs site's agent skill with a coding agent. Every
+ * build publishes a generated skill at `/skill.md` (a map of the docs); this
+ * opens Claude Code or Codex on the `blume-write-skill` skill bundled in this
+ * package to write the richer one, grounded in the docs, under the same name
+ * so it takes the generated one's place. The judgment stays in the skill; the
+ * command is the front door, like `blume migrate`. Status lines go straight to
+ * stderr: consola drops info-level lines in test and CI environments.
+ */
+export const skillCommand = defineCommand({
+  args: {
+    claude: {
+      description: "Write the skill with Claude Code.",
+      type: "boolean",
+    },
+    codex: {
+      description: "Write the skill with Codex.",
+      type: "boolean",
+    },
+  },
+  meta: commandMeta.skill,
+  async run({ args }) {
+    const root = process.cwd();
+    // SAFETY: AGENTS is a closed record keyed by AgentKind, so its keys are
+    // exactly the agent kinds.
+    const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
+      (kind) => args[kind]
+    );
+    if (agents.length > 1) {
+      logger.error("Pass at most one of --codex or --claude.");
+      process.exit(1);
+    }
+    const [agent] = agents;
+
+    try {
+      // A scan, not `prepareProject`: the agent reads the content tree and
+      // the runtime isn't touched, so a running dev server is left alone.
+      const plan = planSkill(await scanProject(root, { mode: "build" }));
+      const skillDir = join(packageRoot(), WRITE_SKILL_DIR);
+      process.stderr.write(
+        `  ${plan.exists ? "Updating" : "Writing"} the "${plan.name}" skill at ${plan.file}.\n`
+      );
+
+      // Without an agent flag the command is the pointer for any other agent:
+      // the bundled skill's path, and the install line that puts the skill
+      // where agents look for it.
+      if (!agent) {
+        process.stderr.write(
+          `  blume skill writes it with a coding agent: rerun with --codex or --claude.\n  Using another agent? Point it at ${join(skillDir, "SKILL.md")},\n  or install the skill where your agent looks for skills: npx skills add haydenbleasel/blume --skill blume-write-skill\n`
+        );
+        return;
+      }
+
+      const cli = AGENTS[agent];
+      process.stderr.write(`  Handing it to ${cli.name}…\n\n`);
+      const code = await launchInstalledAgent(
+        cli.bin,
+        writeSkillPrompt(plan, { skillDir, version: getBlumeVersion() })
+      );
+      if (code === null) {
+        logger.error(
+          `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+        );
+        process.exit(1);
+      }
+      if (code !== 0) {
+        process.exit(code);
+      }
+    } catch (error) {
+      if (error instanceof BlumeError) {
+        reportDiagnostics([error.diagnostic], root);
+        process.exit(1);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+  },
+});

package/src/cli/commands/validate.ts

@@ -13,6 +13,7 @@ import { validateLinks } from "../../core/links.ts";
 import { buildManifest } from "../../core/manifest.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { Diagnostic } from "../../core/types.ts";
+import { parseIgnoreFlag } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import {
@@ -28,6 +29,12 @@ export const validateCommand = defineCommand({
       description: "Check external (HTTP) links over the network.",
       type: "boolean",
     },
+    ignore: {
+      description:
+        'With --external, skip external links whose URL matches this glob (e.g. "https://example.com/**"). Repeat it for more; internal links are always checked.',
+      type: "string",
+      valueHint: "glob",
+    },
     json: {
       description: "Emit diagnostics as JSON on stdout (for CI/editors).",
       type: "boolean",
@@ -38,8 +45,9 @@ export const validateCommand = defineCommand({
     },
   },
   meta: commandMeta.validate,
-  async run({ args }) {
+  async run({ args, rawArgs }) {
     const root = process.cwd();
+    const ignore = parseIgnoreFlag(rawArgs);
     const diagnostics: Diagnostic[] = [];
 
     try {
@@ -83,6 +91,7 @@ export const validateCommand = defineCommand({
           checkExternal: Boolean(args.external),
           extraRoutes,
           i18n: project.config.i18n,
+          ignore,
           publicDir: existsSync(publicDir) ? publicDir : null,
           redirects: project.config.redirects,
         }))

package/src/cli/index.ts

@@ -81,6 +81,11 @@ const main = defineCommand({
       () => import("./commands/preview.ts"),
       "previewCommand"
     ),
+    skill: lazyCommand(
+      commandMeta.skill,
+      () => import("./commands/skill.ts"),
+      "skillCommand"
+    ),
     sync: lazyCommand(
       commandMeta.sync,
       () => import("./commands/sync.ts"),

package/src/cli/init/scaffold.ts

@@ -679,7 +679,7 @@ const ESBUILD_APPROVAL = "  allowBuilds:\n    esbuild: true";
  * What the project still needs from a workspace it sits in, when `init` left
  * that workspace's config alone: a place in a pnpm workspace's `packages`
  * (pnpm skips a folder it doesn't list), pnpm's approval for esbuild's build
- * script (pnpm 10 and later fail the install without it), or Yarn Berry's
+ * script (pnpm 11 and later fail the install without it), or Yarn Berry's
  * `node_modules` linker. Undefined when the workspace already has it, or the
  * project doesn't sit in one.
  */
@@ -699,12 +699,12 @@ export const workspaceNote = (
       const entry = `  packages:\n    - ${relative(workspace, root)}`;
       return approved
         ? `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing:\n\n${entry}`
-        : `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing, and approve esbuild's build script, or pnpm 10 and later stop the install:\n\n${entry}\n${ESBUILD_APPROVAL}`;
+        : `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing, and approve esbuild's build script, or pnpm 11 and later stop the install:\n\n${entry}\n${ESBUILD_APPROVAL}`;
     }
     if (approved) {
       return;
     }
-    return `This project joins the pnpm workspace at ${file}. Approve esbuild's build script there before installing, or pnpm 10 and later stop the install:\n\n${ESBUILD_APPROVAL}`;
+    return `This project joins the pnpm workspace at ${file}. Approve esbuild's build script there before installing, or pnpm 11 and later stop the install:\n\n${ESBUILD_APPROVAL}`;
   }
   if (answers.packageManager !== "yarn" || yarnMajor(env.userAgent) === 1) {
     return;

package/src/cli/prepare.ts

@@ -59,6 +59,12 @@ export const prepareProject = async (
   let project: BlumeProject;
   try {
     project = await scanProject(options.root, {
+      // Fail-fast on missing secrets: warn now, not at the first request, and
+      // before the sources fetch, so a source that can't authenticate on a
+      // fresh build still gets its variable named.
+      beforeSources: (config) => {
+        reportDiagnostics(checkRequiredSecrets(config), options.root);
+      },
       devServerUrl: options.devServerUrl,
       mode: options.mode,
       overrides: options.overrides,
@@ -138,8 +144,5 @@ export const prepareProject = async (
     logger.warn(warning);
   }
 
-  // Fail-fast on missing runtime secrets: warn now, not at the first request.
-  reportDiagnostics(checkRequiredSecrets(project.config), options.root);
-
   return project;
 };