blume 2.0.3 → 2.1.1

package/src/deploy/vercel-negotiation.ts

@@ -14,22 +14,103 @@
  * prerendered Markdown 404 body with the 404 status, instead of the HTML
  * shell, and one that prefers JSON (or asks for a `.json` URL) gets the
  * prerendered problem-details 404.
+ *
+ * Under `deployment.base` every route here matches the served URL, base
+ * included, and names the files where Blume moves them (`static/<base>/`, see
+ * {@link rebaseAdapterRoutes}); `base` is the normalized base, `""` for none.
  */
 
+import { mountBasePath } from "../core/base-path.ts";
 import { SVG_ASSET_HEADERS } from "./headers.ts";
 
-/**
- * Regex for the `accept` header condition. Written to hold under both matching
- * semantics a router may apply — full-string and substring — by anchoring the
- * end and letting `(.*,)?` absorb any earlier list entries: it requires a
- * `text/markdown` or `text/x-markdown` entry terminated by `;`, `,`, or the end
- * of the header. Kept lookaround-free so it stays valid in RE2, and lowercase
- * only — real agents send lowercase media types, and q-values are not compared
- * (a client sending `text/markdown` at `q=0` is pathological). Browsers never
- * send `text/markdown`, so ordinary page requests are unaffected.
+/*
+ * The `accept` header conditions. Dev and the Cloudflare Worker negotiate the
+ * way `prefersMarkdown` (`astro/markdown-negotiation.ts`) does: media types in
+ * any case, and Markdown only when its q-value is above zero and at least
+ * HTML's. A routing condition is a regex over the whole header, with no
+ * arithmetic, so the comparison is spelled as two routes per rewrite:
+ *
+ * - a Markdown entry at full weight (no q-value, or `q=1`) always wins, since
+ *   nothing can outrank it;
+ * - a Markdown entry below full weight wins only when the header has no
+ *   `text/html` entry above zero (a `missing` condition), since two q-values
+ *   below 1 can't be compared. That case, like `text/markdown;q=0.9,
+ *   text/html;q=0.8`, gets HTML on Vercel where dev and Cloudflare send
+ *   Markdown.
+ *
+ * Every pattern is anchored at both ends and lets `(?:.*,)?` absorb the
+ * earlier list entries, so it holds under full-string and substring matching
+ * alike. Case-insensitivity is spelled out letter by letter and the patterns
+ * are lookaround-free, so they read the same in RE2, PCRE, and JavaScript.
+ * Like dev, only the first `q=` parameter of an entry counts, and a `q=`
+ * value is read as a decimal. Browsers never send `text/markdown`, so
+ * ordinary page requests are unaffected.
  */
-export const ACCEPT_MARKDOWN_HEADER_VALUE =
-  "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
+
+/** `word` in any case, one character class per letter: `[Tt][Ee][Xx][Tt]`. */
+const anyCase = (word: string): string =>
+  word.replaceAll(/[a-z]/gu, (letter) => `[${letter.toUpperCase()}${letter}]`);
+
+/** An entry's parameters before its first `q=`: any that isn't one. */
+const OTHER_PARAMS = String.raw`(?:;\s*(?:[^\sq;,][^;,]*|q(?:[^=;,][^;,]*)?)?)*`;
+
+/** Everything after an entry's first `q=` value, up to the next entry. */
+const LATER_PARAMS = "(?:;[^,]*)?";
+
+/** A `q=` value of 1 or more: full weight. */
+const FULL_WEIGHT = String.raw`0*[1-9][0-9]*(?:\.[0-9]*)?`;
+
+/** A `q=` value above zero and below 1. */
+const PARTIAL_WEIGHT = String.raw`0*\.[0-9]*[1-9][0-9]*`;
+
+/** A `q=` value that isn't zero: it has a character besides `0` and `.`. */
+const NONZERO_WEIGHT = String.raw`[\s0.]*[^\s0.;,][^;,]*`;
+
+/** A header with an entry of `type` weighed by `weight`, or by no `q=` when it's optional. */
+const acceptEntry = (type: string, weight: string, optional: boolean) =>
+  String.raw`^(?:.*,)?\s*${type}\s*${OTHER_PARAMS}(?:;\s*q=\s*${weight}\s*${LATER_PARAMS})${optional ? "?" : ""}(?:,.*)?$`;
+
+/** A header with a `type` entry at full weight. */
+const fullWeight = (type: string) => acceptEntry(type, FULL_WEIGHT, true);
+
+/** A header with a `type` entry weighed above zero and below 1. */
+const partialWeight = (type: string) =>
+  acceptEntry(type, PARTIAL_WEIGHT, false);
+
+/** A header with a `text/html` entry weighed above zero. */
+const ACCEPT_HTML = acceptEntry(anyCase("text/html"), NONZERO_WEIGHT, true);
+
+const MARKDOWN_TYPE = `${anyCase("text/")}(?:${anyCase("x-")})?${anyCase("markdown")}`;
+
+const JSON_TYPE = `${anyCase("application/")}(?:${anyCase("problem")}\\+)?${anyCase("json")}`;
+
+/** One header condition on a Build Output route. */
+export interface VercelCondition {
+  key?: string;
+  type: string;
+  value?: string;
+}
+
+/** The conditions of one route: all of `has`, none of `missing`. */
+export interface AcceptConditions {
+  has: VercelCondition[];
+  missing?: VercelCondition[];
+}
+
+const accept = (value: string): VercelCondition => ({
+  key: "accept",
+  type: "header",
+  value,
+});
+
+/** The pair of conditions a route answering `type` is written once for each. */
+const preferring = (type: string): AcceptConditions[] => [
+  { has: [accept(fullWeight(type))] },
+  { has: [accept(partialWeight(type))], missing: [accept(ACCEPT_HTML)] },
+];
+
+/** When a client prefers `text/markdown` (or `text/x-markdown`) over HTML. */
+export const ACCEPT_MARKDOWN_CONDITIONS = preferring(MARKDOWN_TYPE);
 
 /**
  * The JSON counterpart, for the problem-details 404: `application/json` or
@@ -37,8 +118,7 @@ export const ACCEPT_MARKDOWN_HEADER_VALUE =
  * (the catch-all wildcard does not match), so ordinary page requests are
  * unaffected.
  */
-export const ACCEPT_JSON_HEADER_VALUE =
-  "(.*,)?\\s*application/(problem\\+)?json(\\s*[;,].*)?$";
+export const ACCEPT_JSON_CONDITIONS = preferring(JSON_TYPE);
 
 /**
  * A Build Output API route — the subset these helpers read and write. Parsed
@@ -49,23 +129,29 @@ export interface VercelRoute {
   continue?: boolean;
   dest?: string;
   handle?: string;
-  has?: { key?: string; type: string; value?: string }[];
+  has?: VercelCondition[];
   headers?: Record<string, string>;
+  missing?: VercelCondition[];
   src?: string;
   status?: number;
 }
 
+/** `route` once per condition pair, so it fires when either holds. */
+const conditioned = (
+  route: VercelRoute,
+  conditions: readonly AcceptConditions[]
+): VercelRoute[] => conditions.map((condition) => ({ ...route, ...condition }));
+
 /** Whether a parsed route field is a real string (the config is raw JSON). */
 const isString = (value: string | undefined): value is string =>
   typeof value === "string";
 
-const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
-  { key: "accept", type: "header", value: ACCEPT_MARKDOWN_HEADER_VALUE },
-];
-
-const ACCEPT_JSON_CONDITION: VercelRoute["has"] = [
-  { key: "accept", type: "header", value: ACCEPT_JSON_HEADER_VALUE },
-];
+/** The Markdown conditions' `has` values, to recognize a route this module wrote. */
+const MARKDOWN_VALUES = new Set(
+  ACCEPT_MARKDOWN_CONDITIONS.flatMap(({ has }) =>
+    has.map((condition) => condition.value)
+  )
+);
 
 const VARY_ACCEPT = { vary: "Accept" };
 
@@ -78,44 +164,6 @@ const NOT_FOUND_JSON_DEST = "/404.json";
 /** The adapter's own not-found fallback — the anchor the Markdown 404 precedes. */
 const NOT_FOUND_HTML_DEST = "/404.html";
 
-/**
- * Miss-phase routes that answer a missing page with the Markdown 404 body: any
- * path when the client prefers Markdown, and any `.md`/`.mdx` URL (a request
- * for a raw-Markdown mirror that has no page wants Markdown back, not the HTML
- * shell). Both keep the 404 status. Spliced immediately before the adapter's
- * `/404.html` fallback, so they run after every server route (the MCP
- * endpoint, server islands, images) has had its turn and never hijack a
- * request one of those would have answered.
- */
-const NOT_FOUND_MARKDOWN_ROUTES: readonly VercelRoute[] = [
-  {
-    dest: NOT_FOUND_MARKDOWN_DEST,
-    has: ACCEPT_MARKDOWN_CONDITION,
-    headers: VARY_ACCEPT,
-    src: "^/.*$",
-    status: 404,
-  },
-  { dest: NOT_FOUND_MARKDOWN_DEST, src: "^/.*\\.mdx?$", status: 404 },
-];
-
-/**
- * The JSON 404's miss-phase routes, the problem-details twin of the Markdown
- * ones: any path when the client prefers JSON, and any `.json` URL no file
- * backs. Spliced at the same anchor, after every server route — so the
- * `/api/` catch-all (which answers its own namespace with a problem document)
- * has already had its turn.
- */
-const NOT_FOUND_JSON_ROUTES: readonly VercelRoute[] = [
-  {
-    dest: NOT_FOUND_JSON_DEST,
-    has: ACCEPT_JSON_CONDITION,
-    headers: VARY_ACCEPT,
-    src: "^/.*$",
-    status: 404,
-  },
-  { dest: NOT_FOUND_JSON_DEST, src: "^/.*\\.json$", status: 404 },
-];
-
 /** Which prerendered 404 twins the build emitted, so their routes get wired. */
 export interface NotFoundVariants {
   json?: boolean;
@@ -140,6 +188,53 @@ const REGEX_SPECIALS = /[$()*+.?[\]^{|}\\]/gu;
 const routePattern = (route: string): string =>
   encodeURI(route).replace(REGEX_SPECIALS, "\\$&");
 
+/**
+ * The `src` matching the homepage: `^/$`, or the base itself under one, served
+ * without a trailing slash (the adapter's trailing-slash route strips it).
+ */
+const homeSource = (base: string): string =>
+  `^${routePattern(mountBasePath(base, "/"))}$`;
+
+/**
+ * Miss-phase routes that answer a missing page with the Markdown 404 body: any
+ * path when the client prefers Markdown, and any `.md`/`.mdx` URL (a request
+ * for a raw-Markdown mirror that has no page wants Markdown back, not the HTML
+ * shell). Both keep the 404 status. Spliced immediately before the adapter's
+ * `/404.html` fallback, so they run after every server route (the MCP
+ * endpoint, server islands, images) has had its turn and never hijack a
+ * request one of those would have answered.
+ */
+const notFoundMarkdownRoutes = (base: string): VercelRoute[] => {
+  const dest = mountBasePath(base, NOT_FOUND_MARKDOWN_DEST);
+  const prefix = routePattern(base);
+  return [
+    ...conditioned(
+      { dest, headers: VARY_ACCEPT, src: `^${prefix}/.*$`, status: 404 },
+      ACCEPT_MARKDOWN_CONDITIONS
+    ),
+    { dest, src: `^${prefix}/.*\\.mdx?$`, status: 404 },
+  ];
+};
+
+/**
+ * The JSON 404's miss-phase routes, the problem-details twin of the Markdown
+ * ones: any path when the client prefers JSON, and any `.json` URL no file
+ * backs. Spliced at the same anchor, after every server route — so the
+ * `/api/` catch-all (which answers its own namespace with a problem document)
+ * has already had its turn.
+ */
+const notFoundJsonRoutes = (base: string): VercelRoute[] => {
+  const dest = mountBasePath(base, NOT_FOUND_JSON_DEST);
+  const prefix = routePattern(base);
+  return [
+    ...conditioned(
+      { dest, headers: VARY_ACCEPT, src: `^${prefix}/.*$`, status: 404 },
+      ACCEPT_JSON_CONDITIONS
+    ),
+    { dest, src: `^${prefix}/.*\\.json$`, status: 404 },
+  ];
+};
+
 /** Group patterns so each group's alternation stays under the `src` limit. */
 const chunkPatterns = (patterns: readonly string[]): string[][] => {
   const chunks: string[][] = [];
@@ -190,41 +285,49 @@ export interface NegotiationRoutes {
  * rewrite also stamps `x-markdown-tokens` — the estimated token count of the
  * homepage mirror (Cloudflare's Markdown for Agents convention). Only the home
  * route can carry it: the other rewrites are chunked alternations spanning
- * many pages, and a count is per-page.
+ * many pages, and a count is per-page. Under a `base`, each path is matched
+ * and rewritten where it's served (`/docs` → `/docs/index.md`).
  */
 export const buildNegotiationRoutes = (
   routePaths: readonly string[],
-  homeTokens?: number
+  homeTokens?: number,
+  base = ""
 ): NegotiationRoutes => {
   const home = routePaths.includes("/");
   const rest = routePaths
     .filter((path) => path !== "/")
-    .map((path) => routePattern(path));
+    .map((path) => routePattern(mountBasePath(base, path)));
   const chunks = chunkPatterns(rest);
 
   const rewriteRoutes: VercelRoute[] = home
-    ? [
+    ? conditioned(
         {
-          dest: "/index.md",
-          has: ACCEPT_MARKDOWN_CONDITION,
+          dest: mountBasePath(base, "/index.md"),
           headers:
             homeTokens === undefined
               ? VARY_ACCEPT
               : { ...VARY_ACCEPT, "x-markdown-tokens": String(homeTokens) },
-          src: "^/$",
+          src: homeSource(base),
         },
-      ]
+        ACCEPT_MARKDOWN_CONDITIONS
+      )
     : [];
   for (const chunk of chunks) {
-    rewriteRoutes.push({
-      dest: "$1.md",
-      has: ACCEPT_MARKDOWN_CONDITION,
-      headers: VARY_ACCEPT,
-      src: `^(${chunk.join("|")})/?$`,
-    });
+    rewriteRoutes.push(
+      ...conditioned(
+        {
+          dest: "$1.md",
+          headers: VARY_ACCEPT,
+          src: `^(${chunk.join("|")})/?$`,
+        },
+        ACCEPT_MARKDOWN_CONDITIONS
+      )
+    );
   }
 
-  const headerChunks = chunkPatterns(home ? ["/", ...rest] : rest);
+  const headerChunks = chunkPatterns(
+    home ? [routePattern(mountBasePath(base, "/")), ...rest] : rest
+  );
   const headerRoutes: VercelRoute[] = headerChunks.map((chunk) => ({
     continue: true,
     headers: VARY_ACCEPT,
@@ -234,9 +337,6 @@ export const buildNegotiationRoutes = (
   return { headerRoutes, rewriteRoutes };
 };
 
-/** The `src` of the injected homepage `Link` header route. */
-const HOME_SRC = "^/$";
-
 const ALLOW_ANY_ORIGIN = "*";
 
 /**
@@ -244,18 +344,18 @@ const ALLOW_ANY_ORIGIN = "*";
  * one static discovery document (see `crossOriginDiscoveryPaths`), so a
  * registry reading it from another origin isn't refused by the browser.
  */
-const corsRoute = (path: string): VercelRoute => ({
+const corsRoute = (path: string, base: string): VercelRoute => ({
   continue: true,
   headers: { "access-control-allow-origin": ALLOW_ANY_ORIGIN },
-  src: `^${routePattern(path)}$`,
+  src: `^${routePattern(mountBasePath(base, path))}$`,
 });
 
 /**
  * The `src` of the route stamping the content-source SVG headers: every `.svg`
- * under `/blume-assets/`. The adapter copies the static files into the Build
- * Output tree without the deployment base, like every path matched here.
+ * under `/blume-assets/`.
  */
-const SVG_ASSET_SRC = String.raw`^/blume-assets/.+\.svg$`;
+const svgAssetSource = (base: string): string =>
+  String.raw`^${routePattern(base)}/blume-assets/.+\.svg$`;
 
 /**
  * A main-phase `continue` route stamping the sandbox headers
@@ -263,7 +363,7 @@ const SVG_ASSET_SRC = String.raw`^/blume-assets/.+\.svg$`;
  * static layer — where the prerendered asset endpoint's own headers never
  * reach.
  */
-const svgAssetRoute = (): VercelRoute => ({
+const svgAssetRoute = (base: string): VercelRoute => ({
   continue: true,
   headers: Object.fromEntries(
     Object.entries(SVG_ASSET_HEADERS).map(([name, value]) => [
@@ -271,7 +371,7 @@ const svgAssetRoute = (): VercelRoute => ({
       value,
     ])
   ),
-  src: SVG_ASSET_SRC,
+  src: svgAssetSource(base),
 });
 
 /** Whether a route is a `corsRoute` — the same three-field shape test as the others. */
@@ -291,22 +391,23 @@ const isCorsRoute = (route: VercelRoute): boolean =>
  * no user-authored route competes in this file); the Markdown 404 routes by
  * their `/404.md` destination.
  */
-const isNegotiationRoute = (route: VercelRoute): boolean =>
-  route.has?.some(
-    (condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE
-  ) === true ||
-  (route.dest === NOT_FOUND_MARKDOWN_DEST && route.status === 404) ||
-  (route.dest === NOT_FOUND_JSON_DEST && route.status === 404) ||
+const isNegotiationRoute = (route: VercelRoute, base: string): boolean =>
+  route.has?.some((condition) => MARKDOWN_VALUES.has(condition.value)) ===
+    true ||
+  (route.dest === mountBasePath(base, NOT_FOUND_MARKDOWN_DEST) &&
+    route.status === 404) ||
+  (route.dest === mountBasePath(base, NOT_FOUND_JSON_DEST) &&
+    route.status === 404) ||
   (route.continue === true &&
     route.headers?.vary === "Accept" &&
     isString(route.src) &&
     Object.keys(route).length === 3) ||
   (route.continue === true &&
     isString(route.headers?.link) &&
-    route.src === HOME_SRC &&
+    route.src === homeSource(base) &&
     Object.keys(route).length === 3) ||
   isCorsRoute(route) ||
-  (route.continue === true && route.src === SVG_ASSET_SRC);
+  (route.continue === true && route.src === svgAssetSource(base));
 
 /**
  * Splice the negotiation routes into a Build Output `config.json`, plus — when
@@ -325,7 +426,9 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
  * phase right before the adapter's `/404.html` fallback — and nowhere when
  * that fallback is absent, since a `dest` with no file behind it would serve
  * nothing. With `svgAssets`, a main-phase route also sandboxes the SVGs a
- * content source downloaded (see {@link svgAssetRoute}). Returns the updated JSON
+ * content source downloaded (see {@link svgAssetRoute}). Under a `base`, every
+ * route matches and names paths beneath it, and the fallback anchor is the
+ * one {@link rebaseAdapterRoutes} moved there. Returns the updated JSON
  * text (tab-indented, like the adapter's own output), or `null` when there is
  * nowhere safe to splice: an unparsable config, no `routes` array, or no
  * `handle: "filesystem"` marker to anchor the splice.
@@ -338,7 +441,8 @@ export const injectNegotiationRoutes = (
   homeTokens?: number,
   notFound: NotFoundVariants = {},
   corsPaths: readonly string[] = [],
-  svgAssets = false
+  svgAssets = false,
+  base = ""
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   let config: {
@@ -358,7 +462,9 @@ export const injectNegotiationRoutes = (
     // user's own override of the same path is simply refreshed.
     config.overrides = { ...config.overrides, [path]: { contentType } };
   }
-  const routes = config.routes.filter((route) => !isNegotiationRoute(route));
+  const routes = config.routes.filter(
+    (route) => !isNegotiationRoute(route, base)
+  );
   const filesystemIndex = routes.findIndex(
     (route) => route.handle === "filesystem"
   );
@@ -367,30 +473,32 @@ export const injectNegotiationRoutes = (
   }
   const { headerRoutes, rewriteRoutes } = buildNegotiationRoutes(
     routePaths,
-    homeTokens
+    homeTokens,
+    base
   );
   if (homeLinkHeader) {
     headerRoutes.push({
       continue: true,
       headers: { link: homeLinkHeader },
-      src: HOME_SRC,
+      src: homeSource(base),
     });
   }
-  headerRoutes.push(...corsPaths.map(corsRoute));
+  headerRoutes.push(...corsPaths.map((path) => corsRoute(path, base)));
   if (svgAssets) {
-    headerRoutes.push(svgAssetRoute());
+    headerRoutes.push(svgAssetRoute(base));
   }
   // Headers first: `continue` routes accumulate, so a request the rewrite
   // route then terminates (Markdown negotiation on the homepage) still carries
   // the Link header.
   routes.splice(filesystemIndex, 0, ...headerRoutes, ...rewriteRoutes);
   const notFoundRoutes = [
-    ...(notFound.markdown ? NOT_FOUND_MARKDOWN_ROUTES : []),
-    ...(notFound.json ? NOT_FOUND_JSON_ROUTES : []),
+    ...(notFound.markdown ? notFoundMarkdownRoutes(base) : []),
+    ...(notFound.json ? notFoundJsonRoutes(base) : []),
   ];
   if (notFoundRoutes.length > 0) {
+    const fallbackDest = mountBasePath(base, NOT_FOUND_HTML_DEST);
     const fallbackIndex = routes.findIndex(
-      (route) => route.status === 404 && route.dest === NOT_FOUND_HTML_DEST
+      (route) => route.status === 404 && route.dest === fallbackDest
     );
     if (fallbackIndex !== -1) {
       routes.splice(fallbackIndex, 0, ...notFoundRoutes);
@@ -399,3 +507,119 @@ export const injectNegotiationRoutes = (
   config.routes = routes;
   return `${JSON.stringify(config, null, "\t")}\n`;
 };
+
+/**
+ * Splice routes for the pattern redirects (see `vercelPatternRoutes`) into a
+ * Build Output `config.json`, in the main phase just ahead of
+ * `handle: "filesystem"`: after the exact redirects the adapter puts first,
+ * so an exact path still wins. A second pass replaces its own routes. Returns
+ * the updated JSON text, or `null` when there is nowhere safe to splice: an
+ * unparsable config, no `routes` array, or no `handle: "filesystem"` marker.
+ */
+export const injectRedirectRoutes = (
+  configText: string,
+  redirectRoutes: readonly VercelRoute[]
+): string | null => {
+  let config: { routes?: VercelRoute[] };
+  try {
+    config = JSON.parse(configText);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(config.routes)) {
+    return null;
+  }
+  const ours = new Set(redirectRoutes.map((route) => route.src));
+  const routes = config.routes.filter(
+    (route) => !(ours.has(route.src) && isString(route.headers?.Location))
+  );
+  const filesystemIndex = routes.findIndex(
+    (route) => route.handle === "filesystem"
+  );
+  if (filesystemIndex === -1) {
+    return null;
+  }
+  routes.splice(filesystemIndex, 0, ...redirectRoutes);
+  config.routes = routes;
+  return `${JSON.stringify(config, null, "\t")}\n`;
+};
+
+/**
+ * The trailing-slash route `trailingSlash: "never"` gives the adapter's config
+ * (`^/(.*)/$` → `/$1`): it keeps whatever path it strips the slash from, base
+ * and all, so it already serves a based site.
+ */
+const isTrailingSlashRoute = (route: VercelRoute): boolean =>
+  route.headers?.Location === "/$1";
+
+/** The pattern body of the root route, anchored (`^/$`) or not (`/`). */
+const ROOT_BODY = /^\/\$?$/u;
+
+/**
+ * Re-anchor an adapter route pattern under the base, whose escaped form is
+ * `prefix`: each matches a base-less path from its start, and the root route
+ * becomes the base itself, served without a trailing slash.
+ */
+const rebaseSource = (src: string, prefix: string): string => {
+  const body = src.startsWith("^") ? src.slice(1) : src;
+  return `^${prefix}${ROOT_BODY.test(body) ? "$" : body}`;
+};
+
+/**
+ * Move the adapter's routes under `deployment.base`, to match the static files
+ * Blume moves to `static/<base>/`. `@astrojs/vercel` routes a server build as
+ * if it were served from the root: its route patterns (the `_astro/` cache
+ * header, every server route) match base-less paths, its 404 fallback names
+ * `/404.html`, and it joins the base onto each redirect with no slash on the
+ * `from` side and a second time on the `to` side, which Astro hands it
+ * already based (`^/docsold$` → `/docs/docs/new`). Each pattern is
+ * re-anchored under the base and the fallback names the base's `404.html`;
+ * the adapter's redirects make way for `redirectRoutes`, the exact redirects
+ * as the host matches them. Returns the updated JSON text, or `null` when
+ * there is nowhere safe to splice: an unparsable config, no `routes` array,
+ * or no `handle: "filesystem"` marker.
+ */
+export const rebaseAdapterRoutes = (
+  configText: string,
+  base: string,
+  redirectRoutes: readonly VercelRoute[]
+): string | null => {
+  let config: { routes?: VercelRoute[] };
+  try {
+    config = JSON.parse(configText);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(config.routes)) {
+    return null;
+  }
+  const filesystemIndex = config.routes.findIndex(
+    (route) => route.handle === "filesystem"
+  );
+  if (filesystemIndex === -1) {
+    return null;
+  }
+  const prefix = routePattern(base);
+  const routes = config.routes.flatMap((route, index): VercelRoute[] => {
+    // Ahead of the filesystem handler, the adapter writes its redirects and
+    // nothing else with a `Location`.
+    if (index < filesystemIndex && isString(route.headers?.Location)) {
+      return isTrailingSlashRoute(route) ? [route] : [];
+    }
+    const rebased = { ...route };
+    if (isString(route.src)) {
+      rebased.src = rebaseSource(route.src, prefix);
+    }
+    if (route.status === 404 && route.dest === NOT_FOUND_HTML_DEST) {
+      rebased.dest = mountBasePath(base, NOT_FOUND_HTML_DEST);
+    }
+    return [rebased];
+  });
+  routes.splice(
+    routes.findIndex((route) => route.handle === "filesystem"),
+    0,
+    ...redirectRoutes
+  );
+  config.routes = routes;
+  return `${JSON.stringify(config, null, "\t")}\n`;
+};

package/src/eval/agents.ts

@@ -188,7 +188,24 @@ const CLAUDE_READER_MAX_TURNS = "25";
 const CLAUDE_JUDGE_MAX_TURNS = "1";
 
 const claudeArgs = (context: InvocationContext): string[] => {
-  const base = ["-p", "--output-format", "json", "--strict-mcp-config"];
+  // `--tools ""` turns off every Claude Code built-in, including ones the
+  // deny list below doesn't name (`Monitor` runs shell commands, `Skill`
+  // loads the user's skills), so a reader has only the docs MCP tools and the
+  // judge has no tools at all. The deny list stays as a second layer.
+  // `--setting-sources ""` is codex's `--ignore-user-config`: no settings
+  // files, so the user's hooks, plugins, and CLAUDE.md can't hand the reader
+  // context the docs never gave it. Not `--bare`, which also stops reading a
+  // subscription login and fails with "Not logged in".
+  const base = [
+    "-p",
+    "--output-format",
+    "json",
+    "--strict-mcp-config",
+    "--tools",
+    "",
+    "--setting-sources",
+    "",
+  ];
   if (context.mcp) {
     const allowed = MCP_TOOL_NAMES.map(
       (tool) => `mcp__${MCP_SERVER_NAME}__${tool}`

package/src/eval/prompts.ts

@@ -40,8 +40,11 @@ Reply with ONLY this JSON object on a single line, no markdown fences:
 {"pass": true|false, "score": 0.0-1.0, "missing": ["expected facts absent or contradicted"], "notes": "one sentence"}`;
 };
 
-/** The `--fix` handoff prompt: where the report is and the ground rules. */
-export const evalFixPrompt = (reportPath: string): string =>
+/**
+ * The `--fix` handoff prompt: where the report is, the ground rules, and the
+ * `blume eval` command that verifies the fixes (the run's own flags).
+ */
+export const evalFixPrompt = (reportPath: string, command: string): string =>
   `Fix the documentation gaps found by \`blume eval\` in this project.
 
 The full report is at ${reportPath}. It is JSON: each entry in \`eval.results\` with status "fail" is one question the documentation could not answer. Each carries the \`question\`, the \`expected\` facts, the judge's \`missing\` facts, and the reader agent's \`answer\` (what the docs currently convey). The matching \`diagnostics\` entry names the source \`file\` of the page that should answer it.
@@ -51,7 +54,7 @@ Work through every failed question:
 2. Edit the documentation so it states the missing facts explicitly. Add prose, not filler; keep the page's voice.
 3. Never delete questions from the evals file or weaken expected facts.
 
-When you are done, run \`blume eval\` to verify, and repeat until every question passes.`;
+When you are done, run \`${command}\` to verify, and repeat until every question passes.`;
 
 /** The `eval init` prompt: draft a starter evals file from the docs. */
 export const initPrompt = (evalsPath: string): string =>