blume 0.6.7 → 0.8.0

package/src/registry/eject.ts

@@ -6,6 +6,8 @@ import { join, relative } from "pathe";
 import { buildAskData } from "../ai/ask-data.ts";
 import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } from "../ai/markdown.ts";
+import { buildMcpData } from "../ai/mcp/data.ts";
+import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { planComponentSlots } from "../astro/component-slots.ts";
 import { discoverExamples } from "../astro/examples.ts";
 import {
@@ -20,13 +22,17 @@ import {
   askEndpointTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
+  changelogIndexTemplate,
   contentConfigTemplate,
   envTemplate,
   exampleMapTemplate,
   exampleWrapperTemplate,
+  examplesPageTemplate,
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
+  mcpEndpointTemplate,
+  mcpPageFile,
   mixedbreadSearchEndpointTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
@@ -35,7 +41,9 @@ import {
   runtimeTsconfigTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
+  staticJsonEndpointTemplate,
 } from "../astro/templates.ts";
+import { packageRoot } from "../core/package-root.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ProjectContext } from "../core/types.ts";
@@ -45,11 +53,47 @@ import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { servesStaticIndex } from "../search/providers.ts";
-import { tailwindEntryTemplate } from "../theme/entry.ts";
+import {
+  examplesEntryTemplate,
+  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("/");
+const toPosix = (path: string): string => path.split("\\").join("/");
+
+/** The portable `@source` guess: blume in the project's own node_modules. */
+const LOCAL_BLUME_SOURCE = "../../node_modules/blume/src/**/*.{astro,ts,tsx}";
+
+/**
+ * The `@source` glob pointing Tailwind at Blume's own source, relative to the
+ * ejected `src/generated/app.css`. The project-local `node_modules/blume` is
+ * preferred (portable, and under pnpm the symlink survives version bumps), but
+ * hoisted installs (npm/yarn workspaces lift blume into the workspace root's
+ * node_modules) would make that guess match nothing and silently drop utility
+ * classes — so fall back to the package's real installed location, and when
+ * even that fails, warn instead of failing silently.
+ *
+ * Exported for testing.
+ */
+export const blumeSourceGlob = (
+  root: string,
+  genDir: string,
+  resolveBlumeRoot: () => string = packageRoot
+): string => {
+  if (existsSync(join(root, "node_modules", "blume"))) {
+    return LOCAL_BLUME_SOURCE;
+  }
+  try {
+    const src = join(resolveBlumeRoot(), "src");
+    return `${toPosix(relative(genDir, src))}/**/*.{astro,ts,tsx}`;
+  } catch {
+    console.warn(
+      'blume: could not locate the installed blume package; src/generated/app.css keeps its default `@source "../../node_modules/blume/..."` glob. If blume is hoisted elsewhere, point that glob at its install location or Blume\'s utility classes will be missing.'
+    );
+    return LOCAL_BLUME_SOURCE;
+  }
+};
 
 /** The `blume:openapi` payload for the ejected app (`{}` when none). */
 const ejectOpenApiData = (project: BlumeProject): unknown => {
@@ -86,14 +130,158 @@ const askFiles = async (
   return files;
 };
 
+/** Whether the ejected app hosts the MCP server (enabled and route free). */
+const hostsMcp = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): boolean =>
+  project.config.mcp.enabled &&
+  !routeIsTaken(userPages, project.graph.pages, project.config.mcp.route);
+
+/**
+ * The `.well-known` MCP discovery routes, injected as prerendered pages
+ * alongside the user's own so the ejected Astro config wires them in. Empty
+ * when the server is disabled or its route is already owned by a page.
+ */
+const mcpDiscoveryPages = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): { entrypoint: string; pattern: string }[] =>
+  hostsMcp(project, userPages)
+    ? [
+        {
+          entrypoint: "src/blume-mcp/discovery.ts",
+          pattern: "/.well-known/mcp.json",
+        },
+        {
+          entrypoint: "src/blume-mcp/server-card.ts",
+          pattern: "/.well-known/mcp/server-card.json",
+        },
+      ]
+    : [];
+
+/**
+ * The MCP data snapshot, server endpoint, and `.well-known` discovery
+ * documents, mirroring `writeMcpFiles` in generate.ts. Empty when the server
+ * is disabled or its route is already owned by a page.
+ */
+const mcpFiles = async (
+  project: BlumeProject,
+  userPages: { pattern: string }[],
+  srcDir: string,
+  genDir: string
+): Promise<{ content: string; path: string }[]> => {
+  if (!hostsMcp(project, userPages)) {
+    return [];
+  }
+  const { route } = project.config.mcp;
+  const data = await buildMcpData(project);
+  const discoveryInput = {
+    base: data.base,
+    name: data.name,
+    route,
+    site: data.site,
+    version: data.version,
+  };
+  return [
+    {
+      content: `${JSON.stringify(data)}\n`,
+      path: join(genDir, "mcp-data.json"),
+    },
+    {
+      content: mcpEndpointTemplate(route),
+      path: join(srcDir, "pages", mcpPageFile(route)),
+    },
+    {
+      content: staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput)),
+      path: join(srcDir, "blume-mcp", "discovery.ts"),
+    },
+    {
+      content: staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)),
+      path: join(srcDir, "blume-mcp", "server-card.ts"),
+    },
+  ];
+};
+
+/**
+ * The `/changelog` index page, mirroring `shouldGenerateChangelog` in
+ * generate.ts: emitted when `type: changelog` entries or a release-backed
+ * changelog source exist, unless a user page already owns the route.
+ */
+const changelogFiles = (
+  project: BlumeProject,
+  userPages: { pattern: string }[],
+  srcDir: string,
+  options: Parameters<typeof changelogIndexTemplate>[0]
+): { content: string; path: string }[] => {
+  const hasChangelog = project.graph.pages.some(
+    (page) =>
+      page.contentType === "changelog" &&
+      !(page.meta.draft || page.meta.sidebar.hidden)
+  );
+  const hasChangelogSource = (project.config.content.sources ?? []).some(
+    (source) => source.type === "github-releases"
+  );
+  if (
+    !(hasChangelog || hasChangelogSource) ||
+    routeIsTaken(userPages, project.graph.pages, "/changelog")
+  ) {
+    return [];
+  }
+  return [
+    {
+      content: changelogIndexTemplate(options),
+      path: join(srcDir, "pages", "changelog.astro"),
+    },
+  ];
+};
+
+/** Contents of the configured `examples.css`, or `""` when unset/absent. */
+const readExamplesCss = (
+  root: string,
+  css: string | undefined
+): Promise<string> =>
+  css && existsSync(join(root, css))
+    ? readFile(join(root, css), "utf-8")
+    : Promise.resolve("");
+
+/**
+ * The per-example preview route `<Component />` iframes embed, nested under
+ * `basePath` so it stays reachable behind a proxy that only forwards the
+ * base. Empty when the project has no examples.
+ */
+const examplesPreviewFiles = (
+  srcDir: string,
+  basePath: string,
+  hasExamples: boolean
+): { content: string; path: string }[] =>
+  hasExamples
+    ? [
+        {
+          content: examplesPageTemplate(),
+          path: join(
+            srcDir,
+            "pages",
+            ...basePath.split("/").filter(Boolean),
+            "blume-examples",
+            "[...path].astro"
+          ),
+        },
+      ]
+    : [];
+
 /**
  * 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.
+ * Returns the written files plus non-fatal warnings, mirroring the generated
+ * runtime (e.g. a Scalar reference spec that wasn't found, or a reference
+ * route colliding with a content page).
  */
-export const eject = async (root: string): Promise<string[]> => {
+export const eject = async (
+  root: string
+): Promise<{ files: string[]; warnings: string[] }> => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
 
@@ -108,6 +296,7 @@ export const eject = async (root: string): Promise<string[]> => {
     needsReactRaw,
     usesMath,
     userTheme,
+    userExamplesCss,
     rawMarkdown,
     islands,
     examples,
@@ -118,9 +307,10 @@ export const eject = async (root: string): Promise<string[]> => {
     context.themeFile
       ? readFile(context.themeFile, "utf-8")
       : Promise.resolve(""),
+    readExamplesCss(root, config.examples.css),
     buildRawMarkdown(project),
     discoverIslands(root),
-    discoverExamples(root, config.examples),
+    discoverExamples(root, config.examples.source),
   ]);
   // Island/example frameworks drive which Astro renderers the ejected config
   // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
@@ -135,18 +325,21 @@ export const eject = async (root: string): Promise<string[]> => {
   // A project-relative context so generated files use portable paths.
   const relContext: ProjectContext = {
     ...context,
-    contentRoot: POSIX(relative(root, context.contentRoot)),
+    contentRoot: toPosix(relative(root, context.contentRoot)),
     outDir: ".",
     root: ".",
   };
 
   const componentsImport = context.componentsFile
-    ? `../../${POSIX(relative(root, context.componentsFile))}`
+    ? `../../${toPosix(relative(root, context.componentsFile))}`
     : null;
-  const relPages = pages.map((page) => ({
-    entrypoint: POSIX(relative(root, page.entrypoint)),
-    pattern: page.pattern,
-  }));
+  const relPages = [
+    ...pages.map((page) => ({
+      entrypoint: toPosix(relative(root, page.entrypoint)),
+      pattern: page.pattern,
+    })),
+    ...mcpDiscoveryPages(project, pages),
+  ];
 
   // Non-filesystem sources eject their materialized MDX into `<root>/blume-staged`
   // (a dedicated dir so it never clashes with a content root literally named
@@ -168,6 +361,7 @@ export const eject = async (root: string): Promise<string[]> => {
         context: relContext,
         dataPath: "./src/generated/data.json",
         examplesPath: "./src/generated/examples.ts",
+        examplesThemePath: "./src/generated/examples.css",
         needsReact,
         needsSvelte,
         needsVue,
@@ -218,15 +412,27 @@ export const eject = async (root: string): Promise<string[]> => {
       path: join(genDir, "islands.ts"),
     },
     {
-      content: exampleMapTemplate(examples.examples),
+      content: exampleMapTemplate(examples.examples, config.basePath),
       path: join(genDir, "examples.ts"),
     },
+    {
+      // The isolated Tailwind entry for `<Component />` preview frames.
+      // Relative sources keep the ejected app portable.
+      content: examplesEntryTemplate({
+        configTokens: buildThemeCss(config.theme),
+        sources: ["../../**/*.{astro,jsx,svelte,ts,tsx,vue}"],
+        userCss: userExamplesCss,
+      }),
+      path: join(genDir, "examples.css"),
+    },
     {
       content: tailwindEntryTemplate({
         configTokens: buildThemeCss(config.theme),
-        // Relative paths from src/generated/app.css keep the ejected app portable.
+        // Relative paths from src/generated/app.css keep the ejected app
+        // portable; the blume glob resolves the real install location when
+        // the package is hoisted out of the project's own node_modules.
         sources: [
-          "../../node_modules/blume/src/**/*.{astro,ts,tsx}",
+          blumeSourceGlob(root, genDir),
           "../../**/*.{astro,mdx,ts,tsx}",
         ],
         twoslashCss: twoslashCss(),
@@ -244,11 +450,11 @@ export const eject = async (root: string): Promise<string[]> => {
       path: join(genDir, "raw-markdown.json"),
     },
     {
-      content: rawMarkdownEndpointTemplate(),
+      content: rawMarkdownEndpointTemplate("md"),
       path: join(srcDir, "pages", "[...slug].md.ts"),
     },
     {
-      content: rawMarkdownEndpointTemplate(),
+      content: rawMarkdownEndpointTemplate("mdx"),
       path: join(srcDir, "pages", "[...slug].mdx.ts"),
     },
   ];
@@ -264,6 +470,19 @@ export const eject = async (root: string): Promise<string[]> => {
     });
   }
 
+  // The hosted MCP server and the `/changelog` index, mirrored from the
+  // generated runtime (each helper returns `[]` when its feature is off).
+  files.push(
+    ...(await mcpFiles(project, pages, srcDir, genDir)),
+    ...changelogFiles(project, pages, srcDir, {
+      askEnabled,
+      exportEpub,
+      exportPdf,
+      needsReact,
+      staged: hasStaged,
+    })
+  );
+
   // Default 404 page, unless the project already owns `/404` (a custom
   // `pages/404.astro` or a `404.md` content page). The ejected project owns the
   // file afterwards and can edit or remove it.
@@ -321,13 +540,17 @@ export const eject = async (root: string): Promise<string[]> => {
   }
 
   // Scalar API/AsyncAPI reference pages, mirrored from the generated runtime so
-  // the ejected app keeps its reference routes.
+  // the ejected app keeps its reference routes — including the warnings (a
+  // missing spec file, a route collision), which the caller surfaces exactly
+  // like the generated-runtime path does.
+  const warnings: string[] = [];
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
       root,
     });
+    warnings.push(...references.warnings);
     for (const file of references.files) {
       files.push({
         content: file.content,
@@ -345,7 +568,12 @@ export const eject = async (root: string): Promise<string[]> => {
     ...examples.examples.map((example) => ({
       content: exampleWrapperTemplate(example),
       path: join(genDir, "examples", `${exampleSlug(example.path)}.astro`),
-    }))
+    })),
+    ...examplesPreviewFiles(
+      srcDir,
+      config.basePath,
+      examples.examples.length > 0
+    )
   );
 
   // Materialize staged source bodies under `<root>/blume-staged/<source>/<ref>`,
@@ -377,5 +605,5 @@ export const eject = async (root: string): Promise<string[]> => {
   // The hidden runtime is no longer the source of truth.
   await rm(context.outDir, { force: true, recursive: true });
 
-  return written.map((file) => file.path);
+  return { files: written.map((file) => file.path), warnings };
 };

package/src/registry/registry.ts

@@ -23,9 +23,6 @@ export interface RegistryItem {
 /** 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

package/src/search/build.ts

@@ -15,6 +15,9 @@ export const buildSearchIndex = async (outDir: string): Promise<number> => {
     throw new Error("Failed to create Pagefind index.");
   }
 
+  // These awaits are strictly ordered, not independent: the directory must be
+  // indexed before its files are written, and the index closed only after.
+  // oxlint-disable-next-line react-doctor/async-parallel
   const result = await index.addDirectory({ path: outDir });
   await index.writeFiles({ outputPath: join(outDir, "pagefind") });
   await pagefind.close();

package/src/search/documents.ts

@@ -1,3 +1,5 @@
+import { applyAudienceVisibility } from "../ai/visibility.ts";
+import type { VisibilityAudience } from "../ai/visibility.ts";
 import matter from "../core/frontmatter.ts";
 import { contentIndexable } from "../core/manifest.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -65,9 +67,9 @@ const toPlainText = (markdown: string): string => {
   for (const match of withoutBlocks.matchAll(INLINE_CODE)) {
     const start = match.index ?? 0;
     pieces.push(
-      withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " ")
+      withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " "),
+      match.groups?.code ?? ""
     );
-    pieces.push(match.groups?.code ?? "");
     cursor = start + match[0].length;
   }
   pieces.push(withoutBlocks.slice(cursor).replaceAll(HTML_OR_JSX, " "));
@@ -93,9 +95,21 @@ interface Crumbs {
  */
 const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
   const index = new Map<string, Crumbs>();
+  // A config-sidebar section's landing page (the group's `root`) lives on the
+  // *group* node, not on any page leaf — record it under the group's own label
+  // so the section's landing page carries the same facet as its children. A
+  // real page leaf for the route (filesystem sidebars emit index pages as
+  // leaves) wins, so group routes are merged in only where no leaf claimed one.
+  const groupRoutes = new Map<string, Crumbs>();
   const walk = (nodes: NavNode[], trail: string[]): void => {
     for (const node of nodes) {
       if (node.kind === "group") {
+        if (node.route && !groupRoutes.has(node.route)) {
+          groupRoutes.set(node.route, {
+            breadcrumb: [...trail, node.label],
+            section: node.label,
+          });
+        }
         walk(node.children, [...trail, node.label]);
       } else if (node.route) {
         index.set(node.route, {
@@ -106,6 +120,11 @@ const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
     }
   };
   walk(sidebar, []);
+  for (const [route, crumbs] of groupRoutes) {
+    if (!index.has(route)) {
+      index.set(route, crumbs);
+    }
+  }
   return index;
 };
 
@@ -122,10 +141,19 @@ const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
  * searchable text; `"markdown"` keeps the body's Markdown — code blocks, lists,
  * headings — for Ask AI grounding, where fenced examples are often the answer
  * and stripping them makes the model unable to cite content the docs do contain.
+ *
+ * `audience` resolves `<Visibility>` blocks before extraction: `"web"`
+ * (default) keeps web-only content and drops agents-only blocks — the site
+ * search and hosted syncs must not surface content the page hides — while
+ * `"agents"` mirrors llms-full.txt/MCP `get_page` (web removed, agents kept).
  */
 export const buildSearchDocuments = async (
   project: BlumeProject,
-  options?: { includeWhenDisabled?: boolean; content?: "markdown" | "plain" }
+  options?: {
+    includeWhenDisabled?: boolean;
+    content?: "markdown" | "plain";
+    audience?: VisibilityAudience;
+  }
 ): Promise<SearchDocument[]> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
@@ -157,8 +185,12 @@ export const buildSearchDocuments = async (
       const page = pageById.get(route.id);
       const raw = page ? await readEntryText(project, page) : "";
       const source = raw ? matter(raw).content : "";
+      const visible = applyAudienceVisibility(
+        source,
+        options?.audience ?? "web"
+      );
       const body =
-        options?.content === "markdown" ? source.trim() : toPlainText(source);
+        options?.content === "markdown" ? visible.trim() : toPlainText(visible);
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
       return {

package/src/search/sync/typesense.ts

@@ -40,10 +40,12 @@ export const syncTypesense = async (
   });
 
   const collection = client.collections(config.collection);
-  const exists = await collection
-    .retrieve()
-    .then(() => true)
-    .catch(() => false);
+  let exists = true;
+  try {
+    await collection.retrieve();
+  } catch {
+    exists = false;
+  }
   if (exists) {
     await collection.delete();
   }

package/src/seo/jsonld.ts

@@ -1,4 +1,8 @@
 import type { Crumb } from "../components/layout/nav-utils.ts";
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+
+/** A date-ish value carried through frontmatter (string, YAML Date, or unset). */
+type DateInput = string | Date | null;
 
 /** Inputs for a page's JSON-LD, all known at render time in RootLayout. */
 export interface StructuredDataInput {
@@ -9,12 +13,14 @@ export interface StructuredDataInput {
   description?: string;
   /** Page route, e.g. `/blog/post`. */
   route: string;
+  /** Deployment base (`import.meta.env.BASE_URL`); prefixed onto absolute URLs. */
+  base?: string;
   /** Content type — `blog` and `changelog` map to richer article types. */
   pageType?: string;
   /** Publish date (string or YAML Date); emitted as ISO `datePublished`. */
-  published?: string | Date | null;
+  published?: DateInput;
   /** Last-modified date; emitted as ISO `dateModified`. */
-  modified?: string | Date | null;
+  modified?: DateInput;
   /** BCP-47 language tag for `inLanguage`; defaults to `en`. */
   locale?: string;
   breadcrumbs: Crumb[];
@@ -31,7 +37,7 @@ const trimSlash = (value: string): string => value.replace(/\/$/u, "");
 const absolute = (base: string | null, path: string): string =>
   base ? `${base}${path}` : path;
 
-const toIso = (value: string | Date | null | undefined): string | undefined => {
+const toIso = (value: DateInput | undefined): string | undefined => {
   if (!value) {
     return;
   }
@@ -49,7 +55,11 @@ export const buildStructuredData = (
   input: StructuredDataInput
 ): Record<string, unknown> | null => {
   const base = input.siteUrl ? trimSlash(input.siteUrl) : null;
-  const pageUrl = absolute(base, input.route);
+  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top
+  // so JSON-LD URLs match the served location.
+  const deployBase = normalizeBasePath(input.base);
+  const pageUrl = absolute(base, withBasePath(deployBase, input.route));
+  const rootUrl = absolute(base, deployBase);
   const graph: Record<string, unknown>[] = [];
 
   if (base) {
@@ -57,7 +67,7 @@ export const buildStructuredData = (
       "@id": `${base}#website`,
       "@type": "WebSite",
       name: input.siteName,
-      url: base,
+      url: rootUrl,
     });
   }
 
@@ -88,20 +98,21 @@ export const buildStructuredData = (
     }
     graph.push(node);
 
-    if (input.breadcrumbs.length > 1) {
+    // Google requires `item` on every ListItem except the last; sidebar groups
+    // without an index page produce route-less crumbs, so those are dropped
+    // (positions renumbered) rather than emitted as invalid link-less items.
+    const linked = input.breadcrumbs.filter(
+      (crumb): crumb is Required<Crumb> => typeof crumb.route === "string"
+    );
+    if (linked.length > 1) {
       graph.push({
         "@type": "BreadcrumbList",
-        itemListElement: input.breadcrumbs.map((crumb, index) => {
-          const item: Record<string, unknown> = {
-            "@type": "ListItem",
-            name: crumb.label,
-            position: index + 1,
-          };
-          if (crumb.route) {
-            item.item = absolute(base, crumb.route);
-          }
-          return item;
-        }),
+        itemListElement: linked.map((crumb, index) => ({
+          "@type": "ListItem",
+          item: absolute(base, withBasePath(deployBase, crumb.route)),
+          name: crumb.label,
+          position: index + 1,
+        })),
       });
     }
   }