blume 1.7.2 → 2.0.0

package/dist/types/deploy/cloudflare-negotiation.d.ts

@@ -0,0 +1,196 @@
+/**
+ * `Accept: text/markdown` content negotiation for Cloudflare server builds.
+ *
+ * Blume prerenders every content page — even in a server build (`deployment:
+ * cloudflare()`) — and on Cloudflare the ASSETS binding serves those files before
+ * the Worker script runs, so no server-side code (Astro middleware included)
+ * ever sees a content-page request. Worse, even a content-page request that
+ * does reach the Worker is answered by `@astrojs/cloudflare`'s handler
+ * straight from the ASSETS binding, ahead of `app.render` — the only place
+ * middleware runs — because `app.match` resolves a prerendered route to
+ * nothing and the handler then falls back to the binding.
+ *
+ * Negotiation therefore needs two coordinated pieces, both applied to the
+ * adapter's emitted deploy bundle after `astro build`:
+ *
+ * 1. `assets.run_worker_first` in `dist/server/wrangler.json`, claiming every
+ *    path except the static files that never negotiate, so the platform
+ *    routes page requests — and requests for pages that do not exist — to
+ *    the Worker instead of serving the static HTML directly (see
+ *    `buildRunWorkerFirstRules`).
+ * 2. A generated entry Worker that fronts the adapter's: when the client
+ *    prefers `text/markdown` it serves the page's prerendered `.md` mirror
+ *    from the ASSETS binding, and it delegates everything else to the Astro
+ *    Worker untouched.
+ *
+ * The prerendered per-page JSON documents (`/api/docs/pages/{route}.json`)
+ * are the one prerendered surface the adapter's fallback does *not* cover.
+ * They come from a prerendered *dynamic* route, and for those Astro's
+ * `matchRequest` returns the first non-prerendered route matching the same
+ * path — on a server build that is the `/api/[...path]` catch-all, which
+ * answers with a 404 problem document; `fallbackToAssets` never runs. The
+ * static-pathname endpoints (`pages.json`, `navigation.json`) are unaffected:
+ * they sit in the manifest's asset set, which the handler serves from the
+ * binding first. So whenever a worker-first rule claims a page JSON URL, the
+ * wrapper answers it from the binding itself, keyed by the exact set of
+ * documents the build emitted. The generated rule set claims them (a miss
+ * must reach the API's `PAGE_NOT_FOUND` answer, see `STATIC_EXEMPTIONS`), and
+ * so do user-configured rules or a bare `true`.
+ *
+ * Cloudflare does not apply `_headers` to worker-first routes, so the wrapper
+ * also re-stamps what the static layer would otherwise add on the routes it
+ * takes over: the homepage agent-discovery `Link` header and the Markdown
+ * `charset=utf-8` (see `deploy/headers.ts`). The raw `.md`/`.mdx` URLs are
+ * exempted from worker-first routing with negative rules, keeping their
+ * `_headers` treatment and their zero-Worker serving path.
+ *
+ * Configured redirects are baked into the wrapper as well, and answered there
+ * with their exact configured status. On a server build Blume routes
+ * `redirects` through Astro's own config, and `@astrojs/cloudflare` turns
+ * those into `_redirects` entries carrying the exact status — but only
+ * Cloudflare's static layer reads that file, and a worker-first route never
+ * reaches it. Astro's SSR redirect handler would answer instead, and it honors
+ * the configured status only when the destination resolves to a discrete
+ * route: Blume serves every page from `[...slug]`, so it never does, and
+ * `computeRedirectStatus` defaults a GET to **301** — a permanent redirect
+ * that browsers cache indefinitely. The wrapper checking its own redirect
+ * table before delegating closes that hole at zero rule cost: unlike negative
+ * `run_worker_first` exemptions, a baked-in table spends nothing against
+ * Wrangler's 100-rule / 100-character limits, cannot collide with
+ * user-configured rules (or a bare `true`), and needs no basing gymnastics —
+ * its keys are full served URLs, which is exactly what the Worker sees.
+ * Redirects outside every worker-first rule still never invoke the Worker;
+ * the static layer serves them from `_redirects` as before.
+ *
+ * Missing pages negotiate too. Under an explicit `run_worker_first` list the
+ * platform answers every request outside the rules from the static layer —
+ * an asset miss included, as the nearest `404.html` — which is why the rules
+ * claim every path: a request for a URL no page backs then reaches the
+ * Worker, and the Astro Worker answers it with the HTML 404 shell from the
+ * binding (`not_found_handling: "404-page"`). When the client prefers
+ * Markdown the wrapper swaps that shell for the prerendered `/404.md` twin,
+ * and when it prefers JSON for the `/404.json` problem document, keeping the
+ * 404 status either way — the counterpart of the miss-phase routes in
+ * `deploy/vercel-negotiation.ts`. A raw `.md` or `.json` URL no file backs
+ * asks for the same twin implicitly, but on this platform such a request only
+ * reaches the Worker for `.json` (the generated set keeps `.md` on the static
+ * layer for its `_headers`). Only an HTML 404 is swapped, so an API endpoint's
+ * own problem document is never overwritten.
+ */
+import type { NotFoundVariants } from "./vercel-negotiation.ts";
+/** Filename of the generated wrapper Worker, next to the adapter's entry. */
+export declare const NEGOTIATION_WORKER_FILE = "blume-worker.mjs";
+/** A value as `JSON.parse` produces it (the wrangler config's value space). */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * The `run_worker_first` rules: every path under the deployment base goes
+ * through the Worker except the {@link STATIC_EXEMPTIONS}. Claiming
+ * everything — rather than only the content routes — is what lets a
+ * *missing* page negotiate: under an explicit rule list the platform answers
+ * any request outside every rule from the static layer, an asset miss
+ * included (as the nearest `404.html`), so a rule set scoped to the content
+ * routes would never let the Worker see a request for a URL that has no
+ * page. The price is a Worker hop on every page request the site does serve.
+ * On a subpath deploy the base is claimed in both request spellings.
+ *
+ * Configured redirects need no exemption from these rules: the wrapper Worker
+ * answers any it claims from its baked-in redirect table with the configured
+ * status (see the module comment).
+ */
+export declare const buildRunWorkerFirstRules: (base?: string) => string[];
+/**
+ * Merge the generated rules into a user-configured `run_worker_first` (which
+ * flows into the adapter's emitted config from the project's own wrangler
+ * file). `true` already routes everything through the Worker, so it is kept
+ * as-is; an array is unioned with the generated rules and then swept for
+ * redundancy, since coverage by a glob is equivalent routing but a hard
+ * validation error at deploy time.
+ */
+export declare const mergeRunWorkerFirstRules: (existing: JsonValue | undefined, added: readonly string[]) => string[] | true;
+/** A configured redirect the wrapper Worker serves itself. */
+export interface WorkerRedirect {
+    /**
+     * Served path of the redirect, based the way the host platform matches it
+     * (see `applyBaseToPlatformRedirects`) — the full URL path the Worker sees.
+     */
+    from: string;
+    /** Configured HTTP status (301, 302, 307, or 308). */
+    status: number;
+    /** Destination, percent-encoded into the `Location` header. */
+    to: string;
+}
+export interface NegotiationWorkerOptions {
+    /** Import specifier of the adapter's built entry, relative to the Worker. */
+    mainSpecifier: string;
+    /** Content routes with a raw-Markdown mirror (see `markdownRoutePaths`). */
+    routePaths: readonly string[];
+    /** Name of the assets binding the wrapper serves the `.md` mirrors from. */
+    assetsBinding: string;
+    /** `deployment.base` for subpath deploys. */
+    base?: string;
+    /** Homepage agent-discovery `Link` header (see `ai/link-headers.ts`). */
+    homeLinkHeader?: string | null;
+    /** Estimated token count of the homepage Markdown mirror. */
+    homeTokens?: number;
+    /** Configured redirects the wrapper answers with their exact status. */
+    redirects?: readonly WorkerRedirect[];
+    /**
+     * Base-less served paths of the prerendered per-page JSON documents the
+     * build emitted (see `pageJsonPath`), decoded. The wrapper answers exactly
+     * these from the assets binding, since the Astro Worker would route them to
+     * the `/api/` catch-all (see the module comment).
+     */
+    pageJsonPaths?: readonly string[];
+    /**
+     * Which prerendered 404 twins the build emitted (`404.md`, `404.json`), so
+     * the wrapper only substitutes a twin that exists. A project that owns
+     * `/404` emits neither and keeps the HTML answer.
+     */
+    notFound?: NotFoundVariants;
+}
+/**
+ * The wrapper Worker module. The negotiation helpers are a JavaScript copy of
+ * `astro/markdown-negotiation.ts` — the deploy bundle is uploaded with
+ * `no_bundle`, so the module must be self-contained; behavioral parity with
+ * the dev middleware is enforced by `test/cloudflare-negotiation.test.ts`.
+ */
+export declare const buildNegotiationWorker: (options: NegotiationWorkerOptions) => string;
+export interface WorkerNegotiation {
+    /** Updated `wrangler.json` text (worker-first rules + swapped `main`). */
+    wrangler: string;
+    /** The wrapper Worker module, to write as {@link NEGOTIATION_WORKER_FILE}. */
+    worker: string;
+}
+export interface WorkerNegotiationOptions extends Omit<NegotiationWorkerOptions, "assetsBinding" | "mainSpecifier"> {
+    /**
+     * The manifest content routes, based like `routePaths` — the guard that
+     * keeps the wrapper's redirect table off real pages. Defaults to
+     * `routePaths`, which also carries the synthesized homepage mirror (see
+     * `markdownRoutePaths`); passing the manifest routes keeps that synthetic
+     * `/` from blocking a configured root redirect.
+     */
+    contentRoutePaths?: readonly string[];
+}
+/**
+ * Wire the negotiation into the adapter's emitted `dist/server/wrangler.json`:
+ * point `main` at the wrapper Worker and scope `assets.run_worker_first` to
+ * the content routes (merged with any user-configured rules). Returns the
+ * updated config text plus the wrapper module, or `null` when there is
+ * nothing to do or nowhere safe to do it: no routes, unparsable config, no
+ * usable `main` or assets binding (the wrapper serves the `.md` mirrors from
+ * it), an already-swapped `main` (the original entry is unrecoverable), or
+ * user-configured rules that push the set over Wrangler's limits.
+ *
+ * The configured redirects are baked into the wrapper, which answers any the
+ * worker-first rules claim with the exact configured status (see the module
+ * comment) — whichever rules do the claiming: the generated `/*`, or the
+ * user's own (including a bare `true`). A
+ * redirect at a content route's own path is never baked: the page owns it,
+ * and answering a redirect there would take a real page off the air. When
+ * `null` is returned no rule set is written at all, so every request stays on
+ * the static layer and `_redirects` serves the configured statuses as before.
+ */
+export declare const injectWorkerNegotiation: (wranglerText: string, options: WorkerNegotiationOptions) => WorkerNegotiation | null;
+export {};

package/dist/types/deploy/function-bundle.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Post-build audit of a Vercel serverless function bundle.
+ *
+ * The Vercel adapter traces the server entry with `@vercel/nft` and copies
+ * every file it reaches into `.vercel/output/functions/_render.func`. A bare
+ * import the trace cannot resolve — a package that isn't reachable by walking
+ * `node_modules` up from the chunk that imports it — is dropped *silently*,
+ * and the deployed function dies on its first request with
+ * `ERR_MODULE_NOT_FOUND` (Vercel reports it as `FUNCTION_INVOCATION_FAILED`).
+ * Under an isolated linker (pnpm, Bun's `isolated` mode) that is exactly the
+ * shape of Blume's own runtime dependencies: the SSR build leaves them
+ * external, and they live under `blume`'s store directory, not the project
+ * root. Nothing before deploy surfaces it — the build is green, a warm-cache
+ * preview is green — so the bundle is re-checked here with Node's own
+ * resolution rule: a package is present when some `node_modules/<name>` on
+ * the walk from the importing chunk up to the function root exists.
+ */
+/** A bare package import the function bundle cannot satisfy. */
+export interface MissingPackage {
+    /** Function-relative paths of the chunks that import the package. */
+    importers: string[];
+    name: string;
+}
+/** One function directory's audit result. */
+export interface FunctionBundleAudit {
+    /** Absolute path of the `*.func` directory. */
+    dir: string;
+    missing: MissingPackage[];
+}
+/**
+ * The package a bare specifier resolves through (`@scope/name` or `name`), or
+ * null for relative/absolute paths, Node builtins, and virtual ids.
+ */
+export declare const packageName: (specifier: string) => string | null;
+/**
+ * Every bare package name a module's source imports. A module the lexer
+ * rejects (an unterminated string, an invalid escape in a specifier) falls
+ * back to the textual scan rather than going unaudited.
+ */
+export declare const importedPackages: (source: string, name?: string) => Promise<string[]>;
+/**
+ * Audit one function directory: read its `.vc-config.json` handler, scan
+ * every module beside the handler (the adapter's `dist/server` tree) for bare
+ * imports, and report the packages no `node_modules` on the walk up to the
+ * function root provides. A function without a handler has nothing to check.
+ */
+export declare const auditFunctionBundle: (funcDir: string) => Promise<MissingPackage[]>;
+/**
+ * Audit every function in a Vercel Build Output tree (`.vercel/output`).
+ * Functions with nothing missing are omitted; an output tree without a
+ * `functions/` directory (a static build) yields nothing.
+ */
+export declare const auditVercelFunctions: (outputDir: string) => Promise<FunctionBundleAudit[]>;
+/** Blume's own runtime dependency names, from its published `package.json`. */
+export declare const blumeDependencyNames: () => Set<string>;
+/** What a build should do about an audit: nothing, warn, or fail. */
+export interface FunctionBundleVerdict {
+    /**
+     * A missing package is one of Blume's own dependencies — the runtime Blume
+     * generated imports it, so the function is certain to crash. Anything else
+     * (a project's own external import) is reported but left to the author.
+     */
+    fatal: boolean;
+    message: string;
+}
+/**
+ * The command that adds a dev dependency with the project's package manager
+ * (`pnpm add -D`, `npm install -D`, …), for the fix a verdict prints. The
+ * missing packages are an isolated-linker problem, so the project is often
+ * not on npm at all.
+ */
+export declare const addDevDependencyCommand: (root: string) => Promise<string>;
+/**
+ * Describe a function's missing packages and how to fix them. Vercel's trace
+ * only reaches packages resolvable from the project root, so the remedy is a
+ * root-level dependency entry for each — the same mirror rule Blume's native
+ * dependencies (`sharp`, `takumi-js`) already follow — added with
+ * `addDevCommand` (see {@link addDevDependencyCommand}).
+ */
+export declare const functionBundleVerdict: (audit: FunctionBundleAudit, root: string, ownDependencies: ReadonlySet<string>, addDevCommand?: string) => FunctionBundleVerdict;

package/dist/types/deploy/headers.d.ts

@@ -0,0 +1,50 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+/**
+ * The policy a content-source SVG is served with: an opaque origin with
+ * scripts off, so an uploaded SVG that carries a `<script>` stays inert when
+ * opened directly. The endpoint sends it from the server and dev runtimes;
+ * {@link headerRules} carries it to static hosts.
+ */
+export declare const SVG_ASSET_POLICY = "sandbox";
+/**
+ * One static-host header rule: a served path (a `*` glob spanning path
+ * segments, or an exact path) and the header it sets there.
+ */
+export interface HeaderRule {
+    name: string;
+    path: string;
+    value: string;
+}
+/**
+ * The header rules every static host should apply, in `_headers` glob syntax.
+ * The glob carries the served prefix (`{deployment.base}{basePath}` for the
+ * Markdown mirrors, `{deployment.base}` for the root `.txt` files) so the rules
+ * still match once the site is mounted under a subpath (`/docs/*.md`); the
+ * wildcard spans path segments, so a nested route like `/docs/ja/intro.md`
+ * matches too.
+ *
+ * When a homepage `Link` header is provided (see `ai/link-headers.ts`), an
+ * exact-path rule for the root page advertises the agent-discovery resources —
+ * the static-host counterpart of the Vercel routing-config injection.
+ */
+export declare const headerRules: (config: ResolvedConfig, homeLinkHeader?: string | null) => HeaderRule[];
+/**
+ * `_headers` contents: each {@link headerRules} entry as its path with an
+ * indented header line, in the two-space format Netlify and Cloudflare read.
+ */
+export declare const buildNetlifyHeaders: (config: ResolvedConfig, homeLinkHeader?: string | null) => string;
+/** One entry of `vercel.json`'s `headers` array. */
+export interface VercelHeader {
+    headers: {
+        key: string;
+        value: string;
+    }[];
+    source: string;
+}
+/**
+ * The {@link headerRules} as `vercel.json` `headers` entries. Vercel reads no
+ * `_headers` file, so a static deploy of `dist/` carries the same rules here —
+ * the charset on the raw Markdown and text files, the homepage `Link` header,
+ * and the media types and CORS header of the discovery files.
+ */
+export declare const buildVercelHeaders: (config: ResolvedConfig, homeLinkHeader?: string | null) => VercelHeader[];

package/dist/types/deploy/node-headers.d.ts

@@ -0,0 +1,42 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { BuildLog } from "./platforms/types.ts";
+/**
+ * The response headers the Node standalone server can't set itself. Its static
+ * handler (`send`) types a file by its extension alone and sends no CORS
+ * header, so the extensionless well-known files go out as
+ * `application/octet-stream` and a registry reading the discovery documents
+ * from another origin is blocked — the half of the `_headers` rules
+ * (`deploy/headers.ts`) that a Node server has no file to read from. The Markdown
+ * and text charsets need no rule here: `send` already adds `charset=UTF-8` to
+ * `text/*` types.
+ */
+/** The headers one exact served path (deployment base included) gets. */
+export interface NodeHeaderRule {
+    headers: Record<string, string>;
+    path: string;
+}
+/** The server entry `@astrojs/node` writes, which the wrapper takes over. */
+export declare const NODE_ENTRY_FILE = "entry.mjs";
+/** Where Astro's own entry moves, beside the wrapper that imports it. */
+export declare const NODE_ASTRO_ENTRY_FILE = "astro-entry.mjs";
+/** The header rules for this config, merged per path. */
+export declare const nodeHeaderRules: (config: ResolvedConfig) => NodeHeaderRule[];
+/**
+ * The entry that replaces Astro's: it stamps the rules' headers on the
+ * response, then hands the request to Astro's handler. `send` leaves a
+ * Content-Type that is already set alone, so the registered media type wins.
+ *
+ * It keeps Astro's contract — the `handler`, `options`, and `startServer`
+ * exports `astro preview` and a middleware-mode host import — and its
+ * autostart: Astro's entry is imported with autostart off (the env var is read
+ * when that module evaluates, so the import has to be dynamic), and the
+ * wrapper starts the server itself with its listener in front of Astro's.
+ */
+export declare const nodeEntryWrapper: (rules: readonly NodeHeaderRule[]) => string;
+/**
+ * Put the header wrapper in front of a Node server build's entry. A build
+ * with no rule (no API catalog, AI catalog, MCP server, signatures directory,
+ * or downloaded content assets) leaves Astro's entry alone.
+ */
+export declare const wrapNodeEntry: (project: BlumeProject, log: BuildLog) => Promise<void>;

package/dist/types/deploy/platforms/cloudflare.d.ts

@@ -0,0 +1,40 @@
+import type { BlumeProject } from "../../core/project-graph.ts";
+import type { ProjectContext } from "../../core/types.ts";
+import type { BuildLog, DeployPlatform } from "./types.ts";
+/**
+ * Wire `Accept: text/markdown` negotiation into a server build. The ASSETS
+ * binding serves the prerendered content pages before the Worker runs — and
+ * even a request that reaches the Worker is answered by the adapter's handler
+ * from that binding, ahead of the only place middleware runs — so the
+ * negotiation lives in a generated wrapper Worker, routed to by
+ * `assets.run_worker_first` (see `deploy/cloudflare-negotiation.ts`). Both
+ * pieces are spliced into the adapter's emitted `dist/server` bundle.
+ */
+export declare const emitCloudflareNegotiation: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Point `wrangler deploy` run from the project root at the built Worker.
+ * The adapter's Vite plugin writes its redirect beside the Astro root — the
+ * hidden `.blume` runtime, where nobody runs wrangler — and wrangler only
+ * looks in the working directory and its parents, so from the project root it
+ * finds no config and fails with "Could not detect a directory containing
+ * static files". This writes the same redirect at the project root, its paths
+ * rebased there. A user wrangler config at the project root stays compatible:
+ * wrangler accepts a redirect in the same directory's `.wrangler/deploy/`.
+ */
+export declare const emitCloudflareDeployConfig: (context: ProjectContext) => Promise<void>;
+/**
+ * Name the built Worker after the project when it still carries the shared
+ * runtime name. A name set in the project's own wrangler config reaches the
+ * built config instead, and is left alone.
+ */
+export declare const nameCloudflareWorker: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Cloudflare Workers and Pages. A server build emits the Worker into
+ * `dist/server` and serves `dist/client` through the ASSETS binding, which
+ * honors `_headers` from that directory exactly as Pages does — so the file
+ * applies to both output modes here. Without a configured driver the adapter
+ * force-enables KV-backed sessions and declares a `SESSION` binding that
+ * `wrangler deploy` then demands a namespace for, even though Blume never
+ * reads `Astro.session`; `session: false` opts the project out.
+ */
+export declare const cloudflarePlatform: DeployPlatform;

package/dist/types/deploy/platforms/index.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedDeployment } from "../adapters/registry.ts";
+import type { DeployPlatform } from "./types.ts";
+/**
+ * Every platform, in the order their env detection is tried when a build's
+ * own adapter says nothing about where it runs (a static build on Vercel
+ * still gets its site URL from `VERCEL_URL`).
+ */
+export declare const DEPLOY_PLATFORMS: readonly DeployPlatform[];
+/** The behaviors behind a resolved deployment descriptor. */
+export declare const deployPlatform: (deployment: Pick<ResolvedDeployment, "kind">) => DeployPlatform;
+/**
+ * The site URL the platform env implies, or null. The configured adapter's
+ * own platform is asked first, then the rest in registration order, so a
+ * static build (which names no host) still picks up the URL of whichever
+ * platform it is building on.
+ */
+export declare const inferDeploymentSite: (deployment: Pick<ResolvedDeployment, "kind">, env: NodeJS.ProcessEnv) => string | null;
+export type { AstroAdapterSpec, BuildLog, DeployPlatform, FinalizeBuildOptions, HiddenRuntime, PlatformEnv, RedirectFile, } from "./types.ts";

package/dist/types/deploy/platforms/netlify.d.ts

@@ -0,0 +1,13 @@
+import type { DeployPlatform, RedirectFile } from "./types.ts";
+/** `_redirects`, the format Netlify and Cloudflare Pages/Workers read. */
+export declare const REDIRECTS_FILE: RedirectFile;
+/**
+ * Netlify. A server build runs on Netlify Functions from the Frameworks API
+ * tree the adapter writes to `.netlify/v1`, relative to the Astro root —
+ * which for Blume is the hidden `.blume` runtime, so the tree is moved up to
+ * the project root after the build (the `.netlify/build` sibling is only the
+ * intermediate SSR bundle, already traced into `v1/functions`, and moving
+ * `v1` alone keeps the `.netlify/state.json` from `netlify link` intact).
+ * Static assets are served from `dist/` either way.
+ */
+export declare const netlifyPlatform: DeployPlatform;

package/dist/types/deploy/platforms/node.d.ts

@@ -0,0 +1,11 @@
+import type { DeployPlatform } from "./types.ts";
+/**
+ * A self-hosted Node server. The standalone server in `dist/server` serves
+ * `dist/client` through its own static handler, which has no `_headers` or
+ * `_redirects` support — redirects are answered at request time from the
+ * Astro config, and a header file written there would be inert. The headers
+ * the discovery files need come from a wrapper around the server entry
+ * instead (`deploy/node-headers.ts`). No platform env to detect: the site URL
+ * has to be configured.
+ */
+export declare const nodePlatform: DeployPlatform;

package/dist/types/deploy/platforms/paths.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectContext } from "../../core/types.ts";
+/** Astro's build output dir: the runtime's own `distDir`, else `<root>/dist`. */
+export declare const distDir: (context: ProjectContext) => string;
+/**
+ * The `client/` half of a server build that keeps Astro's `dist/client` +
+ * `dist/server` split and serves only the client half: the Node standalone
+ * server's static handler reads only `build.client`, and `@astrojs/cloudflare`
+ * declares `preserveBuildClientDir: true` and points the ASSETS binding in the
+ * `dist/server/wrangler.json` it generates at `../client`.
+ */
+export declare const clientDir: (context: ProjectContext) => string;
+/**
+ * The root a deploy adapter is shown, in place of the `.blume` runtime Astro
+ * actually roots at. Adapters assume `outDir` is `<root>/dist` and resolve
+ * their own output (and Vercel's dependency trace) against `root`, so the
+ * root implied by Blume's `outDir` is the one that keeps that assumption
+ * true. See `withAdapterRoot`.
+ *
+ * For a normal build that is the project root (`<project>/dist` ->
+ * `<project>`). For a relocated runtime (`blume build --isolated`) it is the
+ * runtime dir itself (`<runtime>/dist` -> `<runtime>`), keeping a verify
+ * build's adapter output self-contained instead of overwriting the real
+ * `.vercel/output`.
+ */
+export declare const adapterRoot: (context: ProjectContext) => string;
+/** Prefix a bare host with `https://`; pass values that are already absolute. */
+export declare const toSiteUrl: (value: string | undefined) => string | null;

package/dist/types/deploy/platforms/static.d.ts

@@ -0,0 +1,10 @@
+import type { DeployPlatform } from "./types.ts";
+/**
+ * A static build for an unnamed host — the default. Nothing is known about
+ * where `dist/` ends up, so the build writes every platform's redirect file
+ * (`_redirects` for Netlify and Cloudflare, `vercel.json` for Vercel, plus the
+ * manifest for everything else) and the `_headers` file; a host that reads
+ * none of them ignores them harmlessly. The site URL is still inferred from
+ * whichever platform env the build runs in.
+ */
+export declare const staticPlatform: DeployPlatform;

package/dist/types/deploy/platforms/types.d.ts

@@ -0,0 +1,104 @@
+import type { JsonValue } from "../../core/adapter.ts";
+import type { BlumeProject } from "../../core/project-graph.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
+import type { ProjectContext } from "../../core/types.ts";
+import type { DeployAdapterKind } from "../adapters/registry.ts";
+import type { DeployOutput } from "../adapters/types.ts";
+/**
+ * Everything Blume does differently per deployment target, keyed by the
+ * descriptor's `kind`. The descriptor a `blume/deploy` factory returns is
+ * plain data (it is inlined into the generated project), so the behavior
+ * lives here, one module per adapter, and every consumer reads it through
+ * `deployPlatform()` instead of switching on an adapter name.
+ */
+/** How the generated `astro.config.mjs` constructs the `@astrojs/*` adapter. */
+export interface AstroAdapterSpec {
+    /** Top-level `defineConfig` entries the adapter needs beside itself. */
+    config: Record<string, JsonValue>;
+    /** Blume's own constructor options; the user's passthrough is spread over them. */
+    options: (context: ProjectContext) => Record<string, JsonValue>;
+    /** The package the config imports the adapter from. */
+    package: string;
+}
+/** Platform env detection, for inferring `site` and the audit's wording. */
+export interface PlatformEnv {
+    /** True when the env says the build is running on this platform. */
+    detect: (env: NodeJS.ProcessEnv) => boolean;
+    /** The canonical site URL from the platform's env vars, or null. */
+    site: (env: NodeJS.ProcessEnv) => string | null;
+}
+type Redirect = ResolvedConfig["redirects"][number];
+/** A redirect file a static build writes for the host to read. */
+export interface RedirectFile {
+    build: (redirects: Redirect[]) => string;
+    name: string;
+}
+/** The log surface a post-build step reports through (the CLI's logger). */
+export interface BuildLog {
+    error: (message: string) => void;
+    info: (message: string) => void;
+    success: (message: string) => void;
+    warn: (message: string) => void;
+}
+export interface FinalizeBuildOptions {
+    /** A `blume build --isolated` verify: check the output, publish nothing. */
+    isolated: boolean;
+    log: BuildLog;
+    project: BlumeProject;
+}
+/**
+ * What exists only because the Astro project lives in the hidden `.blume/`
+ * runtime instead of the project root. RFC #114 (integration-first) puts the
+ * Astro project at the root, after which this whole group goes: the platform
+ * then reads its bundle where the adapter wrote it, and the adapter sees the
+ * real root without being told.
+ */
+export interface HiddenRuntime {
+    /**
+     * The top-level directory the adapter's deploy bundle lands in, for
+     * `.gitignore`. The platform's own state lives beside the bundle
+     * (`.vercel/project.json`, `.netlify/state.json`), so the directory is
+     * ignored whole. Null when the bundle lands in `dist/`, already ignored.
+     */
+    ignoreDir: string | null;
+    /**
+     * Hand the adapter the project root (`withAdapterRoot`) instead of the
+     * runtime: for an adapter that resolves its output tree, or a dependency
+     * trace, against `root`, which for Blume is the hidden runtime.
+     */
+    showProjectRoot: boolean;
+    /**
+     * A bundle written relative to the Astro root, to move from
+     * `<root>/.blume/<path>` up to `<root>/<path>` after the build, where the
+     * platform looks for it. Null when nothing needs moving.
+     */
+    surfacePath: string | null;
+}
+export interface DeployPlatform {
+    /** The `@astrojs/*` adapter a server build uses; null for the static kind. */
+    astro: AstroAdapterSpec | null;
+    /** Env detection, or null for a target with no platform env (Node, static). */
+    env: PlatformEnv | null;
+    /**
+     * The post-build step for a server build — Vercel's function-bundle audit
+     * and negotiation routes, Cloudflare's wrapper Worker. Resolves to false
+     * when the build must not ship.
+     */
+    finalizeBuild: ((options: FinalizeBuildOptions) => Promise<boolean>) | null;
+    hiddenRuntime: HiddenRuntime;
+    kind: DeployAdapterKind;
+    /** Whether a server build honors `Accept: text/markdown` at the content URLs. */
+    negotiatesMarkdown: boolean;
+    /**
+     * Whether the platform applies a `_headers` file to the static assets it
+     * serves, per output mode.
+     */
+    readsHeaderFiles: Record<DeployOutput, boolean>;
+    /** The redirect files a static build writes, beside the manifest. */
+    redirectFiles: RedirectFile[];
+    /** Where a server build's deploy bundle lands. */
+    serverOutputDir: (context: ProjectContext) => string;
+    /** The directory a server build serves as static files. */
+    serverStaticDir: (context: ProjectContext) => string;
+}
+export {};

package/dist/types/deploy/platforms/vercel.d.ts

@@ -0,0 +1,32 @@
+import type { BlumeProject } from "../../core/project-graph.ts";
+import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
+/** `vercel.json` with a `redirects` array, for a static deploy of `dist/`. */
+export declare const VERCEL_JSON_FILE: RedirectFile;
+/**
+ * Refuse to ship a function bundle that would crash at runtime: a bare import
+ * the adapter's dependency trace silently dropped (see
+ * `deploy/function-bundle.ts`). A missing package that is one of Blume's own
+ * dependencies is fatal — the generated runtime imports it, so every request
+ * would die; a project's own external import is reported as a warning and
+ * left to the author. Resolves to whether the bundle may ship.
+ */
+export declare const checkVercelFunctionBundles: (outputDir: string, root: string, log: BuildLog) => Promise<boolean>;
+/**
+ * Splice `Accept: text/markdown` negotiation routes into the adapter's Build
+ * Output config, so a content-page request that prefers Markdown gets the
+ * page's prerendered `.md` mirror (content pages are prerendered even in
+ * server output, so Astro middleware never sees them — the routing layer is
+ * the only request-time hook). The adapter writes the config straight to the
+ * root it was shown.
+ */
+export declare const emitVercelNegotiation: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Vercel. A server build's Build Output tree lands at `.vercel/output` — at
+ * the project root, because the adapter is handed that root up front: its
+ * `@vercel/nft` dependency trace is rooted there too, and tracing from the
+ * hidden runtime silently drops the function's chunks and `node_modules`.
+ * Static assets are served from the tree's `static/` half, so the deploy
+ * artifacts are written there; headers arrive through the routing config
+ * rather than a `_headers` file, which Vercel never reads.
+ */
+export declare const vercelPlatform: DeployPlatform;