blume 0.7.0 → 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,6 +22,7 @@ import {
   askEndpointTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
+  changelogIndexTemplate,
   contentConfigTemplate,
   envTemplate,
   exampleMapTemplate,
@@ -28,6 +31,8 @@ import {
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
+  mcpEndpointTemplate,
+  mcpPageFile,
   mixedbreadSearchEndpointTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
@@ -36,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";
@@ -55,6 +62,39 @@ import { twoslashCss } from "../theme/twoslash.ts";
 
 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 => {
   const source = project.sources.find(isOpenApiSource);
@@ -90,6 +130,112 @@ 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,
@@ -129,9 +275,13 @@ const examplesPreviewFiles = (
  * 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;
 
@@ -183,10 +333,13 @@ export const eject = async (root: string): Promise<string[]> => {
   const componentsImport = context.componentsFile
     ? `../../${toPosix(relative(root, context.componentsFile))}`
     : null;
-  const relPages = pages.map((page) => ({
-    entrypoint: toPosix(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
@@ -275,9 +428,11 @@ export const eject = async (root: string): Promise<string[]> => {
     {
       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(),
@@ -295,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"),
     },
   ];
@@ -315,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.
@@ -372,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,
@@ -433,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/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";
@@ -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/seo/jsonld.ts

@@ -98,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, withBasePath(deployBase, crumb.route));
-          }
-          return item;
-        }),
+        itemListElement: linked.map((crumb, index) => ({
+          "@type": "ListItem",
+          item: absolute(base, withBasePath(deployBase, crumb.route)),
+          name: crumb.label,
+          position: index + 1,
+        })),
       });
     }
   }