blume 1.7.3 → 2.0.1

package/src/deploy/artifacts.ts

@@ -28,9 +28,10 @@ import type { ResolvedConfig } from "../core/schema.ts";
 import { buildSearchIndex } from "../search/build.ts";
 import { syncSearchProvider } from "../search/sync/index.ts";
 import { readsHeaderFiles } from "./adapter-output.ts";
-import { buildNetlifyHeaders } from "./headers.ts";
+import { buildNetlifyHeaders, buildVercelHeaders } from "./headers.ts";
+import { deployPlatform } from "./platforms/index.ts";
+import { VERCEL_JSON_FILE } from "./platforms/vercel.ts";
 import {
-  buildNetlifyRedirects,
   buildRedirectManifest,
   buildVercelConfig,
   platformRedirects,
@@ -63,38 +64,63 @@ export interface ArtifactLogger {
 }
 
 /**
- * Emit platform redirect files for a static build (adapters wire redirects
- * natively). Always writes the manifest; writes `_redirects`/`vercel.json` only
- * when the user hasn't shipped one via public/. Note that Vercel's
+ * Emit platform redirect files for a static build (a server build answers
+ * redirects at request time): the files the deployment's platform reads
+ * (`_redirects`, `vercel.json` — every one of them when no host is named),
+ * each only when the user hasn't shipped one via public/, plus the
+ * `blume-redirects.json` manifest when no host is named. `vercel.json` also
+ * carries the header rules `_headers` gives the other hosts, since Vercel reads
+ * no `_headers`, so it is written even with no redirects. Note that Vercel's
  * git-integration builds read `vercel.json` from the repository root only —
  * the copy emitted here takes effect when the dist folder itself is deployed
  * directly via the Vercel CLI.
  */
 const emitRedirectFiles = async (
-  config: ResolvedConfig,
+  project: BlumeProject,
   distDir: string,
   logger: ArtifactLogger
 ): Promise<void> => {
-  const redirects = platformRedirects(config);
-  if (redirects.length === 0 || config.deployment.output !== "static") {
+  const { config } = project;
+  if (config.deployment.options.output !== "static") {
     return;
   }
-  await writeFile(
-    join(distDir, "blume-redirects.json"),
-    buildRedirectManifest(redirects),
-    "utf-8"
+  const platform = deployPlatform(config.deployment);
+  const redirects = platformRedirects(config);
+  const vercelHeaders = platform.redirectFiles.includes(VERCEL_JSON_FILE)
+    ? buildVercelHeaders(
+        config,
+        buildHomeLinkHeader(config, markdownRoutePaths(project))
+      )
+    : [];
+  const files = platform.redirectFiles.filter(
+    (file) =>
+      !existsSync(join(distDir, file.name)) &&
+      (redirects.length > 0 ||
+        (file === VERCEL_JSON_FILE && vercelHeaders.length > 0))
   );
-  const platformFiles = [
-    { content: buildNetlifyRedirects(redirects), name: "_redirects" },
-    { content: buildVercelConfig(redirects), name: "vercel.json" },
-  ];
   await Promise.all(
-    platformFiles.map((file) =>
-      existsSync(join(distDir, file.name))
-        ? Promise.resolve()
-        : writeFile(join(distDir, file.name), file.content, "utf-8")
+    files.map((file) =>
+      writeFile(
+        join(distDir, file.name),
+        file === VERCEL_JSON_FILE
+          ? buildVercelConfig(redirects, vercelHeaders)
+          : file.build(redirects),
+        "utf-8"
+      )
     )
   );
+  if (redirects.length === 0) {
+    return;
+  }
+  // The manifest is for a host Blume can't name, where nothing reads the
+  // platform files above.
+  if (platform.kind === "static") {
+    await writeFile(
+      join(distDir, "blume-redirects.json"),
+      buildRedirectManifest(redirects),
+      "utf-8"
+    );
+  }
   logger.info(`Emitted redirect files for ${redirects.length} redirect(s)`);
 };
 
@@ -161,7 +187,7 @@ export const emitHeaderFiles = async (
 };
 
 /**
- * Collect the Agent Skills `ai.skills` publishes, once per build, so both the
+ * Collect the Agent Skills `agents.skills` publishes, once per build, so both the
  * skills surface and llms.txt (which lists them) read the same set. Empty
  * when the feature is off, the directory is missing, nothing in it is
  * publishable (each with a warning), or a user-shipped
@@ -172,14 +198,14 @@ const collectConfiguredSkills = async (
   distDir: string,
   logger: ArtifactLogger
 ): Promise<SkillArtifact[]> => {
-  const configured = project.config.ai.skills;
+  const configured = project.config.agents.skills;
   if (!configured) {
     return [];
   }
   const dir = resolve(project.context.root, configured);
   if (!existsSync(dir)) {
     logger.warn(
-      `ai.skills points at "${configured}" (${dir}), which does not exist; no skills published.`
+      `agents.skills points at "${configured}" (${dir}), which does not exist; no skills published.`
     );
     return [];
   }
@@ -191,7 +217,9 @@ const collectConfiguredSkills = async (
     logger.warn(warning);
   }
   if (skills.length === 0) {
-    logger.warn(`ai.skills: no publishable skills found in "${configured}".`);
+    logger.warn(
+      `agents.skills: no publishable skills found in "${configured}".`
+    );
   }
   return skills;
 };
@@ -324,7 +352,7 @@ export const publishBuildArtifacts = async (
   logger: ArtifactLogger,
   indexSearch: (outDir: string) => Promise<number> = buildSearchIndex
 ): Promise<void> => {
-  if (project.config.search.provider === "pagefind") {
+  if (project.config.search.provider.mode === "pagefind") {
     logger.info("Building search index");
     const indexed = await indexSearch(distDir);
     logger.info(`Indexed ${indexed} page(s) for search`);
@@ -340,7 +368,7 @@ export const publishBuildArtifacts = async (
 
   // Collected once: llms.txt lists the skills the build publishes below.
   const skills = await collectConfiguredSkills(project, distDir, logger);
-  if (project.config.ai.llmsTxt.enabled) {
+  if (project.config.agents.llmsTxt.enabled) {
     await publishLlmsFiles(project, distDir, skills, logger);
   }
 
@@ -376,6 +404,6 @@ export const publishBuildArtifacts = async (
   await emitWellKnownFiles(project.config, distDir, skills, logger);
   await emitAgentSkills(project, distDir, skills, logger);
 
-  await emitRedirectFiles(project.config, distDir, logger);
+  await emitRedirectFiles(project, distDir, logger);
   await emitHeaderFiles(project, distDir, logger);
 };

package/src/deploy/cloudflare-negotiation.ts

@@ -1,8 +1,8 @@
 /**
  * `Accept: text/markdown` content negotiation for Cloudflare server builds.
  *
- * Blume prerenders every content page — even under `deployment.output:
- * "server"` — and on Cloudflare the ASSETS binding serves those files before
+ * 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
@@ -13,10 +13,11 @@
  * 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`, scoped to the
- *    content routes so the platform routes their requests to the Worker
- *    instead of serving the static HTML directly (other assets keep their
- *    zero-Worker fast path).
+ * 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
@@ -32,11 +33,9 @@
  * 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 sets that would claim every
- * `.json` file — a subpath base and the coarse fallback — exempt `*.json`
- * outright, keeping those files on the zero-Worker path; the wrapper branch
- * covers the remaining claims (a content section under `/api`, or
- * user-configured rules).
+ * 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
@@ -62,9 +61,30 @@
  * 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 {
+  API_NAVIGATION_PATH,
+  API_PAGES_PATH,
+  OPENAPI_PATH,
+} from "../ai/api/paths.ts";
 import { normalizePath } from "../core/base-path.ts";
+import type { NotFoundVariants } from "./vercel-negotiation.ts";
 
 /** Filename of the generated wrapper Worker, next to the adapter's entry. */
 export const NEGOTIATION_WORKER_FILE = "blume-worker.mjs";
@@ -72,28 +92,42 @@ export const NEGOTIATION_WORKER_FILE = "blume-worker.mjs";
 /**
  * Wrangler's limits on `assets.run_worker_first`: at most 100 rules of at
  * most 100 characters each. A rule set over either limit fails
- * `wrangler deploy` outright, so the builder falls back to a coarse set.
+ * `wrangler deploy` outright, so the injection is skipped instead — only
+ * user-configured rules can push the generated set over.
  */
 const MAX_RULES = 100;
 const MAX_RULE_LENGTH = 100;
 
 /**
- * Coarse fallback when the grouped rules would exceed Wrangler's limits:
- * route everything through the Worker except the fingerprinted build assets
- * and the raw AI-ready endpoints, whose `charset=utf-8` comes from `_headers`
- * (not applied on worker-first routes) and whose responses never negotiate.
- * The prerendered `.json` documents are exempted for the same reason, and
- * because the Astro Worker would hand the per-page ones to the `/api/`
- * catch-all (see the module comment); a miss on an exempted path still
- * invokes the Worker, so unknown `.json` URLs keep their problem document.
+ * The paths the generated rules leave on the static layer, relative to the
+ * deployment base: the fingerprinted build assets, and the files whose
+ * response headers come from `_headers` — which Cloudflare does not apply to
+ * a response the Worker produced — and which never negotiate. Those are the
+ * raw AI-ready endpoints (`charset=utf-8` on `.md`/`.mdx`/`.txt`) and the
+ * `.well-known` discovery documents (the extensionless api-catalog's content
+ * type, the CORS headers).
+ *
+ * The JSON Blume writes at fixed paths stays there too, but JSON as a whole
+ * does not: a negative rule outranks every positive one, so a `*.json`
+ * exemption would keep a request for a page JSON that doesn't exist
+ * (`/api/docs/pages/nope.json`) off the Worker, and the platform would answer
+ * it with an empty 404 instead of the API's `PAGE_NOT_FOUND` problem document.
+ * The per-page documents themselves reach the wrapper, which serves them from
+ * the binding (see the module comment); any other JSON goes through the Astro
+ * Worker, which serves a static file from the binding as well.
  */
-const FALLBACK_RULES = [
-  "/*",
-  "!/_astro/*",
-  "!/*.md",
-  "!/*.mdx",
-  "!/*.txt",
-  "!/*.json",
+const STATIC_EXEMPTIONS = [
+  "/_astro/*",
+  "/*.md",
+  "/*.mdx",
+  "/*.txt",
+  "/.well-known/*",
+  "/404.json",
+  "/agent-readability.json",
+  "/blume-search.json",
+  OPENAPI_PATH,
+  API_PAGES_PATH,
+  API_NAVIGATION_PATH,
 ];
 
 /**
@@ -129,68 +163,26 @@ const ruleBody = (rule: string): string =>
   isNegativeRule(rule) ? rule.slice(1) : rule;
 
 /**
- * The `run_worker_first` rules for the given content routes: the routes that
- * must reach the Worker for negotiation, grouped by first path segment so the
- * set stays far under Wrangler's 100-rule cap on real sites. Nested groups
- * get a `/{segment}/*` glob plus negative rules exempting their raw
- * `.md`/`.mdx` mirrors; a bare route gets its exact path in both request
- * spellings (with and without the trailing slash) so no unrelated URL pays
- * the Worker hop. On a subpath deploy the whole base is routed as one group —
- * every route lives under it anyway — with the raw endpoints and the
- * prerendered `.json` documents exempted like the coarse fallback does.
+ * 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 const buildRunWorkerFirstRules = (
-  routePaths: readonly string[],
-  base?: string
-): string[] => {
+export const buildRunWorkerFirstRules = (base?: string): string[] => {
   const prefix = encodeURI(basePrefix(base));
-  if (prefix) {
-    return [
-      prefix,
-      `${prefix}/*`,
-      `!${prefix}/*.md`,
-      `!${prefix}/*.mdx`,
-      `!${prefix}/*.txt`,
-      `!${prefix}/*.json`,
-      `!${prefix}/_astro/*`,
-    ];
-  }
-  const groups = new Map<string, { bare: boolean; nested: boolean }>();
-  let home = false;
-  for (const route of routePaths) {
-    if (route === "/") {
-      home = true;
-      continue;
-    }
-    const segments = route.split("/").filter(Boolean);
-    const head = segments[0] ?? "";
-    const group = groups.get(head) ?? { bare: false, nested: false };
-    if (segments.length === 1) {
-      group.bare = true;
-    } else {
-      group.nested = true;
-    }
-    groups.set(head, group);
-  }
-  const rules: string[] = home ? ["/"] : [];
-  const negatives: string[] = [];
-  for (const [head, group] of groups) {
-    const segment = `/${encodeURI(head)}`;
-    if (group.bare) {
-      rules.push(segment);
-    }
-    if (group.nested) {
-      rules.push(`${segment}/*`);
-      negatives.push(`!${segment}/*.md`, `!${segment}/*.mdx`);
-    } else {
-      rules.push(`${segment}/`);
-    }
-  }
-  return [...rules, ...negatives];
+  const exemptions = STATIC_EXEMPTIONS.map((path) => `!${prefix}${path}`);
+  return prefix
+    ? [prefix, `${prefix}/*`, ...exemptions]
+    : [`/*`, ...exemptions];
 };
 
 /**
@@ -268,6 +260,12 @@ export interface NegotiationWorkerOptions {
    * 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;
 }
 
 /**
@@ -287,6 +285,10 @@ export const buildNegotiationWorker = (
   const homeTokens = JSON.stringify(
     options.homeTokens === undefined ? null : String(options.homeTokens)
   );
+  const notFound = JSON.stringify({
+    json: options.notFound?.json === true,
+    markdown: options.notFound?.markdown === true,
+  });
   // Keyed by the normalized served path; the runtime lookup decodes and
   // trims the request path the same way, so both spellings of a URL match.
   // The destination is percent-encoded here because it ships as a `Location`
@@ -309,9 +311,11 @@ export const buildNegotiationWorker = (
 // per-page JSON document is served from the binding (the Astro Worker would
 // route it to the \`/api/\` catch-all, because Astro resolves a prerendered
 // dynamic route to the first live route on the same path). Every other
-// request is delegated to the Astro Worker untouched. \`_headers\` does not
-// apply to worker-first routes, so the homepage Link header and the Markdown
-// charset are re-stamped here.
+// request is delegated to the Astro Worker untouched — except a missing
+// page, whose HTML 404 shell is swapped for the prerendered Markdown or JSON
+// 404 twin when the client prefers one. \`_headers\` does not apply to
+// worker-first routes, so the homepage Link header and the Markdown charset
+// are re-stamped here.
 import server from ${JSON.stringify(options.mainSpecifier)};
 
 const ROUTES = new Set(${routes});
@@ -321,6 +325,7 @@ const ASSETS_BINDING = ${binding};
 const HOME_LINK_HEADER = ${homeLinkHeader};
 const HOME_TOKENS = ${homeTokens};
 const REDIRECTS = ${redirects};
+const NOT_FOUND = ${notFound};
 
 // Configured redirects live in \`_redirects\`, which only the static layer
 // reads — a worker-first route never reaches it. Answering from this baked-in
@@ -383,20 +388,93 @@ const parseAccept = (accept) =>
     return { q: Number.isNaN(q) ? 1 : q, type };
   });
 
-const prefersMarkdown = (accept) => {
+// Whether the client explicitly prefers one of \`types\` over HTML. Browsers
+// never send these, so an ordinary page request is false.
+const prefers = (accept, types) => {
   if (!accept) {
     return false;
   }
-  let markdownQ = -1;
+  let wantedQ = -1;
   let htmlQ = 0;
   for (const { q, type } of parseAccept(accept)) {
-    if (type === "text/markdown" || type === "text/x-markdown") {
-      markdownQ = Math.max(markdownQ, q);
+    if (types.includes(type)) {
+      wantedQ = Math.max(wantedQ, q);
     } else if (type === "text/html") {
       htmlQ = Math.max(htmlQ, q);
     }
   }
-  return markdownQ > 0 && markdownQ >= htmlQ;
+  return wantedQ > 0 && wantedQ >= htmlQ;
+};
+
+const prefersMarkdown = (accept) =>
+  prefers(accept, ["text/markdown", "text/x-markdown"]);
+
+const prefersJson = (accept) =>
+  prefers(accept, ["application/json", "application/problem+json"]);
+
+// The prerendered 404 twins, in the order a client asking for both is
+// answered: which twin, when a client prefers it, the raw URL extension that
+// asks for it implicitly, where it lives, and the content type to re-pin.
+const NOT_FOUND_TWINS = [
+  {
+    contentType: "text/markdown; charset=utf-8",
+    extension: /\\.mdx?$/u,
+    key: "markdown",
+    path: "/404.md",
+    prefers: prefersMarkdown,
+  },
+  {
+    contentType: "application/problem+json; charset=utf-8",
+    extension: /\\.json$/u,
+    key: "json",
+    path: "/404.json",
+    prefers: prefersJson,
+  },
+];
+
+// A missing page comes back from the Astro Worker as the HTML 404 shell (the
+// binding's \`not_found_handling\`); a client that prefers Markdown or JSON —
+// or asked for a raw \`.md\`/\`.json\` URL no file backs — gets the prerendered
+// twin instead, with the same 404 status. Anything but an HTML 404 (an API
+// endpoint's own problem document, a missing image) is left alone. The twin
+// is fetched without the request's conditional headers, so a stray ETag match
+// cannot turn the 404 into a 304.
+const notFoundTwin = async (request, url, response, assets) => {
+  if (response.status !== 404 || assets === undefined) {
+    return null;
+  }
+  const type = response.headers.get("content-type") ?? "";
+  if (!type.startsWith("text/html")) {
+    return null;
+  }
+  const accept = request.headers.get("accept");
+  for (const twin of NOT_FOUND_TWINS) {
+    if (!NOT_FOUND[twin.key]) {
+      continue;
+    }
+    const negotiated = twin.prefers(accept);
+    if (!negotiated && !twin.extension.test(url.pathname)) {
+      continue;
+    }
+    const asset = await assets.fetch(
+      new Request(new URL(BASE_PREFIX + twin.path, url), {
+        method: request.method,
+      })
+    );
+    if (!asset.ok) {
+      return null;
+    }
+    const patched = new Response(asset.body, {
+      headers: asset.headers,
+      status: 404,
+    });
+    patched.headers.set("content-type", twin.contentType);
+    if (negotiated) {
+      patched.headers.append("vary", "Accept");
+    }
+    return patched;
+  }
+  return null;
 };
 
 const markdownVariantUrl = (rawUrl) => {
@@ -487,6 +565,10 @@ export default {
       }
     }
     const response = await server.fetch(request, env, context);
+    const twin = await notFoundTwin(request, url, response, assets);
+    if (twin !== null) {
+      return twin;
+    }
     if (variant === null && !(home && HOME_LINK_HEADER !== null)) {
       return response;
     }
@@ -531,13 +613,13 @@ export interface WorkerNegotiationOptions extends Omit<
  * 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 a
- * rule set that cannot fit Wrangler's limits even after the coarse fallback.
+ * 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 groups, the
- * coarse fallback's `/*`, or the user's own (including a bare `true`). A
+ * 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
@@ -594,13 +676,10 @@ export const injectWorkerNegotiation = (
       redirect.from.startsWith("/") &&
       !guardRoutes.has(normalizePath(redirect.from))
   );
-  let rules = mergeRunWorkerFirstRules(
+  const rules = mergeRunWorkerFirstRules(
     assets.run_worker_first,
-    buildRunWorkerFirstRules(options.routePaths, options.base)
+    buildRunWorkerFirstRules(options.base)
   );
-  if (!withinWranglerLimits(rules)) {
-    rules = mergeRunWorkerFirstRules(assets.run_worker_first, FALLBACK_RULES);
-  }
   if (!withinWranglerLimits(rules)) {
     return null;
   }

package/src/deploy/function-bundle.ts

@@ -6,6 +6,10 @@ import { init, parse } from "es-module-lexer";
 import { dirname, join, relative } from "pathe";
 import { z } from "zod";
 
+import {
+  commandsFor,
+  detectProjectPackageManager,
+} from "../cli/init/scaffold.ts";
 import { packageRoot } from "../core/package-root.ts";
 
 /**
@@ -271,16 +275,27 @@ export interface FunctionBundleVerdict {
   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 const addDevDependencyCommand = async (root: string): Promise<string> =>
+  `${commandsFor(await detectProjectPackageManager(root)).add} -D`;
+
 /**
  * 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.
+ * dependencies (`sharp`, `takumi-js`) already follow — added with
+ * `addDevCommand` (see {@link addDevDependencyCommand}).
  */
 export const functionBundleVerdict = (
   audit: FunctionBundleAudit,
   root: string,
-  ownDependencies: ReadonlySet<string>
+  ownDependencies: ReadonlySet<string>,
+  addDevCommand = "npm install -D"
 ): FunctionBundleVerdict => {
   const names = audit.missing.map((entry) => entry.name);
   const lines = audit.missing.map(
@@ -291,7 +306,7 @@ export const functionBundleVerdict = (
     `The Vercel function bundle at ${relative(root, audit.dir) || audit.dir} is missing packages its server code imports, so the deployed function would fail on every request with ERR_MODULE_NOT_FOUND:`,
     ...lines,
     "Vercel's dependency trace only includes packages resolvable from the project root; under an isolated linker (pnpm, Bun's isolated mode) Blume's own dependencies are not. Add them to the project's package.json so the trace can find them:",
-    `  npm install -D ${names.join(" ")}`,
+    `  ${addDevCommand} ${names.join(" ")}`,
   ].join("\n");
   return { fatal, message };
 };