blume 1.0.4 → 1.1.1

package/src/astro/templates.ts

@@ -10,7 +10,7 @@ import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
-import { applyBaseToRedirects } from "../deploy/redirects.ts";
+import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries } from "../theme/fonts.ts";
@@ -166,11 +166,16 @@ export const runtimeDependencies = (options: {
  * static-prerender Vite environments.
  *
  * Two reasons a dep lands here:
- *   - `@takumi-rs/core` (OG image rendering) is a native NAPI addon that loads a
- *     platform-specific `.node` binding via `createRequire(import.meta.url)`.
- *     Bundling it relocates `import.meta.url` and breaks the binding lookup
- *     ("Cannot find native binding") on other platforms (e.g. the Linux CI
- *     runner), so it must resolve from `node_modules` at runtime instead.
+ *   - `takumi-js` (OG image rendering) loads `@takumi-rs/core`, a native NAPI
+ *     addon that finds its platform-specific `.node` binding via
+ *     `createRequire(import.meta.url)`. Bundling it relocates `import.meta.url`
+ *     and breaks the binding lookup ("Cannot find native binding") on other
+ *     platforms (e.g. the Linux CI runner), so it must resolve from
+ *     `node_modules` at runtime instead. The prerender env matches these by
+ *     exact specifier, so every entry point Blume imports has to be listed:
+ *     the bare `takumi-js` (render) plus `takumi-js/helpers` (the `googleFonts`
+ *     OG-font loader). The `@takumi-rs/*` packages are listed too so the native
+ *     backend is never pulled into a chunk down any transitive path.
  *   - The rest are pure-JS packages kept external so an isolated linker (Bun's
  *     `isolated` mode, pnpm) doesn't bundle their symlinked store copies. When
  *     Vite bundles such a package but leaves its own `node_modules` child
@@ -190,10 +195,13 @@ const RENDER_EXTERNAL_DEPS = [
   "@shikijs/transformers",
   "@takumi-rs/core",
   "@takumi-rs/helpers",
+  "@takumi-rs/wasm",
   "github-slugger",
   "katex",
   "shiki",
   "simple-icons",
+  "takumi-js",
+  "takumi-js/helpers",
   "zod",
 ];
 
@@ -212,6 +220,21 @@ const renderUserAliases = (
 const astroOutDir = (context: ProjectContext): string =>
   context.distDir ?? `${context.root}/dist`;
 
+/**
+ * The root a deploy adapter is shown, in place of the `.blume` runtime Astro
+ * actually roots at. Adapters assume `outDir` is `<root>/dist` and resolve their
+ * own output (and Vercel's dependency trace) against `root`, so the root implied
+ * by Blume's `outDir` is the one that keeps that assumption true. See
+ * {@link withAdapterRoot}.
+ *
+ * For a normal build that is the project root (`<project>/dist` -> `<project>`).
+ * For a relocated runtime (`blume build --isolated`) it is the runtime dir
+ * itself (`<runtime>/dist` -> `<runtime>`), keeping a verify build's adapter
+ * output self-contained instead of overwriting the real `.vercel/output`.
+ */
+const adapterRoot = (context: ProjectContext): string =>
+  dirname(astroOutDir(context));
+
 /**
  * Excludes Vite's pre-bundled dep cache from @vitejs/plugin-react. Astro's
  * react() replaces the plugin's default `/node_modules/` exclude with just
@@ -296,8 +319,17 @@ export const astroConfigTemplate = (options: {
     }
     return ADAPTER_OPTIONS[deployment.adapter] ?? "";
   })();
+  // Vercel resolves its Build Output tree and its `@vercel/nft` dependency
+  // trace against the Astro root, which for Blume is the hidden `.blume`
+  // runtime — leaving the traced function without its chunks or node_modules.
+  // The other adapters emit into `outDir` (cloudflare, node) or are surfaced
+  // afterwards (netlify), so none of them read `root` this way.
+  const adapterExpr =
+    deployment.adapter === "vercel"
+      ? `withAdapterRoot(adapter(${adapterArgs}), ${JSON.stringify(adapterRoot(context))})`
+      : `adapter(${adapterArgs})`;
   const adapterOption =
-    server && deployment.adapter ? `\n  adapter: adapter(${adapterArgs}),` : "";
+    server && deployment.adapter ? `\n  adapter: ${adapterExpr},` : "";
 
   const siteOption = deployment.site
     ? `\n  site: ${JSON.stringify(deployment.site)},`
@@ -320,10 +352,12 @@ export const astroConfigTemplate = (options: {
     : "";
 
   // Base the redirect paths the same way routes are based, so a redirect lands
-  // under `basePath` too. Astro layers its own `base` (deployment.base) on top.
-  const basedRedirects = applyBaseToRedirects(
+  // under `basePath` too. Astro layers its own `base` (deployment.base) onto
+  // `from` when matching, but never onto `to` — see applyBaseToAstroRedirects.
+  const basedRedirects = applyBaseToAstroRedirects(
     config.redirects,
-    config.basePath
+    config.basePath,
+    deployment.base ?? ""
   );
   const redirectsOption =
     basedRedirects.length > 0
@@ -365,14 +399,21 @@ export const astroConfigTemplate = (options: {
   const svelteImport = needsSvelte
     ? `import svelte from "@astrojs/svelte";\n`
     : "";
-  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin, serverAppResolvePlugin } from "blume/astro";\n`;
+  const blumeImports = [
+    "blumeIntegration",
+    "prerenderDepsPlugin",
+    "serverAppResolvePlugin",
+    ...(adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []),
+  ];
+  const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";\n`;
 
   // Twoslash runs first, before the always-on transformers, but only on fences
   // with the `twoslash` meta (explicitTrigger) — so it's opt-in per block with
   // no config flag; the TypeScript compiler only spins up when a block uses it.
-  const twoslashImport = `import { transformerTwoslash } from "@shikijs/twoslash";\n`;
-  const twoslashTransformer =
-    "transformerTwoslash({ explicitTrigger: true }), ";
+  // Blume's preconfigured transformer compiles with the package's own pinned
+  // classic TypeScript, so the user's project can be on any version (see
+  // markdown/twoslash.ts).
+  const twoslashTransformer = "blumeTwoslashTransformer(), ";
 
   // Content links are rewritten to their real served URL: the `deployment.base`
   // subdirectory (Astro doesn't rewrite `<a href>`) layered over the site-wide
@@ -409,8 +450,8 @@ export const astroConfigTemplate = (options: {
 ${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
-import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers } from "blume/markdown";
-${twoslashImport}${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
+import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
+${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
 export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
@@ -1037,7 +1078,9 @@ import data from "blume:data";
 export const prerender = true;
 
 // Custom (non-content) pages opted into a generated card, baked in at build.
-const customRoutes = ${JSON.stringify(customRoutes)};
+// The annotation keeps the empty-array case from being an implicit any[]
+// (ts(7034)) under a strict tsconfig.
+const customRoutes: { slug: string; title: string }[] = ${JSON.stringify(customRoutes)};
 
 export function getStaticPaths() {
   const seen = new Set<string>();
@@ -1080,6 +1123,7 @@ export async function GET({ props }: { props: { title: string } }) {
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
     description: data.config.description,
+    fonts: data.config.og.fonts,
     logo: data.config.og.logo,
     palette: data.config.og.palette,
     repo: repoSlug,
@@ -1475,6 +1519,18 @@ const toTime = (value: string | null | undefined) => {
   return Number.isNaN(date.getTime()) ? 0 : date.getTime();
 };
 
+// The changelog is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
+
+// Formatted in the same locale as the chrome, and in UTC, to match the
+// per-page "last updated" stamp.
 const formatDate = (value: string | null | undefined) => {
   if (!value) {
     return;
@@ -1482,7 +1538,7 @@ const formatDate = (value: string | null | undefined) => {
   const date = new Date(value);
   return Number.isNaN(date.getTime())
     ? undefined
-    : new Intl.DateTimeFormat("en", {
+    : new Intl.DateTimeFormat(htmlLang, {
         dateStyle: "long",
         timeZone: "UTC",
       }).format(date);
@@ -1579,16 +1635,6 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const basedRoute = withBase("/changelog");
 const canonical = base ? base + basedRoute : null;
 
-// The changelog is an unlocalized route, so its chrome renders in the default
-// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
-// dictionary), mirroring the catch-all's locale wiring.
-const i18n = data.config.i18n;
-const localeMeta = i18n
-  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
-  : null;
-const dir = localeMeta?.dir ?? "ltr";
-const htmlLang = i18n ? i18n.defaultLocale : "en";
-
 // The page chrome (h1, title, description) comes from the same translatable
 // \`changelog\` group as the reveal button; optional chaining tolerates a
 // not-yet-regenerated data snapshot from before these keys existed.
@@ -1760,6 +1806,23 @@ const islandDirective = (spec: IslandSpec): string =>
     ? `client:only="${spec.framework}"`
     : `client:${spec.client}`;
 
+/**
+ * Frontmatter `Props` alias mirroring the wrapped component's own props, so
+ * `{...Astro.props}` satisfies required props under `astro check` (the spread
+ * of an untyped `Astro.props` contributes nothing to the JSX props type).
+ * `infer P extends object` rather than `Record<string, unknown>` because
+ * interfaces have no implicit index signature and would miss the narrower
+ * constraint. Non-function component types (Vue/Svelte ambient modules) fall
+ * back to an open record, keeping the untyped permissiveness they had.
+ */
+const wrapperPropsType = (name: string): string =>
+  `type Props = typeof ${name} extends (
+  props: infer P extends object,
+  ...rest: never[]
+) => unknown
+  ? P
+  : Record<string, unknown>;`;
+
 /**
  * Generate `.blume/src/generated/islands/<Name>.astro` — a wrapper that renders
  * a convention island with its hydration directive applied. Astro client
@@ -1770,6 +1833,7 @@ export const islandWrapperTemplate = (spec: IslandSpec): string =>
   `---
 // Generated by Blume. Do not edit.
 import Island from ${JSON.stringify(spec.file)};
+${wrapperPropsType("Island")}
 ---
 <Island ${islandDirective(spec)} {...Astro.props}><slot /></Island>
 `;
@@ -1832,6 +1896,7 @@ export const exampleWrapperTemplate = (spec: ExampleSpec): string =>
   `---
 // Generated by Blume. Do not edit.
 import Example from ${JSON.stringify(spec.file)};
+${wrapperPropsType("Example")}
 ---
 <Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>
 `;

package/src/audit/agent.ts

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+import { join } from "pathe";
+
+import { reportJson } from "./report.ts";
+import type { AuditResult } from "./run.ts";
+
+/** A coding agent CLI the audit can hand its findings to (`--claude`, `--codex`). */
+export interface AgentCli {
+  /** The executable to look up on PATH. */
+  bin: string;
+  /** How to install it, shown when the executable is missing. */
+  install: string;
+  /** Display name for messages. */
+  name: string;
+}
+
+export type AgentKind = "claude" | "codex";
+
+export const AGENTS: Record<AgentKind, AgentCli> = {
+  claude: {
+    bin: "claude",
+    install: "npm install -g @anthropic-ai/claude-code",
+    name: "Claude Code",
+  },
+  codex: {
+    bin: "codex",
+    install: "npm install -g @openai/codex",
+    name: "Codex",
+  },
+};
+
+/**
+ * Write the full JSON report where the agent can read it. A file rather than
+ * inline prompt text: a large site's report can exceed the platform's argv
+ * limit, and the JSON already carries every finding untruncated — the terminal
+ * report previews three pages per check, the file never does.
+ */
+export const writeAgentReport = async (
+  result: AuditResult,
+  root: string
+): Promise<string> => {
+  const dir = await mkdtemp(join(tmpdir(), "blume-audit-"));
+  const path = join(dir, "report.json");
+  await writeFile(path, reportJson(result, root));
+  return path;
+};
+
+/** The handoff prompt: where the report is, how to read it, and the ground rules. */
+export const fixPrompt = (reportPath: string): string =>
+  `Fix the issues found by \`blume audit\` in this project.
+
+The full audit report is at ${reportPath}. It is JSON: each entry in \`diagnostics\` is one finding, with the check \`code\`, a \`message\` explaining what is wrong, the affected page \`url\`, the source \`file\` to edit (relative to the current directory, with a \`line\` when the finding points at a specific front matter key), and a \`suggestion\` describing the fix.
+
+Work through every finding:
+1. Read the report and group the findings by \`file\`.
+2. Apply each finding's \`suggestion\` by editing the named source file — most fixes are front matter edits at the cited line.
+3. Never fix a finding by deleting a page, removing content, or hiding it from the audit; if a finding genuinely needs a human decision, leave it and say so in your summary.
+
+When you are done, run \`blume build\` and then \`blume audit\` to verify, and repeat until the audit reports no issues.`;
+
+const spawnAgent = (
+  command: string,
+  args: string[],
+  shell: boolean
+): Promise<number> =>
+  // oxlint-disable-next-line promise/avoid-new -- adapt spawn's event callbacks
+  new Promise((resolve, reject) => {
+    const child = spawn(command, args, { shell, stdio: "inherit" });
+    child.once("error", reject);
+    child.once("close", (code) => resolve(code ?? 1));
+  });
+
+/**
+ * cmd.exe reports a missing executable through this exit code instead of a
+ * spawn error, so a shell launch can't rely on the `error` event for the
+ * "not installed" diagnosis.
+ */
+export const WINDOWS_COMMAND_NOT_FOUND = 9009;
+
+/**
+ * Run the agent CLI interactively with the handoff prompt, inheriting the
+ * terminal so the user watches and steers the fixes rather than granting a
+ * headless process blanket write access. Resolves with the agent's exit code;
+ * rejects when the executable isn't on PATH.
+ *
+ * On Windows, npm installs agent CLIs as `.cmd` shims, which Node refuses to
+ * spawn without a shell — and cmd.exe cannot carry the multi-line prompt as an
+ * argument (a newline ends the command). So there the prompt is written to a
+ * file next to the report and handed over via a one-line pointer that survives
+ * cmd.exe quoting; a missing executable surfaces as
+ * {@link WINDOWS_COMMAND_NOT_FOUND} rather than a rejection.
+ */
+export const launchAgent = async (
+  bin: string,
+  prompt: string,
+  platform: NodeJS.Platform = process.platform
+): Promise<number> => {
+  if (platform !== "win32") {
+    return await spawnAgent(bin, [prompt], false);
+  }
+  const dir = await mkdtemp(join(tmpdir(), "blume-audit-"));
+  const promptPath = join(dir, "prompt.md");
+  await writeFile(promptPath, prompt);
+  // Double quotes are the one grouping cmd.exe respects; neither the temp
+  // path nor the fixed pointer text can contain one.
+  return await spawnAgent(
+    `"${bin}" "Read ${promptPath} and follow its instructions exactly."`,
+    [],
+    true
+  );
+};