blume 1.0.4 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # blume
 
+## 1.1.0
+
+### Minor Changes
+
+- 9fec53f: Add `blume audit`, an offline site audit that replaces a hosted SEO crawler.
+
+  `blume audit` reads the built `dist/` HTML, joins each page back to the `.mdx` it came from, and reports SEO and site-health issues that name **both** the URL that is wrong and the front matter line that fixes it:
+
+  ```
+  ⚠ Meta description too long or too short   5 pages
+      /docs/configuration/export    content/docs/configuration/export.mdx:3
+      fix: Rewrite `description` in the frontmatter to fit the length range.
+  ```
+
+  It runs 87 checks across content, duplicates, indexability, links, redirects, social tags, localization, assets, sitemap, robots.txt, structured data, and AI discovery. Findings are rolled up by check rather than dumped per page, and any tier that didn't run says so. The check set deliberately skips things that can't happen to an Astro-built site (missing hashed bundles, `rel=nofollow`) in favor of checks a crawler can't do — broken `#fragment` anchors, `draft: true` pages that shipped, `llms.txt` held to the sitemap's standard, and Open Graph images verified as bytes.
+
+  Flags:
+
+  - `--url <origin>` also probes a live deployment for what `dist/` can't show (bad rewrites, missing compression, `X-Robots-Tag` deindexing).
+  - `--external` probes outbound links.
+  - `--claude` / `--codex` write the JSON report and open the agent interactively to fix each finding at its source.
+  - `--fail-on <severity>` (default `error`) as the CI gate, plus `--only`/`--skip`, `--json`, `--verbose`, and `--list-checks`.
+
+  `blume validate` is unchanged — it remains the fast source-level link check that needs no build.
+
+### Patch Changes
+
+- 3aee378: Strip trailing slashes from the deploy adapter root with a linear scan instead of a `/\/+$/` regex. The old pattern could backtrack polynomially on a root path containing long runs of `/` (CodeQL `js/polynomial-redos`); the new trim is O(n) and yields the same single-trailing-slash directory URL.
+- f779fd5: Make `blume audit --claude`/`--codex` work on Windows: npm installs the agent CLIs as `.cmd` shims that Node only runs through a shell, and cmd.exe can't carry the multi-line prompt as an argument — the handoff now writes the prompt to a file and launches the shim with a one-line pointer, and a missing executable still gets the install hint instead of a raw ENOENT
+- d99726a: Account for `deployment.base` throughout the audit: link, sitemap, hreflang, llms.txt, asset, and og:image checks now strip the deployment base from emitted URLs before comparing them to the built file tree, instead of reporting every internal link and sitemap entry as broken on subpath deploys
+- d99726a: Make the audit's double-slash check able to fire on the case it was written for: an href like `//docs/x` from a trailing-slash base is now flagged (once per target) instead of being silently skipped as a protocol-relative external link
+- d99726a: Replace a raw NUL byte in the audit's duplicate-content grouping key with the `\u0000` escape, so the shipped source is valid text (git diffed it as binary and grep skipped it)
+- d99726a: Exempt the home page from the audit's orphan-page check when it lives under a `basePath` — `/docs` was reported as an orphan even though `/` never is
+- d99726a: Stop reporting a redirect to a served static file (`/old-whitepaper` → `/files/whitepaper.pdf`) as broken — the audit now resolves redirects against files as well as pages
+- d99726a: Keep a gap between the URL and source-file columns in the audit report when a URL reaches the column width, instead of fusing them into one string
+- d99726a: Fix two robots.txt matching gaps in the audit: `Disallow: /docs*$` now matches everything under `/docs` (the trailing wildcard absorbs the anchor), and trailing-slash rules like `Disallow: /page/` are matched against the sitemap `<loc>` as served instead of a slash-stripped copy
+- d99726a: Only report `ROBOTS_META_UNEXPECTED` when the robots meta actually blocks indexing — a page declaring `index, follow` is no longer claimed to "not be indexed"
+- 8d7e779: Format the changelog timeline's dates in the configured locale. The timeline hardcoded `en`, so an i18n site showed two languages at once: a page's "last updated" stamp honored the locale while `/changelog` stayed English. `/changelog` is an unlocalized route whose chrome already renders in the default locale, so its dates now follow that same locale. English sites are unaffected.
+- d518958: Add `inline` and `param` props to the `Tabs` component. `inline` renders borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. `param` syncs the active tab to a URL query param instead of the hash; because each group owns its own `param`, several `Tabs` can share a page and every selection is deep-linkable (a link ending in `?install=windows` opens on that tab). Existing boxed, hash-synced `Tabs` and `CodeGroup` are unchanged.
+- d9dfdba: Stop shipping underscore-prefixed `.astro` files in `pages/` as routes. Blume injects user pages itself and globbed every `.astro` file, so private partials — shared layouts and home-page sections like `pages/_home/Hero.astro` or `pages/_FeatureBrowser.astro` — were each built into their own HTML page. Page discovery now honors Astro's convention: any file or folder whose name starts with `_` stays importable but is never routed.
+- 437ce03: Fix `blume dev` under pnpm's default isolated linker. The generated runtime now checks Astro through the same physical `node_modules` ancestor lookup used by its ESM config, instead of mistaking pnpm's CommonJS-only `NODE_PATH` exposure for a resolvable `astro/config` import.
+- 9aad3e6: Add `frontmatter.extend`: opt-in custom frontmatter keys, each validated by a user-supplied schema. Page frontmatter stays strictly validated by default; a project can now declare extra keys (e.g. `owner`, `reviewedAt`) in `blume.config.ts`, mapped to schemas consumed through the Standard Schema interface — so Zod (any version the project installs), Valibot, and ArkType all work. Declared keys are validated on every page (mark them `.optional()` to relax), validated values are preserved on each page record's `custom` field, and every other key keeps the strict typo-catching behavior.
+- 368b258: Emit a `_headers` file for static builds so hosts serve the raw AI-ready endpoints with an explicit `charset=utf-8`. Blume's `/<route>.md`, `/<route>.mdx`, and `.txt` outputs (`llms.txt`, `llms-full.txt`) are valid UTF-8, but common static hosts serve them as `text/markdown` / `text/plain` with no charset — so browsers fall back to Windows-1252 and non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. The new `_headers` pins the same `charset=utf-8` Content-Type the dev/server runtime already sends; Netlify and Cloudflare (Pages/Workers static assets) honor it, and hosts that ignore `_headers` (Vercel, S3) are unaffected. The globs carry any `deployment.base`/`basePath` stack, and a `_headers` you ship in `public/` is left untouched — exactly like `_redirects`.
+- d99726a: Prefix the `_headers` `.txt` charset rule with only `deployment.base` — `llms.txt`/`llms-full.txt` are served at the deploy root, so a `basePath` deployment shipped a `/docs/*.txt` rule that matched nothing and left the mojibake fix inert
+- a4453e4: Upgrade Takumi to v2 via takumi-js. Emoji in titles now render as Twemoji glyphs, fetched once per glyph per build. The OG card palette accepts any CSS color, matching `theme.accent` — a color the renderer can't parse now fails the build instead of silently falling back. `renderOgImage` (exported from `blume/og`) now returns a `Uint8Array` rather than a `Buffer`.
+- 548bdd7: Link the RSS feeds from `llms.txt`. The generated index mirrored the docs navigation but never referenced the per-content-type feeds (e.g. `/blog/rss.xml`), so an agent reading `llms.txt` had no pointer to fresh blog posts or changelog entries. The index now closes with an `## RSS Feeds` section listing each configured feed that has pages, under the same condition the feeds themselves exist — RSS enabled and an absolute `deployment.site` — and carrying any `deployment.base` subpath. This mirrors the `artifacts.feeds` list already emitted in `agent-readability.json`.
+- d99726a: Fix a data-loss bug in the blume-migrate Mintlify codemod: renaming a key into a parent block that appears earlier in the frontmatter (e.g. `canonical` into an existing `seo:`) deleted the wrong line and left the source key behind; icon remaps also now preserve trailing comments, and the skill references no longer document the pre-1.0.3 top-level `mcp` config
+- 8769dd1: Add `seo.og.fonts` to load Google Font families into the Open Graph card renderer. Takumi's built-in font covers only Latin, so a non-Latin page or site title (CJK, and so on) rendered as tofu with no way to fix it. List the families by name — bare strings, or `{ name, weight, style }` for weight/style — and Blume fetches them from Google Fonts at build via Takumi's `googleFonts` helper, registering only the glyph subsets each title uses. Latin text renders unchanged.
+- d99726a: Add `seo.og.fonts` to the `OgConfig` authoring type — the schema accepted it but TypeScript rejected it in `blume.config.ts`, making the documented CJK/tofu fix untypeable — and correct the palette doc comment to say any CSS color works, not just hex
+- de6403c: Fix the OG image build failing with "Cannot find native binding" on Vercel (Linux). The `googleFonts` OG-font loader is imported from `takumi-js/helpers`, but only the bare `takumi-js` was externalized for the static-prerender Vite environment — which matches by exact specifier, so the subpath (and the native `@takumi-rs/core` backend it pulls in) got bundled into the prerender chunk, relocating the `.node` binding lookup. Externalize `takumi-js/helpers` and the `@takumi-rs/*` packages so the native backend always resolves from `node_modules` at runtime.
+- bb9737e: Render authentication requirements in the native OpenAPI reference. Operations that declare security requirements — their own `security`, or the document's root default — now show an **Authorization** section above their parameters: the credential's carrier (`Authorization` header, API-key header/query/cookie), a human label per scheme type (Bearer token, Basic auth, API key, OAuth2, OpenID Connect, Mutual TLS), the scheme's description, and OAuth scopes. Multiple requirement alternatives render as "or" groups (schemes within one requirement are required together), an empty `{}` requirement marks auth as optional, and `security: []` on an operation keeps it public with no section. The generated code samples now send a matching placeholder credential (e.g. `-H "Authorization: Bearer YOUR_TOKEN"`), with a spec-declared explicit header parameter still taking precedence, and a query-borne API key appended to the sample URL. Previously the renderer ignored `security` entirely, so authenticated endpoints were indistinguishable from public ones.
+- d99726a: Align the accessible heading level of the Authorization and Parameters sections with Request body and Responses on API reference operation pages
+- d99726a: Stop duplicating a query API key in request samples when the spec also declares the credential as an explicit query parameter — the parameter's own example now wins, matching the header behavior
+- e6be2f6: Match unordered-list bullets to ordered-list numbers in prose. `--tw-prose-bullets` now defaults to `--blume-muted-foreground` (like `--tw-prose-counters`) instead of `--blume-border`, which rendered bullets much lighter than the numbers beside them.
+- d99726a: Normalize `deployment.base` before composing it into redirect targets — a trailing-slash (`/base/`) or bare (`base`) value produced `/base//new` or relative destinations in Astro redirects and the platform redirect files
+- 93ea41b: Fix redirects escaping the site under `deployment.base`. A redirect's `to` was only ever rewritten with `basePath`, never with the deployment base, so with `base: "/docs"` a `to: "/new"` emitted a redirect to `/new` — outside the base, 404ing on a subpath deploy (GitHub Pages project sites, most commonly) with no build-time error. Astro applies `base` when it builds the match pattern for `from`, but resolves a destination either by regenerating it from a matching route's segments (which carry no base) or by passing it through verbatim — neither prepends `base`, so Blume now applies it to `to` itself. The two bases also compose correctly: `deployment.base` and `basePath` set together stack as `{base}/{basePath}`, which the old front-prepend could not produce in that order.
+
+  The static host redirect files (`_redirects`, `vercel.json`, `blume-redirects.json`) had the mirror-image bug on the other side: they are matched against the real served URL, but `from` was written without the deployment base, so it never matched. Both sides now carry the full stack. Redirects are authored root-relative in every case, and a base already written into `to` by hand is preserved rather than doubled.
+
+- d99726a: Warn when a `search.popular` link uses an image or inline-SVG icon — the client search island can only render built-in icon names, and the silent fallback to the file glyph was exactly what the validator was meant to catch
+- 1c18379: Add `search.popular` to curate the Cmd+K empty-state link list. When set, each `{ href, label, icon? }` entry replaces the default first-six sidebar pages — useful on multi-tab sites where sidebar order surfaces the wrong section. Each `href` is authored root-relative and picks up `basePath` automatically (external URLs pass through); `icon` takes a built-in icon name and defaults to a file glyph. Omit or leave empty to keep the sidebar fallback.
+- ea4c560: Stop headings inside a `<Prompt>` block from leaking into the page's table of contents. `Prompt.astro` renders its children into a permanently `hidden` node (used only to build the copy-to-clipboard and Cursor-deeplink text), but `extractHeadings` had no way to know that — any `##` inside a `<Prompt>` was extracted as a real page heading and appeared in the "On this page" sidebar, linking to content that never renders visibly. Heading extraction now tracks `<Prompt>`/`</Prompt>` nesting depth the same way fenced code blocks already are, and skips headings while inside one. Tag detection is anchored to line starts — block-level JSX in MDX starts its own line — so a prose or heading mention of `<Prompt>` never opens a hidden region, and a tag whose attributes span several lines only counts once its closing `>` shows it isn't self-closing.
+- c6ca54a: Add a themeable content-column width. A new `--blume-content-width` token (default `42rem`) is exposed as a `max-w-content` utility through Tailwind's `--container-content` theme key, and the article, breadcrumb, mobile table of contents, page feedback, pagination, and last-updated line now use it instead of hardcoding `42rem`. Override `--blume-content-width` to re-measure the whole column at once; the default is unchanged.
+- 31ee259: Bundle the Vercel serverless function with its chunks, virtual middleware, and dependencies. With `deployment.output: "server"` and `adapter: "vercel"`, the render function (`.vercel/output/functions/_render.func`) shipped as `entry.mjs` alone, so any server-rendered request — the Docs MCP endpoint, Ask AI — 500'd at runtime with `ERR_MODULE_NOT_FOUND`. The adapter resolves both its Build Output tree and its `@vercel/nft` dependency trace against Astro's `root`, which Blume points at the hidden `.blume` runtime; the trace's base then excluded the server bundle (which lives under `outDir`, outside `.blume`) and collapsed to a single file. The adapter is now shown the real project root, so the trace covers the function's chunks and `node_modules` and the output lands at the project root natively. Projects inside a workspace were unaffected — nft's base search climbed past `.blume` to the workspace root — so this only ever broke standalone projects.
+
 ## 1.0.4
 
 ### Patch Changes