blume 0.0.0 → 0.1.1

package/src/core/tsconfig-aliases.ts

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+import { dirname, isAbsolute, join, resolve } from "pathe";
+
+/**
+ * Read the project's TypeScript path aliases (`compilerOptions.paths`) and turn
+ * them into Vite `resolve.alias` entries, so `@/`-style imports in custom pages,
+ * islands, and components resolve in the generated Astro build exactly as they
+ * do in the user's own tooling.
+ *
+ * The generated `.blume/` runtime is its own Astro project with its own tsconfig
+ * and never inherits the project's, so without this every shadcn-style `@/…`
+ * import would have to be rewritten to a relative path. Reading the aliases here
+ * lets those components port over unchanged.
+ *
+ * Best-effort and non-fatal: tsconfig is parsed leniently (it is JSONC —
+ * comments and trailing commas), a single `extends` chain is followed to the
+ * file that actually declares `paths`, and anything unparseable yields no
+ * aliases (the prior behavior).
+ */
+
+/** Strip `//` line and `/* *\/` block comments that sit outside strings. */
+const stripJsonComments = (text: string): string => {
+  let out = "";
+  let inString = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      out += char;
+      if (char === "\\") {
+        out += text[index + 1] ?? "";
+        index += 1;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    if (char === "/" && text[index + 1] === "/") {
+      const newline = text.indexOf("\n", index + 2);
+      index = newline === -1 ? text.length : newline - 1;
+      continue;
+    }
+    if (char === "/" && text[index + 1] === "*") {
+      const end = text.indexOf("*/", index + 2);
+      index = end === -1 ? text.length : end + 1;
+      continue;
+    }
+    out += char;
+  }
+  return out;
+};
+
+const TRAILING_COMMA = /,(?<rest>\s*[}\]])/gu;
+
+/** Parse JSONC (tsconfig) into a plain object, or null if it can't be read. */
+const parseJsonc = (text: string): Record<string, unknown> | null => {
+  try {
+    const cleaned = stripJsonComments(text).replaceAll(
+      TRAILING_COMMA,
+      "$<rest>"
+    );
+    const value: unknown = JSON.parse(cleaned);
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const isFile = (path: string): boolean => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/** Resolve a tsconfig `extends` target (relative path, directory, or package). */
+const resolveExtends = (spec: string, fromDir: string): string | null => {
+  if (spec.startsWith(".") || isAbsolute(spec)) {
+    const candidates = spec.endsWith(".json")
+      ? [resolve(fromDir, spec)]
+      : [
+          resolve(fromDir, `${spec}.json`),
+          resolve(fromDir, spec, "tsconfig.json"),
+          resolve(fromDir, spec),
+        ];
+    return candidates.find(isFile) ?? null;
+  }
+  // A bare specifier points at a package's shared config (e.g. `@tsconfig/*`).
+  try {
+    const require_ = createRequire(pathToFileURL(join(fromDir, "_.js")).href);
+    for (const sub of [`${spec}/tsconfig.json`, spec]) {
+      try {
+        return require_.resolve(sub);
+      } catch {
+        // try the next candidate
+      }
+    }
+  } catch {
+    // createRequire failed; fall through
+  }
+  return null;
+};
+
+interface LoadedPaths {
+  /** Directory `paths` entries resolve against (`dirname(file)` + `baseUrl`). */
+  baseDir: string;
+  paths: Record<string, unknown>;
+}
+
+/** Find the nearest tsconfig in an `extends` chain that declares `paths`. */
+const loadPaths = (file: string, seen: Set<string>): LoadedPaths | null => {
+  if (seen.has(file) || !existsSync(file)) {
+    return null;
+  }
+  seen.add(file);
+  const json = parseJsonc(readFileSync(file, "utf-8"));
+  if (!json) {
+    return null;
+  }
+  const options = (json.compilerOptions ?? {}) as Record<string, unknown>;
+  if (options.paths && typeof options.paths === "object") {
+    const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : ".";
+    return {
+      baseDir: resolve(dirname(file), baseUrl),
+      paths: options.paths as Record<string, unknown>,
+    };
+  }
+  // `extends` is a string or, since TS 5.0, an array searched first-to-last.
+  const bases = Array.isArray(json.extends)
+    ? json.extends
+    : [json.extends].filter(Boolean);
+  for (const base of bases) {
+    if (typeof base !== "string") {
+      continue;
+    }
+    const resolved = resolveExtends(base, dirname(file));
+    const found = resolved ? loadPaths(resolved, seen) : null;
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+};
+
+/** Convert one tsconfig `paths` mapping to a Vite alias, or null to skip. */
+const toAlias = (
+  key: string,
+  value: unknown,
+  baseDir: string
+): { find: string; replacement: string } | null => {
+  // tsconfig allows a fallback array; Vite aliases are 1:1, so take the first.
+  const first = Array.isArray(value) ? value[0] : value;
+  if (typeof first !== "string") {
+    return null;
+  }
+  const find = key.endsWith("/*") ? key.slice(0, -2) : key;
+  const target = first.endsWith("/*") ? first.slice(0, -2) : first;
+  // A bare `*`/`/*` catch-all would alias every import — never wire that.
+  if (find === "" || find === "*") {
+    return null;
+  }
+  return { find, replacement: resolve(baseDir, target) };
+};
+
+/**
+ * Resolve the project's tsconfig/jsconfig path aliases to absolute Vite
+ * `resolve.alias` entries (`find` → absolute replacement). Returns `{}` when no
+ * config or no usable `paths` is found.
+ */
+export const resolveTsconfigAliases = (
+  root: string
+): Record<string, string> => {
+  const entry = ["tsconfig.json", "jsconfig.json"]
+    .map((name) => join(root, name))
+    .find((file) => existsSync(file));
+  if (!entry) {
+    return {};
+  }
+  const loaded = loadPaths(entry, new Set());
+  if (!loaded) {
+    return {};
+  }
+  const aliases: Record<string, string> = {};
+  for (const [key, value] of Object.entries(loaded.paths)) {
+    const alias = toAlias(key, value, loaded.baseDir);
+    if (alias) {
+      aliases[alias.find] = alias.replacement;
+    }
+  }
+  return aliases;
+};

package/src/core/types.ts

@@ -0,0 +1,261 @@
+import type {
+  DirectoryMode,
+  PageMeta,
+  ResolvedConfig,
+  SidebarDisplay,
+} from "./schema.ts";
+
+/** Severity levels for Blume diagnostics. */
+export type DiagnosticSeverity = "error" | "warning" | "info";
+
+/**
+ * A single actionable diagnostic. Diagnostics are printable in the CLI, the
+ * Astro/Vite overlay, and as JSON for editor integrations.
+ */
+export interface Diagnostic {
+  code: string;
+  severity: DiagnosticSeverity;
+  message: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  schemaPath?: string;
+  suggestion?: string;
+  docsUrl?: string;
+}
+
+/** A heading extracted from page content, used for the TOC and search. */
+export interface Heading {
+  depth: number;
+  text: string;
+  slug: string;
+}
+
+/** A link target discovered in page content, anchored to its source line. */
+export interface PageLink {
+  /** Raw link target as written, e.g. `./foo`, `/api#auth`, `https://x.dev`. */
+  target: string;
+  /** 1-based line number in the source file. */
+  line: number;
+  /** 1-based column of the target within the line. */
+  column: number;
+}
+
+/**
+ * Resolved project paths. Computed once per CLI invocation and threaded
+ * through the core pipeline.
+ */
+export interface ProjectContext {
+  /** Absolute path to the user project root. */
+  root: string;
+  /** Absolute path to the content root (e.g. `<root>/docs`). */
+  contentRoot: string;
+  /** Absolute path to the custom pages dir, if it exists. */
+  pagesRoot: string | null;
+  /** Absolute path to the generated runtime (`<root>/.blume`). */
+  outDir: string;
+  /** Absolute path to the user `theme.css`, if present. */
+  themeFile: string | null;
+  /** Absolute path to the user `components.ts`/`.tsx`, if present. */
+  componentsFile: string | null;
+  /** Absolute path to the resolved config file, if any was found. */
+  configFile: string | null;
+}
+
+/**
+ * A normalized content page. This is the unit the route manifest, nav graph,
+ * and search index are derived from.
+ */
+export interface PageRecord {
+  /** Stable, globally-unique id: `"<source>:<ref>"`, e.g. `filesystem:api/auth.mdx`. */
+  id: string;
+  /** Provenance: the owning source's name and its source-local ref. */
+  source: { name: string; ref: string };
+  /** Absolute source path. Populated by the filesystem adapter only (back-compat). */
+  sourcePath?: string;
+  /**
+   * Renderable body captured at scan time. Set for staged (non-filesystem)
+   * sources so they can be materialized to `.blume/content` and so soft
+   * consumers need no re-read; omitted for filesystem entries (read from disk).
+   */
+  body?: { format: "md" | "mdx"; text: string };
+  /** Adapter-supplied "edit this page" URL (non-filesystem sources). */
+  editUrl?: string;
+  /** Astro collection this entry renders through; defaults to `"docs"`. */
+  collection?: string;
+  /** Astro collection-relative entry id for `getEntry`; defaults to the ref. */
+  entryId?: string;
+  /** URL route, e.g. `/api/auth`. Always starts with `/`. Locale-prefixed under i18n. */
+  route: string;
+  /** Resolved locale code; the default locale when not under i18n. */
+  locale: string;
+  /**
+   * Locale-agnostic logical route shared by every translation (e.g.
+   * `/guides/x`). Pages with the same key are translations of each other.
+   */
+  translationKey: string;
+  /**
+   * Content-relative path with the leading locale directory stripped, used for
+   * sidebar grouping so the locale dir is not surfaced as a nav group. Equals
+   * `id` for single-locale projects.
+   */
+  navPath: string;
+  /** Path segments without numeric prefixes, e.g. `["api", "auth"]`. */
+  segments: string[];
+  /** Group-folder labels this page lives under, e.g. `["guides"]`. */
+  groups: string[];
+  title: string;
+  description?: string;
+  contentType: string;
+  meta: PageMeta;
+  headings: Heading[];
+  /** Whether the file is `.md`/`.mdx`. */
+  format: "md" | "mdx";
+  /** Internal/asset links discovered in the page (for validation). */
+  links: PageLink[];
+  /** Resolved "last updated" ISO date, when the feature is enabled. */
+  lastModified?: string;
+}
+
+/** A node in the generated navigation tree. */
+export type NavNode =
+  | {
+      kind: "page";
+      label: string;
+      route: string;
+      description?: string;
+      icon?: string;
+      badge?: string;
+      deprecated?: boolean;
+      pageId: string;
+    }
+  | {
+      kind: "group";
+      label: string;
+      badge?: string;
+      directory?: DirectoryMode;
+      display?: SidebarDisplay;
+      icon?: string;
+      route?: string;
+      collapsed?: boolean;
+      children: NavNode[];
+    };
+
+/** Top-level tab/section. */
+export interface NavTab {
+  label: string;
+  path: string;
+  icon?: string;
+  items?: NavSelectorItem[];
+}
+
+/** A selectable navigation option inside a tab menu or top selector. */
+export interface NavSelectorItem {
+  label: string;
+  path: string;
+  description?: string;
+  icon?: string;
+  tag?: string;
+}
+
+/** Top-level Mintlify-style partition selectors. */
+export interface NavSelector {
+  label: string;
+  kind: "dropdown" | "language" | "product" | "version";
+  items: NavSelectorItem[];
+}
+
+/** Sidebar tree used when the current route belongs to a nav partition. */
+export interface NavSidebarVariant {
+  path: string;
+  sidebar: NavNode[];
+}
+
+/** Chrome overrides used when the current route belongs to a nav partition. */
+export interface NavChromeVariant {
+  path: string;
+  banner?: ResolvedConfig["banner"];
+  footer?: ResolvedConfig["footer"];
+  navbar?: ResolvedConfig["navbar"];
+}
+
+/** The complete navigation model derived from the content graph. */
+export interface Navigation {
+  tabs: NavTab[];
+  selectors: NavSelector[];
+  chromeVariants: NavChromeVariant[];
+  sidebar: NavNode[];
+  sidebarVariants: NavSidebarVariant[];
+  /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
+  repoUrl?: string | null;
+}
+
+/** The full content graph: the source of truth for generated modules. */
+export interface ContentGraph {
+  pages: PageRecord[];
+  /** Default-locale navigation (the whole site when not under i18n). */
+  navigation: Navigation;
+  /** Navigation per locale; one entry per configured locale under i18n. */
+  navigationByLocale: Record<string, Navigation>;
+  /** Map of route -> pageId for fast lookup and duplicate detection. */
+  routes: Map<string, string>;
+  diagnostics: Diagnostic[];
+}
+
+/** A locale a logical page exists in, for the switcher and `hreflang`. */
+export interface RouteAlternate {
+  locale: string;
+  path: string;
+}
+
+/** A resolved language-switcher entry for the current page. */
+export interface LocaleSwitchOption {
+  code: string;
+  label: string;
+  dir: "ltr" | "rtl";
+  /** Target URL: the real translation, or the localized fallback URL. */
+  href: string;
+  current: boolean;
+  /** True when this locale has no real translation (renders fallback content). */
+  untranslated: boolean;
+}
+
+/** A route entry written to `blume.manifest.json`. */
+export interface RouteManifestEntry {
+  id: string;
+  /** Provenance: the owning source's name and its source-local ref. */
+  source: { name: string; ref: string };
+  /** Astro collection this entry renders through (`"docs"` | `"staged"`). */
+  collection: string;
+  /** Astro collection-relative entry id, passed to `getEntry`. */
+  entryId: string;
+  path: string;
+  /** Absolute source path; populated for filesystem entries only (back-compat). */
+  sourcePath?: string;
+  /** Adapter-supplied "edit this page" URL (non-filesystem sources). */
+  editUrl?: string;
+  title: string;
+  contentType: string;
+  hidden: boolean;
+  draft: boolean;
+  /** Whether the page should be included in the search index. */
+  indexable: boolean;
+  /** Resolved locale code; the default locale when not under i18n. */
+  locale: string;
+  /** Locales this logical page is genuinely translated into (excludes fallbacks). */
+  alternates: RouteAlternate[];
+  /** True when this route renders fallback content for a missing translation. */
+  fallback?: boolean;
+  /** Resolved "last updated" ISO date, when the feature is enabled. */
+  lastModified?: string;
+}
+
+/** The generated runtime contract between core and the Astro project. */
+export interface BlumeManifest {
+  version: number;
+  blumeVersion: string;
+  projectRoot: string;
+  contentRoot: string;
+  output: ResolvedConfig["deployment"]["output"];
+  routes: RouteManifestEntry[];
+}

package/src/core/ui-packs/ar.ts

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Arabic (ar) UI strings. */
+export const ar: UIStringsOverride = {
+  actions: {
+    addToCursor: "إضافة إلى Cursor",
+    addToVscode: "إضافة إلى VS Code",
+    askAI: "اسأل الذكاء الاصطناعي عن هذه الصفحة",
+    connectMcp: "الاتصال بـ MCP",
+    copied: "تم النسخ!",
+    copyClaudeCode: "نسخ أمر Claude Code",
+    copyMarkdown: "نسخ بصيغة Markdown",
+    copyServerUrl: "نسخ عنوان URL للخادم",
+    edit: "التعديل على GitHub",
+    openInChat: "فتح في المحادثة",
+    scrollToTop: "العودة إلى الأعلى",
+  },
+  ask: {
+    empty: "اطرح سؤالاً حول الوثائق.",
+    error: "عذراً، حدث خطأ ما.",
+    label: "اطرح سؤالاً",
+    placeholder: "اطرح سؤالاً…",
+    send: "إرسال",
+    title: "اسأل الذكاء الاصطناعي",
+  },
+  feedback: {
+    no: "لا",
+    question: "هل كانت هذه الصفحة مفيدة؟",
+    thanks: "شكراً على ملاحظاتك!",
+    yes: "نعم",
+  },
+  languageSwitcher: { label: "اللغة", untranslated: "غير مترجم" },
+  page: {
+    lastUpdated: "آخر تحديث في",
+    next: "التالي",
+    previous: "السابق",
+    skipToContent: "الانتقال إلى المحتوى",
+  },
+  search: {
+    button: "بحث",
+    devOnly: "البحث متاح في إصدار الإنتاج.",
+    label: "البحث في الوثائق",
+    noResults: "لم يتم العثور على نتائج.",
+    placeholder: "البحث في الوثائق…",
+  },
+  toc: { title: "في هذه الصفحة" },
+};

package/src/core/ui-packs/bg.ts

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Bulgarian (bg) UI strings. */
+export const bg: UIStringsOverride = {
+  actions: {
+    addToCursor: "Добави в Cursor",
+    addToVscode: "Добави във VS Code",
+    askAI: "Попитай ИИ за тази страница",
+    connectMcp: "Свържи се с MCP",
+    copied: "Копирано!",
+    copyClaudeCode: "Копирай командата на Claude Code",
+    copyMarkdown: "Копирай като Markdown",
+    copyServerUrl: "Копирай URL на сървъра",
+    edit: "Редактирай в GitHub",
+    openInChat: "Отвори в чата",
+    scrollToTop: "Нагоре",
+  },
+  ask: {
+    empty: "Задайте въпрос за документацията.",
+    error: "Съжаляваме, нещо се обърка.",
+    label: "Задайте въпрос",
+    placeholder: "Задайте въпрос…",
+    send: "Изпрати",
+    title: "Попитай ИИ",
+  },
+  feedback: {
+    no: "Не",
+    question: "Беше ли полезна тази страница?",
+    thanks: "Благодарим за обратната връзка!",
+    yes: "Да",
+  },
+  languageSwitcher: { label: "Език", untranslated: "Непреведено" },
+  page: {
+    lastUpdated: "Последна актуализация",
+    next: "Напред",
+    previous: "Назад",
+    skipToContent: "Към съдържанието",
+  },
+  search: {
+    button: "Търсене",
+    devOnly: "Търсенето е достъпно в производствената компилация.",
+    label: "Търсене в документацията",
+    noResults: "Няма намерени резултати.",
+    placeholder: "Търсене в документацията…",
+  },
+  toc: { title: "На тази страница" },
+};

package/src/core/ui-packs/bn.ts

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Bengali (bn) UI strings. */
+export const bn: UIStringsOverride = {
+  actions: {
+    addToCursor: "Cursor-এ যোগ করুন",
+    addToVscode: "VS Code-এ যোগ করুন",
+    askAI: "এই পৃষ্ঠা সম্পর্কে AI-কে জিজ্ঞাসা করুন",
+    connectMcp: "MCP-তে সংযোগ করুন",
+    copied: "অনুলিপি করা হয়েছে!",
+    copyClaudeCode: "Claude Code কমান্ড অনুলিপি করুন",
+    copyMarkdown: "Markdown হিসেবে অনুলিপি করুন",
+    copyServerUrl: "সার্ভার URL অনুলিপি করুন",
+    edit: "GitHub-এ সম্পাদনা করুন",
+    openInChat: "চ্যাটে খুলুন",
+    scrollToTop: "উপরে যান",
+  },
+  ask: {
+    empty: "ডকুমেন্টেশন সম্পর্কে একটি প্রশ্ন করুন।",
+    error: "দুঃখিত, কিছু একটা ভুল হয়েছে।",
+    label: "একটি প্রশ্ন করুন",
+    placeholder: "একটি প্রশ্ন করুন…",
+    send: "পাঠান",
+    title: "AI-কে জিজ্ঞাসা করুন",
+  },
+  feedback: {
+    no: "না",
+    question: "এই পৃষ্ঠাটি কি সহায়ক ছিল?",
+    thanks: "আপনার মতামতের জন্য ধন্যবাদ!",
+    yes: "হ্যাঁ",
+  },
+  languageSwitcher: { label: "ভাষা", untranslated: "অনূদিত নয়" },
+  page: {
+    lastUpdated: "সর্বশেষ আপডেট",
+    next: "পরবর্তী",
+    previous: "পূর্ববর্তী",
+    skipToContent: "বিষয়বস্তুতে যান",
+  },
+  search: {
+    button: "অনুসন্ধান",
+    devOnly: "অনুসন্ধান প্রোডাকশন বিল্ডে উপলব্ধ।",
+    label: "ডকুমেন্টেশন অনুসন্ধান করুন",
+    noResults: "কোনো ফলাফল পাওয়া যায়নি।",
+    placeholder: "ডকুমেন্টেশন অনুসন্ধান করুন…",
+  },
+  toc: { title: "এই পৃষ্ঠায়" },
+};

package/src/core/ui-packs/ca.ts

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Catalan (ca) UI strings. */
+export const ca: UIStringsOverride = {
+  actions: {
+    addToCursor: "Afegeix a Cursor",
+    addToVscode: "Afegeix a VS Code",
+    askAI: "Pregunta a la IA sobre aquesta pàgina",
+    connectMcp: "Connecta a MCP",
+    copied: "Copiat!",
+    copyClaudeCode: "Copia l'ordre de Claude Code",
+    copyMarkdown: "Copia com a Markdown",
+    copyServerUrl: "Copia l'URL del servidor",
+    edit: "Edita a GitHub",
+    openInChat: "Obre al xat",
+    scrollToTop: "Torna a dalt",
+  },
+  ask: {
+    empty: "Fes una pregunta sobre la documentació.",
+    error: "Ho sentim, alguna cosa ha anat malament.",
+    label: "Fes una pregunta",
+    placeholder: "Fes una pregunta…",
+    send: "Envia",
+    title: "Pregunta a la IA",
+  },
+  feedback: {
+    no: "No",
+    question: "Aquesta pàgina t'ha estat útil?",
+    thanks: "Gràcies pels teus comentaris!",
+    yes: "Sí",
+  },
+  languageSwitcher: { label: "Idioma", untranslated: "Sense traduir" },
+  page: {
+    lastUpdated: "Última actualització el",
+    next: "Següent",
+    previous: "Anterior",
+    skipToContent: "Vés al contingut",
+  },
+  search: {
+    button: "Cerca",
+    devOnly: "La cerca està disponible a la compilació de producció.",
+    label: "Cerca a la documentació",
+    noResults: "No s'ha trobat cap resultat.",
+    placeholder: "Cerca a la documentació…",
+  },
+  toc: { title: "En aquesta pàgina" },
+};