blume 0.3.0 → 0.4.0

package/src/markdown/directives.ts

@@ -3,7 +3,8 @@ import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
 
 interface DirectiveNode extends MdastNode {
   attributes?: Record<string, string | null | undefined> | null;
-  children: MdastNode[];
+  // Satteri gives an empty container directive (`:::note\n:::`) `children: null`.
+  children?: MdastNode[] | null;
   name: string;
 }
 
@@ -38,11 +39,18 @@ interface TextNode extends MdastNode {
   value?: string;
 }
 
-/** Concatenate the plain text of a node's immediate phrasing children. */
-const textOf = (node: MdastNode): string =>
-  ((node.children as TextNode[] | undefined) ?? [])
-    .map((child) => child.value ?? "")
-    .join("");
+/**
+ * Concatenate the plain text of a node, recursing through phrasing children so
+ * formatted labels keep every word — `:::note[Read **this**]` yields
+ * `Read this`, not `Read ` (the bolded run dropped).
+ */
+const textOf = (node: MdastNode): string => {
+  const { children } = node as { children?: MdastNode[] };
+  if (children && children.length > 0) {
+    return children.map(textOf).join("");
+  }
+  return (node as TextNode).value ?? "";
+};
 
 /**
  * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
@@ -57,7 +65,7 @@ export const directiveToCalloutPlugin = () => ({
       return;
     }
 
-    const children = [...node.children];
+    const children = [...(node.children ?? [])];
     let title = node.attributes?.title ?? undefined;
 
     // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.

package/src/markdown/package-commands.ts

@@ -10,7 +10,14 @@ const WHITESPACE = /\s+/u;
 const WHITESPACE_RUN = /\s+/gu;
 const GLOBAL_FLAGS = new Set(["-g", "--global"]);
 
-type Operation = "add" | "create" | "exec" | "install" | "remove" | "run";
+type Operation =
+  | "add"
+  | "ci"
+  | "create"
+  | "exec"
+  | "install"
+  | "remove"
+  | "run";
 
 interface Intent {
   args: string[];
@@ -26,6 +33,9 @@ const normalizeVerb = (verb: string): Operation | null => {
     case "install": {
       return "add";
     }
+    case "ci": {
+      return "ci";
+    }
     case "create":
     case "init": {
       return "create";
@@ -125,10 +135,22 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
       }
       return `${manager} dlx ${args}`;
     }
-    case "remove": {
+    case "ci": {
+      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere.
       return manager === "npm"
-        ? `npm uninstall ${args}`
-        : `${manager} remove ${args}`;
+        ? "npm ci"
+        : `${manager} install --frozen-lockfile`;
+    }
+    case "remove": {
+      if (manager === "npm") {
+        return `npm uninstall ${args}`;
+      }
+      // Yarn Classic has no `remove -g`; the global form is `yarn global remove`.
+      if (manager === "yarn" && intent.args.some((a) => GLOBAL_FLAGS.has(a))) {
+        const pkgs = intent.args.filter((a) => !GLOBAL_FLAGS.has(a)).join(" ");
+        return `yarn global remove ${pkgs}`;
+      }
+      return `${manager} remove ${args}`;
     }
     case "run": {
       return `${manager} run ${args}`;

package/src/migrate/fumadocs/content.ts

@@ -4,7 +4,12 @@ import { readFile as readFileFromDisk } from "node:fs/promises";
 import { dirname, resolve } from "pathe";
 
 import matter from "../../core/frontmatter.ts";
-import { findOpenTagEnd, renameTag, rewriteCallouts } from "../shared.ts";
+import {
+  findOpenTagEnd,
+  isInsideRoot,
+  renameTag,
+  rewriteCallouts,
+} from "../shared.ts";
 
 /**
  * Source-to-source rewrites that turn Fumadocs-only MDX into idiomatic Blume
@@ -291,6 +296,8 @@ const INCLUDE = /<include\b[^>]*>(?<path>[\s\S]*?)<\/include>/gu;
 interface IncludeOptions {
   filePath: string;
   readFile?: (file: string) => Promise<string>;
+  /** Docs root the include must stay within; targets escaping it are skipped. */
+  root: string;
   seen?: Set<string>;
 }
 
@@ -321,6 +328,12 @@ export const inlineFumadocsIncludes = async (
       continue;
     }
     const target = resolve(dirname(options.filePath), rawPath);
+    if (!isInsideRoot(options.root, target)) {
+      warnings.push(
+        `<include> target "${rawPath}" is outside the docs tree — left as-is.`
+      );
+      continue;
+    }
     if (seen.has(target)) {
       warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
       continue;

package/src/migrate/fumadocs/groups.ts

@@ -3,6 +3,7 @@ import { mkdir, rename, writeFile } from "node:fs/promises";
 
 import { basename, join } from "pathe";
 
+import { isInsideRoot } from "../shared.ts";
 import { renderMetaModule } from "./meta.ts";
 import type {
   FumadocsPageItem,
@@ -47,6 +48,12 @@ const isDirectory = (path: string): boolean => {
 
 /** Resolve a `pages` name to its on-disk page file or folder under `docsDir`. */
 const resolveEntry = (docsDir: string, name: string): ResolvedEntry | null => {
+  // A `pages` entry is author-controlled; reject any that escapes `docsDir`
+  // (e.g. `"../../victim"`) so the later `rename` can't move a file out of the
+  // docs tree.
+  if (!isInsideRoot(docsDir, join(docsDir, name))) {
+    return null;
+  }
   for (const ext of PAGE_EXTS) {
     const file = join(docsDir, `${name}${ext}`);
     if (existsSync(file)) {

package/src/migrate/fumadocs/index.ts

@@ -5,9 +5,9 @@ import { dirname, join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import matter from "../../core/frontmatter.ts";
+import { ensureGitignore } from "../../core/gitignore.ts";
 import type { FolderMeta } from "../../core/schema.ts";
 import {
-  ensureGitignore,
   leftoverFiles,
   rewriteFrameworkScripts,
   writeBlumeConfig,
@@ -85,7 +85,10 @@ const movePage = async (
   }
 
   const raw = await readFile(abs, "utf-8");
-  const included = await inlineFumadocsIncludes(raw, { filePath: abs });
+  const included = await inlineFumadocsIncludes(raw, {
+    filePath: abs,
+    root: base,
+  });
   let text = stripFumadocsImports(included.content);
   text = rewriteFumadocsCallouts(text);
   text = rewriteFumadocsContainers(text);

package/src/migrate/mintlify/assets.ts

@@ -0,0 +1,46 @@
+import type { BlumeConfig } from "../../core/schema.ts";
+
+/** Asset paths referenced by the resolved config (logo, favicon, backgrounds). */
+const assetRefs = (config: BlumeConfig): unknown[] => {
+  const refs: unknown[] = ["/images"];
+  const logo = config.logo as
+    | string
+    | { dark?: string; light?: string }
+    | undefined;
+  if (typeof logo === "string") {
+    refs.push(logo);
+  } else if (logo) {
+    refs.push(logo.light, logo.dark);
+  }
+  const favicon = config.favicon as
+    | string
+    | { dark?: string; light?: string }
+    | undefined;
+  if (typeof favicon === "string") {
+    refs.push(favicon);
+  } else if (favicon) {
+    refs.push(favicon.light, favicon.dark);
+  }
+  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
+  return refs;
+};
+
+/**
+ * Top-level path segments referenced as static assets by a Mintlify config
+ * (the conventional `/images`, plus logo/favicon/background paths). These are
+ * the root-served folders Mintlify exposes at the site root; Blume serves them
+ * via `content.assets` (bridge) or relocates them under `public/` (migrator).
+ */
+export const assetSegments = (config: BlumeConfig): string[] => {
+  const segments = new Set<string>();
+  for (const ref of assetRefs(config)) {
+    if (typeof ref !== "string" || !ref.startsWith("/")) {
+      continue;
+    }
+    const [segment] = ref.replace(/^\/+/u, "").split("/");
+    if (segment) {
+      segments.add(segment);
+    }
+  }
+  return [...segments];
+};

package/src/migrate/mintlify/index.ts

@@ -1,10 +1,11 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 
 import { dirname, join } from "pathe";
 import { glob } from "tinyglobby";
 
 import type { BlumeConfig } from "../../core/schema.ts";
+import { assetSegments } from "./assets.ts";
 import { loadMintlifyConfig } from "./config.ts";
 import { mintlifyI18n } from "./i18n.ts";
 import { transformMintlifyContent } from "./transform.ts";
@@ -52,28 +53,37 @@ const writeBlumeConfig = async (
   await writeFile(join(root, "blume.config.ts"), body, "utf-8");
 };
 
-/** Move a referenced top-level asset path (file or dir) under `public/`. */
+interface RelocatedAssets {
+  /** Top-level dirs served in place via `content.assets` (no files moved). */
+  served: string[];
+  /** Top-level files moved under `public/`. */
+  moved: string[];
+}
+
+/**
+ * Make referenced top-level assets resolvable in Blume. Directories (e.g.
+ * Mintlify's `images/`) are left in place and served via `content.assets`, so
+ * the migration doesn't churn every file under them; loose top-level files
+ * (a root `favicon.png`, `logo.png`) are moved under `public/` since a mount
+ * points at a directory.
+ */
 const relocateAssets = async (
   root: string,
-  refs: unknown[]
-): Promise<string[]> => {
-  const segments = new Set<string>();
-  for (const ref of refs) {
-    if (typeof ref !== "string" || !ref.startsWith("/")) {
-      continue;
-    }
-    const [segment] = ref.replace(/^\/+/u, "").split("/");
-    if (segment) {
-      segments.add(segment);
-    }
-  }
-
+  segments: string[]
+): Promise<RelocatedAssets> => {
+  const served: string[] = [];
   const moved: string[] = [];
   for (const segment of segments) {
     const source = join(root, segment);
     if (!existsSync(source) || segment === "public") {
       continue;
     }
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs stats
+    const stats = await stat(source);
+    if (stats.isDirectory()) {
+      served.push(segment);
+      continue;
+    }
     const dest = join(root, "public", segment);
     if (existsSync(dest)) {
       continue;
@@ -84,7 +94,32 @@ const relocateAssets = async (
     await rename(source, dest);
     moved.push(segment);
   }
-  return moved;
+  return { moved, served };
+};
+
+/**
+ * Fold relocated assets into the config (served dirs become `content.assets`)
+ * and record what happened. Served dirs stay in place; only loose files moved.
+ */
+const applyRelocatedAssets = (
+  config: BlumeConfig,
+  assets: RelocatedAssets,
+  warnings: string[]
+): void => {
+  if (assets.served.length > 0) {
+    config.content = {
+      ...config.content,
+      assets: [
+        ...new Set([...(config.content?.assets ?? []), ...assets.served]),
+      ],
+    };
+    warnings.push(
+      `Kept asset dir(s) in place, served via content.assets: ${assets.served.join(", ")}.`
+    );
+  }
+  if (assets.moved.length > 0) {
+    warnings.push(`Moved assets into public/: ${assets.moved.join(", ")}.`);
+  }
 };
 
 /**
@@ -121,31 +156,6 @@ const cleanupSnippets = async (
   }
 };
 
-/** Asset paths referenced by the resolved config (logo, favicon, backgrounds). */
-const assetRefs = (config: BlumeConfig): unknown[] => {
-  const refs: unknown[] = ["/images"];
-  const logo = config.logo as
-    | string
-    | { dark?: string; light?: string }
-    | undefined;
-  if (typeof logo === "string") {
-    refs.push(logo);
-  } else if (logo) {
-    refs.push(logo.light, logo.dark);
-  }
-  const favicon = config.favicon as
-    | string
-    | { dark?: string; light?: string }
-    | undefined;
-  if (typeof favicon === "string") {
-    refs.push(favicon);
-  } else if (favicon) {
-    refs.push(favicon.light, favicon.dark);
-  }
-  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
-  return refs;
-};
-
 /**
  * Migrate a Mintlify project to Blume: translate `docs.json`/`mint.json` into
  * `blume.config.ts`, rewrite every page to idiomatic Blume MDX in place, and
@@ -232,12 +242,13 @@ export const migrateMintlifyProject = async (
     moved += 1;
   }
 
-  const movedAssets = await relocateAssets(root, assetRefs(config));
+  const assets = await relocateAssets(root, assetSegments(config));
   await cleanupSnippets(root, keptComponents, warnings);
 
   if (config.content?.exclude) {
     config.content.exclude = [...new Set(config.content.exclude)];
   }
+  applyRelocatedAssets(config, assets, warnings);
   await writeBlumeConfig(root, config);
 
   if (Object.keys(variables).length > 0) {
@@ -245,9 +256,6 @@ export const migrateMintlifyProject = async (
       `Inlined ${Object.keys(variables).length} docs.json variable(s) into content; Blume has no runtime variable substitution.`
     );
   }
-  if (movedAssets.length > 0) {
-    warnings.push(`Moved assets into public/: ${movedAssets.join(", ")}.`);
-  }
   if (removedKeys.size > 0) {
     warnings.push(
       `Dropped unsupported page frontmatter keys: ${[...removedKeys].join(", ")}.`

package/src/migrate/shared.ts

@@ -1,11 +1,22 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 
-import { join } from "pathe";
+import { isAbsolute, join, relative } from "pathe";
 
 import type { BlumeConfig } from "../core/schema.ts";
 import { pageMetaSchema } from "../core/schema.ts";
 
+/**
+ * Whether `candidate` resolves to a path inside `root` (or is `root` itself).
+ * Guards migrators against `../` traversal in author-controlled source paths
+ * (`pages` entries, `<include>` targets) that would otherwise read or move
+ * files outside the docs tree.
+ */
+export const isInsideRoot = (root: string, candidate: string): boolean => {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+
 /**
  * Framework-agnostic helpers shared by more than one migrator. Each piece here
  * was generalized from a migrator-specific implementation so Mintlify, Nextra,
@@ -86,32 +97,6 @@ export const rewriteFrameworkScripts = async (
   return changed;
 };
 
-/** A `.gitignore` line, normalized for comparison (trailing slashes dropped). */
-const gitignoreKey = (line: string): string => line.trim().replace(/\/+$/u, "");
-
-/**
- * Ensure `.gitignore` ignores each of `entries`, appending any that are missing
- * (creating the file when absent). Trailing-slash differences (`dist` vs
- * `dist/`) count as already present. Returns the entries actually added.
- */
-export const ensureGitignore = async (
-  root: string,
-  entries: string[]
-): Promise<string[]> => {
-  const path = join(root, ".gitignore");
-  const existing = existsSync(path) ? await readFile(path, "utf-8") : "";
-  const present = new Set(
-    existing.split("\n").map(gitignoreKey).filter(Boolean)
-  );
-  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
-  if (added.length === 0) {
-    return [];
-  }
-  const gap = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-  await writeFile(path, `${existing}${gap}${added.join("\n")}\n`, "utf-8");
-  return added;
-};
-
 /** Of the candidate project-relative paths, the ones that still exist — the old
  * framework files a migration leaves behind for the user to remove by hand. */
 export const leftoverFiles = (root: string, candidates: string[]): string[] =>

package/src/og/card.ts

@@ -56,8 +56,20 @@ const MUTED = "#737373";
 const FAINT = "#a3a3a3";
 const BORDER = "#e5e5e5";
 
-const truncate = (value: string, max: number): string =>
-  value.length > max ? `${value.slice(0, max - 1).trimEnd()}…` : value;
+/**
+ * Truncate to `max` code points with an ellipsis. Slices by code points, not
+ * UTF-16 units, so cutting mid-emoji doesn't leave a lone surrogate (a broken
+ * glyph) before the ellipsis.
+ */
+export const truncate = (value: string, max: number): string => {
+  const chars = [...value];
+  return chars.length > max
+    ? `${chars
+        .slice(0, max - 1)
+        .join("")
+        .trimEnd()}…`
+    : value;
+};
 
 // Brand mark sizing: target this height, but scale down so a wide wordmark logo
 // stays within the lockup.

package/src/registry/eject.ts

@@ -140,7 +140,12 @@ export const eject = async (root: string): Promise<string[]> => {
   const hasStaged = staged.size > 0;
   const stagedDir = "blume-staged";
 
-  const files: { path: string; content: string }[] = [
+  const files: {
+    path: string;
+    content: string;
+    /** Don't overwrite a file the user already owns (e.g. a tuned tsconfig). */
+    skipIfExists?: boolean;
+  }[] = [
     {
       content: astroConfigTemplate({
         config,
@@ -160,6 +165,8 @@ export const eject = async (root: string): Promise<string[]> => {
     {
       content: runtimeTsconfigTemplate(),
       path: join(root, "tsconfig.json"),
+      // Never clobber a hand-tuned tsconfig; only write ours if none exists.
+      skipIfExists: true,
     },
     { content: envTemplate(), path: join(srcDir, "env.d.ts") },
     {
@@ -327,8 +334,11 @@ export const eject = async (root: string): Promise<string[]> => {
     files.push({ content, path: join(root, stagedDir, entryId) });
   }
 
+  const written = files.filter(
+    (file) => !(file.skipIfExists && existsSync(file.path))
+  );
   await Promise.all(
-    files.map(async (file) => {
+    written.map(async (file) => {
       await mkdir(join(file.path, ".."), { recursive: true });
       await writeFile(file.path, file.content, "utf-8");
     })
@@ -347,5 +357,5 @@ export const eject = async (root: string): Promise<string[]> => {
   // The hidden runtime is no longer the source of truth.
   await rm(context.outDir, { force: true, recursive: true });
 
-  return files.map((file) => file.path);
+  return written.map((file) => file.path);
 };

package/src/registry/registry.ts

@@ -219,6 +219,12 @@ const CONTENT_COMPONENTS: {
     name: "prompt",
     tag: "Prompt",
   },
+  {
+    description: "A responsive, privacy-friendly YouTube embed.",
+    file: "YouTube.astro",
+    name: "youtube",
+    tag: "YouTube",
+  },
 ];
 
 /** The built-in, Blume-owned source registry. */

package/src/registry/rewrite-imports.ts

@@ -1,10 +1,16 @@
 import { dirname, relative, resolve } from "pathe";
 
-// The module specifier in `... from "<spec>"` and side-effect `import "<spec>"`,
-// limited to relative specifiers (those starting with `.`). Capturing the
-// keyword, gap, and quote lets us rebuild the statement verbatim.
-const RELATIVE_IMPORT =
-  /(?<kw>\bfrom|\bimport)(?<gap>\s+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gu;
+// A relative specifier (starting with `.`) in an `import … from "…"` or
+// `export … from "…"` statement. Anchored to the start of a line (`m` flag) and
+// bounded by `[^;]` so it only matches a real statement — not a `from "./…"`
+// that happens to appear inside a string or JSX text — while still allowing a
+// multiline import body between the keyword and `from`.
+const FROM_IMPORT =
+  /(?<prefix>^[ \t]*(?:import|export)\b[^;]*?\bfrom[ \t]*)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
+
+// A side-effect `import "./…"` at the start of a line.
+const SIDE_EFFECT_IMPORT =
+  /(?<prefix>^[ \t]*import[ \t]+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
 
 /**
  * Rewrite a built-in component's relative imports to `blume/*` package
@@ -22,18 +28,24 @@ export const rewriteImports = (
   content: string,
   sourceFile: string,
   srcRoot: string
-): string =>
-  content.replaceAll(
-    RELATIVE_IMPORT,
-    (match, kw: string, gap: string, quote: string, spec: string) => {
-      const resolved = resolve(dirname(sourceFile), spec);
-      if (resolved === sourceFile) {
-        return match;
-      }
-      const rel = relative(srcRoot, resolved);
-      if (rel.startsWith("..")) {
-        return match;
-      }
-      return `${kw}${gap}${quote}blume/${rel}${quote}`;
+): string => {
+  const rewrite = (
+    match: string,
+    prefix: string,
+    quote: string,
+    spec: string
+  ): string => {
+    const resolved = resolve(dirname(sourceFile), spec);
+    if (resolved === sourceFile) {
+      return match;
+    }
+    const rel = relative(srcRoot, resolved);
+    if (rel.startsWith("..")) {
+      return match;
     }
-  );
+    return `${prefix}${quote}blume/${rel}${quote}`;
+  };
+  return content
+    .replaceAll(FROM_IMPORT, rewrite)
+    .replaceAll(SIDE_EFFECT_IMPORT, rewrite);
+};

package/src/search/documents.ts

@@ -47,17 +47,35 @@ const MARKDOWN_PUNCT = /[*_~>]+/gu;
 const WHITESPACE = /\s+/gu;
 
 /** Reduce Markdown/MDX to plain, searchable text. */
-const toPlainText = (markdown: string): string =>
-  markdown
+const toPlainText = (markdown: string): string => {
+  const withoutBlocks = markdown
     .replaceAll(CODE_FENCE, " ")
     .replaceAll(IMAGE, " ")
-    .replaceAll(LINK, "$<text>")
-    .replaceAll(HTML_OR_JSX, " ")
-    .replaceAll(INLINE_CODE, "$<code>")
+    .replaceAll(LINK, "$<text>");
+
+  // Strip HTML/JSX from the prose, but keep the contents of inline code — an
+  // angle-bracket span like `<T>` inside `Array<T>` is a type parameter, not a
+  // tag, and stripping it would drop those tokens from the search index. Split
+  // on inline-code spans and only run the HTML strip on the text between them.
+  const pieces: string[] = [];
+  let cursor = 0;
+  for (const match of withoutBlocks.matchAll(INLINE_CODE)) {
+    const start = match.index ?? 0;
+    pieces.push(
+      withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " ")
+    );
+    pieces.push(match.groups?.code ?? "");
+    cursor = start + match[0].length;
+  }
+  pieces.push(withoutBlocks.slice(cursor).replaceAll(HTML_OR_JSX, " "));
+
+  return pieces
+    .join("")
     .replaceAll(HEADING_MARK, "")
     .replaceAll(MARKDOWN_PUNCT, " ")
     .replaceAll(WHITESPACE, " ")
     .trim();
+};
 
 interface Crumbs {
   breadcrumb: string[];

package/src/search/sync/algolia.ts

@@ -9,6 +9,10 @@ export interface AlgoliaSyncConfig {
  * Upload the search records to Algolia. Uses the admin key from
  * `ALGOLIA_ADMIN_API_KEY` (never the config, which holds only the public,
  * search-only key). Throws on a missing key/config so the caller can warn.
+ *
+ * Uses `replaceAllObjects`, which atomically replaces the index contents, so
+ * pages deleted or renamed since the last sync don't linger as stale search
+ * hits that 404 when clicked.
  */
 export const syncAlgolia = async (
   records: SearchRecord[],
@@ -23,7 +27,7 @@ export const syncAlgolia = async (
   }
   const { algoliasearch } = await import("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
-  await client.saveObjects({
+  await client.replaceAllObjects({
     indexName: config.indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id })),
   });