blume 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/generate.ts

@@ -973,6 +973,11 @@ export const generateRuntime = async (
   // entryId so i18n duplicates of one entry write a single file.
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
+  // Only emit a project-scanning `docs` collection when a filesystem source
+  // actually feeds it. Bridge mode has just the staged Mintlify source, so the
+  // `docs` glob would otherwise scan (and watch) the whole project root for
+  // nothing — see contentConfigTemplate.
+  const hasFilesystemSource = project.sources.some((source) => !source.staged);
 
   const structural = await Promise.all([
     write(
@@ -1003,7 +1008,12 @@ export const generateRuntime = async (
     write(join(srcDir, "env.d.ts"), envTemplate()),
     write(
       join(srcDir, "content.config.ts"),
-      contentConfigTemplate({ config, context, staged: hasStaged })
+      contentConfigTemplate({
+        config,
+        context,
+        filesystem: hasFilesystemSource,
+        staged: hasStaged,
+      })
     ),
     write(
       join(srcDir, "pages", "[...slug].astro"),

package/src/astro/templates.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 
-import { dirname, join } from "pathe";
+import { dirname, isAbsolute, join, relative } from "pathe";
 
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
@@ -392,18 +392,44 @@ export const contentConfigTemplate = (options: {
   staged?: boolean;
   /** Base dir for the staged collection; defaults to `<outDir>/content`. */
   stagedBase?: string;
+  /**
+   * Whether any filesystem (non-staged) source feeds the `docs` collection.
+   * When false (e.g. Mintlify bridge mode, where every page is staged), the
+   * collection globs nothing — see below.
+   */
+  filesystem?: boolean;
 }): string => {
   const { context, config } = options;
   const stagedBase = options.stagedBase ?? stagedContentDir(context.outDir);
 
   // Fold the content excludes into the glob as negative patterns so the `docs`
-  // collection never walks into ignored trees. This matters when `content.root`
-  // is the project root (Mintlify bridge mode, or a migrated `.`-rooted project):
-  // without it the collection would scan `node_modules`, `snippets`, etc.
-  const docsPattern = [
-    ...config.content.include,
-    ...(config.content.exclude ?? []).map((pattern) => `!${pattern}`),
-  ];
+  // collection doesn't ingest ignored trees (`node_modules`, `snippets`, the
+  // staged bodies under `.blume/content`, …) as entries. This matters when
+  // `content.root` is the project root (a migrated `.`-rooted project).
+  const outDirRel = relative(context.contentRoot, context.outDir);
+  const outDirIgnore =
+    outDirRel && !outDirRel.startsWith("..") && !isAbsolute(outDirRel)
+      ? [`!${outDirRel}/**`]
+      : [];
+
+  // With no filesystem source, no route renders through `docs`, so glob nothing.
+  // Beyond skipping wasted work, this is the only thing that keeps Astro's
+  // content-layer *watcher* out of `.blume/`: bridge mode roots the collection
+  // at the project dir (which contains `.blume/.astro/fonts`, rewritten on every
+  // request), and the watcher's match test is `picomatch.isMatch(path, pattern)`
+  // — with array-OR semantics, any `!ignored/**` negation *matches* unrelated
+  // files, so negative patterns can't exclude a subtree there. An empty pattern
+  // matches nothing, so the watcher stays silent. The collection is still
+  // declared below so `getCollection("docs")` / `getEntry` resolve (to empty).
+  const filesystem = options.filesystem ?? true;
+  const docsPattern = filesystem
+    ? [
+        ...config.content.include,
+        ...(config.content.exclude ?? []).map((pattern) => `!${pattern}`),
+        "!**/node_modules/**",
+        ...outDirIgnore,
+      ]
+    : [];
 
   // Non-filesystem sources render through a parallel `staged` collection backed
   // by materialized MDX, so the filesystem `docs` collection stays untouched.

package/src/cli/commands/init.ts

@@ -5,35 +5,10 @@ import { defineCommand } from "citty";
 import { basename, dirname, isAbsolute, join, relative } from "pathe";
 
 import { ensureGitignore } from "../../core/gitignore.ts";
-import { getBlumeVersion } from "../../core/version.ts";
+import { blumePackageJson, toPackageName } from "../../core/package-json.ts";
 import { eject } from "../../registry/eject.ts";
 import { logger } from "../log.ts";
 
-/**
- * Derive a valid npm package name from a directory name, falling back to
- * `docs` when nothing usable remains.
- */
-const toPackageName = (raw: string): string =>
-  raw
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9._-]+/gu, "-")
-    .replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
-
-const packageTemplate = (name: string, version: string): string => `{
-  "name": ${JSON.stringify(name)},
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "blume dev",
-    "build": "blume build",
-    "doctor": "blume doctor"
-  },
-  "dependencies": {
-    "blume": "^${version}"
-  }
-}
-`;
-
 const TEMPLATES = ["docs", "api", "sdk", "changelog"] as const;
 type Template = (typeof TEMPLATES)[number];
 
@@ -221,7 +196,7 @@ export const initCommand = defineCommand({
     const starter = STARTERS[template];
     const createdPackage = await writeFileSafe(
       join(root, "package.json"),
-      packageTemplate(toPackageName(basename(root)), getBlumeVersion())
+      blumePackageJson(toPackageName(basename(root)))
     );
     await writeFileSafe(join(root, "blume.config.ts"), starter.config);
     await Promise.all(

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/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/migrate/mintlify/index.ts

@@ -4,7 +4,9 @@ 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, partitionMintlifyRedirects } from "./config.ts";
 import { mintlifyI18n } from "./i18n.ts";
@@ -188,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`.
@@ -324,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/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
 // ---------------------------------------------------------------------------