blume 1.4.2 → 1.5.0

package/src/core/version-cut.ts

@@ -0,0 +1,301 @@
+import { existsSync } from "node:fs";
+import { cp, readdir, readFile, rm } from "node:fs/promises";
+
+import { join, relative } from "pathe";
+
+import { stripBasePath } from "./base-path.ts";
+import { writeTextAtomic } from "./fs-atomic.ts";
+import { localizeRoute } from "./i18n.ts";
+import type { BlumeProject } from "./project-graph.ts";
+import { scanProject } from "./project-graph.ts";
+import { VERSION_ID } from "./schema.ts";
+import { nextFenceState } from "./sources/normalize.ts";
+import type { FenceState } from "./sources/normalize.ts";
+import { VERSION_LIKE, versionizeRoute } from "./versions.ts";
+
+/** What `cutVersion` did, for the CLI to report. */
+export interface CutResult {
+  /** Files copied into the snapshot. */
+  copied: number;
+  /** Markdown pages whose root-absolute links were rewritten, with counts. */
+  rewritten: { file: string; count: number }[];
+  /** Whether `blume.config.ts` was updated in place. */
+  configUpdated: boolean;
+  /** Ready-to-paste config snippet when in-place update was not possible. */
+  configSnippet: string | null;
+  /** Absolute path of the created snapshot directory. */
+  dir: string;
+}
+
+/** A `cutVersion` failure the CLI reports as a user error, not a crash. */
+export class CutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CutError";
+  }
+}
+
+// Inline code spans are syntax being *shown*, not links — blank them before
+// 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;
+
+/**
+ * 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.
+ */
+const buildRouteRewrites = (
+  project: BlumeProject,
+  id: string
+): Map<string, string> => {
+  const { basePath, i18n } = project.config;
+  const { contentRoot } = project.context;
+  const rewrites = new Map<string, string>();
+  for (const page of project.graph.pages) {
+    // `sourcePath` is set by the filesystem adapter only, so its absence
+    // already excludes generated and remote pages.
+    const { sourcePath } = page;
+    if (
+      page.version !== "" ||
+      !sourcePath ||
+      relative(contentRoot, sourcePath).startsWith("..")
+    ) {
+      continue;
+    }
+    const logical = versionizeRoute(page.versionKey, id);
+    rewrites.set(
+      stripBasePath(basePath, page.route),
+      i18n ? localizeRoute(logical, page.locale, i18n) : logical
+    );
+  }
+  return rewrites;
+};
+
+/** Rewrite one line's root-absolute internal links via the rewrite table. */
+const rewriteLine = (line: string, rewrites: Map<string, string>): string => {
+  const masked = line.replaceAll(INLINE_CODE, (span) =>
+    " ".repeat(span.length)
+  );
+  let out = "";
+  let cursor = 0;
+  let count = 0;
+  for (const match of masked.matchAll(ROOT_LINK)) {
+    const target = match.groups?.target ?? "";
+    // An anchor or query stays attached to the rewritten path.
+    const hash = target.search(/[#?]/u);
+    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);
+    if (replacement === undefined) {
+      continue;
+    }
+    const offset = (match.index ?? 0) + (match.groups?.prefix?.length ?? 0);
+    out += line.slice(cursor, offset) + replacement + suffix;
+    cursor = offset + target.length;
+    count += 1;
+  }
+  return count === 0 ? line : out + line.slice(cursor);
+};
+
+/** A page's link-rewritten text and how many of its lines changed. */
+export interface SnapshotRewrite {
+  text: string;
+  count: number;
+}
+
+/**
+ * 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.
+ */
+export const rewriteSnapshotLinks = (
+  source: string,
+  rewrites: Map<string, string>
+): SnapshotRewrite => {
+  let fence: FenceState = null;
+  let count = 0;
+  const lines = source.split("\n").map((line) => {
+    const next = nextFenceState(line, fence);
+    const inFence = fence !== null || next !== null;
+    fence = next;
+    if (inFence) {
+      return line;
+    }
+    const rewrittenLine = rewriteLine(line, rewrites);
+    if (rewrittenLine !== line) {
+      count += 1;
+    }
+    return rewrittenLine;
+  });
+  return { count, text: lines.join("\n") };
+};
+
+/** The config entry to add, as a paste-ready snippet for the fallback path. */
+const snippetFor = (id: string, hasVersions: boolean): string =>
+  hasVersions
+    ? `Add to versions.archived in blume.config.ts (newest first):\n\n  { id: "${id}" },\n`
+    : `Add to blume.config.ts:\n\n  versions: {\n    archived: [{ id: "${id}" }],\n    current: { label: "…" },\n  },\n`;
+
+/**
+ * Best-effort in-place config update: insert the new id at the head of an
+ * existing \`archived: [\` array literal, preserving indentation. Anything
+ * fancier (computed arrays, config spread across files) falls back to a
+ * printed snippet — the config is user-authored TypeScript, and string-level
+ * surgery beyond this simple shape risks corrupting it.
+ */
+export const insertArchivedVersion = async (
+  configPath: string,
+  id: string
+): Promise<boolean> => {
+  let text: string;
+  try {
+    text = await readFile(configPath, "utf-8");
+  } catch {
+    return false;
+  }
+  const match = text.match(/(?<lead>archived:\s*\[)/u);
+  if (!match || match.index === undefined) {
+    return false;
+  }
+  const insertAt = match.index + (match.groups?.lead?.length ?? 0);
+  // Indentation: one level deeper than the line holding `archived:`.
+  const lineStart = text.lastIndexOf("\n", match.index) + 1;
+  const indent = text.slice(lineStart).match(/^\s*/u)?.[0] ?? "";
+  const rest = text.slice(insertAt);
+  // Match the array's authored shape: empty stays bare, an inline array gets
+  // an inline entry, a multiline array gets its own indented line.
+  let entry: string;
+  if (rest.trimStart().startsWith("]")) {
+    entry = `{ id: "${id}" }`;
+  } else if (rest.startsWith("\n")) {
+    entry = `\n${indent}  { id: "${id}" },`;
+  } else {
+    entry = `{ id: "${id}" }, `;
+  }
+  await writeTextAtomic(configPath, text.slice(0, insertAt) + entry + rest);
+  return true;
+};
+
+/**
+ * Freeze the current docs as an archived version: copy the content tree into
+ * `<contentRoot>/<id>/` (excluding existing snapshots), rewrite root-absolute
+ * internal links so the copy is self-contained, and register the id in
+ * `blume.config.ts` (or print the snippet to paste).
+ */
+export const cutVersion = async (
+  root: string,
+  id: string,
+  options: { force?: boolean } = {}
+): Promise<CutResult> => {
+  if (!VERSION_ID.test(id)) {
+    throw new CutError(
+      `Version ids must start with a letter (e.g. "v1.0") and contain only letters, digits, dots, hyphens, and underscores — got "${id}".`
+    );
+  }
+
+  const project = await scanProject(root);
+  const errors = project.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "error"
+  );
+  if (errors.length > 0) {
+    throw new CutError(
+      `The project has ${errors.length} error diagnostic(s) — fix them before cutting a version (run \`blume validate\`).`
+    );
+  }
+  // A missing content root already fails inside `scanProject` (the filesystem
+  // source's own validation), so only the version-level checks remain here.
+  const { contentRoot } = project.context;
+  if (project.config.versions?.archived.some((version) => version.id === id)) {
+    throw new CutError(
+      `Version "${id}" is already registered in versions.archived.`
+    );
+  }
+
+  const dir = join(contentRoot, id);
+  if (existsSync(dir)) {
+    if (!options.force) {
+      throw new CutError(
+        `${dir} already exists — pass --force to overwrite the snapshot.`
+      );
+    }
+    await rm(dir, { force: true, recursive: true });
+  }
+
+  // Existing snapshots must not nest inside the new one: configured ids, plus
+  // any version-shaped directory (`v1.0/`) that never made it into the config —
+  // e.g. a prior cut whose config update fell back to a printed snippet. A
+  // genuine content folder that merely looks like a version already draws the
+  // rename-or-register diagnostic, so skipping it here is consistent.
+  const excluded = new Set([
+    id,
+    "node_modules",
+    ...(project.config.versions?.archived.map((version) => version.id) ?? []),
+  ]);
+  const entries = await readdir(contentRoot, { withFileTypes: true });
+  let copied = 0;
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (
+        excluded.has(entry.name) ||
+        entry.name.startsWith(".") ||
+        (entry.isDirectory() && VERSION_LIKE.test(entry.name))
+      ) {
+        return;
+      }
+      await cp(join(contentRoot, entry.name), join(dir, entry.name), {
+        recursive: true,
+      });
+    })
+  );
+
+  // Rewrite root-absolute internal links in every copied markdown page.
+  const rewrites = buildRouteRewrites(project, id);
+  const rewritten: { file: string; count: number }[] = [];
+  const walk = async (current: string): Promise<void> => {
+    const children = await readdir(current, { withFileTypes: true });
+    await Promise.all(
+      children.map(async (child) => {
+        const abs = join(current, child.name);
+        if (child.isDirectory()) {
+          await walk(abs);
+          return;
+        }
+        copied += 1;
+        if (!/\.mdx?$/u.test(child.name)) {
+          return;
+        }
+        const source = await readFile(abs, "utf-8");
+        const { text, count } = rewriteSnapshotLinks(source, rewrites);
+        if (count > 0) {
+          await writeTextAtomic(abs, text);
+          rewritten.push({ count, file: relative(dir, abs) });
+        }
+      })
+    );
+  };
+  await walk(dir);
+
+  const configPath = join(root, "blume.config.ts");
+  const configUpdated =
+    project.config.versions !== undefined &&
+    (await insertArchivedVersion(configPath, id));
+
+  return {
+    configSnippet: configUpdated
+      ? null
+      : snippetFor(id, project.config.versions !== undefined),
+    configUpdated,
+    copied,
+    dir,
+    rewritten,
+  };
+};

package/src/core/version.ts

@@ -16,6 +16,8 @@ let cached: string | undefined;
 export const getBlumeVersion = (): string => {
   if (cached === undefined) {
     const pkgPath = join(packageRoot(), "package.json");
+    // SAFETY: this reads blume's own package.json, which always declares a
+    // `version` (publishing requires it).
     cached = (JSON.parse(readFileSync(pkgPath, "utf-8")) as { version: string })
       .version;
   }

package/src/core/versions.ts

@@ -0,0 +1,170 @@
+import { localizeRoute } from "./i18n.ts";
+import type {
+  ArchivedVersionConfig,
+  ResolvedConfig,
+  ResolvedI18nConfig,
+  ResolvedVersionsConfig,
+} from "./schema.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+
+/**
+ * Version logic, centralized. Every seam that needs to reason about docs
+ * versions (content discovery, navigation, manifest, runtime generation, the
+ * catch-all) goes through these helpers so the routing rules live in exactly
+ * one place — the same contract `./i18n.ts` holds for locales.
+ *
+ * The current version is the empty string `""`: the latest docs live at the
+ * content root with unprefixed URLs, and only archived snapshots have a
+ * directory and a URL segment.
+ */
+
+/**
+ * Top-level folders that look like a version (`v1`, `V2.0`) — used by the
+ * unconfigured-snapshot diagnostic and by `blume version` to keep such folders
+ * out of new snapshots.
+ */
+export const VERSION_LIKE = /^v\d/iu;
+
+/** True when the project opts into versioning. */
+export const versionsEnabled = (
+  config: ResolvedConfig
+): config is ResolvedConfig & { versions: ResolvedVersionsConfig } =>
+  config.versions !== undefined;
+
+/** All archived version ids, in configured (switcher) order. */
+export const archivedIds = (versions: ResolvedVersionsConfig): string[] =>
+  versions.archived.map((version) => version.id);
+
+/** Switcher label for a version: the current label for `""`, else per config. */
+export const versionLabel = (
+  id: string,
+  versions: ResolvedVersionsConfig
+): string => {
+  if (id === "") {
+    return versions.current.label;
+  }
+  const archived = versions.archived.find((version) => version.id === id);
+  return archived?.label ?? id;
+};
+
+/** The archived version config for an id (`undefined` for current/unknown). */
+export const archivedVersion = (
+  id: string,
+  versions: ResolvedVersionsConfig
+): ArchivedVersionConfig | undefined =>
+  versions.archived.find((version) => version.id === id);
+
+/** A resolved version (`""` for current) and the version-stripped remainder. */
+export interface DetectedVersion {
+  version: string;
+  rest: string[];
+}
+
+/** {@link DetectedVersion} for a slash-joined source ref. */
+export interface DetectedVersionRef {
+  version: string;
+  rest: string;
+}
+
+/**
+ * Detect a leading archived-version directory in a path's segments. The
+ * current version lives at the content root, so only archived ids are matched
+ * as a leading segment. Returns the resolved version (`""` for current) and
+ * the remaining (version-stripped) segments. Runs BEFORE locale detection —
+ * the snapshot directory is outermost on disk, so the locale parser must see
+ * a version-stripped path.
+ */
+export const detectVersion = (
+  parts: string[],
+  versions: ResolvedVersionsConfig
+): DetectedVersion => {
+  const [first] = parts;
+  if (first && versions.archived.some((version) => version.id === first)) {
+    return { rest: parts.slice(1), version: first };
+  }
+  return { rest: parts, version: "" };
+};
+
+/**
+ * {@link detectVersion} over a slash-joined source ref (`v1.0/fr/x.mdx`):
+ * returns the version and the version-stripped ref for the locale parser and
+ * route mapping to consume.
+ */
+export const detectVersionRef = (
+  ref: string,
+  versions: ResolvedVersionsConfig
+): DetectedVersionRef => {
+  const { version, rest } = detectVersion(ref.split("/"), versions);
+  return { rest: rest.join("/"), version };
+};
+
+/**
+ * Prefix a version-agnostic logical route with its version: `/guides/x`
+ * becomes `/v1.0/guides/x`, `/` becomes `/v1.0`. The current version (`""`)
+ * is the identity.
+ */
+export const versionizeRoute = (
+  logicalRoute: string,
+  version: string
+): string => {
+  if (!version) {
+    return logicalRoute;
+  }
+  return logicalRoute === "/" ? `/${version}` : `/${version}${logicalRoute}`;
+};
+
+/**
+ * The localized root route of a version: `/`, `/fr`, `/v1.0`, or `/fr/v1.0`.
+ * The locale prefix stays outermost, matching how page routes compose
+ * (`localizeRoute(versionizeRoute(...))`).
+ */
+export const versionRoot = (
+  version: string,
+  locale?: string,
+  i18n?: ResolvedI18nConfig
+): string => {
+  const logical = versionizeRoute("/", version);
+  if (i18n && locale !== undefined) {
+    return localizeRoute(logical, locale, i18n);
+  }
+  return logical;
+};
+
+/**
+ * Warn about top-level content folders shaped like a version (`v1`, `v2.0`)
+ * that aren't declared in `versions.archived`. Without this they're silently
+ * treated as current-version content under a `/<folder>/…` route — usually a
+ * snapshot that wasn't registered in config.
+ */
+export const versionsDiagnostics = (
+  pages: PageRecord[],
+  versions: ResolvedVersionsConfig
+): Diagnostic[] => {
+  // Exact-id comparison, matching `detectVersion`: a folder that differs from
+  // a configured id only by case (`V1.0/` vs `v1.0`) is NOT routed as that
+  // snapshot, so it must still warn. `VERSION_LIKE` is case-insensitive on
+  // its own.
+  const configured = new Set(versions.archived.map((version) => version.id));
+  const seen = new Set<string>();
+  const diagnostics: Diagnostic[] = [];
+  for (const page of pages) {
+    // The version-looking folder is the first segment of the source-local ref
+    // (e.g. `v1.0/guide.md`), not the namespaced id (`filesystem:v1.0/guide.md`).
+    const [first] = page.source.ref.split("/");
+    if (
+      first &&
+      !seen.has(first) &&
+      VERSION_LIKE.test(first) &&
+      !configured.has(first)
+    ) {
+      seen.add(first);
+      diagnostics.push({
+        code: "BLUME_VERSIONS_UNCONFIGURED_VERSION",
+        message: `Folder "${first}/" looks like a version, but "${first}" is not in versions.archived — its pages are treated as current-version content at /${first}/….`,
+        severity: "warning",
+        suggestion: `Add { id: "${first}" } to versions.archived, or rename the folder if it isn't a snapshot.`,
+      });
+    }
+  }
+  return diagnostics;
+};

package/src/deploy/adapter-output.ts

@@ -8,6 +8,9 @@ import type { ProjectContext } from "../core/types.ts";
 
 type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
 
+/** An optional per-adapter path, keyed by the closed adapter union. */
+type AdapterPathMap = { [A in Adapter]?: string };
+
 /**
  * Top-level directory each server adapter writes its deploy bundle into, for
  * `.gitignore` — the bundle is a build artifact, and the platform's own state
@@ -15,7 +18,7 @@ type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
  * whole directory is ignored. `node` and `cloudflare` emit into `dist/`, which
  * `blume init` already ignores.
  */
-export const ADAPTER_IGNORE_DIRS: Partial<Record<Adapter, string>> = {
+export const ADAPTER_IGNORE_DIRS: AdapterPathMap = {
   netlify: ".netlify/",
   vercel: ".vercel/",
 };
@@ -40,7 +43,7 @@ export const ADAPTER_IGNORE_DIRS: Partial<Record<Adapter, string>> = {
  * chunks and `node_modules`. Given the right root it writes its Build Output
  * tree straight to `<root>/.vercel/output`, so there is nothing left to move.
  */
-export const ADAPTER_OUTPUT_PATHS: Partial<Record<Adapter, string>> = {
+export const ADAPTER_OUTPUT_PATHS: AdapterPathMap = {
   netlify: ".netlify/v1",
 };
 

package/src/deploy/cloudflare-negotiation.ts

@@ -75,6 +75,25 @@ const FALLBACK_RULES = ["/*", "!/_astro/*", "!/*.md", "!/*.mdx", "!/*.txt"];
 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
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** Narrow a parsed JSON value to a plain (non-array) object. */
+const isJsonObject = (
+  value: JsonValue | undefined
+): value is { [key: string]: JsonValue } =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Narrow a parsed JSON value to a string. */
+const isJsonString = (value: JsonValue | undefined): value is string =>
+  typeof value === "string";
+
 const isNegativeRule = (rule: string): boolean => rule.startsWith("!");
 
 const ruleBody = (rule: string): string =>
@@ -163,7 +182,7 @@ const coveredBy = (rule: string, other: string): boolean =>
  * validation error at deploy time.
  */
 export const mergeRunWorkerFirstRules = (
-  existing: unknown,
+  existing: JsonValue | undefined,
   added: readonly string[]
 ): string[] | true => {
   if (existing === true) {
@@ -276,6 +295,20 @@ const redirectFor = (pathname) => {
   return Object.hasOwn(REDIRECTS, path) ? REDIRECTS[path] : null;
 };
 
+// \`_redirects\` semantics, which the static layer applies to these same
+// paths: the request's query string is forwarded unless the destination
+// carries its own, and a destination fragment stays after the query.
+const redirectLocation = (destination, search) => {
+  const hashIndex = destination.indexOf("#");
+  const bare = hashIndex === -1 ? destination : destination.slice(0, hashIndex);
+  if (!search || bare.includes("?")) {
+    return destination;
+  }
+  return hashIndex === -1
+    ? bare + search
+    : bare + search + destination.slice(hashIndex);
+};
+
 const parseAccept = (accept) =>
   accept.split(",").map((part) => {
     const segments = part.trim().split(";");
@@ -355,7 +388,7 @@ export default {
     const redirect = redirectFor(url.pathname);
     if (redirect !== null) {
       return new Response(null, {
-        headers: { location: redirect[0] },
+        headers: { location: redirectLocation(redirect[0], url.search) },
         status: redirect[1],
       });
     }
@@ -452,29 +485,25 @@ export const injectWorkerNegotiation = (
   if (options.routePaths.length === 0) {
     return null;
   }
-  let config: Record<string, unknown>;
+  let config: JsonValue;
   try {
     config = JSON.parse(wranglerText);
   } catch {
     return null;
   }
-  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+  if (!isJsonObject(config)) {
     return null;
   }
   const { main } = config;
   if (
-    typeof main !== "string" ||
+    !isJsonString(main) ||
     main.length === 0 ||
     main === NEGOTIATION_WORKER_FILE
   ) {
     return null;
   }
-  const assets = config.assets as Record<string, unknown> | undefined;
-  if (
-    assets === null ||
-    typeof assets !== "object" ||
-    typeof assets.binding !== "string"
-  ) {
+  const { assets } = config;
+  if (!isJsonObject(assets) || !isJsonString(assets.binding)) {
     return null;
   }
   const {

package/src/deploy/robots.ts

@@ -1,6 +1,7 @@
 import { normalizeBasePath, withBasePath } 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";
 
 /**
  * Ordered mapping from config field to its `Content-Signal` token. The order
@@ -52,7 +53,7 @@ export const buildRobots = (project: BlumeProject): string | null => {
       normalizeBasePath(config.deployment.base),
       "/sitemap.xml"
     );
-    lines.push("", `Sitemap: ${site.replace(/\/$/u, "")}${sitemapPath}`);
+    lines.push("", `Sitemap: ${absoluteUrl(site, sitemapPath)}`);
   }
   return `${lines.join("\n")}\n`;
 };

package/src/deploy/rss.ts

@@ -4,6 +4,7 @@ import { escape as escapeXml } from "html-escaper";
 
 import { normalizeBasePath, withBasePath } 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";
 
 /** A single feed entry derived from a content page. */
@@ -55,7 +56,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
   if (!(rss.enabled && site)) {
     return [];
   }
-  const base = site.replace(/\/$/u, "");
+  const base = siteRoot(site);
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
   // 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).