blume 0.0.0 → 0.1.1

package/src/registry/eject.ts

@@ -0,0 +1,310 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+
+import { join, relative } from "pathe";
+
+import { resolveAskBackend } from "../ai/ask.ts";
+import { buildRawMarkdown } from "../ai/markdown.ts";
+import { discoverExamples } from "../astro/examples.ts";
+import {
+  buildRuntimeData,
+  collectStaged,
+  detectNeedsReact,
+} from "../astro/generate.ts";
+import { discoverIslands } from "../astro/islands.ts";
+import { customOgRoutes, discoverPages } from "../astro/pages.ts";
+import {
+  askEndpointTemplate,
+  astroConfigTemplate,
+  catchAllPageTemplate,
+  contentConfigTemplate,
+  envTemplate,
+  exampleMapTemplate,
+  exampleWrapperTemplate,
+  exampleSlug,
+  islandMapTemplate,
+  islandWrapperTemplate,
+  mixedbreadSearchEndpointTemplate,
+  ogEndpointTemplate,
+  rawMarkdownEndpointTemplate,
+  rssEndpointTemplate,
+  runtimeTsconfigTemplate,
+  searchClientTemplate,
+  searchEndpointTemplate,
+  userComponentsTemplate,
+} from "../astro/templates.ts";
+import { scanProject } from "../core/project-graph.ts";
+import type { ProjectContext } from "../core/types.ts";
+import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import { buildReferenceFiles, hasReferences } from "../openapi/scalar.ts";
+import { buildSearchDocuments } from "../search/documents.ts";
+import { servesStaticIndex } from "../search/providers.ts";
+import { tailwindEntryTemplate } from "../theme/entry.ts";
+import { buildThemeCss } from "../theme/palette.ts";
+import { twoslashCss } from "../theme/twoslash.ts";
+
+const POSIX = (path: string): string => path.split("\\").join("/");
+
+/**
+ * Promote the generated runtime into the project as an owned Astro app. After
+ * eject the project has a normal `astro.config.mjs` and `src/`, the `blume` CLI
+ * is no longer required, and the `blume` package remains importable.
+ *
+ * Returns the list of written files.
+ */
+export const eject = async (root: string): Promise<string[]> => {
+  const project = await scanProject(root, { mode: "build" });
+  const { context, config } = project;
+
+  const srcDir = join(root, "src");
+  const genDir = join(srcDir, "generated");
+  const askEnabled = config.ai.ask?.enabled ?? false;
+  const exportPdf = config.export.pdf;
+  const exportEpub = config.export.epub;
+
+  const [pages, needsReactRaw, userTheme, rawMarkdown, islands, examples] =
+    await Promise.all([
+      context.pagesRoot
+        ? discoverPages(context.pagesRoot)
+        : Promise.resolve([]),
+      detectNeedsReact(root),
+      context.themeFile
+        ? readFile(context.themeFile, "utf-8")
+        : Promise.resolve(""),
+      buildRawMarkdown(project),
+      discoverIslands(root),
+      discoverExamples(root),
+    ]);
+  // Island/example frameworks drive which Astro renderers the ejected config
+  // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
+  const frameworks = new Set<string>([
+    ...islands.islands.map((island) => island.framework),
+    ...examples.examples.map((example) => example.framework),
+  ]);
+  const needsReact = needsReactRaw || askEnabled || frameworks.has("react");
+  const needsVue = frameworks.has("vue");
+  const needsSvelte = frameworks.has("svelte");
+
+  // A project-relative context so generated files use portable paths.
+  const relContext: ProjectContext = {
+    ...context,
+    contentRoot: POSIX(relative(root, context.contentRoot)),
+    outDir: ".",
+    root: ".",
+  };
+
+  const componentsImport = context.componentsFile
+    ? `../../${POSIX(relative(root, context.componentsFile))}`
+    : null;
+  const relPages = pages.map((page) => ({
+    entrypoint: POSIX(relative(root, page.entrypoint)),
+    pattern: page.pattern,
+  }));
+
+  // Non-filesystem sources eject their materialized MDX into `<root>/blume-staged`
+  // (a dedicated dir so it never clashes with a content root literally named
+  // `content`; the relative `staged` collection points there).
+  const staged = collectStaged(project);
+  const hasStaged = staged.size > 0;
+  const stagedDir = "blume-staged";
+
+  const files: { path: string; content: string }[] = [
+    {
+      content: astroConfigTemplate({
+        config,
+        contentRoutes: project.manifest.routes.map((route) => route.path),
+        context: relContext,
+        dataPath: "./src/generated/data.json",
+        examplesPath: "./src/generated/examples.ts",
+        needsReact,
+        needsSvelte,
+        needsVue,
+        pages: relPages,
+        searchClientPath: "./src/generated/search-client.ts",
+        themePath: "./src/generated/app.css",
+      }),
+      path: join(root, "astro.config.mjs"),
+    },
+    {
+      content: runtimeTsconfigTemplate(),
+      path: join(root, "tsconfig.json"),
+    },
+    { content: envTemplate(), path: join(srcDir, "env.d.ts") },
+    {
+      content: contentConfigTemplate({
+        config,
+        context: relContext,
+        staged: hasStaged,
+        stagedBase: stagedDir,
+      }),
+      path: join(srcDir, "content.config.ts"),
+    },
+    {
+      content: catchAllPageTemplate({
+        askEnabled,
+        exportEpub,
+        exportPdf,
+        mathEnabled: config.markdown.math,
+      }),
+      path: join(srcDir, "pages", "[...slug].astro"),
+    },
+    {
+      content: userComponentsTemplate(componentsImport),
+      path: join(genDir, "components.ts"),
+    },
+    // Island/example maps the catch-all imports; written even when empty so the
+    // relative import and the `blume:examples` alias always resolve.
+    {
+      content: islandMapTemplate(islands.islands),
+      path: join(genDir, "islands.ts"),
+    },
+    {
+      content: exampleMapTemplate(examples.examples),
+      path: join(genDir, "examples.ts"),
+    },
+    {
+      content: tailwindEntryTemplate({
+        configTokens: buildThemeCss(config.theme),
+        // Relative paths from src/generated/app.css keep the ejected app portable.
+        sources: [
+          "../../node_modules/blume/src/**/*.{astro,ts,tsx}",
+          "../../**/*.{astro,mdx,ts,tsx}",
+        ],
+        twoslashCss: twoslashCss(),
+        userTheme,
+      }),
+      path: join(genDir, "app.css"),
+    },
+    { content: buildRuntimeData(project), path: join(genDir, "data.json") },
+    {
+      content: `${JSON.stringify(rawMarkdown)}\n`,
+      path: join(genDir, "raw-markdown.json"),
+    },
+    {
+      content: rawMarkdownEndpointTemplate(),
+      path: join(srcDir, "pages", "[...slug].md.ts"),
+    },
+    {
+      content: rawMarkdownEndpointTemplate(),
+      path: join(srcDir, "pages", "[...slug].mdx.ts"),
+    },
+  ];
+
+  if (askEnabled) {
+    files.push({
+      content: askEndpointTemplate(resolveAskBackend(config.ai.ask)),
+      path: join(srcDir, "pages", "api", "ask.ts"),
+    });
+  }
+
+  if (config.seo.og.enabled) {
+    files.push({
+      content: ogEndpointTemplate(
+        customOgRoutes(pages, config.title, config.description)
+      ),
+      path: join(srcDir, "pages", "og", "[...slug].png.ts"),
+    });
+  }
+
+  // The provider-specific client loader behind the `blume:search-client` alias.
+  files.push({
+    content: searchClientTemplate(config),
+    path: join(genDir, "search-client.ts"),
+  });
+
+  if (servesStaticIndex(config.search.provider)) {
+    const documents = await buildSearchDocuments(project);
+    files.push(
+      {
+        content: `${JSON.stringify(documents)}\n`,
+        path: join(genDir, "search.json"),
+      },
+      {
+        content: searchEndpointTemplate(),
+        path: join(srcDir, "pages", "blume-search.json.ts"),
+      }
+    );
+  }
+
+  if (config.search.provider === "mixedbread") {
+    files.push({
+      content: mixedbreadSearchEndpointTemplate(
+        config.search.mixedbread?.storeId ?? ""
+      ),
+      path: join(srcDir, "pages", "api", "search.ts"),
+    });
+  }
+
+  const feeds = buildRssFeeds(project);
+  if (feeds.length > 0) {
+    const feedXml = Object.fromEntries(
+      feeds.map((feed) => [feed.type, renderRssFeed(feed)])
+    );
+    files.push(
+      {
+        content: `${JSON.stringify(feedXml)}\n`,
+        path: join(genDir, "rss.json"),
+      },
+      {
+        content: rssEndpointTemplate(),
+        path: join(srcDir, "pages", "[section]", "rss.xml.ts"),
+      }
+    );
+  }
+
+  // Scalar API/AsyncAPI reference pages, mirrored from the generated runtime so
+  // the ejected app keeps its reference routes.
+  if (hasReferences(config)) {
+    const references = await buildReferenceFiles({
+      config,
+      contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
+      root,
+    });
+    for (const file of references.files) {
+      files.push({
+        content: file.content,
+        path: join(srcDir, "pages", file.pagePath),
+      });
+    }
+  }
+
+  // Per-island and per-example live wrappers referenced by the maps above.
+  files.push(
+    ...islands.islands.map((island) => ({
+      content: islandWrapperTemplate(island),
+      path: join(genDir, "islands", `${island.name}.astro`),
+    })),
+    ...examples.examples.map((example) => ({
+      content: exampleWrapperTemplate(example),
+      path: join(genDir, "examples", `${exampleSlug(example.path)}.astro`),
+    }))
+  );
+
+  // Materialize staged source bodies under `<root>/blume-staged/<source>/<ref>`,
+  // matching the relative `staged` collection base in the ejected config.
+  for (const [entryId, content] of staged) {
+    files.push({ content, path: join(root, stagedDir, entryId) });
+  }
+
+  await Promise.all(
+    files.map(async (file) => {
+      await mkdir(join(file.path, ".."), { recursive: true });
+      await writeFile(file.path, file.content, "utf-8");
+    })
+  );
+
+  // Materialized source assets (e.g. downloaded Notion images) live under the
+  // hidden runtime's public dir; copy them into the owned project's `public/`
+  // so the staged content's `/blume-assets/…` references still resolve.
+  const assetsSrc = join(context.outDir, "public", "blume-assets");
+  if (existsSync(assetsSrc)) {
+    await cp(assetsSrc, join(root, "public", "blume-assets"), {
+      recursive: true,
+    });
+  }
+
+  // The hidden runtime is no longer the source of truth.
+  await rm(context.outDir, { force: true, recursive: true });
+
+  return files.map((file) => file.path);
+};

package/src/registry/registry.ts

@@ -0,0 +1,100 @@
+import { join } from "pathe";
+
+import { packageRoot } from "../core/package-root.ts";
+
+/** A file copied into the user's project by `blume add`. */
+export interface RegistryFile {
+  /** Path to the source file, relative to the blume package `src` directory. */
+  source: string;
+  /** Destination path relative to the project root. */
+  target: string;
+  /** Rewrite the file's relative imports to `blume/*` specifiers on copy. */
+  rewrite?: boolean;
+}
+
+export interface RegistryItem {
+  name: string;
+  description: string;
+  files: RegistryFile[];
+  /** Lines printed after install to guide the user. */
+  postInstall: string[];
+}
+
+/** Absolute path to the blume package `src` directory (the copy source root). */
+export const packageSrc = join(packageRoot(), "src");
+
+/** Absolute path to the bundled registry item sources. */
+export const itemsRoot = join(packageRoot(), "src", "registry", "items");
+
+/**
+ * A built-in layout component offered as editable source. `blume add` rewrites
+ * its relative imports to `blume/*`, so it renders identically to the built-in
+ * until the user changes it, then registers under the matching `layout` slot.
+ */
+const layoutComponent = (config: {
+  name: string;
+  description: string;
+  /** Source basename under `src/components/layout`. */
+  file: string;
+  /** Layout slot key, also the import name in the post-install hint. */
+  slot: string;
+}): RegistryItem => {
+  const target = `components/blume/${config.file}`;
+  return {
+    description: config.description,
+    files: [
+      {
+        rewrite: true,
+        source: `components/layout/${config.file}`,
+        target,
+      },
+    ],
+    name: config.name,
+    postInstall: [
+      "Register it in components.ts:",
+      '  import { defineComponents } from "blume";',
+      `  import ${config.slot} from "./${target}";`,
+      "",
+      `  export default defineComponents({ layout: { ${config.slot} } });`,
+      "",
+      "It imports the rest from `blume/*`, so it matches the built-in until you edit it.",
+    ],
+  };
+};
+
+/** The built-in, Blume-owned source registry. */
+export const registry: RegistryItem[] = [
+  layoutComponent({
+    description: "The top navigation bar (logo, search, nav links).",
+    file: "Header.astro",
+    name: "header",
+    slot: "Header",
+  }),
+  layoutComponent({
+    description: "The sidebar navigation tree.",
+    file: "NavTree.astro",
+    name: "sidebar",
+    slot: "Sidebar",
+  }),
+  layoutComponent({
+    description: "The breadcrumb trail shown above page content.",
+    file: "Breadcrumbs.astro",
+    name: "breadcrumbs",
+    slot: "Breadcrumbs",
+  }),
+  layoutComponent({
+    description: "The on-this-page table of contents.",
+    file: "TableOfContents.astro",
+    name: "table-of-contents",
+    slot: "TableOfContents",
+  }),
+  layoutComponent({
+    description: "The previous/next pagination footer.",
+    file: "Pagination.astro",
+    name: "pagination",
+    slot: "Pagination",
+  }),
+];
+
+export const findItem = (name: string): RegistryItem | undefined =>
+  registry.find((item) => item.name === name);

package/src/registry/rewrite-imports.ts

@@ -0,0 +1,39 @@
+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;
+
+/**
+ * Rewrite a built-in component's relative imports to `blume/*` package
+ * specifiers, so a copy installed by `blume add` resolves the rest of the
+ * framework from the package instead of broken relative paths.
+ *
+ * `sourceFile` is the original file's absolute path and `srcRoot` the package
+ * `src` directory; a relative import is resolved against the source, mapped to
+ * its path under `src`, and re-emitted as `blume/<that path>`. Two specifiers
+ * are left untouched: a self-reference (a component importing itself, e.g. the
+ * recursive nav tree) stays relative so the copy recurses into the copy, and
+ * anything resolving outside `src` is left as-is.
+ */
+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}`;
+    }
+  );

package/src/runtime/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime helpers usable inside `.astro` pages and islands.
+ *
+ * These give custom pages and components access to Blume project data
+ * (config, navigation, page collections) without reaching into generated
+ * runtime internals. The surface grows with the customization milestone.
+ */
+export type {
+  Heading,
+  NavNode,
+  Navigation,
+  NavTab,
+  PageRecord,
+} from "../core/types.ts";

package/src/search/build.ts

@@ -0,0 +1,23 @@
+import { join } from "pathe";
+
+/**
+ * Build a local Pagefind search index over the built site. Pagefind only
+ * indexes elements marked with `data-pagefind-body`, which Blume adds to the
+ * content of indexable pages, so nav chrome and excluded pages are skipped.
+ *
+ * Returns the number of pages indexed.
+ */
+export const buildSearchIndex = async (outDir: string): Promise<number> => {
+  const pagefind = await import("pagefind");
+
+  const { index } = await pagefind.createIndex({});
+  if (!index) {
+    throw new Error("Failed to create Pagefind index.");
+  }
+
+  const result = await index.addDirectory({ path: outDir });
+  await index.writeFiles({ outputPath: join(outDir, "pagefind") });
+  await pagefind.close();
+
+  return result.page_count;
+};

package/src/search/documents.ts

@@ -0,0 +1,164 @@
+import matter from "../core/frontmatter.ts";
+import { contentIndexable } from "../core/manifest.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import { readEntryText } from "../core/sources/read.ts";
+import type { NavNode } from "../core/types.ts";
+
+/** A document indexed by the client-side search providers (Orama, FlexSearch). */
+export interface SearchDocument {
+  route: string;
+  title: string;
+  description: string;
+  content: string;
+  /** Ancestor section labels for the result breadcrumb, e.g. `["Guides"]`. */
+  breadcrumb: string[];
+  /** Top-level section label, used by the search filter pills. */
+  section: string;
+  /** Locale code, so the dialog can filter results to the active language. */
+  locale: string;
+  /** Frontmatter `search.tags`, surfaced for hosted-provider faceting. */
+  tags?: string[];
+}
+
+/**
+ * A record uploaded to a hosted search backend (Algolia, Orama Cloud,
+ * Typesense, Mixedbread). `_id` is the stable per-page key; each sync adapts it
+ * to the backend's own id field (`objectID`, `id`, …).
+ */
+export interface SearchRecord {
+  _id: string;
+  url: string;
+  title: string;
+  description: string;
+  content: string;
+  /** Locale code, carried as a facet for per-language filtering. */
+  locale: string;
+  /** Single faceting tag (the first frontmatter tag, when present). */
+  tag?: string;
+}
+
+const CODE_FENCE = /```[\s\S]*?```/gu;
+const INLINE_CODE = /`(?<code>[^`]+)`/gu;
+const HTML_OR_JSX = /<[^>]+>/gu;
+const IMAGE = /!\[[^\]]*\]\([^)]*\)/gu;
+const LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
+const HEADING_MARK = /^#{1,6}\s+/gmu;
+const MARKDOWN_PUNCT = /[*_~>]+/gu;
+const WHITESPACE = /\s+/gu;
+
+/** Reduce Markdown/MDX to plain, searchable text. */
+const toPlainText = (markdown: string): string =>
+  markdown
+    .replaceAll(CODE_FENCE, " ")
+    .replaceAll(IMAGE, " ")
+    .replaceAll(LINK, "$<text>")
+    .replaceAll(HTML_OR_JSX, " ")
+    .replaceAll(INLINE_CODE, "$<code>")
+    .replaceAll(HEADING_MARK, "")
+    .replaceAll(MARKDOWN_PUNCT, " ")
+    .replaceAll(WHITESPACE, " ")
+    .trim();
+
+interface Crumbs {
+  breadcrumb: string[];
+  section: string;
+}
+
+/**
+ * Map each page route to its ancestor section labels by walking the nav sidebar
+ * once. The nearest ancestor group — the sidebar section a page appears under —
+ * becomes its `section`, the dimension the search filter pills group by, so the
+ * pills mirror the visible sidebar (and honor folder-meta renames).
+ */
+const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
+  const index = new Map<string, Crumbs>();
+  const walk = (nodes: NavNode[], trail: string[]): void => {
+    for (const node of nodes) {
+      if (node.kind === "group") {
+        walk(node.children, [...trail, node.label]);
+      } else if (node.route) {
+        index.set(node.route, {
+          breadcrumb: trail,
+          section: trail.at(-1) ?? "",
+        });
+      }
+    }
+  };
+  walk(sidebar, []);
+  return index;
+};
+
+/**
+ * Build search documents from the content graph. Only indexable pages are
+ * included (per the route manifest), and content comes from the source files,
+ * so the index is identical in dev and build.
+ *
+ * Pass `includeWhenDisabled` to index pages on their content merits even when
+ * the search provider is `none` — used by the MCP server, which is a separate
+ * feature from on-page search.
+ */
+export const buildSearchDocuments = async (
+  project: BlumeProject,
+  options?: { includeWhenDisabled?: boolean }
+): Promise<SearchDocument[]> => {
+  const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
+
+  // Build the crumb index from every locale's sidebar (their nodes carry
+  // locale-prefixed routes), so localized pages get the right section/breadcrumb.
+  // Falls back to the single default-locale nav when i18n is off.
+  const byLocale = Object.values(project.graph.navigationByLocale ?? {});
+  const sidebars =
+    byLocale.length > 0
+      ? byLocale.map((nav) => nav.sidebar)
+      : [project.graph.navigation?.sidebar ?? []];
+  const crumbs = new Map<string, Crumbs>();
+  for (const sidebar of sidebars) {
+    for (const [route, crumb] of buildCrumbIndex(sidebar)) {
+      crumbs.set(route, crumb);
+    }
+  }
+
+  const indexable = project.manifest.routes.filter((route) => {
+    if (!options?.includeWhenDisabled) {
+      return route.indexable;
+    }
+    const page = pageById.get(route.id);
+    return page ? contentIndexable(page, project.config) : false;
+  });
+
+  return await Promise.all(
+    indexable.map(async (route) => {
+      const page = pageById.get(route.id);
+      const raw = page ? await readEntryText(project, page) : "";
+      const body = raw ? toPlainText(matter(raw).content) : "";
+      const tags = page?.meta?.search?.tags;
+      const crumb = crumbs.get(route.path);
+      return {
+        breadcrumb: crumb?.breadcrumb ?? [],
+        content: body,
+        description: page?.description ?? "",
+        locale: route.locale,
+        route: route.path,
+        section: crumb?.section || "Docs",
+        tags: tags && tags.length > 0 ? tags : undefined,
+        title: route.title,
+      };
+    })
+  );
+};
+
+/**
+ * Map per-page search documents to the flat record shape hosted backends
+ * ingest. One record per page, keyed by route; the first tag becomes the
+ * faceting `tag`.
+ */
+export const toSearchRecords = (documents: SearchDocument[]): SearchRecord[] =>
+  documents.map((doc) => ({
+    _id: doc.route,
+    content: doc.content,
+    description: doc.description,
+    locale: doc.locale,
+    tag: doc.tags?.[0],
+    title: doc.title,
+    url: doc.route,
+  }));