create-thally-docs 0.10.88 → 0.10.89

package/dist/{chunk-MFJ6H3MQ.js → chunk-LKI5X3H2.js}

@@ -14,6 +14,7 @@ import {
   readFileSync,
   readdirSync,
   renameSync,
+  writeFileSync,
   rmSync
 } from "fs";
 import { dirname, join, relative, resolve, sep } from "path";
@@ -212,6 +213,7 @@ function collectFiles(root, contract, desiredOwnership) {
   const rules = desiredOwnership === "syncable" ? contract.frameworkSyncEligible : contract.manualReview;
   const visit = (absolutePath) => {
     const resolvedPath = resolve(absolutePath);
+    if (resolvedPath !== resolve(root)) assertSafeTargetParents(root, resolvedPath);
     if (visited.has(resolvedPath)) return;
     visited.add(resolvedPath);
     const repositoryPath = filesystemPathToRepositoryPath(root, resolvedPath);
@@ -362,15 +364,20 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
   if (plan.conflictPaths.length > 0) {
     throw new Error("Resolve starter synchronization conflicts before applying.");
   }
-  const uniqueMutations = /* @__PURE__ */ new Set([...plan.copyPaths, ...plan.deletePaths]);
-  if (uniqueMutations.size !== plan.copyPaths.length + plan.deletePaths.length) {
+  const manual = options.manualMutations;
+  const copyPaths = [...plan.copyPaths, ...manual?.writeFiles.keys() ?? []];
+  const deletePaths = [...plan.deletePaths, ...manual?.deletePaths ?? []];
+  const preconditions = { ...plan.targetPreconditions, ...manual?.targetPreconditions };
+  const uniqueMutations = /* @__PURE__ */ new Set([...copyPaths, ...deletePaths]);
+  if (uniqueMutations.size !== copyPaths.length + deletePaths.length) {
     throw new Error("Starter synchronization plan contains conflicting mutations.");
   }
   for (const path of uniqueMutations) {
-    if (classifyStarterPath(path, contract) !== "syncable") {
+    const isManualMutation = manual?.writeFiles.has(path) || manual?.deletePaths.includes(path);
+    if (classifyStarterPath(path, contract) !== (isManualMutation ? "manual" : "syncable")) {
       throw new Error(`Starter synchronization refused owner path ${path}.`);
     }
-    if (!plan.targetPreconditions[path]) {
+    if (!preconditions[path]) {
       throw new Error(`Starter synchronization plan lacks a target precondition for ${path}.`);
     }
   }
@@ -428,7 +435,11 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
     mutationIndex += 1;
   };
   try {
-    for (const path of plan.copyPaths) {
+    for (const path of copyPaths) {
+      if (manual?.writeFiles.has(path)) {
+        writeFileSync(stagePath(path), manual.writeFiles.get(path));
+        continue;
+      }
       const sourcePath = ensureContained(newStarterDir, path);
       if (!existsSync(sourcePath) || !lstatSync(sourcePath).isFile()) {
         throw new Error(`Starter synchronization source is missing ${path}.`);
@@ -446,7 +457,7 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
     for (const path of uniqueMutations) {
       const targetPath = ensureContained(targetDir, path);
       assertSafeTargetParents(targetDir, targetPath);
-      if (!matchesTargetPrecondition(targetPath, plan.targetPreconditions[path])) {
+      if (!matchesTargetPrecondition(targetPath, preconditions[path])) {
         throw new Error(`Starter synchronization target changed after planning: ${path}.`);
       }
     }
@@ -456,18 +467,18 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
         throw new Error("The project starter manifest changed during update planning.");
       }
     }
-    for (const path of plan.deletePaths) {
+    for (const path of deletePaths) {
       mutate(
         path,
         ensureContained(targetDir, path),
-        plan.targetPreconditions[path]
+        preconditions[path]
       );
     }
-    for (const path of plan.copyPaths) {
+    for (const path of copyPaths) {
       mutate(
         path,
         ensureContained(targetDir, path),
-        plan.targetPreconditions[path],
+        preconditions[path],
         ensureContained(stagedDir, path)
       );
     }
@@ -515,6 +526,7 @@ export {
   parseStarterReleaseManifest,
   readStarterReleaseManifest,
   classifyStarterPath,
+  captureTargetPrecondition,
   planStarterRuntimeSync,
   applyStarterRuntimeSyncPlan
 };

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   readStarterReleaseManifest
-} from "./chunk-MFJ6H3MQ.js";
+} from "./chunk-LKI5X3H2.js";
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-D7ANFHIL.js";

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

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

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

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

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "./chunk-JZ75H4V3.js";
+} from "./chunk-WQMTOYV4.js";
 import {
   parseFrontmatter,
   runCheck
@@ -13,11 +13,11 @@ import {
   scaffold,
   slugify,
   success
-} from "./chunk-YBVSKK53.js";
+} from "./chunk-T6HHQNCZ.js";
 import "./chunk-UG3OXVLE.js";
 import "./chunk-J7255UQA.js";
-import "./chunk-QCHFKSPD.js";
-import "./chunk-MFJ6H3MQ.js";
+import "./chunk-N25GFJOS.js";
+import "./chunk-LKI5X3H2.js";
 import "./chunk-D7ANFHIL.js";
 import {
   acquireTerminalAccent,

package/dist/migrate/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "../chunk-JZ75H4V3.js";
+} from "../chunk-WQMTOYV4.js";
 import "../chunk-KDLP27DS.js";
-import "../chunk-YBVSKK53.js";
+import "../chunk-T6HHQNCZ.js";
 import "../chunk-UG3OXVLE.js";
 import "../chunk-J7255UQA.js";
-import "../chunk-QCHFKSPD.js";
-import "../chunk-MFJ6H3MQ.js";
+import "../chunk-N25GFJOS.js";
+import "../chunk-LKI5X3H2.js";
 import "../chunk-D7ANFHIL.js";
 import "../chunk-L2YCVQBR.js";
 export {

package/dist/scaffold.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   scaffold
-} from "./chunk-YBVSKK53.js";
+} from "./chunk-T6HHQNCZ.js";
 import "./chunk-UG3OXVLE.js";
 import "./chunk-J7255UQA.js";
 import {
@@ -9,8 +9,8 @@ import {
   STARTER_COMMIT_SHA,
   STARTER_REPOSITORY,
   validateStarterArchiveEntry
-} from "./chunk-QCHFKSPD.js";
-import "./chunk-MFJ6H3MQ.js";
+} from "./chunk-N25GFJOS.js";
+import "./chunk-LKI5X3H2.js";
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-D7ANFHIL.js";

package/dist/starter-sync.d.ts

@@ -5,8 +5,8 @@ import { ScaffoldOwnershipContract, ScaffoldRelease, StarterReleaseManifest } fr
  *
  * The ownership contract comes from the pinned starter archive's
  * `starter-release.json`. Automatic updates touch only framework-eligible files
- * that still match the recorded old starter; owner and manual-review paths are
- * never included in an apply plan.
+ * that still match the recorded old starter. Owner paths are never mutated;
+ * manual-review files join the transaction only after a separate safe merge.
  */
 
 type StarterPathOwnership = 'protected' | 'manual' | 'syncable' | 'unmanaged';
@@ -34,6 +34,12 @@ interface ApplyStarterRuntimeSyncOptions {
     /** Optional immutable provenance file, atomically replaced after mutations. */
     provenance?: StarterApplyProvenance;
     /** Integration hook; an exception aborts and rolls back the transaction. */
+    /** Owner-reviewed paths explicitly resolved by the shared three-way merge. */
+    manualMutations?: {
+        writeFiles: ReadonlyMap<string, Buffer>;
+        deletePaths: readonly string[];
+        targetPreconditions: Record<string, StarterTargetPrecondition>;
+    };
     onMutationApplied?: (path: string, index: number) => void;
 }
 /** Parse and validate the ownership section in `starter-release.json`. */
@@ -57,6 +63,8 @@ declare function parseStarterReleaseManifest(source: string, release?: ScaffoldR
 declare function readStarterReleaseManifest(starterDir: string, release?: ScaffoldRelease): StarterReleaseManifest;
 /** Protected > manual-review > syncable > unmanaged. */
 declare function classifyStarterPath(path: string, contract: ScaffoldOwnershipContract): StarterPathOwnership;
+/** Capture exact file identity before planning a filesystem mutation. */
+declare function captureTargetPrecondition(path: string): StarterTargetPrecondition;
 /**
  * Build a safe three-way update plan from the recorded old starter, the new
  * starter, and the customer's current tree.
@@ -65,4 +73,4 @@ declare function planStarterRuntimeSync(oldStarterDir: string, newStarterDir: st
 /** Apply an explicitly confirmed, conflict-free three-way plan. */
 declare function applyStarterRuntimeSyncPlan(newStarterDir: string, targetDir: string, plan: StarterRuntimeSyncPlan, ownership: ScaffoldOwnershipContract, options: ApplyStarterRuntimeSyncOptions): void;
 
-export { type ApplyStarterRuntimeSyncOptions, type StarterApplyProvenance, type StarterPathOwnership, type StarterRuntimeSyncPlan, type StarterTargetPrecondition, applyStarterRuntimeSyncPlan, classifyStarterPath, mergeStarterOwnershipContracts, parseStarterOwnershipContract, parseStarterReleaseManifest, planStarterRuntimeSync, readStarterReleaseManifest, starterManifestSha256 };
+export { type ApplyStarterRuntimeSyncOptions, type StarterApplyProvenance, type StarterPathOwnership, type StarterRuntimeSyncPlan, type StarterTargetPrecondition, applyStarterRuntimeSyncPlan, captureTargetPrecondition, classifyStarterPath, mergeStarterOwnershipContracts, parseStarterOwnershipContract, parseStarterReleaseManifest, planStarterRuntimeSync, readStarterReleaseManifest, starterManifestSha256 };

package/dist/starter-sync.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   applyStarterRuntimeSyncPlan,
+  captureTargetPrecondition,
   classifyStarterPath,
   mergeStarterOwnershipContracts,
   parseStarterOwnershipContract,
@@ -8,10 +9,11 @@ import {
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-MFJ6H3MQ.js";
+} from "./chunk-LKI5X3H2.js";
 import "./chunk-D7ANFHIL.js";
 export {
   applyStarterRuntimeSyncPlan,
+  captureTargetPrecondition,
   classifyStarterPath,
   mergeStarterOwnershipContracts,
   parseStarterOwnershipContract,

package/dist/starter-update.d.ts

@@ -1,6 +1,28 @@
 import { ScaffoldRelease } from './release.js';
 import { StarterRuntimeSyncPlan } from './starter-sync.js';
 
+/** File-level and JSON-pointer conflict details without customer file contents. */
+interface StarterManualConflict {
+    path: string;
+    fields: string[];
+}
+/** Complete resolved writes and deletions, or conflicts requiring owner review. */
+interface ManualReviewMutations {
+    writeFiles: Map<string, Buffer>;
+    deletePaths: Array<string>;
+    conflicts: Array<StarterManualConflict>;
+}
+/**
+ * Resolve manual-review files without silently overwriting downstream work.
+ *
+ * Package manifests and lockfiles sit outside the hidden runtime ownership
+ * surface. Their object keys have independent ownership, so non-overlapping
+ * JSON edits merge structurally: a customer package name survives while a
+ * framework dependency advances. Same-field edits and every unstructured
+ * manual-review file remain fail-closed.
+ */
+declare function resolveManualReviewMutations(paths: readonly string[], downstreamFiles: ReadonlyMap<string, Buffer>, previousReleaseFiles: ReadonlyMap<string, Buffer>, targetReleaseFiles: ReadonlyMap<string, Buffer>): ManualReviewMutations;
+
 /**
  * User-reachable orchestration for immutable starter release updates.
  *
@@ -22,6 +44,7 @@ interface UpdateStarterProjectOptions {
     targetRelease?: ScaffoldRelease;
     releases?: readonly ScaffoldRelease[];
     download?: StarterUpdateDownload;
+    resolveReleaseHint?: StarterReleaseHintResolver;
 }
 interface StarterUpdateResult {
     previousRelease: ScaffoldRelease;
@@ -29,9 +52,44 @@ interface StarterUpdateResult {
     plan: StarterRuntimeSyncPlan;
     isUpToDate: boolean;
     applied: boolean;
+    /** A verified published baseline replaced noncanonical manifest provenance. */
+    manualConflicts?: StarterManualConflict[];
+    resolvedManualPaths?: string[];
+    deletedManualPaths?: string[];
+    recoveredProvenance?: boolean;
 }
 /** Resolve exact downstream provenance without consulting a moving branch. */
 declare function resolveStarterReleaseFromManifest(source: string, releases?: readonly ScaffoldRelease[]): ScaffoldRelease;
+/** An untrusted promotion record can suggest only an already trusted release. */
+interface StarterReleaseHintResolver {
+    (runtimeCommitSha: string): Promise<unknown>;
+}
+/** Recognizable transient failure; callers must not cache it as unsupported. */
+declare function starterReleaseProviderError(cause?: unknown): Error & {
+    code: string;
+};
+/** Read a bounded lookup hint from the fixed public repository at an exact SHA. */
+declare function fetchStarterReleaseHint(runtimeCommitSha: string): Promise<unknown>;
+/** Trusted catalog and bounded download seams shared by CLI and managed callers. */
+interface ResolveStarterUpdateBaseOptions {
+    targetDir: string;
+    releases?: readonly ScaffoldRelease[];
+    download?: StarterUpdateDownload;
+    resolveReleaseHint?: StarterReleaseHintResolver;
+}
+/** Published baseline identity plus evidence needed to guard provenance writes. */
+interface StarterUpdateBase {
+    release: ScaffoldRelease;
+    recoveredProvenance: boolean;
+    /** The actual initial bytes, including noncanonical provenance, guard apply. */
+    manifestSha256: string;
+}
+/**
+ * Resolve a published three-way base. Unknown provenance is accepted only when
+ * its contract and complete framework inventory equal a trusted published tree.
+ * Neither arbitrary manifest ownership nor a fetched hint authorizes writes.
+ */
+declare function resolveStarterUpdateBase(options: ResolveStarterUpdateBaseOptions): Promise<StarterUpdateBase>;
 /**
  * Plan or explicitly apply an immutable three-way starter update.
  *
@@ -40,4 +98,4 @@ declare function resolveStarterReleaseFromManifest(source: string, releases?: re
  */
 declare function updateStarterProject(options: UpdateStarterProjectOptions): Promise<StarterUpdateResult>;
 
-export { type StarterUpdateDownload, type StarterUpdateResult, type UpdateStarterProjectOptions, resolveStarterReleaseFromManifest, updateStarterProject };
+export { type ManualReviewMutations, type ResolveStarterUpdateBaseOptions, type StarterManualConflict, type StarterReleaseHintResolver, type StarterUpdateBase, type StarterUpdateDownload, type StarterUpdateResult, type UpdateStarterProjectOptions, fetchStarterReleaseHint, resolveManualReviewMutations, resolveStarterReleaseFromManifest, resolveStarterUpdateBase, starterReleaseProviderError, updateStarterProject };

package/dist/starter-update.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
 import {
   downloadStarter
-} from "./chunk-QCHFKSPD.js";
+} from "./chunk-N25GFJOS.js";
 import {
   applyStarterRuntimeSyncPlan,
+  captureTargetPrecondition,
   mergeStarterOwnershipContracts,
   parseStarterReleaseManifest,
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-MFJ6H3MQ.js";
+} from "./chunk-LKI5X3H2.js";
 import {
   STABLE_SCAFFOLD_RELEASE,
   SUPPORTED_SCAFFOLD_RELEASES
@@ -19,13 +20,137 @@ 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: [],
@@ -42,6 +167,10 @@ function readDownstreamManifest(targetDir, manifestPath) {
       `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) {
@@ -57,6 +186,124 @@ function resolveStarterReleaseFromManifest(source, releases = SUPPORTED_SCAFFOLD
   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.");
@@ -80,14 +327,18 @@ function assertForwardRelease(previous, target, releases) {
 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 previousRelease = resolveStarterReleaseFromManifest(
-    downstreamManifest,
-    releases
-  );
+  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 (previousRelease.source.commitSha === targetRelease.source.commitSha) {
+  if (!base.recoveredProvenance && previousRelease.source.commitSha === targetRelease.source.commitSha) {
     return {
       previousRelease,
       targetRelease,
@@ -116,19 +367,62 @@ async function updateStarterProject(options) {
       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
+        applied: false,
+        recoveredProvenance: base.recoveredProvenance,
+        manualConflicts: manual.conflicts,
+        resolvedManualPaths,
+        deletedManualPaths: manual.deletePaths
       };
     }
     if (plan.conflictPaths.length > 0) {
@@ -144,10 +438,11 @@ async function updateStarterProject(options) {
       ownership,
       {
         confirmed: true,
+        manualMutations: { ...manual, targetPreconditions: manualPreconditions },
         provenance: {
           sourcePath: join(newStarterDir, manifestPath),
           targetPath: join(options.targetDir, manifestPath),
-          expectedSha256: previousRelease.source.manifestSha256
+          expectedSha256: base.manifestSha256
         }
       }
     );
@@ -156,13 +451,21 @@ async function updateStarterProject(options) {
       targetRelease,
       plan,
       isUpToDate: false,
-      applied: true
+      applied: true,
+      recoveredProvenance: base.recoveredProvenance,
+      manualConflicts: manual.conflicts,
+      resolvedManualPaths,
+      deletedManualPaths: manual.deletePaths
     };
   } finally {
     rmSync(workspace, { recursive: true, force: true });
   }
 }
 export {
+  fetchStarterReleaseHint,
+  resolveManualReviewMutations,
   resolveStarterReleaseFromManifest,
+  resolveStarterUpdateBase,
+  starterReleaseProviderError,
   updateStarterProject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-thally-docs",
-  "version": "0.10.88",
+  "version": "0.10.89",
   "description": "Scaffold an open-source Thally docs site for people, search engines, and AI tools.",
   "type": "module",
   "engines": {