blume 1.7.3 → 2.0.1

package/dist/types/analytics/segment.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** Segment's CDN, where `segment()` loads analytics.js from when `cdn` is unset. */
+export declare const SEGMENT_DEFAULT_CDN = "https://cdn.segment.com";
+/** The options {@link segment} maps itself. */
+export interface SegmentNamedOptions {
+    /**
+     * Origin of a custom domain that proxies Segment's CDN, e.g.
+     * `https://cdn.example.com`. Defaults to Segment's own.
+     */
+    cdn?: string;
+    /** Write key of the JavaScript source. */
+    key: string;
+}
+/**
+ * Options for {@link segment}: the named options plus any other
+ * `analytics.load` option, forwarded verbatim (`integrations`, …). JSON
+ * values only.
+ */
+export type SegmentOptions = SegmentNamedOptions & {
+    [option: string]: JsonValue;
+};
+export declare const segmentOptionsSchema: z.ZodObject<{
+    cdn: z.ZodOptional<z.ZodString>;
+    key: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type SegmentAdapter = AdapterDescriptor<"segment", SegmentOptions>;
+export declare const segmentAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"segment">;
+    options: z.ZodObject<{
+        cdn: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Segment (Twilio Segment) analytics.js. The write key is meant for the
+ * browser — it identifies the source the SDK reports to.
+ */
+export declare const segment: (options: SegmentOptions) => SegmentAdapter;
+/**
+ * The install snippet, with `key` mapped to the write key, `cdn` mapped to
+ * the script origin (and `analytics._cdn`, so the library fetches its
+ * integrations from the same place), and everything else forwarded as the
+ * load options; the object is left off when there is nothing to pass, as the
+ * snippet prints it.
+ */
+export declare const segmentHead: (options: SegmentOptions) => HeadScript[];

package/dist/types/analytics/vercel.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+/** The props of `@vercel/analytics/astro` that {@link vercel} documents. */
+export interface VercelNamedOptions {
+    /** Log every event to the console. Defaults to the component's own rule (on outside production). */
+    debug?: boolean;
+    /** Force the script's environment instead of letting it detect one. */
+    mode?: "auto" | "development" | "production";
+}
+/**
+ * Options for {@link vercel}: the documented props plus any other prop of the
+ * official component, forwarded verbatim (`endpoint`, `scriptSrc`, `dsn`, …).
+ * JSON values only; `beforeSend` is a function and can't travel through
+ * config — assign `window.webAnalyticsBeforeSend` from a `script()` adapter
+ * listed before `vercel()` instead.
+ */
+export type VercelOptions = VercelNamedOptions & {
+    [option: string]: JsonValue;
+};
+export declare const vercelOptionsSchema: z.ZodObject<{
+    debug: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        development: "development";
+        production: "production";
+    }>>;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type VercelAdapter = AdapterDescriptor<"vercel", VercelOptions>;
+export declare const vercelAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"vercel">;
+    options: z.ZodObject<{
+        debug: z.ZodOptional<z.ZodBoolean>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            development: "development";
+            production: "production";
+        }>>;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Vercel Web Analytics, rendered through the official Astro component, which
+ * injects the first-party script Vercel serves at `/_vercel/insights` once Web
+ * Analytics is enabled for the project. Needs no keys. `@vercel/analytics` is
+ * one of Blume's own dependencies, so the adapter declares no runtime dep.
+ */
+export declare const vercel: (options?: VercelOptions) => VercelAdapter;

package/dist/types/astro/integration.d.ts

@@ -0,0 +1,76 @@
+import type { AstroIntegration } from "astro";
+import type { CustomPageRoute } from "../core/custom-pages.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { Diagnostic } from "../core/types.ts";
+/**
+ * Hand the scanned project to the integration ahead of `build()`, so its
+ * `astro:build:done` hook can write the deploy artifacts without scanning
+ * again. `blume build` publishes it for a real build and nothing for an
+ * isolated verify build, which produces no artifacts. `null` withdraws it.
+ */
+export declare const publishBuildProject: (project: BlumeProject | null) => void;
+/**
+ * Publish the dev negotiation inputs for the running server: the content
+ * routes with a Markdown variant and the homepage `Link` header. Called by
+ * `generateRuntime` on every pass, so the middleware follows a route rename
+ * without the generated config changing. `null` withdraws a publication, so
+ * the middleware falls back to the options baked into the integration call
+ * (an ejected project has no CLI to publish).
+ */
+export declare const publishDevNegotiation: (negotiation: {
+    contentRoutes: readonly string[];
+    homeLinkHeader?: string;
+} | null) => void;
+/**
+ * Re-run Astro's content-layer loaders against the live dev server. Returns
+ * `false` when no server has registered one — before the first
+ * `astro:server:setup`, or outside `blume dev` — so the caller can fall back.
+ * A route-set change (a page added, removed, or a folder renamed) is what
+ * needs this: Astro's glob watcher misses directory renames, and its in-place
+ * config restart never re-globs, so without a re-sync `getEntry` reads a
+ * stale store and the moved page 404s.
+ */
+export declare const refreshBlumeContent: () => Promise<boolean>;
+/**
+ * Surface Blume's own diagnostics (config/frontmatter/content errors) in the
+ * Vite/Astro browser error overlay during `blume dev`, so they don't hide in the
+ * terminal. A no-op when there are no errors or the dev server isn't up. The
+ * overlay clears itself on the next successful HMR update.
+ */
+export declare const showBlumeErrorOverlay: (diagnostics: Diagnostic[]) => void;
+/** A user page mounted into the generated runtime. */
+export type BlumePageRoute = CustomPageRoute;
+export interface BlumeIntegrationOptions {
+    pages: BlumePageRoute[];
+    /**
+     * Page routes that have a raw-Markdown variant (the content manifest). The
+     * hidden runtime leaves this out: the CLI publishes the live set through
+     * `publishDevNegotiation` on every regeneration, so a route change never
+     * rewrites the generated config. An ejected project, which has no CLI,
+     * bakes it in here.
+     */
+    contentRoutes?: string[];
+    /**
+     * Homepage `Link` header value for agent discovery (see
+     * `ai/link-headers.ts`); the dev-server counterpart of the `_headers` /
+     * Vercel-config emission, so `curl -I` against `blume dev` shows what the
+     * deployed site will send. Published the same way as `contentRoutes`.
+     */
+    homeLinkHeader?: string;
+    /**
+     * Blume project root to scan on `astro:build:done` for the deploy artifacts
+     * (search index, llms.txt, sitemap, …) when no CLI has published the
+     * project — an ejected app running plain `astro build`. Relative to the
+     * Astro root. The hidden runtime leaves it unset: `blume build` publishes
+     * its already-scanned project instead.
+     */
+    buildArtifactsRoot?: string;
+}
+/**
+ * Blume's Astro integration. Mounts user-authored pages from `pages/` into the
+ * generated runtime via `injectRoute`, keeping each file in its original
+ * location so relative imports and `getStaticPaths` keep working; declares
+ * the `blume:*` virtual modules' types through `injectTypes`; and teaches the
+ * dev server to honor `Accept: text/markdown`.
+ */
+export declare const blumeIntegration: (options: BlumeIntegrationOptions) => AstroIntegration;

package/dist/types/astro/markdown-negotiation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTTP content negotiation for the raw-Markdown variants. The `<route>.md`
+ * endpoints already serve a page's source verbatim; these helpers let the dev
+ * server honor `Accept: text/markdown` by transparently rewriting a page
+ * request to its `.md` variant.
+ *
+ * The Cloudflare negotiation Worker embeds a plain-JavaScript copy of these
+ * helpers (`deploy/cloudflare-negotiation.ts` — its deploy bundle is uploaded
+ * unbundled, so it cannot import this module); when editing here, mirror the
+ * change there. Parity is enforced by `test/cloudflare-negotiation.test.ts`.
+ */
+/**
+ * Whether the client explicitly prefers Markdown over HTML. Browsers never send
+ * `text/markdown`, so an ordinary page request (`text/html` or the catch-all wildcard) is false.
+ */
+export declare const prefersMarkdown: (accept: string | null | undefined) => boolean;
+/**
+ * Map a page request URL to its `.md` variant, or `null` when the requested
+ * path is not a known content route (Vite/Astro internals, assets, API routes,
+ * landing pages, and user `.astro` pages all fall through). `routes` is the set
+ * of page paths that have a raw-Markdown variant.
+ */
+export declare const markdownVariantUrl: (rawUrl: string | null | undefined, routes: ReadonlySet<string>, base?: string) => string | null;

package/dist/types/astro/module-types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ambient declarations for the `blume:*` virtual modules the generated pages
+ * and Blume's own layouts import. The integration hands them to Astro through
+ * `injectTypes` on `astro:config:done`, so they land under
+ * `.astro/integrations/blume/` and are referenced from Astro's generated
+ * `types.d.ts` — the same channel `astro:content` and `astro:env` use — rather
+ * than a hand-written `src/env.d.ts` the generator and eject each had to
+ * write. Every project that mounts the integration gets the types with it.
+ *
+ * `examplesModule` is the path of the generated `examples.ts` relative to the
+ * declaration file: the `blume:examples` map is typed from that module's
+ * literal export so `<Component path>` lookups stay typed per project.
+ */
+export declare const runtimeModuleDeclarations: (examplesModule: string) => string;

package/dist/types/astro/pages.d.ts

@@ -0,0 +1,44 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { BlumePageRoute } from "./integration.ts";
+export { customStaticRoutes, discoverPages, discoverPagesSync, } from "../core/custom-pages.ts";
+/**
+ * Whether the project already owns `route` — through a custom `.astro` page
+ * (injected, so matched on `pattern`) or a content page (matched on `route`).
+ * Used to skip a generated default page (e.g. `/404`, `/changelog`) so a
+ * user-authored page overrides it without a route collision.
+ */
+export declare const routeIsTaken: (pages: {
+    pattern: string;
+}[], contentPages: {
+    route: string;
+}[], route: string) => boolean;
+/** 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 headline. */
+    title: string;
+}
+/**
+ * Whether the generated `/changelog` index route exists for this project —
+ * `generate.ts` (which writes the page) and the sitemap/link validator all
+ * share this check: there are visible `type: changelog` entries — or a
+ * release-backed changelog source, whose route must resolve even when a fetch
+ * fails — and no user content or custom page already owns `/changelog`.
+ */
+export declare const hasGeneratedChangelog: (project: BlumeProject, userPages: {
+    pattern: string;
+}[]) => boolean;
+/**
+ * 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. A `titles` entry (`seo.og.titles`,
+ * keyed by route) names a card outright — the only way to say "CLI" when the
+ * segment humanizes to "Cli". Otherwise the home is titled with the site title
+ * and a deeper page from its last path segment. The card's brand lockup,
+ * description, and footer come from the resolved config at render time.
+ */
+export declare const customOgRoutes: (pages: BlumePageRoute[], siteTitle: string, titles?: Record<string, string>) => OgCustomRoute[];

package/dist/types/cli/env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Load `.env`/`.env.local`, cascading from `startDir` up to the repository root
+ * (the first ancestor containing a `.git`) or the filesystem root. The ordered
+ * path list is handed to dotenv, whose `config` is first-wins, never clobbers
+ * existing `process.env` values, and treats unreadable files as best-effort —
+ * so shell/CI overrides are never lost, `.env.local` layers over `.env`, and a
+ * bad file never aborts a build. dotenv is also the parser Vite runs over
+ * these files at build time, so a value means the same thing to the pre-boot
+ * content scan and the built site — including multi-line double-quoted values
+ * (PEM keys), which a line-based parser silently truncates.
+ */
+export declare const loadEnvFiles: (startDir: string) => void;

package/dist/types/cli/init/scaffold.d.ts

@@ -0,0 +1,154 @@
+export declare const TEMPLATES: readonly ["docs", "api", "sdk", "changelog"];
+export type Template = (typeof TEMPLATES)[number];
+export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+/** The content-source kinds `init` can scaffold a config block for. */
+export declare const SOURCE_KINDS: readonly ["filesystem", "obsidian", "github-releases", "notion", "sanity", "contentful", "payload", "strapi", "mdx-remote"];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+/** Everything the scaffolder needs, whether prompted or derived from flags. */
+export interface InitAnswers {
+    contentDir: string;
+    /** Target directory as the user gave it (`.` = current directory). */
+    directory: string;
+    packageManager: PackageManager;
+    sources: SourceKind[];
+    template: Template;
+    title: string;
+}
+/** One file the scaffold plan will write; `path` is absolute. */
+export interface ScaffoldFile {
+    content: string;
+    path: string;
+}
+/** Log sink for scaffold output — satisfied by both consola and clack's `log`. */
+export interface ScaffoldLog {
+    info: (message: string) => void;
+    success: (message: string) => void;
+}
+export declare const STARTERS: {
+    api: {
+        configExtra: string;
+        configImports: string[];
+        files: (dir: string) => {
+            content: string;
+            path: string;
+        }[];
+    };
+    changelog: {
+        configExtra: string;
+        configImports: never[];
+        files: (dir: string) => {
+            content: string;
+            path: string;
+        }[];
+    };
+    docs: {
+        configExtra: string;
+        configImports: never[];
+        files: (dir: string) => {
+            content: string;
+            path: string;
+        }[];
+    };
+    sdk: {
+        configExtra: string;
+        configImports: never[];
+        files: (dir: string) => {
+            content: string;
+            path: string;
+        }[];
+    };
+};
+/**
+ * Add, install, and dev commands to print for the chosen package manager, plus the
+ * prefix that runs a locally installed bin (`exec`, e.g. `npx blume eject`) —
+ * dependency bins aren't on PATH, so a bare `blume …` hint would not run.
+ */
+export declare const commandsFor: (pm: PackageManager) => {
+    add: string;
+    build: string;
+    dev: string;
+    exec: string;
+    install: string;
+};
+/**
+ * Derive the package manager from an npm user-agent string (the first
+ * `name/version` token of `npm_config_user_agent`), falling back to npm.
+ * Right for `init`, where the project doesn't exist yet and the invoking
+ * runner is the only signal.
+ */
+export declare const detectPackageManager: (userAgent?: string) => PackageManager;
+/**
+ * Detect an existing project's package manager from its lockfile /
+ * `packageManager` field (package-manager-detector), falling back to the
+ * user agent. Right for `eject`: the CLI is often run directly (`npx blume
+ * eject`, a bare `blume eject`), where `npm_config_user_agent` is absent or
+ * names the runner rather than the project's manager, and the old
+ * user-agent-only detection silently printed npm hints for a pnpm project.
+ */
+export declare const detectProjectPackageManager: (root: string) => Promise<PackageManager>;
+/**
+ * The content dir is joined into every scaffolded file path, so an absolute or
+ * `../`-escaping value would write outside the project. Returns an error
+ * message, or `undefined` when the dir is safe.
+ */
+export declare const validateContentDir: (root: string, dir: string) => string | undefined;
+/** Turn a directory name into a display title: `my-docs` → `My Docs`. */
+export declare const titleize: (raw: string) => string;
+/** The full `blume.config.ts` text for the chosen answers. */
+export declare const buildConfig: (answers: InitAnswers) => string;
+/**
+ * The major version of the Yarn that ran `init`, read off the npm user agent
+ * (`yarn/4.5.1 npm/? node/v22…`), or undefined when something else ran it.
+ */
+export declare const yarnMajor: (userAgent?: string) => number | undefined;
+/** Environment `buildPlan` and `workspaceNote` read, injectable for tests. */
+export interface PlanEnvironment {
+    /** `npm_config_user_agent` of the process that ran `init`. */
+    userAgent?: string;
+}
+/**
+ * What the project still needs from a workspace it joins, when `init` left
+ * that workspace's config alone: pnpm's approval for esbuild's build script
+ * (pnpm 10 and later fail the install without it), or Yarn Berry's
+ * `node_modules` linker. Undefined when the workspace already has it, or the
+ * project doesn't sit in one.
+ */
+export declare const workspaceNote: (root: string, answers: InitAnswers, env?: PlanEnvironment) => string | undefined;
+/** Every file `init` should write for the given answers, package.json first. */
+export declare const buildPlan: (root: string, answers: InitAnswers, env?: PlanEnvironment) => ScaffoldFile[];
+/**
+ * Write the plan's files, skipping any that already exist. Reports whether a
+ * `package.json` was newly created (it decides whether `init` installs).
+ */
+export declare const applyPlan: (files: ScaffoldFile[], log: ScaffoldLog) => Promise<{
+    createdPackage: boolean;
+}>;
+/** What an existing package.json — one `init` left alone — already wires up. */
+export interface ExistingPackage {
+    /**
+     * Whether `blume` is installed where the project resolves it: its own
+     * `node_modules`, or an ancestor's in a hoisted workspace. Listing it isn't
+     * enough — a rerun of `init --no-install` lists it without installing it.
+     */
+    blumeInstalled: boolean;
+    /** Every package it lists in `dependencies` or `devDependencies`. */
+    dependencies: string[];
+    /** Whether its `dev` script runs Blume. */
+    devRunsBlume: boolean;
+}
+/**
+ * Read the package.json `init` didn't write. An unreadable or malformed one
+ * reads as wiring nothing up, so the next steps list everything to add.
+ */
+export declare const readExistingPackage: (root: string) => Promise<ExistingPackage>;
+/**
+ * The next-steps message: `cd` hint, the install command when `init` did not
+ * run it itself, the dev command, and token setup. With an `existing`
+ * package.json — which `init` never edits — it first adds whatever of `blume`
+ * and the sources' SDKs isn't listed yet (or installs, when everything is
+ * listed but `blume` was never installed), then starts the dev server through
+ * the package runner unless its `dev` script already runs Blume. A `note` —
+ * what a workspace the project joins still needs — closes the message.
+ */
+export declare const nextSteps: (answers: InitAnswers, needsInstall: boolean, existing?: ExistingPackage, note?: string) => string;

package/dist/types/components/layout/nav-utils.d.ts

@@ -10,6 +10,17 @@ export interface Crumb {
     label: string;
     route?: string;
 }
+/**
+ * Whether a group's header row reads as the current page. A routed group links
+ * to its folder's index page; when that index is also listed as one of the
+ * group's own rows (kept under a different label), the row is the more
+ * specific indicator, so the header stays quiet rather than lighting up beside
+ * it. With the index row hidden the header is the only link and takes the
+ * highlight.
+ */
+export declare const isGroupRowCurrent: (group: Extract<NavNode, {
+    kind: "group";
+}>, currentRoute: string) => boolean;
 /** Flatten the sidebar tree into ordered internal page links. */
 export declare const flattenPages: (nodes: NavNode[]) => FlatPage[];
 /** Find the breadcrumb trail (group ancestors + page) for a route. */

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

@@ -0,0 +1,47 @@
+import { z } from "zod";
+/**
+ * The serializable descriptor an integration factory returns — `posthog({ key })`,
+ * `vercel()`, `script({ src })` and their siblings. A descriptor is plain data:
+ * the CLI evaluates `blume.config.ts` once, validates what came back, and
+ * writes it into the generated project's data snapshot as a JSON literal. That
+ * is where the runtime reads it — nothing generated imports the config at
+ * request time — so a descriptor can't carry functions, class instances, or
+ * anything else JSON drops.
+ *
+ * Every consumer reads the descriptor instead of switching on a provider name:
+ * the head emitter and `blume doctor` branch on `kind`, the generated
+ * `.blume/package.json` declares `runtimeDeps`, and the secrets check warns
+ * when an entry of `requiredSecrets` is unset.
+ *
+ * An adapter's verbatim option passthrough is typed as {@link JsonValue} and
+ * validated with `z.json()`, so a function, `undefined`, a bigint, or a
+ * non-finite number fails config validation with a path instead of vanishing
+ * (or throwing) when the snapshot is serialized.
+ */
+export interface AdapterDescriptor<Kind extends string, Options> {
+    /** Which integration this is. */
+    kind: Kind;
+    /** The options the factory was called with, verbatim. */
+    options: Options;
+    /** Env vars the integration reads at runtime; `blume dev`/`build` warn when one is unset. */
+    requiredSecrets: string[];
+    /** Extra packages the generated `.blume/package.json` must declare. */
+    runtimeDeps: string[];
+}
+/**
+ * A value JSON can carry unchanged — what an adapter's passthrough options are
+ * typed as. Structurally identical to what `z.json()` accepts.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * The schema for one descriptor `kind`, validating its `options` with the
+ * adapter's own option schema. Members of a `z.discriminatedUnion("kind", …)`.
+ */
+export declare const adapterDescriptorSchema: <Kind extends string, Options extends z.ZodType>(kind: Kind, options: Options) => z.ZodObject<{
+    kind: z.ZodLiteral<Kind>;
+    options: Options;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;

package/dist/types/core/api-name.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `name` as the phrase "the ___" in generated prose — the spec title or
+ * reference label, followed by ` API` unless it already says so. Keeps
+ * "Petstore" reading as "Petstore API" without turning "Petstore API" into
+ * "Petstore API API".
+ */
+export declare const apiNamePhrase: (name: string) => string;

package/dist/types/core/changelog-index.d.ts

@@ -0,0 +1,13 @@
+import type { ResolvedConfig } from "./schema.ts";
+import type { PageRecord } from "./types.ts";
+/** Where the changelog timeline index is served. */
+export declare const CHANGELOG_INDEX_ROUTE = "/changelog";
+/**
+ * Whether the site serves a changelog index at {@link CHANGELOG_INDEX_ROUTE}:
+ * there are visible `type: changelog` entries, or a release-backed source
+ * (whose index must resolve even when a fetch fails). Blume generates the
+ * timeline there unless a custom or content page already owns the route —
+ * either way the route is servable, which is what navigation needs to point a
+ * `/changelog` tab at the index rather than its newest entry.
+ */
+export declare const hasChangelogIndex: (pages: Pick<PageRecord, "contentType" | "meta">[], config: ResolvedConfig) => boolean;