create-thally-docs 0.9.0 → 0.10.1

package/dist/release.d.ts

@@ -11,6 +11,22 @@ interface ScaffoldSourceRelease {
     commitSha: string;
     treeSha: string;
     archiveUrl: string;
+    manifestPath: 'starter-release.json';
+    manifestSha256: string;
+}
+interface ScaffoldOwnershipContract {
+    frameworkSyncEligible: readonly string[];
+    userOwnedNeverOverwrite: readonly string[];
+    manualReview: readonly string[];
+}
+interface StarterReleaseManifest {
+    schemaVersion: 1;
+    starterVersion: number;
+    repository: string;
+    defaultBranch: string;
+    runtime: Pick<ScaffoldRuntimeRelease, 'repository' | 'commitSha' | 'treeSha'>;
+    packages: Record<string, string>;
+    ownership: ScaffoldOwnershipContract;
 }
 interface ScaffoldRuntimeRelease {
     repository: string;
@@ -29,30 +45,22 @@ interface ScaffoldRelease {
 /**
  * Current stable scaffold release.
  *
- * The source commit is the refreshed public docs template and the runtime
- * commit is the matching engine change. `create-thally-docs`, the CLI, MCP,
- * and Thally Cloud all import this exact record rather than following a moving
- * branch independently.
+ * The source commit is the complete, standalone `thallylabs/starter` tree and
+ * the runtime commit is the matching engine change. `create-thally-docs`, the
+ * CLI, MCP, and Thally Cloud all import this exact record rather than following
+ * a moving branch independently. Promotion replaces the placeholders in the
+ * adjacent JSON record, which is also consumed by Cloud build parity checks.
+ */
+declare const STABLE_SCAFFOLD_RELEASE: ScaffoldRelease;
+/**
+ * Immutable releases this toolchain can use as a three-way update base.
+ *
+ * Promotion prepends the new stable record but retains earlier records. That
+ * lets a project created directly from GitHub carry only the exact manifest
+ * bytes and still resolve its original starter without mutable branch state.
  */
-declare const STABLE_SCAFFOLD_RELEASE: {
-    readonly schemaVersion: 1;
-    readonly id: "2026-08-04.b0094de4.e36d2bcf";
-    readonly source: {
-        readonly repository: "thallylabs/docs";
-        readonly commitSha: "b0094de4fea84567eb12c39c6783fdae6820bb98";
-        readonly treeSha: "ffd0a6fda07341ddd1ba164cb40acef796f89e2d";
-        readonly archiveUrl: "https://codeload.github.com/thallylabs/docs/tar.gz/b0094de4fea84567eb12c39c6783fdae6820bb98";
-    };
-    readonly runtime: {
-        readonly repository: "thallylabs/thally";
-        readonly commitSha: "e36d2bcff38f7638a77369e12773a7cab4d5d9ce";
-        readonly treeSha: "1c8b0358d78d8caa14ed039bff6ab47c98b685d8";
-        readonly contentSource: "assets";
-        readonly identityContractVersion: 1;
-    };
-    readonly starterVersion: 1;
-};
+declare const SUPPORTED_SCAFFOLD_RELEASES: readonly ScaffoldRelease[];
 /** True only when an unknown record is the currently supported release. */
 declare function isStableScaffoldRelease(value: unknown): value is ScaffoldRelease;
 
-export { STABLE_SCAFFOLD_RELEASE, type ScaffoldRelease, type ScaffoldRuntimeRelease, type ScaffoldSourceRelease, isStableScaffoldRelease };
+export { STABLE_SCAFFOLD_RELEASE, SUPPORTED_SCAFFOLD_RELEASES, type ScaffoldOwnershipContract, type ScaffoldRelease, type ScaffoldRuntimeRelease, type ScaffoldSourceRelease, type StarterReleaseManifest, isStableScaffoldRelease };

package/dist/release.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import {
   STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES,
   isStableScaffoldRelease
-} from "./chunk-PJW4JJIT.js";
+} from "./chunk-RLGB6QF3.js";
 export {
   STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES,
   isStableScaffoldRelease
 };

package/dist/scaffold.d.ts

@@ -1,16 +1,31 @@
 export { STABLE_SCAFFOLD_RELEASE } from './release.js';
 
 /**
- * The live Thally documentation site is also the canonical standalone site
- * source. Keeping one source means a runtime or UI improvement shipped to the
- * docs is available to every subsequent scaffold without maintaining a second
- * template repository.
+ * Immutable starter archive download and extraction.
+ *
+ * The dedicated starter repository is already a customer-ready project. Every
+ * safe filesystem entry is extracted; there is no exclusion list or second
+ * manifest that can silently produce a different scaffold.
  */
-declare const TEMPLATE_REPOSITORY: "thallylabs/docs";
-declare const TEMPLATE_COMMIT_SHA: "b0094de4fea84567eb12c39c6783fdae6820bb98";
-declare const EXCLUDE_PATHS: string[];
-/** True if a tarball entry should land in the scaffold (see EXCLUDE_PATHS). */
-declare function shouldInclude(path: string): boolean;
+
+/** Repository whose complete tree becomes every newly scaffolded site. */
+declare const STARTER_REPOSITORY: string;
+/** Exact starter commit consumed by every creation surface. */
+declare const STARTER_COMMIT_SHA: string;
+/** GitHub codeload's single top-level directory for the pinned archive. */
+declare const STARTER_ARCHIVE_ROOT: string;
+interface StarterArchiveEntryMetadata {
+    type: string;
+    size: number;
+}
+/**
+ * Validate one codeload entry before `strip: 1` can write it to disk.
+ *
+ * Git cannot store devices or FIFOs, and starter sites do not need links. A
+ * release containing one is rejected rather than partially extracted because
+ * the entire repository tree is the immutable contract.
+ */
+declare function validateStarterArchiveEntry(archivePath: string, entry: StarterArchiveEntryMetadata, archiveRoot?: string): void;
 
 interface ScaffoldOptions {
     projectDir: string;
@@ -35,4 +50,4 @@ interface ScaffoldResult {
 }
 declare function scaffold(options: ScaffoldOptions): Promise<ScaffoldResult>;
 
-export { EXCLUDE_PATHS, type ScaffoldOptions, type ScaffoldResult, TEMPLATE_COMMIT_SHA, TEMPLATE_REPOSITORY, scaffold, shouldInclude };
+export { STARTER_ARCHIVE_ROOT, STARTER_COMMIT_SHA, STARTER_REPOSITORY, type ScaffoldOptions, type ScaffoldResult, scaffold, validateStarterArchiveEntry };

package/dist/scaffold.js

@@ -1,20 +1,23 @@
 #!/usr/bin/env node
 import {
-  EXCLUDE_PATHS,
-  TEMPLATE_COMMIT_SHA,
-  TEMPLATE_REPOSITORY,
-  scaffold,
-  shouldInclude
-} from "./chunk-JNDRCCJV.js";
-import "./chunk-BW7J7DJV.js";
+  scaffold
+} from "./chunk-2N74PW2Y.js";
+import "./chunk-ORUAMPNF.js";
+import {
+  STARTER_ARCHIVE_ROOT,
+  STARTER_COMMIT_SHA,
+  STARTER_REPOSITORY,
+  validateStarterArchiveEntry
+} from "./chunk-TMXBINSI.js";
+import "./chunk-IJXZ4YRL.js";
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-PJW4JJIT.js";
+} from "./chunk-RLGB6QF3.js";
 export {
-  EXCLUDE_PATHS,
   STABLE_SCAFFOLD_RELEASE,
-  TEMPLATE_COMMIT_SHA,
-  TEMPLATE_REPOSITORY,
+  STARTER_ARCHIVE_ROOT,
+  STARTER_COMMIT_SHA,
+  STARTER_REPOSITORY,
   scaffold,
-  shouldInclude
+  validateStarterArchiveEntry
 };

package/dist/starter-sync.d.ts

@@ -0,0 +1,68 @@
+import { ScaffoldOwnershipContract, ScaffoldRelease, StarterReleaseManifest } from './release.js';
+
+/**
+ * Ownership-aware, three-way planning for future starter runtime updates.
+ *
+ * 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.
+ */
+
+type StarterPathOwnership = 'protected' | 'manual' | 'syncable' | 'unmanaged';
+interface StarterRuntimeSyncPlan {
+    copyPaths: string[];
+    deletePaths: string[];
+    conflictPaths: string[];
+    manualReviewPaths: string[];
+    preservedPaths: string[];
+    unchangedPaths: string[];
+    targetPreconditions: Record<string, StarterTargetPrecondition>;
+}
+interface StarterTargetPrecondition {
+    kind: 'missing' | 'file';
+    sha256?: string;
+}
+interface StarterApplyProvenance {
+    sourcePath: string;
+    targetPath: string;
+    expectedSha256: string;
+}
+interface ApplyStarterRuntimeSyncOptions {
+    /** Explicit acknowledgement that the caller reviewed this exact plan. */
+    confirmed: boolean;
+    /** Optional immutable provenance file, atomically replaced after mutations. */
+    provenance?: StarterApplyProvenance;
+    /** Integration hook; an exception aborts and rolls back the transaction. */
+    onMutationApplied?: (path: string, index: number) => void;
+}
+/** Parse and validate the ownership section in `starter-release.json`. */
+declare function parseStarterOwnershipContract(value: unknown): ScaffoldOwnershipContract;
+/**
+ * Combine the previous and next release policies without weakening ownership.
+ *
+ * A later starter may broaden framework ownership, but it cannot retroactively
+ * make a path safe to overwrite when either release marked that path as owner
+ * controlled or manual-review. Classification precedence enforces that union.
+ */
+declare function mergeStarterOwnershipContracts(previous: ScaffoldOwnershipContract, next: ScaffoldOwnershipContract): ScaffoldOwnershipContract;
+/** Stable SHA-256 of the exact manifest bytes promoted with a release. */
+declare function starterManifestSha256(source: string): string;
+/**
+ * Parse the archive-owned release manifest and bind it to its promoted source,
+ * runtime identity, and SHA-256. Branch names never participate in updates.
+ */
+declare function parseStarterReleaseManifest(source: string, release?: ScaffoldRelease): StarterReleaseManifest;
+/** Read and validate the canonical ownership manifest from an extracted archive. */
+declare function readStarterReleaseManifest(starterDir: string, release?: ScaffoldRelease): StarterReleaseManifest;
+/** Protected > manual-review > syncable > unmanaged. */
+declare function classifyStarterPath(path: string, contract: ScaffoldOwnershipContract): StarterPathOwnership;
+/**
+ * Build a safe three-way update plan from the recorded old starter, the new
+ * starter, and the customer's current tree.
+ */
+declare function planStarterRuntimeSync(oldStarterDir: string, newStarterDir: string, targetDir: string, ownership: ScaffoldOwnershipContract): StarterRuntimeSyncPlan;
+/** 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 };

package/dist/starter-sync.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import {
+  applyStarterRuntimeSyncPlan,
+  classifyStarterPath,
+  mergeStarterOwnershipContracts,
+  parseStarterOwnershipContract,
+  parseStarterReleaseManifest,
+  planStarterRuntimeSync,
+  readStarterReleaseManifest,
+  starterManifestSha256
+} from "./chunk-IJXZ4YRL.js";
+import "./chunk-RLGB6QF3.js";
+export {
+  applyStarterRuntimeSyncPlan,
+  classifyStarterPath,
+  mergeStarterOwnershipContracts,
+  parseStarterOwnershipContract,
+  parseStarterReleaseManifest,
+  planStarterRuntimeSync,
+  readStarterReleaseManifest,
+  starterManifestSha256
+};

package/dist/starter-update.d.ts

@@ -0,0 +1,43 @@
+import { ScaffoldRelease } from './release.js';
+import { StarterRuntimeSyncPlan } from './starter-sync.js';
+
+/**
+ * User-reachable orchestration for immutable starter release updates.
+ *
+ * Projects carry the exact bytes of `starter-release.json`. The manifest hash
+ * resolves the old release from the toolchain's retained immutable catalog;
+ * neither the old nor new side follows a branch. Updates are dry-run by
+ * default and advance provenance only after a confirmed, conflict-free apply.
+ */
+
+interface StarterUpdateDownload {
+    (targetDir: string, release: ScaffoldRelease): Promise<void>;
+}
+interface UpdateStarterProjectOptions {
+    targetDir: string;
+    /** Applying is opt-in. Omitted/false always produces a dry-run plan. */
+    apply?: boolean;
+    /** Separate acknowledgement for programmatic callers. */
+    confirmed?: boolean;
+    targetRelease?: ScaffoldRelease;
+    releases?: readonly ScaffoldRelease[];
+    download?: StarterUpdateDownload;
+}
+interface StarterUpdateResult {
+    previousRelease: ScaffoldRelease;
+    targetRelease: ScaffoldRelease;
+    plan: StarterRuntimeSyncPlan;
+    isUpToDate: boolean;
+    applied: boolean;
+}
+/** Resolve exact downstream provenance without consulting a moving branch. */
+declare function resolveStarterReleaseFromManifest(source: string, releases?: readonly ScaffoldRelease[]): ScaffoldRelease;
+/**
+ * Plan or explicitly apply an immutable three-way starter update.
+ *
+ * Direct GitHub-template copies need no generated state beyond the canonical
+ * manifest: its pinned hash selects the old archive from the retained catalog.
+ */
+declare function updateStarterProject(options: UpdateStarterProjectOptions): Promise<StarterUpdateResult>;
+
+export { type StarterUpdateDownload, type StarterUpdateResult, type UpdateStarterProjectOptions, resolveStarterReleaseFromManifest, updateStarterProject };

package/dist/starter-update.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import {
+  downloadStarter
+} from "./chunk-TMXBINSI.js";
+import {
+  applyStarterRuntimeSyncPlan,
+  mergeStarterOwnershipContracts,
+  parseStarterReleaseManifest,
+  planStarterRuntimeSync,
+  readStarterReleaseManifest,
+  starterManifestSha256
+} from "./chunk-IJXZ4YRL.js";
+import {
+  STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES
+} from "./chunk-RLGB6QF3.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.1",
   "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"
   },