create-thally-docs 0.9.0 → 0.10.1

package/dist/{chunk-JNDRCCJV.js → chunk-2N74PW2Y.js}

@@ -1,83 +1,16 @@
 #!/usr/bin/env node
 import {
-  patchApiReferenceGuard,
-  patchGitignore,
-  patchOpenApiFetch,
-  patchPackageJson,
-  patchTopBarNavigation,
-  updateEnvExample,
-  updateSiteConfig,
-  writeCloudflareRuntimeConfig,
-  writeStarterAgentGuide,
-  writeStarterContent,
-  writeStarterReadme
-} from "./chunk-BW7J7DJV.js";
+  personalizeStarter,
+  updateEnvExample
+} from "./chunk-ORUAMPNF.js";
 import {
-  STABLE_SCAFFOLD_RELEASE
-} from "./chunk-PJW4JJIT.js";
+  downloadStarter
+} from "./chunk-TMXBINSI.js";
 
 // src/scaffold.ts
 import { existsSync, mkdirSync, readdirSync } from "fs";
 import { resolve } from "path";
 
-// src/download.ts
-import { Readable, pipeline } from "stream";
-import { promisify } from "util";
-import { extract } from "tar";
-var pipelineAsync = promisify(pipeline);
-var TEMPLATE_REPOSITORY = STABLE_SCAFFOLD_RELEASE.source.repository;
-var TEMPLATE_COMMIT_SHA = STABLE_SCAFFOLD_RELEASE.source.commitSha;
-var TARBALL_URL = STABLE_SCAFFOLD_RELEASE.source.archiveUrl;
-var EXCLUDE_PATHS = [
-  // Match both the directory entry itself and every nested file. Tar invokes
-  // the filter for `.../node_modules` before descendants, without a trailing `/`.
-  "/node_modules",
-  // The canonical docs repository may temporarily retain package sources while
-  // runtime work is being upstreamed. A scaffold consumes the published
-  // packages declared in package.json; it must never inherit those sources.
-  "/packages",
-  "/.git/",
-  "/.next/",
-  "/.data/",
-  "/.thally/",
-  // The first-party docs deployment pins its own canonical origin.
-  "/.env.production",
-  "/thally-track.yml",
-  "/CODEOWNERS",
-  "/CLAUDE.md",
-  "/notes/",
-  "/public/images/",
-  "/src/public/",
-  "/snippets/",
-  "/.github/ISSUE_TEMPLATE/",
-  "/.github/PULL_REQUEST_TEMPLATE.md",
-  "/README.md"
-];
-function shouldInclude(path) {
-  for (const excluded of EXCLUDE_PATHS) {
-    if (path.includes(excluded)) {
-      return false;
-    }
-  }
-  return true;
-}
-async function downloadTemplate(targetDir, siteName) {
-  console.log("");
-  console.log(`  \u23F3 Creating ${siteName?.trim() || "your docs site"}...`);
-  const response = await fetch(TARBALL_URL);
-  if (!response.ok) {
-    throw new Error(`Failed to download template: ${response.status} ${response.statusText}`);
-  }
-  if (!response.body) {
-    throw new Error("Response body is empty");
-  }
-  const nodeStream = Readable.fromWeb(response.body);
-  await pipelineAsync(
-    nodeStream,
-    extract({ cwd: targetDir, strip: 1, filter: shouldInclude })
-  );
-}
-
 // src/docs-json.ts
 import { readFileSync, writeFileSync } from "fs";
 import { join } from "path";
@@ -189,7 +122,16 @@ async function scaffold(options) {
   }
   mkdirSync(targetDir, { recursive: true });
   const slug = slugify(projectName);
-  await downloadTemplate(targetDir, projectName);
+  await downloadStarter(targetDir, projectName);
+  personalizeStarter(targetDir, {
+    projectName,
+    packageName: slug,
+    description,
+    brandPreset,
+    repoUrl,
+    enableAiChat,
+    i18nLocales
+  });
   resetTrackingConfig(targetDir);
   if (trackRepos?.length) {
     writeTrackingConfig(targetDir, trackRepos);
@@ -198,16 +140,6 @@ async function scaffold(options) {
     console.log("    To finish wiring it: `thally track setup` (pick a trigger) + `thally agent init`,");
     console.log("    then add your ANTHROPIC_API_KEY. See /guides/thally-track.");
   }
-  writeStarterContent(targetDir, projectName, enableAiChat, repoUrl, i18nLocales);
-  writeStarterReadme(targetDir, projectName);
-  writeStarterAgentGuide(targetDir, projectName);
-  updateSiteConfig(targetDir, projectName, description, brandPreset, repoUrl);
-  patchApiReferenceGuard(targetDir);
-  patchTopBarNavigation(targetDir);
-  patchOpenApiFetch(targetDir);
-  patchPackageJson(targetDir, slug);
-  writeCloudflareRuntimeConfig(targetDir, slug);
-  patchGitignore(targetDir);
   updateEnvExample(targetDir);
   if (doInstall) {
     installDeps(targetDir);
@@ -222,10 +154,6 @@ export {
   installDeps,
   logo,
   success,
-  TEMPLATE_REPOSITORY,
-  TEMPLATE_COMMIT_SHA,
-  EXCLUDE_PATHS,
-  shouldInclude,
   readDocsJson,
   writeDocsJson,
   scaffold

package/dist/{chunk-YWNWLSZ2.js → chunk-DGK6XREP.js}

@@ -3,7 +3,7 @@ import {
   initGit,
   installDeps,
   scaffold
-} from "./chunk-JNDRCCJV.js";
+} from "./chunk-2N74PW2Y.js";
 
 // src/migrate/index.ts
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";

package/dist/chunk-IJXZ4YRL.js

@@ -0,0 +1,520 @@
+#!/usr/bin/env node
+import {
+  STABLE_SCAFFOLD_RELEASE
+} from "./chunk-RLGB6QF3.js";
+
+// src/starter-sync.ts
+import { createHash } from "crypto";
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync
+} from "fs";
+import { dirname, join, relative, resolve, sep } from "path";
+var MAX_MANIFEST_BYTES = 256 * 1024;
+var SHA256_PATTERN = /^[a-f0-9]{64}$/;
+function normalizedRelativePath(value) {
+  if (!value || value.includes("\0") || value.includes("\\") || value.startsWith("/")) {
+    return null;
+  }
+  const parts = value.split("/");
+  if (parts.some((part) => !part || part === "." || part === "..")) return null;
+  return parts.join("/");
+}
+function normalizedRule(value) {
+  const isDirectoryRule = value.endsWith("/**");
+  const isFilenamePrefixRule = !isDirectoryRule && value.endsWith("*");
+  const path = isDirectoryRule ? value.slice(0, -3) : isFilenamePrefixRule ? value.slice(0, -1) : value;
+  const normalized = normalizedRelativePath(path);
+  if (!normalized || path.includes("*")) return null;
+  if (isFilenamePrefixRule) {
+    const filenamePrefix = normalized.split("/").at(-1);
+    if (!filenamePrefix) return null;
+    return `${normalized}*`;
+  }
+  return isDirectoryRule ? `${normalized}/**` : normalized;
+}
+function parsePathRules(value, field, allowEmpty = false) {
+  if (!Array.isArray(value) || !allowEmpty && value.length === 0) {
+    throw new Error(`The starter ownership contract requires ${field}.`);
+  }
+  const rules = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const candidate of value) {
+    const rule = typeof candidate === "string" ? normalizedRule(candidate) : null;
+    if (!rule || seen.has(rule)) {
+      throw new Error(`The starter ownership contract contains invalid ${field}.`);
+    }
+    seen.add(rule);
+    rules.push(rule);
+  }
+  return rules;
+}
+function parseStarterOwnershipContract(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("The starter ownership contract is invalid.");
+  }
+  const candidate = value;
+  return {
+    frameworkSyncEligible: parsePathRules(
+      candidate.frameworkSyncEligible,
+      "frameworkSyncEligible"
+    ),
+    userOwnedNeverOverwrite: parsePathRules(
+      candidate.userOwnedNeverOverwrite,
+      "userOwnedNeverOverwrite"
+    ),
+    manualReview: parsePathRules(candidate.manualReview, "manualReview", true)
+  };
+}
+function mergeStarterOwnershipContracts(previous, next) {
+  const oldContract = parseStarterOwnershipContract(previous);
+  const newContract = parseStarterOwnershipContract(next);
+  const unique = (values) => [...new Set(values)];
+  return {
+    frameworkSyncEligible: unique([
+      ...oldContract.frameworkSyncEligible,
+      ...newContract.frameworkSyncEligible
+    ]),
+    userOwnedNeverOverwrite: unique([
+      ...oldContract.userOwnedNeverOverwrite,
+      ...newContract.userOwnedNeverOverwrite,
+      STABLE_SCAFFOLD_RELEASE.source.manifestPath
+    ]),
+    manualReview: unique([
+      ...oldContract.manualReview,
+      ...newContract.manualReview
+    ])
+  };
+}
+function starterManifestSha256(source) {
+  return createHash("sha256").update(source, "utf8").digest("hex");
+}
+function parseStringRecord(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`The starter release manifest contains invalid ${field}.`);
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0 || entries.some(([key, item]) => !key || typeof item !== "string")) {
+    throw new Error(`The starter release manifest contains invalid ${field}.`);
+  }
+  return Object.fromEntries(entries);
+}
+function parseStarterReleaseManifest(source, release = STABLE_SCAFFOLD_RELEASE) {
+  if (!source || Buffer.byteLength(source, "utf8") > MAX_MANIFEST_BYTES) {
+    throw new Error("The starter release manifest is missing or too large.");
+  }
+  const expectedHash = release.source.manifestSha256;
+  if (!SHA256_PATTERN.test(expectedHash) || starterManifestSha256(source) !== expectedHash) {
+    throw new Error("The starter release manifest does not match its promoted SHA-256.");
+  }
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error("The starter release manifest is invalid JSON.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("The starter release manifest is invalid.");
+  }
+  const candidate = value;
+  if (candidate.schemaVersion !== 1 || !Number.isSafeInteger(candidate.starterVersion) || Number(candidate.starterVersion) < 1 || candidate.starterVersion !== release.starterVersion || candidate.repository !== release.source.repository || candidate.defaultBranch !== "main" || !candidate.runtime || candidate.runtime.repository !== release.runtime.repository || candidate.runtime.commitSha !== release.runtime.commitSha || candidate.runtime.treeSha !== release.runtime.treeSha) {
+    throw new Error("The starter release manifest identity does not match its release.");
+  }
+  return {
+    schemaVersion: 1,
+    starterVersion: candidate.starterVersion,
+    repository: candidate.repository,
+    defaultBranch: candidate.defaultBranch,
+    runtime: {
+      repository: candidate.runtime.repository,
+      commitSha: candidate.runtime.commitSha,
+      treeSha: candidate.runtime.treeSha
+    },
+    packages: parseStringRecord(candidate.packages, "packages"),
+    ownership: parseStarterOwnershipContract(candidate.ownership)
+  };
+}
+function readStarterReleaseManifest(starterDir, release = STABLE_SCAFFOLD_RELEASE) {
+  const manifest = parseStarterReleaseManifest(
+    readFileSync(join(starterDir, release.source.manifestPath), "utf8"),
+    release
+  );
+  let packageValue;
+  try {
+    packageValue = JSON.parse(readFileSync(join(starterDir, "package.json"), "utf8"));
+  } catch {
+    throw new Error("The stable Thally starter contains invalid package.json.");
+  }
+  if (!packageValue || typeof packageValue !== "object" || Array.isArray(packageValue)) {
+    throw new Error("The stable Thally starter contains invalid package.json.");
+  }
+  const packageJson = packageValue;
+  const declaredPackages = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies
+  };
+  for (const [name, version] of Object.entries(manifest.packages)) {
+    if (declaredPackages[name] !== version) {
+      throw new Error(
+        `The starter release manifest package ${name} does not match package.json.`
+      );
+    }
+  }
+  return manifest;
+}
+function matchesRule(path, rule) {
+  if (rule.endsWith("/**")) {
+    const root = rule.slice(0, -3);
+    return path === root || path.startsWith(`${root}/`);
+  }
+  if (rule.endsWith("*")) {
+    const prefix = rule.slice(0, -1);
+    if (!path.startsWith(prefix)) return false;
+    return !path.slice(prefix.length).includes("/");
+  }
+  return path === rule;
+}
+function ruleRoot(rule) {
+  if (rule.endsWith("/**")) return rule.slice(0, -3);
+  if (!rule.endsWith("*")) return rule;
+  const prefix = rule.slice(0, -1);
+  const slash = prefix.lastIndexOf("/");
+  return slash === -1 ? "" : prefix.slice(0, slash);
+}
+function classifyStarterPath(path, contract) {
+  const normalized = normalizedRelativePath(path);
+  if (!normalized) throw new Error("Cannot classify an unsafe starter path.");
+  const parsed = parseStarterOwnershipContract(contract);
+  if (parsed.userOwnedNeverOverwrite.some((rule) => matchesRule(normalized, rule))) {
+    return "protected";
+  }
+  if (parsed.manualReview.some((rule) => matchesRule(normalized, rule))) {
+    return "manual";
+  }
+  if (parsed.frameworkSyncEligible.some((rule) => matchesRule(normalized, rule))) {
+    return "syncable";
+  }
+  return "unmanaged";
+}
+function filesystemPathToRepositoryPath(root, path) {
+  return relative(root, path).split(sep).join("/");
+}
+function collectFiles(root, contract, desiredOwnership) {
+  const files = /* @__PURE__ */ new Map();
+  const visited = /* @__PURE__ */ new Set();
+  const rules = desiredOwnership === "syncable" ? contract.frameworkSyncEligible : contract.manualReview;
+  const visit = (absolutePath) => {
+    const resolvedPath = resolve(absolutePath);
+    if (visited.has(resolvedPath)) return;
+    visited.add(resolvedPath);
+    const repositoryPath = filesystemPathToRepositoryPath(root, resolvedPath);
+    const ownership = classifyStarterPath(repositoryPath, contract);
+    if (ownership === "protected") return;
+    const entry = lstatSync(resolvedPath);
+    if (entry.isSymbolicLink()) {
+      throw new Error("Starter synchronization does not follow symbolic links.");
+    }
+    if (entry.isFile()) {
+      if (ownership === desiredOwnership) files.set(repositoryPath, resolvedPath);
+      return;
+    }
+    if (!entry.isDirectory()) {
+      throw new Error("Starter synchronization supports only files and directories.");
+    }
+    for (const child of readdirSync(resolvedPath)) visit(join(resolvedPath, child));
+  };
+  for (const rule of rules) {
+    const rootPath = join(root, ruleRoot(rule));
+    if (!existsSync(rootPath)) continue;
+    if (rule.endsWith("*") && !rule.endsWith("/**")) {
+      for (const child of readdirSync(rootPath)) {
+        const childPath = join(rootPath, child);
+        const repositoryPath = filesystemPathToRepositoryPath(root, childPath);
+        if (matchesRule(repositoryPath, rule)) visit(childPath);
+      }
+    } else {
+      visit(rootPath);
+    }
+  }
+  return files;
+}
+function sameFile(left, right) {
+  if (!left || !right) return left === right;
+  return readFileSync(left).equals(readFileSync(right));
+}
+function fileSha256(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function captureTargetPrecondition(path) {
+  if (!existsSync(path)) return { kind: "missing" };
+  const entry = lstatSync(path);
+  if (!entry.isFile() || entry.isSymbolicLink()) {
+    throw new Error("Starter synchronization target mutations must be regular files.");
+  }
+  return { kind: "file", sha256: fileSha256(path) };
+}
+function matchesTargetPrecondition(path, precondition) {
+  if (precondition.kind === "missing") return !existsSync(path);
+  if (!existsSync(path)) return false;
+  const entry = lstatSync(path);
+  return entry.isFile() && !entry.isSymbolicLink() && fileSha256(path) === precondition.sha256;
+}
+function planStarterRuntimeSync(oldStarterDir, newStarterDir, targetDir, ownership) {
+  const contract = parseStarterOwnershipContract(ownership);
+  const oldFiles = collectFiles(resolve(oldStarterDir), contract, "syncable");
+  const newFiles = collectFiles(resolve(newStarterDir), contract, "syncable");
+  const targetFiles = collectFiles(resolve(targetDir), contract, "syncable");
+  const manualReviewPaths = /* @__PURE__ */ new Set([
+    ...collectFiles(resolve(oldStarterDir), contract, "manual").keys(),
+    ...collectFiles(resolve(newStarterDir), contract, "manual").keys(),
+    ...collectFiles(resolve(targetDir), contract, "manual").keys()
+  ]);
+  const copyPaths = [];
+  const deletePaths = [];
+  const conflictPaths = [];
+  const preservedPaths = [];
+  const unchangedPaths = [];
+  const paths = /* @__PURE__ */ new Set([
+    ...oldFiles.keys(),
+    ...newFiles.keys(),
+    ...targetFiles.keys()
+  ]);
+  for (const path of paths) {
+    const oldPath = oldFiles.get(path);
+    const newPath = newFiles.get(path);
+    const targetPath = targetFiles.get(path);
+    const targetMatchesOld = sameFile(targetPath, oldPath);
+    const newMatchesOld = sameFile(newPath, oldPath);
+    const targetMatchesNew = sameFile(targetPath, newPath);
+    if (!oldPath) {
+      if (!newPath) preservedPaths.push(path);
+      else if (!targetPath) copyPaths.push(path);
+      else if (targetMatchesNew) unchangedPaths.push(path);
+      else conflictPaths.push(path);
+      continue;
+    }
+    if (targetMatchesOld) {
+      if (!newPath) deletePaths.push(path);
+      else if (newMatchesOld) unchangedPaths.push(path);
+      else copyPaths.push(path);
+      continue;
+    }
+    if (newMatchesOld || targetMatchesNew || !targetPath && !newPath) {
+      preservedPaths.push(path);
+    } else {
+      conflictPaths.push(path);
+    }
+  }
+  const sortedCopyPaths = copyPaths.sort();
+  const sortedDeletePaths = deletePaths.sort();
+  const targetPreconditions = Object.fromEntries(
+    [...sortedCopyPaths, ...sortedDeletePaths].map((path) => [
+      path,
+      captureTargetPrecondition(ensureContained(targetDir, path))
+    ])
+  );
+  return {
+    copyPaths: sortedCopyPaths,
+    deletePaths: sortedDeletePaths,
+    conflictPaths: conflictPaths.sort(),
+    manualReviewPaths: [...manualReviewPaths].sort(),
+    preservedPaths: preservedPaths.sort(),
+    unchangedPaths: unchangedPaths.sort(),
+    targetPreconditions
+  };
+}
+function ensureContained(root, repositoryPath) {
+  const target = resolve(root, repositoryPath);
+  const prefix = `${resolve(root)}${sep}`;
+  if (!target.startsWith(prefix)) {
+    throw new Error("Starter synchronization resolved outside its target.");
+  }
+  return target;
+}
+function assertSafeTargetParents(root, path) {
+  const resolvedRoot = resolve(root);
+  let parent = dirname(resolve(path));
+  while (parent !== resolvedRoot) {
+    if (!parent.startsWith(`${resolvedRoot}${sep}`)) {
+      throw new Error("Starter synchronization parent resolved outside its target.");
+    }
+    if (existsSync(parent)) {
+      const entry = lstatSync(parent);
+      if (!entry.isDirectory() || entry.isSymbolicLink()) {
+        throw new Error("Starter synchronization refuses unsafe target parents.");
+      }
+    }
+    parent = dirname(parent);
+  }
+}
+function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership, options) {
+  const contract = parseStarterOwnershipContract(ownership);
+  if (!options.confirmed) {
+    throw new Error("Review and confirm the starter synchronization plan first.");
+  }
+  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) {
+    throw new Error("Starter synchronization plan contains conflicting mutations.");
+  }
+  for (const path of uniqueMutations) {
+    if (classifyStarterPath(path, contract) !== "syncable") {
+      throw new Error(`Starter synchronization refused owner path ${path}.`);
+    }
+    if (!plan.targetPreconditions[path]) {
+      throw new Error(`Starter synchronization plan lacks a target precondition for ${path}.`);
+    }
+  }
+  const targetRoot = resolve(targetDir);
+  const targetRootEntry = lstatSync(targetRoot);
+  if (!targetRootEntry.isDirectory() || targetRootEntry.isSymbolicLink()) {
+    throw new Error("Starter synchronization requires a regular target directory.");
+  }
+  if (options.provenance) {
+    const expectedTarget = ensureContained(
+      targetDir,
+      STABLE_SCAFFOLD_RELEASE.source.manifestPath
+    );
+    const expectedSource = ensureContained(
+      newStarterDir,
+      STABLE_SCAFFOLD_RELEASE.source.manifestPath
+    );
+    if (resolve(options.provenance.targetPath) !== expectedTarget || resolve(options.provenance.sourcePath) !== expectedSource) {
+      throw new Error("Starter synchronization received unsafe provenance paths.");
+    }
+  }
+  const transactionDir = mkdtempSync(join(dirname(targetRoot), ".thally-starter-transaction-"));
+  const stagedDir = join(transactionDir, "staged");
+  const backupDir = join(transactionDir, "backup");
+  mkdirSync(stagedDir);
+  mkdirSync(backupDir);
+  const applied = [];
+  let mutationIndex = 0;
+  const stagePath = (path) => {
+    const stagedPath = ensureContained(stagedDir, path);
+    mkdirSync(dirname(stagedPath), { recursive: true });
+    return stagedPath;
+  };
+  const backupPath = (path) => {
+    const pathInBackup = ensureContained(backupDir, path);
+    mkdirSync(dirname(pathInBackup), { recursive: true });
+    return pathInBackup;
+  };
+  const mutate = (path, targetPath, precondition, replacementPath) => {
+    assertSafeTargetParents(targetDir, targetPath);
+    if (!matchesTargetPrecondition(targetPath, precondition)) {
+      throw new Error(`Starter synchronization target changed after planning: ${path}.`);
+    }
+    if (precondition.kind === "file") {
+      copyFileSync(targetPath, backupPath(path));
+    }
+    applied.push({ path, targetPath, precondition });
+    if (replacementPath) {
+      mkdirSync(dirname(targetPath), { recursive: true });
+      renameSync(replacementPath, targetPath);
+    } else {
+      rmSync(targetPath, { force: true });
+    }
+    options.onMutationApplied?.(path, mutationIndex);
+    mutationIndex += 1;
+  };
+  try {
+    for (const path of plan.copyPaths) {
+      const sourcePath = ensureContained(newStarterDir, path);
+      if (!existsSync(sourcePath) || !lstatSync(sourcePath).isFile()) {
+        throw new Error(`Starter synchronization source is missing ${path}.`);
+      }
+      copyFileSync(sourcePath, stagePath(path));
+    }
+    let provenanceStagePath;
+    if (options.provenance) {
+      if (!existsSync(options.provenance.sourcePath) || !lstatSync(options.provenance.sourcePath).isFile()) {
+        throw new Error("Starter synchronization provenance source is missing.");
+      }
+      provenanceStagePath = join(transactionDir, "next-provenance");
+      copyFileSync(options.provenance.sourcePath, provenanceStagePath);
+    }
+    for (const path of uniqueMutations) {
+      const targetPath = ensureContained(targetDir, path);
+      assertSafeTargetParents(targetDir, targetPath);
+      if (!matchesTargetPrecondition(targetPath, plan.targetPreconditions[path])) {
+        throw new Error(`Starter synchronization target changed after planning: ${path}.`);
+      }
+    }
+    if (options.provenance) {
+      assertSafeTargetParents(targetDir, options.provenance.targetPath);
+      if (fileSha256(options.provenance.targetPath) !== options.provenance.expectedSha256) {
+        throw new Error("The project starter manifest changed during update planning.");
+      }
+    }
+    for (const path of plan.deletePaths) {
+      mutate(
+        path,
+        ensureContained(targetDir, path),
+        plan.targetPreconditions[path]
+      );
+    }
+    for (const path of plan.copyPaths) {
+      mutate(
+        path,
+        ensureContained(targetDir, path),
+        plan.targetPreconditions[path],
+        ensureContained(stagedDir, path)
+      );
+    }
+    if (options.provenance && provenanceStagePath) {
+      const provenancePrecondition = {
+        kind: "file",
+        sha256: options.provenance.expectedSha256
+      };
+      mutate(
+        STABLE_SCAFFOLD_RELEASE.source.manifestPath,
+        options.provenance.targetPath,
+        provenancePrecondition,
+        provenanceStagePath
+      );
+    }
+  } catch (error) {
+    let rollbackError;
+    for (const mutation of applied.reverse()) {
+      try {
+        rmSync(mutation.targetPath, { force: true });
+        if (mutation.precondition.kind === "file") {
+          mkdirSync(dirname(mutation.targetPath), { recursive: true });
+          renameSync(backupPath(mutation.path), mutation.targetPath);
+        }
+      } catch (candidate) {
+        rollbackError ??= candidate;
+      }
+    }
+    if (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "Starter synchronization failed and rollback was incomplete."
+      );
+    }
+    throw error;
+  } finally {
+    rmSync(transactionDir, { recursive: true, force: true });
+  }
+}
+
+export {
+  parseStarterOwnershipContract,
+  mergeStarterOwnershipContracts,
+  starterManifestSha256,
+  parseStarterReleaseManifest,
+  readStarterReleaseManifest,
+  classifyStarterPath,
+  planStarterRuntimeSync,
+  applyStarterRuntimeSyncPlan
+};