blume 1.4.3 → 1.5.1

package/src/core/types.ts

@@ -121,9 +121,24 @@ export interface PageRecord {
   locale: string;
   /**
    * Locale-agnostic logical route shared by every translation (e.g.
-   * `/guides/x`). Pages with the same key are translations of each other.
+   * `/guides/x`, or `/v1.0/guides/x` under versioning — the key is
+   * version-specific, so translations group within their version).
+   * Pages with the same key are translations of each other.
    */
   translationKey: string;
+  /**
+   * Resolved docs version: an archived id (`v1.0`) for snapshot pages, `""`
+   * for the current (unprefixed) docs — including every page of an
+   * unversioned project.
+   */
+  version: string;
+  /**
+   * Version- and locale-agnostic logical route (e.g. `/guides/x` for
+   * `/v1.0/guides/x`). Pages with the same key and locale are the same
+   * logical page across versions — this drives the switcher's same-page
+   * navigation and the canonical-to-latest lookup.
+   */
+  versionKey: string;
   /**
    * True for entries filled in from the fallback locale to pad a locale's
    * navigation for pages it hasn't translated yet. The record's content —
@@ -151,6 +166,7 @@ export interface PageRecord {
    * schemas (schema output, so transforms apply). Present only when the
    * project opts in and the page carries at least one value.
    */
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- values are outputs of arbitrary user-supplied zod schemas (transforms included), so no narrower type exists
   custom?: Record<string, unknown>;
   headings: Heading[];
   /** Whether the file is `.md`/`.mdx`. */
@@ -180,7 +196,12 @@ export type NavNode =
       label: string;
       badge?: string;
       directory?: DirectoryMode;
-      display?: SidebarDisplay;
+      /**
+       * The group's resolved render mode. Always stamped by both builders
+       * (generated and explicit-config sidebars), so the renderer can rely
+       * on it per node.
+       */
+      display: SidebarDisplay;
       icon?: string;
       route?: string;
       /**
@@ -266,6 +287,12 @@ export interface ContentGraph {
   navigation: Navigation;
   /** Navigation per locale; one entry per configured locale under i18n. */
   navigationByLocale: Record<string, Navigation>;
+  /**
+   * Navigation per archived version, keyed by version id and then locale code
+   * (`""` on a single-locale site). The current version's trees are
+   * `navigation`/`navigationByLocale`; empty when versioning is off.
+   */
+  navigationByVersion: Record<string, Record<string, Navigation>>;
   /** Map of route -> pageId for fast lookup and duplicate detection. */
   routes: Map<string, string>;
   diagnostics: Diagnostic[];
@@ -289,6 +316,13 @@ export interface LocaleSwitchOption {
   untranslated: boolean;
 }
 
+/** A docs version a logical page exists in, for the switcher and canonicals. */
+export interface VersionAlternate {
+  /** Version id; `""` for the current (unprefixed) docs. */
+  version: string;
+  path: string;
+}
+
 /** A route entry written to `blume.manifest.json`. */
 export interface RouteManifestEntry {
   id: string;
@@ -313,6 +347,15 @@ export interface RouteManifestEntry {
   locale: string;
   /** Locales this logical page is genuinely translated into (excludes fallbacks). */
   alternates: RouteAlternate[];
+  /** Resolved docs version (`""` for the current docs; see `PageRecord.version`). */
+  version: string;
+  /**
+   * Versions this logical page exists in within this route's locale — the
+   * current version first, then archived versions in configured order. Drives
+   * the switcher's same-page navigation and the canonical-to-latest lookup.
+   * Empty when versioning is off.
+   */
+  versionAlternates: VersionAlternate[];
   /** True when this route renders fallback content for a missing translation. */
   fallback?: boolean;
   /** Resolved "last updated" ISO date, when the feature is enabled. */

package/src/core/ui-packs/index.ts

@@ -47,7 +47,15 @@ import { zh } from "./zh.ts";
  * `zh-TW`). A locale's pack is merged onto English by {@link resolveUIStrings},
  * so a pack only needs the keys it translates.
  */
-export const UI_PACKS: Record<string, UIStringsOverride> = {
+/**
+ * Starter packs keyed by locale code. Open-keyed on purpose: resolvers look
+ * packs up by whatever locale a project configures, not only the codes here.
+ */
+interface UiPackRegistry {
+  [locale: string]: UIStringsOverride;
+}
+
+export const UI_PACKS: UiPackRegistry = {
   ar,
   bg,
   bn,

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) {
@@ -466,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 {