blume 0.0.0 → 0.1.0

package/src/migrate/starlight/index.ts

@@ -0,0 +1,131 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+
+import matter from "gray-matter";
+import { join } from "pathe";
+import { glob } from "tinyglobby";
+
+import { writeBlumeConfig } from "../shared.ts";
+import { loadStarlightConfig, mapStarlightConfig } from "./config.ts";
+import {
+  hasAliasedAssets,
+  rewriteStarlightAsides,
+  rewriteStarlightComponents,
+  stripStarlightImports,
+  unsupportedStarlightComponents,
+} from "./content.ts";
+import { normalizeStarlightPageMeta } from "./frontmatter.ts";
+import { starlightI18n } from "./i18n.ts";
+
+export interface StarlightMigrationResult {
+  moved: number;
+  warnings: string[];
+}
+
+/** Starlight always keeps its docs collection here. */
+const CONTENT_DIR = "src/content/docs";
+
+interface PageResult {
+  aliased: boolean;
+  removed: string[];
+  unsupported: string[];
+}
+
+/** Rewrite one Starlight page to idiomatic Blume MDX, in place. */
+const transformPage = async (file: string): Promise<PageResult> => {
+  const raw = await readFile(file, "utf-8");
+  let text = stripStarlightImports(raw);
+  text = rewriteStarlightAsides(text);
+  text = rewriteStarlightComponents(text);
+  const unsupported = unsupportedStarlightComponents(text);
+  const aliased = hasAliasedAssets(text);
+
+  const parsed = matter(text);
+  const { data, removed } = normalizeStarlightPageMeta(parsed.data);
+  const content =
+    Object.keys(data).length > 0
+      ? matter.stringify(parsed.content, data)
+      : parsed.content;
+  if (content !== raw) {
+    await writeFile(file, content, "utf-8");
+  }
+  return { aliased, removed, unsupported };
+};
+
+/**
+ * Migrate a Starlight project to Blume: translate the `starlight({...})` options
+ * out of `astro.config.*` into `blume.config.ts`, then rewrite each page under
+ * `src/content/docs` to idiomatic Blume MDX in place (asides → directives,
+ * component renames, frontmatter mapping). Content stays put — the generated
+ * config points `content.root` at `src/content/docs`.
+ */
+export const migrateStarlightProject = async (
+  root: string
+): Promise<StarlightMigrationResult> => {
+  const { options, warnings } = await loadStarlightConfig(root);
+  const config = mapStarlightConfig(options, warnings);
+
+  const i18n = starlightI18n(options);
+  if (i18n) {
+    config.i18n = i18n;
+    warnings.push(
+      `Mapped ${i18n.locales.length} locale(s) to i18n (default: ${i18n.defaultLocale}); review the locale labels.`
+    );
+  }
+
+  const base = join(root, CONTENT_DIR);
+  if (!existsSync(base)) {
+    await writeBlumeConfig(root, config);
+    return {
+      moved: 0,
+      warnings: [
+        ...warnings,
+        `Content directory ${CONTENT_DIR} not found; wrote blume.config.ts only.`,
+      ],
+    };
+  }
+
+  const files = await glob(["**/*.{md,mdx}"], { absolute: true, cwd: base });
+  const results = await Promise.all(files.map(transformPage));
+
+  await writeBlumeConfig(root, config);
+
+  const removedKeys = new Set<string>();
+  const unsupported = new Set<string>();
+  let aliasedAssets = false;
+  for (const result of results) {
+    for (const key of result.removed) {
+      removedKeys.add(key);
+    }
+    for (const name of result.unsupported) {
+      unsupported.add(name);
+    }
+    aliasedAssets ||= result.aliased;
+  }
+
+  if (removedKeys.size > 0) {
+    warnings.push(
+      `Dropped unsupported page frontmatter keys: ${[...removedKeys].join(", ")}.`
+    );
+    if (removedKeys.has("hero") || removedKeys.has("template")) {
+      warnings.push(
+        "Pages using `template: splash` / `hero` have no automatic equivalent — rebuild them as custom pages under `pages/`."
+      );
+    }
+  }
+  if (unsupported.size > 0) {
+    warnings.push(
+      `Components without a drop-in Blume equivalent need manual review: ${[...unsupported].join(", ")}.`
+    );
+  }
+  if (aliasedAssets) {
+    warnings.push(
+      "Some pages reference images via `~/`/`@/` aliases; rewrite them to relative or /public paths."
+    );
+  }
+  warnings.push(
+    "Content stays under src/content/docs; the now-unused astro.config.*, src/content.config.ts, and @astrojs/starlight dependency are safe to remove."
+  );
+
+  return { moved: results.length, warnings };
+};

package/src/og/card.ts

@@ -0,0 +1,92 @@
+import { Renderer } from "@takumi-rs/core";
+import { container, text } from "@takumi-rs/helpers";
+
+// Reuse one renderer (and its loaded default fonts) across all images.
+let renderer: Renderer | null = null;
+const getRenderer = (): Renderer => {
+  renderer ??= new Renderer();
+  return renderer;
+};
+
+const ACCENT_HEX: Record<string, string> = {
+  blue: "#3b82f6",
+  green: "#22c55e",
+  orange: "#f97316",
+  pink: "#ec4899",
+  purple: "#8b5cf6",
+  red: "#ef4444",
+  teal: "#14b8a6",
+};
+
+// OG rendering uses hex (Takumi's color parser does not accept oklch); named
+// presets map to hex, raw hex passes through, anything else falls back.
+const resolveAccent = (accent: string): string =>
+  ACCENT_HEX[accent] ?? (accent.startsWith("#") ? accent : "#3b82f6");
+
+export interface OgCardOptions {
+  title: string;
+  eyebrow?: string;
+  accent?: string;
+}
+
+const WIDTH = 1200;
+const HEIGHT = 630;
+
+/** Render a 1200x630 Open Graph card to a PNG buffer. */
+export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
+  const accent = resolveAccent(options.accent ?? "blue");
+
+  const node = container({
+    children: [
+      container({
+        children: [
+          container({
+            style: {
+              backgroundColor: accent,
+              borderRadius: 6,
+              height: 32,
+              width: 32,
+            },
+          }),
+          options.eyebrow
+            ? text(options.eyebrow, {
+                color: "#94a3b8",
+                fontSize: 30,
+              })
+            : container({}),
+        ],
+        style: { alignItems: "center", display: "flex", gap: 16 },
+      }),
+      text(options.title, {
+        color: "#f8fafc",
+        fontSize: 76,
+        fontWeight: 700,
+        lineHeight: 1.1,
+      }),
+      container({
+        style: {
+          backgroundColor: accent,
+          borderRadius: 4,
+          height: 8,
+          width: 120,
+        },
+      }),
+    ],
+    style: {
+      backgroundColor: "#0b1020",
+      color: "#ffffff",
+      display: "flex",
+      flexDirection: "column",
+      height: HEIGHT,
+      justifyContent: "space-between",
+      padding: 80,
+      width: WIDTH,
+    },
+  });
+
+  return getRenderer().render(node, {
+    format: "png",
+    height: HEIGHT,
+    width: WIDTH,
+  });
+};

package/src/og/index.ts

@@ -0,0 +1,2 @@
+export { renderOgImage } from "./card.ts";
+export type { OgCardOptions } from "./card.ts";

package/src/openapi/scalar.ts

@@ -0,0 +1,246 @@
+import { readFile } from "node:fs/promises";
+
+import { isAbsolute, join } from "pathe";
+
+import { scalarReferenceTemplate } from "../astro/templates.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { NavTab } from "../core/types.ts";
+import { resolveAccent, resolveRadius } from "../theme/palette.ts";
+
+/**
+ * API reference support, delegated wholesale to Scalar (`@scalar/astro`). Blume
+ * resolves the configured spec sources into routes, generates one self-contained
+ * Scalar page per source, and adds a nav tab. OpenAPI and AsyncAPI share this
+ * exact path — Scalar auto-detects the document type — so the only difference
+ * between the two config blocks is their default route and nav label.
+ */
+
+type ReferenceKind = "openapi" | "asyncapi";
+
+/** A spec source resolved to a concrete route and nav label. */
+export interface ReferenceSource {
+  kind: ReferenceKind;
+  /** Normalized route the reference mounts at, e.g. `/reference`. */
+  route: string;
+  label: string;
+  /** Local path or `http(s)` URL, verbatim from config. */
+  spec: string;
+  /** Per-block Scalar theme name override, if any. */
+  theme?: string;
+}
+
+/** A generated reference page, ready to write under `src/pages`. */
+export interface ReferenceFile {
+  /** Path relative to `src/pages`, e.g. `reference.astro`, `api/events.astro`. */
+  pagePath: string;
+  content: string;
+}
+
+const URL_SPEC = /^https?:\/\//u;
+const NON_SLUG = /[^a-z0-9]+/gu;
+const SLUG_EDGES = /^-+|-+$/gu;
+const ROUTE_EDGES = /^\/+|\/+$/gu;
+const TRAILING_SLASH = /\/+$/u;
+
+const slugify = (text: string): string =>
+  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
+
+/** Normalize a configured route to a single leading slash, no trailing slash. */
+const normalizeRoute = (route: string): string => {
+  const trimmed = route.trim();
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
+  return noTrailing === "" ? "/" : noTrailing;
+};
+
+/** The `src/pages`-relative file path for a reference route. */
+const referencePagePath = (route: string): string => {
+  const segments = route.replace(ROUTE_EDGES, "");
+  return `${segments === "" ? "index" : segments}.astro`;
+};
+
+/** A spec is a single source (`spec` shorthand prepended to any `sources`). */
+type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
+
+const sourcesOf = (
+  block: Block
+): { label?: string; route?: string; spec: string }[] => {
+  const sources = [...block.sources];
+  if (block.spec) {
+    sources.unshift({ spec: block.spec });
+  }
+  return sources;
+};
+
+const referencesFor = (
+  kind: ReferenceKind,
+  block: Block,
+  defaultLabel: string
+): ReferenceSource[] => {
+  if (!block.enabled) {
+    return [];
+  }
+  const sources = sourcesOf(block);
+  const base = normalizeRoute(block.route);
+
+  return sources.map((source, index) => {
+    const label =
+      source.label ??
+      (sources.length > 1 ? `${defaultLabel} ${index + 1}` : defaultLabel);
+
+    let route: string;
+    if (source.route) {
+      route = normalizeRoute(source.route);
+    } else if (sources.length === 1) {
+      route = base;
+    } else {
+      const suffix = source.label ? slugify(source.label) : "";
+      route = normalizeRoute(`${base}/${suffix || index + 1}`);
+    }
+
+    return { kind, label, route, spec: source.spec, theme: block.theme };
+  });
+};
+
+/**
+ * Resolve every enabled reference source into its route and label. Pure (no file
+ * IO), so the nav and the page generator stay in sync from one source of truth.
+ */
+export const resolveReferences = (
+  config: ResolvedConfig
+): ReferenceSource[] => [
+  ...referencesFor("openapi", config.openapi, "API Reference"),
+  ...referencesFor("asyncapi", config.asyncapi, "Events"),
+];
+
+/** Nav tabs (header links) for the configured references. */
+export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
+  resolveReferences(config).map((ref) => ({
+    label: ref.label,
+    path: ref.route,
+  }));
+
+/** Whether any reference block is enabled (gates dependency + page wiring). */
+export const hasReferences = (config: ResolvedConfig): boolean =>
+  config.openapi.enabled || config.asyncapi.enabled;
+
+const darkModeConfig = (
+  mode: ResolvedConfig["theme"]["mode"]
+): Record<string, boolean> => {
+  if (mode === "dark") {
+    return { darkMode: true };
+  }
+  if (mode === "light") {
+    return { darkMode: false };
+  }
+  // "system": leave Scalar to follow the OS preference.
+  return {};
+};
+
+/**
+ * Map Blume's theme onto Scalar's. An explicit `theme` name wins; otherwise we
+ * keep Scalar's default theme and layer Blume's accent/radius on top via
+ * `customCss`. Scalar re-injects `customCss` after its bundled theme, so these
+ * variables reliably override the defaults. Best-effort, not pixel-exact.
+ */
+const themeConfiguration = (
+  config: ResolvedConfig,
+  override?: string
+): Record<string, unknown> => {
+  if (override) {
+    return { theme: override };
+  }
+  const accent = resolveAccent(config.theme);
+  const radius = resolveRadius(config.theme);
+  return {
+    customCss: `:root,.light-mode,.dark-mode{--scalar-color-accent:${accent};--scalar-radius:${radius};}`,
+    ...darkModeConfig(config.theme.mode),
+  };
+};
+
+/** Build the Scalar spec config for a source: inline `content` or remote `url`. */
+const specConfiguration = async (
+  spec: string,
+  root: string
+): Promise<{ config: Record<string, unknown>; warning?: string }> => {
+  if (URL_SPEC.test(spec)) {
+    return { config: { url: spec } };
+  }
+  // A local spec is read at generate time and inlined as `content`, so the page
+  // stays self-contained and nothing is copied into the user's source tree.
+  const absolute = isAbsolute(spec) ? spec : join(root, spec);
+  try {
+    return { config: { content: await readFile(absolute, "utf-8") } };
+  } catch {
+    return {
+      config: { url: spec },
+      warning: `API reference spec not found: "${spec}" (looked in ${absolute}).`,
+    };
+  }
+};
+
+/**
+ * Build the Scalar reference page(s) for the project. Reads local specs, maps
+ * the theme, and skips routes that collide with a content page or another
+ * source. Returns the files to write under `src/pages` plus any warnings.
+ */
+export const buildReferenceFiles = async (options: {
+  config: ResolvedConfig;
+  root: string;
+  contentRoutes: ReadonlySet<string>;
+}): Promise<{ files: ReferenceFile[]; warnings: string[] }> => {
+  const { config, root, contentRoutes } = options;
+  const warnings: string[] = [];
+
+  // Resolve and dedupe routes first (sync), then read every spec in parallel.
+  const seen = new Set<string>();
+  const accepted: ReferenceSource[] = [];
+  for (const ref of resolveReferences(config)) {
+    if (seen.has(ref.route)) {
+      warnings.push(
+        `Two API reference sources resolve to ${ref.route}; keeping the first.`
+      );
+      continue;
+    }
+    if (contentRoutes.has(ref.route)) {
+      warnings.push(
+        `API reference route ${ref.route} collides with a content page; skipping the reference there.`
+      );
+      continue;
+    }
+    seen.add(ref.route);
+    accepted.push(ref);
+  }
+
+  const built = await Promise.all(
+    accepted.map(async (ref) => ({
+      ref,
+      spec: await specConfiguration(ref.spec, root),
+    }))
+  );
+
+  const files: ReferenceFile[] = [];
+  for (const { ref, spec } of built) {
+    if (spec.warning) {
+      warnings.push(spec.warning);
+    }
+    const pagePath = referencePagePath(ref.route);
+    // Relative path from the page back to src/generated/data.json: a page one
+    // directory deep (api/events.astro) needs an extra "../".
+    const depth = pagePath.split("/").length - 1;
+    files.push({
+      content: scalarReferenceTemplate({
+        configuration: {
+          ...spec.config,
+          ...themeConfiguration(config, ref.theme),
+        },
+        dataImport: `${"../".repeat(depth + 1)}generated/data.json`,
+        route: ref.route,
+        title: ref.label,
+      }),
+      pagePath,
+    });
+  }
+
+  return { files, warnings };
+};