blume 1.7.3 → 2.0.1

package/src/audit/agent.ts

@@ -97,3 +97,27 @@ export const launchAgent = async (
     `Read ${promptPath} and follow its instructions exactly.`,
   ]);
 };
+
+/**
+ * {@link launchAgent}, but resolving `null` instead of rejecting when the
+ * executable isn't on PATH, so each command can print its own install hint.
+ * Only `ENOENT` means "not installed" — any other spawn failure (`EACCES`,
+ * `EMFILE`, …) must surface as itself, not be masked by an irrelevant hint.
+ */
+export const launchInstalledAgent = async (
+  bin: string,
+  prompt: string,
+  platform: NodeJS.Platform = process.platform
+): Promise<number | null> => {
+  try {
+    return await launchAgent(bin, prompt, platform);
+  } catch (error) {
+    // SAFETY: only the `code` tag is inspected; a spawn failure throws an
+    // ErrnoException, and any other thrown value fails the comparison and
+    // rethrows unchanged.
+    if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      throw error;
+    }
+    return null;
+  }
+};

package/src/audit/catalog.ts

@@ -668,7 +668,7 @@ export const CHECKS = [
   // audits it — they audit for Google. Blume emits it, so Blume checks it.
   {
     category: "ai",
-    fix: "Rebuild — `ai.llmsTxt` is enabled but the build has no llms.txt. If that's intentional, set `ai.llmsTxt: false`.",
+    fix: "Rebuild — `agents.llmsTxt` is enabled but the build has no llms.txt. If that's intentional, set `agents.llmsTxt: false`.",
     id: "BLUME_AUDIT_LLMS_TXT_MISSING",
     severity: "warning",
     tier: "static",
@@ -806,7 +806,7 @@ export const checkMeta = (id: CheckId): CheckMeta => {
   return meta;
 };
 
-const DOCS_BASE = "https://useblume.dev/docs/reference/audit";
+const DOCS_BASE = "https://useblume.dev/docs/cli/audit";
 
 /** `BLUME_AUDIT_TITLE_TOO_LONG` -> `…/audit#title-too-long`. */
 export const checkDocsUrl = (id: CheckId): string =>

package/src/audit/checks/assets.ts

@@ -43,12 +43,12 @@ const resolveAsset = (
     return null;
   }
 
-  const origin = siteOrigin(context.project.config.deployment.site);
+  const origin = siteOrigin(context.project.config.deployment.options.site);
   const resolved = resolveHref(
     page.url,
     asset.src,
     origin,
-    normalizeBasePath(context.project.config.deployment.base)
+    normalizeBasePath(context.project.config.deployment.options.base)
   );
   // A subresource on another origin (a CDN, an analytics script) is outside the
   // build; we can't check whether it exists without the network.

package/src/audit/checks/dns-aid.ts

@@ -181,7 +181,7 @@ export const dnsAidChecks: CheckModule = {
     if (!context.origin) {
       return [];
     }
-    const host = dnsAidHost(context.project.config.deployment.site);
+    const host = dnsAidHost(context.project.config.deployment.options.site);
     if (!host) {
       return [];
     }

package/src/audit/checks/duplicates.ts

@@ -27,7 +27,9 @@ const isNonCanonical = (page: PageSnapshot, deployBase: string): boolean => {
 
 /** Pages that can meaningfully be compared against each other for duplication. */
 const comparable = (context: AuditContext): PageSnapshot[] => {
-  const deployBase = normalizeBasePath(context.project.config.deployment.base);
+  const deployBase = normalizeBasePath(
+    context.project.config.deployment.options.base
+  );
   return context.pages.filter(
     (page) =>
       page.indexable &&

package/src/audit/checks/i18n.ts

@@ -7,7 +7,7 @@ import { normalizePath } from "../url.ts";
 
 /** The normalized `deployment.base` — hreflang hrefs carry it, page URLs don't. */
 const deployBaseOf = (context: AuditContext): string =>
-  normalizeBasePath(context.project.config.deployment.base);
+  normalizeBasePath(context.project.config.deployment.options.base);
 
 /** The hreflang value meaning "use this when nothing else matches". Not a locale. */
 const X_DEFAULT = "x-default";

package/src/audit/checks/indexability.ts

@@ -1,6 +1,6 @@
 import { normalizeBasePath, stripBasePath } from "../../core/base-path.ts";
-import { SITE_INFERRING_ADAPTERS } from "../../core/deployment-env.ts";
 import type { Diagnostic } from "../../core/types.ts";
+import { deployPlatform } from "../../deploy/platforms/index.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
 import { ERROR_ROUTES } from "../types.ts";
@@ -20,7 +20,7 @@ const canonicalChecks = (
   context: AuditContext,
   page: PageSnapshot
 ): Diagnostic[] => {
-  const { site } = context.project.config.deployment;
+  const { site } = context.project.config.deployment.options;
   const origin = siteOrigin(site);
 
   // Error routes are noindex by design, so a canonical on them is meaningless
@@ -79,7 +79,7 @@ const canonicalChecks = (
   // comparing.
   const target = normalizePath(
     stripBasePath(
-      normalizeBasePath(context.project.config.deployment.base),
+      normalizeBasePath(context.project.config.deployment.options.base),
       decodePath(canonical.pathname)
     )
   );
@@ -151,8 +151,8 @@ export const indexabilityChecks: CheckModule = {
     // cannot emit a canonical, an Open Graph image, or a sitemap on *any* page.
     // That's one fact about the config, not a defect on each of 200 pages —
     // report it once, and let the checks that depend on it stay quiet.
-    if (!context.project.config.deployment.site) {
-      const { adapter } = context.project.config.deployment;
+    if (!context.project.config.deployment.options.site) {
+      const { deployment } = context.project.config;
       const site = {
         file: context.project.context.configFile ?? undefined,
         url: "/",
@@ -163,11 +163,11 @@ export const indexabilityChecks: CheckModule = {
       // would duplicate state the platform owns, so the finding (which agents
       // apply verbatim via `--claude`/`--codex`) must not suggest it.
       found.push(
-        adapter && SITE_INFERRING_ADAPTERS.has(adapter)
+        deployPlatform(deployment).env
           ? finding(
               "BLUME_AUDIT_SITE_INFERRED_AT_DEPLOY",
               site,
-              `deployment.site is not set in this build — on ${adapter} it is inferred from the platform env at deploy time, so canonical URLs, Open Graph images, and the sitemap are only missing from this local artifact.`
+              `deployment.site is not set in this build — on ${deployment.kind} it is inferred from the platform env at deploy time, so canonical URLs, Open Graph images, and the sitemap are only missing from this local artifact.`
             )
           : finding(
               "BLUME_AUDIT_SITE_NOT_SET",

package/src/audit/checks/links.ts

@@ -45,9 +45,9 @@ export const linkChecks: CheckModule = {
   category: "links",
   run(context) {
     const found: Diagnostic[] = [];
-    const origin = siteOrigin(context.project.config.deployment.site);
+    const origin = siteOrigin(context.project.config.deployment.options.site);
     const deployBase = normalizeBasePath(
-      context.project.config.deployment.base
+      context.project.config.deployment.options.base
     );
     /** Broken chrome targets, and the first page each was seen on. */
     const brokenChrome = new Map<string, PageSnapshot>();

package/src/audit/checks/llms.ts

@@ -6,16 +6,16 @@ import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule } from "../types.ts";
 import { isServed, normalizePath, siteOrigin } from "../url.ts";
 
-/** The object form of `ai.llmsTxt`. The schema always emits it, but hand-built
+/** The object form of `agents.llmsTxt`. The schema always emits it, but hand-built
  * audit contexts (tests, partial configs) may still carry the raw boolean. */
 const isLlmsToggleObject = (
   value: boolean | { enabled: boolean; openapi: boolean } | undefined
 ): value is { enabled: boolean; openapi: boolean } =>
   typeof value === "object" && value !== null;
 
-/** The `ai.llmsTxt` config normalized to what the checks need. */
+/** The `agents.llmsTxt` config normalized to what the checks need. */
 const llmsConfig = (context: AuditContext) => {
-  const value = context.project.config.ai?.llmsTxt;
+  const value = context.project.config.agents?.llmsTxt;
   if (isLlmsToggleObject(value)) {
     return { enabled: value.enabled, openapi: value.openapi };
   }
@@ -82,9 +82,9 @@ export const llmsChecks: CheckModule = {
     }
 
     const found: Diagnostic[] = [];
-    const origin = siteOrigin(context.project.config.deployment.site);
+    const origin = siteOrigin(context.project.config.deployment.options.site);
     const deployBase = normalizeBasePath(
-      context.project.config.deployment.base
+      context.project.config.deployment.options.base
     );
 
     const listed = new Set<string>();
@@ -114,7 +114,7 @@ export const llmsChecks: CheckModule = {
     // The reverse direction, mirroring INDEXABLE_PAGE_NOT_IN_SITEMAP: a page
     // that is built, indexable, and in the nav belongs in the index. Pages the
     // generator deliberately skips — hidden, drafts, error routes, API
-    // reference when `ai.llmsTxt.openapi` is off, custom pages with no
+    // reference when `agents.llmsTxt.openapi` is off, custom pages with no
     // manifest route — are skipped here for the same reasons.
     for (const page of context.pages) {
       const { route } = page;

package/src/audit/checks/network.ts

@@ -153,7 +153,7 @@ export const networkChecks: CheckModule = {
 
     const found: Diagnostic[] = [];
     const deployBase = normalizeBasePath(
-      context.project.config.deployment.base
+      context.project.config.deployment.options.base
     );
     const targets = context.pages.map((page) =>
       liveUrl(origin, page, deployBase)
@@ -217,9 +217,9 @@ export const networkChecks: CheckModule = {
 export const externalChecks: CheckModule = {
   category: "network",
   async run(context) {
-    const origin = siteOrigin(context.project.config.deployment.site);
+    const origin = siteOrigin(context.project.config.deployment.options.site);
     const deployBase = normalizeBasePath(
-      context.project.config.deployment.base
+      context.project.config.deployment.options.base
     );
 
     /** Every outbound URL, and the pages that link to it. */

package/src/audit/checks/og-image.ts

@@ -53,9 +53,9 @@ export const ogImageChecks: CheckModule = {
       return pending;
     };
 
-    const origin = siteOrigin(context.project.config.deployment.site);
+    const origin = siteOrigin(context.project.config.deployment.options.site);
     const deployBase = normalizeBasePath(
-      context.project.config.deployment.base
+      context.project.config.deployment.options.base
     );
     const candidates: { page: PageSnapshot; path: string }[] = [];
 

package/src/audit/checks/robots.ts

@@ -23,7 +23,7 @@ export const robotsChecks: CheckModule = {
   category: "robots",
   run(context) {
     const { robots } = context;
-    const { site } = context.project.config.deployment;
+    const { site } = context.project.config.deployment.options;
 
     if (!context.project.config.seo.robots) {
       return [];

package/src/audit/checks/sitemap.ts

@@ -150,7 +150,7 @@ export const sitemapChecks: CheckModule = {
   category: "sitemap",
   run(context) {
     const { sitemap } = context;
-    const { site } = context.project.config.deployment;
+    const { site } = context.project.config.deployment.options;
 
     // Without `deployment.site` Blume can't emit a sitemap at all (absolute URLs
     // are required), and that's a config choice, not a defect. Stay quiet.
@@ -220,7 +220,7 @@ export const sitemapChecks: CheckModule = {
 
     const origin = siteOrigin(site);
     const deployBase = normalizeBasePath(
-      context.project.config.deployment.base
+      context.project.config.deployment.options.base
     );
     const listed = sitemapPaths(context, deployBase);
 

package/src/audit/checks/social.ts

@@ -27,7 +27,7 @@ export const socialChecks: CheckModule = {
   category: "social",
   run(context) {
     const found: Diagnostic[] = [];
-    const hasSite = Boolean(context.project.config.deployment.site);
+    const hasSite = Boolean(context.project.config.deployment.options.site);
     const required = ogRequired(hasSite);
 
     for (const page of context.pages) {

package/src/audit/run.ts

@@ -29,6 +29,7 @@ import {
 import { crawlStaticDir } from "./crawl.ts";
 import { buildGraph } from "./graph.ts";
 import { resolveRedirects } from "./redirects.ts";
+import { shortId } from "./terms.ts";
 import { DEFAULT_THRESHOLDS } from "./types.ts";
 import type {
   AuditContext,
@@ -119,7 +120,7 @@ const readSources = async (
 /** Does a check id or its category match one of the user's `--only`/`--skip` terms? */
 const matches = (id: CheckId, terms: string[]): boolean => {
   const meta = CHECKS.find((check) => check.id === id);
-  const short = id.replace("BLUME_AUDIT_", "").toLowerCase();
+  const short = shortId(id);
   return terms.some((raw) => {
     const term = raw.trim().toLowerCase();
     return (
@@ -150,8 +151,8 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
     files: crawl.files,
     graph: buildGraph(
       crawl.pages,
-      siteOrigin(project.config.deployment.site),
-      normalizeBasePath(project.config.deployment.base)
+      siteOrigin(project.config.deployment.options.site),
+      normalizeBasePath(project.config.deployment.options.base)
     ),
     llms: crawl.llms,
     origin,

package/src/audit/terms.ts

@@ -0,0 +1,31 @@
+import { CHECKS } from "./catalog.ts";
+import type { CheckId } from "./catalog.ts";
+
+/** A check id without its `BLUME_AUDIT_` prefix, lowercased: `link_to_broken`. */
+export const shortId = (id: CheckId): string =>
+  id.replace("BLUME_AUDIT_", "").toLowerCase();
+
+/**
+ * Every term `--only`/`--skip` accept, as the audit's filter compares them:
+ * each check's short id and each category. The full `BLUME_AUDIT_…` id is
+ * accepted too, but it's the short id with a prefix, so it isn't listed.
+ */
+export const checkTerms = (): string[] => [
+  ...new Set([
+    ...CHECKS.map((check) => check.category),
+    ...CHECKS.map((check) => shortId(check.id)),
+  ]),
+];
+
+/**
+ * The `--only`/`--skip` terms that name no check and no category. A typo there
+ * (`--only link` for `links`) would otherwise match nothing, report nothing,
+ * and pass a CI gate that was meant to catch something.
+ */
+export const unknownCheckTerms = (terms: readonly string[]): string[] => {
+  const known = new Set(checkTerms());
+  return terms.filter((raw) => {
+    const term = raw.trim().toLowerCase();
+    return !(known.has(term) || known.has(term.replace(/^blume_audit_/u, "")));
+  });
+};

package/src/audit/url.ts

@@ -11,16 +11,16 @@ export type ServedContext = Pick<AuditContext, "byUrl" | "files" | "project">;
 /**
  * Routes the server answers that the build writes no file for.
  *
- * The MCP endpoint is streamable HTTP: llms.txt advertises `ai.mcp.route`
+ * The MCP endpoint is streamable HTTP: llms.txt advertises `agents.mcp.route`
  * whenever the server is enabled, but it appears in neither the page snapshots
  * nor the static file index, so a check that only consults those reads the
  * site's own index as broken. The exemption is the configured route while the
- * server is on, and nothing wider — with `ai.mcp` off, a listed `/mcp` is as
+ * server is on, and nothing wider — with `agents.mcp` off, a listed `/mcp` is as
  * dead as any other missing target. Any future server route (a search API, a
  * playground proxy) belongs here too, so every check recognizes it at once.
  */
 const serverRoutes = (context: ServedContext): string[] => {
-  const mcp = context.project.config.ai?.mcp;
+  const mcp = context.project.config.agents?.mcp;
   return mcp?.enabled ? [normalizePath(mcp.route)] : [];
 };
 
@@ -124,16 +124,16 @@ export const resolveHref = (
     return { kind: "external", url: parsed.toString() };
   }
 
-  // A relative href resolves against the page's own URL. `URL` needs an origin
-  // to do that, so borrow a placeholder one and keep only the path. The base
-  // carries a trailing slash because Astro's directory build serves `/docs/api`
-  // at `/docs/api/` — so in a browser `./auth` there means `/docs/api/auth`, not
-  // `/docs/auth`. Resolving against the slashless form would silently mis-target
-  // every relative link on the site by one directory level.
-  const base =
-    pageUrl === "/"
-      ? "https://blume.invalid/"
-      : `https://blume.invalid${pageUrl}/`;
+  // A relative href resolves the way a browser resolves it from the page's
+  // canonical URL. `URL` needs an origin to do that, so borrow a placeholder
+  // one and keep only the path. The canonical URL is slashless — the generated
+  // config sets `trailingSlash: "never"`, Vercel redirects `/docs/api/` onto
+  // `/docs/api`, and the dev server 404s the slashed form — so `./auth` there
+  // means `/docs/auth`, exactly where a reader's click lands. Content links
+  // never hit this: the Markdown pipeline rewrites them root-relative (see
+  // `resolveRelativeHref`); what's left is hand-written HTML, which a browser
+  // reads this way.
+  const base = `https://blume.invalid${pageUrl}`;
   let resolved: URL;
   try {
     resolved = new URL(target, base);

package/src/blume-modules.d.ts

@@ -18,9 +18,9 @@ declare module "blume:search-client" {
 declare module "blume:ask" {
   /** The generated Ask trigger (see `askComponentTemplate`); empty when Ask is off. */
   // Mirrors the generated `.blume/src/env.d.ts` declaration: the trigger's type
-  // is the AskAI island the enabled template re-exports.
+  // is the Assistant island the enabled template re-exports.
   // oxlint-disable-next-line typescript/consistent-type-imports
-  const Ask: typeof import("./components/islands/AskAI.astro").default;
+  const Ask: typeof import("./components/islands/Assistant.astro").default;
   export default Ask;
 }
 

package/src/cli/command-meta.ts

@@ -53,6 +53,11 @@ export const commandMeta = {
       "Serve an MCP data snapshot over stdio (internal, used by `blume eval`).",
     name: "mcp-stdio",
   },
+  migrate: {
+    description:
+      "Migrate a docs site from Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra with a coding agent.",
+    name: "migrate",
+  },
   preview: {
     description: "Preview the last production build.",
     name: "preview",
@@ -66,6 +71,11 @@ export const commandMeta = {
       "Translate docs into the configured locales with a local agent CLI.",
     name: "translate",
   },
+  upgrade: {
+    description:
+      "Upgrade to this version of Blume: bump the dependency and list the config changes left.",
+    name: "upgrade",
+  },
   validate: {
     description: "Validate internal, anchor, asset, and external links.",
     name: "validate",

package/src/cli/commands/audit.ts

@@ -3,19 +3,21 @@ import { defineCommand } from "citty";
 import {
   AGENTS,
   fixPrompt,
-  launchAgent,
+  launchInstalledAgent,
   writeAgentReport,
 } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
 import { formatCatalog, formatReport, reportJson } from "../../audit/report.ts";
 import { NoBuildError, runAudit } from "../../audit/run.ts";
 import type { AuditResult } from "../../audit/run.ts";
+import { checkTerms, unknownCheckTerms } from "../../audit/terms.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { DiagnosticSeverity } from "../../core/types.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { flushStdout, logger } from "../log.ts";
+import { flushStdout, logger, reportDiagnostics } from "../log.ts";
+import { closestMatch } from "../unknown-flags.ts";
 
 const SEVERITIES: DiagnosticSeverity[] = ["error", "warning", "info"];
 
@@ -31,6 +33,31 @@ const splitTerms = (value: string | undefined): string[] =>
         .filter(Boolean)
     : [];
 
+/**
+ * Exit when `--only`/`--skip` name a check or category that doesn't exist,
+ * suggesting the closest real one — a typo would otherwise filter every
+ * finding out and pass the gate.
+ */
+const rejectUnknownTerms = (terms: string[]): void => {
+  const unknown = unknownCheckTerms(terms);
+  if (unknown.length === 0) {
+    return;
+  }
+  const known = checkTerms();
+  const listed = unknown
+    .map((term) => {
+      const suggestion = closestMatch(term.trim().toLowerCase(), known);
+      return suggestion
+        ? `"${term}" (did you mean "${suggestion}"?)`
+        : `"${term}"`;
+    })
+    .join(", ");
+  logger.error(
+    `--only/--skip name no check or category: ${listed}. Run \`blume audit --list-checks\` for every check id and category.`
+  );
+  process.exit(1);
+};
+
 /** Whether the run should exit non-zero, given the gate. */
 export const shouldFail = (
   result: AuditResult,
@@ -40,31 +67,20 @@ export const shouldFail = (
   return result.diagnostics.some((d) => failing.has(d.severity));
 };
 
-/**
- * Launch the agent CLI, turning a missing executable into the install hint.
- * Only `ENOENT` means "not installed" — any other spawn failure (`EACCES`,
- * `EMFILE`, …) must surface as itself, not be masked by an irrelevant
- * install hint.
- */
+/** Launch the agent CLI, turning a missing executable into the install hint. */
 const launchAgentCode = async (
   agent: AgentKind,
   prompt: string
 ): Promise<number> => {
   const cli = AGENTS[agent];
-  try {
-    return await launchAgent(cli.bin, prompt);
-  } catch (error) {
-    // SAFETY: only the `code` tag is inspected; a spawn failure throws an
-    // ErrnoException, and any other thrown value fails the comparison and
-    // rethrows unchanged.
-    if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
-      throw error;
-    }
+  const code = await launchInstalledAgent(cli.bin, prompt);
+  if (code === null) {
     logger.error(
       `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
     );
     return process.exit(1);
   }
+  return code;
 };
 
 export const auditCommand = defineCommand({
@@ -138,7 +154,7 @@ export const auditCommand = defineCommand({
       (kind) => args[kind]
     );
     if (agents.length > 1) {
-      logger.error("Pass at most one of --claude or --codex.");
+      logger.error("Pass at most one of --codex or --claude.");
       process.exit(1);
     }
     const [agent] = agents;
@@ -146,6 +162,9 @@ export const auditCommand = defineCommand({
       logger.error(`--json and --${agent} are mutually exclusive.`);
       process.exit(1);
     }
+    const only = splitTerms(args.only);
+    const skip = splitTerms(args.skip);
+    rejectUnknownTerms([...only, ...skip]);
     let result: AuditResult;
     try {
       // `scanProject`, not `prepareProject`: the audit reads the *existing*
@@ -154,10 +173,10 @@ export const auditCommand = defineCommand({
       const project = await scanProject(root, { mode: "build" });
       result = await runAudit({
         external: args.external,
-        only: splitTerms(args.only),
+        only,
         origin: args.url,
         project,
-        skip: splitTerms(args.skip),
+        skip,
       });
     } catch (error) {
       if (error instanceof NoBuildError) {
@@ -165,7 +184,7 @@ export const auditCommand = defineCommand({
         process.exit(1);
       }
       if (error instanceof BlumeError) {
-        logger.error(error.diagnostic.message);
+        reportDiagnostics([error.diagnostic], root);
         process.exit(1);
       }
       reportInternalError(error);