blume 1.7.3 → 2.0.1

package/src/deploy/platforms/cloudflare.ts

@@ -0,0 +1,312 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import { basename, dirname, join, relative, resolve } from "pathe";
+
+import { pageJsonPath } from "../../ai/api/paths.ts";
+import { buildHomeLinkHeader } from "../../ai/link-headers.ts";
+import {
+  agentMarkdown,
+  buildRawMarkdown,
+  markdownRoutePaths,
+  markdownTokenCount,
+} from "../../ai/markdown.ts";
+import type { BlumeProject } from "../../core/project-graph.ts";
+import type { ProjectContext } from "../../core/types.ts";
+import { CLOUDFLARE_ADAPTER_PACKAGE } from "../adapters/cloudflare.ts";
+import {
+  injectWorkerNegotiation,
+  NEGOTIATION_WORKER_FILE,
+} from "../cloudflare-negotiation.ts";
+import { platformRedirects } from "../redirects.ts";
+import { REDIRECTS_FILE } from "./netlify.ts";
+import { clientDir, distDir, toSiteUrl } from "./paths.ts";
+import type { BuildLog, DeployPlatform } from "./types.ts";
+
+const WRANGLER_CONFIG_FILES = [
+  "wrangler.jsonc",
+  "wrangler.json",
+  "wrangler.toml",
+];
+
+/**
+ * The adapter's constructor options. Every Blume HTML route prerenders (the
+ * only server routes are API endpoints), so images are optimized at build
+ * time with sharp: the adapter's default (`cloudflare-binding`) would instead
+ * declare a runtime `IMAGES` binding in the generated wrangler config that
+ * nothing uses. A wrangler config at the project root is pointed at
+ * explicitly, because the adapter would otherwise look beside the Astro
+ * root — the hidden runtime — and the dev workerd runtime would miss
+ * `nodejs_compat`.
+ */
+const adapterOptions = (context: ProjectContext) => {
+  const options = { imageService: "compile", prerenderEnvironment: "node" };
+  const wranglerPath = WRANGLER_CONFIG_FILES.map((file) =>
+    join(context.root, file)
+  ).find((file) => existsSync(file));
+  if (!wranglerPath) {
+    return options;
+  }
+  let configPath = relative(context.outDir, wranglerPath);
+  // The wrangler config always lives at the project root, above the `.blume`
+  // runtime, so `relative` yields a `../…` path; normalize the theoretical
+  // sibling case to an explicit `./` so it reads as relative.
+  if (!configPath.startsWith(".") && !configPath.startsWith("/")) {
+    configPath = `./${configPath}`;
+  }
+  return { ...options, configPath };
+};
+
+const warnNegotiationSkipped = (log: BuildLog): void =>
+  log.warn(
+    "Could not wire Accept: text/markdown negotiation into dist/server/wrangler.json — raw Markdown stays available at the .md URLs."
+  );
+
+/**
+ * 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 const emitCloudflareNegotiation = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<void> => {
+  const { config, context } = project;
+  const serverDir = join(distDir(context), "server");
+  const wranglerPath = join(serverDir, "wrangler.json");
+  if (!existsSync(wranglerPath)) {
+    warnNegotiationSkipped(log);
+    return;
+  }
+  const routePaths = markdownRoutePaths(project);
+  // The homepage mirror is served from the static layer, so its
+  // `x-markdown-tokens` estimate rides the wrapper Worker, mirroring the
+  // Vercel routing config.
+  const rawMarkdown = await buildRawMarkdown(project);
+  const home = rawMarkdown["/"];
+  // The 404 twins the wrapper may substitute for the HTML shell; only wired
+  // when the build actually emitted them (a project that owns `/404` gets
+  // neither), like the Vercel routing config.
+  const staticDir = clientDir(context);
+  const injected = injectWorkerNegotiation(
+    await readFile(wranglerPath, "utf-8"),
+    {
+      base: config.deployment.options.base,
+      // The manifest routes guard the wrapper's redirect table; `routePaths`
+      // also carries the synthesized homepage mirror, which must not block a
+      // configured root redirect.
+      contentRoutePaths: project.manifest.routes.map((route) => route.path),
+      homeLinkHeader: buildHomeLinkHeader(config, routePaths),
+      homeTokens: home ? markdownTokenCount(agentMarkdown(home)) : undefined,
+      notFound: {
+        json: existsSync(join(staticDir, "404.json")),
+        markdown: existsSync(join(staticDir, "404.md")),
+      },
+      // Exactly the per-page JSON documents the API emits (see `pageParams`):
+      // the non-hidden routes with agent Markdown, when the API is on.
+      pageJsonPaths: config.agents.api
+        ? project.manifest.routes
+            .filter(
+              (route) => !route.hidden && rawMarkdown[route.path] !== undefined
+            )
+            .map((route) => pageJsonPath(route.path))
+        : [],
+      // The wrapper Worker matches full served URLs, so the redirects are
+      // based the same way the platform files are — it answers any the
+      // worker-first rules claim, where `_redirects` is never consulted and
+      // Astro would default their status.
+      redirects: platformRedirects(config),
+      routePaths,
+    }
+  );
+  if (injected === null) {
+    warnNegotiationSkipped(log);
+    return;
+  }
+  await writeFile(
+    join(serverDir, NEGOTIATION_WORKER_FILE),
+    injected.worker,
+    "utf-8"
+  );
+  await writeFile(wranglerPath, injected.wrangler, "utf-8");
+  log.success(
+    "Wired Accept: text/markdown negotiation into the Cloudflare Worker"
+  );
+};
+
+/**
+ * Where Cloudflare's deploy tooling looks for the redirect to the built
+ * config, relative to the directory `wrangler deploy` runs in (or any parent).
+ */
+const DEPLOY_CONFIG = join(".wrangler", "deploy", "config.json");
+
+/** The redirect file the Cloudflare Vite plugin writes. */
+interface DeployConfig {
+  auxiliaryWorkers?: { configPath: string }[];
+  configPath: string;
+  prerenderWorkerConfigPath?: string;
+}
+
+/**
+ * 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 const emitCloudflareDeployConfig = async (
+  context: ProjectContext
+): Promise<void> => {
+  const builtConfig = join(distDir(context), "server", "wrangler.json");
+  if (!existsSync(builtConfig)) {
+    return;
+  }
+  const source = join(context.outDir, DEPLOY_CONFIG);
+  const target = join(context.root, DEPLOY_CONFIG);
+  const rebase = (path: string): string =>
+    relative(dirname(target), resolve(dirname(source), path));
+  const deployConfig: DeployConfig = existsSync(source)
+    ? JSON.parse(await readFile(source, "utf-8"))
+    : { configPath: relative(dirname(source), builtConfig) };
+  const rebased: DeployConfig = {
+    auxiliaryWorkers: (deployConfig.auxiliaryWorkers ?? []).map((worker) => ({
+      configPath: rebase(worker.configPath),
+    })),
+    configPath: rebase(deployConfig.configPath),
+  };
+  if (deployConfig.prerenderWorkerConfigPath) {
+    rebased.prerenderWorkerConfigPath = rebase(
+      deployConfig.prerenderWorkerConfigPath
+    );
+  }
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, `${JSON.stringify(rebased)}\n`, "utf-8");
+};
+
+/**
+ * The name the Worker gets when the build names it: the generated runtime's
+ * package name, which every Blume site shares. Left as is, two sites deployed
+ * to one account would overwrite each other's Worker.
+ */
+const RUNTIME_WORKER_NAME = "blume-runtime";
+
+/**
+ * A Worker name from free text: lowercase letters, digits, and dashes, no
+ * leading or trailing dash, at most 63 characters (a Worker name is also a
+ * `workers.dev` hostname label).
+ */
+const toWorkerName = (text: string): string =>
+  text
+    .toLowerCase()
+    .replaceAll(/[^\da-z]+/gu, "-")
+    .slice(0, 63)
+    .replaceAll(/^-+|-+$/gu, "");
+
+/**
+ * The Worker name for a project that doesn't name its own: the project's
+ * `package.json` name (a scope folded in, `@acme/docs` → `acme-docs`), else the
+ * site's hostname, else the project folder's name.
+ */
+const projectWorkerName = async (
+  project: BlumeProject
+): Promise<string | undefined> => {
+  const { config, context } = project;
+  const packageFile = join(context.root, "package.json");
+  const manifest: { name?: string } = existsSync(packageFile)
+    ? JSON.parse(await readFile(packageFile, "utf-8"))
+    : {};
+  const { site } = config.deployment.options;
+  return [
+    String(manifest.name ?? ""),
+    site ? new URL(site).hostname : "",
+    basename(context.root),
+  ]
+    .map(toWorkerName)
+    .find((name) => name.length > 0);
+};
+
+/**
+ * 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 const nameCloudflareWorker = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<void> => {
+  const wranglerPath = join(
+    distDir(project.context),
+    "server",
+    "wrangler.json"
+  );
+  if (!existsSync(wranglerPath)) {
+    return;
+  }
+  // Only the two name fields are read; every other key rides through as parsed.
+  const wrangler: { name?: string; topLevelName?: string } = JSON.parse(
+    await readFile(wranglerPath, "utf-8")
+  );
+  const name = await projectWorkerName(project);
+  if (wrangler.name !== RUNTIME_WORKER_NAME || name === undefined) {
+    return;
+  }
+  wrangler.name = name;
+  if (wrangler.topLevelName === RUNTIME_WORKER_NAME) {
+    wrangler.topLevelName = name;
+  }
+  await writeFile(wranglerPath, JSON.stringify(wrangler), "utf-8");
+  log.info(
+    `Named the Cloudflare Worker "${name}"; set "name" in a wrangler.jsonc at the project root to choose another.`
+  );
+};
+
+/**
+ * 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 const cloudflarePlatform: DeployPlatform = {
+  astro: {
+    config: { session: false },
+    options: adapterOptions,
+    package: CLOUDFLARE_ADAPTER_PACKAGE,
+  },
+  env: {
+    detect: (env) => Boolean(env.CF_PAGES),
+    site: (env) => toSiteUrl(env.CF_PAGES_URL),
+  },
+  finalizeBuild: async ({ isolated, log, project }) => {
+    // The Worker's name, the wrapper Worker, and the deploy redirect are
+    // deploy artifacts; an isolated verify skips them.
+    if (!isolated) {
+      await nameCloudflareWorker(project, log);
+      await emitCloudflareNegotiation(project, log);
+      await emitCloudflareDeployConfig(project.context);
+    }
+    return true;
+  },
+  hiddenRuntime: {
+    // The redirected deploy config `wrangler deploy` reads from the project
+    // root lands in `.wrangler/`, a build artifact like Vercel's `.vercel/`.
+    ignoreDir: ".wrangler/",
+    showProjectRoot: false,
+    surfacePath: null,
+  },
+  kind: "cloudflare",
+  negotiatesMarkdown: true,
+  readsHeaderFiles: { server: true, static: true },
+  redirectFiles: [REDIRECTS_FILE],
+  serverOutputDir: distDir,
+  serverStaticDir: clientDir,
+};

package/src/deploy/platforms/index.ts

@@ -0,0 +1,67 @@
+import type {
+  DeployAdapterKind,
+  ResolvedDeployment,
+} from "../adapters/registry.ts";
+import { cloudflarePlatform } from "./cloudflare.ts";
+import { netlifyPlatform } from "./netlify.ts";
+import { nodePlatform } from "./node.ts";
+import { staticPlatform } from "./static.ts";
+import type { DeployPlatform } from "./types.ts";
+import { vercelPlatform } from "./vercel.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 const DEPLOY_PLATFORMS: readonly DeployPlatform[] = [
+  vercelPlatform,
+  netlifyPlatform,
+  cloudflarePlatform,
+  nodePlatform,
+  staticPlatform,
+];
+
+const byKind = new Map<DeployAdapterKind, DeployPlatform>(
+  DEPLOY_PLATFORMS.map((platform) => [platform.kind, platform])
+);
+
+/** The behaviors behind a resolved deployment descriptor. */
+export const deployPlatform = (
+  deployment: Pick<ResolvedDeployment, "kind">
+): DeployPlatform => {
+  const platform = byKind.get(deployment.kind);
+  if (!platform) {
+    throw new Error(`Unknown deployment adapter "${deployment.kind}".`);
+  }
+  return platform;
+};
+
+/**
+ * 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 const inferDeploymentSite = (
+  deployment: Pick<ResolvedDeployment, "kind">,
+  env: NodeJS.ProcessEnv
+): string | null => {
+  const own = deployPlatform(deployment);
+  const candidates = [own, ...DEPLOY_PLATFORMS.filter((p) => p !== own)];
+  const detected = candidates.find(
+    (platform) => platform.env?.detect(env) ?? false
+  );
+  // `find` only returns a platform whose `env` matched, so it is present.
+  return detected?.env?.site(env) ?? null;
+};
+
+export type {
+  AstroAdapterSpec,
+  BuildLog,
+  DeployPlatform,
+  FinalizeBuildOptions,
+  HiddenRuntime,
+  PlatformEnv,
+  RedirectFile,
+} from "./types.ts";

package/src/deploy/platforms/netlify.ts

@@ -0,0 +1,52 @@
+import { NETLIFY_ADAPTER_PACKAGE } from "../adapters/netlify.ts";
+import { buildNetlifyRedirects } from "../redirects.ts";
+import { distDir, toSiteUrl } from "./paths.ts";
+import type { DeployPlatform, RedirectFile } from "./types.ts";
+
+/** `_redirects`, the format Netlify and Cloudflare Pages/Workers read. */
+export const REDIRECTS_FILE: RedirectFile = {
+  build: buildNetlifyRedirects,
+  name: "_redirects",
+};
+
+/**
+ * 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 const netlifyPlatform: DeployPlatform = {
+  astro: {
+    config: {},
+    options: () => ({}),
+    package: NETLIFY_ADAPTER_PACKAGE,
+  },
+  env: {
+    detect: (env) => Boolean(env.NETLIFY),
+    // Fall through per *resolved* value, not per variable — a platform can
+    // set a var to the empty string, which `??` on the raw values treats as
+    // present, dead-ending the chain and silently losing the site URL.
+    site: (env) =>
+      toSiteUrl(env.URL) ??
+      toSiteUrl(env.DEPLOY_PRIME_URL) ??
+      toSiteUrl(env.DEPLOY_URL),
+  },
+  finalizeBuild: null,
+  hiddenRuntime: {
+    ignoreDir: ".netlify/",
+    showProjectRoot: false,
+    surfacePath: ".netlify/v1",
+  },
+  kind: "netlify",
+  negotiatesMarkdown: false,
+  // Netlify reads `_headers` from the publish directory of a static deploy.
+  // A server build's static assets ride the Frameworks API tree instead,
+  // where the file has never been applied.
+  readsHeaderFiles: { server: false, static: true },
+  redirectFiles: [REDIRECTS_FILE],
+  serverOutputDir: distDir,
+  serverStaticDir: distDir,
+};

package/src/deploy/platforms/node.ts

@@ -0,0 +1,40 @@
+import { NODE_ADAPTER_PACKAGE } from "../adapters/node.ts";
+import { wrapNodeEntry } from "../node-headers.ts";
+import { clientDir, distDir } from "./paths.ts";
+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 const nodePlatform: DeployPlatform = {
+  astro: {
+    config: {},
+    options: () => ({ mode: "standalone" }),
+    package: NODE_ADAPTER_PACKAGE,
+  },
+  env: null,
+  finalizeBuild: async ({ isolated, log, project }) => {
+    // The wrapped entry is a deploy artifact; an isolated verify skips it.
+    if (!isolated) {
+      await wrapNodeEntry(project, log);
+    }
+    return true;
+  },
+  hiddenRuntime: {
+    ignoreDir: null,
+    showProjectRoot: false,
+    surfacePath: null,
+  },
+  kind: "node",
+  negotiatesMarkdown: false,
+  readsHeaderFiles: { server: false, static: false },
+  redirectFiles: [],
+  serverOutputDir: distDir,
+  serverStaticDir: clientDir,
+};

package/src/deploy/platforms/paths.ts

@@ -0,0 +1,42 @@
+import { dirname, join } from "pathe";
+
+import type { ProjectContext } from "../../core/types.ts";
+
+/** Astro's build output dir: the runtime's own `distDir`, else `<root>/dist`. */
+export const distDir = (context: ProjectContext): string =>
+  context.distDir ?? join(context.root, "dist");
+
+/**
+ * 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 const clientDir = (context: ProjectContext): string =>
+  join(distDir(context), "client");
+
+/**
+ * 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 const adapterRoot = (context: ProjectContext): string =>
+  dirname(distDir(context));
+
+/** Prefix a bare host with `https://`; pass values that are already absolute. */
+export const toSiteUrl = (value: string | undefined): string | null => {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  return /^https?:\/\//u.test(trimmed) ? trimmed : `https://${trimmed}`;
+};

package/src/deploy/platforms/static.ts

@@ -0,0 +1,29 @@
+import { REDIRECTS_FILE } from "./netlify.ts";
+import { distDir } from "./paths.ts";
+import type { DeployPlatform } from "./types.ts";
+import { VERCEL_JSON_FILE } from "./vercel.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 const staticPlatform: DeployPlatform = {
+  astro: null,
+  env: null,
+  finalizeBuild: null,
+  hiddenRuntime: {
+    ignoreDir: null,
+    showProjectRoot: false,
+    surfacePath: null,
+  },
+  kind: "static",
+  negotiatesMarkdown: false,
+  readsHeaderFiles: { server: false, static: true },
+  redirectFiles: [REDIRECTS_FILE, VERCEL_JSON_FILE],
+  serverOutputDir: distDir,
+  serverStaticDir: distDir,
+};

package/src/deploy/platforms/types.ts

@@ -0,0 +1,112 @@
+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;
+}