blume 0.2.0 → 0.4.0

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/config.ts

@@ -579,72 +579,6 @@ const mintlifySelectors = (spec: JsonObject): NavigationSelectors => {
   ].filter((selector) => selector.items.length > 0);
 };
 
-const navbarTypeLabel = (type: string | undefined): string | undefined => {
-  if (type === "github") {
-    return "GitHub";
-  }
-  if (type === "discord") {
-    return "Discord";
-  }
-  return undefined;
-};
-
-const navbarLinkType = (
-  type: string | undefined
-): "github" | "discord" | undefined =>
-  type === "github" || type === "discord" ? type : undefined;
-
-const navbarPrimaryType = (
-  type: string | undefined
-): "button" | "github" | "discord" =>
-  type === "github" || type === "discord" ? type : "button";
-
-const mintlifyNavbar = (value: unknown): NonNullable<BlumeConfig["navbar"]> => {
-  const object = asObject(value);
-  if (!object) {
-    return { links: [] };
-  }
-
-  const links = asArray(object.links).flatMap((item) => {
-    const itemObject = asObject(item);
-    const href = itemObject ? asString(itemObject.href) : undefined;
-    const type = itemObject ? asString(itemObject.type) : undefined;
-    const label = itemObject
-      ? (asString(itemObject.label) ?? navbarTypeLabel(type))
-      : undefined;
-    if (!itemObject || !href || !label) {
-      return [];
-    }
-    return [
-      withoutUndefined({
-        href,
-        icon: asString(itemObject.icon),
-        label,
-        type: navbarLinkType(type),
-      }),
-    ];
-  });
-
-  const primaryObject = asObject(object.primary);
-  const primaryHref = primaryObject ? asString(primaryObject.href) : undefined;
-  const primaryType = primaryObject
-    ? (asString(primaryObject.type) ?? "button")
-    : undefined;
-  const primaryLabel = primaryObject
-    ? (asString(primaryObject.label) ?? navbarTypeLabel(primaryType))
-    : undefined;
-  const primary =
-    primaryObject && primaryHref && primaryLabel
-      ? withoutUndefined({
-          href: primaryHref,
-          label: primaryLabel,
-          type: navbarPrimaryType(primaryType),
-        })
-      : undefined;
-
-  return withoutUndefined({ links, primary });
-};
-
 const mintignorePatterns = async (root: string): Promise<string[]> => {
   try {
     const raw = await readFile(resolve(root, ".mintignore"), "utf-8");
@@ -678,78 +612,6 @@ const mintlifyRedirects = (
     return [{ from, to }];
   });
 
-const mintlifyContextual = (
-  value: unknown
-): NonNullable<BlumeConfig["contextual"]> => {
-  const object = asObject(value);
-  if (!object) {
-    return { options: [] };
-  }
-
-  const display = object.display === "toc" ? "toc" : "header";
-  const options: NonNullable<BlumeConfig["contextual"]>["options"] = [];
-  for (const option of asArray(object.options)) {
-    if (typeof option === "string") {
-      options.push(option);
-      continue;
-    }
-
-    const optionObject = asObject(option);
-    const title = optionObject ? asString(optionObject.title) : undefined;
-    if (!optionObject || !title) {
-      continue;
-    }
-
-    options.push(
-      withoutUndefined({
-        description: asString(optionObject.description),
-        href: asString(optionObject.href),
-        icon: asString(optionObject.icon),
-        title,
-      })
-    );
-  }
-
-  return { display, options };
-};
-
-const mintlifyFooter = (value: unknown): NonNullable<BlumeConfig["footer"]> => {
-  const object = asObject(value);
-  const socials = asObject(object?.socials);
-  const links = asArray(object?.links)
-    .flatMap((group) => {
-      const groupObject = asObject(group);
-      const items = asArray(groupObject?.items).flatMap((item) => {
-        const itemObject = asObject(item);
-        const label = itemObject ? asString(itemObject.label) : undefined;
-        const href = itemObject ? asString(itemObject.href) : undefined;
-        return label && href ? [{ href, label }] : [];
-      });
-      if (!groupObject || items.length === 0) {
-        return [];
-      }
-      return [
-        withoutUndefined({
-          header: asString(groupObject.header),
-          items,
-        }),
-      ];
-    })
-    .slice(0, 4);
-
-  return {
-    links,
-    socials: socials
-      ? Object.fromEntries(
-          Object.entries(socials).flatMap(([label, href]) => {
-            const hrefValue = asString(href);
-            return hrefValue ? [[label, hrefValue]] : [];
-          })
-        )
-      : {},
-  };
-};
-
 const mintlifyLogo = (value: unknown): BlumeConfig["logo"] => {
   if (typeof value === "string") {
     return value;
@@ -826,21 +688,13 @@ const mintlifyChromeVariants = (spec: JsonObject): NavigationChromeVariants => {
     const banner = hasOwn(object, "banner")
       ? mintlifyBanner(object.banner)
       : undefined;
-    const footer = hasOwn(object, "footer")
-      ? mintlifyFooter(object.footer)
-      : undefined;
-    const navbar = hasOwn(object, "navbar")
-      ? mintlifyNavbar(object.navbar)
-      : undefined;
-    if (!banner && !footer && !navbar) {
+    if (!banner) {
       return [];
     }
 
     return [
       withoutUndefined({
         banner,
-        footer,
-        navbar,
         path,
       }),
     ];
@@ -914,19 +768,6 @@ const mintlifyMarkdown = (
   });
 };
 
-const mintlifyStyling = (
-  value: unknown
-): NonNullable<BlumeConfig["styling"]> => {
-  const object = asObject(value);
-  const eyebrows = asString(object?.eyebrows);
-  return withoutUndefined({
-    eyebrows:
-      eyebrows === "breadcrumbs" || eyebrows === "section"
-        ? eyebrows
-        : undefined,
-  });
-};
-
 const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   const object = asObject(value);
   const metatags = asObject(object?.metatags);
@@ -942,17 +783,6 @@ const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   };
 };
 
-const mintlifyIcons = (value: unknown): NonNullable<BlumeConfig["icons"]> => {
-  const object = asObject(value);
-  const library = object?.library;
-  return withoutUndefined({
-    library:
-      library === "fontawesome" || library === "lucide" || library === "tabler"
-        ? library
-        : undefined,
-  });
-};
-
 export const loadMintlifyConfig = async (
   root: string,
   file: string
@@ -993,14 +823,10 @@ export const loadMintlifyConfig = async (
       ],
       root: ".",
     },
-    contextual: mintlifyContextual(spec.contextual),
     description: asString(spec.description),
     favicon: mintlifyFavicon(spec.favicon),
-    footer: mintlifyFooter(spec.footer),
-    icons: mintlifyIcons(spec.icons),
     logo: mintlifyLogo(spec.logo),
     markdown: mintlifyMarkdown(spec.markdown, styling),
-    navbar: mintlifyNavbar(spec.navbar),
     navigation: {
       chromeVariants: mintlifyChromeVariants(spec),
       selectors: mintlifySelectors(spec),
@@ -1016,7 +842,6 @@ export const loadMintlifyConfig = async (
       prompt: asString(search.prompt),
     },
     seo: mintlifySeo(seo),
-    styling: mintlifyStyling(styling),
     theme: {
       accent: asString(colors.primary) ?? "blue",
       accentDark: asString(colors.light),

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/migrate/starlight/config.ts

@@ -425,10 +425,6 @@ export const mapStarlightConfig = (
   }
 
   const social = mapSocial(options.social);
-  if (Object.keys(social.socials).length > 0) {
-    config.footer = { socials: social.socials };
-  }
-
   const github = mapEditLink(options.editLink) ?? social.github;
   if (github) {
     config.github = github;