blume 2.0.2 → 2.1.0

package/src/deploy/platforms/cloudflare.ts

@@ -11,8 +11,10 @@ import {
   markdownRoutePaths,
   markdownTokenCount,
 } from "../../ai/markdown.ts";
+import { normalizeBasePath } from "../../core/base-path.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ProjectContext } from "../../core/types.ts";
+import { withRateLimitBinding } from "../../ratelimit/wrangler.ts";
 import { CLOUDFLARE_ADAPTER_PACKAGE } from "../adapters/cloudflare.ts";
 import {
   injectWorkerNegotiation,
@@ -90,8 +92,13 @@ export const emitCloudflareNegotiation = async (
   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);
+  // neither), like the Vercel routing config. The adapter writes the
+  // prerendered files under the deployment base (`dist/client/<base>/`),
+  // where the wrapper fetches them from.
+  const staticDir = join(
+    clientDir(context),
+    normalizeBasePath(config.deployment.options.base)
+  );
   const injected = injectWorkerNegotiation(
     await readFile(wranglerPath, "utf-8"),
     {
@@ -119,7 +126,7 @@ export const emitCloudflareNegotiation = async (
       // 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),
+      redirects: platformRedirects(project),
       routePaths,
     }
   );
@@ -267,6 +274,36 @@ export const nameCloudflareWorker = async (
   );
 };
 
+/**
+ * Declare the Workers rate limiting binding `rateLimit: cloudflare()` counts
+ * with in the built Worker's config, which `wrangler deploy` reads.
+ */
+export const bindCloudflareRateLimit = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<void> => {
+  const { rateLimit } = project.config;
+  if (rateLimit?.kind !== "cloudflare") {
+    return;
+  }
+  const wranglerPath = join(
+    distDir(project.context),
+    "server",
+    "wrangler.json"
+  );
+  const bound = existsSync(wranglerPath)
+    ? withRateLimitBinding(await readFile(wranglerPath, "utf-8"), rateLimit)
+    : null;
+  if (bound === null) {
+    log.warn(
+      "Could not declare the rate limiting binding in dist/server/wrangler.json — the routes count in memory instead."
+    );
+    return;
+  }
+  await writeFile(wranglerPath, bound, "utf-8");
+  log.success("Declared the Workers rate limiting binding");
+};
+
 /**
  * Cloudflare Workers and Pages. A server build emits the Worker into
  * `dist/server` and serves `dist/client` through the ASSETS binding, which
@@ -292,6 +329,7 @@ export const cloudflarePlatform: DeployPlatform = {
     if (!isolated) {
       await nameCloudflareWorker(project, log);
       await emitCloudflareNegotiation(project, log);
+      await bindCloudflareRateLimit(project, log);
       await emitCloudflareDeployConfig(project.context);
     }
     return true;
@@ -308,6 +346,9 @@ export const cloudflarePlatform: DeployPlatform = {
   previewDeploy: null,
   readsHeaderFiles: { server: true, static: true },
   redirectFiles: [REDIRECTS_FILE],
+  // The adapter points `build.client` at `dist/client/<base>/` for a server
+  // build, and hoists its own `_headers`/`_redirects` back up to `dist/client`.
+  serverClientUnderBase: true,
   serverOutputDir: distDir,
   serverStaticDir: clientDir,
 };

package/src/deploy/platforms/netlify.ts

@@ -9,7 +9,11 @@ import type { BlumeProject } from "../../core/project-graph.ts";
 import { NETLIFY_ADAPTER_PACKAGE } from "../adapters/netlify.ts";
 import { buildNetlifyConfigHeaders } from "../headers.ts";
 import type { NetlifyConfigHeaders } from "../headers.ts";
-import { buildNetlifyRedirects } from "../redirects.ts";
+import {
+  buildNetlifyRedirects,
+  netlifyPatternRedirects,
+  platformRedirects,
+} from "../redirects.ts";
 import { distDir, toSiteUrl } from "./paths.ts";
 import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
 
@@ -76,6 +80,33 @@ export const emitNetlifyHeaders = async (
   await writeFile(configPath, JSON.stringify(frameworks), "utf-8");
 };
 
+/**
+ * Carry the pattern redirects (`/beta/:slug*`) into a server build, as
+ * `redirects` in the Frameworks API config: Astro's `redirects` carry only
+ * the exact ones, since it can't prerender a pattern's pages, so the adapter
+ * never writes these. Netlify appends them after any rules of the user's own.
+ */
+export const emitNetlifyPatternRedirects = async (
+  project: BlumeProject
+): Promise<void> => {
+  const ours = netlifyPatternRedirects(platformRedirects(project));
+  const configPath = join(project.context.root, NETLIFY_CONFIG_FILE);
+  if (ours.length === 0 || !existsSync(configPath)) {
+    return;
+  }
+  // Only `redirects` is read; every other key rides through as parsed.
+  const frameworks: { redirects?: { from: string }[] } = JSON.parse(
+    await readFile(configPath, "utf-8")
+  );
+  // A second pass over the same build replaces its own entries.
+  const froms = new Set(ours.map((entry) => entry.from));
+  frameworks.redirects = [
+    ...(frameworks.redirects ?? []).filter((entry) => !froms.has(entry.from)),
+    ...ours,
+  ];
+  await writeFile(configPath, JSON.stringify(frameworks), "utf-8");
+};
+
 /**
  * Netlify. A server build runs on Netlify Functions from the Frameworks API
  * tree the adapter writes to `.netlify/v1`, relative to the Astro root —
@@ -106,6 +137,7 @@ export const netlifyPlatform: DeployPlatform = {
     // never surfaces it.
     if (!isolated) {
       await emitNetlifyHeaders(project, log);
+      await emitNetlifyPatternRedirects(project);
     }
     return true;
   },
@@ -124,6 +156,7 @@ export const netlifyPlatform: DeployPlatform = {
   // same rules into that tree's config.
   readsHeaderFiles: { server: false, static: true },
   redirectFiles: [NETLIFY_REDIRECTS_FILE],
+  serverClientUnderBase: false,
   serverOutputDir: distDir,
   serverStaticDir: distDir,
 };

package/src/deploy/platforms/node.ts

@@ -37,6 +37,7 @@ export const nodePlatform: DeployPlatform = {
   previewDeploy: null,
   readsHeaderFiles: { server: false, static: false },
   redirectFiles: [],
+  serverClientUnderBase: false,
   serverOutputDir: distDir,
   serverStaticDir: clientDir,
 };

package/src/deploy/platforms/static.ts

@@ -25,6 +25,7 @@ export const staticPlatform: DeployPlatform = {
   previewDeploy: null,
   readsHeaderFiles: { server: false, static: true },
   redirectFiles: [REDIRECTS_FILE, VERCEL_JSON_FILE],
+  serverClientUnderBase: false,
   serverOutputDir: distDir,
   serverStaticDir: distDir,
 };

package/src/deploy/platforms/types.ts

@@ -112,6 +112,14 @@ export interface DeployPlatform {
   readsHeaderFiles: Record<DeployOutput, boolean>;
   /** The redirect files a static build writes, beside the manifest. */
   redirectFiles: RedirectFile[];
+  /**
+   * Whether the adapter moves a server build's client output under
+   * `deployment.base` (`dist/client/<base>/`, the directory Astro then hands
+   * `astro:build:done`) while the platform keeps serving `serverStaticDir`
+   * as the assets root. The files the platform reads there, like `_headers`,
+   * belong above the directory Astro reports.
+   */
+  serverClientUnderBase: boolean;
   /** Where a server build's deploy bundle lands. */
   serverOutputDir: (context: ProjectContext) => string;
   /** The directory a server build serves as static files. */

package/src/deploy/platforms/vercel.ts

@@ -29,8 +29,15 @@ import {
   blumeDependencyNames,
   functionBundleVerdict,
 } from "../function-bundle.ts";
-import { buildVercelConfig } from "../redirects.ts";
-import { injectNegotiationRoutes } from "../vercel-negotiation.ts";
+import {
+  buildVercelConfig,
+  platformRedirects,
+  vercelPatternRoutes,
+} from "../redirects.ts";
+import {
+  injectNegotiationRoutes,
+  injectRedirectRoutes,
+} from "../vercel-negotiation.ts";
 import { adapterRoot, toSiteUrl } from "./paths.ts";
 import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
 
@@ -141,6 +148,33 @@ export const emitVercelNegotiation = async (
   );
 };
 
+/**
+ * Route the pattern redirects (`/beta/:slug*`) in the adapter's Build Output
+ * config: Astro's `redirects` carry only the exact ones, since it can't
+ * prerender a pattern's pages, so the adapter never sees these.
+ */
+export const emitVercelPatternRedirects = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<void> => {
+  const routes = vercelPatternRoutes(platformRedirects(project));
+  const configPath = join(buildOutputDir(project.context), "config.json");
+  if (routes.length === 0 || !existsSync(configPath)) {
+    return;
+  }
+  const injected = injectRedirectRoutes(
+    await readFile(configPath, "utf-8"),
+    routes
+  );
+  if (injected === null) {
+    log.warn(
+      "Could not route the pattern redirects in .vercel/output/config.json, so paths they cover answer 404."
+    );
+    return;
+  }
+  await writeFile(configPath, injected, "utf-8");
+};
+
 /**
  * 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
@@ -180,6 +214,7 @@ export const vercelPlatform: DeployPlatform = {
     // config is a deploy artifact and stays untouched.
     if (!isolated) {
       await emitVercelNegotiation(project, log);
+      await emitVercelPatternRedirects(project, log);
     }
     return true;
   },
@@ -194,6 +229,7 @@ export const vercelPlatform: DeployPlatform = {
   previewDeploy: "vercel deploy",
   readsHeaderFiles: { server: false, static: false },
   redirectFiles: [VERCEL_JSON_FILE],
+  serverClientUnderBase: false,
   serverOutputDir: buildOutputDir,
   serverStaticDir: (context) => join(buildOutputDir(context), "static"),
 };

package/src/deploy/redirects.ts

@@ -1,21 +1,55 @@
 import {
   normalizeBasePath,
+  withAuthoredBasePath,
   withBasePath,
   withComposedBasePath,
 } from "../core/base-path.ts";
+import { routeSetFor, servesRoute } from "../core/locale-links.ts";
+import type { RouteSet } from "../core/locale-links.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import {
+  compileRedirects,
+  exactFirst,
+  expandRedirect,
+  underscoreRedirect,
+  vercelRedirect,
+} from "../core/redirect-patterns.ts";
+import type { RedirectRule } from "../core/redirect-patterns.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { escapeVercelSource } from "./headers.ts";
 import type { VercelHeader } from "./headers.ts";
+import type { VercelRoute } from "./vercel-negotiation.ts";
 
 /**
  * Platform redirect files for a static build. Astro already emits redirect HTML
  * (meta-refresh) pages for static output, but that's a soft client redirect.
  * These give the host a real HTTP 3xx: Netlify/Cloudflare read `_redirects`,
  * Vercel reads `vercel.json`, and `blume-redirects.json` is a structured
- * manifest for anything else (Apache/nginx rules, an edge worker).
+ * manifest for anything else (Apache/nginx rules, an edge worker). A pattern
+ * redirect (`/beta/:slug*`) gets no redirect page, since Astro can't
+ * prerender one for paths it doesn't know; each host file carries it in that
+ * host's syntax (see `core/redirect-patterns.ts`).
  */
 
 type Redirect = ResolvedConfig["redirects"][number];
 
+/**
+ * Base a redirect destination authored as if mounted at root by what it
+ * names (see `withAuthoredBasePath`): a page gains the full
+ * `{deployment.base}{basePath}` stack, a public file (`/files/spec.pdf`, with
+ * no page in `routes`) only the deployment base — `public/` is served there
+ * whatever `basePath` is. External URLs pass through.
+ */
+const baseRedirectTarget = (
+  to: string,
+  basePath: string,
+  base: string,
+  routes: RouteSet
+): string =>
+  withAuthoredBasePath(base, basePath, to, (route) =>
+    servesRoute(routes, route)
+  );
+
 /**
  * Base a redirect for Astro's `redirects` config, where the two sides are not
  * symmetric:
@@ -23,19 +57,23 @@ type Redirect = ResolvedConfig["redirects"][number];
  * - `from` gains only `basePath`. Astro builds the match pattern with
  *   `deployment.base` already applied (`getPattern(segments, config.base)`), so
  *   adding it here would serve the redirect at `{base}{base}/from`.
- * - `to` gains the full `{deployment.base}{basePath}` stack. Astro resolves a
- *   destination that matches a known route by regenerating it from that route's
- *   segments, which carry no base — and passes an unmatched destination through
- *   verbatim. Neither path prepends `base`, so a root-relative `to` escapes the
- *   base entirely (withastro/astro#7774, still the behavior in Astro 7).
+ * - `to` gains the full `{deployment.base}{basePath}` stack, or the deployment
+ *   base alone for a public file (see {@link baseRedirectTarget}). Astro
+ *   resolves a destination that matches a known route by regenerating it from
+ *   that route's segments, which carry no base — and passes an unmatched
+ *   destination through verbatim. Neither path prepends `base`, so a
+ *   root-relative `to` escapes the base entirely (withastro/astro#7774, still
+ *   the behavior in Astro 7).
  *
- * Both sides are authored as if mounted at root; external `to` URLs pass
- * through. Idempotent, so a hand-written base isn't doubled.
+ * Both sides are authored as if mounted at root; `routes` (the served page
+ * routes, carrying `basePath`) tell a dotted page route like `/releases/v1.2`
+ * from a file. Idempotent, so a hand-written base isn't doubled.
  */
 export const applyBaseToAstroRedirects = (
   redirects: Redirect[],
   basePath: string,
-  deployBase: string
+  deployBase: string,
+  routes: RouteSet
 ): Redirect[] => {
   // `deployment.base` arrives as the user wrote it (Astro accepts `/base/`,
   // even `base`); normalizing here keeps the composed paths well-formed.
@@ -44,58 +82,86 @@ export const applyBaseToAstroRedirects = (
     ? redirects.map((redirect) => ({
         ...redirect,
         from: withBasePath(basePath, redirect.from),
-        to: withComposedBasePath(base, basePath, redirect.to),
+        to: baseRedirectTarget(redirect.to, basePath, base, routes),
       }))
     : redirects;
 };
 
 /**
  * Base a redirect for the host platform files below. Unlike Astro's config,
- * these are matched against the real served URL, so both sides carry the full
- * `{deployment.base}{basePath}` stack.
+ * these are matched against the real served URL, so `from` carries the full
+ * `{deployment.base}{basePath}` stack, and so does `to` unless it names a
+ * public file (see {@link baseRedirectTarget}).
  */
 export const applyBaseToPlatformRedirects = (
   redirects: Redirect[],
   basePath: string,
-  deployBase: string
+  deployBase: string,
+  routes: RouteSet
 ): Redirect[] => {
   const base = normalizeBasePath(deployBase);
   return basePath || base
     ? redirects.map((redirect) => ({
         ...redirect,
         from: withComposedBasePath(base, basePath, redirect.from),
-        to: withComposedBasePath(base, basePath, redirect.to),
+        to: baseRedirectTarget(redirect.to, basePath, base, routes),
       }))
     : redirects;
 };
 
 /**
  * The configured redirects as the host platform matches them, via
- * {@link applyBaseToPlatformRedirects}. The one basing every consumer must
- * share: the emitted redirect files and the Cloudflare worker-first redirect
- * exemptions both compare these paths against real served URLs.
+ * {@link applyBaseToPlatformRedirects}, exact paths ahead of patterns: hosts
+ * try rules in order, and an exact redirect wins over a pattern that also
+ * covers its path. The one basing every consumer must share: the emitted
+ * redirect files and the server wrappers all compare these paths against
+ * real served URLs.
  */
-export const platformRedirects = (config: ResolvedConfig): Redirect[] =>
-  applyBaseToPlatformRedirects(
-    config.redirects,
-    config.basePath,
-    config.deployment.options.base ?? ""
+export const platformRedirects = (project: {
+  config: ResolvedConfig;
+  manifest: Pick<BlumeProject["manifest"], "routes">;
+}): Redirect[] => {
+  const { config } = project;
+  return exactFirst(
+    applyBaseToPlatformRedirects(
+      config.redirects,
+      config.basePath,
+      config.deployment.options.base ?? "",
+      routeSetFor(project.manifest.routes)
+    )
   );
+};
+
+/**
+ * A redirect as the entries a host file lists: itself when its path is
+ * exact, else the rules its pattern expands to, in the host's syntax.
+ */
+const hostEntries = <Entry>(
+  redirect: Redirect,
+  exact: (redirect: Redirect) => Entry,
+  pattern: (rule: RedirectRule) => Entry
+): Entry[] => {
+  const rules = expandRedirect(redirect);
+  return rules.length > 0 ? rules.map(pattern) : [exact(redirect)];
+};
 
 /**
- * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line.
- * `force` appends Netlify's `!` to each status (`301!`), so the rule wins over
- * the redirect page Astro writes at `from`; Cloudflare, which always applies
- * its rules first, rejects a line carrying it.
+ * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line,
+ * a pattern as `:placeholder`s and a `*` splat the destination reads as
+ * `:splat`. `force` appends Netlify's `!` to each status (`301!`), so the rule
+ * wins over the redirect page Astro writes at `from`; Cloudflare, which always
+ * applies its rules first, rejects a line carrying it.
  */
 export const buildNetlifyRedirects = (
   redirects: Redirect[],
   force = false
 ): string =>
   `${redirects
-    .map(
-      (redirect) =>
-        `${redirect.from} ${redirect.to} ${redirect.status}${force ? "!" : ""}`
+    .flatMap((redirect) =>
+      hostEntries(redirect, (exact) => exact, underscoreRedirect).map(
+        (entry) =>
+          `${entry.from} ${entry.to} ${redirect.status}${force ? "!" : ""}`
+      )
     )
     .join("\n")}\n`;
 
@@ -110,18 +176,26 @@ interface VercelConfig {
  * header rules are given (see `buildVercelHeaders`). Uses `statusCode` (Vercel's
  * alternative to the boolean `permanent`) so the configured code ships exactly:
  * `permanent` would silently coerce a 301 to 308 and a 302 to 307, diverging
- * from the `_redirects` file, which preserves exact codes.
+ * from the `_redirects` file, which preserves exact codes. A `source` is a
+ * `path-to-regexp` pattern, so each literal run of a `from` path is escaped:
+ * unescaped, `/c++-guide` fails the whole config and `/faq(old)` never
+ * matches. A pattern's captures are `path-to-regexp` params.
  */
 export const buildVercelConfig = (
   redirects: Redirect[],
   headers: readonly VercelHeader[] = []
 ): string => {
   const config: VercelConfig = {
-    redirects: redirects.map((redirect) => ({
-      destination: redirect.to,
-      source: redirect.from,
-      statusCode: redirect.status,
-    })),
+    redirects: redirects.flatMap((redirect) =>
+      hostEntries(
+        redirect,
+        (exact) => ({
+          destination: exact.to,
+          source: escapeVercelSource(exact.from),
+        }),
+        (rule) => vercelRedirect(rule, escapeVercelSource)
+      ).map((entry) => ({ ...entry, statusCode: redirect.status }))
+    ),
   };
   if (headers.length > 0) {
     config.headers = headers;
@@ -129,7 +203,36 @@ export const buildVercelConfig = (
   return `${JSON.stringify(config, null, 2)}\n`;
 };
 
-/** Structured manifest for hosts that need manual wiring. */
+/**
+ * The pattern redirects as `_redirects` entries, for the `redirects` of a
+ * Netlify server build's Frameworks API config (see
+ * {@link buildNetlifyRedirects} for the syntax).
+ */
+export const netlifyPatternRedirects = (
+  redirects: Redirect[]
+): { from: string; status: number; to: string }[] =>
+  redirects.flatMap(expandRedirect).map((rule) => ({
+    ...underscoreRedirect(rule),
+    status: rule.status,
+  }));
+
+/**
+ * The pattern redirects as Build Output API routes, for a Vercel server
+ * build: the adapter routes only the exact redirects Astro's config carries.
+ * Each matches the served path, a trailing slash optional, and fills its
+ * `Location` from numbered captures, as the adapter's own redirect routes do.
+ */
+export const vercelPatternRoutes = (redirects: Redirect[]): VercelRoute[] =>
+  compileRedirects(redirects).map(([src, location, status]) => ({
+    headers: { Location: location },
+    src,
+    status,
+  }));
+
+/**
+ * Structured manifest for hosts that need manual wiring. A pattern stays as
+ * configured (`/beta/:slug*`), for the rule it becomes to be written by hand.
+ */
 export const buildRedirectManifest = (redirects: Redirect[]): string =>
   `${JSON.stringify(
     redirects.map((redirect) => ({

package/src/deploy/robots.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -49,7 +49,7 @@ export const buildRobots = (project: BlumeProject): string | null => {
 
   const { site } = config.deployment.options;
   if (site && config.seo.sitemap) {
-    const sitemapPath = withBasePath(
+    const sitemapPath = mountBasePath(
       normalizeBasePath(config.deployment.options.base),
       "/sitemap.xml"
     );

package/src/deploy/rss.ts

@@ -2,7 +2,7 @@
 // `'` reference rather than `'`, which XML accepts equally.
 import { escape as escapeXml } from "html-escaper";
 
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { siteRoot } from "../core/site-url.ts";
 import type { PageRecord } from "../core/types.ts";
@@ -57,7 +57,8 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
     return [];
   }
   const base = siteRoot(site);
-  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
+  // Routes carry `basePath`; a `deployment.base` subdirectory is mounted on top
+  // of every one, even a route whose first segment matches it (see sitemap.ts).
   // The feed's own `link`/self URL points at the docs root under that base, while
   // `path` stays base-less (it's also the on-disk output location).
   const deployBase = normalizeBasePath(config.deployment.options.base);
@@ -80,7 +81,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
         description: page.description,
         // Encode like the sitemap does: a route with spaces or non-ASCII
         // must still yield a valid <link>/<guid> URL after XML decoding.
-        link: encodeURI(`${base}${withBasePath(deployBase, page.route)}`),
+        link: encodeURI(`${base}${mountBasePath(deployBase, page.route)}`),
         title: page.title,
       }))
       .toSorted((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0))

package/src/deploy/sitemap.ts

@@ -6,7 +6,7 @@ import {
   discoverPagesSync,
   hasGeneratedChangelog,
 } from "../astro/pages.ts";
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { siteRoot } from "../core/site-url.ts";
 
@@ -78,7 +78,9 @@ export const buildSitemapFiles = (
   }
 
   const base = siteRoot(site);
-  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
+  // Routes carry `basePath`; a `deployment.base` subdirectory is mounted on
+  // top of every one, even a route whose first segment matches it: under base
+  // `/guides`, `guides/setup.md` is served at `/guides/guides/setup`.
   const deployBase = normalizeBasePath(project.config.deployment.options.base);
 
   // Archived-version pages leave the sitemap when the version is noindexed,
@@ -135,7 +137,7 @@ export const buildSitemapFiles = (
     ) {
       continue;
     }
-    pushUrl(withBasePath(deployBase, page.route), page.lastModified);
+    pushUrl(mountBasePath(deployBase, page.route), page.lastModified);
   }
   // Custom `.astro` pages and the generated changelog index mount outside
   // `basePath` (they're injected at their pattern — see `blumeIntegration`), so
@@ -150,7 +152,7 @@ export const buildSitemapFiles = (
     extraRoutes.push("/changelog");
   }
   for (const route of extraRoutes) {
-    pushUrl(withBasePath(deployBase, route));
+    pushUrl(mountBasePath(deployBase, route));
   }
   urls.sort();
 
@@ -169,7 +171,7 @@ export const buildSitemapFiles = (
     // Chunks sit next to sitemap.xml, so their URLs layer the same deployment
     // base robots.txt uses for the index.
     const loc = escapeXml(
-      encodeURI(`${base}${withBasePath(deployBase, `/${name}`)}`)
+      encodeURI(`${base}${mountBasePath(deployBase, `/${name}`)}`)
     );
     references.push(`  <sitemap><loc>${loc}</loc></sitemap>`);
   }

package/src/deploy/vercel-negotiation.ts

@@ -399,3 +399,39 @@ 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`;
+};