blume 1.7.3 → 2.0.0

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;