blume 0.3.0 → 0.5.0

package/src/openapi/source.ts

@@ -0,0 +1,140 @@
+import matter from "../core/frontmatter.ts";
+import { hashText } from "../core/sources/cache.ts";
+import type {
+  ContentSource,
+  SourceContext,
+  SourceEntry,
+  SourceLoadResult,
+} from "../core/sources/types.ts";
+import type { Diagnostic } from "../core/types.ts";
+import { extractOperations } from "./model.ts";
+import type { ApiOperationRef, ApiSpecData, OpenApiData } from "./model.ts";
+import { parseSpec } from "./parse.ts";
+import type { ReferenceSource } from "./references.ts";
+import { operationMdx, overviewMdx } from "./render-mdx.ts";
+import type { RenderedPage } from "./render-mdx.ts";
+
+/**
+ * The staged content source behind Blume's own OpenAPI renderer. Each configured
+ * spec is parsed once here, then lowered into one MDX page per operation plus an
+ * overview page — so operations become first-class Blume pages (real routes,
+ * sidebar, search, i18n, OG) and the parsed documents are handed to the
+ * generated `blume:openapi` module for the UI components to render.
+ */
+
+/** A content source that also exposes the specs it parsed during `load()`. */
+export interface OpenApiContentSource extends ContentSource {
+  readonly kind: "openapi-source";
+  /** Parsed spec data, populated by `load()`; `{}` before the first load. */
+  openApiData: () => OpenApiData;
+}
+
+/** Narrow a content source to the OpenAPI source (to read its parsed specs). */
+export const isOpenApiSource = (
+  source: ContentSource
+): source is OpenApiContentSource =>
+  (source as Partial<OpenApiContentSource>).kind === "openapi-source";
+
+/** Route (`/reference/pet/add-pet`) to a staged content ref, without extension. */
+const routeToRef = (route: string): string => route.replace(/^\/+/u, "");
+
+const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
+  const raw = matter.stringify(`${rendered.body}\n`, rendered.data);
+  return {
+    body: { format: "mdx", text: rendered.body },
+    data: rendered.data,
+    hash: hashText(raw),
+    raw,
+    ref,
+  };
+};
+
+/** All staged entries for one spec: operations first, overview last. */
+const specEntries = (
+  spec: ApiSpecData,
+  operations: ApiOperationRef[]
+): SourceEntry[] => {
+  const entries = operations.map((operation) =>
+    toEntry(operationMdx(spec, operation), `${routeToRef(operation.route)}.mdx`)
+  );
+  // Overview last so an operation sets the section's routePath before the index
+  // page is inserted (the group's routePath is derived from its first child).
+  entries.push(
+    toEntry(overviewMdx(spec), `${routeToRef(spec.route)}/index.mdx`)
+  );
+  return entries;
+};
+
+interface LoadedSpec {
+  slug: string;
+  spec: ApiSpecData;
+  entries: SourceEntry[];
+}
+
+export const openApiSource = (
+  references: ReferenceSource[],
+  ctx: SourceContext
+): OpenApiContentSource => {
+  let parsed: OpenApiData = {};
+
+  const loadReference = async (
+    reference: ReferenceSource
+  ): Promise<LoadedSpec | Diagnostic> => {
+    try {
+      const { document } = await parseSpec(reference.spec, ctx.projectRoot);
+      const { operations, tags } = extractOperations(document, reference.route);
+      const info = document.info ?? { title: reference.label, version: "" };
+      const spec: ApiSpecData = {
+        codeSamples: reference.display.codeSamples,
+        description: info.description ?? "",
+        document,
+        expandSchemas: reference.display.expandSchemas,
+        label: reference.label,
+        operations: Object.fromEntries(
+          operations.map((operation) => [operation.key, operation])
+        ),
+        route: reference.route,
+        slug: reference.slug,
+        tags,
+        title: info.title ?? reference.label,
+        version: info.version ?? "",
+      };
+      return {
+        entries: specEntries(spec, operations),
+        slug: reference.slug,
+        spec,
+      };
+    } catch (error) {
+      return {
+        code: "BLUME_OPENAPI_UNAVAILABLE",
+        message: `Could not load OpenAPI spec "${reference.spec}" for ${reference.route} (${(error as Error).message}); its reference pages were skipped.`,
+        severity: "warning",
+      };
+    }
+  };
+
+  const load = async (): Promise<SourceLoadResult> => {
+    const results = await Promise.all(references.map(loadReference));
+    const entries: SourceEntry[] = [];
+    const diagnostics: Diagnostic[] = [];
+    const data: OpenApiData = {};
+    for (const result of results) {
+      if ("severity" in result) {
+        diagnostics.push(result);
+        continue;
+      }
+      data[result.slug] = result.spec;
+      entries.push(...result.entries);
+    }
+    parsed = data;
+    return { diagnostics, entries };
+  };
+
+  return {
+    kind: "openapi-source",
+    load,
+    name: "openapi",
+    openApiData: () => parsed,
+    staged: true,
+  };
+};

package/src/registry/eject.ts

@@ -39,7 +39,9 @@ import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } 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 { hasScalarReferences } from "../openapi/references.ts";
+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";
@@ -48,6 +50,12 @@ import { twoslashCss } from "../theme/twoslash.ts";
 
 const POSIX = (path: string): string => path.split("\\").join("/");
 
+/** The `blume:openapi` payload for the ejected app (`{}` when none). */
+const ejectOpenApiData = (project: BlumeProject): unknown => {
+  const source = project.sources.find(isOpenApiSource);
+  return source ? source.openApiData() : {};
+};
+
 /**
  * The Ask AI endpoint plus, unless the backend runs its own retrieval (Inkeep),
  * its grounding snapshot. Empty when Ask AI is disabled.
@@ -140,7 +148,12 @@ export const eject = async (root: string): Promise<string[]> => {
   const hasStaged = staged.size > 0;
   const stagedDir = "blume-staged";
 
-  const files: { path: string; content: string }[] = [
+  const files: {
+    path: string;
+    content: string;
+    /** Don't overwrite a file the user already owns (e.g. a tuned tsconfig). */
+    skipIfExists?: boolean;
+  }[] = [
     {
       content: astroConfigTemplate({
         config,
@@ -151,6 +164,7 @@ export const eject = async (root: string): Promise<string[]> => {
         needsReact,
         needsSvelte,
         needsVue,
+        openapiPath: "./src/generated/openapi.json",
         pages: relPages,
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css",
@@ -160,6 +174,8 @@ export const eject = async (root: string): Promise<string[]> => {
     {
       content: runtimeTsconfigTemplate(),
       path: join(root, "tsconfig.json"),
+      // Never clobber a hand-tuned tsconfig; only write ours if none exists.
+      skipIfExists: true,
     },
     { content: envTemplate(), path: join(srcDir, "env.d.ts") },
     {
@@ -212,6 +228,10 @@ export const eject = async (root: string): Promise<string[]> => {
       path: join(genDir, "app.css"),
     },
     { content: buildRuntimeData(project), path: join(genDir, "data.json") },
+    {
+      content: `${JSON.stringify(ejectOpenApiData(project))}\n`,
+      path: join(genDir, "openapi.json"),
+    },
     {
       content: `${JSON.stringify(rawMarkdown)}\n`,
       path: join(genDir, "raw-markdown.json"),
@@ -295,7 +315,7 @@ 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.
-  if (hasReferences(config)) {
+  if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
@@ -327,8 +347,11 @@ export const eject = async (root: string): Promise<string[]> => {
     files.push({ content, path: join(root, stagedDir, entryId) });
   }
 
+  const written = files.filter(
+    (file) => !(file.skipIfExists && existsSync(file.path))
+  );
   await Promise.all(
-    files.map(async (file) => {
+    written.map(async (file) => {
       await mkdir(join(file.path, ".."), { recursive: true });
       await writeFile(file.path, file.content, "utf-8");
     })
@@ -347,5 +370,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 files.map((file) => file.path);
+  return written.map((file) => file.path);
 };

package/src/registry/registry.ts

@@ -219,6 +219,12 @@ const CONTENT_COMPONENTS: {
     name: "prompt",
     tag: "Prompt",
   },
+  {
+    description: "A responsive, privacy-friendly YouTube embed.",
+    file: "YouTube.astro",
+    name: "youtube",
+    tag: "YouTube",
+  },
 ];
 
 /** The built-in, Blume-owned source registry. */

package/src/registry/rewrite-imports.ts

@@ -1,10 +1,16 @@
 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;
+// A relative specifier (starting with `.`) in an `import … from "…"` or
+// `export … from "…"` statement. Anchored to the start of a line (`m` flag) and
+// bounded by `[^;]` so it only matches a real statement — not a `from "./…"`
+// that happens to appear inside a string or JSX text — while still allowing a
+// multiline import body between the keyword and `from`.
+const FROM_IMPORT =
+  /(?<prefix>^[ \t]*(?:import|export)\b[^;]*?\bfrom[ \t]*)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
+
+// A side-effect `import "./…"` at the start of a line.
+const SIDE_EFFECT_IMPORT =
+  /(?<prefix>^[ \t]*import[ \t]+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
 
 /**
  * Rewrite a built-in component's relative imports to `blume/*` package
@@ -22,18 +28,24 @@ 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}`;
+): string => {
+  const rewrite = (
+    match: string,
+    prefix: string,
+    quote: string,
+    spec: string
+  ): string => {
+    const resolved = resolve(dirname(sourceFile), spec);
+    if (resolved === sourceFile) {
+      return match;
+    }
+    const rel = relative(srcRoot, resolved);
+    if (rel.startsWith("..")) {
+      return match;
     }
-  );
+    return `${prefix}${quote}blume/${rel}${quote}`;
+  };
+  return content
+    .replaceAll(FROM_IMPORT, rewrite)
+    .replaceAll(SIDE_EFFECT_IMPORT, rewrite);
+};

package/src/search/documents.ts

@@ -47,17 +47,35 @@ const MARKDOWN_PUNCT = /[*_~>]+/gu;
 const WHITESPACE = /\s+/gu;
 
 /** Reduce Markdown/MDX to plain, searchable text. */
-const toPlainText = (markdown: string): string =>
-  markdown
+const toPlainText = (markdown: string): string => {
+  const withoutBlocks = markdown
     .replaceAll(CODE_FENCE, " ")
     .replaceAll(IMAGE, " ")
-    .replaceAll(LINK, "$<text>")
-    .replaceAll(HTML_OR_JSX, " ")
-    .replaceAll(INLINE_CODE, "$<code>")
+    .replaceAll(LINK, "$<text>");
+
+  // Strip HTML/JSX from the prose, but keep the contents of inline code — an
+  // angle-bracket span like `<T>` inside `Array<T>` is a type parameter, not a
+  // tag, and stripping it would drop those tokens from the search index. Split
+  // on inline-code spans and only run the HTML strip on the text between them.
+  const pieces: string[] = [];
+  let cursor = 0;
+  for (const match of withoutBlocks.matchAll(INLINE_CODE)) {
+    const start = match.index ?? 0;
+    pieces.push(
+      withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " ")
+    );
+    pieces.push(match.groups?.code ?? "");
+    cursor = start + match[0].length;
+  }
+  pieces.push(withoutBlocks.slice(cursor).replaceAll(HTML_OR_JSX, " "));
+
+  return pieces
+    .join("")
     .replaceAll(HEADING_MARK, "")
     .replaceAll(MARKDOWN_PUNCT, " ")
     .replaceAll(WHITESPACE, " ")
     .trim();
+};
 
 interface Crumbs {
   breadcrumb: string[];

package/src/search/sync/algolia.ts

@@ -9,6 +9,10 @@ export interface AlgoliaSyncConfig {
  * Upload the search records to Algolia. Uses the admin key from
  * `ALGOLIA_ADMIN_API_KEY` (never the config, which holds only the public,
  * search-only key). Throws on a missing key/config so the caller can warn.
+ *
+ * Uses `replaceAllObjects`, which atomically replaces the index contents, so
+ * pages deleted or renamed since the last sync don't linger as stale search
+ * hits that 404 when clicked.
  */
 export const syncAlgolia = async (
   records: SearchRecord[],
@@ -23,7 +27,7 @@ export const syncAlgolia = async (
   }
   const { algoliasearch } = await import("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
-  await client.saveObjects({
+  await client.replaceAllObjects({
     indexName: config.indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id })),
   });

package/src/search/sync/typesense.ts

@@ -8,9 +8,13 @@ export interface TypesenseSyncConfig {
 }
 
 /**
- * Import the search records into a Typesense collection, creating the
- * collection on first run. Uses the admin key from `TYPESENSE_ADMIN_API_KEY`.
- * Throws on a missing key/config so the caller can warn.
+ * Import the search records into a Typesense collection. Uses the admin key
+ * from `TYPESENSE_ADMIN_API_KEY`. Throws on a missing key/config so the caller
+ * can warn.
+ *
+ * The collection is dropped and recreated on each sync so that pages deleted or
+ * renamed since the last sync don't linger as stale search hits that 404 when
+ * clicked (an upsert alone never removes them).
  */
 export const syncTypesense = async (
   records: SearchRecord[],
@@ -35,20 +39,24 @@ export const syncTypesense = async (
     ],
   });
 
-  try {
-    await client.collections(config.collection).retrieve();
-  } catch {
-    await client.collections().create({
-      fields: [
-        { name: "title", type: "string" },
-        { name: "description", optional: true, type: "string" },
-        { name: "content", type: "string" },
-        { name: "url", type: "string" },
-        { facet: true, name: "tag", optional: true, type: "string" },
-      ],
-      name: config.collection,
-    });
+  const collection = client.collections(config.collection);
+  const exists = await collection
+    .retrieve()
+    .then(() => true)
+    .catch(() => false);
+  if (exists) {
+    await collection.delete();
   }
+  await client.collections().create({
+    fields: [
+      { name: "title", type: "string" },
+      { name: "description", optional: true, type: "string" },
+      { name: "content", type: "string" },
+      { name: "url", type: "string" },
+      { facet: true, name: "tag", optional: true, type: "string" },
+    ],
+    name: config.collection,
+  });
 
   const documents = records.map((record) => ({
     content: record.content,

package/src/theme/chrome-icons.ts

@@ -0,0 +1,22 @@
+/**
+ * The handful of built-in glyphs Blume's own chrome renders from **client-side**
+ * scripts (copy/check buttons, search result rows). These stay hand-inlined and
+ * dependency-free so they can be bundled into client JS — the full icon
+ * resolver (`./icons.ts`) pulls in library data far too large to ship to the
+ * browser, so it must never be imported from a client script.
+ *
+ * Author-facing content icons (Cards, Steps, sidebar, `icon:` frontmatter) do
+ * NOT come from here — they resolve from the bundled icon libraries at build
+ * time via `resolveIcon` and inline as zero-JS SVG.
+ *
+ * Values are Lucide inner-SVG markup; the client `svg()` helpers wrap them in an
+ * `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" …>`.
+ */
+export const chromeIcons: Record<string, string> = {
+  check: '<path d="M20 6 9 17l-5-5"/>',
+  copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
+  file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
+  search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',
+  sparkles:
+    '<path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1 1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3Z"/><path d="M5 3v4"/><path d="M3 5h4"/><path d="M19 17v4"/><path d="M17 19h4"/>',
+};