blume 0.1.0 → 0.1.2

package/dist/types/core/bridge.d.ts

@@ -0,0 +1,24 @@
+import type { BlumeConfig } from "./schema.ts";
+/** A detected docs-tool config that Blume can serve without a migration. */
+export interface BridgeDetection {
+    /** Which foreign docs tool was detected. */
+    tool: "mintlify";
+    /** Absolute path of the detected config file (`docs.json`/`mint.json`). */
+    configFile: string;
+    /** A Blume config synthesized from the foreign config, ready to validate. */
+    raw: BlumeConfig;
+}
+/**
+ * Detect a Mintlify project at `root` and synthesize an equivalent Blume config.
+ *
+ * "Bridge mode" lets a team swap `mintlify dev` for `blume dev` with no file
+ * changes: `docs.json` is translated to Blume config (`loadMintlifyConfig`) and
+ * its content block is rewired to a single `mintlify` content source, which
+ * transforms each MDX page to Blume idiom at scan time. The original
+ * `content.root`/`exclude` and `variables` move onto the source (Blume has no
+ * runtime variable substitution, so globals are inlined into content there).
+ *
+ * Returns `null` when no Mintlify config is present. Only called when no
+ * `blume.config.*` exists, so an explicit Blume config always takes precedence.
+ */
+export declare const detectMintlifyBridge: (root: string) => Promise<BridgeDetection | null>;

package/dist/types/core/config.d.ts

@@ -0,0 +1,35 @@
+import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { Diagnostic } from "./types.ts";
+/**
+ * Identity helper for authoring `blume.config.ts`. Exists for type inference
+ * and a stable future home for plugin hooks; it does not transform input.
+ */
+export declare const defineConfig: (config: BlumeConfig) => BlumeConfig;
+/** Bridge mode info: a foreign docs tool Blume is serving without migrating. */
+export interface ConfigBridge {
+    tool: "mintlify";
+    /** Absolute path of the foreign config file (`docs.json`/`mint.json`). */
+    configFile: string;
+}
+/** Result of loading + validating a project config. */
+export interface ConfigLoadResult {
+    config: ResolvedConfig;
+    /** Absolute path of the config file used, or null when defaults were used. */
+    configFile: string | null;
+    /** Set when a foreign docs config (e.g. Mintlify) is being bridged. */
+    bridge: ConfigBridge | null;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Load and validate the project config. When no config file exists, schema
+ * defaults produce a fully resolved config so the zero-boilerplate path works.
+ */
+export declare const loadConfig: (root: string, 
+/**
+ * Supplied only by `blume dev`: the local dev server URL, used as the
+ * `deployment.site` fallback when none is configured or detected. Builds
+ * never pass it, so production output can't end up pointing at localhost.
+ */
+options?: {
+    devServerUrl?: string;
+}) => Promise<ConfigLoadResult>;

package/dist/types/core/data.d.ts

@@ -0,0 +1,129 @@
+import type { UIStrings } from "./i18n-ui.ts";
+import type { ResolvedConfig, SearchProvider } from "./schema.ts";
+import type { Navigation, RouteAlternate } from "./types.ts";
+/**
+ * The shape of the `blume:data` virtual module — the resolved, serializable
+ * snapshot of a site that custom `.astro` pages read with
+ * `import data from "blume:data"`. `buildRuntimeData` (`astro/generate.ts`)
+ * produces exactly this object and annotates it with {@link BlumeData}, so the
+ * documented type and the emitted JSON stay in lockstep.
+ */
+/** Resolved site logo: an inlined SVG, or light/dark image URLs. */
+export interface BlumeLogo {
+    svg?: string;
+    light?: string;
+    dark?: string;
+    alt: string;
+    href: string;
+}
+/** A favicon or apple-touch-icon: a link href plus an optional MIME type. */
+export interface BlumeFavicon {
+    href: string;
+    type?: string;
+}
+/** Announcement banner, normalized from its config (string shorthand or object). */
+export interface BlumeBanner {
+    content: string;
+    link?: {
+        href: string;
+        text: string;
+    };
+    dismissible: boolean;
+    /** Dismissal key: the configured id, else the content itself. */
+    key: string;
+}
+/** A generated syndication feed surfaced in the UI. */
+export interface BlumeFeed {
+    href: string;
+    title: string;
+}
+/** One configured locale, as exposed to the runtime. */
+export interface BlumeDataLocale {
+    code: string;
+    dir: "ltr" | "rtl";
+    label: string;
+}
+/** Resolved i18n settings; `null` when the site is single-locale. */
+export interface BlumeDataI18n {
+    defaultLocale: string;
+    /** Locale whose content renders for a missing translation; `null` disables it. */
+    fallbackLocale: string | null;
+    hideDefaultLocalePrefix: boolean;
+    locales: BlumeDataLocale[];
+}
+/** A single content route, with the metadata custom pages can read. */
+export interface BlumeRoute {
+    /** Locales this logical page is translated into (excludes fallbacks). */
+    alternates: RouteAlternate[];
+    /** Astro collection the entry renders through (`"docs"` | `"staged"`). */
+    collection: string;
+    draft: boolean;
+    /** "Edit this page" URL, or `null` when no repo/source provides one. */
+    editUrl: string | null;
+    /** Astro collection entry id (for `getEntry`/`getCollection`); matches `id`. */
+    entryId: string;
+    /** True when this route renders fallback content for a missing translation. */
+    fallback: boolean;
+    hidden: boolean;
+    id: string;
+    /** Whether the page is part of the search index. */
+    indexable: boolean;
+    /** ISO "last updated" date when the feature is on, else `null`. */
+    lastModified: string | null;
+    /** Resolved locale code (the default locale when not under i18n). */
+    locale: string;
+    path: string;
+    title: string;
+}
+/** Site-wide settings derived from `blume.config` — the `config` field of {@link BlumeData}. */
+export interface BlumeDataConfig {
+    analytics: NonNullable<ResolvedConfig["analytics"]> | null;
+    /** Apple touch icon, or `null` when none is configured/detected. */
+    appleIcon: BlumeFavicon | null;
+    banner: BlumeBanner | null;
+    /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
+    codeWrap: boolean;
+    description: string | undefined;
+    favicon: BlumeFavicon;
+    feedback: boolean;
+    i18n: BlumeDataI18n | null;
+    /** `markdown.imageZoom`: click-to-zoom content images. */
+    imageZoom: boolean;
+    logo: BlumeLogo | null;
+    /** Hosted MCP server, or `null` when MCP is off. */
+    mcp: {
+        name: string;
+        route: string;
+    } | null;
+    /** Open Graph image generation. */
+    og: {
+        enabled: boolean;
+    };
+    /** Repository URL for header/edit links, or `null`. */
+    repoUrl: string | null;
+    search: {
+        enabled: boolean;
+        provider: SearchProvider;
+    };
+    /** Deployment site URL, or `null` when none is configured/detected. */
+    site: string | null;
+    structuredData: boolean;
+    theme: ResolvedConfig["theme"];
+    title: string;
+}
+/** The `blume:data` module a Blume site's custom pages import. */
+export interface BlumeData {
+    config: BlumeDataConfig;
+    feeds: BlumeFeed[];
+    /** CSS variable names for the configured fonts (Astro `<Font>` integration). */
+    fontCssVars: string[];
+    /** Sidebar + tab tree for the default locale. */
+    navigation: Navigation;
+    /** Per-locale navigation trees, keyed by locale code (empty without i18n). */
+    navigationByLocale: Record<string, Navigation>;
+    routes: BlumeRoute[];
+    /** Resolved UI strings for the default locale. */
+    ui: UIStrings;
+    /** Per-locale UI strings, keyed by locale code (empty without i18n). */
+    uiByLocale: Record<string, UIStrings>;
+}

package/dist/types/core/define-components.d.ts

@@ -0,0 +1,27 @@
+import type { HydrationMode } from "./schema.ts";
+/**
+ * A reference to a component. Either an imported component (preferred, for type
+ * safety) or a string path resolved relative to the project root.
+ */
+export type ComponentReference = unknown | string;
+/** An interactive component plus its hydration strategy. */
+export interface IslandDescriptor {
+    component: ComponentReference;
+    client: HydrationMode;
+    /** Required when `client` is `"media"`. */
+    media?: string;
+}
+/** A component override: a static component or a hydrated island. */
+export type ComponentOverride = ComponentReference | IslandDescriptor;
+/** User-authored component overrides, grouped by surface. */
+export interface ComponentOverrides {
+    /** MDX component map overrides (`Callout`, `Card`, ...). */
+    mdx?: Record<string, ComponentOverride>;
+    /** Layout slot overrides (`Header`, `Sidebar`, `Search`, ...). */
+    layout?: Record<string, ComponentOverride>;
+}
+/**
+ * Identity helper for authoring `components.ts`. Provides type inference and a
+ * stable home for future normalization; it does not transform input.
+ */
+export declare const defineComponents: (overrides: ComponentOverrides) => ComponentOverrides;

package/dist/types/core/define-meta.d.ts

@@ -0,0 +1,16 @@
+import type { FolderMeta } from "./schema.ts";
+/** A function that computes folder meta, optionally asynchronously. */
+export type FolderMetaFactory = () => FolderMeta | Promise<FolderMeta>;
+/** What a `meta.ts` may default-export: a plain object or a (async) factory. */
+export type FolderMetaDefinition = FolderMeta | FolderMetaFactory;
+/**
+ * Identity helper for authoring a folder's `meta.ts`. Provides type inference;
+ * it does not transform input. Pass an object, or a function (sync or async)
+ * that returns one when you need to compute the meta:
+ *
+ * ```ts
+ * export default defineMeta({ title: "Guides", order: 2 });
+ * export default defineMeta(async () => ({ pages: await orderPages() }));
+ * ```
+ */
+export declare const defineMeta: (meta: FolderMetaDefinition) => FolderMetaDefinition;

package/dist/types/core/deployment-env.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedConfig } from "./schema.ts";
+/**
+ * Fill in `deployment.adapter` and `deployment.site` from platform env vars
+ * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit
+ * config always wins, and the adapter is only inferred for server output (it
+ * has no effect on static builds). Mirrors Astro's platform auto-detection so a
+ * project deployed to a known host gets a working canonical origin for free.
+ */
+export declare const applyDeploymentEnv: (config: ResolvedConfig, env?: NodeJS.ProcessEnv) => ResolvedConfig;

package/dist/types/core/diagnostics.d.ts

@@ -0,0 +1,17 @@
+import type { ZodError } from "zod";
+import type { Diagnostic } from "./types.ts";
+/** A recoverable error carrying a structured diagnostic. */
+export declare class BlumeError extends Error {
+    readonly diagnostic: Diagnostic;
+    constructor(diagnostic: Diagnostic);
+}
+export declare const createDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
+/** Convert a ZodError into Blume diagnostics, anchored to a file. */
+export declare const diagnosticsFromZod: (error: ZodError, options: {
+    code: string;
+    file?: string;
+}) => Diagnostic[];
+/** Format a single diagnostic for terminal output. */
+export declare const formatDiagnostic: (diagnostic: Diagnostic, root?: string) => string;
+export declare const hasErrors: (diagnostics: Diagnostic[]) => boolean;
+export declare const countBySeverity: (diagnostics: Diagnostic[]) => Record<Diagnostic["severity"], number>;