create-thally-docs 0.9.0 → 0.10.0

package/dist/starter-update.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import {
+  downloadStarter
+} from "./chunk-ENQIF6MA.js";
+import {
+  applyStarterRuntimeSyncPlan,
+  mergeStarterOwnershipContracts,
+  parseStarterReleaseManifest,
+  planStarterRuntimeSync,
+  readStarterReleaseManifest,
+  starterManifestSha256
+} from "./chunk-KXJT2MG5.js";
+import {
+  STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES
+} from "./chunk-WMHBVXWW.js";
+
+// src/starter-update.ts
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync
+} from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+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.`
+    );
+  }
+  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 assertForwardRelease(previous, target) {
+  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 && previous.starterVersion >= target.starterVersion) {
+    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;
+  const manifestPath = targetRelease.source.manifestPath;
+  const downstreamManifest = readDownstreamManifest(options.targetDir, manifestPath);
+  const previousRelease = resolveStarterReleaseFromManifest(
+    downstreamManifest,
+    releases
+  );
+  assertForwardRelease(previousRelease, targetRelease);
+  if (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
+    );
+    const plan = planStarterRuntimeSync(
+      oldStarterDir,
+      newStarterDir,
+      options.targetDir,
+      ownership
+    );
+    if (!options.apply) {
+      return {
+        previousRelease,
+        targetRelease,
+        plan,
+        isUpToDate: false,
+        applied: false
+      };
+    }
+    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,
+        provenance: {
+          sourcePath: join(newStarterDir, manifestPath),
+          targetPath: join(options.targetDir, manifestPath),
+          expectedSha256: previousRelease.source.manifestSha256
+        }
+      }
+    );
+    return {
+      previousRelease,
+      targetRelease,
+      plan,
+      isUpToDate: false,
+      applied: true
+    };
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+export {
+  resolveStarterReleaseFromManifest,
+  updateStarterProject
+};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "create-thally-docs",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Scaffold the first documentation surface in a Thally product-knowledge pipeline.",
   "type": "module",
   "engines": {
     "node": ">=18"
   },
   "bin": {
-    "create-thally-docs": "./dist/index.js"
+    "create-thally-docs": "dist/index.js"
   },
   "exports": {
     ".": "./dist/index.js",
@@ -20,6 +20,14 @@
       "types": "./dist/release.d.ts",
       "import": "./dist/release.js"
     },
+    "./starter-sync": {
+      "types": "./dist/starter-sync.d.ts",
+      "import": "./dist/starter-sync.js"
+    },
+    "./starter-update": {
+      "types": "./dist/starter-update.d.ts",
+      "import": "./dist/starter-update.js"
+    },
     "./migrate": "./dist/migrate/index.js",
     "./package.json": "./package.json"
   },