@decocms/start 4.4.0 → 4.5.0

package/.github/workflows/lockfile-check.yml

@@ -0,0 +1,35 @@
+name: lockfile-check
+
+# PR-time guardrail: re-runs the same install our release workflow
+# runs on main (`bun install --frozen-lockfile`). Fails the PR if
+# bun.lock would have rejected the install — closes the loop so drift
+# can never reach main.
+#
+# Pairs with:
+#   - "packageManager": "bun@1.3.5" in package.json
+#   - .gitignore bans on package-lock.json / yarn.lock / pnpm-lock.yaml
+#   - the deco-post-cleanup audit's lockfile-* rules
+#
+# Adjust `bun-version` here in lockstep with the package.json
+# `packageManager` field.
+
+on:
+  pull_request:
+    paths:
+      - "package.json"
+      - "bun.lock"
+      - ".github/workflows/lockfile-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  frozen-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+      - name: bun install --frozen-lockfile
+        run: bun install --frozen-lockfile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/phase-report.ts

@@ -187,21 +187,21 @@ export function report(ctx: MigrationContext): void {
   lines.push("## Next Steps");
   lines.push("");
   lines.push("```bash");
-  lines.push("# 1. Install dependencies");
-  lines.push("npm install");
+  lines.push("# 1. Install dependencies (bun is the canonical PM)");
+  lines.push("bun install");
   lines.push("");
   lines.push("# 2. Generate CMS blocks and schema");
-  lines.push("npm run generate:blocks");
-  lines.push("npm run generate:schema");
+  lines.push("bun run generate:blocks");
+  lines.push("bun run generate:schema");
   lines.push("");
   lines.push("# 3. Generate routes");
-  lines.push("npx tsr generate");
+  lines.push("bunx tsr generate");
   lines.push("");
   lines.push("# 4. Type check");
-  lines.push("npx tsc --noEmit");
+  lines.push("bunx tsc --noEmit");
   lines.push("");
   lines.push("# 5. Find unused code");
-  lines.push("npm run knip");
+  lines.push("bun run knip");
   lines.push("");
   lines.push("# 6. Run dev server");
   lines.push("npm run dev");

package/scripts/migrate/phase-scaffold.ts

@@ -2,7 +2,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { MigrationContext } from "./types";
 import { log, logPhase } from "./types";
-import { generatePackageJson } from "./templates/package-json";
+import { CANONICAL_BUN_VERSION, generatePackageJson } from "./templates/package-json";
+import { generateLockfileCheckYml } from "./templates/lockfile-check-yml";
 import { generateTsconfig } from "./templates/tsconfig";
 import { generateViteConfig } from "./templates/vite-config";
 import { generateKnipConfig } from "./templates/knip-config";
@@ -72,6 +73,16 @@ export function scaffold(ctx: MigrationContext): void {
     tabWidth: 2,
   }, null, 2) + "\n");
 
+  // PR-time lockfile guardrail. Lives in the site repo (per-site, not
+  // a centralised reusable workflow) because per D6.3 we are not
+  // scaffolding caller stubs into storefronts. Bun version is pinned
+  // in lockstep with `package.json` via CANONICAL_BUN_VERSION.
+  writeFile(
+    ctx,
+    ".github/workflows/lockfile-check.yml",
+    generateLockfileCheckYml(CANONICAL_BUN_VERSION),
+  );
+
   // Server entry files (server.ts, worker-entry.ts, router.tsx, runtime.ts, context.ts)
   writeMultiFile(ctx, generateServerEntry(ctx));
 
@@ -238,6 +249,11 @@ vite.config.timestamp_*
 # IDE
 .vscode/
 .idea/
+
+# Lockfiles — bun is canonical, prevent accidental drift
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
 `;
 }
 

package/scripts/migrate/phase-verify.ts

@@ -17,6 +17,7 @@ const REQUIRED_FILES = [
   // Workers Builds (D6.3) -- configured in the CF dashboard, not via
   // GitHub workflow files in the site repo.
   ".github/workflows/regen-blocks.yml",
+  ".github/workflows/lockfile-check.yml",
   "knip.config.ts",
   ".prettierrc",
   "src/server.ts",

package/scripts/migrate/post-cleanup/rules.ts

@@ -1239,6 +1239,345 @@ const ruleHtmxResidue: Rule = {
   },
 };
 
+/* ------------------------------------------------------------------ */
+/* Rule 9 — `lockfile-multiple` — multiple lockfiles tracked          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Per the fleet-wide bun-canonical decision, every storefront commits
+ * exactly one lockfile: `bun.lock`. This rule fires when any of the
+ * non-bun lockfiles co-exist with bun.lock — that's the exact pattern
+ * that broke Cloudflare Workers Builds with `lockfile had changes, but
+ * lockfile is frozen` (the dual-lockfile drift).
+ *
+ * The `--fix` deletes the offending non-bun lockfiles. Adding the
+ * `.gitignore` bans is a separate concern handled by `packageManager-missing`
+ * (which also nudges the site to add the bans), so this rule stays
+ * focused.
+ */
+const NON_BUN_LOCKFILES = ["package-lock.json", "yarn.lock", "pnpm-lock.yaml"];
+
+const ruleLockfileMultiple: Rule = {
+  id: "lockfile-multiple",
+  title: "Multiple lockfiles tracked alongside bun.lock",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const bunLock = `${siteDir}/bun.lock`;
+    if (!fs.exists(bunLock)) return [];
+    const findings: Finding[] = [];
+    for (const name of NON_BUN_LOCKFILES) {
+      const abs = `${siteDir}/${name}`;
+      if (!fs.exists(abs)) continue;
+      findings.push({
+        rule: "lockfile-multiple",
+        severity: "warning",
+        file: name,
+        message: `${name} co-exists with bun.lock — Cloudflare Workers Builds picks bun and the other will silently drift`,
+        fix: `rm ${name} (bun.lock is the canonical lockfile)`,
+        meta: { lockfile: name },
+      });
+    }
+    return findings;
+  },
+  applyFix({ siteDir }, findings, writer): FixAction[] {
+    const actions: FixAction[] = [];
+    for (const f of findings) {
+      writer.deleteFile(`${siteDir}/${f.file}`);
+      actions.push({
+        file: f.file,
+        kind: "delete",
+        detail: `deleted (bun.lock is canonical)`,
+      });
+    }
+    return actions;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 10 — `lockfile-missing` — package.json without bun.lock        */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A storefront with `package.json` but no committed lockfile cannot
+ * run `bun install --frozen-lockfile` in CI — Cloudflare Workers
+ * Builds either falls back to a non-reproducible install or fails
+ * outright depending on the build image. Detect-only because the
+ * fix (`bun install`) requires network access and a working bun
+ * toolchain that the audit shouldn't shell out to from inside its
+ * own runner.
+ */
+const ruleLockfileMissing: Rule = {
+  id: "lockfile-missing",
+  title: "Lockfile missing",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const pkg = `${siteDir}/package.json`;
+    if (!fs.exists(pkg)) return [];
+    const bunLock = `${siteDir}/bun.lock`;
+    if (fs.exists(bunLock)) return [];
+    // If a non-bun lockfile is present, `lockfile-multiple` doesn't
+    // apply but the site is still mid-migration to bun. We flag the
+    // missing bun.lock here so the operator runs `bun install` to
+    // produce the canonical one.
+    return [
+      {
+        rule: "lockfile-missing",
+        severity: "warning",
+        file: "bun.lock",
+        message: `No bun.lock committed — frozen installs cannot run on CF Workers Builds`,
+        fix: `Run \`bun install\` and commit the resulting bun.lock`,
+        meta: {},
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 11 — `lockfile-drift` — bun.lock out of sync with package.json */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Detects the head-on case behind the `lockfile had changes, but
+ * lockfile is frozen` Workers Builds error: a direct dependency in
+ * `package.json` has no version in `bun.lock` that satisfies the
+ * declared range.
+ *
+ * Coverage is intentionally pragmatic — we recognise the four most
+ * common range shapes (`^a.b.c`, `~a.b.c`, plain `a.b.c`, and the
+ * sentinels `*` / `latest` / `next` / git/github specs which we skip).
+ * Everything else falls back to "present in lockfile?", treating
+ * unknown ranges as satisfied as long as the name appears at all.
+ * The goal is high signal on the storefront fleet's actual failure
+ * mode; full npm-semver fidelity is out of scope for this rule.
+ *
+ * Detect-only: regenerating bun.lock requires running `bun install`,
+ * which the audit script doesn't do (would need network + bun in
+ * PATH). Operators run it manually and re-run the audit.
+ */
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-[\w.+-]+)?$/;
+
+function parseSemver(v: string): [number, number, number] | null {
+  const m = SEMVER_RE.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function gte(a: [number, number, number], b: [number, number, number]): boolean {
+  if (a[0] !== b[0]) return a[0] > b[0];
+  if (a[1] !== b[1]) return a[1] > b[1];
+  return a[2] >= b[2];
+}
+
+function lt(a: [number, number, number], b: [number, number, number]): boolean {
+  if (a[0] !== b[0]) return a[0] < b[0];
+  if (a[1] !== b[1]) return a[1] < b[1];
+  return a[2] < b[2];
+}
+
+/**
+ * Minimal `range satisfies version` check. Returns:
+ * - `true` when the range is satisfied,
+ * - `false` when it is definitely violated,
+ * - `null` when we don't recognise the range shape and the caller
+ *   should fall back to a presence check.
+ */
+function satisfiesRange(version: string, range: string): boolean | null {
+  const trimmed = range.trim();
+  // Sentinels and non-numeric specs we don't try to evaluate.
+  if (
+    trimmed === "*" ||
+    trimmed === "latest" ||
+    trimmed === "next" ||
+    trimmed.startsWith("workspace:") ||
+    trimmed.startsWith("file:") ||
+    trimmed.startsWith("link:") ||
+    trimmed.startsWith("git+") ||
+    trimmed.startsWith("github:") ||
+    trimmed.includes("://")
+  ) {
+    return null;
+  }
+  const ver = parseSemver(version);
+  if (!ver) return null;
+  // Caret: ^a.b.c → >=a.b.c <(a+1).0.0   when a > 0
+  //        ^0.b.c → >=0.b.c <0.(b+1).0   when a == 0 && b > 0
+  //        ^0.0.c → exactly 0.0.c
+  if (trimmed.startsWith("^")) {
+    const base = parseSemver(trimmed.slice(1));
+    if (!base) return null;
+    if (!gte(ver, base)) return false;
+    let upper: [number, number, number];
+    if (base[0] > 0) upper = [base[0] + 1, 0, 0];
+    else if (base[1] > 0) upper = [0, base[1] + 1, 0];
+    else upper = [0, 0, base[2] + 1];
+    return lt(ver, upper);
+  }
+  // Tilde: ~a.b.c → >=a.b.c <a.(b+1).0
+  if (trimmed.startsWith("~")) {
+    const base = parseSemver(trimmed.slice(1));
+    if (!base) return null;
+    return gte(ver, base) && lt(ver, [base[0], base[1] + 1, 0]);
+  }
+  // Plain pin: a.b.c → exact match.
+  const exact = parseSemver(trimmed);
+  if (exact) return exact[0] === ver[0] && exact[1] === ver[1] && exact[2] === ver[2];
+  return null;
+}
+
+/**
+ * Pull every `"<name>@<version>"` token out of bun.lock for a given
+ * package name. Bun's lockfile format embeds the version inside the
+ * package descriptor array, e.g.:
+ *
+ *   "@decocms/start": ["@decocms/start@2.1.1", ...]
+ *
+ * We scan all such occurrences (a single package may appear multiple
+ * times if the dep tree pulled different versions).
+ */
+function lockfileVersionsOf(lockfile: string, name: string): string[] {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`['"]${escaped}@([^'"\\s]+)['"]`, "g");
+  const seen = new Set<string>();
+  for (const m of lockfile.matchAll(re)) {
+    seen.add(m[1]);
+  }
+  return [...seen];
+}
+
+const ruleLockfileDrift: Rule = {
+  id: "lockfile-drift",
+  title: "bun.lock drifted vs package.json direct dependencies",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const pkgPath = `${siteDir}/package.json`;
+    const lockPath = `${siteDir}/bun.lock`;
+    if (!fs.exists(pkgPath) || !fs.exists(lockPath)) return [];
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fs.readText(pkgPath));
+    } catch {
+      return [];
+    }
+    if (typeof parsed !== "object" || parsed === null) return [];
+    const pkg = parsed as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    const lockText = fs.readText(lockPath);
+    const drifted: { name: string; range: string; locked: string[] }[] = [];
+    const buckets: Record<string, string>[] = [pkg.dependencies ?? {}, pkg.devDependencies ?? {}];
+    for (const bucket of buckets) {
+      for (const [name, range] of Object.entries(bucket)) {
+        const versions = lockfileVersionsOf(lockText, name);
+        if (versions.length === 0) {
+          drifted.push({ name, range, locked: [] });
+          continue;
+        }
+        // If at least one locked version satisfies the range, we're fine.
+        // For unknown range shapes (return null), treat presence as
+        // satisfaction — pragmatic, see rule docstring.
+        let satisfied = false;
+        for (const v of versions) {
+          const result = satisfiesRange(v, range);
+          if (result === true || result === null) {
+            satisfied = true;
+            break;
+          }
+        }
+        if (!satisfied) drifted.push({ name, range, locked: versions });
+      }
+    }
+    if (drifted.length === 0) return [];
+    return [
+      {
+        rule: "lockfile-drift",
+        severity: "warning",
+        file: "bun.lock",
+        message: `${drifted.length} direct dep(s) not satisfied by bun.lock — frozen install will fail`,
+        fix: `Run \`bun install\` to refresh bun.lock, then commit. Drift: ${drifted
+          .slice(0, 5)
+          .map((d) => `${d.name} ${d.range} (locked: ${d.locked.length > 0 ? d.locked.join(", ") : "none"})`)
+          .join("; ")}${drifted.length > 5 ? `; +${drifted.length - 5} more` : ""}`,
+        meta: { drifted },
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 12 — `package-manager-missing` — no packageManager field      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Without a `packageManager` field in package.json, neither developers
+ * nor CI are forced to agree on a PM. Anyone running `npm install`
+ * or `yarn` produces an alternate lockfile that risks drifting from
+ * `bun.lock` and breaking Workers Builds. The fleet-wide canonical
+ * value is `bun@<CANONICAL_BUN_VERSION>`; bumping that constant here
+ * propagates to all `--fix` runs.
+ */
+const CANONICAL_PACKAGE_MANAGER = "bun@1.3.5";
+
+const rulePackageManagerMissing: Rule = {
+  id: "package-manager-missing",
+  title: "Missing packageManager field in package.json",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const pkgPath = `${siteDir}/package.json`;
+    if (!fs.exists(pkgPath)) return [];
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fs.readText(pkgPath));
+    } catch {
+      return [];
+    }
+    if (typeof parsed !== "object" || parsed === null) return [];
+    const pkg = parsed as { packageManager?: string };
+    if (typeof pkg.packageManager === "string" && pkg.packageManager.length > 0) {
+      return [];
+    }
+    return [
+      {
+        rule: "package-manager-missing",
+        severity: "info",
+        file: "package.json",
+        message: `Missing "packageManager" field — contributors and CF Workers Builds may pick different PMs`,
+        fix: `Set "packageManager": "${CANONICAL_PACKAGE_MANAGER}" in package.json`,
+        meta: { canonical: CANONICAL_PACKAGE_MANAGER },
+      },
+    ];
+  },
+  applyFix({ siteDir, fs }, findings, writer): FixAction[] {
+    if (findings.length === 0) return [];
+    const pkgPath = `${siteDir}/package.json`;
+    if (!fs.exists(pkgPath)) return [];
+    const content = fs.readText(pkgPath);
+    let parsed: Record<string, unknown>;
+    try {
+      parsed = JSON.parse(content) as Record<string, unknown>;
+    } catch {
+      return [];
+    }
+    if (typeof parsed.packageManager === "string" && parsed.packageManager.length > 0) {
+      return [];
+    }
+    // Insert `packageManager` directly after `license` to match the
+    // convention used across the storefront fleet. Falls back to the
+    // end of the object when `license` is absent.
+    const ordered: Record<string, unknown> = {};
+    let inserted = false;
+    for (const [k, v] of Object.entries(parsed)) {
+      ordered[k] = v;
+      if (!inserted && k === "license") {
+        ordered.packageManager = CANONICAL_PACKAGE_MANAGER;
+        inserted = true;
+      }
+    }
+    if (!inserted) ordered.packageManager = CANONICAL_PACKAGE_MANAGER;
+    writer.writeText(pkgPath, `${JSON.stringify(ordered, null, 2)}\n`);
+    return [
+      {
+        file: "package.json",
+        kind: "edit",
+        detail: `set packageManager: "${CANONICAL_PACKAGE_MANAGER}"`,
+      },
+    ];
+  },
+};
+
 export const ALL_RULES: Rule[] = [
   ruleDeadLibShims,
   ruleObsoleteVitePlugins,
@@ -1249,12 +1588,18 @@ export const ALL_RULES: Rule[] = [
   ruleFrameworkTodos,
   ruleLocalFrameworkDuplicate,
   ruleHtmxResidue,
+  ruleLockfileMultiple,
+  ruleLockfileMissing,
+  ruleLockfileDrift,
+  rulePackageManagerMissing,
 ];
 
 /** Exported for direct unit tests. */
 export const _internals = {
   extractExports,
   symbolUsedOutsideLib,
+  satisfiesRange,
+  lockfileVersionsOf,
   rules: {
     ruleDeadLibShims,
     ruleObsoleteVitePlugins,
@@ -1265,5 +1610,9 @@ export const _internals = {
     ruleLocalWidgetsTypes,
     ruleFrameworkTodos,
     ruleLocalFrameworkDuplicate,
+    ruleLockfileMultiple,
+    ruleLockfileMissing,
+    ruleLockfileDrift,
+    rulePackageManagerMissing,
   },
 };

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -668,7 +668,9 @@ describe("runAudit — totals", () => {
         "dead-runtime-shim",
         "local-framework-duplicate",
         "local-widgets-types",
+        "lockfile-multiple",
         "obsolete-vite-plugins",
+        "package-manager-missing",
         "vtex-shim-regression",
       ].sort(),
     );
@@ -1450,3 +1452,217 @@ describe("rule: local-framework-duplicate", () => {
     expect(r.supportsAutoFix).toBe(true);
   });
 });
+
+describe("rule: lockfile-multiple", () => {
+  it("flags package-lock.json and yarn.lock when bun.lock exists", () => {
+    const fs = makeFs({
+      "/site/package.json": "{}",
+      "/site/bun.lock": "{}",
+      "/site/package-lock.json": "{}",
+      "/site/yarn.lock": "",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-multiple")!;
+    expect(r.findings.map((f) => f.file).sort()).toEqual(["package-lock.json", "yarn.lock"]);
+  });
+
+  it("does not flag when only bun.lock is present", () => {
+    const fs = makeFs({
+      "/site/package.json": "{}",
+      "/site/bun.lock": "{}",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-multiple")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does not fire when bun.lock is absent (lockfile-missing handles that case)", () => {
+    const fs = makeFs({
+      "/site/package.json": "{}",
+      "/site/package-lock.json": "{}",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-multiple")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("--fix deletes the offending lockfiles", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/package.json": "{}",
+      "/site/bun.lock": "{}",
+      "/site/package-lock.json": "{}",
+      "/site/yarn.lock": "",
+    });
+    runAudit(SITE, fs, { writer });
+    expect(store["/site/package-lock.json"]).toBeUndefined();
+    expect(store["/site/yarn.lock"]).toBeUndefined();
+    expect(store["/site/bun.lock"]).toBeDefined();
+  });
+});
+
+describe("rule: lockfile-missing", () => {
+  it("fires when package.json exists without bun.lock", () => {
+    const fs = makeFs({ "/site/package.json": "{}" });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-missing")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("bun.lock");
+    expect(r.findings[0].fix).toContain("bun install");
+  });
+
+  it("does not fire when bun.lock exists", () => {
+    const fs = makeFs({ "/site/package.json": "{}", "/site/bun.lock": "{}" });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-missing")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does not fire on a directory without package.json", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-missing")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: lockfile-drift", () => {
+  it("flags a caret range whose locked version is below the floor", () => {
+    const pkg = JSON.stringify({
+      dependencies: { "@decocms/apps": "^1.11.0" },
+    });
+    const lock = `"@decocms/apps@1.6.2"\n`;
+    const fs = makeFs({
+      "/site/package.json": pkg,
+      "/site/bun.lock": lock,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-drift")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].fix).toContain("@decocms/apps");
+  });
+
+  it("does not flag when locked version satisfies the caret range", () => {
+    const pkg = JSON.stringify({
+      dependencies: { "@decocms/apps": "^1.11.0" },
+    });
+    const lock = `"@decocms/apps@1.13.2"\n`;
+    const fs = makeFs({
+      "/site/package.json": pkg,
+      "/site/bun.lock": lock,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-drift")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags a dep that's missing from bun.lock entirely", () => {
+    const pkg = JSON.stringify({
+      dependencies: { "missing-pkg": "^1.0.0" },
+    });
+    const fs = makeFs({
+      "/site/package.json": pkg,
+      "/site/bun.lock": `"other-pkg@1.0.0"\n`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-drift")!;
+    expect(r.findings).toHaveLength(1);
+  });
+
+  it("treats * / latest / git specs as satisfied by mere presence", () => {
+    const pkg = JSON.stringify({
+      dependencies: {
+        "loose-dep": "*",
+        "latest-dep": "latest",
+      },
+    });
+    const lock = `"loose-dep@9.9.9"\n"latest-dep@0.0.1"\n`;
+    const fs = makeFs({
+      "/site/package.json": pkg,
+      "/site/bun.lock": lock,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-drift")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("considers devDependencies too", () => {
+    const pkg = JSON.stringify({
+      devDependencies: { typescript: "~5.9.0" },
+    });
+    const lock = `"typescript@5.8.0"\n`;
+    const fs = makeFs({
+      "/site/package.json": pkg,
+      "/site/bun.lock": lock,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "lockfile-drift")!;
+    expect(r.findings).toHaveLength(1);
+  });
+
+  it("internals: satisfiesRange handles caret, tilde, exact, and sentinels", () => {
+    const { satisfiesRange } = _internals;
+    expect(satisfiesRange("1.13.2", "^1.11.0")).toBe(true);
+    expect(satisfiesRange("1.6.2", "^1.11.0")).toBe(false);
+    expect(satisfiesRange("2.0.0", "^1.11.0")).toBe(false);
+    expect(satisfiesRange("0.5.3", "^0.5.0")).toBe(true);
+    expect(satisfiesRange("0.6.0", "^0.5.0")).toBe(false);
+    expect(satisfiesRange("5.9.5", "~5.9.0")).toBe(true);
+    expect(satisfiesRange("5.10.0", "~5.9.0")).toBe(false);
+    expect(satisfiesRange("1.2.3", "1.2.3")).toBe(true);
+    expect(satisfiesRange("1.2.4", "1.2.3")).toBe(false);
+    expect(satisfiesRange("1.2.3", "*")).toBeNull();
+    expect(satisfiesRange("1.2.3", "latest")).toBeNull();
+    expect(satisfiesRange("1.2.3", "git+https://...")).toBeNull();
+  });
+});
+
+describe("rule: package-manager-missing", () => {
+  it("fires when packageManager is absent", () => {
+    const fs = makeFs({
+      "/site/package.json": JSON.stringify({ name: "x", license: "MIT" }),
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "package-manager-missing")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].fix).toContain("bun@");
+  });
+
+  it("does not fire when packageManager is set", () => {
+    const fs = makeFs({
+      "/site/package.json": JSON.stringify({
+        name: "x",
+        packageManager: "bun@1.3.5",
+      }),
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "package-manager-missing")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("--fix writes packageManager directly after license, preserving other keys", () => {
+    const initial = JSON.stringify({
+      name: "x",
+      version: "1.0.0",
+      license: "MIT",
+      dependencies: { foo: "^1.0.0" },
+    });
+    const { fs, writer, store } = makeMutableFs({
+      "/site/package.json": initial,
+    });
+    runAudit(SITE, fs, { writer });
+    const updated = JSON.parse(store["/site/package.json"]);
+    expect(updated.packageManager).toMatch(/^bun@/);
+    const keys = Object.keys(updated);
+    expect(keys.indexOf("packageManager")).toBe(keys.indexOf("license") + 1);
+    expect(updated.dependencies).toEqual({ foo: "^1.0.0" });
+  });
+
+  it("--fix appends packageManager when license is absent", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/package.json": JSON.stringify({ name: "x" }),
+    });
+    runAudit(SITE, fs, { writer });
+    const updated = JSON.parse(store["/site/package.json"]);
+    expect(updated.packageManager).toMatch(/^bun@/);
+  });
+});

package/scripts/migrate/templates/lockfile-check-yml.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { generateLockfileCheckYml } from "./lockfile-check-yml";
+
+describe("generateLockfileCheckYml", () => {
+  it("emits a valid GitHub Actions workflow with the bun version pinned", () => {
+    const yaml = generateLockfileCheckYml("1.3.5");
+    expect(yaml).toContain("name: lockfile-check");
+    expect(yaml).toContain("on:");
+    expect(yaml).toContain("pull_request:");
+    expect(yaml).toContain("bun-version: 1.3.5");
+    expect(yaml).toContain("bun install --frozen-lockfile");
+  });
+
+  it("strips an accidental `bun@` prefix from the version input", () => {
+    const yaml = generateLockfileCheckYml("bun@1.3.5");
+    expect(yaml).toContain("bun-version: 1.3.5");
+    expect(yaml).not.toMatch(/bun-version:\s*bun@/);
+  });
+
+  it("scopes the trigger to package.json + bun.lock + the workflow itself", () => {
+    const yaml = generateLockfileCheckYml("1.3.5");
+    expect(yaml).toContain('"package.json"');
+    expect(yaml).toContain('"bun.lock"');
+    expect(yaml).toContain('".github/workflows/lockfile-check.yml"');
+  });
+});

package/scripts/migrate/templates/lockfile-check-yml.ts

@@ -0,0 +1,66 @@
+/**
+ * Generates `.github/workflows/lockfile-check.yml`, the PR-time
+ * guardrail that fails any pull request which would have failed
+ * Cloudflare Workers Builds with `lockfile had changes, but lockfile
+ * is frozen`. This catches drift before it reaches main, instead of
+ * only after deploy attempts.
+ *
+ * Lives in the site repo (per-site, not centralised) because per
+ * D6.3 we are NOT scaffolding caller stubs that pull in
+ * `decocms/deco-start@vN` reusable workflows. The check is small
+ * enough that copy-paste-per-site is the right tradeoff.
+ *
+ * Bun version pinning matches the `packageManager` field in the
+ * scaffolded `package.json` (see `templates/package-json.ts`'s
+ * `CANONICAL_BUN_VERSION`). Kept in lockstep manually for now;
+ * future iterations may consolidate both into a shared constant.
+ */
+export function generateLockfileCheckYml(bunVersion: string): string {
+  const v = stripBunPrefix(bunVersion);
+  return `name: lockfile-check
+
+# PR-time guardrail: re-runs the same install Cloudflare Workers Builds
+# runs on deploy (\`bun install --frozen-lockfile\`). Fails the PR if
+# bun.lock would have rejected the install — closes the loop so drift
+# can never reach main, only to be caught by Workers Builds at deploy
+# time.
+#
+# Pairs with:
+#   - "packageManager": "bun@${v}" in package.json
+#   - .gitignore bans on package-lock.json / yarn.lock / pnpm-lock.yaml
+#   - the deco-post-cleanup audit's lockfile-* rules
+#
+# Adjust \`bun-version\` here in lockstep with the package.json
+# \`packageManager\` field.
+
+on:
+  pull_request:
+    paths:
+      - "package.json"
+      - "bun.lock"
+      - ".github/workflows/lockfile-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  frozen-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${v}
+      - name: bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
+`;
+}
+
+/**
+ * Strip an accidental `bun@` prefix from the version string so the
+ * YAML's `bun-version` input (which expects a bare semver) doesn't
+ * receive `bun@1.3.5`.
+ */
+function stripBunPrefix(input: string): string {
+  return input.replace(/^bun@/, "");
+}

package/scripts/migrate/templates/package-json.ts

@@ -1,6 +1,17 @@
 import { execSync } from "node:child_process";
 import type { MigrationContext } from "../types";
 
+/**
+ * Fleet-wide canonical bun version. Bumped here propagates to all newly
+ * migrated sites via the `packageManager` field AND the
+ * `lockfile-check.yml` workflow's `bun-version` input. See
+ * MIGRATION_TOOLING_PLAN.md for the bun-canonical decision.
+ *
+ * Exported because the lockfile-check workflow template reads it
+ * directly to keep both files in lockstep.
+ */
+export const CANONICAL_BUN_VERSION = "1.3.5";
+
 /**
  * Get the latest published version of an npm package.
  * Falls back to the provided default if the lookup fails.
@@ -120,7 +131,7 @@ export function generatePackageJson(ctx: MigrationContext): string {
       "format:check": 'prettier --check "src/**/*.{ts,tsx}"',
       knip: "knip",
       clean:
-        "rm -rf node_modules .cache dist .wrangler/state node_modules/.vite && npm install",
+        "rm -rf node_modules .cache dist .wrangler/state node_modules/.vite && bun install",
       "tailwind:lint":
         "tsx scripts/tailwind-lint.ts",
       "tailwind:fix":
@@ -128,6 +139,7 @@ export function generatePackageJson(ctx: MigrationContext): string {
     },
     author: "deco.cx",
     license: "MIT",
+    packageManager: `bun@${CANONICAL_BUN_VERSION}`,
     dependencies: {
       "@decocms/apps": `^${appsVersion}`,
       "@decocms/start": `^${startVersion}`,

package/scripts/migrate-post-cleanup.ts

@@ -78,9 +78,11 @@ function showHelp() {
     --fix            Auto-apply mechanical fixes for the safe rules
                      (dead-lib-shims, dead-runtime-shim, local-widgets-types,
                      vtex-shim-regression swap subset, obsolete-vite-plugins,
-                     local-framework-duplicate auto-fixable subset).
-                     Other rules — including htmx-residue and the warn-only
-                     entries of local-framework-duplicate — stay detect-only.
+                     local-framework-duplicate auto-fixable subset,
+                     lockfile-multiple, package-manager-missing).
+                     Other rules — including htmx-residue, lockfile-missing,
+                     lockfile-drift, and the warn-only entries of
+                     local-framework-duplicate — stay detect-only.
     --json           Emit machine-readable JSON instead of pretty text
     --strict         Exit code 2 if any warning-severity findings exist
     --help, -h       Show this help

package/scripts/migrate.ts

@@ -246,11 +246,16 @@ function bootstrap(ctx: { sourceDir: string }) {
     return true;
   };
 
-  // Detect package manager
-  const pm = process.env.npm_execpath?.includes("bun") ? "bun" : "npm";
+  // bun is the fleet-wide canonical package manager for decocms storefronts.
+  // We hardcode it here (instead of sniffing process.env.npm_execpath) so a
+  // freshly-migrated site always commits a bun.lock and never accidentally
+  // ships a package-lock.json that drifts vs bun.lock under CF Workers Builds.
+  // See MIGRATION_TOOLING_PLAN.md and the package-json template for the
+  // matching `packageManager` field that pins the version.
+  const pm = "bun";
   if (!run(`${pm} install`, "Install dependencies", true)) return;
-  run("npx tsx node_modules/@decocms/start/scripts/generate-blocks.ts", "Generate CMS blocks");
-  run("npx tsr generate", "Generate TanStack routes");
+  run("bunx tsx node_modules/@decocms/start/scripts/generate-blocks.ts", "Generate CMS blocks");
+  run("bunx tsr generate", "Generate TanStack routes");
 
   if (failures > 0) {
     console.log(