blume 1.3.1 → 1.4.0

package/src/cli/commands/translate.ts

@@ -0,0 +1,300 @@
+import { defineCommand } from "citty";
+
+import { AGENTS } from "../../audit/agent.ts";
+import type { AgentKind } from "../../audit/agent.ts";
+import { BlumeError } from "../../core/diagnostics.ts";
+import { i18nEnabled, localeCodes } from "../../core/i18n.ts";
+import { scanProject } from "../../core/project-graph.ts";
+import type { ResolvedI18nConfig } from "../../core/schema.ts";
+import { DEFAULT_TRANSLATE_TIMEOUT_MS } from "../../translate/agents.ts";
+import {
+  pruneLedger,
+  readLedger,
+  stampLedger,
+  writeLedger,
+} from "../../translate/ledger.ts";
+import {
+  checkLines,
+  checkReportJson,
+  checkSummaryLine,
+  createProgressRenderer,
+  diagnosticLines,
+  hasDrift,
+  translateHeaderLine,
+  translateReportJson,
+  translateSummaryLine,
+} from "../../translate/report.ts";
+import { runTranslate } from "../../translate/run.ts";
+import { computeWorkList } from "../../translate/work-list.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { flushStdout, logger } from "../log.ts";
+
+/** Wall-clock ceiling per file, in seconds. */
+const DEFAULT_TIMEOUT_S = DEFAULT_TRANSLATE_TIMEOUT_MS / 1000;
+
+/** Parallel agent sessions per run; each one is a full agent process. */
+const DEFAULT_CONCURRENCY = 4;
+const MAX_CONCURRENCY = 16;
+
+interface TranslateFlags {
+  check?: boolean;
+  claude?: boolean;
+  codex?: boolean;
+  concurrency?: string;
+  force?: boolean;
+  json?: boolean;
+  locale?: string;
+  timeout?: string;
+}
+
+/** Validate the flag surface, exiting with a message on the first offense. */
+const parseFlags = (
+  args: TranslateFlags
+): { agent: AgentKind | undefined; concurrency: number; timeoutS: number } => {
+  const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
+    (kind) => args[kind]
+  );
+  if (agents.length > 1) {
+    logger.error("Pass exactly one of --claude or --codex.");
+    process.exit(1);
+  }
+  if (args.check && agents.length > 0) {
+    logger.error(
+      "--check is read-only and never runs an agent; drop --claude/--codex."
+    );
+    process.exit(1);
+  }
+  if (!args.check && agents.length === 0) {
+    logger.error(
+      "Pass --claude or --codex to choose the agent CLI that translates."
+    );
+    process.exit(1);
+  }
+  const timeoutS =
+    args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
+  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
+    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
+    process.exit(1);
+  }
+  const concurrency =
+    args.concurrency === undefined
+      ? DEFAULT_CONCURRENCY
+      : Number(args.concurrency);
+  if (
+    !Number.isInteger(concurrency) ||
+    concurrency < 1 ||
+    concurrency > MAX_CONCURRENCY
+  ) {
+    logger.error(
+      `Invalid --concurrency "${args.concurrency}" (use 1..${MAX_CONCURRENCY}).`
+    );
+    process.exit(1);
+  }
+  return { agent: agents[0], concurrency, timeoutS };
+};
+
+/**
+ * Resolve `--locale` against the configured locales: comma-separated,
+ * case-insensitive, adopting the configured casing. Unknown codes and the
+ * default locale (the translation source) are errors.
+ */
+const parseLocales = (
+  value: string | undefined,
+  i18n: ResolvedI18nConfig
+): string[] | undefined => {
+  if (value === undefined) {
+    return;
+  }
+  const configured = new Map(
+    i18n.locales.map((locale) => [locale.code.toLowerCase(), locale.code])
+  );
+  const resolved: string[] = [];
+  for (const part of value.split(",")) {
+    const code = configured.get(part.trim().toLowerCase());
+    if (code === undefined) {
+      logger.error(
+        `Unknown --locale "${part.trim()}" (configured: ${localeCodes(i18n).join(", ")}).`
+      );
+      process.exit(1);
+    }
+    if (code === i18n.defaultLocale) {
+      logger.error(
+        `--locale "${code}" is the default locale — it is the translation source, not a target.`
+      );
+      process.exit(1);
+    }
+    resolved.push(code);
+  }
+  return resolved;
+};
+
+const notInstalled = (agent: AgentKind): never => {
+  const cli = AGENTS[agent];
+  logger.error(
+    `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+  );
+  return process.exit(1);
+};
+
+export const translateCommand = defineCommand({
+  args: {
+    check: {
+      description:
+        "Report missing/stale translations without writing anything; exits 1 on drift (for CI).",
+      type: "boolean",
+    },
+    claude: {
+      description: "Translate with Claude Code.",
+      type: "boolean",
+    },
+    codex: {
+      description: "Translate with Codex.",
+      type: "boolean",
+    },
+    concurrency: {
+      description: `Parallel agent sessions. Defaults to ${DEFAULT_CONCURRENCY}, max ${MAX_CONCURRENCY}.`,
+      type: "string",
+    },
+    force: {
+      description:
+        "Retranslate everything, up-to-date and hand-authored files included.",
+      type: "boolean",
+    },
+    json: {
+      description: "Emit the report as JSON on stdout (for CI/editors).",
+      type: "boolean",
+    },
+    locale: {
+      description:
+        "Comma-separated target locale codes; defaults to every non-default locale.",
+      type: "string",
+    },
+    timeout: {
+      description: `Agent time limit per file, in seconds. Defaults to ${DEFAULT_TIMEOUT_S}.`,
+      type: "string",
+    },
+  },
+  meta: {
+    description:
+      "Translate docs into the configured locales with a local agent CLI.",
+    name: "translate",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const { agent, concurrency, timeoutS } = parseFlags(args);
+
+    try {
+      // `scanProject`, not `prepareProject`: translation reads the content
+      // tree and writes source files, never `.blume/`, so it doesn't contend
+      // with a running dev server. Same reasoning as `blume audit`/`eval`.
+      const project = await scanProject(root, { mode: "build" });
+      if (!i18nEnabled(project.config)) {
+        logger.error(
+          "i18n is not configured — add `i18n.locales` to blume.config to use `blume translate`."
+        );
+        process.exit(1);
+      }
+      const { i18n } = project.config;
+      if (localeCodes(i18n).every((code) => code === i18n.defaultLocale)) {
+        logger.error(
+          "i18n.locales has no locale besides the default — nothing to translate into."
+        );
+        process.exit(1);
+      }
+      const locales = parseLocales(args.locale, i18n);
+      const ledger = await readLedger(root);
+      const workList = await computeWorkList(project, ledger, {
+        force: !args.check && Boolean(args.force),
+        locales,
+      });
+
+      if (args.check) {
+        const lines = [
+          ...diagnosticLines(workList.diagnostics),
+          ...checkLines(workList),
+          "",
+          `  ${checkSummaryLine(workList)}`,
+          "",
+        ];
+        process.stderr.write(`${lines.join("\n")}\n`);
+        if (args.json) {
+          process.stdout.write(checkReportJson(workList));
+        }
+        if (hasDrift(workList)) {
+          await flushStdout();
+          process.exit(1);
+        }
+        return;
+      }
+
+      const kind = agent as AgentKind;
+      process.stderr.write(
+        `${translateHeaderLine(workList.items.length, workList.targetLocales.length, kind)}\n\n`
+      );
+
+      // Adopt pre-existing hand-authored translations (stamp, never rewrite)
+      // and persist BEFORE the agents run, so adoption survives an interrupt.
+      for (const entry of workList.untracked) {
+        stampLedger(ledger, entry.sourceRel, entry.locale, entry.hash);
+      }
+      await writeLedger(root, ledger);
+
+      const renderer = createProgressRenderer({
+        isTTY: process.stderr.isTTY === true,
+        write: (chunk) => process.stderr.write(chunk),
+      });
+      const result = await runTranslate({
+        agent: kind,
+        concurrency,
+        ledger,
+        onProgress: (event) => renderer.onProgress(event),
+        // Flush after every finished item, so stopping a long run mid-way
+        // keeps everything already translated out of the next work list.
+        persistLedger: () => writeLedger(root, ledger),
+        project,
+        timeoutMs: timeoutS * 1000,
+        workList,
+      });
+      renderer.stop();
+
+      // Prune entries whose source or locale no longer exists. Pruning spans
+      // ALL non-default locales — a `--locale fr` run must not drop the other
+      // locales' stamps.
+      const knownLocales = new Set(
+        localeCodes(i18n).filter((code) => code !== i18n.defaultLocale)
+      );
+      await writeLedger(
+        root,
+        pruneLedger(ledger, workList.knownSources, knownLocales)
+      );
+
+      const tail = [
+        "",
+        ...diagnosticLines(workList.diagnostics),
+        `  ${translateSummaryLine(result, workList)}`,
+        "",
+      ];
+      process.stderr.write(tail.join("\n"));
+
+      if (args.json) {
+        process.stdout.write(translateReportJson(result, workList));
+      }
+      if (result.counts.failed > 0 || result.counts.partial > 0) {
+        // The ledger write above already persisted every success, so a failed
+        // rerun only retries what actually failed.
+        await flushStdout();
+        process.exit(1);
+      }
+    } catch (error) {
+      if (error instanceof BlumeError) {
+        logger.error(error.diagnostic.message);
+        process.exit(1);
+      }
+      if ((error as NodeJS.ErrnoException)?.code === "ENOENT" && agent) {
+        notInstalled(agent);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+  },
+});

package/src/cli/index.ts

@@ -13,6 +13,7 @@ import { initCommand } from "./commands/init.ts";
 import { mcpStdioCommand } from "./commands/mcp-stdio.ts";
 import { previewCommand } from "./commands/preview.ts";
 import { syncCommand } from "./commands/sync.ts";
+import { translateCommand } from "./commands/translate.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { loadEnvFiles } from "./env.ts";
 import { reportInternalError } from "./internal-error.ts";
@@ -36,6 +37,7 @@ const main = defineCommand({
     "mcp-stdio": mcpStdioCommand,
     preview: previewCommand,
     sync: syncCommand,
+    translate: translateCommand,
     validate: validateCommand,
   },
 });

package/src/components/Icon.astro

@@ -1,4 +1,5 @@
 ---
+import { isImageIcon, isInlineSvg } from "../theme/icon-kind.ts";
 import { resolveIcon } from "../theme/icons.ts";
 import { withBase } from "./islands/base-path.ts";
 
@@ -27,13 +28,7 @@ const customIcon =
     ? rawIcon
     : null;
 const iconName = typeof rawIcon === "string" ? rawIcon : null;
-const rawSvg =
-  iconName && /^\s*<svg[\s\S]*<\/svg>\s*$/u.test(iconName)
-    ? iconName.trim()
-    : null;
-const isImageIcon = (value: string): boolean =>
-  /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)/u.test(value) ||
-  /\.(?:avif|gif|jpe?g|png|svg|webp)$/iu.test(value);
+const rawSvg = iconName && isInlineSvg(iconName) ? iconName.trim() : null;
 const imageSrc = iconName && !rawSvg && isImageIcon(iconName) ? iconName : null;
 const resolvedIcon =
   iconName && !(imageSrc || rawSvg) ? resolveIcon(iconName) : null;

package/src/components/content/Step.astro

@@ -1,6 +1,7 @@
 ---
-import Icon from "../Icon.astro";
+import { isAssetIcon } from "../../theme/icon-kind.ts";
 import { hasIcon } from "../../theme/icons.ts";
+import Icon from "../Icon.astro";
 
 interface Props {
   icon?: string;
@@ -10,14 +11,8 @@ interface Props {
 const { icon, title } = Astro.props;
 const markerClass =
   "absolute top-0 -start-[2.75rem] flex size-6 items-center justify-center rounded-full bg-accent text-center font-semibold text-accent-foreground text-xs";
-const isImageIcon = (value: string): boolean =>
-  /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)/u.test(value) ||
-  /\.(?:avif|gif|jpe?g|png|svg|webp)$/iu.test(value);
 const canRenderIcon =
-  icon !== undefined &&
-  (/^\s*<svg[\s\S]*<\/svg>\s*$/u.test(icon) ||
-    isImageIcon(icon) ||
-    hasIcon(icon));
+  icon !== undefined && (isAssetIcon(icon) || hasIcon(icon));
 ---
 
 <div

package/src/components/content/Tab.astro

@@ -21,9 +21,28 @@ const slugify = (value: string): string =>
 const tabId = id ?? slugify(title);
 ---
 
+{/*
+  Drop the inset only when the panel is *nothing but* code fences: a fence owns
+  its own frame, so a code-only panel would double-inset it. A panel holding a
+  fence AND prose is real prose content and keeps the inset, matching every
+  other code-block host (CodeGroup, Steps, Callout, Card, Accordion) — see the
+  scroll-container note in theme/entry.ts. Previously the bare `:has(>pre)`
+  also matched mixed panels, stripping padding from the prose too; with
+  `[&>:last-child]:mb-0!` a trailing paragraph sat flush against the border.
+
+  The `template` exclusion is load-bearing, not defensive: when `icon` is set
+  this component renders a `<template data-blume-tab-icon>` that stays a
+  permanent child, because the tabs script *clones* its content into the
+  trigger (`icon.content.cloneNode(true)`) rather than moving the node. So the
+  panel legitimately has a non-`pre` child even when it is code-only, and
+  `:has(>pre:only-child)` would stop matching every icon tab — restoring the
+  double inset. `:only-of-type` survives the single-fence case but breaks a
+  code-only panel holding two fences. Excluding `template` handles both. Do
+  not "simplify" this to those.
+*/}
 <div
   class:list={[
-    "px-4 py-3 [&:has(>pre)]:p-0 [&>:first-child]:mt-0! [&>:last-child]:mb-0!",
+    "px-4 py-3 [&:has(>pre):not(:has(>:not(pre,template)))]:p-0 [&>:first-child]:mt-0! [&>:last-child]:mb-0!",
     className,
   ]}
   data-blume-tab-panel

package/src/components/layout/LanguageSwitcher.astro

@@ -26,7 +26,8 @@ const menuRowClass =
         class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
       >
         <Icon name="globe" size={16} />
-        <span class="max-sm:hidden">{current?.label ?? label}</span>
+        {/* Collapses to the globe icon below `lg`, matching the search field. */}
+        <span class="max-lg:hidden">{current?.label ?? label}</span>
         <Icon
           class="transition-transform group-open:rotate-180"
           name="chevron-down"

package/src/components/layout/Logo.astro

@@ -36,7 +36,7 @@ const brandText = logo?.text ?? site.title;
     logoSvg && (
       <span
         aria-hidden="true"
-        class="inline-flex h-5 items-center [&>svg]:h-5 [&>svg]:w-auto"
+        class="inline-flex h-5 shrink-0 items-center [&>svg]:h-5 [&>svg]:w-auto"
         set:html={logoSvg}
       />
     )
@@ -47,7 +47,7 @@ const brandText = logo?.text ?? site.title;
       (logoLight === logoDark ? (
         <img
           alt={logoAlt}
-          class="h-5 w-auto"
+          class="h-5 w-auto shrink-0"
           height={logoLightDimensions?.height}
           src={withBase(logoLight)}
           width={logoLightDimensions?.width}
@@ -56,14 +56,14 @@ const brandText = logo?.text ?? site.title;
         <>
           <img
             alt={logoAlt}
-            class="h-5 w-auto dark:hidden"
+            class="h-5 w-auto shrink-0 dark:hidden"
             height={logoLightDimensions?.height}
             src={withBase(logoLight)}
             width={logoLightDimensions?.width}
           />
           <img
             alt={logoAlt}
-            class="hidden h-5 w-auto dark:block"
+            class="hidden h-5 w-auto shrink-0 dark:block"
             height={logoDarkDimensions?.height}
             src={withBase(logoDark)}
             width={logoDarkDimensions?.width}

package/src/components/layout/PageActions.astro

@@ -44,14 +44,19 @@ const LOGOS: Record<string, string> = {
   v0: '<svg class="size-4 shrink-0" fill="currentColor" viewBox="0 0 147 70" xmlns="http://www.w3.org/2000/svg"><path d="M56 50.2031V14H70V60.1562C70 65.5928 65.5928 70 60.1562 70C57.5605 70 54.9982 68.9992 53.1562 67.1573L0 14H19.7969L56 50.2031Z"/><path d="M147 56H133V23.9531L100.953 56H133V70H96.6875C85.8144 70 77 61.1856 77 50.3125V14H91V46.1562L123.156 14H91V0H127.312C138.186 0 147 8.81439 147 19.6875V56Z"/></svg>',
 };
 
+// Brand names stay verbatim; the surrounding "Open in" phrase localizes via
+// the `actions.openIn` template.
 const PROVIDERS = [
-  { key: "v0", label: "Open in v0" },
-  { key: "chatgpt", label: "Open in ChatGPT" },
-  { key: "claude", label: "Open in Claude" },
-  { key: "t3", label: "Open in T3 Chat" },
-  { key: "scira", label: "Open in Scira" },
-  { key: "cursor", label: "Open in Cursor" },
-];
+  { key: "v0", name: "v0" },
+  { key: "chatgpt", name: "ChatGPT" },
+  { key: "claude", name: "Claude" },
+  { key: "t3", name: "T3 Chat" },
+  { key: "scira", name: "Scira" },
+  { key: "cursor", name: "Cursor" },
+].map((provider) => ({
+  ...provider,
+  label: a.openIn.replace("{name}", provider.name),
+}));
 
 // Top-level actions match the ToC links: flat, no background/padding, color
 // shift on hover only.

package/src/components/layout/Search.astro

@@ -2,7 +2,7 @@
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
-import { resolveIcon } from "../../theme/icons.ts";
+import { resolvePopularIconMarkup } from "../../search/popular-icon.ts";
 import Icon from "../Icon.astro";
 import { flattenPages } from "./nav-utils.ts";
 
@@ -28,23 +28,15 @@ const { askEnabled = false, navigation, popularPages, strings, locale } =
 // default, matching the pattern PageActions uses for its own dictionary.
 const s = { ...EN_UI.search, ...strings };
 
-// Icons resolve to inline SVG here (`theme/icons.ts` is a server-only module —
-// far too large to ship to the browser), so the island gets ready-to-render
-// markup rather than a name it can't resolve. Same approach as AskAI.astro.
-// A name outside the set falls through to the island's own file glyph.
-const iconSvg = (name: string | undefined): string | undefined => {
-  const resolved = name ? resolveIcon(name) : null;
-  return resolved
-    ? `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="${resolved.viewBox}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${resolved.body}</svg>`
-    : undefined;
-};
-
-// Pages shown in the empty state, before the user has typed anything. Only
-// curated entries carry an icon; sidebar-derived rows keep the file glyph.
+// Resolve popular icons to markup here (icon set is server-only). Unknown
+// names fall through to the island's file glyph.
 const popular =
   popularPages && popularPages.length > 0
     ? popularPages.map((page) => ({
-        icon: iconSvg(page.icon),
+        icon: resolvePopularIconMarkup(
+          page.icon,
+          import.meta.env.BASE_URL ?? "/"
+        ),
         label: page.label,
         route: page.route,
       }))
@@ -68,15 +60,18 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-i18n-results={s.results}
   data-locale={locale || undefined}
 >
+  {/* The label and shortcut hint wait until `lg`: below it the hamburger and
+      inline tab bar share the header row, and a full-width search field would
+      press into the language switcher. */}
   <button
     aria-label={s.button}
-    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground sm:min-w-48"
+    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground lg:min-w-48"
     data-blume-search-open
     type="button"
   >
     <Icon name="search" size={16} />
-    <span class="flex-1 text-start max-sm:hidden">{s.button}</span>
-    <kbd class="font-mono text-[0.7rem] max-sm:hidden" data-blume-search-kbd
+    <span class="flex-1 text-start max-lg:hidden">{s.button}</span>
+    <kbd class="font-mono text-[0.7rem] max-lg:hidden" data-blume-search-kbd
       >⌘K</kbd
     >
   </button>
@@ -626,8 +621,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         const href = prefixBase(import.meta.env.BASE_URL, url);
         el.href = href;
         el.className = ROW_CLASS;
-        // `icon` is server-resolved markup from the bundled icon set, not
-        // author HTML — the label still goes through `escapeHtml`.
+        // `icon` is server-resolved markup (built-in Lucide, `<img>`, or
+        // config-authored inline SVG) — the label still goes through `escapeHtml`.
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-muted-foreground">${icon ?? svg("file")}</span>
           <span class="flex-1">

package/src/components/layout/search/orama.ts

@@ -23,7 +23,9 @@ export const createSearch = async (opts: {
   const db = await buildOramaIndex(documents, opts.locale);
 
   return async (query, options) => {
-    const docs = await queryOramaIndex(db, query, RESULT_POOL, options?.locale);
+    const docs = await queryOramaIndex(db, query, RESULT_POOL, {
+      locale: options?.locale,
+    });
     return buildResult(docs as IndexedDocument[], query, options?.section);
   };
 };

package/src/core/base-path.ts

@@ -28,6 +28,15 @@ export const normalizeBasePath = (input?: string): string => {
   return trimmed === "" ? "" : `/${trimmed}`;
 };
 
+/**
+ * Normalize a served path for comparison: drop the trailing slash (Astro serves
+ * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
+ */
+export const normalizePath = (path: string): string => {
+  const trimmed = path.replace(/\/+$/u, "");
+  return trimmed === "" ? "/" : trimmed;
+};
+
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,