blume 2.0.2 → 2.0.3

package/src/deploy/headers.ts

@@ -200,6 +200,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 +216,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

@@ -124,7 +124,7 @@ export const nodeRedirects = (project: BlumeProject): NodeRedirects => {
     )
   );
   return Object.fromEntries(
-    platformRedirects(config)
+    platformRedirects(project)
       .filter((redirect) => !pages.has(normalizePath(redirect.from)))
       .map((redirect) => [
         normalizePath(redirect.from),

package/src/deploy/platforms/cloudflare.ts

@@ -11,6 +11,7 @@ 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 { CLOUDFLARE_ADAPTER_PACKAGE } from "../adapters/cloudflare.ts";
@@ -90,8 +91,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 +125,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,
     }
   );
@@ -308,6 +314,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

@@ -124,6 +124,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

@@ -194,6 +194,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,9 +1,14 @@
 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 type { ResolvedConfig } from "../core/schema.ts";
+import { escapeVercelSource } from "./headers.ts";
 import type { VercelHeader } from "./headers.ts";
 
 /**
@@ -16,6 +21,23 @@ import type { VercelHeader } from "./headers.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 +45,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,27 +70,29 @@ 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;
 };
@@ -75,12 +103,18 @@ export const applyBaseToPlatformRedirects = (
  * share: the emitted redirect files and the Cloudflare worker-first redirect
  * exemptions both compare these paths against real served URLs.
  */
-export const platformRedirects = (config: ResolvedConfig): Redirect[] =>
-  applyBaseToPlatformRedirects(
+export const platformRedirects = (project: {
+  config: ResolvedConfig;
+  manifest: Pick<BlumeProject["manifest"], "routes">;
+}): Redirect[] => {
+  const { config } = project;
+  return applyBaseToPlatformRedirects(
     config.redirects,
     config.basePath,
-    config.deployment.options.base ?? ""
+    config.deployment.options.base ?? "",
+    routeSetFor(project.manifest.routes)
   );
+};
 
 /**
  * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line.
@@ -110,7 +144,9 @@ 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 exact `from` path is escaped: unescaped,
+ * `/c++-guide` fails the whole config and `/faq(old)` never matches.
  */
 export const buildVercelConfig = (
   redirects: Redirect[],
@@ -119,7 +155,7 @@ export const buildVercelConfig = (
   const config: VercelConfig = {
     redirects: redirects.map((redirect) => ({
       destination: redirect.to,
-      source: redirect.from,
+      source: escapeVercelSource(redirect.from),
       statusCode: redirect.status,
     })),
   };

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/markdown/base-links.ts

@@ -1,7 +1,7 @@
 import {
   isInternalPath,
+  withAuthoredBasePath,
   withBasePath,
-  withComposedBasePath,
 } from "../core/base-path.ts";
 import { servesRoute } from "../core/locale-links.ts";
 import type { MdastNode } from "./mdast.ts";
@@ -20,18 +20,6 @@ interface MdastUrlContext {
   setProperty: (node: MdastNode, key: "url", value: string) => void;
 }
 
-/**
- * A path whose final segment carries a file extension (`/spec.pdf`, `/logo.svg`)
- * — a public asset, which Blume serves from `public/` at the site root and
- * does *not* move under `basePath`, unless a page is served there: a dotted
- * route (`/releases/v1.2`) is based like any other page link, the same
- * served-route test the link checker and the locale rewrite apply.
- */
-const DOTTED_PATH = /\.[a-z0-9]+$/iu;
-
-/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
-const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
-
 /** Only a string URL can be rebased; MDAST allows null or absent urls. */
 const isUrl = (url: string | null | undefined): url is string =>
   typeof url === "string";
@@ -45,13 +33,15 @@ export interface BaseLinksPluginOptions {
 }
 
 /**
- * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
- * layered over the site-wide `basePath` — to root-relative internal page links
- * (`[x](/guide)` -> `/base/docs/guide`), so authors write links as if mounted
- * at root. Idempotent per layer (via `withComposedBasePath`, so a hand-written
- * `/docs/x` isn't double-prefixed) and inert for external URLs, fragments,
- * relative paths, images, and asset links. Only constructed when a base is set
- * (see `markdown/index.ts`).
+ * Satteri MDAST plugin that prepends the served-URL base to root-relative
+ * internal links, so authors write links as if mounted at root. A page link
+ * gains `deployment.base` layered over the site-wide `basePath` (`[x](/guide)`
+ * -> `/base/docs/guide`); a public asset — an image, or a link to a file like
+ * `/spec.pdf` (see `withAuthoredBasePath`) — gains `deployment.base` alone,
+ * since Astro serves `public/` under it but never under `basePath`.
+ * Idempotent per layer (a hand-written `/docs/x` isn't double-prefixed) and
+ * inert for external URLs, fragments, and relative paths. Only constructed
+ * when a base is set (see `markdown/index.ts`).
  */
 export const baseLinksPlugin = (
   deployBase: string,
@@ -78,30 +68,38 @@ export const baseLinksPlugin = (
     return cached.routes;
   };
 
-  /** Whether an internal `url` links a page rather than a public asset. */
-  const isPageLink = (url: string): boolean => {
-    const path = pathOf(url);
-    return (
-      !DOTTED_PATH.test(path) ||
-      servesRoute(servedRoutes(), withBasePath(basePath, path))
-    );
-  };
+  /** Whether a page is served at a based, fragment-less path. */
+  const servesPage = (route: string): boolean =>
+    servesRoute(servedRoutes(), route);
 
-  const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
+  /** Record `based(url)` on the node when its root-relative URL changes. */
+  const rebase = (
+    node: UrlNode,
+    ctx: MdastUrlContext,
+    based: (url: string) => string
+  ): void => {
     const { url } = node;
-    if (isUrl(url) && isInternalPath(url) && isPageLink(url)) {
-      const next = withComposedBasePath(deployBase, basePath, url);
+    if (isUrl(url) && isInternalPath(url)) {
+      const next = based(url);
       if (next !== url) {
         ctx.setProperty(node, "url", next);
       }
     }
   };
-  // `link` covers inline links; `definition` covers reference-style link
-  // definitions (`[x]: /guide`). `image` is intentionally excluded — images are
-  // public assets served at the site root, unaffected by `basePath`.
+  const rebaseLink = (node: UrlNode, ctx: MdastUrlContext): void =>
+    rebase(node, ctx, (url) =>
+      withAuthoredBasePath(deployBase, basePath, url, servesPage)
+    );
+  // An image is always a file, never a page: `public/` (or a generated asset
+  // endpoint), served under the deployment base but not `basePath`.
+  const rebaseImage = (node: UrlNode, ctx: MdastUrlContext): void =>
+    rebase(node, ctx, (url) => withBasePath(deployBase, url));
+  // `link` covers inline links; `definition` covers reference-style
+  // definitions (`[x]: /guide`), which a link or an image may cite.
   return {
-    definition: rebase,
-    link: rebase,
+    definition: rebaseLink,
+    image: rebaseImage,
+    link: rebaseLink,
     name: "blume-base-links",
   };
 };