blume 0.0.0 → 0.1.0

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" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Czech (cs) UI strings. */
+export const cs: UIStringsOverride = {
+  actions: {
+    addToCursor: "Přidat do Cursoru",
+    addToVscode: "Přidat do VS Code",
+    askAI: "Zeptat se AI na tuto stránku",
+    connectMcp: "Připojit k MCP",
+    copied: "Zkopírováno!",
+    copyClaudeCode: "Kopírovat příkaz Claude Code",
+    copyMarkdown: "Kopírovat jako Markdown",
+    copyServerUrl: "Kopírovat URL serveru",
+    edit: "Upravit na GitHubu",
+    openInChat: "Otevřít v chatu",
+    scrollToTop: "Zpět nahoru",
+  },
+  ask: {
+    empty: "Zeptejte se na dokumentaci.",
+    error: "Omlouváme se, něco se pokazilo.",
+    label: "Položit otázku",
+    placeholder: "Položit otázku…",
+    send: "Odeslat",
+    title: "Zeptat se AI",
+  },
+  feedback: {
+    no: "Ne",
+    question: "Byla tato stránka užitečná?",
+    thanks: "Děkujeme za zpětnou vazbu!",
+    yes: "Ano",
+  },
+  languageSwitcher: { label: "Jazyk", untranslated: "Nepřeloženo" },
+  page: {
+    lastUpdated: "Naposledy aktualizováno",
+    next: "Další",
+    previous: "Předchozí",
+    skipToContent: "Přejít k obsahu",
+  },
+  search: {
+    button: "Hledat",
+    devOnly: "Vyhledávání je dostupné v produkčním buildu.",
+    label: "Prohledat dokumentaci",
+    noResults: "Nebyly nalezeny žádné výsledky.",
+    placeholder: "Prohledat dokumentaci…",
+  },
+  toc: { title: "Na této stránce" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Danish (da) UI strings. */
+export const da: UIStringsOverride = {
+  actions: {
+    addToCursor: "Føj til Cursor",
+    addToVscode: "Føj til VS Code",
+    askAI: "Spørg AI om denne side",
+    connectMcp: "Opret forbindelse til MCP",
+    copied: "Kopieret!",
+    copyClaudeCode: "Kopiér Claude Code-kommando",
+    copyMarkdown: "Kopiér som Markdown",
+    copyServerUrl: "Kopiér server-URL",
+    edit: "Rediger på GitHub",
+    openInChat: "Åbn i chat",
+    scrollToTop: "Tilbage til toppen",
+  },
+  ask: {
+    empty: "Stil et spørgsmål om dokumentationen.",
+    error: "Beklager, noget gik galt.",
+    label: "Stil et spørgsmål",
+    placeholder: "Stil et spørgsmål…",
+    send: "Send",
+    title: "Spørg AI",
+  },
+  feedback: {
+    no: "Nej",
+    question: "Var denne side nyttig?",
+    thanks: "Tak for din feedback!",
+    yes: "Ja",
+  },
+  languageSwitcher: { label: "Sprog", untranslated: "Ikke oversat" },
+  page: {
+    lastUpdated: "Senest opdateret den",
+    next: "Næste",
+    previous: "Forrige",
+    skipToContent: "Spring til indhold",
+  },
+  search: {
+    button: "Søg",
+    devOnly: "Søgning er tilgængelig i produktionsbygningen.",
+    label: "Søg i dokumentationen",
+    noResults: "Ingen resultater fundet.",
+    placeholder: "Søg i dokumentationen…",
+  },
+  toc: { title: "På denne side" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** German (de) UI strings. */
+export const de: UIStringsOverride = {
+  actions: {
+    addToCursor: "Zu Cursor hinzufügen",
+    addToVscode: "Zu VS Code hinzufügen",
+    askAI: "KI zu dieser Seite fragen",
+    connectMcp: "Mit MCP verbinden",
+    copied: "Kopiert!",
+    copyClaudeCode: "Claude-Code-Befehl kopieren",
+    copyMarkdown: "Als Markdown kopieren",
+    copyServerUrl: "Server-URL kopieren",
+    edit: "Auf GitHub bearbeiten",
+    openInChat: "Im Chat öffnen",
+    scrollToTop: "Nach oben scrollen",
+  },
+  ask: {
+    empty: "Stelle eine Frage zur Dokumentation.",
+    error: "Entschuldigung, etwas ist schiefgelaufen.",
+    label: "Eine Frage stellen",
+    placeholder: "Eine Frage stellen…",
+    send: "Senden",
+    title: "KI fragen",
+  },
+  feedback: {
+    no: "Nein",
+    question: "War diese Seite hilfreich?",
+    thanks: "Danke für dein Feedback!",
+    yes: "Ja",
+  },
+  languageSwitcher: { label: "Sprache", untranslated: "Nicht übersetzt" },
+  page: {
+    lastUpdated: "Zuletzt aktualisiert am",
+    next: "Weiter",
+    previous: "Zurück",
+    skipToContent: "Zum Inhalt springen",
+  },
+  search: {
+    button: "Suchen",
+    devOnly: "Die Suche ist im Produktions-Build verfügbar.",
+    label: "Dokumentation durchsuchen",
+    noResults: "Keine Ergebnisse gefunden.",
+    placeholder: "Dokumentation durchsuchen…",
+  },
+  toc: { title: "Auf dieser Seite" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Greek (el) UI strings. */
+export const el: 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: "Σε αυτή τη σελίδα" },
+};