blume 2.1.0 → 2.1.2

package/src/deploy/platforms/vercel.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 
-import { join } from "pathe";
+import { dirname, join } from "pathe";
 
 import { crossOriginDiscoveryPaths } from "../../ai/ai-catalog.ts";
 import {
@@ -20,7 +20,10 @@ import {
   SIGNATURES_DIRECTORY_PATH,
   SIGNATURES_DIRECTORY_TYPE,
 } from "../../ai/web-bot-auth.ts";
+import { mountBasePath, normalizeBasePath } from "../../core/base-path.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
+import { isPatternPath, regexRedirect } from "../../core/redirect-patterns.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
 import type { ProjectContext } from "../../core/types.ts";
 import { VERCEL_ADAPTER_PACKAGE } from "../adapters/vercel.ts";
 import {
@@ -37,7 +40,9 @@ import {
 import {
   injectNegotiationRoutes,
   injectRedirectRoutes,
+  rebaseAdapterRoutes,
 } from "../vercel-negotiation.ts";
+import type { VercelRoute } from "../vercel-negotiation.ts";
 import { adapterRoot, toSiteUrl } from "./paths.ts";
 import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
 
@@ -56,6 +61,14 @@ export const VERCEL_JSON_FILE: RedirectFile = {
 const buildOutputDir = (context: ProjectContext): string =>
   join(adapterRoot(context), ".vercel", "output");
 
+/** The static files a server build serves, under the base's directory. */
+const staticDir = (context: ProjectContext, base: string): string =>
+  join(buildOutputDir(context), "static", base);
+
+/** The project's normalized `deployment.base`, `""` for none. */
+const deploymentBase = (project: BlumeProject): string =>
+  normalizeBasePath(project.config.deployment.options.base);
+
 /**
  * Refuse to ship a function bundle that would crash at runtime: a bare import
  * the adapter's dependency trace silently dropped (see
@@ -99,18 +112,21 @@ export const emitVercelNegotiation = async (
   log: BuildLog
 ): Promise<void> => {
   const { config, context } = project;
-  const outputDir = buildOutputDir(context);
-  const configPath = join(outputDir, "config.json");
+  const configPath = join(buildOutputDir(context), "config.json");
   if (!existsSync(configPath)) {
     return;
   }
+  const base = deploymentBase(project);
   const routePaths = markdownRoutePaths(project);
+  // Keyed by the file's path in `static/`, under the base's directory.
   const overrides: Record<string, string> = {};
   if (hasApiCatalog(config)) {
-    overrides[API_CATALOG_PATH.slice(1)] = API_CATALOG_TYPE;
+    overrides[mountBasePath(base, API_CATALOG_PATH).slice(1)] =
+      API_CATALOG_TYPE;
   }
   if (config.agents.webBotAuth.keys.length > 0) {
-    overrides[SIGNATURES_DIRECTORY_PATH.slice(1)] = SIGNATURES_DIRECTORY_TYPE;
+    overrides[mountBasePath(base, SIGNATURES_DIRECTORY_PATH).slice(1)] =
+      SIGNATURES_DIRECTORY_TYPE;
   }
   // The homepage rewrite serves `/index.md` from the static layer, so its
   // `x-markdown-tokens` estimate has to ride the routing config; the runtime
@@ -120,7 +136,7 @@ export const emitVercelNegotiation = async (
   // The Markdown and JSON 404 routes point at the prerendered twins; only
   // wire each when the build actually emitted it (a project that owns `/404`
   // gets none).
-  const staticDir = join(outputDir, "static");
+  const builtDir = staticDir(context, base);
   const injected = injectNegotiationRoutes(
     await readFile(configPath, "utf-8"),
     routePaths,
@@ -128,13 +144,15 @@ export const emitVercelNegotiation = async (
     overrides,
     home ? markdownTokenCount(agentMarkdown(home)) : undefined,
     {
-      json: existsSync(join(staticDir, "404.json")),
-      markdown: existsSync(join(staticDir, "404.md")),
+      json: existsSync(join(builtDir, "404.json")),
+      markdown: existsSync(join(builtDir, "404.md")),
     },
     crossOriginDiscoveryPaths(config),
     // Downloaded content assets are prerendered static files; only a build
     // that has them needs the SVG sandbox route.
-    existsSync(join(staticDir, "blume-assets"))
+    existsSync(join(builtDir, "blume-assets")),
+    base,
+    config.poweredBy
   );
   if (injected === null) {
     log.warn(
@@ -175,6 +193,76 @@ export const emitVercelPatternRedirects = async (
   await writeFile(configPath, injected, "utf-8");
 };
 
+type Redirect = ResolvedConfig["redirects"][number];
+
+/**
+ * The exact redirects as Build Output routes, matched the way the pattern ones
+ * are (see `regexRedirect`): the served path, a trailing slash optional.
+ */
+const exactRedirectRoutes = (redirects: Redirect[]): VercelRoute[] =>
+  redirects
+    .filter((redirect) => !isPatternPath(redirect.from))
+    .map(({ from, status, to }) => ({
+      headers: { Location: encodeURI(to) },
+      src: regexRedirect({ parts: [{ kind: "text", text: from }], status, to })
+        .source,
+      status,
+    }));
+
+/**
+ * Move a server build's static files under `deployment.base`.
+ * `@astrojs/vercel` copies them to the root of the Build Output tree's
+ * `static/`, while the pages request `<base>/_astro/…` and link to
+ * `<base>/…`, so nothing the site asks for would be found. Moved to
+ * `static/<base>/`, they're served at the base, as the routes that
+ * {@link rebaseVercelRoutes} moves there expect.
+ */
+export const moveStaticUnderBase = async (
+  context: ProjectContext,
+  base: string
+): Promise<void> => {
+  const root = staticDir(context, "");
+  if (!base || !existsSync(root)) {
+    return;
+  }
+  // Through a sibling, since the target lies inside the directory it moves.
+  const staging = join(buildOutputDir(context), "static-unbased");
+  await rename(root, staging);
+  const target = staticDir(context, base);
+  await mkdir(dirname(target), { recursive: true });
+  await rename(staging, target);
+};
+
+/**
+ * Move the adapter's routing config under `deployment.base` to match the
+ * static files (see `rebaseAdapterRoutes`), its exact redirects rebuilt from
+ * the configured ones. Resolves to false when the config can't be read: the
+ * adapter's routes would then miss every path under the base.
+ */
+export const rebaseVercelRoutes = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<boolean> => {
+  const base = deploymentBase(project);
+  const configPath = join(buildOutputDir(project.context), "config.json");
+  if (!base || !existsSync(configPath)) {
+    return true;
+  }
+  const rebased = rebaseAdapterRoutes(
+    await readFile(configPath, "utf-8"),
+    base,
+    exactRedirectRoutes(platformRedirects(project))
+  );
+  if (rebased === null) {
+    log.error(
+      `Could not move the routes in .vercel/output/config.json under the deployment base "${base}", so the site would not be served there.`
+    );
+    return false;
+  }
+  await writeFile(configPath, rebased, "utf-8");
+  return true;
+};
+
 /**
  * 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
@@ -182,12 +270,15 @@ export const emitVercelPatternRedirects = async (
  * hidden runtime silently drops the function's chunks and `node_modules`.
  * Static assets are served from the tree's `static/` half, so the deploy
  * artifacts are written there; headers (the discovery files', the sandbox on
- * downloaded SVGs) arrive through the routing config rather than a
- * `_headers` file, which Vercel never reads.
+ * downloaded SVGs, `X-Powered-By`) arrive through the routing config rather
+ * than a `_headers` file, which Vercel never reads. The adapter ignores
+ * `deployment.base`, so under one the build moves the static files and the
+ * routes beneath it.
  */
 export const vercelPlatform: DeployPlatform = {
   astro: {
-    config: {},
+    config: () => ({}),
+    configOptions: [],
     options: () => ({}),
     package: VERCEL_ADAPTER_PACKAGE,
   },
@@ -210,12 +301,19 @@ export const vercelPlatform: DeployPlatform = {
     if (!ok) {
       return false;
     }
+    // A verify build moves its static files too, where the budget gate reads
+    // them (`serverStaticDir`).
+    await moveStaticUnderBase(context, deploymentBase(project));
     // An isolated verify only proves the bundle would ship; the routing
     // config is a deploy artifact and stays untouched.
-    if (!isolated) {
-      await emitVercelNegotiation(project, log);
-      await emitVercelPatternRedirects(project, log);
+    if (isolated) {
+      return true;
+    }
+    if (!(await rebaseVercelRoutes(project, log))) {
+      return false;
     }
+    await emitVercelNegotiation(project, log);
+    await emitVercelPatternRedirects(project, log);
     return true;
   },
   hiddenRuntime: {
@@ -231,5 +329,5 @@ export const vercelPlatform: DeployPlatform = {
   redirectFiles: [VERCEL_JSON_FILE],
   serverClientUnderBase: false,
   serverOutputDir: buildOutputDir,
-  serverStaticDir: (context) => join(buildOutputDir(context), "static"),
+  serverStaticDir: staticDir,
 };

package/src/deploy/redirects.ts

@@ -1,5 +1,7 @@
 import {
   normalizeBasePath,
+  normalizePath,
+  stripBasePath,
   withAuthoredBasePath,
   withBasePath,
   withComposedBasePath,
@@ -11,6 +13,7 @@ import {
   compileRedirects,
   exactFirst,
   expandRedirect,
+  isPatternPath,
   underscoreRedirect,
   vercelRedirect,
 } from "../core/redirect-patterns.ts";
@@ -109,9 +112,60 @@ export const applyBaseToPlatformRedirects = (
     : redirects;
 };
 
+/**
+ * The raw-Markdown copies Blume serves beside every page (`/guide.md`,
+ * `/guide.mdx`; see `rawMarkdownEndpointTemplate`).
+ */
+const MIRROR_EXTENSIONS = [".md", ".mdx"] as const;
+
+/**
+ * Where a page's Markdown copy is served, from the page's served path and the
+ * deployment base that path carries: the endpoints name the root `index`.
+ */
+const mirrorPath = (path: string, base: string, extension: string): string => {
+  const route = stripBasePath(base, path);
+  return `${base}${route === "/" ? "/index" : route}${extension}`;
+};
+
+/**
+ * Based `redirects`, each exact one that moves a page followed by the same
+ * redirect for the page's Markdown copies: from a path no page is served at
+ * to one a page is, `/old.md` goes to `/new.md` (and `.mdx` alike), where it
+ * would otherwise 404 for an agent still reading the old URL. A pattern gets
+ * none; one that carries its capture over (`/beta/:slug*` → `/v2/:slug*`)
+ * already moves `/beta/guide.md` along. `pages` are the served page routes
+ * (carrying `basePath`, not `deployment.base`), and `bases` the deployment
+ * base each end carries: Astro's config leaves it off `from` (see
+ * {@link applyBaseToAstroRedirects}).
+ */
+export const withMirrorRedirects = (
+  redirects: Redirect[],
+  pages: RouteSet,
+  bases: { from: string; to: string }
+): Redirect[] =>
+  redirects.flatMap((redirect) => {
+    const from = normalizePath(redirect.from);
+    const to = normalizePath(redirect.to);
+    const movesPage =
+      !isPatternPath(redirect.from) &&
+      servesRoute(pages, stripBasePath(bases.to, to)) &&
+      !servesRoute(pages, stripBasePath(bases.from, from));
+    return movesPage
+      ? [
+          redirect,
+          ...MIRROR_EXTENSIONS.map((extension) => ({
+            from: mirrorPath(from, bases.from, extension),
+            status: redirect.status,
+            to: mirrorPath(to, bases.to, extension),
+          })),
+        ]
+      : [redirect];
+  });
+
 /**
  * The configured redirects as the host platform matches them, via
- * {@link applyBaseToPlatformRedirects}, exact paths ahead of patterns: hosts
+ * {@link applyBaseToPlatformRedirects} plus the Markdown copies of each moved
+ * page ({@link withMirrorRedirects}), 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
@@ -122,12 +176,18 @@ export const platformRedirects = (project: {
   manifest: Pick<BlumeProject["manifest"], "routes">;
 }): Redirect[] => {
   const { config } = project;
+  const base = normalizeBasePath(config.deployment.options.base);
+  const pages = routeSetFor(project.manifest.routes);
   return exactFirst(
-    applyBaseToPlatformRedirects(
-      config.redirects,
-      config.basePath,
-      config.deployment.options.base ?? "",
-      routeSetFor(project.manifest.routes)
+    withMirrorRedirects(
+      applyBaseToPlatformRedirects(
+        config.redirects,
+        config.basePath,
+        base,
+        pages
+      ),
+      pages,
+      { from: base, to: base }
     )
   );
 };

package/src/deploy/rss.ts

@@ -78,7 +78,9 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
     const items: RssItem[] = pages
       .map((page) => ({
         date: pageDate(page),
-        description: page.description,
+        // A page with only a meta description (a GitHub release, whose
+        // summary goes in `seo.description`) still describes its item.
+        description: page.description ?? page.meta.seo.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}${mountBasePath(deployBase, page.route)}`),

package/src/deploy/sitemap.ts

@@ -6,7 +6,11 @@ import {
   discoverPagesSync,
   hasGeneratedChangelog,
 } from "../astro/pages.ts";
-import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
+import {
+  mountBasePath,
+  normalizeBasePath,
+  normalizePath,
+} from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { siteRoot } from "../core/site-url.ts";
 
@@ -30,6 +34,30 @@ const lastmodTag = (value: string | undefined): string => {
     : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
 };
 
+/**
+ * Whether a page's own `seo.canonical` names another URL. The sitemap lists
+ * canonical URLs only, so such a page stays out — `blume audit` reports a
+ * listed one as NON_CANONICAL_IN_SITEMAP and expects it unlisted. Compared by
+ * decoded path, as the audit does: `served` is the page's path with the
+ * deployment base mounted, which the canonical carries too.
+ */
+const canonicalElsewhere = (
+  canonical: string | undefined,
+  served: string
+): boolean => {
+  if (!canonical) {
+    return false;
+  }
+  const { pathname } = new URL(canonical);
+  let path = pathname;
+  try {
+    path = decodeURI(pathname);
+  } catch {
+    // A malformed escape stays as written; it can't match the served path.
+  }
+  return normalizePath(path) !== normalizePath(served);
+};
+
 /** One emitted sitemap artifact: its dist-root filename and XML body. */
 export interface SitemapFile {
   name: string;
@@ -62,7 +90,8 @@ ${urls.join("\n")}
  * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
  * the generated `/changelog` index. Returns null when the sitemap is disabled
  * or no `site` is configured (absolute URLs are required for a valid sitemap).
- * Drafts, hidden, and `noindex` pages are excluded.
+ * Drafts, hidden, and `noindex` pages are excluded, and so is a page whose
+ * `seo.canonical` points elsewhere.
  *
  * Sites within the per-file URL cap get the single classic `sitemap.xml`;
  * larger sites get `sitemap.xml` as a sitemap index over numbered
@@ -87,7 +116,9 @@ export const buildSitemapFiles = (
   // or when their canonical points at a still-existing latest equivalent —
   // listing a URL whose canonical says "index the other page" invites the
   // noindexed-page-in-sitemap incoherence Docusaurus is known for. A page
-  // that exists only in an archived version stays listed (self-canonical).
+  // that exists only in an archived version stays listed (self-canonical),
+  // and a page's own `seo.canonical` wins over the version's default, as it
+  // does in the page head (see `canonicalElsewhere`).
   const { versions } = project.config;
   const archivedById = new Map(
     (versions?.archived ?? []).map((version) => [version.id, version])
@@ -109,6 +140,7 @@ export const buildSitemapFiles = (
     return Boolean(
       archived?.noindex ||
       (archived?.canonical === "latest" &&
+        !page.meta.seo.canonical &&
         currentKeys?.has(`${page.versionKey}\u0000${page.locale}`))
     );
   };
@@ -128,16 +160,18 @@ export const buildSitemapFiles = (
     urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
   };
   for (const page of project.graph.pages) {
+    const served = mountBasePath(deployBase, page.route);
     if (
       page.meta.draft ||
       page.meta.sidebar.hidden ||
       page.meta.seo.noindex ||
       ERROR_ROUTES.has(page.route) ||
-      archivedExcluded(page)
+      archivedExcluded(page) ||
+      canonicalElsewhere(page.meta.seo.canonical, served)
     ) {
       continue;
     }
-    pushUrl(mountBasePath(deployBase, page.route), page.lastModified);
+    pushUrl(served, page.lastModified);
   }
   // Custom `.astro` pages and the generated changelog index mount outside
   // `basePath` (they're injected at their pattern — see `blumeIntegration`), so