blume 1.3.1 → 1.4.1

package/src/audit/crawl.ts

@@ -1,5 +1,6 @@
 import { readFile, stat } from "node:fs/promises";
 
+import { XMLParser } from "fast-xml-parser";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -74,27 +75,25 @@ const routeIndex = (
   return index;
 };
 
-const SITEMAP_URL = /<url>(?<block>[\s\S]*?)<\/url>/gu;
-const SITEMAP_LOC = /<loc>(?<loc>[\s\S]*?)<\/loc>/gu;
-const SITEMAP_LASTMOD = /<lastmod>(?<date>[\s\S]*?)<\/lastmod>/u;
-const XML_ENTITIES: Record<string, string> = {
-  "&amp;": "&",
-  "&apos;": "'",
-  "&gt;": ">",
-  "&lt;": "<",
-  "&quot;": '"',
-};
-
-const unescapeXml = (value: string): string =>
-  value.replaceAll(
-    /&(?:amp|apos|gt|lt|quot);/gu,
-    (entity) => XML_ENTITIES[entity] ?? entity
-  );
+/**
+ * Sitemaps arrive from arbitrary generators (the audit also fetches remote
+ * ones), so parsing is fast-xml-parser's job: CDATA sections, numeric
+ * entities, and namespace-prefixed elements are all legal there and all
+ * invisible to a regex scan. Values stay strings (`parseTagValue: false`) so
+ * a numeric-looking `<lastmod>` isn't coerced.
+ */
+const sitemapParser = new XMLParser({
+  // htmlEntities adds numeric character references (&#38;) on top of the
+  // default XML five; a sitemap loc legitimately carries either form.
+  htmlEntities: true,
+  ignoreAttributes: true,
+  parseTagValue: false,
+  removeNSPrefix: true,
+});
 
 /**
- * Parse `sitemap.xml`. Deliberately shallow: we only need the `<loc>` list and
- * whether the document is a well-formed urlset, and pulling in an XML parser to
- * learn that would be a dependency for one regex.
+ * Parse `sitemap.xml`. Deliberately shallow: the checks only need the `<loc>`
+ * list, each loc's `<lastmod>`, and whether the document is a urlset at all.
  */
 export const parseSitemap = (
   file: string,
@@ -102,31 +101,34 @@ export const parseSitemap = (
   bytes: number
 ): SitemapDoc => {
   const doc: SitemapDoc = { bytes, file, lastmod: new Map(), urls: [] };
-  if (!xml.includes("<urlset")) {
-    doc.error = xml.includes("<sitemapindex")
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = sitemapParser.parse(xml) as Record<string, unknown>;
+  } catch {
+    doc.error = "no <urlset> element";
+    return doc;
+  }
+  if (!Object.hasOwn(parsed, "urlset")) {
+    doc.error = Object.hasOwn(parsed, "sitemapindex")
       ? "sitemap is an index, not a urlset"
       : "no <urlset> element";
     return doc;
   }
-  for (const match of xml.matchAll(SITEMAP_LOC)) {
-    const loc = unescapeXml((match.groups?.loc ?? "").trim());
-    if (loc) {
-      doc.urls.push(loc);
+  const urlset = parsed.urlset as { url?: unknown } | string | null;
+  const entries =
+    typeof urlset === "object" && urlset !== null ? [urlset.url].flat() : [];
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null) {
+      continue;
     }
-  }
-  // `<lastmod>` is scoped per `<url>` block so it stays attached to its `<loc>`
-  // — the flat loc scan above deliberately isn't, so a sitemap with stray text
-  // between blocks still yields its URL list.
-  for (const match of xml.matchAll(SITEMAP_URL)) {
-    const block = match.groups?.block ?? "";
-    const loc = unescapeXml(
-      (
-        new RegExp(SITEMAP_LOC.source, "u").exec(block)?.groups?.loc ?? ""
-      ).trim()
-    );
-    const lastmod = SITEMAP_LASTMOD.exec(block)?.groups?.date?.trim();
-    if (loc && lastmod) {
-      doc.lastmod?.set(loc, lastmod);
+    const { loc, lastmod } = entry as { loc?: unknown; lastmod?: unknown };
+    const locText = typeof loc === "string" ? loc.trim() : "";
+    if (!locText) {
+      continue;
+    }
+    doc.urls.push(locText);
+    if (typeof lastmod === "string" && lastmod.trim() !== "") {
+      doc.lastmod?.set(locText, lastmod.trim());
     }
   }
   return doc;
@@ -153,12 +155,14 @@ export const parseLlms = (file: string, text: string): LlmsDoc => {
 
 const ROBOTS_DIRECTIVE = /^(?<field>[a-z-]+)\s*:\s*(?<value>.*)$/iu;
 
-/** Parse `robots.txt` into the directives the audit cares about. */
+/**
+ * Parse `robots.txt` into the pieces the audit cares about. Sitemap
+ * declarations and a not-a-directive lint come from a line scan; rule
+ * *matching* is robots-parser's job at check time (see `checks/robots.ts`),
+ * so the raw text rides along instead of a pre-extracted rule list.
+ */
 export const parseRobots = (file: string, text: string): RobotsDoc => {
-  const doc: RobotsDoc = { disallow: [], file, invalid: [], sitemaps: [] };
-  // Only `User-agent: *` rules bind the crawlers we're auditing for; a block
-  // scoped to some other agent isn't a finding about our indexable pages.
-  let appliesToAll = false;
+  const doc: RobotsDoc = { file, invalid: [], raw: text, sitemaps: [] };
   for (const [index, raw] of text.split(/\r?\n/u).entries()) {
     const line = raw.trim();
     if (line === "" || line.startsWith("#")) {
@@ -171,11 +175,7 @@ export const parseRobots = (file: string, text: string): RobotsDoc => {
     }
     const field = (match.groups?.field ?? "").toLowerCase();
     const value = (match.groups?.value ?? "").trim();
-    if (field === "user-agent") {
-      appliesToAll = value === "*";
-    } else if (field === "disallow" && appliesToAll && value) {
-      doc.disallow.push(value);
-    } else if (field === "sitemap" && value) {
+    if (field === "sitemap" && value) {
       doc.sitemaps.push(value);
     }
   }

package/src/audit/image-size.ts

@@ -1,63 +1,23 @@
+import { imageSize as measureImage } from "image-size";
+
 /**
- * Pixel dimensions read straight from a PNG, JPEG, or GIF header. A dedicated
- * image library would be a dependency for three well-documented byte layouts;
- * anything else (SVG, WebP, AVIF) yields null and its checks simply don't run.
+ * Pixel dimensions read from an image header via the image-size package,
+ * which covers the formats a modern pipeline actually emits — WebP and AVIF
+ * included, where the previous hand parser (PNG/JPEG/GIF only) went silent
+ * and the dimension checks never ran. An unrecognized or truncated buffer
+ * yields null and its checks simply don't run.
  */
 export interface ImageSize {
   width: number;
   height: number;
 }
 
-const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
-
-const pngSize = (bytes: Buffer): ImageSize | null => {
-  // Signature, then the IHDR chunk is required to come first: width and height
-  // are big-endian u32s at fixed offsets 16 and 20.
-  if (bytes.length < 24 || !bytes.subarray(0, 4).equals(PNG_SIGNATURE)) {
-    return null;
-  }
-  return { height: bytes.readUInt32BE(20), width: bytes.readUInt32BE(16) };
-};
-
-/** JPEG start-of-frame markers (C0–CF minus DHT C4, JPG C8, DAC CC). */
-const isSof = (marker: number): boolean =>
-  marker >= 0xc0 &&
-  marker <= 0xcf &&
-  marker !== 0xc4 &&
-  marker !== 0xc8 &&
-  marker !== 0xcc;
-
-const jpegSize = (bytes: Buffer): ImageSize | null => {
-  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) {
-    return null;
-  }
-  // Walk the segment list: each is FF <marker> <u16 length> <payload>. The
-  // dimensions live in the first start-of-frame segment's payload, as
-  // big-endian u16s after a one-byte precision field.
-  let offset = 2;
-  while (offset + 9 < bytes.length) {
-    if (bytes[offset] !== 0xff) {
-      return null;
-    }
-    const marker = bytes[offset + 1] ?? 0;
-    if (isSof(marker)) {
-      return {
-        height: bytes.readUInt16BE(offset + 5),
-        width: bytes.readUInt16BE(offset + 7),
-      };
-    }
-    offset += 2 + bytes.readUInt16BE(offset + 2);
-  }
-  return null;
-};
-
-const gifSize = (bytes: Buffer): ImageSize | null => {
-  if (bytes.length < 10 || bytes.subarray(0, 4).toString("latin1") !== "GIF8") {
+/** The image's pixel dimensions, or null when the format isn't recognized. */
+export const imageSize = (bytes: Buffer): ImageSize | null => {
+  try {
+    const { width, height } = measureImage(bytes);
+    return width > 0 && height > 0 ? { height, width } : null;
+  } catch {
     return null;
   }
-  return { height: bytes.readUInt16LE(8), width: bytes.readUInt16LE(6) };
 };
-
-/** The image's pixel dimensions, or null when the format isn't recognized. */
-export const imageSize = (bytes: Buffer): ImageSize | null =>
-  pngSize(bytes) ?? jpegSize(bytes) ?? gifSize(bytes);

package/src/audit/report.ts

@@ -1,3 +1,5 @@
+import { colors } from "consola/utils";
+import type { ColorFunction } from "consola/utils";
 import { relative } from "pathe";
 
 import { countBySeverity } from "../core/diagnostics.ts";
@@ -7,21 +9,10 @@ import type { CheckId } from "./catalog.ts";
 import type { AuditResult } from "./run.ts";
 import type { AuditCategory, AuditTier } from "./types.ts";
 
-const ESC = String.fromCodePoint(27);
-const COLORS = {
-  bold: `${ESC}[1m`,
-  cyan: `${ESC}[36m`,
-  dim: `${ESC}[2m`,
-  green: `${ESC}[32m`,
-  red: `${ESC}[31m`,
-  reset: `${ESC}[0m`,
-  yellow: `${ESC}[33m`,
-};
-
-const SEVERITY_COLOR: Record<DiagnosticSeverity, string> = {
-  error: COLORS.red,
-  info: `${ESC}[34m`,
-  warning: COLORS.yellow,
+const SEVERITY_COLOR: Record<DiagnosticSeverity, ColorFunction> = {
+  error: colors.red,
+  info: colors.blue,
+  warning: colors.yellow,
 };
 
 const GLYPH: Record<DiagnosticSeverity, string> = {
@@ -108,7 +99,7 @@ const skippedTiers = (tiers: Record<AuditTier, boolean>): string[] =>
     .filter((tier) => !tiers[tier])
     .map((tier) => {
       const label = CHECKS.filter((check) => check.tier === tier).length;
-      return `  ${COLORS.dim}⊘ ${tier.padEnd(12)} skipped — pass ${TIER_FLAG[tier]} (${label} checks)${COLORS.reset}`;
+      return `  ${colors.dim(`⊘ ${tier.padEnd(12)} skipped — pass ${TIER_FLAG[tier]} (${label} checks)`)}`;
     });
 
 /** How many checks actually ran, i.e. those whose tier was enabled. */
@@ -138,9 +129,11 @@ const summaryLine = (
 const findingLine = (diagnostic: Diagnostic, root: string): string => {
   const url = diagnostic.url ?? "";
   const source = diagnostic.file
-    ? `${COLORS.dim}${relative(root, diagnostic.file)}${
-        diagnostic.line === undefined ? "" : `:${diagnostic.line}`
-      }${COLORS.reset}`
+    ? colors.dim(
+        `${relative(root, diagnostic.file)}${
+          diagnostic.line === undefined ? "" : `:${diagnostic.line}`
+        }`
+      )
     : "";
   // padEnd alone yields no gap once the URL reaches the column width.
   return `      ${url.padEnd(34)} ${source}`.trimEnd();
@@ -164,13 +157,13 @@ export const formatReport = (
     : `${relative(root, result.staticDir) || "dist"} · offline`;
   lines.push(
     "",
-    `  ${COLORS.bold}blume audit${COLORS.reset}  ${COLORS.dim}${result.pages} pages · ${where}${COLORS.reset}`,
+    `  ${colors.bold("blume audit")}  ${colors.dim(`${result.pages} pages · ${where}`)}`,
     `  ${summaryLine(counts, auditCount(result))}`,
     ""
   );
 
   if (groups.length === 0) {
-    lines.push(`  ${COLORS.green}✔ No issues found.${COLORS.reset}`, "");
+    lines.push(`  ${colors.green("✔ No issues found.")}`, "");
   }
 
   let category: AuditCategory | null = null;
@@ -178,13 +171,13 @@ export const formatReport = (
     const { category: next } = group;
     if (next !== category) {
       category = next;
-      lines.push(`  ${COLORS.bold}${category}${COLORS.reset}`, "");
+      lines.push(`  ${colors.bold(category)}`, "");
     }
 
     const color = SEVERITY_COLOR[group.severity];
     const pages = `${group.count} page${group.count === 1 ? "" : "s"}`;
     lines.push(
-      `  ${color}${GLYPH[group.severity]} ${group.title}${COLORS.reset}  ${COLORS.dim}${pages}${COLORS.reset}`
+      `  ${color(`${GLYPH[group.severity]} ${group.title}`)}  ${colors.dim(pages)}`
     );
 
     const shown = options.verbose
@@ -195,14 +188,12 @@ export const formatReport = (
       // The message names the specifics the rolled-up line can't — which target
       // is broken, what the duplicate is — so --verbose prints it per finding.
       if (options.verbose) {
-        lines.push(`        ${COLORS.dim}${diagnostic.message}${COLORS.reset}`);
+        lines.push(`        ${colors.dim(diagnostic.message)}`);
       }
     }
     const hidden = group.count - shown.length;
     if (hidden > 0) {
-      lines.push(
-        `      ${COLORS.dim}… and ${hidden} more (--verbose)${COLORS.reset}`
-      );
+      lines.push(`      ${colors.dim(`… and ${hidden} more (--verbose)`)}`);
     }
 
     // Every finding in a group shares the catalog's fix unless it overrode it,
@@ -210,7 +201,7 @@ export const formatReport = (
     const [first] = group.findings;
     const fix = first?.suggestion;
     if (fix) {
-      lines.push(`      ${COLORS.cyan}fix: ${fix}${COLORS.reset}`);
+      lines.push(`      ${colors.cyan(`fix: ${fix}`)}`);
     }
     lines.push("");
   }
@@ -268,14 +259,12 @@ export const formatCatalog = (): string => {
     const { category: next } = check;
     if (next !== category) {
       category = next;
-      lines.push(`  ${COLORS.bold}${category}${COLORS.reset}`);
+      lines.push(`  ${colors.bold(category)}`);
     }
     const tier =
-      check.tier === "static"
-        ? ""
-        : ` ${COLORS.dim}[${check.tier}]${COLORS.reset}`;
+      check.tier === "static" ? "" : ` ${colors.dim(`[${check.tier}]`)}`;
     lines.push(
-      `    ${SEVERITY_COLOR[check.severity]}${GLYPH[check.severity]}${COLORS.reset} ${check.id.replace("BLUME_AUDIT_", "").toLowerCase().padEnd(34)} ${COLORS.dim}${check.title}${COLORS.reset}${tier}`
+      `    ${SEVERITY_COLOR[check.severity](GLYPH[check.severity])} ${check.id.replace("BLUME_AUDIT_", "").toLowerCase().padEnd(34)} ${colors.dim(check.title)}${tier}`
     );
   }
   lines.push("", `  ${CHECKS.length} checks.`, "");

package/src/audit/types.ts

@@ -135,8 +135,12 @@ export interface LlmsDoc {
 /** A parsed `robots.txt`. */
 export interface RobotsDoc {
   file: string;
-  /** `Disallow:` paths for `User-agent: *`. */
-  disallow: string[];
+  /**
+   * The file's full text. Rule matching runs through robots-parser (which
+   * owns longest-match Allow/Disallow semantics), so the raw text is the
+   * source of truth rather than a pre-extracted rule list.
+   */
+  raw: string;
   /** `Sitemap:` declarations. */
   sitemaps: string[];
   /** Lines that aren't a recognized directive, with their 1-based line number. */

package/src/audit/url.ts

@@ -1,4 +1,8 @@
-import { stripBasePath } from "../core/base-path.ts";
+import { normalizePath, stripBasePath } from "../core/base-path.ts";
+
+// Re-exported from its home next to the other path helpers; the audit checks
+// (and their tests) import it from here.
+export { normalizePath } from "../core/base-path.ts";
 
 /** What an `href` in built HTML turned out to point at. */
 export type ResolvedHref =
@@ -13,15 +17,6 @@ export type ResolvedHref =
 
 const NON_HTTP_SCHEME = /^(?!https?:)[a-z][a-z0-9+.-]*:/iu;
 
-/**
- * Normalize a site path for comparison: drop the trailing slash (Astro serves
- * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
- */
-export const normalizePath = (path: string): string => {
-  const trimmed = path.replace(/\/+$/u, "");
-  return trimmed === "" ? "/" : trimmed;
-};
-
 /**
  * Percent-decode a pathname for comparison against the built file tree. Page
  * URLs and file-index keys come from raw on-disk names, while `URL#pathname`

package/src/cli/commands/build.ts

@@ -38,14 +38,20 @@ import type { ProjectContext } from "../../core/types.ts";
 import {
   ADAPTER_IGNORE_DIRS,
   deployStaticDir,
+  readsHeaderFiles,
+  servesClientSubdir,
   surfaceAdapterOutput,
 } from "../../deploy/adapter-output.ts";
+import {
+  injectWorkerNegotiation,
+  NEGOTIATION_WORKER_FILE,
+} from "../../deploy/cloudflare-negotiation.ts";
 import { buildNetlifyHeaders } from "../../deploy/headers.ts";
 import {
-  applyBaseToPlatformRedirects,
   buildNetlifyRedirects,
   buildRedirectManifest,
   buildVercelConfig,
+  platformRedirects,
 } from "../../deploy/redirects.ts";
 import { buildRobots } from "../../deploy/robots.ts";
 import { buildSitemap } from "../../deploy/sitemap.ts";
@@ -99,11 +105,7 @@ const emitRedirectFiles = async (
   config: ResolvedConfig,
   distDir: string
 ): Promise<void> => {
-  const redirects = applyBaseToPlatformRedirects(
-    config.redirects,
-    config.basePath,
-    config.deployment.base ?? ""
-  );
+  const redirects = platformRedirects(config);
   if (redirects.length === 0 || config.deployment.output !== "static") {
     return;
   }
@@ -127,33 +129,61 @@ const emitRedirectFiles = async (
 };
 
 /**
- * Emit a `_headers` file for a static build so Netlify / Cloudflare static
- * hosts serve the raw AI-ready endpoints (`*.md`, `*.mdx`, `*.txt`) with an
- * explicit `charset=utf-8`. Without it those hosts send `text/markdown` /
- * `text/plain` with no charset and browsers fall back to Windows-1252, garbling
- * any non-ASCII docs (#82). The same file also stamps the homepage
- * agent-discovery `Link` header (RFC 8288, see `ai/link-headers.ts`). A
- * `_headers` shipped in `public/` (copied into dist by Astro before this runs)
- * wins, exactly like `_redirects`. Server adapters set the Content-Type on the
- * Response directly, so this is static-only.
+ * Emit a `_headers` file so Netlify / Cloudflare serve the raw AI-ready
+ * endpoints (`*.md`, `*.mdx`, `*.txt`) with an explicit `charset=utf-8`. Without
+ * it those hosts send `text/markdown` / `text/plain` with no charset and
+ * browsers fall back to Windows-1252, garbling any non-ASCII docs (#82).
+ *
+ * The same file carries the rest of the agent-discovery surface that only a
+ * response header can express: the homepage `Link` header (RFC 8288, see
+ * `ai/link-headers.ts`), and the registered media types for the extensionless
+ * well-known files — `application/linkset+json` for the API catalog, the
+ * signatures directory, and the Agent Skills archives. A static host serves
+ * those as `octet-stream` or nothing at all without a rule.
+ *
+ * A `_headers` shipped in `public/` wins, exactly like `_redirects` — the opt-out
+ * is checked at its source rather than in `dist`, because on Cloudflare the file
+ * in `dist` is not necessarily the user's: `@astrojs/cloudflare` writes its own
+ * `_headers` (an immutable `Cache-Control` rule for `/_astro/*`) during the
+ * build, before this runs. Testing `dist` therefore read an adapter-generated
+ * file as a user opt-out and skipped silently. When both exist, the adapter's
+ * rules are preserved and ours are appended.
+ *
+ * Gated on {@link readsHeaderFiles}, not on `output === "static"`. A **Cloudflare
+ * server** build serves `dist/client` through the Worker's ASSETS binding, and
+ * Workers static assets honor `_headers` from that directory — so the file
+ * applies there too, and skipping it left every Cloudflare server build with no
+ * `Link` header and no media type on its own discovery files. The charset half
+ * of this file *is* redundant on a server build, because the runtime endpoint
+ * sets Content-Type on the Response itself; the `Link` and well-known halves are
+ * not, and one conclusion about the first was applied to all three.
+ *
+ * Exported for the test suite, which exercises it in a subprocess like the
+ * other command helpers.
  */
-const emitHeaderFiles = async (
+export const emitHeaderFiles = async (
   project: BlumeProject,
   distDir: string
 ): Promise<void> => {
   const { config } = project;
   if (
-    config.deployment.output !== "static" ||
-    existsSync(join(distDir, "_headers"))
+    !readsHeaderFiles(config.deployment) ||
+    existsSync(join(project.context.root, "public", "_headers"))
   ) {
     return;
   }
+  const ours = buildNetlifyHeaders(
+    config,
+    buildHomeLinkHeader(config, markdownRoutePaths(project))
+  );
+  // 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 existing = existsSync(target) ? await readFile(target, "utf-8") : "";
   await writeFile(
-    join(distDir, "_headers"),
-    buildNetlifyHeaders(
-      config,
-      buildHomeLinkHeader(config, markdownRoutePaths(project))
-    ),
+    target,
+    existing ? `${existing.trimEnd()}\n${ours}` : ours,
     "utf-8"
   );
   logger.success(
@@ -297,6 +327,72 @@ const emitVercelNegotiation = async (
   );
 };
 
+const warnCloudflareNegotiationSkipped = (): void =>
+  logger.warn(
+    "Could not wire Accept: text/markdown negotiation into dist/server/wrangler.json — raw Markdown stays available at the .md URLs."
+  );
+
+/**
+ * Wire `Accept: text/markdown` negotiation into a Cloudflare server build. The
+ * ASSETS binding serves the prerendered content pages before the Worker runs —
+ * and even a request that reaches the Worker is answered by the adapter's
+ * handler from that binding, ahead of the only place middleware runs — so the
+ * negotiation lives in a generated wrapper Worker, routed to by
+ * `assets.run_worker_first` (see `deploy/cloudflare-negotiation.ts`). Both
+ * pieces are spliced into the adapter's emitted `dist/server` bundle.
+ */
+const emitCloudflareNegotiation = async (
+  project: BlumeProject,
+  routePaths: string[]
+): Promise<void> => {
+  const { config, context } = project;
+  const serverDir = join(
+    context.distDir ?? join(context.root, "dist"),
+    "server"
+  );
+  const wranglerPath = join(serverDir, "wrangler.json");
+  if (!existsSync(wranglerPath)) {
+    warnCloudflareNegotiationSkipped();
+    return;
+  }
+  // The homepage mirror is served from the static layer, so its
+  // `x-markdown-tokens` estimate rides the wrapper Worker, mirroring the
+  // Vercel routing config.
+  const rawMarkdown = await buildRawMarkdown(project);
+  const home = rawMarkdown["/"];
+  const injected = injectWorkerNegotiation(
+    await readFile(wranglerPath, "utf-8"),
+    {
+      base: config.deployment.base,
+      // The manifest routes guard the wrapper's redirect table; `routePaths`
+      // also carries the synthesized homepage mirror, which must not block a
+      // configured root redirect.
+      contentRoutePaths: project.manifest.routes.map((route) => route.path),
+      homeLinkHeader: buildHomeLinkHeader(config, routePaths),
+      homeTokens: home ? markdownTokenCount(agentMarkdown(home)) : undefined,
+      // The wrapper Worker matches full served URLs, so the redirects are
+      // 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),
+      routePaths,
+    }
+  );
+  if (injected === null) {
+    warnCloudflareNegotiationSkipped();
+    return;
+  }
+  await writeFile(
+    join(serverDir, NEGOTIATION_WORKER_FILE),
+    injected.worker,
+    "utf-8"
+  );
+  await writeFile(wranglerPath, injected.wrangler, "utf-8");
+  logger.success(
+    "Wired Accept: text/markdown negotiation into the Cloudflare Worker"
+  );
+};
+
 const formatBytes = (bytes: number): string => {
   if (bytes < 1024) {
     return `${bytes} B`;
@@ -435,6 +531,8 @@ export const isolatedOutputDir = (
  * bundle to the project root — a Vercel server build's static output stays at
  * `<runtime>/.vercel/output/static`, where `deployStaticDir` would instead
  * point at the project-root copy (a previous real build's assets, or nothing).
+ * Node and Cloudflare server builds serve one level down, at `client/` — see
+ * {@link servesClientSubdir}.
  */
 export const isolatedStaticDir = (
   config: ResolvedConfig,
@@ -445,7 +543,7 @@ export const isolatedStaticDir = (
   if (output === "server" && adapter === "vercel") {
     return join(outputDir, "static");
   }
-  if (output === "server" && adapter === "node") {
+  if (servesClientSubdir(config.deployment)) {
     return join(outputDir, "client");
   }
   return outputDir;
@@ -722,6 +820,13 @@ export const buildCommand = defineCommand({
       await emitVercelNegotiation(project, markdownRoutePaths(project), root);
     }
 
+    if (
+      project.config.deployment.output === "server" &&
+      adapter === "cloudflare"
+    ) {
+      await emitCloudflareNegotiation(project, markdownRoutePaths(project));
+    }
+
     await publishBuildArtifacts(
       project,
       deployStaticDir(project.config, project.context),

package/src/cli/commands/dev.ts

@@ -1,8 +1,6 @@
-import { watch } from "node:fs";
-
 import { dev } from "astro";
+import { watch } from "chokidar";
 import { defineCommand } from "citty";
-import { basename, dirname } from "pathe";
 
 import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
@@ -212,26 +210,16 @@ export const devCommand = defineCommand({
       project.context.componentsFile,
     ].filter((target) => target !== null);
 
+    // chokidar handles what raw fs.watch made us hand-roll: recursive
+    // directory watching on every platform, and single files surviving a
+    // rename-replace save (vim and most "atomic save" editors), which orphans
+    // an inode-tracking fs.watch watcher after the first write.
+    const projectWatcher = watch([...dirTargets, ...fileTargets], {
+      ignoreInitial: true,
+    }).on("all", regenerate);
     const disposers = [
       ...project.sources.map((source) => source.watch?.(regenerate)),
-      ...dirTargets.map((target) => {
-        const watcher = watch(target, { recursive: true }, regenerate);
-        return () => watcher.close();
-      }),
-      // Single files are watched via their parent directory: fs.watch on the
-      // file itself tracks the inode, so a rename-replace save (vim and most
-      // "atomic save" editors) orphans the watcher after the first write and
-      // every later edit is silently ignored.
-      ...fileTargets.map((target) => {
-        const name = basename(target);
-        const watcher = watch(dirname(target), (_event, filename) => {
-          // A null filename (some platforms) can't be filtered — regenerate.
-          if (!filename || filename === name) {
-            regenerate();
-          }
-        });
-        return () => watcher.close();
-      }),
+      () => void projectWatcher.close(),
     ].filter((dispose) => dispose !== undefined);
 
     const shutdown = async () => {