create-thally-docs 0.10.89 → 0.10.90

package/dist/{chunk-WQMTOYV4.js → chunk-HRCNLXFC.js}

@@ -8,7 +8,7 @@ import {
   installDeps,
   runProjectCommand,
   scaffold
-} from "./chunk-T6HHQNCZ.js";
+} from "./chunk-IX2FP4D5.js";
 import {
   pruneMissingSiteLinks
 } from "./chunk-UG3OXVLE.js";

package/dist/{chunk-T6HHQNCZ.js → chunk-IX2FP4D5.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-J7255UQA.js";
 import {
   downloadStarter
-} from "./chunk-N25GFJOS.js";
+} from "./chunk-VHIX2IYK.js";
 import {
   terminal
 } from "./chunk-L2YCVQBR.js";

package/dist/chunk-J5V4UJXD.js

@@ -0,0 +1,471 @@
+#!/usr/bin/env node
+import {
+  downloadStarter
+} from "./chunk-VHIX2IYK.js";
+import {
+  applyStarterRuntimeSyncPlan,
+  captureTargetPrecondition,
+  mergeStarterOwnershipContracts,
+  parseStarterReleaseManifest,
+  planStarterRuntimeSync,
+  readStarterReleaseManifest,
+  starterManifestSha256
+} from "./chunk-LKI5X3H2.js";
+import {
+  STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES
+} from "./chunk-D7ANFHIL.js";
+
+// src/starter-update.ts
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync
+} from "fs";
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+import { tmpdir } from "os";
+import { join } from "path";
+
+// src/starter-manual-review.ts
+import { isDeepStrictEqual } from "util";
+var STRUCTURED_MANUAL_REVIEW_PATHS = /* @__PURE__ */ new Set([
+  "package.json",
+  "package-lock.json"
+]);
+var MISSING_JSON_VALUE = /* @__PURE__ */ Symbol("missing-json-value");
+function hasSameBytes(left, right) {
+  if (!left || !right) return left === right;
+  return left.equals(right);
+}
+function isJsonObject(value) {
+  return value !== MISSING_JSON_VALUE && value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function escapeJsonPointerSegment(segment) {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function childJsonPointer(pointer, segment) {
+  return `${pointer}/${escapeJsonPointerSegment(segment)}`;
+}
+function sameJsonValue(left, right) {
+  if (left === MISSING_JSON_VALUE || right === MISSING_JSON_VALUE) {
+    return left === right;
+  }
+  return isDeepStrictEqual(left, right);
+}
+function mergeJsonValue(previous, downstream, target, pointer = "") {
+  if (sameJsonValue(downstream, target)) {
+    return { value: downstream, conflicts: [] };
+  }
+  if (sameJsonValue(previous, target)) {
+    return { value: downstream, conflicts: [] };
+  }
+  if (sameJsonValue(previous, downstream)) {
+    return { value: target, conflicts: [] };
+  }
+  if (isJsonObject(previous) && isJsonObject(downstream) && isJsonObject(target)) {
+    const keys = Array.from(
+      /* @__PURE__ */ new Set([
+        ...Object.keys(downstream),
+        ...Object.keys(target),
+        ...Object.keys(previous)
+      ])
+    );
+    const entries = [];
+    const conflicts = [];
+    for (const key of keys) {
+      const merged = mergeJsonValue(
+        Object.hasOwn(previous, key) ? previous[key] : MISSING_JSON_VALUE,
+        Object.hasOwn(downstream, key) ? downstream[key] : MISSING_JSON_VALUE,
+        Object.hasOwn(target, key) ? target[key] : MISSING_JSON_VALUE,
+        childJsonPointer(pointer, key)
+      );
+      conflicts.push(...merged.conflicts);
+      if (merged.value !== MISSING_JSON_VALUE) {
+        entries.push([key, merged.value]);
+      }
+    }
+    return { value: Object.fromEntries(entries), conflicts };
+  }
+  return { value: downstream, conflicts: [pointer || "/"] };
+}
+function mergeStructuredManualReviewFile(input) {
+  try {
+    const previous = JSON.parse(input.previous.toString("utf8"));
+    const downstream = JSON.parse(
+      input.downstream.toString("utf8")
+    );
+    const target = JSON.parse(input.target.toString("utf8"));
+    const merged = mergeJsonValue(previous, downstream, target);
+    if (merged.conflicts.length > 0 || merged.value === MISSING_JSON_VALUE) {
+      return { conflicts: merged.conflicts };
+    }
+    return {
+      content: Buffer.from(`${JSON.stringify(merged.value, null, 2)}
+`),
+      conflicts: []
+    };
+  } catch {
+    return { conflicts: ["/"] };
+  }
+}
+function resolveManualReviewMutations(paths, downstreamFiles, previousReleaseFiles, targetReleaseFiles) {
+  const mutations = {
+    writeFiles: /* @__PURE__ */ new Map(),
+    deletePaths: [],
+    conflicts: []
+  };
+  for (const path of paths) {
+    const downstream = downstreamFiles.get(path);
+    const previous = previousReleaseFiles.get(path);
+    const target = targetReleaseFiles.get(path);
+    if (hasSameBytes(previous, target) || hasSameBytes(downstream, target)) {
+      continue;
+    }
+    if (hasSameBytes(downstream, previous)) {
+      if (target) mutations.writeFiles.set(path, target);
+      else mutations.deletePaths.push(path);
+      continue;
+    }
+    if (STRUCTURED_MANUAL_REVIEW_PATHS.has(path) && downstream && previous && target) {
+      const merged = mergeStructuredManualReviewFile({
+        previous,
+        downstream,
+        target
+      });
+      if (merged.content) {
+        if (!hasSameBytes(downstream, merged.content)) {
+          mutations.writeFiles.set(path, merged.content);
+        }
+        continue;
+      }
+      mutations.conflicts.push({ path, fields: merged.conflicts });
+      continue;
+    }
+    mutations.conflicts.push({ path, fields: [] });
+  }
+  return mutations;
+}
+
+// src/starter-update.ts
+var EMPTY_PLAN = {
+  copyPaths: [],
+  deletePaths: [],
+  conflictPaths: [],
+  manualReviewPaths: [],
+  preservedPaths: [],
+  unchangedPaths: [],
+  targetPreconditions: {}
+};
+function readDownstreamManifest(targetDir, manifestPath) {
+  const path = join(targetDir, manifestPath);
+  if (!existsSync(path)) {
+    throw new Error(
+      `This project has no ${manifestPath}; update it from a versioned Thally starter first.`
+    );
+  }
+  const entry = lstatSync(path);
+  if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 256 * 1024) {
+    throw new Error("The project starter manifest must be a bounded regular file.");
+  }
+  return readFileSync(path, "utf8");
+}
+function resolveStarterReleaseFromManifest(source, releases = SUPPORTED_SCAFFOLD_RELEASES) {
+  const hash = starterManifestSha256(source);
+  const matching = releases.filter(
+    (release) => release.source.manifestSha256 === hash
+  );
+  if (matching.length !== 1) {
+    throw new Error(
+      "The project starter manifest is edited, unknown, or ambiguously registered; refusing to update."
+    );
+  }
+  parseStarterReleaseManifest(source, matching[0]);
+  return matching[0];
+}
+function starterReleaseProviderError(cause) {
+  return Object.assign(new Error("The public starter release provider is unavailable.", { cause }), {
+    name: "StarterReleaseProviderError",
+    code: "STARTER_RELEASE_PROVIDER_UNAVAILABLE"
+  });
+}
+async function fetchStarterReleaseHint(runtimeCommitSha) {
+  if (!/^[a-f0-9]{40}$/.test(runtimeCommitSha)) return void 0;
+  let response;
+  try {
+    response = await fetch(
+      `https://raw.githubusercontent.com/thallylabs/thally/${runtimeCommitSha}/packages/create-thally-docs/src/stable-scaffold-release.json`,
+      { signal: AbortSignal.timeout(15e3), redirect: "error" }
+    );
+  } catch (error) {
+    throw starterReleaseProviderError(error);
+  }
+  if (response.status === 404) return void 0;
+  if (!response.ok || !response.body) throw starterReleaseProviderError();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        throw starterReleaseProviderError(error);
+      }
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 256 * 1024) return void 0;
+      chunks.push(chunk.value);
+    }
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    } catch {
+      return void 0;
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+}
+function comparableManifest(source) {
+  const manifest = JSON.parse(source);
+  const runtime = manifest.runtime;
+  if (!runtime || typeof runtime !== "object" || Array.isArray(runtime)) return void 0;
+  const runtimeContract = { ...runtime };
+  delete runtimeContract.commitSha;
+  delete runtimeContract.treeSha;
+  return { ...manifest, runtime: runtimeContract };
+}
+function assertRecoveryPackages(targetDir, baselineDir, packages) {
+  const installed = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf8"));
+  const declarations = { ...installed.dependencies, ...installed.devDependencies };
+  for (const [name, version] of Object.entries(packages)) {
+    if (declarations[name] !== version) throw new Error("Installed starter packages do not match the recovery baseline.");
+  }
+  if (existsSync(join(baselineDir, "package-lock.json"))) {
+    const canonical = JSON.parse(readFileSync(join(baselineDir, "package-lock.json"), "utf8"));
+    const current = JSON.parse(readFileSync(join(targetDir, "package-lock.json"), "utf8"));
+    for (const name of Object.keys(packages)) {
+      const path = `node_modules/${name}`;
+      const expected = canonical.packages?.[path];
+      if (!expected?.version || !isDeepStrictEqual2(current.packages?.[path], expected)) {
+        throw new Error("Installed starter package lock does not match the recovery baseline.");
+      }
+    }
+  }
+}
+async function resolveStarterUpdateBase(options) {
+  const releases = options.releases ?? SUPPORTED_SCAFFOLD_RELEASES;
+  const manifestPath = STABLE_SCAFFOLD_RELEASE.source.manifestPath;
+  const source = readDownstreamManifest(options.targetDir, manifestPath);
+  const manifestSha256 = starterManifestSha256(source);
+  const exact = releases.filter((release) => release.source.manifestSha256 === manifestSha256);
+  if (exact.length) return { release: resolveStarterReleaseFromManifest(source, releases), recoveredProvenance: false, manifestSha256 };
+  if (Buffer.byteLength(source, "utf8") > 256 * 1024) throw new Error("The project starter manifest is too large.");
+  let candidate;
+  try {
+    candidate = JSON.parse(source);
+  } catch {
+    throw new Error("The project starter manifest is invalid JSON.");
+  }
+  const runtime = candidate?.runtime;
+  if (!runtime || typeof runtime.commitSha !== "string" || !/^[a-f0-9]{40}$/.test(runtime.commitSha) || typeof runtime.treeSha !== "string" || !/^[a-f0-9]{40}$/.test(runtime.treeSha)) {
+    throw new Error("The project starter manifest has no verifiable recovery baseline.");
+  }
+  let candidates = releases.filter((release) => release.runtime.commitSha === runtime.commitSha);
+  if (!candidates.length) {
+    const hint = await (options.resolveReleaseHint ?? fetchStarterReleaseHint)(runtime.commitSha);
+    const record = hint;
+    candidates = releases.filter((release) => record?.id === release.id && record.source?.commitSha === release.source.commitSha);
+  }
+  const download = options.download ?? (async (directory, release) => {
+    await downloadStarter(directory, void 0, release, { announce: false });
+  });
+  const workspace = mkdtempSync(join(tmpdir(), "thally-starter-base-"));
+  try {
+    for (const [index, release] of candidates.entries()) {
+      const baselineDir = join(workspace, String(index));
+      mkdirSync(baselineDir);
+      await download(baselineDir, release);
+      const baseline = readStarterReleaseManifest(baselineDir, release);
+      const canonicalSource = readFileSync(join(baselineDir, manifestPath), "utf8");
+      if (!isDeepStrictEqual2(comparableManifest(source), comparableManifest(canonicalSource))) continue;
+      const ownership = mergeStarterOwnershipContracts(baseline.ownership, baseline.ownership);
+      const proof = planStarterRuntimeSync(baselineDir, baselineDir, options.targetDir, ownership);
+      if (proof.copyPaths.length || proof.deletePaths.length || proof.preservedPaths.length || proof.conflictPaths.length) continue;
+      assertRecoveryPackages(options.targetDir, baselineDir, baseline.packages);
+      return { release, recoveredProvenance: true, manifestSha256 };
+    }
+    throw new Error("The project starter manifest is edited, unknown, or has no verified published framework baseline; refusing to update.");
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+function assertForwardRelease(previous, target, releases) {
+  if (previous.source.repository !== target.source.repository || previous.source.manifestPath !== target.source.manifestPath) {
+    throw new Error("Starter updates cannot cross repository or manifest contracts.");
+  }
+  if (previous.source.commitSha === target.source.commitSha) return;
+  if (previous.starterVersion > target.starterVersion) {
+    throw new Error("The installed CLI does not contain a newer starter release.");
+  }
+  if (previous.starterVersion === target.starterVersion) {
+    const targetIndex = releases.findIndex(
+      (release) => release.source.commitSha === target.source.commitSha
+    );
+    const previousIndex = releases.findIndex(
+      (release) => release.source.commitSha === previous.source.commitSha
+    );
+    if (targetIndex === -1 || previousIndex === -1 || previousIndex <= targetIndex) {
+      throw new Error("The installed CLI does not contain a newer starter release.");
+    }
+  }
+}
+async function updateStarterProject(options) {
+  const targetRelease = options.targetRelease ?? STABLE_SCAFFOLD_RELEASE;
+  const releases = options.releases ?? SUPPORTED_SCAFFOLD_RELEASES;
+  if (!releases.some((release) => isDeepStrictEqual2(release, targetRelease))) {
+    throw new Error("The target starter release is not in the trusted release catalog.");
+  }
+  const manifestPath = targetRelease.source.manifestPath;
+  const downstreamManifest = readDownstreamManifest(options.targetDir, manifestPath);
+  const base = await resolveStarterUpdateBase({ ...options, releases });
+  const previousRelease = base.release;
+  if (base.manifestSha256 !== starterManifestSha256(downstreamManifest) || readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
+    throw new Error("The project starter manifest changed during update planning.");
+  }
+  assertForwardRelease(previousRelease, targetRelease, releases);
+  if (!base.recoveredProvenance && previousRelease.source.commitSha === targetRelease.source.commitSha) {
+    return {
+      previousRelease,
+      targetRelease,
+      plan: EMPTY_PLAN,
+      isUpToDate: true,
+      applied: false
+    };
+  }
+  if (options.apply && !options.confirmed) {
+    throw new Error("Pass explicit confirmation before applying a starter update.");
+  }
+  const workspace = mkdtempSync(join(tmpdir(), "thally-starter-update-"));
+  const oldStarterDir = join(workspace, "old");
+  const newStarterDir = join(workspace, "new");
+  mkdirSync(oldStarterDir);
+  mkdirSync(newStarterDir);
+  const download = options.download ?? (async (targetDir, release) => {
+    await downloadStarter(targetDir, void 0, release, { announce: false });
+  });
+  try {
+    await download(oldStarterDir, previousRelease);
+    await download(newStarterDir, targetRelease);
+    const oldManifest = readStarterReleaseManifest(oldStarterDir, previousRelease);
+    const newManifest = readStarterReleaseManifest(newStarterDir, targetRelease);
+    const ownership = mergeStarterOwnershipContracts(
+      oldManifest.ownership,
+      newManifest.ownership
+    );
+    if (base.recoveredProvenance) {
+      const proof = planStarterRuntimeSync(
+        oldStarterDir,
+        oldStarterDir,
+        options.targetDir,
+        mergeStarterOwnershipContracts(oldManifest.ownership, oldManifest.ownership)
+      );
+      if (proof.copyPaths.length || proof.deletePaths.length || proof.preservedPaths.length || proof.conflictPaths.length) {
+        throw new Error("The recovery framework changed during update planning.");
+      }
+      assertRecoveryPackages(options.targetDir, oldStarterDir, oldManifest.packages);
+    }
+    if (readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
+      throw new Error("The project starter manifest changed during update planning.");
+    }
+    const plan = planStarterRuntimeSync(
+      oldStarterDir,
+      newStarterDir,
+      options.targetDir,
+      ownership
+    );
+    const allManualPreconditions = Object.fromEntries(plan.manualReviewPaths.map((path) => [
+      path,
+      captureTargetPrecondition(join(options.targetDir, path))
+    ]));
+    const readManualFiles = (root) => new Map(
+      plan.manualReviewPaths.filter((path) => existsSync(join(root, path))).map((path) => {
+        const entry = lstatSync(join(root, path));
+        if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Manual starter updates require regular files.");
+        return [path, readFileSync(join(root, path))];
+      })
+    );
+    const manual = resolveManualReviewMutations(
+      plan.manualReviewPaths,
+      readManualFiles(options.targetDir),
+      readManualFiles(oldStarterDir),
+      readManualFiles(newStarterDir)
+    );
+    const resolvedManualPaths = [...manual.writeFiles.keys(), ...manual.deletePaths].sort();
+    const manualPreconditions = Object.fromEntries(resolvedManualPaths.map((path) => [
+      path,
+      allManualPreconditions[path]
+    ]));
+    plan.conflictPaths = [.../* @__PURE__ */ new Set([...plan.conflictPaths, ...manual.conflicts.map((conflict) => conflict.path)])].sort();
+    plan.manualReviewPaths = manual.conflicts.map((conflict) => conflict.path);
+    if (!options.apply) {
+      return {
+        previousRelease,
+        targetRelease,
+        plan,
+        isUpToDate: false,
+        applied: false,
+        recoveredProvenance: base.recoveredProvenance,
+        manualConflicts: manual.conflicts,
+        resolvedManualPaths,
+        deletedManualPaths: manual.deletePaths
+      };
+    }
+    if (plan.conflictPaths.length > 0) {
+      throw new Error("Resolve starter synchronization conflicts before applying.");
+    }
+    if (readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
+      throw new Error("The project starter manifest changed during update planning.");
+    }
+    applyStarterRuntimeSyncPlan(
+      newStarterDir,
+      options.targetDir,
+      plan,
+      ownership,
+      {
+        confirmed: true,
+        manualMutations: { ...manual, targetPreconditions: manualPreconditions },
+        provenance: {
+          sourcePath: join(newStarterDir, manifestPath),
+          targetPath: join(options.targetDir, manifestPath),
+          expectedSha256: base.manifestSha256
+        }
+      }
+    );
+    return {
+      previousRelease,
+      targetRelease,
+      plan,
+      isUpToDate: false,
+      applied: true,
+      recoveredProvenance: base.recoveredProvenance,
+      manualConflicts: manual.conflicts,
+      resolvedManualPaths,
+      deletedManualPaths: manual.deletePaths
+    };
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+
+export {
+  resolveManualReviewMutations,
+  resolveStarterReleaseFromManifest,
+  starterReleaseProviderError,
+  fetchStarterReleaseHint,
+  resolveStarterUpdateBase,
+  updateStarterProject
+};

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "./chunk-WQMTOYV4.js";
+} from "./chunk-HRCNLXFC.js";
 import {
   parseFrontmatter,
   runCheck
@@ -13,17 +13,17 @@ import {
   scaffold,
   slugify,
   success
-} from "./chunk-T6HHQNCZ.js";
+} from "./chunk-IX2FP4D5.js";
 import "./chunk-UG3OXVLE.js";
 import "./chunk-J7255UQA.js";
-import "./chunk-N25GFJOS.js";
-import "./chunk-LKI5X3H2.js";
-import "./chunk-D7ANFHIL.js";
+import "./chunk-VHIX2IYK.js";
 import {
   acquireTerminalAccent,
   formatHelp,
   terminal
 } from "./chunk-L2YCVQBR.js";
+import "./chunk-LKI5X3H2.js";
+import "./chunk-D7ANFHIL.js";
 
 // src/index.ts
 import { existsSync as existsSync2, readdirSync } from "fs";

package/dist/migrate/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "../chunk-WQMTOYV4.js";
+} from "../chunk-HRCNLXFC.js";
 import "../chunk-KDLP27DS.js";
-import "../chunk-T6HHQNCZ.js";
+import "../chunk-IX2FP4D5.js";
 import "../chunk-UG3OXVLE.js";
 import "../chunk-J7255UQA.js";
-import "../chunk-N25GFJOS.js";
+import "../chunk-VHIX2IYK.js";
+import "../chunk-L2YCVQBR.js";
 import "../chunk-LKI5X3H2.js";
 import "../chunk-D7ANFHIL.js";
-import "../chunk-L2YCVQBR.js";
 export {
   migrateDocs
 };

package/dist/scaffold.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   scaffold
-} from "./chunk-T6HHQNCZ.js";
+} from "./chunk-IX2FP4D5.js";
 import "./chunk-UG3OXVLE.js";
 import "./chunk-J7255UQA.js";
 import {
@@ -9,12 +9,12 @@ import {
   STARTER_COMMIT_SHA,
   STARTER_REPOSITORY,
   validateStarterArchiveEntry
-} from "./chunk-N25GFJOS.js";
+} from "./chunk-VHIX2IYK.js";
+import "./chunk-L2YCVQBR.js";
 import "./chunk-LKI5X3H2.js";
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-D7ANFHIL.js";
-import "./chunk-L2YCVQBR.js";
 export {
   STABLE_SCAFFOLD_RELEASE,
   STARTER_ARCHIVE_ROOT,

package/dist/starter-update.js

@@ -1,466 +1,16 @@
 #!/usr/bin/env node
 import {
-  downloadStarter
-} from "./chunk-N25GFJOS.js";
-import {
-  applyStarterRuntimeSyncPlan,
-  captureTargetPrecondition,
-  mergeStarterOwnershipContracts,
-  parseStarterReleaseManifest,
-  planStarterRuntimeSync,
-  readStarterReleaseManifest,
-  starterManifestSha256
-} from "./chunk-LKI5X3H2.js";
-import {
-  STABLE_SCAFFOLD_RELEASE,
-  SUPPORTED_SCAFFOLD_RELEASES
-} from "./chunk-D7ANFHIL.js";
+  fetchStarterReleaseHint,
+  resolveManualReviewMutations,
+  resolveStarterReleaseFromManifest,
+  resolveStarterUpdateBase,
+  starterReleaseProviderError,
+  updateStarterProject
+} from "./chunk-J5V4UJXD.js";
+import "./chunk-VHIX2IYK.js";
 import "./chunk-L2YCVQBR.js";
-
-// src/starter-update.ts
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync
-} from "fs";
-import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
-import { tmpdir } from "os";
-import { join } from "path";
-
-// src/starter-manual-review.ts
-import { isDeepStrictEqual } from "util";
-var STRUCTURED_MANUAL_REVIEW_PATHS = /* @__PURE__ */ new Set([
-  "package.json",
-  "package-lock.json"
-]);
-var MISSING_JSON_VALUE = /* @__PURE__ */ Symbol("missing-json-value");
-function hasSameBytes(left, right) {
-  if (!left || !right) return left === right;
-  return left.equals(right);
-}
-function isJsonObject(value) {
-  return value !== MISSING_JSON_VALUE && value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function escapeJsonPointerSegment(segment) {
-  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
-}
-function childJsonPointer(pointer, segment) {
-  return `${pointer}/${escapeJsonPointerSegment(segment)}`;
-}
-function sameJsonValue(left, right) {
-  if (left === MISSING_JSON_VALUE || right === MISSING_JSON_VALUE) {
-    return left === right;
-  }
-  return isDeepStrictEqual(left, right);
-}
-function mergeJsonValue(previous, downstream, target, pointer = "") {
-  if (sameJsonValue(downstream, target)) {
-    return { value: downstream, conflicts: [] };
-  }
-  if (sameJsonValue(previous, target)) {
-    return { value: downstream, conflicts: [] };
-  }
-  if (sameJsonValue(previous, downstream)) {
-    return { value: target, conflicts: [] };
-  }
-  if (isJsonObject(previous) && isJsonObject(downstream) && isJsonObject(target)) {
-    const keys = Array.from(
-      /* @__PURE__ */ new Set([
-        ...Object.keys(downstream),
-        ...Object.keys(target),
-        ...Object.keys(previous)
-      ])
-    );
-    const entries = [];
-    const conflicts = [];
-    for (const key of keys) {
-      const merged = mergeJsonValue(
-        Object.hasOwn(previous, key) ? previous[key] : MISSING_JSON_VALUE,
-        Object.hasOwn(downstream, key) ? downstream[key] : MISSING_JSON_VALUE,
-        Object.hasOwn(target, key) ? target[key] : MISSING_JSON_VALUE,
-        childJsonPointer(pointer, key)
-      );
-      conflicts.push(...merged.conflicts);
-      if (merged.value !== MISSING_JSON_VALUE) {
-        entries.push([key, merged.value]);
-      }
-    }
-    return { value: Object.fromEntries(entries), conflicts };
-  }
-  return { value: downstream, conflicts: [pointer || "/"] };
-}
-function mergeStructuredManualReviewFile(input) {
-  try {
-    const previous = JSON.parse(input.previous.toString("utf8"));
-    const downstream = JSON.parse(
-      input.downstream.toString("utf8")
-    );
-    const target = JSON.parse(input.target.toString("utf8"));
-    const merged = mergeJsonValue(previous, downstream, target);
-    if (merged.conflicts.length > 0 || merged.value === MISSING_JSON_VALUE) {
-      return { conflicts: merged.conflicts };
-    }
-    return {
-      content: Buffer.from(`${JSON.stringify(merged.value, null, 2)}
-`),
-      conflicts: []
-    };
-  } catch {
-    return { conflicts: ["/"] };
-  }
-}
-function resolveManualReviewMutations(paths, downstreamFiles, previousReleaseFiles, targetReleaseFiles) {
-  const mutations = {
-    writeFiles: /* @__PURE__ */ new Map(),
-    deletePaths: [],
-    conflicts: []
-  };
-  for (const path of paths) {
-    const downstream = downstreamFiles.get(path);
-    const previous = previousReleaseFiles.get(path);
-    const target = targetReleaseFiles.get(path);
-    if (hasSameBytes(previous, target) || hasSameBytes(downstream, target)) {
-      continue;
-    }
-    if (hasSameBytes(downstream, previous)) {
-      if (target) mutations.writeFiles.set(path, target);
-      else mutations.deletePaths.push(path);
-      continue;
-    }
-    if (STRUCTURED_MANUAL_REVIEW_PATHS.has(path) && downstream && previous && target) {
-      const merged = mergeStructuredManualReviewFile({
-        previous,
-        downstream,
-        target
-      });
-      if (merged.content) {
-        if (!hasSameBytes(downstream, merged.content)) {
-          mutations.writeFiles.set(path, merged.content);
-        }
-        continue;
-      }
-      mutations.conflicts.push({ path, fields: merged.conflicts });
-      continue;
-    }
-    mutations.conflicts.push({ path, fields: [] });
-  }
-  return mutations;
-}
-
-// src/starter-update.ts
-var EMPTY_PLAN = {
-  copyPaths: [],
-  deletePaths: [],
-  conflictPaths: [],
-  manualReviewPaths: [],
-  preservedPaths: [],
-  unchangedPaths: [],
-  targetPreconditions: {}
-};
-function readDownstreamManifest(targetDir, manifestPath) {
-  const path = join(targetDir, manifestPath);
-  if (!existsSync(path)) {
-    throw new Error(
-      `This project has no ${manifestPath}; update it from a versioned Thally starter first.`
-    );
-  }
-  const entry = lstatSync(path);
-  if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 256 * 1024) {
-    throw new Error("The project starter manifest must be a bounded regular file.");
-  }
-  return readFileSync(path, "utf8");
-}
-function resolveStarterReleaseFromManifest(source, releases = SUPPORTED_SCAFFOLD_RELEASES) {
-  const hash = starterManifestSha256(source);
-  const matching = releases.filter(
-    (release) => release.source.manifestSha256 === hash
-  );
-  if (matching.length !== 1) {
-    throw new Error(
-      "The project starter manifest is edited, unknown, or ambiguously registered; refusing to update."
-    );
-  }
-  parseStarterReleaseManifest(source, matching[0]);
-  return matching[0];
-}
-function starterReleaseProviderError(cause) {
-  return Object.assign(new Error("The public starter release provider is unavailable.", { cause }), {
-    name: "StarterReleaseProviderError",
-    code: "STARTER_RELEASE_PROVIDER_UNAVAILABLE"
-  });
-}
-async function fetchStarterReleaseHint(runtimeCommitSha) {
-  if (!/^[a-f0-9]{40}$/.test(runtimeCommitSha)) return void 0;
-  let response;
-  try {
-    response = await fetch(
-      `https://raw.githubusercontent.com/thallylabs/thally/${runtimeCommitSha}/packages/create-thally-docs/src/stable-scaffold-release.json`,
-      { signal: AbortSignal.timeout(15e3), redirect: "error" }
-    );
-  } catch (error) {
-    throw starterReleaseProviderError(error);
-  }
-  if (response.status === 404) return void 0;
-  if (!response.ok || !response.body) throw starterReleaseProviderError();
-  const reader = response.body.getReader();
-  const chunks = [];
-  let size = 0;
-  try {
-    while (true) {
-      let chunk;
-      try {
-        chunk = await reader.read();
-      } catch (error) {
-        throw starterReleaseProviderError(error);
-      }
-      if (chunk.done) break;
-      size += chunk.value.byteLength;
-      if (size > 256 * 1024) return void 0;
-      chunks.push(chunk.value);
-    }
-    try {
-      return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-    } catch {
-      return void 0;
-    }
-  } finally {
-    await reader.cancel().catch(() => void 0);
-  }
-}
-function comparableManifest(source) {
-  const manifest = JSON.parse(source);
-  const runtime = manifest.runtime;
-  if (!runtime || typeof runtime !== "object" || Array.isArray(runtime)) return void 0;
-  const runtimeContract = { ...runtime };
-  delete runtimeContract.commitSha;
-  delete runtimeContract.treeSha;
-  return { ...manifest, runtime: runtimeContract };
-}
-function assertRecoveryPackages(targetDir, baselineDir, packages) {
-  const installed = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf8"));
-  const declarations = { ...installed.dependencies, ...installed.devDependencies };
-  for (const [name, version] of Object.entries(packages)) {
-    if (declarations[name] !== version) throw new Error("Installed starter packages do not match the recovery baseline.");
-  }
-  if (existsSync(join(baselineDir, "package-lock.json"))) {
-    const canonical = JSON.parse(readFileSync(join(baselineDir, "package-lock.json"), "utf8"));
-    const current = JSON.parse(readFileSync(join(targetDir, "package-lock.json"), "utf8"));
-    for (const name of Object.keys(packages)) {
-      const path = `node_modules/${name}`;
-      const expected = canonical.packages?.[path];
-      if (!expected?.version || !isDeepStrictEqual2(current.packages?.[path], expected)) {
-        throw new Error("Installed starter package lock does not match the recovery baseline.");
-      }
-    }
-  }
-}
-async function resolveStarterUpdateBase(options) {
-  const releases = options.releases ?? SUPPORTED_SCAFFOLD_RELEASES;
-  const manifestPath = STABLE_SCAFFOLD_RELEASE.source.manifestPath;
-  const source = readDownstreamManifest(options.targetDir, manifestPath);
-  const manifestSha256 = starterManifestSha256(source);
-  const exact = releases.filter((release) => release.source.manifestSha256 === manifestSha256);
-  if (exact.length) return { release: resolveStarterReleaseFromManifest(source, releases), recoveredProvenance: false, manifestSha256 };
-  if (Buffer.byteLength(source, "utf8") > 256 * 1024) throw new Error("The project starter manifest is too large.");
-  let candidate;
-  try {
-    candidate = JSON.parse(source);
-  } catch {
-    throw new Error("The project starter manifest is invalid JSON.");
-  }
-  const runtime = candidate?.runtime;
-  if (!runtime || typeof runtime.commitSha !== "string" || !/^[a-f0-9]{40}$/.test(runtime.commitSha) || typeof runtime.treeSha !== "string" || !/^[a-f0-9]{40}$/.test(runtime.treeSha)) {
-    throw new Error("The project starter manifest has no verifiable recovery baseline.");
-  }
-  let candidates = releases.filter((release) => release.runtime.commitSha === runtime.commitSha);
-  if (!candidates.length) {
-    const hint = await (options.resolveReleaseHint ?? fetchStarterReleaseHint)(runtime.commitSha);
-    const record = hint;
-    candidates = releases.filter((release) => record?.id === release.id && record.source?.commitSha === release.source.commitSha);
-  }
-  const download = options.download ?? (async (directory, release) => {
-    await downloadStarter(directory, void 0, release, { announce: false });
-  });
-  const workspace = mkdtempSync(join(tmpdir(), "thally-starter-base-"));
-  try {
-    for (const [index, release] of candidates.entries()) {
-      const baselineDir = join(workspace, String(index));
-      mkdirSync(baselineDir);
-      await download(baselineDir, release);
-      const baseline = readStarterReleaseManifest(baselineDir, release);
-      const canonicalSource = readFileSync(join(baselineDir, manifestPath), "utf8");
-      if (!isDeepStrictEqual2(comparableManifest(source), comparableManifest(canonicalSource))) continue;
-      const ownership = mergeStarterOwnershipContracts(baseline.ownership, baseline.ownership);
-      const proof = planStarterRuntimeSync(baselineDir, baselineDir, options.targetDir, ownership);
-      if (proof.copyPaths.length || proof.deletePaths.length || proof.preservedPaths.length || proof.conflictPaths.length) continue;
-      assertRecoveryPackages(options.targetDir, baselineDir, baseline.packages);
-      return { release, recoveredProvenance: true, manifestSha256 };
-    }
-    throw new Error("The project starter manifest is edited, unknown, or has no verified published framework baseline; refusing to update.");
-  } finally {
-    rmSync(workspace, { recursive: true, force: true });
-  }
-}
-function assertForwardRelease(previous, target, releases) {
-  if (previous.source.repository !== target.source.repository || previous.source.manifestPath !== target.source.manifestPath) {
-    throw new Error("Starter updates cannot cross repository or manifest contracts.");
-  }
-  if (previous.source.commitSha === target.source.commitSha) return;
-  if (previous.starterVersion > target.starterVersion) {
-    throw new Error("The installed CLI does not contain a newer starter release.");
-  }
-  if (previous.starterVersion === target.starterVersion) {
-    const targetIndex = releases.findIndex(
-      (release) => release.source.commitSha === target.source.commitSha
-    );
-    const previousIndex = releases.findIndex(
-      (release) => release.source.commitSha === previous.source.commitSha
-    );
-    if (targetIndex === -1 || previousIndex === -1 || previousIndex <= targetIndex) {
-      throw new Error("The installed CLI does not contain a newer starter release.");
-    }
-  }
-}
-async function updateStarterProject(options) {
-  const targetRelease = options.targetRelease ?? STABLE_SCAFFOLD_RELEASE;
-  const releases = options.releases ?? SUPPORTED_SCAFFOLD_RELEASES;
-  if (!releases.some((release) => isDeepStrictEqual2(release, targetRelease))) {
-    throw new Error("The target starter release is not in the trusted release catalog.");
-  }
-  const manifestPath = targetRelease.source.manifestPath;
-  const downstreamManifest = readDownstreamManifest(options.targetDir, manifestPath);
-  const base = await resolveStarterUpdateBase({ ...options, releases });
-  const previousRelease = base.release;
-  if (base.manifestSha256 !== starterManifestSha256(downstreamManifest) || readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
-    throw new Error("The project starter manifest changed during update planning.");
-  }
-  assertForwardRelease(previousRelease, targetRelease, releases);
-  if (!base.recoveredProvenance && previousRelease.source.commitSha === targetRelease.source.commitSha) {
-    return {
-      previousRelease,
-      targetRelease,
-      plan: EMPTY_PLAN,
-      isUpToDate: true,
-      applied: false
-    };
-  }
-  if (options.apply && !options.confirmed) {
-    throw new Error("Pass explicit confirmation before applying a starter update.");
-  }
-  const workspace = mkdtempSync(join(tmpdir(), "thally-starter-update-"));
-  const oldStarterDir = join(workspace, "old");
-  const newStarterDir = join(workspace, "new");
-  mkdirSync(oldStarterDir);
-  mkdirSync(newStarterDir);
-  const download = options.download ?? (async (targetDir, release) => {
-    await downloadStarter(targetDir, void 0, release, { announce: false });
-  });
-  try {
-    await download(oldStarterDir, previousRelease);
-    await download(newStarterDir, targetRelease);
-    const oldManifest = readStarterReleaseManifest(oldStarterDir, previousRelease);
-    const newManifest = readStarterReleaseManifest(newStarterDir, targetRelease);
-    const ownership = mergeStarterOwnershipContracts(
-      oldManifest.ownership,
-      newManifest.ownership
-    );
-    if (base.recoveredProvenance) {
-      const proof = planStarterRuntimeSync(
-        oldStarterDir,
-        oldStarterDir,
-        options.targetDir,
-        mergeStarterOwnershipContracts(oldManifest.ownership, oldManifest.ownership)
-      );
-      if (proof.copyPaths.length || proof.deletePaths.length || proof.preservedPaths.length || proof.conflictPaths.length) {
-        throw new Error("The recovery framework changed during update planning.");
-      }
-      assertRecoveryPackages(options.targetDir, oldStarterDir, oldManifest.packages);
-    }
-    if (readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
-      throw new Error("The project starter manifest changed during update planning.");
-    }
-    const plan = planStarterRuntimeSync(
-      oldStarterDir,
-      newStarterDir,
-      options.targetDir,
-      ownership
-    );
-    const allManualPreconditions = Object.fromEntries(plan.manualReviewPaths.map((path) => [
-      path,
-      captureTargetPrecondition(join(options.targetDir, path))
-    ]));
-    const readManualFiles = (root) => new Map(
-      plan.manualReviewPaths.filter((path) => existsSync(join(root, path))).map((path) => {
-        const entry = lstatSync(join(root, path));
-        if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Manual starter updates require regular files.");
-        return [path, readFileSync(join(root, path))];
-      })
-    );
-    const manual = resolveManualReviewMutations(
-      plan.manualReviewPaths,
-      readManualFiles(options.targetDir),
-      readManualFiles(oldStarterDir),
-      readManualFiles(newStarterDir)
-    );
-    const resolvedManualPaths = [...manual.writeFiles.keys(), ...manual.deletePaths].sort();
-    const manualPreconditions = Object.fromEntries(resolvedManualPaths.map((path) => [
-      path,
-      allManualPreconditions[path]
-    ]));
-    plan.conflictPaths = [.../* @__PURE__ */ new Set([...plan.conflictPaths, ...manual.conflicts.map((conflict) => conflict.path)])].sort();
-    plan.manualReviewPaths = manual.conflicts.map((conflict) => conflict.path);
-    if (!options.apply) {
-      return {
-        previousRelease,
-        targetRelease,
-        plan,
-        isUpToDate: false,
-        applied: false,
-        recoveredProvenance: base.recoveredProvenance,
-        manualConflicts: manual.conflicts,
-        resolvedManualPaths,
-        deletedManualPaths: manual.deletePaths
-      };
-    }
-    if (plan.conflictPaths.length > 0) {
-      throw new Error("Resolve starter synchronization conflicts before applying.");
-    }
-    if (readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
-      throw new Error("The project starter manifest changed during update planning.");
-    }
-    applyStarterRuntimeSyncPlan(
-      newStarterDir,
-      options.targetDir,
-      plan,
-      ownership,
-      {
-        confirmed: true,
-        manualMutations: { ...manual, targetPreconditions: manualPreconditions },
-        provenance: {
-          sourcePath: join(newStarterDir, manifestPath),
-          targetPath: join(options.targetDir, manifestPath),
-          expectedSha256: base.manifestSha256
-        }
-      }
-    );
-    return {
-      previousRelease,
-      targetRelease,
-      plan,
-      isUpToDate: false,
-      applied: true,
-      recoveredProvenance: base.recoveredProvenance,
-      manualConflicts: manual.conflicts,
-      resolvedManualPaths,
-      deletedManualPaths: manual.deletePaths
-    };
-  } finally {
-    rmSync(workspace, { recursive: true, force: true });
-  }
-}
+import "./chunk-LKI5X3H2.js";
+import "./chunk-D7ANFHIL.js";
 export {
   fetchStarterReleaseHint,
   resolveManualReviewMutations,

package/dist/starter-upgrade-canary.d.ts

@@ -0,0 +1,18 @@
+import { ScaffoldRelease } from './release.js';
+import { StarterUpdateDownload } from './starter-update.js';
+import './starter-sync.js';
+
+/** Immutable candidate and trusted historical baselines used by release gates. */
+interface UpgradeCanaryOptions {
+    target: ScaffoldRelease;
+    candidateDirectory: string;
+    releases?: readonly ScaffoldRelease[];
+    current?: ScaffoldRelease;
+    download?: StarterUpdateDownload;
+}
+/** Reject noncanonical sources before any gate downloads an archive. */
+declare function assertCanonicalScaffoldUpgradeRelease(release: ScaffoldRelease): void;
+/** Run the current and oldest retained bases through the real complete updater. */
+declare function verifyScaffoldUpgrades(options: UpgradeCanaryOptions): Promise<string[]>;
+
+export { type UpgradeCanaryOptions, assertCanonicalScaffoldUpgradeRelease, verifyScaffoldUpgrades };

package/dist/starter-upgrade-canary.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import {
+  updateStarterProject
+} from "./chunk-J5V4UJXD.js";
+import {
+  downloadStarter
+} from "./chunk-VHIX2IYK.js";
+import "./chunk-L2YCVQBR.js";
+import {
+  classifyStarterPath,
+  mergeStarterOwnershipContracts,
+  readStarterReleaseManifest
+} from "./chunk-LKI5X3H2.js";
+import {
+  STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES
+} from "./chunk-D7ANFHIL.js";
+
+// src/starter-upgrade-canary.ts
+import { createHash } from "crypto";
+import { cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { isDeepStrictEqual } from "util";
+function files(root, prefix = "") {
+  const result = /* @__PURE__ */ new Map();
+  for (const entry of readdirSync(join(root, prefix))) {
+    const path = prefix ? `${prefix}/${entry}` : entry;
+    const stat = lstatSync(join(root, path));
+    if (stat.isSymbolicLink()) throw new Error("Canary archives cannot contain symbolic links.");
+    if (stat.isDirectory()) for (const [key, bytes] of files(root, path)) result.set(key, bytes);
+    else if (stat.isFile()) result.set(path, readFileSync(join(root, path)));
+    else throw new Error("Canary archives must contain only regular files.");
+  }
+  return result;
+}
+function assertCanonicalScaffoldUpgradeRelease(release) {
+  if (release.source.repository !== "thallylabs/starter" || release.runtime.repository !== "thallylabs/thally" || !/^[a-f0-9]{40}$/.test(release.source.commitSha) || !/^[a-f0-9]{40}$/.test(release.source.treeSha) || !/^[a-f0-9]{40}$/.test(release.runtime.commitSha) || !/^[a-f0-9]{40}$/.test(release.runtime.treeSha) || !/^[a-f0-9]{64}$/.test(release.source.manifestSha256) || release.source.archiveUrl !== `https://codeload.github.com/thallylabs/starter/tar.gz/${release.source.commitSha}`) {
+    throw new Error("Historical upgrade canaries require immutable canonical releases.");
+  }
+}
+async function verifyScaffoldUpgrades(options) {
+  const { target } = options;
+  assertCanonicalScaffoldUpgradeRelease(target);
+  const targetManifest = readStarterReleaseManifest(options.candidateDirectory, target);
+  const targetFiles = files(options.candidateDirectory);
+  const history = [...options.releases ?? SUPPORTED_SCAFFOLD_RELEASES].filter((release) => release.source.manifestSha256 !== target.source.manifestSha256);
+  if (!history.length) throw new Error("Historical upgrade canary has no retained baseline.");
+  const current = options.current ?? STABLE_SCAFFOLD_RELEASE;
+  const bases = [current, history.at(-1)].filter((release, index, all) => all.findIndex((other) => other.source.manifestSha256 === release.source.manifestSha256) === index);
+  const catalog = [target, ...bases, ...history].filter((release, index, all) => all.findIndex((other) => other.source.manifestSha256 === release.source.manifestSha256) === index);
+  catalog.forEach(assertCanonicalScaffoldUpgradeRelease);
+  const workspace = mkdtempSync(join(tmpdir(), "thally-upgrade-canary-"));
+  const snapshots = /* @__PURE__ */ new Map();
+  const download = async (destination, release) => {
+    if (!catalog.some((known) => known.id === release.id && known.source.manifestSha256 === release.source.manifestSha256)) throw new Error("Canary requested an uncatalogued release.");
+    if (release.source.manifestSha256 === target.source.manifestSha256) cpSync(options.candidateDirectory, destination, { recursive: true });
+    else if (options.download) await options.download(destination, release);
+    else {
+      let snapshot = snapshots.get(release.source.manifestSha256);
+      if (!snapshot) {
+        snapshot = join(workspace, "archives", release.source.manifestSha256);
+        mkdirSync(snapshot, { recursive: true });
+        await downloadStarter(snapshot, void 0, release, { announce: false });
+        readStarterReleaseManifest(snapshot, release);
+        files(snapshot);
+        snapshots.set(release.source.manifestSha256, snapshot);
+      }
+      cpSync(snapshot, destination, { recursive: true });
+    }
+    readStarterReleaseManifest(destination, release);
+    files(destination);
+  };
+  try {
+    for (const [index, base] of bases.entries()) {
+      const customer = join(workspace, String(index));
+      mkdirSync(customer);
+      await download(customer, base);
+      const oldManifest = readStarterReleaseManifest(customer, base);
+      const ownership = mergeStarterOwnershipContracts(oldManifest.ownership, targetManifest.ownership);
+      for (const [path, bytes] of [
+        ["src/content/__upgrade-canary.mdx", Buffer.from("---\ntitle: Upgrade canary\ndescription: Owner preservation\n---\nOwner content.\n")],
+        ["docs.json", Buffer.from('{"name":"Customer upgrade canary","navigation":[]}\n')]
+      ]) {
+        if (classifyStarterPath(path, ownership) !== "protected") throw new Error(`Canary owner path is not protected: ${path}`);
+        mkdirSync(dirname(join(customer, path)), { recursive: true });
+        writeFileSync(join(customer, path), bytes);
+      }
+      const packagePath = join(customer, "package.json");
+      const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+      packageJson.name = "customer-upgrade-canary";
+      writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}
+`);
+      const before = files(customer);
+      const plan = await updateStarterProject({ targetDir: customer, targetRelease: target, releases: catalog, download });
+      if (plan.plan.conflictPaths.length) throw new Error(`Historical upgrade conflicts: ${base.id}`);
+      await updateStarterProject({ targetDir: customer, targetRelease: target, releases: catalog, download, apply: true, confirmed: true });
+      const after = files(customer);
+      for (const [path, bytes] of before) if (path !== target.source.manifestPath && classifyStarterPath(path, ownership) === "protected" && !after.get(path)?.equals(bytes)) throw new Error(`Upgrade changed owner bytes: ${path}`);
+      for (const path of /* @__PURE__ */ new Set([...targetFiles.keys(), ...after.keys()])) if (classifyStarterPath(path, ownership) === "syncable" && (!targetFiles.has(path) || !after.has(path) || !targetFiles.get(path).equals(after.get(path)))) throw new Error(`Upgrade runtime differs from candidate: ${path}`);
+      if (JSON.parse(readFileSync(packagePath, "utf8")).name !== "customer-upgrade-canary") throw new Error("Upgrade lost independent package customization.");
+      for (const path of ["package.json", "package-lock.json"]) {
+        const actual = JSON.parse(readFileSync(join(customer, path), "utf8"));
+        const expected = JSON.parse(readFileSync(join(options.candidateDirectory, path), "utf8"));
+        delete actual.name;
+        delete expected.name;
+        if (actual.packages?.[""]) delete actual.packages[""].name;
+        if (expected.packages?.[""]) delete expected.packages[""].name;
+        if (!isDeepStrictEqual(actual, expected)) throw new Error(`Upgrade package inputs differ from candidate: ${path}`);
+      }
+      const hash = createHash("sha256").update(readFileSync(join(customer, target.source.manifestPath))).digest("hex");
+      if (hash !== target.source.manifestSha256) throw new Error("Upgrade did not advance exact target provenance.");
+    }
+    return bases.map((base) => base.id);
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+export {
+  assertCanonicalScaffoldUpgradeRelease,
+  verifyScaffoldUpgrades
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-thally-docs",
-  "version": "0.10.89",
+  "version": "0.10.90",
   "description": "Scaffold an open-source Thally docs site for people, search engines, and AI tools.",
   "type": "module",
   "engines": {
@@ -33,6 +33,10 @@
     "./terminal": {
       "types": "./dist/terminal.d.ts",
       "import": "./dist/terminal.js"
+    },
+    "./starter-upgrade-canary": {
+      "types": "./dist/starter-upgrade-canary.d.ts",
+      "import": "./dist/starter-upgrade-canary.js"
     }
   },
   "files": [

package/dist/{chunk-N25GFJOS.js → chunk-VHIX2IYK.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
+import {
+  terminal
+} from "./chunk-L2YCVQBR.js";
 import {
   readStarterReleaseManifest
 } from "./chunk-LKI5X3H2.js";
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-D7ANFHIL.js";
-import {
-  terminal
-} from "./chunk-L2YCVQBR.js";
 
 // src/download.ts
 import { Readable, Transform, pipeline } from "stream";