blume 0.5.0 → 0.5.2

package/src/core/navigation.ts

@@ -8,7 +8,6 @@ import type {
 import type {
   NavChromeVariant,
   NavNode,
-  NavSidebarVariant,
   Navigation,
   NavSelector,
   NavTab,
@@ -348,7 +347,6 @@ export const buildNavigation = (
     selectors?: NavSelector[];
     tabs?: NavTab[];
     sidebar?: SidebarItemConfig[];
-    sidebarVariants?: { path: string; items: SidebarItemConfig[] }[];
     /** Locale dir prefix for folder-meta lookup (`""` for the default locale). */
     metaPrefix?: string;
     /**
@@ -372,19 +370,12 @@ export const buildNavigation = (
       page,
     ])
   );
-  const sidebarVariants: NavSidebarVariant[] = (
-    options.sidebarVariants ?? []
-  ).map((variant) => ({
-    path: variant.path,
-    sidebar: buildConfigSidebar(variant.items, byRoute),
-  }));
 
   if (options.sidebar) {
     return {
       chromeVariants,
       selectors,
       sidebar: buildConfigSidebar(options.sidebar, byRoute),
-      sidebarVariants,
       tabs,
     };
   }
@@ -398,7 +389,6 @@ export const buildNavigation = (
       sharedFolderMeta,
       metaPrefix
     ),
-    sidebarVariants,
     tabs,
   };
 };

package/src/core/package-json.ts

@@ -0,0 +1,32 @@
+import { getBlumeVersion } from "./version.ts";
+
+/**
+ * Derive a valid npm package name from a directory name, falling back to
+ * `docs` when nothing usable remains.
+ */
+export const toPackageName = (raw: string): string =>
+  raw
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/gu, "-")
+    .replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
+
+/**
+ * A minimal, runnable `package.json` body for a Blume project: the `blume`
+ * dependency pinned to the installed version plus `dev`/`build`/`doctor`
+ * scripts, so `npm install && npm run dev` works immediately. Shared by
+ * `blume init` and the migrators, which scaffold one when a project has none.
+ */
+export const blumePackageJson = (name: string): string => `{
+  "name": ${JSON.stringify(name)},
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "blume dev",
+    "build": "blume build",
+    "doctor": "blume doctor"
+  },
+  "dependencies": {
+    "blume": "^${getBlumeVersion()}"
+  }
+}
+`;

package/src/core/schema.ts

@@ -483,13 +483,6 @@ const sidebarItemSchema: z.ZodType<SidebarItemConfig> = z.lazy(() =>
   ])
 );
 
-const sidebarVariantSchema = z
-  .object({
-    items: z.array(sidebarItemSchema).default([]),
-    path: z.string(),
-  })
-  .strict();
-
 const variablesConfigSchema = z
   .record(z.string().regex(/^[A-Za-z0-9-]+$/u), z.string())
   .default({});
@@ -666,7 +659,6 @@ const navigationConfigSchema = z
     selectors: z.array(navSelectorSchema).default([]),
     /** Explicit sidebar override; when omitted the sidebar is generated. */
     sidebar: z.array(sidebarItemSchema).optional(),
-    sidebarVariants: z.array(sidebarVariantSchema).default([]),
     tabs: z.array(navTabSchema).optional(),
   })
   .strict();

package/src/core/sources/mintlify.ts

@@ -1,4 +1,5 @@
 import { existsSync, watch as fsWatch } from "node:fs";
+import type { WatchListener } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 import { isAbsolute, join, relative, resolve } from "pathe";
@@ -42,6 +43,41 @@ const MINTLIFY_SOURCE_IGNORES = [
   "snippets/**",
 ];
 
+/**
+ * Directory names the recursive dev watcher must ignore. In bridge mode the
+ * content root is the project root, so a naive recursive `fs.watch` also sees
+ * Blume's own `.blume/` output — which the dev server rewrites on every request
+ * (`.blume/.astro/data-store.json`). Left unfiltered, each such write re-triggers
+ * a full rescan + runtime regeneration, whose writes land back under `.blume/`
+ * and fire the watcher again: a self-sustaining storm that stalls page renders
+ * and floods the console. `fs.watch` has no ignore option, so we filter by the
+ * changed path in the callback. Derived from {@link MINTLIFY_SOURCE_IGNORES}
+ * (dir prefixes) plus VCS metadata.
+ */
+const WATCH_IGNORE_DIRS = new Set([
+  ...MINTLIFY_SOURCE_IGNORES.map((pattern) => pattern.replace(/\/\*\*$/u, "")),
+  ".git",
+]);
+
+/**
+ * Build the recursive-watch listener: fire `onChange` for content changes but
+ * ignore events whose path crosses a {@link WATCH_IGNORE_DIRS} segment (Blume's
+ * own `.blume/` output, `node_modules`, VCS metadata, …). A missing `filename`
+ * — rare; the platform couldn't name the changed path — falls through to
+ * regenerate rather than silently dropping a real edit. Exported for testing.
+ */
+export const mintlifyWatchListener =
+  (onChange: () => void): WatchListener<string> =>
+  (_event, filename) => {
+    if (
+      typeof filename === "string" &&
+      filename.split(/[/\\]/u).some((segment) => WATCH_IGNORE_DIRS.has(segment))
+    ) {
+      return;
+    }
+    onChange();
+  };
+
 /**
  * The Mintlify bridge content source. Reads an unconverted Mintlify project in
  * place and transforms each page to Blume MDX at scan time (callouts → `:::`
@@ -126,7 +162,14 @@ export const mintlifySource = (
   const watch = (onChange: () => void): (() => void) => {
     const disposers: (() => void)[] = [];
     if (existsSync(contentRoot)) {
-      const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
+      // Recursively watch the content root, but skip Blume's own output and
+      // other non-content trees so the dev server's `.blume/` writes don't feed
+      // a regeneration loop (`fs.watch` has no ignore option, so filter here).
+      const watcher = fsWatch(
+        contentRoot,
+        { recursive: true },
+        mintlifyWatchListener(onChange)
+      );
       disposers.push(() => watcher.close());
     }
     // Watch docs.json directly: it lives at the content root but a non-recursive

package/src/core/types.ts

@@ -180,12 +180,6 @@ export interface NavSelector {
   items: NavSelectorItem[];
 }
 
-/** Sidebar tree used when the current route belongs to a nav partition. */
-export interface NavSidebarVariant {
-  path: string;
-  sidebar: NavNode[];
-}
-
 /** Chrome overrides used when the current route belongs to a nav partition. */
 export interface NavChromeVariant {
   path: string;
@@ -198,7 +192,6 @@ export interface Navigation {
   selectors: NavSelector[];
   chromeVariants: NavChromeVariant[];
   sidebar: NavNode[];
-  sidebarVariants: NavSidebarVariant[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
   repoUrl?: string | null;
 }

package/src/migrate/mintlify/config.ts

@@ -17,8 +17,6 @@ type NavigationSelectorItem = NavigationSelectors[number]["items"][number];
 type NavigationChromeVariants = NonNullable<
   BlumeConfig["navigation"]
 >["chromeVariants"];
-type NavigationSidebarVariants =
-  ResolvedConfig["navigation"]["sidebarVariants"];
 
 const MINTLIFY_DEFAULT_IGNORES = [
   "**/_*",
@@ -307,18 +305,6 @@ const mintlifyBackgroundDecoration = (
   return undefined;
 };
 
-const sidebarItemPaths = (items: SidebarItemConfig[]): string[] =>
-  items.flatMap((item) => {
-    if (typeof item === "string") {
-      return [tabPathFromRef(item)];
-    }
-    if (item.href) {
-      return [item.href];
-    }
-    const paths = item.root ? [tabPathFromRef(item.root)] : [];
-    return item.items ? [...paths, ...sidebarItemPaths(item.items)] : paths;
-  });
-
 const collapsedFromExpanded = (value: unknown): boolean | undefined => {
   if (value === false) {
     return true;
@@ -439,79 +425,6 @@ const isExternalRoute = (path: string): boolean =>
   path.startsWith("mailto:") ||
   path.startsWith("tel:");
 
-const hasOwnNavigationContent = (item: JsonObject): boolean =>
-  Boolean(asString(item.root)) || childItemsFor(item).length > 0;
-
-const mintlifySidebarVariants = async (
-  spec: JsonObject
-): Promise<NavigationSidebarVariants> => {
-  const navigation = asObject(spec.navigation) ?? {};
-  const global = asObject(navigation.global) ?? {};
-  interface SidebarVariantCandidate {
-    item: unknown;
-    path: string;
-  }
-  const candidates: SidebarVariantCandidate[] = [];
-
-  const addCandidate = (item: unknown): void => {
-    const path = navItemPath(item);
-    if (!path || isExternalRoute(path)) {
-      return;
-    }
-
-    candidates.push({ item, path });
-  };
-
-  for (const item of [
-    ...asArray(navigation.tabs),
-    ...asArray(navigation.anchors),
-    ...asArray(global.anchors),
-  ]) {
-    const object = asObject(item);
-    if (!object) {
-      addCandidate(item);
-      continue;
-    }
-
-    for (const menuItem of asArray(object.menu)) {
-      addCandidate(menuItem);
-    }
-
-    if (hasOwnNavigationContent(object)) {
-      addCandidate(item);
-    }
-  }
-
-  for (const item of [
-    ...asArray(navigation.dropdowns),
-    ...asArray(navigation.products),
-    ...asArray(navigation.versions),
-    ...asArray(navigation.languages),
-  ]) {
-    addCandidate(item);
-  }
-
-  const resolved = await Promise.all(
-    candidates.map(async (candidate) => {
-      const items = await toSidebarItems([candidate.item], {});
-      if (items.length === 0) {
-        return [];
-      }
-      return [candidate.path, ...sidebarItemPaths(items)]
-        .filter((path) => !isExternalRoute(path))
-        .map((path) => ({ items, path }));
-    })
-  );
-  const seen = new Set<string>();
-  return resolved.flat().flatMap((variant) => {
-    if (!variant || seen.has(variant.path)) {
-      return [];
-    }
-    seen.add(variant.path);
-    return [variant];
-  });
-};
-
 const mintlifyTabs = (
   spec: JsonObject
 ): NonNullable<BlumeConfig["navigation"]>["tabs"] => {
@@ -604,24 +517,53 @@ const toAstroRedirectPath = (path: string): string =>
     modifier === "*" || modifier === "+" ? `[...${name}]` : `[${name}]`
   );
 
-const mintlifyRedirects = (
+// A converted path is dynamic once it holds an Astro segment (`[id]`/`[...slug]`
+// from a `:param`). Blume redirects are static path-to-path: a dynamic segment
+// has no matching route, so Astro aborts the build ("destination does not match
+// any existing route"), and the platform redirect files emit the segment
+// verbatim, which no host understands. Such redirects are dropped, not emitted.
+const isDynamicRedirectPath = (path: string): boolean => path.includes("[");
+
+export interface MintlifyRedirectPartition {
+  /** Static redirects Blume can honor, translated to Blume's `from`/`to` shape. */
+  kept: NonNullable<BlumeConfig["redirects"]>;
+  /** Source paths of dynamic redirects dropped because Blume can't model them. */
+  dropped: string[];
+}
+
+/**
+ * Split a spec's redirects into the static ones Blume emits and the dynamic
+ * (wildcard/param) ones it drops. Keeping a dynamic redirect crashes the Astro
+ * build, so the migrator surfaces the dropped sources as a warning instead.
+ */
+export const partitionMintlifyRedirects = (
   spec: JsonObject
-): NonNullable<BlumeConfig["redirects"]> =>
-  asArray(spec.redirects).flatMap((redirect) => {
+): MintlifyRedirectPartition => {
+  const kept: NonNullable<BlumeConfig["redirects"]> = [];
+  const dropped: string[] = [];
+  for (const redirect of asArray(spec.redirects)) {
     const object = asObject(redirect);
     if (!object) {
-      return [];
+      continue;
     }
-    const from = asString(object.source) ?? asString(object.from);
-    const to =
+    const source = asString(object.source) ?? asString(object.from);
+    const destination =
       asString(object.destination) ??
       asString(object.to) ??
       asString(object.redirect);
-    if (!from || !to) {
-      return [];
+    if (!source || !destination) {
+      continue;
     }
-    return [{ from: toAstroRedirectPath(from), to: toAstroRedirectPath(to) }];
-  });
+    const from = toAstroRedirectPath(source);
+    const to = toAstroRedirectPath(destination);
+    if (isDynamicRedirectPath(from) || isDynamicRedirectPath(to)) {
+      dropped.push(source);
+    } else {
+      kept.push({ from, to });
+    }
+  }
+  return { dropped, kept };
+};
 
 interface OpenApiSourceDraft {
   label?: string;
@@ -981,11 +923,10 @@ export const loadMintlifyConfig = async (
       chromeVariants: mintlifyChromeVariants(spec),
       selectors: mintlifySelectors(spec),
       sidebar: await toSidebarItems(mintlifyNavigationItems(navigation), {}),
-      sidebarVariants: await mintlifySidebarVariants(spec),
       tabs: mintlifyTabs(spec),
     },
     openapi: mintlifyOpenapi(spec),
-    redirects: mintlifyRedirects(spec),
+    redirects: partitionMintlifyRedirects(spec).kept,
     search: {
       indexing: {
         includeHiddenPages: seo.indexing === "all",

package/src/migrate/mintlify/content.ts

@@ -56,6 +56,22 @@ export const rewriteMintlifyExampleBlocks = (source: string): string =>
     "<$<close>CodeGroup"
   );
 
+/**
+ * Mintlify nests `<Accordion title="…">` items inside an `<AccordionGroup>`.
+ * Blume inverts that: `<Accordion>` is the container and each item is an
+ * `<AccordionItem title="…">`. Rewrite both in a single pass — the `\b` after
+ * `Accordion` keeps `<AccordionGroup>` (the `Group` branch) distinct from an
+ * item, so open/close tags of either map correctly regardless of order. Without
+ * this, migrated pages keep `<AccordionGroup>`, which Blume doesn't ship and the
+ * MDX build rejects with "Expected component AccordionGroup to be defined".
+ */
+export const rewriteMintlifyAccordions = (source: string): string =>
+  source.replaceAll(
+    /<(?<close>\/?)Accordion(?<group>Group)?\b/gu,
+    (_match, close: string, group: string | undefined) =>
+      group ? `<${close}Accordion` : `<${close}AccordionItem`
+  );
+
 const SNIPPET_IMPORT =
   /^import\s+[\s\S]*?\s+from\s+["'](?<source>\/snippets\/[^"']+)["'];?[ \t]*\n?/gmu;
 

package/src/migrate/mintlify/index.ts

@@ -4,9 +4,11 @@ import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "pathe";
 import { glob } from "tinyglobby";
 
+import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeConfig } from "../../core/schema.ts";
+import { ensurePackageJson } from "../shared.ts";
 import { assetSegments } from "./assets.ts";
-import { loadMintlifyConfig } from "./config.ts";
+import { loadMintlifyConfig, partitionMintlifyRedirects } from "./config.ts";
 import { mintlifyI18n } from "./i18n.ts";
 import { transformMintlifyContent } from "./transform.ts";
 
@@ -65,6 +67,22 @@ const droppedChromeWarnings = (
   return warnings;
 };
 
+/**
+ * Warn about dynamic (wildcard/param) redirects the migrator dropped. Blume
+ * redirects are static path-to-path, so a `:slug*`/`:id` source becomes an
+ * unroutable Astro destination — kept ones crash the build. Point the user at
+ * host-level rules that do support wildcards.
+ */
+const droppedRedirectWarnings = (spec: Record<string, unknown>): string[] => {
+  const { dropped } = partitionMintlifyRedirects(spec);
+  if (dropped.length === 0) {
+    return [];
+  }
+  return [
+    `Dropped ${dropped.length} dynamic redirect(s) Blume can't model as static path-to-path (${dropped.join(", ")}); re-add them as host-level rules (e.g. _redirects or vercel.json).`,
+  ];
+};
+
 /** Recursively drop `undefined`, empty arrays, and empty objects. */
 const prune = (value: unknown): unknown => {
   if (Array.isArray(value)) {
@@ -172,6 +190,27 @@ const applyRelocatedAssets = (
   }
 };
 
+/**
+ * Scaffold the project files a config-only Mintlify repo lacks: a runnable
+ * `package.json` (it ships no npm manifest) and a `.gitignore` for Blume's
+ * generated `.blume/` runtime and `dist/` build output. Both are idempotent —
+ * an existing file is extended, not overwritten — and noted in the warnings.
+ */
+const scaffoldProjectFiles = async (
+  root: string,
+  warnings: string[]
+): Promise<void> => {
+  if (await ensurePackageJson(root)) {
+    warnings.push(
+      "Created a package.json with blume as a dependency; run `npm install`, then `npm run dev`."
+    );
+  }
+  const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
+  if (ignored.length > 0) {
+    warnings.push(`Added ${ignored.join(", ")} to .gitignore.`);
+  }
+};
+
 /**
  * Delete the inlined markdown snippets. Component files (e.g. `.jsx`) are kept
  * because their imports were rewritten to resolve against `/snippets`.
@@ -247,6 +286,7 @@ export const migrateMintlifyProject = async (
       );
     }
     warnings.push(...droppedChromeWarnings(spec, config));
+    warnings.push(...droppedRedirectWarnings(spec));
   } else {
     warnings.push("No docs.json or mint.json found; writing a default config.");
     config = { content: { root: "." }, title: "Documentation" };
@@ -307,6 +347,7 @@ export const migrateMintlifyProject = async (
   }
   applyRelocatedAssets(config, assets, warnings);
   await writeBlumeConfig(root, config);
+  await scaffoldProjectFiles(root, warnings);
 
   if (Object.keys(variables).length > 0) {
     warnings.push(

package/src/migrate/mintlify/transform.ts

@@ -1,6 +1,7 @@
 import matter from "../../core/frontmatter.ts";
 import { stripUnknownPageMeta } from "../shared.ts";
 import {
+  rewriteMintlifyAccordions,
   rewriteMintlifyCallouts,
   rewriteMintlifyExampleBlocks,
   rewriteSnippetImports,
@@ -59,6 +60,7 @@ export const transformMintlifyContent = async (
   text = snippetImports.source;
   text = rewriteMintlifySvgIconProps(text);
   text = rewriteMintlifyExampleBlocks(text);
+  text = rewriteMintlifyAccordions(text);
   text = rewriteMintlifyCallouts(text);
 
   const unsupported = unsupportedMintlifyComponents(text);

package/src/migrate/shared.ts

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 
-import { isAbsolute, join, relative } from "pathe";
+import { basename, isAbsolute, join, relative } from "pathe";
 
+import { blumePackageJson, toPackageName } from "../core/package-json.ts";
 import type { BlumeConfig } from "../core/schema.ts";
 import { pageMetaSchema } from "../core/schema.ts";
 
@@ -102,6 +103,28 @@ export const rewriteFrameworkScripts = async (
 export const leftoverFiles = (root: string, candidates: string[]): string[] =>
   candidates.filter((candidate) => existsSync(join(root, candidate)));
 
+/**
+ * Scaffold a minimal, runnable `package.json` when the migrated project has
+ * none. Config-only sources (e.g. a Mintlify `docs.json`) ship no npm manifest,
+ * so a fresh migration has nothing to run `blume dev` with; this writes a stub
+ * with `blume` as a dependency and `dev`/`build`/`doctor` scripts, making
+ * `npm install && npm run dev` work immediately. A pre-existing `package.json`
+ * is left untouched — {@link rewriteFrameworkScripts} repoints those instead.
+ * Returns true when a file was created.
+ */
+export const ensurePackageJson = async (root: string): Promise<boolean> => {
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    return false;
+  }
+  await writeFile(
+    pkgPath,
+    blumePackageJson(toPackageName(basename(root))),
+    "utf-8"
+  );
+  return true;
+};
+
 // ---------------------------------------------------------------------------
 // Callout components -> Blume `:::` directives
 // ---------------------------------------------------------------------------