blume 1.3.1 → 1.4.0

package/src/search/orama-index.ts

@@ -13,6 +13,10 @@ export interface OramaDoc {
   title: string;
   /** Locale code; indexed as an enum so queries can filter to one language. */
   locale?: string;
+  /** Resolved page `type`; indexed as an enum so queries can filter by type. */
+  contentType?: string;
+  /** Declared facet values (`content.types.<type>.facets`), key → value. */
+  facets?: Record<string, string>;
   /** Carried through for the search dialog's breadcrumb + filter pills. Stored
    * but not indexed, so they ride along on the returned document untouched. */
   breadcrumb?: string[];
@@ -21,13 +25,22 @@ export interface OramaDoc {
 
 const SCHEMA = {
   content: "string",
+  // Enums (not full-text "string") so `where` does an exact-match filter.
+  contentType: "enum",
   description: "string",
-  // Enum (not full-text "string") so `where` does an exact-match filter.
+  // Facets, flattened to `key:value` terms — enum[] so one static schema
+  // serves every project's facet keys, with `containsAll` matching a filter
+  // set. Derived from `facets` at insert time.
+  facetTerms: "enum[]",
   locale: "enum",
   route: "string",
   title: "string",
 } as const;
 
+/** Flatten a facet map to the `key:value` terms the `facetTerms` enum holds. */
+const toFacetTerms = (facets: Record<string, string>): string[] =>
+  Object.entries(facets).map(([key, value]) => `${key}:${value}`);
+
 /** Title and description outrank body text, matching the search dialog. */
 const BOOST = { description: 2, title: 3 };
 
@@ -169,17 +182,36 @@ export const buildOramaIndex = async (
     schema: SCHEMA,
     ...(tokenizer ? { components: { tokenizer } } : {}),
   });
-  await insertMultiple(db, documents);
+  await insertMultiple(
+    db,
+    documents.map((doc) =>
+      doc.facets ? { ...doc, facetTerms: toFacetTerms(doc.facets) } : doc
+    )
+  );
   return db;
 };
 
 /** Orama keeps only documents matching every token at a threshold of 0. */
 const ALL_TOKENS = 0;
 
+/** Optional exact-match filters applied to a query via Orama's `where`. */
+export interface OramaQueryFilters {
+  /** Keep only documents whose `contentType` is in this list. */
+  contentTypes?: string[];
+  /**
+   * Keep only documents matching every facet, key → required value. Facet
+   * keys and values come from the `facets` field on the indexed documents.
+   */
+  facets?: Record<string, string>;
+  /** Keep only documents in this locale. */
+  locale?: string;
+}
+
 /**
  * Query the index, returning the matching documents (highest-ranked first).
- * When `locale` is given, results are filtered to that language via an exact
- * `where` match on the `locale` enum.
+ * `filters` narrows results by exact `where` matches on the enum fields:
+ * `locale` to one language, `contentTypes` to a set of page types, `facets`
+ * to documents carrying every requested `key:value` term.
  *
  * On a bigrammed index the strict pass runs first: a term is only meant to
  * match where its bigrams sit together, and scoring them independently lets a
@@ -191,14 +223,24 @@ export const queryOramaIndex = async (
   db: AnyOrama,
   term: string,
   limit: number,
-  locale?: string
+  filters?: OramaQueryFilters
 ): Promise<OramaDoc[]> => {
+  const facetTerms = filters?.facets ? toFacetTerms(filters.facets) : [];
+  const where = {
+    ...(filters?.locale ? { locale: { eq: filters.locale } } : {}),
+    ...(filters?.contentTypes && filters.contentTypes.length > 0
+      ? { contentType: { in: filters.contentTypes } }
+      : {}),
+    ...(facetTerms.length > 0
+      ? { facetTerms: { containsAll: facetTerms } }
+      : {}),
+  };
   const params = {
     boost: BOOST,
     limit,
     properties: ["title", "description", "content"],
     term,
-    ...(locale ? { where: { locale: { eq: locale } } } : {}),
+    ...(Object.keys(where).length > 0 ? { where } : {}),
   };
   const bigrammed = BIGRAM_LANGUAGES.has(db.tokenizer?.language ?? "");
   const strict = bigrammed

package/src/search/popular-icon.ts

@@ -0,0 +1,33 @@
+import { prefixBase } from "../components/islands/base-path.ts";
+import { isImageIcon, isInlineSvg } from "../theme/icon-kind.ts";
+import { resolveIcon } from "../theme/icons.ts";
+
+/**
+ * Resolve a `search.popular` icon to markup for the Cmd+K island. Accepts the
+ * same *inputs* as nav `<Icon>` (built-in name, image path/URL, inline SVG);
+ * resolved on the server so the island never loads the icon set.
+ */
+export const resolvePopularIconMarkup = (
+  icon?: string,
+  /** `deployment.base` / `import.meta.env.BASE_URL` for root-relative image paths. */
+  base = "/"
+): string | undefined => {
+  if (!icon) {
+    return undefined;
+  }
+  if (isInlineSvg(icon)) {
+    // Author SVG carries no guaranteed width/height (a viewBox-only <svg>
+    // defaults to 300x150), so size it the same way Icon.astro's wrapper does.
+    return `<span aria-hidden="true" style="display:inline-flex;width:16px;height:16px">${icon.trim()}</span>`;
+  }
+  if (isImageIcon(icon)) {
+    const src = prefixBase(base, icon.trim())
+      .replaceAll("&", "&amp;")
+      .replaceAll('"', "&quot;");
+    return `<img src="${src}" width="16" height="16" alt="" aria-hidden="true" class="size-4" />`;
+  }
+  const resolved = resolveIcon(icon);
+  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;
+};

package/src/theme/icon-kind.ts

@@ -0,0 +1,20 @@
+/**
+ * Classify author-supplied icon strings — built-in Lucide names vs image
+ * paths/URLs vs inline SVG. Shared by nav diagnostics, `<Icon>`, and the
+ * Cmd+K popular-icon resolver so the three shapes stay in sync.
+ */
+
+const IMAGE_ICON =
+  /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)|\.(?:avif|gif|jpe?g|png|svg|webp)$/iu;
+
+const INLINE_SVG = /^\s*<svg[\s\S]*<\/svg>\s*$/u;
+
+/** Image path, remote URL, or data URI — not a Lucide name or inline SVG. */
+export const isImageIcon = (value: string): boolean => IMAGE_ICON.test(value);
+
+/** Full `<svg>…</svg>` markup (whitespace-tolerant). */
+export const isInlineSvg = (value: string): boolean => INLINE_SVG.test(value);
+
+/** Image or inline SVG — anything that is not a built-in icon name. */
+export const isAssetIcon = (value: string): boolean =>
+  isInlineSvg(value) || isImageIcon(value);

package/src/translate/agents.ts

@@ -0,0 +1,51 @@
+import type { AgentKind } from "../audit/agent.ts";
+import { DISALLOWED_TOOLS } from "../eval/agents.ts";
+
+/**
+ * argv builders for the translator role. The subprocess machinery
+ * (`runAgentHeadless`, `readAgentOutput`, the `HeadlessRunner` test seam) is
+ * shared with `blume eval` — only the argument surface differs: a translator
+ * is a pure text→text call with no MCP servers and no tools at all, so the
+ * agent can neither read the repo nor write files (Blume owns every write).
+ */
+
+/**
+ * Wall-clock ceiling per file. Generous by design: translating a large page
+ * means regenerating the whole file token by token, and a 20KB+ reference
+ * page comfortably exceeds the eval reader's 3-minute precedent. The ceiling
+ * exists to catch hung agents, not to police slow-but-progressing ones.
+ */
+export const DEFAULT_TRANSLATE_TIMEOUT_MS = 600_000;
+
+const claudeArgs = (): string[] => [
+  "-p",
+  "--output-format",
+  "json",
+  "--strict-mcp-config",
+  "--disallowedTools",
+  DISALLOWED_TOOLS.join(","),
+  "--max-turns",
+  "1",
+];
+
+const codexArgs = (lastMessagePath: string): string[] => [
+  "exec",
+  "--skip-git-repo-check",
+  "--ignore-user-config",
+  "--ephemeral",
+  "--sandbox",
+  "read-only",
+  "--output-last-message",
+  lastMessagePath,
+  "-",
+];
+
+/**
+ * Build the argv for one headless translation call. `lastMessagePath` is where
+ * codex writes its final message (its stdout interleaves progress); claude
+ * ignores it and answers as JSON on stdout.
+ */
+export const translateAgentArgs = (
+  kind: AgentKind,
+  lastMessagePath: string
+): string[] => (kind === "claude" ? claudeArgs() : codexArgs(lastMessagePath));

package/src/translate/ledger.ts

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+
+import { dirname, join } from "pathe";
+import { z } from "zod";
+
+/**
+ * The committed translation ledger: which source files have been translated
+ * into which locales, and at what source content. Named "ledger" to avoid
+ * colliding with the route manifest (`core/manifest.ts`). It lives at the
+ * project root — never inside `.blume/` (init gitignores that dir wholesale,
+ * and the whole point is that the ledger is committed alongside the docs).
+ */
+export const LEDGER_FILE = "blume.translations.json";
+
+/**
+ * `files` maps a POSIX root-relative source path to, per locale, the hash of
+ * the raw source text at the moment that locale's translation was written.
+ */
+export interface TranslationLedger {
+  version: 1;
+  files: Record<string, Record<string, string>>;
+}
+
+const ledgerSchema = z.object({
+  files: z.record(z.string(), z.record(z.string(), z.string())),
+  version: z.literal(1),
+});
+
+export const emptyLedger = (): TranslationLedger => ({
+  files: {},
+  version: 1,
+});
+
+/**
+ * Hash the raw source text (frontmatter included), so any edit invalidates
+ * every locale's stamp. sha256-16 like the audit snapshot's content hash —
+ * never `hashText` (djb2), which is an ephemeral-cache-only hash.
+ */
+export const hashSource = (text: string): string =>
+  createHash("sha256").update(text).digest("hex").slice(0, 16);
+
+/**
+ * Read the ledger at `root`, tolerantly: a missing file, unparseable JSON, or
+ * an unknown shape/version all resolve to an empty ledger rather than an error
+ * (same posture as the dev lock's `parseLock`) — the worst outcome of a
+ * corrupt ledger is retranslating files that were already up to date.
+ */
+export const readLedger = async (root: string): Promise<TranslationLedger> => {
+  let raw: string;
+  try {
+    raw = await readFile(join(root, LEDGER_FILE), "utf-8");
+  } catch {
+    return emptyLedger();
+  }
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return emptyLedger();
+  }
+  const parsed = ledgerSchema.safeParse(data);
+  return parsed.success ? parsed.data : emptyLedger();
+};
+
+/** Deterministic serialization: keys sorted at both levels, 2-space indent. */
+export const serializeLedger = (ledger: TranslationLedger): string => {
+  const files: Record<string, Record<string, string>> = {};
+  for (const source of Object.keys(ledger.files).toSorted()) {
+    const locales = ledger.files[source] ?? {};
+    files[source] = Object.fromEntries(
+      Object.keys(locales)
+        .toSorted()
+        .map((locale) => [locale, locales[locale] ?? ""])
+    );
+  }
+  return `${JSON.stringify({ files, version: ledger.version }, null, 2)}\n`;
+};
+
+/**
+ * Write the ledger at `root`, returning whether anything changed on disk. A
+ * byte-identical ledger is left untouched (no mtime churn, no git noise);
+ * a changed one lands via temp-file-plus-rename so a concurrent reader never
+ * observes a half-written file.
+ */
+export const writeLedger = async (
+  root: string,
+  ledger: TranslationLedger
+): Promise<boolean> => {
+  const path = join(root, LEDGER_FILE);
+  const content = serializeLedger(ledger);
+  let existing: string | null = null;
+  try {
+    existing = await readFile(path, "utf-8");
+  } catch {
+    existing = null;
+  }
+  if (existing === content) {
+    return false;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, content, "utf-8");
+  try {
+    await rename(tmp, path);
+  } catch (error) {
+    await rm(tmp, { force: true });
+    throw error;
+  }
+  return true;
+};
+
+/** Record that `sourceRel` is translated into `locale` at source hash `hash`. */
+export const stampLedger = (
+  ledger: TranslationLedger,
+  sourceRel: string,
+  locale: string,
+  hash: string
+): void => {
+  const locales = ledger.files[sourceRel] ?? {};
+  locales[locale] = hash;
+  ledger.files[sourceRel] = locales;
+};
+
+/**
+ * Drop entries for sources that no longer exist and locales that are no longer
+ * configured, so deleted pages and removed locales don't linger in the ledger
+ * forever. Returns a new ledger.
+ */
+export const pruneLedger = (
+  ledger: TranslationLedger,
+  knownSources: ReadonlySet<string>,
+  knownLocales: ReadonlySet<string>
+): TranslationLedger => {
+  const files: Record<string, Record<string, string>> = {};
+  for (const [source, locales] of Object.entries(ledger.files)) {
+    if (!knownSources.has(source)) {
+      continue;
+    }
+    const kept = Object.fromEntries(
+      Object.entries(locales).filter(([locale]) => knownLocales.has(locale))
+    );
+    if (Object.keys(kept).length > 0) {
+      files[source] = kept;
+    }
+  }
+  return { files, version: ledger.version };
+};

package/src/translate/meta.ts

@@ -0,0 +1,149 @@
+import { readFile } from "node:fs/promises";
+
+import { dirname, join, relative } from "pathe";
+import { glob } from "tinyglobby";
+
+import { createModuleLoader } from "../core/load-module.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import { folderMetaSchema } from "../core/schema.ts";
+import type { FolderMeta } from "../core/schema.ts";
+import type { Diagnostic } from "../core/types.ts";
+
+/**
+ * Folder-nav `meta.ts` titles are translatable under the `dir` parser ONLY:
+ * per-locale meta is a whole-file replacement, not a merge (`applyFolderMeta`
+ * looks up `<locale>/<group>` and falls back to shared meta, never to the
+ * default locale's file), and the `dot` parser has no per-locale meta
+ * mechanism at all. So the generated module must copy EVERY source key
+ * (order/pages/icon/collapsed) with only the title translated — otherwise the
+ * locale's navigation loses its ordering.
+ */
+
+/** One default-locale meta file whose title can be translated. */
+export interface TranslatableMeta {
+  /** The parsed meta module; copied wholesale into the generated module. */
+  data: FolderMeta;
+  /** Directory relative to the owning source's content root (`""` = root). */
+  dir: string;
+  /** Absolute path of the source meta file. */
+  file: string;
+  /** The owning source's content root (locale directories live under it). */
+  contentRoot: string;
+  /** Raw source text at discovery time — what the ledger hashes. */
+  raw: string;
+  /** POSIX root-relative path of the source meta file — the ledger key. */
+  sourceRel: string;
+  /** The source title to translate. */
+  title: string;
+}
+
+const META_FILES = ["**/meta.ts", "**/meta.js", "**/meta.mjs"];
+
+/** Where a locale's generated meta module lives (always written as `meta.ts`). */
+export const metaTargetPath = (
+  meta: TranslatableMeta,
+  locale: string
+): string => join(meta.contentRoot, locale, meta.dir, "meta.ts");
+
+/**
+ * Discover the default-locale `meta.{ts,js,mjs}` files whose titles a
+ * translation run covers. Skips (in order): non-`dir` i18n projects entirely,
+ * files inside a configured locale directory (those ARE translations),
+ * factory-form modules (a warning — the generator can't re-emit a function),
+ * modules that fail meta validation (the scan already errors on those), and
+ * modules with no `title` (nothing to translate).
+ */
+export const discoverTranslatableMeta = async (
+  project: BlumeProject
+): Promise<{ metas: TranslatableMeta[]; diagnostics: Diagnostic[] }> => {
+  const { i18n } = project.config;
+  if (!i18n || i18n.parser !== "dir") {
+    return { diagnostics: [], metas: [] };
+  }
+  const localeDirs = new Set(
+    i18n.locales.flatMap((locale) =>
+      locale.code === i18n.defaultLocale ? [] : [locale.code.toLowerCase()]
+    )
+  );
+
+  const load = createModuleLoader();
+  const metas: TranslatableMeta[] = [];
+  const diagnostics: Diagnostic[] = [];
+
+  const roots = project.sources.flatMap((source) =>
+    source.staged || !source.contentRoot ? [] : [source.contentRoot]
+  );
+  for (const contentRoot of roots) {
+    // oxlint-disable-next-line no-await-in-loop -- a project has O(1) sources
+    const files = await glob(META_FILES, {
+      absolute: true,
+      cwd: contentRoot,
+      ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+      onlyFiles: true,
+    });
+    for (const file of files.toSorted()) {
+      const dir = relative(contentRoot, dirname(file));
+      const first = dir.split("/")[0]?.toLowerCase();
+      if (first && localeDirs.has(first)) {
+        continue;
+      }
+      // oxlint-disable-next-line no-await-in-loop -- sequential, ordered discovery
+      const [raw, mod] = await Promise.all([
+        readFile(file, "utf-8"),
+        load(file),
+      ]);
+      if (typeof mod === "function") {
+        diagnostics.push({
+          code: "BLUME_TRANSLATE_META_FACTORY",
+          file,
+          message:
+            "This meta file default-exports a function, so `blume translate` cannot generate per-locale copies of it.",
+          severity: "warning",
+          suggestion:
+            "Export a plain object, or author the locale's meta file by hand.",
+        });
+        continue;
+      }
+      const parsed = folderMetaSchema.safeParse(mod);
+      if (!parsed.success || parsed.data.title === undefined) {
+        continue;
+      }
+      metas.push({
+        contentRoot,
+        data: parsed.data,
+        dir: dir === "." ? "" : dir,
+        file,
+        raw,
+        sourceRel: relative(project.context.root, file),
+        title: parsed.data.title,
+      });
+    }
+  }
+  return { diagnostics, metas };
+};
+
+/**
+ * Emit the per-locale meta module: every source key copied verbatim, only the
+ * title swapped for its translation. Keys alphabetical, values as JSON.
+ */
+export const generateMetaModule = (
+  meta: FolderMeta,
+  translatedTitle: string
+): string => {
+  const data: Record<string, unknown> = {
+    ...meta,
+    title: translatedTitle,
+  };
+  const lines = Object.keys(data)
+    .toSorted()
+    .filter((key) => data[key] !== undefined)
+    .map((key) => `  ${key}: ${JSON.stringify(data[key])},`);
+  return [
+    "// Generated by `blume translate` — edit the default locale's meta file",
+    "// and rerun the translation instead of editing this copy.",
+    "export default {",
+    ...lines,
+    "};",
+    "",
+  ].join("\n");
+};

package/src/translate/prompts.ts

@@ -0,0 +1,95 @@
+import type { LocaleConfig } from "../core/schema.ts";
+
+/**
+ * The frontmatter key paths whose *values* an agent may translate. Everything
+ * else in the frontmatter is copied from the source verbatim by the validator,
+ * so this list is both the prompt's instruction and the reconciliation
+ * contract in `validate.ts`.
+ */
+export const TRANSLATABLE_KEY_PATHS: readonly (readonly string[])[] = [
+  ["title"],
+  ["description"],
+  ["sidebar", "label"],
+  ["sidebar", "badge"],
+  ["seo", "title"],
+  ["seo", "description"],
+];
+
+/** "French (fr)" — the configured display label plus the code. */
+const localeName = (locale: LocaleConfig): string =>
+  `${locale.label} (${locale.code})`;
+
+const KEY_LIST = TRANSLATABLE_KEY_PATHS.map((path) => path.join(".")).join(
+  ", "
+);
+
+/**
+ * The page-translation prompt. Delivered over stdin (no argv limits), so the
+ * full source file rides along inline. When the page was translated before,
+ * the previous translation rides along too: without it, every retranslation
+ * is a from-scratch rewrite in which the agent re-decides register, dialect,
+ * and terminology (du vs Sie, pt-BR vs pt-PT) and churns the whole page for
+ * a one-paragraph source edit.
+ */
+export const pagePrompt = (
+  sourceText: string,
+  target: LocaleConfig,
+  source: LocaleConfig,
+  previousTranslation?: string
+): string => {
+  const styleRule =
+    target.style === undefined
+      ? ""
+      : `
+- Write the translation in this style: ${target.style}`;
+  const previousRule =
+    previousTranslation === undefined
+      ? ""
+      : `
+- A translation of an earlier revision of this page is included below. Match its register, formality, dialect, and terminology exactly; re-translate only what the changed source requires and keep everything else word-for-word identical.${
+          target.style === undefined
+            ? ""
+            : " Where the previous translation disagrees with the style rule above, the style rule wins."
+        }`;
+  const previousSection =
+    previousTranslation === undefined
+      ? ""
+      : `
+The previous translation begins after this line and ends at the "page source" marker.
+${previousTranslation}`;
+  return `Translate the following documentation page from ${localeName(
+    source
+  )} into ${localeName(target)}.
+
+Rules:
+- Translate the prose: headings, paragraphs, list items, table cells, admonitions, and image alt text.
+- In the YAML frontmatter, translate ONLY the values of these keys: ${KEY_LIST}. Copy every other frontmatter key and value exactly as written.
+- Never translate or alter: code blocks, inline code, import/export statements, JSX/MDX component names and their attributes, URLs, link targets, HTML tags, or frontmatter keys.
+- Preserve the document structure exactly: the same headings, the same lists and tables, and the same number of code fences.${styleRule}${previousRule}
+- Output ONLY the complete translated file. Do not wrap it in a code fence. Do not add commentary before or after it.
+${previousSection}
+The page source begins after this line.
+${sourceText}`;
+};
+
+/**
+ * The sidebar-titles prompt: a JSON object of `{directory: title}` in, the
+ * same keys with translated values out.
+ */
+export const metaPrompt = (
+  titles: Record<string, string>,
+  target: LocaleConfig,
+  source: LocaleConfig
+): string => `Translate the following documentation sidebar section titles from ${localeName(
+  source
+)} into ${localeName(target)}.
+
+The input is a JSON object mapping a directory path to its title. Reply with ONLY a JSON object that has exactly the same keys, where each value is the title translated into ${localeName(
+  target
+)}. Do not translate the keys. Do not add commentary.${
+  target.style === undefined
+    ? ""
+    : `\nWrite the titles in this style: ${target.style}`
+}
+
+${JSON.stringify(titles, null, 2)}`;