blume 0.5.2 → 0.5.4

package/src/astro/static-assets.ts

@@ -1,117 +0,0 @@
-import { createReadStream, existsSync, statSync } from "node:fs";
-import type { Stats } from "node:fs";
-import { cp } from "node:fs/promises";
-import type { IncomingMessage, ServerResponse } from "node:http";
-
-import { extname, join, relative, resolve, sep } from "pathe";
-
-import type { AssetMount } from "../core/assets.ts";
-
-/** Content types for the asset extensions a docs project commonly serves. */
-const MIME_TYPES: Record<string, string> = {
-  ".avif": "image/avif",
-  ".css": "text/css; charset=utf-8",
-  ".gif": "image/gif",
-  ".ico": "image/x-icon",
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".js": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".mp4": "video/mp4",
-  ".otf": "font/otf",
-  ".pdf": "application/pdf",
-  ".png": "image/png",
-  ".svg": "image/svg+xml",
-  ".ttf": "font/ttf",
-  ".txt": "text/plain; charset=utf-8",
-  ".webm": "video/webm",
-  ".webp": "image/webp",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-};
-
-const mimeType = (file: string): string =>
-  MIME_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
-
-/** Whether `child` is `parent` itself or a path nested under it. */
-const isContained = (parent: string, child: string): boolean => {
-  const rel = relative(parent, child);
-  return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep));
-};
-
-/** Resolve a request URL to an on-disk file within one of the mounts, if any. */
-const resolveRequest = (url: string, mounts: AssetMount[]): string | null => {
-  const pathname = decodeURIComponent(
-    (url.split("?")[0] ?? "").split("#")[0] ?? ""
-  );
-  for (const mount of mounts) {
-    if (pathname !== mount.url && !pathname.startsWith(`${mount.url}/`)) {
-      continue;
-    }
-    // `.` + rel keeps the join relative so an absolute-looking suffix can't
-    // escape the mount; the containment check rejects `..` traversal outright.
-    const file = resolve(mount.dir, `.${pathname.slice(mount.url.length)}`);
-    if (isContained(mount.dir, file)) {
-      return file;
-    }
-  }
-  return null;
-};
-
-/** `statSync` that returns null instead of throwing on a missing file. */
-const statFile = (file: string): Stats | null => {
-  try {
-    return statSync(file);
-  } catch {
-    return null;
-  }
-};
-
-/**
- * A dev-server middleware that serves `content.assets` mounts (top-level dirs
- * kept in place, e.g. a migrated `images/`) at their site URL. Astro only serves
- * `publicDir` in dev, so without this those references would 404. Non-matching
- * requests, and any path that isn't a real file, fall through to Astro. Stat is
- * synchronous — this is dev-only middleware and mirrors how sirv serves statics.
- */
-export const serveAssetMounts =
-  (mounts: AssetMount[]) =>
-  (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
-    if ((req.method !== "GET" && req.method !== "HEAD") || !req.url) {
-      next();
-      return;
-    }
-    const file = resolveRequest(req.url, mounts);
-    const stats = file ? statFile(file) : null;
-    if (!(file && stats?.isFile())) {
-      next();
-      return;
-    }
-    res.setHeader("Content-Type", mimeType(file));
-    res.setHeader("Content-Length", String(stats.size));
-    if (req.method === "HEAD") {
-      res.end();
-      return;
-    }
-    createReadStream(file).pipe(res);
-  };
-
-/**
- * Copy every asset mount into the build output, mirroring what Astro does with
- * `publicDir`. Runs on `astro:build:done` so in-place asset dirs ship in the
- * final `dist/`. A missing source dir is skipped (it may be referenced but
- * absent); `cp` handles both directories and single files.
- */
-export const copyAssetMounts = async (
-  mounts: AssetMount[],
-  outDir: string
-): Promise<void> => {
-  for (const mount of mounts) {
-    if (!existsSync(mount.dir)) {
-      continue;
-    }
-    const dest = join(outDir, mount.url.replace(/^\/+/u, ""));
-    // oxlint-disable-next-line no-await-in-loop -- sequential fs copies
-    await cp(mount.dir, dest, { recursive: true });
-  }
-};

package/src/cli/commands/migrate.ts

@@ -1,39 +0,0 @@
-import { defineCommand } from "citty";
-
-import { migrators } from "../../migrate/migrate.ts";
-import { logger } from "../log.ts";
-
-const makeMigrateCommand = (source: keyof typeof migrators) =>
-  defineCommand({
-    meta: {
-      description: `Migrate a ${source} project to Blume.`,
-      name: source,
-    },
-    async run() {
-      const root = process.cwd();
-      logger.start(`Migrating ${source} project`);
-      const result = await migrators[source]?.(root);
-      if (!result) {
-        logger.error(`No migrator for ${source}.`);
-        process.exit(1);
-      }
-      logger.success(`Migrated ${result.moved} content file(s).`);
-      for (const warning of result.warnings) {
-        logger.warn(warning);
-      }
-      logger.box("Review blume.config.ts and run `blume dev`.");
-    },
-  });
-
-export const migrateCommand = defineCommand({
-  meta: {
-    description: "Migrate from another docs tool to Blume.",
-    name: "migrate",
-  },
-  subCommands: {
-    fumadocs: makeMigrateCommand("fumadocs"),
-    mintlify: makeMigrateCommand("mintlify"),
-    nextra: makeMigrateCommand("nextra"),
-    starlight: makeMigrateCommand("starlight"),
-  },
-});

package/src/components/content/ApiField.astro

@@ -1,75 +0,0 @@
----
-// Shared field row behind the Mintlify-compat <ParamField>/<ResponseField>/
-// <RequestField> components: a labeled name + type + badges, with the field's
-// description rendered from the slot (which may hold rich MDX, including nested
-// <Expandable> or further fields). Styled to match the native OpenAPI reference
-// rows (src/components/openapi/), so a migrated site reads consistently.
-interface Props {
-  default?: unknown;
-  deprecated?: unknown;
-  location?: string;
-  name?: string;
-  required?: unknown;
-  type?: string;
-}
-
-const {
-  default: defaultValue,
-  deprecated,
-  location,
-  name,
-  required,
-  type,
-} = Astro.props;
-
-// Booleans arrive as MDX shorthand (`required`) or strings (`required="true"`).
-const isTrue = (value: unknown): boolean => value === true || value === "true";
-const hasDefault =
-  defaultValue !== undefined && defaultValue !== null && defaultValue !== "";
-const hasDescription = Astro.slots.has("default");
----
-
-<div class="not-prose my-2 rounded-blume border border-border px-4 py-3">
-  <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
-    {name && <code class="font-mono text-foreground text-sm">{name}</code>}
-    {
-      location && (
-        <span class="rounded bg-muted px-1.5 py-0.5 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
-          {location}
-        </span>
-      )
-    }
-    {type && <span class="text-muted-foreground text-xs">{type}</span>}
-    {
-      isTrue(required) && (
-        <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
-          required
-        </span>
-      )
-    }
-    {
-      isTrue(deprecated) && (
-        <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
-          deprecated
-        </span>
-      )
-    }
-  </div>
-  {
-    hasDefault && (
-      <div class="mt-1 text-muted-foreground text-xs">
-        Default:{" "}
-        <code class="rounded bg-muted px-1 py-0.5 text-foreground">
-          {String(defaultValue)}
-        </code>
-      </div>
-    )
-  }
-  {
-    hasDescription && (
-      <div class="mt-1.5 text-muted-foreground text-sm [&>:first-child]:mt-0 [&>:last-child]:mb-0">
-        <slot />
-      </div>
-    )
-  }
-</div>

package/src/components/content/ParamField.astro

@@ -1,39 +0,0 @@
----
-// Mintlify-compat <ParamField>. Mintlify encodes the parameter's location in the
-// attribute name (`<ParamField path="id" />`, `query`, `header`, `body`); the
-// attribute's value is the field name. Falls back to a plain `name` prop.
-import ApiField from "./ApiField.astro";
-
-const {
-  body,
-  default: defaultValue,
-  deprecated,
-  header,
-  name,
-  path,
-  query,
-  required,
-  type,
-} = Astro.props;
-
-const locations = [
-  { key: "path", value: path },
-  { key: "query", value: query },
-  { key: "header", value: header },
-  { key: "body", value: body },
-] as const;
-const located = locations.find((entry) => typeof entry.value === "string");
-const fieldName = located ? located.value : name;
-const location = located?.key;
----
-
-<ApiField
-  default={defaultValue}
-  deprecated={deprecated}
-  location={location}
-  name={fieldName}
-  required={required}
-  type={type}
->
-  <slot />
-</ApiField>

package/src/components/content/RequestField.astro

@@ -1,23 +0,0 @@
----
-// Mintlify-compat <RequestField>: same shape as <ResponseField> — a named field
-// (`name`, `type`, `required`, `default`, `deprecated`) with a slotted body.
-import ApiField from "./ApiField.astro";
-
-const {
-  default: defaultValue,
-  deprecated,
-  name,
-  required,
-  type,
-} = Astro.props;
----
-
-<ApiField
-  default={defaultValue}
-  deprecated={deprecated}
-  name={name}
-  required={required}
-  type={type}
->
-  <slot />
-</ApiField>

package/src/components/content/ResponseField.astro

@@ -1,23 +0,0 @@
----
-// Mintlify-compat <ResponseField>: a named field (`name`, `type`, `required`,
-// `default`, `deprecated`) with its description in the slot.
-import ApiField from "./ApiField.astro";
-
-const {
-  default: defaultValue,
-  deprecated,
-  name,
-  required,
-  type,
-} = Astro.props;
----
-
-<ApiField
-  default={defaultValue}
-  deprecated={deprecated}
-  name={name}
-  required={required}
-  type={type}
->
-  <slot />
-</ApiField>

package/src/components/content/Warning.astro

@@ -1,9 +0,0 @@
----
-import Callout from "./Callout.astro";
-
-const { title } = Astro.props;
----
-
-<Callout title={title} type="warning">
-  <slot />
-</Callout>

package/src/core/assets.ts

@@ -1,31 +0,0 @@
-import { join } from "pathe";
-
-/** A static directory served at a URL prefix, in addition to `public/`. */
-export interface AssetMount {
-  /** Absolute filesystem path to the source directory (or file). */
-  dir: string;
-  /** URL path prefix the source is served at, e.g. `/images`. */
-  url: string;
-}
-
-/**
- * Resolve `content.assets` entries (top-level dirs served at the site root,
- * alongside `public/`) to `{ dir, url }` mounts. Shared by the generated Astro
- * runtime (dev middleware + build copy) and by link validation, so all three
- * agree on where a `/images/foo.png` reference resolves on disk.
- *
- * Each entry is normalized to a leading-slash URL and joined to the project
- * root; leading `./` or `/` and any `..` segments are stripped so a mount can't
- * escape the root or collide with the site's own routing prefix.
- */
-export const resolveAssetMounts = (
-  root: string,
-  assets: string[]
-): AssetMount[] =>
-  assets.map((entry) => {
-    const rel = entry
-      .replace(/^[./]+/u, "")
-      .replaceAll(/\.\.\/?/gu, "")
-      .replace(/\/+$/u, "");
-    return { dir: join(root, rel), url: `/${rel}` };
-  });

package/src/core/bridge.ts

@@ -1,102 +0,0 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-
-import { join } from "pathe";
-
-import { assetSegments } from "../migrate/mintlify/assets.ts";
-import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
-import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
-import type { BlumeConfig } from "./schema.ts";
-
-/** A detected docs-tool config that Blume can serve without a migration. */
-export interface BridgeDetection {
-  /** Which foreign docs tool was detected. */
-  tool: "mintlify";
-  /** Absolute path of the detected config file (`docs.json`/`mint.json`). */
-  configFile: string;
-  /** A Blume config synthesized from the foreign config, ready to validate. */
-  raw: BlumeConfig;
-}
-
-const MINTLIFY_CONFIG_FILES = ["docs.json", "mint.json"];
-
-/**
- * Detect a Mintlify project at `root` and synthesize an equivalent Blume config.
- *
- * "Bridge mode" lets a team swap `mintlify dev` for `blume dev` with no file
- * changes: `docs.json` is translated to Blume config (`loadMintlifyConfig`) and
- * its content block is rewired to a single `mintlify` content source, which
- * transforms each MDX page to Blume idiom at scan time. The original
- * `content.root`/`exclude` and `variables` move onto the source (Blume has no
- * runtime variable substitution, so globals are inlined into content there).
- *
- * Returns `null` when no Mintlify config is present. Only called when no
- * `blume.config.*` exists, so an explicit Blume config always takes precedence.
- */
-export const detectMintlifyBridge = async (
-  root: string
-): Promise<BridgeDetection | null> => {
-  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join(root, name)).find(
-    (candidate) => existsSync(candidate)
-  );
-  if (!configFile) {
-    return null;
-  }
-
-  const config = await loadMintlifyConfig(root, configFile);
-
-  // i18n is derived from the raw spec (language dirs), mirroring the migrator.
-  const spec = JSON.parse(await readFile(configFile, "utf-8")) as Record<
-    string,
-    unknown
-  >;
-  const i18n = mintlifyI18n(spec);
-  if (i18n) {
-    config.i18n = i18n;
-    // Language switching is handled by Blume i18n, not a nav selector.
-    if (config.navigation?.selectors) {
-      config.navigation.selectors = config.navigation.selectors.filter(
-        (selector) => selector.kind !== "language"
-      );
-    }
-  }
-
-  const variables = (config.variables as Record<string, string>) ?? {};
-  const root_ = config.content?.root ?? ".";
-  const exclude = config.content?.exclude ?? [];
-
-  // Mintlify serves assets from the project root; the bridge never moves files,
-  // so referenced root-level asset folders (e.g. `images/`) are served in place
-  // via `content.assets` instead. This is the read-only twin of the migrator's
-  // relocation — same referenced segments, just no `public/` move.
-  const assets = assetSegments(config).filter(
-    (segment) => segment !== "public" && existsSync(join(root, segment))
-  );
-
-  return {
-    configFile,
-    raw: {
-      ...config,
-      content: {
-        assets,
-        // Mirror the excludes onto `content.exclude` too: the generated Astro
-        // `docs` collection globs `content.root` (here the project root) and
-        // must skip node_modules/snippets just like the source does.
-        exclude,
-        root: root_,
-        sources: [
-          {
-            configFile,
-            exclude,
-            root: root_,
-            type: "mintlify",
-            variables,
-          },
-        ],
-      },
-      // Globals are inlined into content by the source; drop the top-level copy.
-      variables: undefined,
-    },
-    tool: "mintlify",
-  };
-};

package/src/core/sources/mintlify.ts

@@ -1,204 +0,0 @@
-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";
-import { glob } from "tinyglobby";
-
-import { transformMintlifyContent } from "../../migrate/mintlify/transform.ts";
-import { BlumeError } from "../diagnostics.ts";
-import matter from "../frontmatter.ts";
-import type { Diagnostic } from "../types.ts";
-import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
-
-/** Options for the Mintlify bridge content source. */
-export interface MintlifySourceOptions {
-  /** Stable source name; namespaces ids and diagnostics. */
-  name: string;
-  /** Optional route prefix. */
-  prefix?: string;
-  /** Content root, absolute or relative to `projectRoot` (Mintlify: `.`). */
-  root: string;
-  include: string[];
-  exclude: string[];
-  /** `docs.json` variables, inlined into content (`{{name}}`) at scan time. */
-  variables: Record<string, string>;
-  /** Absolute path of the `docs.json`/`mint.json`, watched for changes in dev. */
-  configFile?: string;
-  /** Absolute project root, used to resolve a relative `root`. */
-  projectRoot: string;
-}
-
-/**
- * Folders Mintlify projects keep alongside content that are never pages:
- * snippets are inlined as includes, and build/tooling dirs are noise. Merged
- * with the user's `exclude` so bridge mode behaves like the one-shot migrator.
- */
-const MINTLIFY_SOURCE_IGNORES = [
-  "node_modules/**",
-  ".blume/**",
-  "dist/**",
-  "build/**",
-  "public/**",
-  "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 → `:::`
- * directives, snippet/variable inlining, etc.) via `transformMintlifyContent`.
- * Staged: the transformed bodies are materialized under `.blume/content` and
- * rendered through Astro's `staged` collection, so the rewrites actually reach
- * the output. Components Blume already ships (Card, Tabs, Steps, …) render as-is.
- */
-export const mintlifySource = (
-  options: MintlifySourceOptions
-): ContentSource & { readonly contentRoot: string } => {
-  const contentRoot = isAbsolute(options.root)
-    ? options.root
-    : join(resolve(options.projectRoot), options.root);
-  const ignore = [...new Set([...options.exclude, ...MINTLIFY_SOURCE_IGNORES])];
-
-  const transform = (
-    raw: string,
-    file: string
-  ): ReturnType<typeof transformMintlifyContent> =>
-    transformMintlifyContent(raw, {
-      filePath: file,
-      root: resolve(options.projectRoot),
-      variables: options.variables,
-    });
-
-  const load = async (): Promise<SourceLoadResult> => {
-    const files = await glob(options.include, {
-      absolute: true,
-      cwd: contentRoot,
-      ignore,
-      onlyFiles: true,
-    });
-    files.sort();
-
-    const unsupported = new Set<string>();
-    const entries = await Promise.all(
-      files.map(async (file): Promise<SourceEntry> => {
-        const result = await transform(await readFile(file, "utf-8"), file);
-        for (const name of result.unsupported) {
-          unsupported.add(name);
-        }
-        const parsed = matter(result.content);
-        // Force MDX: Mintlify pages are MDX-authored and the rewrites emit `:::`
-        // directives + JSX, neither of which the plain `.md` processor expands.
-        return {
-          body: { format: "mdx", text: parsed.content },
-          data: parsed.data,
-          raw: result.content,
-          ref: relative(contentRoot, file),
-          sourcePath: file,
-        };
-      })
-    );
-
-    const diagnostics: Diagnostic[] =
-      unsupported.size > 0
-        ? [
-            {
-              code: "BLUME_MINTLIFY_UNSUPPORTED",
-              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Replace them by hand or provide a matching component.`,
-              severity: "warning",
-            },
-          ]
-        : [];
-
-    return { diagnostics, entries };
-  };
-
-  const validate = (): void => {
-    if (!existsSync(contentRoot)) {
-      throw new BlumeError({
-        code: "BLUME_CONTENT_ROOT_MISSING",
-        file: contentRoot,
-        message: `Content root not found: ${options.root}`,
-        severity: "error",
-        suggestion: `Run "blume dev" from the directory that contains docs.json.`,
-      });
-    }
-  };
-
-  const watch = (onChange: () => void): (() => void) => {
-    const disposers: (() => void)[] = [];
-    if (existsSync(contentRoot)) {
-      // 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
-    // single-file watch fires reliably on edits that recursive dir-watch can miss.
-    if (options.configFile && existsSync(options.configFile)) {
-      const watcher = fsWatch(options.configFile, onChange);
-      disposers.push(() => watcher.close());
-    }
-    return () => {
-      for (const dispose of disposers) {
-        dispose();
-      }
-    };
-  };
-
-  const read = async (ref: string): Promise<string> => {
-    const file = join(contentRoot, ref);
-    const result = await transform(await readFile(file, "utf-8"), file);
-    return result.content;
-  };
-
-  return {
-    contentRoot,
-    load,
-    name: options.name,
-    prefix: options.prefix,
-    read,
-    staged: true,
-    validate,
-    watch,
-  };
-};