blume 2.0.2 → 2.1.0

package/src/core/version-cut.ts

@@ -3,7 +3,7 @@ import { cp, readdir, readFile, rm } from "node:fs/promises";
 
 import { join, relative } from "pathe";
 
-import { stripBasePath } from "./base-path.ts";
+import { mountBasePath, stripBasePath } from "./base-path.ts";
 import { nextFenceState } from "./code-fences.ts";
 import type { FenceState } from "./code-fences.ts";
 import { writeTextAtomic } from "./fs-atomic.ts";
@@ -45,18 +45,22 @@ export class CutError extends Error {
 // matching so replacements can splice into the real line by index (the mask
 // preserves length). Mirrors the content-assets rewriter.
 const INLINE_CODE = /`[^`]*`/gu;
-// A markdown link/image target or an HTML href/src attribute whose value is
-// root-absolute. Named groups carry the prefix (kept) and target (rewritten).
-const ROOT_LINK = /(?<prefix>\]\(|href="|src=")(?<target>\/[^\s"')]*)/gu;
+// A root-absolute markdown link/image target, reference-style link definition
+// (`[setup]: /guides/setup`, up to three spaces in, never a `[^note]:`
+// footnote), or HTML href/src attribute in either quote style. Named groups
+// carry the prefix (kept) and target (rewritten).
+const ROOT_LINK =
+  /(?<prefix>\]\(|^ {0,3}\[(?!\^)[^\]]+\]:[ \t]*<?|(?:href|src)=["'])(?<target>\/[^\s"'<>)]*)/gu;
 
 /**
  * Build the link-rewrite table: every current-version route (basePath
- * stripped, since authors write root-absolute links as if mounted at root)
- * mapped to the same page's route inside the new snapshot. Only pages the
- * snapshot actually contains qualify — filesystem pages under the content
- * root. Spec-rendered references (`/api`, `/events`) and remote sources
- * aren't copied, so links to them keep pointing at the live pages instead of
- * a 404 inside the snapshot.
+ * stripped, since authors write root-absolute links as if mounted at root;
+ * a link that spells the base out is looked up without it, see
+ * `snapshotTarget`) mapped to the same page's route inside the new snapshot.
+ * Only pages the snapshot actually contains qualify — filesystem pages under
+ * the content root. Spec-rendered references (`/api`, `/events`) and remote
+ * sources aren't copied, so links to them keep pointing at the live pages
+ * instead of a 404 inside the snapshot.
  */
 const buildRouteRewrites = (
   project: BlumeProject,
@@ -105,8 +109,35 @@ const buildRouteRewrites = (
   return rewrites;
 };
 
+/**
+ * The snapshot link a root-absolute path rewrites to, or undefined when the
+ * snapshot has no copy of its page. A path written with the base path by hand
+ * (`/docs/guides/x` under `basePath: "/docs"`) names the same page as
+ * `/guides/x` — rendering leaves an already-based link alone (see
+ * `withBasePath`) — so it is looked up without the base and keeps it.
+ */
+const snapshotTarget = (
+  path: string,
+  rewrites: Map<string, string>,
+  basePath: string
+): string | undefined => {
+  const based =
+    basePath !== "" && (path === basePath || path.startsWith(`${basePath}/`));
+  if (!based) {
+    return rewrites.get(path);
+  }
+  const replacement = rewrites.get(stripBasePath(basePath, path));
+  return replacement === undefined
+    ? undefined
+    : mountBasePath(basePath, replacement);
+};
+
 /** Rewrite one line's root-absolute internal links via the rewrite table. */
-const rewriteLine = (line: string, rewrites: Map<string, string>): string => {
+const rewriteLine = (
+  line: string,
+  rewrites: Map<string, string>,
+  basePath: string
+): string => {
   const masked = line.replaceAll(INLINE_CODE, (span) =>
     " ".repeat(span.length)
   );
@@ -120,7 +151,7 @@ const rewriteLine = (line: string, rewrites: Map<string, string>): string => {
     const path = hash === -1 ? target : target.slice(0, hash);
     const suffix = hash === -1 ? "" : target.slice(hash);
     const bare = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
-    const replacement = rewrites.get(bare);
+    const replacement = snapshotTarget(bare, rewrites, basePath);
     if (replacement === undefined) {
       continue;
     }
@@ -142,10 +173,12 @@ export interface SnapshotRewrite {
  * Rewrite a copied page's root-absolute internal links to their snapshot
  * equivalents, skipping fenced and inline code. Relative links need no
  * rewriting — the whole tree copies together, so they stay self-contained.
+ * `basePath` is the site's, for links that spell it out by hand.
  */
 export const rewriteSnapshotLinks = (
   source: string,
-  rewrites: Map<string, string>
+  rewrites: Map<string, string>,
+  basePath = ""
 ): SnapshotRewrite => {
   let fence: FenceState = null;
   let count = 0;
@@ -156,7 +189,7 @@ export const rewriteSnapshotLinks = (
     if (inFence) {
       return line;
     }
-    const rewrittenLine = rewriteLine(line, rewrites);
+    const rewrittenLine = rewriteLine(line, rewrites, basePath);
     if (rewrittenLine !== line) {
       count += 1;
     }
@@ -416,7 +449,11 @@ export const cutVersion = async (
           return;
         }
         const source = await readFile(abs, "utf-8");
-        const { text, count } = rewriteSnapshotLinks(source, rewrites);
+        const { text, count } = rewriteSnapshotLinks(
+          source,
+          rewrites,
+          project.config.basePath
+        );
         if (count > 0) {
           await writeTextAtomic(abs, text);
           rewritten.push({ count, file: relative(dir, abs) });

package/src/deploy/artifacts.ts

@@ -14,6 +14,11 @@ import { API_CATALOG_PATH, buildApiCatalog } from "../ai/api-catalog.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { buildLlmsFiles } from "../ai/llms.ts";
 import { markdownRoutePaths } from "../ai/markdown.ts";
+import {
+  buildSiteSkill,
+  SKILL_MD_PATH,
+  siteSkillName,
+} from "../ai/site-skill.ts";
 import {
   AGENT_SKILLS_DIR,
   AGENT_SKILLS_INDEX_PATH,
@@ -25,9 +30,11 @@ import {
   buildSignaturesDirectory,
   SIGNATURES_DIRECTORY_PATH,
 } from "../ai/web-bot-auth.ts";
+import { normalizeBasePath } from "../core/base-path.ts";
 import { discoverPagesSync } from "../core/custom-pages.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { buildNarration } from "../narration/build.ts";
 import { buildSearchIndex } from "../search/build.ts";
 import { syncSearchProvider } from "../search/sync/index.ts";
 import { readsHeaderFiles } from "./adapter-output.ts";
@@ -51,10 +58,12 @@ import { buildSitemapFiles, describeSitemapFiles } from "./sitemap.ts";
  * Written from the integration's `astro:build:done` hook — Astro's channel
  * for exactly this kind of post-build work — into the directory Astro
  * reports as the client output (`dist/`, or `dist/client` for a server
- * build). The Vercel adapter copies that directory into its Build Output
- * static tree in a later hook, so the artifacts ride along; every other
- * adapter serves it directly. Running inside the hook rather than after
- * `astro build` returns means an ejected project keeps producing them.
+ * build, or `dist/client/<base>/` on Cloudflare, whose `_headers` goes to
+ * the root the platform serves above it). The Vercel adapter copies that
+ * directory into its Build Output static tree in a later hook, so the
+ * artifacts ride along; every other adapter serves it directly. Running
+ * inside the hook rather than after `astro build` returns means an ejected
+ * project keeps producing them.
  *
  * Every file yields to one the user ships in `public/` (Astro copied it into
  * the output before this runs).
@@ -88,7 +97,7 @@ const emitRedirectFiles = async (
     return;
   }
   const platform = deployPlatform(config.deployment);
-  const redirects = platformRedirects(config);
+  const redirects = platformRedirects(project);
   const vercelHeaders = platform.redirectFiles.includes(VERCEL_JSON_FILE)
     ? buildVercelHeaders(
         config,
@@ -127,6 +136,24 @@ const emitRedirectFiles = async (
   logger.info(`Emitted redirect files for ${redirects.length} redirect(s)`);
 };
 
+/**
+ * The root of the static assets the platform serves, where it reads
+ * `_headers`: `distDir` itself, except on a server build whose adapter moved
+ * the client output under `deployment.base` (`@astrojs/cloudflare` hands
+ * `astro:build:done` `dist/client/<base>/` but serves `dist/client`). A file
+ * left in `distDir` there would never be read, and would be served publicly
+ * at `<base>/_headers`.
+ */
+const assetsRoot = (config: ResolvedConfig, distDir: string): string => {
+  const base = normalizeBasePath(config.deployment.options.base);
+  const nested =
+    config.deployment.options.output === "server" &&
+    deployPlatform(config.deployment).serverClientUnderBase;
+  // One `..` per base segment climbs back out of `dist/client/<base>/`.
+  const depth = base.split("/").length - 1;
+  return nested && base ? join(distDir, "../".repeat(depth)) : distDir;
+};
+
 /**
  * Emit a `_headers` file so Netlify / Cloudflare serve the raw AI-ready
  * endpoints (`*.md`, `*.mdx`, `*.txt`) with an explicit `charset=utf-8`. Without
@@ -179,7 +206,7 @@ export const emitHeaderFiles = async (
   // An adapter may have written its own rules here already (Cloudflare adds an
   // immutable Cache-Control for /_astro/*). Keep them and append ours: both
   // sets are wanted, and `_headers` has no merge semantics beyond order.
-  const target = join(distDir, "_headers");
+  const target = join(assetsRoot(config, distDir), "_headers");
   const existing = existsSync(target) ? await readFile(target, "utf-8") : "";
   await writeFile(
     target,
@@ -191,7 +218,8 @@ export const emitHeaderFiles = async (
 
 /**
  * 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
+ * skills surface and llms.txt (which lists them) read the same set (the
+ * generated site skill joins them in {@link publishedSkills}). Empty
  * when the feature is off, the directory is missing, nothing in it is
  * publishable (each with a warning), or a user-shipped
  * `public/.well-known/agent-skills/index.json` already owns the surface.
@@ -227,6 +255,57 @@ const collectConfiguredSkills = async (
   return skills;
 };
 
+/**
+ * Every skill the build publishes: the `agents.skills` ones, plus the
+ * generated site skill unless one of those shares its name (the hand-written
+ * one wins) or a user-shipped index owns the surface.
+ */
+const publishedSkills = async (
+  project: BlumeProject,
+  distDir: string,
+  surface: { mcp: boolean; userIndex: boolean },
+  logger: ArtifactLogger
+): Promise<SkillArtifact[]> => {
+  const configured = await collectConfiguredSkills(project, distDir, logger);
+  // The skill lists the MCP server only when the build serves it.
+  const site = surface.userIndex
+    ? null
+    : buildSiteSkill({
+        ...project,
+        config: advertisedConfig(project.config, {
+          mcp: surface.mcp,
+          skills: true,
+        }),
+      });
+  return site && !configured.some((skill) => skill.name === site.name)
+    ? [site, ...configured]
+    : configured;
+};
+
+/**
+ * Serve the site skill at `/skill.md` too, the path agents try first: the
+ * generated one, or a same-named hand-written skill that is a lone
+ * `SKILL.md` (an archive's relative references need its other files). A
+ * `public/skill.md` wins.
+ */
+const emitSkillMd = async (
+  project: BlumeProject,
+  distDir: string,
+  skills: readonly SkillArtifact[],
+  logger: ArtifactLogger
+): Promise<void> => {
+  const target = join(distDir, SKILL_MD_PATH.slice(1));
+  const name = siteSkillName(project);
+  const skill = skills.find(
+    (candidate) => candidate.name === name && candidate.type === "skill-md"
+  );
+  if (!(project.config.agents.skillMd && skill) || existsSync(target)) {
+    return;
+  }
+  await writeFile(target, skill.content);
+  logger.info(`Generated ${SKILL_MD_PATH.slice(1)} (the "${name}" skill)`);
+};
+
 /**
  * Publish the collected Agent Skills: copy each skill artifact under
  * `.well-known/agent-skills/` and emit the discovery index. A user-shipped
@@ -361,6 +440,10 @@ export const publishBuildArtifacts = async (
     logger.info(`Indexed ${indexed} page(s) for search`);
   }
 
+  // Generated narration reads the built pages, so it runs once they exist.
+  // Nothing happens without `narration.provider`.
+  await buildNarration(project, distDir, logger);
+
   // Upload the index to a hosted provider (Algolia, Orama Cloud, Typesense).
   // Skipped with a warning when its admin key isn't configured.
   await syncSearchProvider(project, {
@@ -373,18 +456,24 @@ export const publishBuildArtifacts = async (
   const userSkillsIndex = existsSync(
     join(distDir, AGENT_SKILLS_INDEX_PATH.slice(1))
   );
-  const skills = await collectConfiguredSkills(project, distDir, logger);
+  const mcp = servesMcp(
+    project,
+    project.context.pagesRoot
+      ? discoverPagesSync(project.context.pagesRoot)
+      : []
+  );
+  const skills = await publishedSkills(
+    project,
+    distDir,
+    { mcp, userIndex: userSkillsIndex },
+    logger
+  );
   // The discovery documents advertise what this build serves: no MCP server
   // when a page took its route, no skills index when nothing was published.
   const advertised: BlumeProject = {
     ...project,
     config: advertisedConfig(project.config, {
-      mcp: servesMcp(
-        project,
-        project.context.pagesRoot
-          ? discoverPagesSync(project.context.pagesRoot)
-          : []
-      ),
+      mcp,
       skills: skills.length > 0 || userSkillsIndex,
     }),
   };
@@ -423,6 +512,7 @@ export const publishBuildArtifacts = async (
 
   await emitWellKnownFiles(advertised.config, distDir, skills, logger);
   await emitAgentSkills(project, distDir, skills, logger);
+  await emitSkillMd(project, distDir, skills, logger);
 
   await emitRedirectFiles(advertised, distDir, logger);
   await emitHeaderFiles(advertised, distDir, logger);

package/src/deploy/cloudflare-negotiation.ts

@@ -84,7 +84,8 @@ import {
   API_PAGES_PATH,
   OPENAPI_PATH,
 } from "../ai/api/paths.ts";
-import { normalizePath } from "../core/base-path.ts";
+import { normalizeBasePath, normalizePath } from "../core/base-path.ts";
+import { compileRedirects, isPatternPath } from "../core/redirect-patterns.ts";
 import { CONTENT_ASSETS_ROOT, SVG_ASSET_HEADERS } from "./headers.ts";
 import type { NotFoundVariants } from "./vercel-negotiation.ts";
 
@@ -132,14 +133,6 @@ const STATIC_EXEMPTIONS = [
   API_NAVIGATION_PATH,
 ];
 
-/**
- * The deployment base as a rule/URL prefix: trailing slash stripped, empty
- * for a root deploy — the same normalization the dev middleware applies in
- * `astro/markdown-negotiation.ts`.
- */
-const basePrefix = (base?: string): string =>
-  base && base !== "/" ? base.replace(/\/$/u, "") : "";
-
 /** A value as `JSON.parse` produces it (the wrangler config's value space). */
 type JsonValue =
   | string
@@ -180,7 +173,7 @@ const ruleBody = (rule: string): string =>
  * status (see the module comment).
  */
 export const buildRunWorkerFirstRules = (base?: string): string[] => {
-  const prefix = encodeURI(basePrefix(base));
+  const prefix = encodeURI(normalizeBasePath(base));
   const exemptions = STATIC_EXEMPTIONS.map((path) => `!${prefix}${path}`);
   return prefix
     ? [prefix, `${prefix}/*`, ...exemptions]
@@ -282,7 +275,7 @@ export const buildNegotiationWorker = (
   const routes = JSON.stringify(options.routePaths);
   const pageJson = JSON.stringify(options.pageJsonPaths ?? []);
   const binding = JSON.stringify(options.assetsBinding);
-  const prefix = JSON.stringify(encodeURI(basePrefix(options.base)));
+  const prefix = JSON.stringify(encodeURI(normalizeBasePath(options.base)));
   const homeLinkHeader = JSON.stringify(options.homeLinkHeader ?? null);
   const homeTokens = JSON.stringify(
     options.homeTokens === undefined ? null : String(options.homeTokens)
@@ -297,12 +290,18 @@ export const buildNegotiationWorker = (
   // header, which cannot carry non-ASCII.
   const redirects = JSON.stringify(
     Object.fromEntries(
-      (options.redirects ?? []).map((redirect) => [
-        normalizePath(redirect.from),
-        [encodeURI(redirect.to), redirect.status],
-      ])
+      (options.redirects ?? [])
+        .filter((redirect) => !isPatternPath(redirect.from))
+        .map((redirect) => [
+          normalizePath(redirect.from),
+          [encodeURI(redirect.to), redirect.status],
+        ])
     )
   );
+  // Patterns (`/beta/:slug*`) are tried in order after the exact paths.
+  const patternRedirects = JSON.stringify(
+    compileRedirects(options.redirects ?? [])
+  );
   return `// Generated by Blume. Do not edit; this file is recreated on each build.
 //
 // Request-time \`Accept: text/markdown\` negotiation for a Cloudflare server
@@ -327,6 +326,9 @@ const ASSETS_BINDING = ${binding};
 const HOME_LINK_HEADER = ${homeLinkHeader};
 const HOME_TOKENS = ${homeTokens};
 const REDIRECTS = ${redirects};
+const PATTERN_REDIRECTS = ${patternRedirects}.map(
+  ([source, location, status]) => [new RegExp(source, "u"), location, status]
+);
 const NOT_FOUND = ${notFound};
 const SVG_ASSET_HEADERS = ${JSON.stringify(SVG_ASSET_HEADERS)};
 
@@ -343,11 +345,31 @@ const isSvgAsset = (pathname) => {
 // reads — a worker-first route never reaches it. Answering from this baked-in
 // copy keeps the exact configured status; delegating instead would let Astro's
 // SSR handler default a GET to a permanent 301.
+// An exact path is looked up first, then each pattern is tried in order, its
+// Location template filled with the captures, encoded so a capture can't grow
+// a query or fragment.
 const redirectFor = (pathname) => {
   const trimmed =
     pathname !== "/" && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
   const path = safeDecode(trimmed);
-  return Object.hasOwn(REDIRECTS, path) ? REDIRECTS[path] : null;
+  if (Object.hasOwn(REDIRECTS, path)) {
+    return REDIRECTS[path];
+  }
+  const decoded = safeDecode(pathname);
+  for (const [pattern, location, status] of PATTERN_REDIRECTS) {
+    const match = pattern.exec(decoded);
+    if (match) {
+      return [
+        location.replace(/\\$(\\d+)/gu, (_reference, index) =>
+          encodeURI(match[Number(index)] ?? "")
+            .replaceAll("?", "%3F")
+            .replaceAll("#", "%23")
+        ),
+        status,
+      ];
+    }
+  }
+  return null;
 };
 
 // The request path with the deployment base removed: the whole path on a
@@ -680,7 +702,7 @@ export const injectWorkerNegotiation = (
   // The content-route guard compares against redirect `from`s, which carry the
   // full `{deployment.base}{basePath}` stack; the routes carry only
   // `basePath`, so the deployment base is applied here.
-  const deployPrefix = basePrefix(options.base);
+  const deployPrefix = normalizeBasePath(options.base);
   const guardRoutes = new Set(
     contentRoutePaths.map((route) =>
       normalizePath(

package/src/deploy/headers.ts

@@ -4,6 +4,7 @@ import {
   API_CATALOG_TYPE,
   hasApiCatalog,
 } from "../ai/api-catalog.ts";
+import { servesSkillsIndex } from "../ai/skills.ts";
 import {
   SIGNATURES_DIRECTORY_PATH,
   SIGNATURES_DIRECTORY_TYPE,
@@ -128,7 +129,7 @@ export const headerRules = (
   }
   // Published skills live at the deployment base, and the RFC wants their
   // archives served as application/gzip explicitly.
-  if (config.agents.skills) {
+  if (servesSkillsIndex(config)) {
     rules.push(
       {
         name: "Content-Type",
@@ -200,6 +201,13 @@ export interface VercelHeader {
 /** The characters `path-to-regexp` would read as syntax in a literal path. */
 const SOURCE_SYNTAX = /[\\(){}?+:]/gu;
 
+/**
+ * A literal path as `path-to-regexp` source text — what a `vercel.json`
+ * `source` is — with each syntax character escaped, so it matches only itself.
+ */
+export const escapeVercelSource = (path: string): string =>
+  path.replaceAll(SOURCE_SYNTAX, String.raw`\$&`);
+
 /**
  * A `_headers` path as a `vercel.json` `source`, which `path-to-regexp` reads:
  * the literal parts are escaped, and a `*` glob becomes the `(.*)` group that
@@ -209,10 +217,7 @@ const SOURCE_SYNTAX = /[\\(){}?+:]/gu;
 const vercelSource = (path: string): string => {
   const trimmed =
     path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
-  return trimmed
-    .split("*")
-    .map((part) => part.replaceAll(SOURCE_SYNTAX, String.raw`\$&`))
-    .join("(.*)");
+  return trimmed.split("*").map(escapeVercelSource).join("(.*)");
 };
 
 /**

package/src/deploy/node-headers.ts

@@ -15,6 +15,8 @@ import {
 } from "../ai/web-bot-auth.ts";
 import { normalizeBasePath, normalizePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { compileRedirects, isPatternPath } from "../core/redirect-patterns.ts";
+import type { CompiledRedirect } from "../core/redirect-patterns.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { SVG_ASSET_HEADERS, svgAssetPath } from "./headers.ts";
 import { distDir } from "./platforms/paths.ts";
@@ -106,11 +108,12 @@ const patternRules = (
 export type NodeRedirects = Record<string, [string, number]>;
 
 /**
- * The configured redirects, based the way the host matches them (see
+ * The configured exact redirects, based the way the host matches them (see
  * `platformRedirects`) and keyed for the wrapper's lookup, the `Location`
  * percent-encoded as Astro sends it. A redirect at a content route's own path
  * is left out: the prerendered page owns that URL, and the static handler
- * serves it before Astro's redirect ever could.
+ * serves it before Astro's redirect ever could. Patterns are compiled apart
+ * ({@link nodePatternRedirects}).
  */
 export const nodeRedirects = (project: BlumeProject): NodeRedirects => {
   const { config } = project;
@@ -124,8 +127,14 @@ export const nodeRedirects = (project: BlumeProject): NodeRedirects => {
     )
   );
   return Object.fromEntries(
-    platformRedirects(config)
-      .filter((redirect) => !pages.has(normalizePath(redirect.from)))
+    platformRedirects(project)
+      .filter(
+        (redirect) =>
+          !(
+            isPatternPath(redirect.from) ||
+            pages.has(normalizePath(redirect.from))
+          )
+      )
       .map((redirect) => [
         normalizePath(redirect.from),
         [encodeURI(redirect.to), redirect.status],
@@ -133,12 +142,27 @@ export const nodeRedirects = (project: BlumeProject): NodeRedirects => {
   );
 };
 
+/**
+ * The configured pattern redirects (`/beta/:slug*`), based the way the host
+ * matches them and compiled for the wrapper, which tries them in order after
+ * the exact ones. None can match a page: the scan rejects a pattern that
+ * does (`BLUME_REDIRECT_MATCHES_PAGE`).
+ */
+export const nodePatternRedirects = (
+  project: BlumeProject
+): CompiledRedirect[] =>
+  project.config.redirects.length === 0
+    ? []
+    : compileRedirects(platformRedirects(project));
+
 /** What the wrapper needs beyond the header rules. */
 export interface NodeEntryOptions {
   /** `deployment.base`, normalized (`""` at the root). */
   base?: string;
   /** The configured redirects, from {@link nodeRedirects}. */
   redirects?: NodeRedirects;
+  /** The configured pattern redirects, from {@link nodePatternRedirects}. */
+  patternRedirects?: CompiledRedirect[];
 }
 
 /**
@@ -177,6 +201,9 @@ const BASE = ${JSON.stringify(options.base ?? "")};
 const RULES = new Map(${JSON.stringify(exactRules(rules))});
 const PATTERNS = ${JSON.stringify(patternRules(rules))};
 const REDIRECTS = ${JSON.stringify(options.redirects ?? {})};
+const PATTERN_REDIRECTS = ${JSON.stringify(options.patternRedirects ?? [])}.map(
+  ([source, location, status]) => [new RegExp(source, "u"), location, status]
+);
 const safeDecode = (path) => {
   try {
     return decodeURIComponent(path);
@@ -210,16 +237,37 @@ const applyHeaders = (req, res) => {
     }
   }
 };
+// A pattern redirect's Location: its template, each $n filled with that
+// capture, encoded so it can't grow a query or fragment.
+const fillLocation = (location, match) =>
+  location.replace(/\\$(\\d+)/gu, (_reference, index) =>
+    encodeURI(match[Number(index)] ?? "")
+      .replaceAll("?", "%3F")
+      .replaceAll("#", "%23")
+  );
+// The configured redirect for a decoded path: an exact one, else the first
+// pattern that matches it.
+const redirectFor = (path) => {
+  const trimmed = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  if (Object.hasOwn(REDIRECTS, trimmed)) {
+    return REDIRECTS[trimmed];
+  }
+  for (const [pattern, location, status] of PATTERN_REDIRECTS) {
+    const match = pattern.exec(path);
+    if (match) {
+      return [fillLocation(location, match), status];
+    }
+  }
+  return null;
+};
 // Answer a configured redirect with its exact status; Astro's handler would
 // send a 301 (a 308 for other methods) whatever the configured one.
 const answerRedirect = (req, res) => {
-  const path = urlPath(req);
-  const trimmed = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
-  const key = safeDecode(trimmed);
-  if (!Object.hasOwn(REDIRECTS, key)) {
+  const redirect = redirectFor(safeDecode(urlPath(req)));
+  if (redirect === null) {
     return false;
   }
-  const [location, status] = REDIRECTS[key];
+  const [location, status] = redirect;
   res.writeHead(status, { location });
   res.end();
   return true;
@@ -291,7 +339,12 @@ export const wrapNodeEntry = async (
       : []),
   ];
   const redirects = nodeRedirects(project);
-  if (rules.length === 0 && Object.keys(redirects).length === 0) {
+  const patternRedirects = nodePatternRedirects(project);
+  if (
+    rules.length === 0 &&
+    Object.keys(redirects).length === 0 &&
+    patternRedirects.length === 0
+  ) {
     return;
   }
   const serverDir = join(distDir(project.context), "server");
@@ -311,6 +364,7 @@ export const wrapNodeEntry = async (
     entry,
     nodeEntryWrapper(rules, {
       base: normalizeBasePath(project.config.deployment.options.base),
+      patternRedirects,
       redirects,
     }),
     "utf-8"