blume 0.1.0 → 0.1.1

package/src/astro/generate.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import {
+  lstat,
   mkdir,
   readFile,
   rename,
@@ -17,11 +18,18 @@ 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 type {
+  BlumeBanner,
+  BlumeData,
+  BlumeFavicon,
+  BlumeLogo,
+} from "../core/data.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import {
@@ -35,8 +43,9 @@ import { tailwindEntryTemplate } from "../theme/entry.ts";
 import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
+import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
-import { discoverPages } from "./pages.ts";
+import { customOgRoutes, discoverPages } from "./pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -44,6 +53,9 @@ import {
   changelogIndexTemplate,
   contentConfigTemplate,
   envTemplate,
+  exampleMapTemplate,
+  exampleWrapperTemplate,
+  exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
   mcpEndpointTemplate,
@@ -64,8 +76,6 @@ import {
 
 /** Absolute path to the Blume package `src` directory. */
 const BLUME_SRC = join(packageRoot(), "src");
-/** The Blume package's own `node_modules` (where Astro and friends live). */
-const BLUME_NODE_MODULES = join(packageRoot(), "node_modules");
 
 /** Whether a module specifier resolves from a directory via node resolution. */
 const canResolveFrom = (fromDir: string, spec: string): boolean => {
@@ -77,29 +87,97 @@ const canResolveFrom = (fromDir: string, spec: string): boolean => {
   }
 };
 
-/** Whether Astro resolves from a directory via normal node resolution. */
-const canResolveAstro = (fromDir: string): boolean =>
-  canResolveFrom(fromDir, "astro/package.json");
+/**
+ * Realpath of the `astro` package node resolves from a directory, or null when
+ * none resolves. Comparing this for `.blume/` against Blume's own deps tells
+ * whether the runtime would bind to the *same* astro Blume uses or a different
+ * one shadowing it (the hoisted-conflict failure mode).
+ */
+const resolvedAstroPath = (fromDir: string): string | null => {
+  try {
+    const pkg = createRequire(
+      pathToFileURL(join(fromDir, "_.js")).href
+    ).resolve("astro/package.json");
+    return realpathSync(pkg);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Locate the directory that holds Blume's installed dependencies (Astro and its
+ * integrations).
+ *
+ * With a clean hoisted install this is moot — the deps sit in a `node_modules`
+ * the generated `.blume/` already walks up into, and {@link ensureDepsLink}
+ * short-circuits before we need it. But under isolated linkers (Bun's
+ * `isolated` mode, pnpm) Blume's deps are NOT hoisted into the project; they
+ * live beside the Blume package in a virtual store, invisible to the upward
+ * walk from `.blume/`. Two layouts are possible, so probe for `astro`:
+ *   - `<blume>/node_modules` — deps nested under the package (workspace source)
+ *   - `dirname(<blume>)`     — deps as siblings in the store (isolated/pnpm)
+ *
+ * `packageRoot()` resolves to Blume's real on-disk path (Node follows the
+ * install symlink), so its parent is the store's package directory where the
+ * isolated linker places the siblings. The previous fixed
+ * `packageRoot()/node_modules` assumption missed the sibling layout entirely,
+ * which is why isolated-linker projects had to redeclare Blume's deps by hand.
+ */
+export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
+  const candidates = [join(pkgDir, "node_modules"), dirname(pkgDir)];
+  return candidates.find((dir) => existsSync(join(dir, "astro"))) ?? null;
+};
 
 /**
- * Make the generated runtime resolve Astro and its integrations. When they are
- * hoisted into the project (the usual case for published installs), resolution
- * already works. When they are nested and unreachable (workspaces, strict
- * package managers), symlink Blume's own dependencies into `.blume`.
+ * Make the generated runtime resolve Astro and its integrations against Blume's
+ * own dependency set. Two failure modes this repairs:
+ *
+ *   - Astro is *unreachable* from `.blume/` (workspaces under isolated linkers,
+ *     pnpm) — the deps live in a store the upward walk can't see.
+ *   - Astro *resolves to the wrong copy* — a hoisted sibling pinned an older
+ *     major (e.g. `astro@6` for a type-only import) that shadows Blume's
+ *     `astro@7`, so `@astrojs/mdx@7` binds to it and crashes the build on a
+ *     missing export. Resolving merely *an* astro isn't enough; it must be the
+ *     same one Blume uses.
+ *
+ * In both cases we symlink Blume's dependency directory in as
+ * `.blume/node_modules` so the generated config's bare specifiers (`astro`,
+ * `@astrojs/mdx`, …) bind to the matching set. We only do this when those deps
+ * are a *co-located, consistent* set (astro beside the `@astrojs/mdx` that binds
+ * to it). A split layout — an integration hoisted away from a conflicting astro
+ * — can't be made consistent by a single symlink and needs a root `overrides`/
+ * `resolutions` pin instead, so we leave it untouched rather than half-fix it.
  */
-const ensureDepsLink = async (outDir: string): Promise<void> => {
-  if (canResolveAstro(outDir)) {
+export const ensureDepsLink = async (
+  outDir: string,
+  pkgDir: string = packageRoot()
+): Promise<void> => {
+  const depsDir = blumeDepsDir(pkgDir);
+  if (!depsDir || !existsSync(join(depsDir, "@astrojs", "mdx"))) {
     return;
   }
-  if (!existsSync(join(BLUME_NODE_MODULES, "astro"))) {
+  // Already correct when `.blume/` resolves the very same astro Blume's deps
+  // provide — the clean hoisted case. Otherwise (unreachable, or a different
+  // astro shadowing Blume's) link Blume's deps in.
+  const blumeAstro = resolvedAstroPath(depsDir);
+  if (blumeAstro && resolvedAstroPath(outDir) === blumeAstro) {
     return;
   }
   const link = join(outDir, "node_modules");
-  if (existsSync(link)) {
-    return;
+  // `lstat`, not `existsSync`, so a broken junction (target since moved) is
+  // still detected — `existsSync` follows the link and reports a dangling one
+  // as absent. Reaching here means `outDir` doesn't resolve Blume's astro, so
+  // any existing link is stale: replace a link we own (a junction/symlink) and
+  // leave a real directory untouched.
+  const existing = await lstat(link).catch(() => null);
+  if (existing) {
+    if (!existing.isSymbolicLink()) {
+      return;
+    }
+    await rm(link, { force: true });
   }
   await mkdir(outDir, { recursive: true });
-  await symlink(BLUME_NODE_MODULES, link, "junction");
+  await symlink(depsDir, link, "junction");
 };
 
 /** Astro integration package each non-React island framework needs installed. */
@@ -243,20 +321,12 @@ const writeStagedContent = async (
 };
 
 /** The logo shape the runtime consumes: an inline SVG or image URL(s). */
-interface ResolvedLogo {
-  svg?: string;
-  light?: string;
-  dark?: string;
-  alt: string;
-  href: string;
-}
-
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
  * `<img>`. The file is looked up under `public/` and the project root.
  */
-const resolveLogo = (project: BlumeProject): ResolvedLogo | null => {
+const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   const { logo } = project.config;
   if (!logo) {
     return null;
@@ -280,12 +350,6 @@ const resolveLogo = (project: BlumeProject): ResolvedLogo | null => {
   return { alt, dark, href, light };
 };
 
-/** The favicon shape the runtime consumes: a link href plus optional MIME type. */
-interface ResolvedFavicon {
-  href: string;
-  type?: string;
-}
-
 /**
  * Favicon filenames Blume auto-detects, in priority order. Mirrors the Next.js
  * convention: an `icon.*` or `favicon.*` file in `public/` or the project root
@@ -303,6 +367,8 @@ const FAVICON_CANDIDATES = [
 /** `<link type>` MIME for the favicon extensions we recognize. */
 const FAVICON_TYPES: Record<string, string> = {
   ico: "image/x-icon",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
   png: "image/png",
   svg: "image/svg+xml",
 };
@@ -318,45 +384,67 @@ const inlineDataUri = (file: string, type: string): string =>
   `data:${type};base64,${readFileSync(file).toString("base64")}`;
 
 /** The bundled Blume favicon, inlined as a data URI so it needs no public file. */
-const defaultFavicon = (): ResolvedFavicon => ({
+const defaultFavicon = (): BlumeFavicon => ({
   href: inlineDataUri(join(BLUME_SRC, "assets", "icon.png"), "image/png"),
   type: "image/png",
 });
 
 /**
- * Resolve the site favicon by convention. An `icon.*`/`favicon.*` file in
- * `public/` is served as-is and referenced by URL; one at the project root is
- * inlined as a data URI (the root isn't a served directory). Falls back to the
- * bundled Blume mark when the project ships no icon.
+ * Apple touch icon filenames Blume auto-detects, in priority order. Mirrors the
+ * Next.js `apple-icon.*` convention (plus the `apple-touch-icon.png` most favicon
+ * generators emit): a match in `public/` or the project root becomes the iOS
+ * home-screen icon, no config required.
  */
-const resolveFavicon = (project: BlumeProject): ResolvedFavicon => {
+const APPLE_ICON_CANDIDATES = [
+  "apple-icon.png",
+  "apple-icon.jpg",
+  "apple-icon.jpeg",
+  "apple-touch-icon.png",
+];
+
+/**
+ * Resolve an icon file by convention. A candidate in `public/` is served as-is
+ * and referenced by URL; one at the project root is inlined as a data URI (the
+ * root isn't a served directory). Returns null when the project ships none.
+ */
+const resolveIconFile = (
+  project: BlumeProject,
+  candidates: string[]
+): BlumeFavicon | null => {
   const { root } = project.context;
-  for (const name of FAVICON_CANDIDATES) {
+  for (const name of candidates) {
     if (existsSync(join(root, "public", name))) {
       return { href: `/${name}`, type: faviconType(name) };
     }
   }
-  for (const name of FAVICON_CANDIDATES) {
+  for (const name of candidates) {
     const file = join(root, name);
     if (existsSync(file)) {
       const type = faviconType(name);
       return { href: inlineDataUri(file, type ?? "image/x-icon"), type };
     }
   }
-  return defaultFavicon();
+  return null;
 };
 
-/** The announcement banner shape the runtime consumes. */
-interface ResolvedBanner {
-  content: string;
-  link?: { href: string; text: string };
-  dismissible: boolean;
-  /** Dismissal key: the configured id, else the content itself. */
-  key: string;
-}
+/**
+ * Resolve the site favicon by convention, falling back to the bundled Blume mark
+ * when the project ships no `icon.*`/`favicon.*` file.
+ */
+const resolveFavicon = (project: BlumeProject): BlumeFavicon =>
+  resolveIconFile(project, FAVICON_CANDIDATES) ?? defaultFavicon();
+
+/**
+ * Resolve the Apple touch icon by convention, or null when the project ships
+ * none (unlike the favicon, there's no bundled default). Note: iOS ignores
+ * `data:`-URI apple-touch-icons, so a `public/` file (served by URL) is the
+ * reliable path; a root-level file is still inlined for symmetry with favicons.
+ */
+const resolveAppleIcon = (project: BlumeProject): BlumeFavicon | null =>
+  resolveIconFile(project, APPLE_ICON_CANDIDATES);
 
 /** Normalize the banner config (string shorthand or object) for the runtime. */
-const resolveBanner = (config: ResolvedConfig): ResolvedBanner | null => {
+const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   const { banner } = config;
   if (!banner) {
     return null;
@@ -436,9 +524,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       )
     : {};
 
-  const data = {
+  const data: BlumeData = {
     config: {
       analytics: config.analytics ?? null,
+      appleIcon: resolveAppleIcon(project),
       banner: resolveBanner(config),
       codeWrap: config.markdown.code.wrap,
       description: config.description,
@@ -463,7 +552,9 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       mcp: config.mcp.enabled
         ? { name: config.mcp.name ?? config.title, route: config.mcp.route }
         : null,
-      og: { enabled: config.seo.og.enabled },
+      // `og.enabled` is resolved to a definite boolean in `loadConfig`; coerce
+      // the optional schema type so the serialized shape stays `boolean`.
+      og: { enabled: config.seo.og.enabled ?? false },
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
@@ -619,6 +710,7 @@ export const generateRuntime = async (
   const dataPath = join(srcDir, "generated", "data.json");
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
+  const examplesPath = join(srcDir, "generated", "examples.ts");
 
   // Record every file this pass writes so orphans (from a now-disabled feature)
   // can be pruned afterwards. `write` wraps the atomic writer and tracks paths.
@@ -633,21 +725,31 @@ export const generateRuntime = async (
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
-  const [pages, detectedReact, userTheme, islandDiscovery] = await Promise.all([
-    context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
-    detectNeedsReact(context.root),
-    readOptional(context.themeFile),
-    discoverIslands(context.root),
+  const [pages, detectedReact, userTheme, islandDiscovery, exampleDiscovery] =
+    await Promise.all([
+      context.pagesRoot
+        ? discoverPages(context.pagesRoot)
+        : Promise.resolve([]),
+      detectNeedsReact(context.root),
+      readOptional(context.themeFile),
+      discoverIslands(context.root),
+      discoverExamples(context.root),
+    ]);
+  // Each island/example framework enables its Astro renderer. React also
+  // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
+  // island/example-driven. `.astro` examples need no renderer.
+  const frameworks = new Set<string>([
+    ...islandDiscovery.islands.map((island) => island.framework),
+    ...exampleDiscovery.examples.map((example) => example.framework),
   ]);
-  // Each island's framework enables its Astro renderer. React also switches on
-  // for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are island-driven.
-  const islandFrameworks = new Set(
-    islandDiscovery.islands.map((island) => island.framework)
-  );
-  const needsReact =
-    detectedReact || askEnabled || islandFrameworks.has("react");
-  const needsVue = islandFrameworks.has("vue");
-  const needsSvelte = islandFrameworks.has("svelte");
+  const needsReact = detectedReact || askEnabled || frameworks.has("react");
+  const needsVue = frameworks.has("vue");
+  const needsSvelte = frameworks.has("svelte");
+
+  // Custom pages that should get a generated OG card (the home most of all).
+  // Computed before the MCP `.well-known` routes are appended below — those are
+  // private and filtered out anyway, but the intent is the user's pages.
+  const ogRoutes = customOgRoutes(pages, config.title, config.description);
 
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
@@ -664,10 +766,12 @@ export const generateRuntime = async (
     write(
       join(out, "astro.config.mjs"),
       astroConfigTemplate({
+        aliases: resolveTsconfigAliases(context.root),
         config,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context,
         dataPath,
+        examplesPath,
         needsReact,
         needsSvelte,
         needsVue,
@@ -705,6 +809,10 @@ export const generateRuntime = async (
       join(srcDir, "generated", "islands.ts"),
       islandMapTemplate(islandDiscovery.islands)
     ),
+    write(
+      join(srcDir, "generated", "examples.ts"),
+      exampleMapTemplate(exampleDiscovery.examples)
+    ),
     write(
       themePath,
       tailwindEntryTemplate({
@@ -731,6 +839,22 @@ export const generateRuntime = async (
     )
   );
 
+  // Per-example live wrappers for the `examples/` convention, resolved by
+  // `<Component path>` through the `examples.ts` map (written above, always).
+  await Promise.all(
+    exampleDiscovery.examples.map((example) =>
+      write(
+        join(
+          srcDir,
+          "generated",
+          "examples",
+          `${exampleSlug(example.path)}.astro`
+        ),
+        exampleWrapperTemplate(example)
+      )
+    )
+  );
+
   if (askEnabled) {
     await write(
       join(srcDir, "pages", "api", "ask.ts"),
@@ -743,7 +867,7 @@ export const generateRuntime = async (
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate()
+      ogEndpointTemplate(ogRoutes)
     );
   }
 
@@ -827,7 +951,11 @@ export const generateRuntime = async (
 
   // API/AsyncAPI reference pages (Scalar). One self-contained page per source,
   // mounted on its configured route and regenerated each run.
-  const warnings: string[] = [...mcp.warnings, ...islandDiscovery.warnings];
+  const warnings: string[] = [
+    ...mcp.warnings,
+    ...islandDiscovery.warnings,
+    ...exampleDiscovery.warnings,
+  ];
 
   // The new provider SDKs are optional peers; warn (rather than fail opaquely in
   // Vite) when the configured provider's package isn't installed.
@@ -841,7 +969,7 @@ export const generateRuntime = async (
 
   // React ships with Blume; Vue/Svelte islands need their Astro integration
   // installed by the project. Warn early rather than let Vite fail to resolve it.
-  warnings.push(...islandFrameworkWarnings(islandFrameworks, context.root));
+  warnings.push(...islandFrameworkWarnings(frameworks, context.root));
   if (hasReferences(config)) {
     const references = await buildReferenceFiles({
       config,

package/src/astro/islands.ts

@@ -53,7 +53,7 @@ const ISLAND_FILE = /\.(?<ext>jsx|svelte|tsx|vue)$/u;
 const CLIENT_EXPORT =
   /export\s+const\s+client\s*(?::[^=]+)?=\s*["'](?<mode>\w+)["']/u;
 
-const readClientMode = (
+export const readClientMode = (
   source: string,
   file: string,
   warnings: string[]

package/src/astro/pages.ts

@@ -26,3 +26,62 @@ export const discoverPages = async (
     return { entrypoint: file, pattern };
   });
 };
+
+/** A custom-page route that should get a generated OG card. */
+export interface OgCustomRoute {
+  /** `og/<slug>.png` path segment; `index` for the site root. */
+  slug: string;
+  /** Card title. */
+  title: string;
+  /** Small eyebrow line above the title. */
+  eyebrow?: string;
+}
+
+/** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
+const PRIVATE_SEGMENT = /^[._]/u;
+
+const humanizeSegment = (segment: string): string =>
+  segment
+    .split(/[-_]/u)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+
+/**
+ * Pick the custom-page routes that should get a generated Open Graph card, with
+ * the card's slug and text. OG is otherwise content-route only, so a custom page
+ * — most importantly the landing `/`, the most-shared URL — would have no card.
+ *
+ * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
+ * are skipped: they aren't shareable pages. The home is titled with the site
+ * title (eyebrow: the site description); a deeper page is titled from its last
+ * path segment.
+ */
+export const customOgRoutes = (
+  pages: BlumePageRoute[],
+  siteTitle: string,
+  siteDescription?: string
+): OgCustomRoute[] => {
+  const seen = new Set<string>();
+  const routes: OgCustomRoute[] = [];
+  for (const { pattern } of pages) {
+    const segments = pattern.split("/").filter(Boolean);
+    if (
+      segments.some((part) => PRIVATE_SEGMENT.test(part) || part.includes("["))
+    ) {
+      continue;
+    }
+    const slug = segments.length === 0 ? "index" : segments.join("/");
+    if (seen.has(slug)) {
+      continue;
+    }
+    seen.add(slug);
+    const last = segments.at(-1);
+    routes.push(
+      last
+        ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) }
+        : { eyebrow: siteDescription, slug, title: siteTitle }
+    );
+  }
+  return routes;
+};