@dbx-tools/projen 0.6.194 → 0.6.196

package/src/project-rs.ts

@@ -2,10 +2,9 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { project as coreProject } from "@dbx-tools/core";
+import { exec, project as coreProject } from "@dbx-tools/core";
 import { string } from "@dbx-tools/shared-core";
-import { Project, TextFile, javascript } from "projen";
-import { GithubWorkflow } from "projen/lib/github";
+import { Component, Project, TextFile, javascript } from "projen";
 import { JobPermission, type JobStep } from "projen/lib/github/workflows-model";
 import { BUN_VERSION } from "./bun-workflow.ts";
 import { DBXToolsTypeScriptProject, projectRepositoryUrl } from "./project-js.ts";
@@ -84,7 +83,7 @@ export interface DBXToolsRustWorkspaceOptions {
   readonly pythonRoot?: string;
   readonly pythonModulePrefix?: string;
   readonly private?: boolean;
-  /** Generate tag-driven cross-platform UniFFI package releases. */
+  /** Generate release-branch-driven cross-platform UniFFI package releases. */
   readonly release?: boolean;
   /** Native release targets; defaults to the maintained GitHub-hosted matrix. */
   readonly releaseTargets?: readonly UniFFIReleaseTarget[];
@@ -174,30 +173,35 @@ export const UNIFFI_RELEASE_TARGETS: readonly UniFFIReleaseTarget[] = [
   },
 ] as const;
 
+const UBRN_VERSION = "0.31.0-5";
+const RELEASE_PLATFORMS_ENV = "DBX_TOOLS_RELEASE_PLATFORMS";
 const RUST_CACHE_ENV = {
   CARGO_INCREMENTAL: "0",
   CARGO_TERM_COLOR: "always",
 } as const;
-const UBRN_VERSION = "0.31.0-5";
-const RELEASE_PLATFORMS_ENV = "DBX_TOOLS_RELEASE_PLATFORMS";
 
-function rustCacheSteps(
-  sharedKey: string,
-  idPrefix = "",
-  saveIf = true,
-): readonly Record<string, unknown>[] {
+function cargoCacheKeyStep(): Record<string, unknown> {
+  return {
+    name: "Resolve Cargo dependency cache key",
+    id: "cargo_cache_key",
+    run: "node .projen/cargo-cache-key.mjs",
+  };
+}
+
+function rustCacheSteps(sharedKey: string): readonly Record<string, unknown>[] {
   return [
     {
-      name: "Cache Cargo registry and targets",
-      id: `${idPrefix}cargo_cache`,
+      name: "Cache Cargo registry and dependencies",
+      id: "cargo_cache",
       uses: "Swatinem/rust-cache@v2.9.2",
       with: {
         "cache-targets": true,
         "cache-workspace-crates": false,
         "add-job-id-key": false,
-        "add-rust-environment-hash-key": true,
+        "add-rust-environment-hash-key": false,
+        key: "${{ steps.cargo_cache_key.outputs.key }}",
         "shared-key": sharedKey,
-        "save-if": saveIf,
+        "save-if": "${{ github.event_name == 'push' }}",
       },
     },
   ];
@@ -273,6 +277,79 @@ function uniffiReleaseTaskSource(): string {
   return readFileSync(source, "utf8");
 }
 
+function cargoCacheKeySource(): string {
+  return `#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+function command(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(\`\${command} exited with \${result.status}\`);
+  return result.stdout;
+}
+
+const hasLock = existsSync("Cargo.lock");
+const metadata = JSON.parse(
+  command("cargo", [
+    "metadata",
+    ...(hasLock ? ["--locked"] : []),
+    "--format-version",
+    "1",
+    "--no-deps",
+  ]),
+);
+const workspaceNames = new Set(metadata.packages.map((pkg) => pkg.name));
+const dependencyLock = hasLock
+  ? readFileSync("Cargo.lock", "utf8")
+      .split("[[package]]")
+      .slice(1)
+      .filter((block) => {
+        const name = /^\\s*name = "([^"]+)"/m.exec(block)?.[1];
+        return name && !workspaceNames.has(name);
+      })
+      .map((block) => \`[[package]]\${block}\`)
+      .join("")
+  : "";
+const manifests = [
+  metadata.workspace_root + "/Cargo.toml",
+  ...metadata.packages.map((pkg) => pkg.manifest_path),
+]
+  .map((path) =>
+    readFileSync(path, "utf8").replace(/^version = "[0-9]+\\.[0-9]+\\.[0-9]+"\\s*$/gm, ""),
+  )
+  .join("\\n");
+const config = existsSync(".cargo/config.toml")
+  ? readFileSync(".cargo/config.toml", "utf8")
+  : "";
+const key = createHash("sha256")
+  .update(dependencyLock)
+  .update(manifests)
+  .update(config)
+  .update(command("rustc", ["-vV"]))
+  .digest("hex");
+if (process.env.GITHUB_OUTPUT) {
+  appendFileSync(process.env.GITHUB_OUTPUT, \`key=\${key}\\n\`);
+} else {
+  process.stdout.write(\`\${key}\\n\`);
+}
+`;
+}
+
+/** Keep tracked workspace package versions in Cargo.lock aligned with VERSION. */
+class RustWorkspaceVersionLock extends Component {
+  public override postSynthesize(): void {
+    exec.spawnSync("cargo", ["metadata", "--format-version", "1", "--no-deps"], {
+      cwd: this.project.outdir,
+      stdout: "ignore",
+      stderr: "inherit",
+      stdin: "ignore",
+      check: true,
+    });
+  }
+}
+
 /** Persisted mapping consumed by the focused Rust source watcher. */
 export interface RustBindingMapping {
   readonly crate: string;
@@ -829,125 +906,24 @@ export class DBXToolsRustWorkspace {
         .trimEnd()
         .split("\n"),
     });
+    new RustWorkspaceVersionLock(project);
     project.addTask("rs:format", { exec: "cargo fmt --all" });
     project.addTask("rs:lint", { exec: "cargo clippy --workspace --all-targets --all-features" });
     project.addTask("rs:test", { exec: "cargo test --workspace" });
     project.addTask("rs:build", { exec: "cargo build --workspace" });
-    const bindingsTask = project.addTask("rs:bindings", {
+    project.addTask("rs:bindings", {
       exec: "bun node_modules/@dbx-tools/projen/tasks/rust.ts",
       description: "Generate language bindings for UniFFI-enabled Rust crates",
     });
-    if (this.bindingMappings.some((binding) => binding.node)) {
-      project.tasks.tryFind("pre-compile")?.spawn(bindingsTask);
-    }
     project.removeTask("rs:bindings:demo");
     if (releaseEnabled) {
-      this.addCacheWorkflow(project, options, nativeTargets);
+      new TextFile(project, ".projen/cargo-cache-key.mjs", {
+        lines: cargoCacheKeySource().trimEnd().split("\n"),
+      });
       this.addReleaseWorkflow(project, options, nativeTargets);
     }
   }
 
-  private addCacheWorkflow(
-    project: javascript.NodeProject,
-    options: DBXToolsRustWorkspaceOptions,
-    targets: readonly UniFFIReleaseTarget[],
-  ): void {
-    if (!project.github || !isDBXToolsJavaScriptProject()(project) || targets.length === 0) return;
-    const releaseRustVersion = options.releaseRustVersion ?? "stable";
-    const usePreinstalledWindowsRust = releaseRustVersion === "stable";
-    const usesCargoLock = existsSync(join(project.outdir, "Cargo.lock"));
-    const hasReleaseExclusions = this.packages.some(
-      (pkg) => pkg.packageOptions.releaseExcludeOs?.length,
-    );
-    const matrix = targets.map((target) => ({
-      ...target,
-      ...(hasReleaseExclusions
-        ? {
-            cargoExcludes: this.packages
-              .filter((pkg) => pkg.packageOptions.releaseExcludeOs?.includes(target.os))
-              .map((pkg) => `--exclude ${pkg.crateName}`)
-              .join(" "),
-          }
-        : {}),
-    }));
-    const workflow = new GithubWorkflow(project.github, "rust-cache", {
-      fileName: "rust-cache.yml",
-      limitConcurrency: true,
-      concurrencyOptions: { group: "rust-cache", cancelInProgress: true },
-    });
-    workflow.on({
-      push: {
-        branches: ["main"],
-        paths: [
-          ".cargo/**",
-          ".github/workflows/rust-cache.yml",
-          "Cargo.lock",
-          "Cargo.toml",
-          "packages/rs/**",
-        ],
-      },
-      workflowDispatch: {},
-    });
-    workflow.addJob("prime", {
-      name: "${{ matrix.node }}",
-      runsOn: ["${{ matrix.runner }}"],
-      permissions: { contents: JobPermission.READ },
-      env: RUST_CACHE_ENV,
-      strategy: {
-        failFast: false,
-        matrix: { include: matrix },
-      },
-      steps: [
-        { name: "Checkout", uses: "actions/checkout@v6" },
-        {
-          name: "Setup Rust",
-          ...(usePreinstalledWindowsRust ? { if: "${{ matrix.os != 'win32' }}" } : {}),
-          uses: `dtolnay/rust-toolchain@${releaseRustVersion}`,
-          with: { targets: "${{ matrix.cargo }}" },
-        },
-        ...(usePreinstalledWindowsRust
-          ? [
-              {
-                name: "Verify preinstalled Windows Rust",
-                if: "${{ matrix.os == 'win32' }}",
-                shell: "bash",
-                run: [
-                  "rustc --version --verbose",
-                  "cargo --version",
-                  'rustup target list --installed | grep -Fx "${{ matrix.cargo }}"',
-                  'test -f "$(rustc --print sysroot)/lib/rustlib/${{ matrix.cargo }}/bin/rust-lld.exe"',
-                ].join("\n"),
-              },
-            ]
-          : []),
-        ...rustCacheSteps(`release-\${{ matrix.cargo }}-rust-${releaseRustVersion}`),
-        {
-          name: "Install Linux native dependencies",
-          if: "${{ matrix.os == 'linux' }}",
-          run: [
-            "sudo rm -f /etc/apt/sources.list.d/google-chrome.list",
-            "sudo apt-get update",
-            "sudo apt-get install --yes libdbus-1-dev pkg-config",
-          ].join("\n"),
-        },
-        {
-          name: "Prime Cargo target cache",
-          shell: "bash",
-          env: {
-            CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER:
-              "${{ matrix.os == 'win32' && 'rust-lld' || '' }}",
-          },
-          run: timedBash(
-            "rust_cache",
-            `cargo build --release --workspace${usesCargoLock ? " --locked" : ""} --target "\${{ matrix.cargo }}"${
-              hasReleaseExclusions ? " ${{ matrix.cargoExcludes }}" : ""
-            }`,
-          ),
-        },
-      ],
-    });
-  }
-
   private addReleaseWorkflow(
     project: javascript.NodeProject,
     options: DBXToolsRustWorkspaceOptions,
@@ -1142,15 +1118,8 @@ export class DBXToolsRustWorkspace {
               },
             ]
           : []),
-        ...rustCacheSteps(`release-\${{ matrix.cargo }}-rust-${releaseRustVersion}`, "", false),
-        {
-          name: "Log cache configuration",
-          shell: "bash",
-          run: [
-            `echo "cargo_cache_namespace=release-\${{ matrix.cargo }}-rust-${releaseRustVersion}"`,
-            'echo "cargo_cache_hit=${{ steps.cargo_cache.outputs.cache-hit }}"',
-          ].join("\n"),
-        },
+        cargoCacheKeyStep(),
+        ...rustCacheSteps(`release-\${{ matrix.cargo }}-rust-${releaseRustVersion}`),
         {
           name: "Install Linux native dependencies",
           if: "${{ matrix.os == 'linux' }}",

package/src/release.ts

@@ -1,9 +1,9 @@
-/** Unified tag-driven release workflow generation. */
+/** Unified default-branch release workflow generation. */
 import { Component } from "projen";
 import { GithubWorkflow } from "projen/lib/github";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
 import { BUN_VERSION, bunCacheRestoreSteps, bunCacheSaveStep } from "./bun-workflow.ts";
-import type { DBXToolsJavaScriptProject } from "./project-js.ts";
+import { projectReleaseBranch, type DBXToolsJavaScriptProject } from "./project-js.ts";
 import { applyTasks, taskScript } from "./project.ts";
 import { RELEASE_VERSION, releaseSourceSteps } from "./release-dispatch.ts";
 
@@ -44,14 +44,14 @@ export function hasNodeRelease(project: DBXToolsJavaScriptProject): boolean {
   return nodeReleaseProjects.has(project);
 }
 
-/** Tag pattern accepted by release jobs and GitHub environments. */
+/** Tag pattern created by release jobs and accepted by manual recovery. */
 export function releaseTagPattern(project: DBXToolsJavaScriptProject): string {
   const prefix = releaseTagPrefixes.get(project);
   if (!prefix) throw new Error("Release workflow is not configured");
   return `${prefix}*`;
 }
 
-/** Run a release stage on tag pushes or when selected for manual recovery. */
+/** Run a release stage on default-branch pushes or when selected for manual recovery. */
 export function releaseStageCondition(stage: Exclude<ReleaseStage, "all">): string {
   return `\${{ github.event_name == 'push' || inputs.stage == 'all' || inputs.stage == '${stage}' }}`;
 }
@@ -121,10 +121,10 @@ export function npmPublishEnvironment(): Record<string, string> {
   };
 }
 
-function verifyContextJob(tagPrefix: string): Job {
+function verifyContextJob(tagPrefix: string, releaseBranch: string): Job {
   return {
     runsOn: ["ubuntu-latest"],
-    permissions: { actions: JobPermission.READ, contents: JobPermission.READ },
+    permissions: { actions: JobPermission.READ, contents: JobPermission.WRITE },
     outputs: {
       release_tag: { stepId: "release", outputName: "release_tag" },
       expected_sha: { stepId: "release", outputName: "expected_sha" },
@@ -132,11 +132,11 @@ function verifyContextJob(tagPrefix: string): Job {
     },
     steps: [
       {
-        name: "Checkout release tag",
+        name: "Checkout release source",
         uses: "actions/checkout@v6",
         with: {
-          ref: "${{ github.event_name == 'push' && github.ref || inputs.expected_sha }}",
-          "fetch-depth": 1,
+          ref: "${{ github.event_name == 'push' && github.sha || inputs.expected_sha }}",
+          "fetch-depth": 2,
         },
       },
       {
@@ -145,18 +145,50 @@ function verifyContextJob(tagPrefix: string): Job {
         shell: "bash",
         env: {
           RELEASE_TAG:
-            "${{ github.event_name == 'push' && github.ref_name || inputs.release_tag }}",
+            "${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || '' }}",
           EXPECTED_SHA:
             "${{ github.event_name == 'workflow_dispatch' && inputs.expected_sha || '' }}",
           DRY_RUN: "${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}",
         },
         run: [
-          `case "$RELEASE_TAG" in ${tagPrefix}*) ;; *) exit 1 ;; esac`,
-          'git fetch --force origin "+refs/tags/$RELEASE_TAG:refs/tags/$RELEASE_TAG"',
-          'test "$(git cat-file -t "$RELEASE_TAG")" = "tag"',
-          'RELEASE_SHA="$(git rev-parse "$RELEASE_TAG^{commit}")"',
-          'test "$(git rev-parse HEAD)" = "$RELEASE_SHA"',
-          'if [ "$GITHUB_EVENT_NAME" = "workflow_dispatch" ]; then',
+          'if [ "$GITHUB_EVENT_NAME" = "push" ]; then',
+          '  test "$GITHUB_REF_TYPE" = "branch"',
+          `  test "$GITHUB_REF_NAME" = "${releaseBranch}"`,
+          '  RELEASE_SHA="$GITHUB_SHA"',
+          '  test "$(git rev-parse HEAD)" = "$RELEASE_SHA"',
+          "  RELEASE_VERSION=\"$(tr -d '\\r\\n' < VERSION)\"",
+          '  [[ "$RELEASE_VERSION" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+$ ]]',
+          '  PREVIOUS_VERSION="$(git show "$RELEASE_SHA^:VERSION" | tr -d \'\\r\\n\')"',
+          '  test "$PREVIOUS_VERSION" != "$RELEASE_VERSION"',
+          `  RELEASE_TAG="${tagPrefix}$RELEASE_VERSION"`,
+          '  if git ls-remote --exit-code --tags origin "refs/tags/$RELEASE_TAG" >/dev/null 2>&1; then',
+          '    git fetch --force origin "+refs/tags/$RELEASE_TAG:refs/tags/$RELEASE_TAG"',
+          '    test "$(git cat-file -t "$RELEASE_TAG")" = "tag"',
+          '    test "$(git rev-parse "$RELEASE_TAG^{commit}")" = "$RELEASE_SHA"',
+          "  else",
+          "    git fetch --force --tags origin",
+          '    LATEST_VERSION=""',
+          `    for TAG in $(git tag --sort=-version:refname --list '${tagPrefix}*'); do`,
+          `      CANDIDATE="\${TAG#${tagPrefix}}"`,
+          '      if [[ "$CANDIDATE" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+$ ]]; then',
+          '        LATEST_VERSION="$CANDIDATE"',
+          "        break",
+          "      fi",
+          "    done",
+          '    if [ -n "$LATEST_VERSION" ]; then',
+          '      node -e \'const a=process.argv[1].split(".").map(Number); const b=process.argv[2].split(".").map(Number); if (!(b[0]>a[0] || b[0]===a[0] && (b[1]>a[1] || b[1]===a[1] && b[2]>a[2]))) process.exit(1)\' "$LATEST_VERSION" "$RELEASE_VERSION"',
+          "    fi",
+          '    git config user.name "github-actions[bot]"',
+          '    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
+          '    git tag -a "$RELEASE_TAG" "$RELEASE_SHA" -m "$RELEASE_TAG"',
+          '    git push origin "refs/tags/$RELEASE_TAG"',
+          "  fi",
+          "else",
+          `  case "$RELEASE_TAG" in ${tagPrefix}*) ;; *) exit 1 ;; esac`,
+          '  git fetch --force origin "+refs/tags/$RELEASE_TAG:refs/tags/$RELEASE_TAG"',
+          '  test "$(git cat-file -t "$RELEASE_TAG")" = "tag"',
+          '  RELEASE_SHA="$(git rev-parse "$RELEASE_TAG^{commit}")"',
+          '  test "$(git rev-parse HEAD)" = "$RELEASE_SHA"',
           '  test "$GITHUB_REF_TYPE" = "tag"',
           '  test "$GITHUB_REF_NAME" = "$RELEASE_TAG"',
           '  test "$RELEASE_SHA" = "$EXPECTED_SHA"',
@@ -289,31 +321,49 @@ function addDocsJobs(
   });
 }
 
-/** Owns the single release workflow and the local bump task. */
+/** Owns the single release workflow and local release preparation tasks. */
 export class DBXToolsRelease extends Component {
   constructor(project: DBXToolsJavaScriptProject, options: DBXToolsReleaseOptions = {}) {
     super(project);
     const tagPrefix = options.tagPrefix ?? "v";
+    const releaseBranch = projectReleaseBranch(project);
     releaseTagPrefixes.set(project, tagPrefix);
     if (options.nodeRelease !== false) nodeReleaseProjects.add(project);
     applyTasks(project, {
       bump: {
         exec: taskScript(project, "bump.ts", `--prefix ${tagPrefix}`),
         receiveArgs: true,
-        description: "Bump the release version (default patch), then commit, tag, and push it",
+        description: "Increment VERSION and synchronize generated workspace versions",
+      },
+      "version:check": {
+        exec: taskScript(project, "version-check.ts"),
+        description: "Verify every package and generated barrel matches VERSION",
       },
+      ...(project.github
+        ? {
+            release: {
+              exec: taskScript(
+                project,
+                "release-pr.ts",
+                `--prefix ${tagPrefix} --base ${releaseBranch}`,
+              ),
+              receiveArgs: true,
+              description: "Prepare, validate, locally publish, and open a reviewed release PR",
+            },
+          }
+        : {}),
     });
     if (!project.github) return;
 
     const workflow = new GithubWorkflow(project.github, "release", {
       fileName: "release.yml",
       limitConcurrency: true,
-      concurrencyOptions: { group: "release", cancelInProgress: true },
+      concurrencyOptions: { group: "release", cancelInProgress: false },
     });
     workflow.runName =
-      "release ${{ github.event_name == 'push' && github.ref_name || inputs.release_tag }}";
+      "release ${{ github.event_name == 'push' && github.sha || inputs.release_tag }}";
     workflow.on({
-      push: { tags: [`${tagPrefix}*`] },
+      push: { branches: [releaseBranch], paths: ["VERSION"] },
       workflowDispatch: {
         inputs: {
           release_tag: {
@@ -350,7 +400,7 @@ export class DBXToolsRelease extends Component {
     });
     workflow.file?.addOverride("permissions.contents", "read");
     workflow.file?.addOverride("on.workflow_dispatch.inputs.dry_run.default", true);
-    workflow.addJob("verify-context", verifyContextJob(tagPrefix));
+    workflow.addJob("verify-context", verifyContextJob(tagPrefix, releaseBranch));
     if (options.nodeRelease !== false) {
       workflow.addJob("publish-node", nodePublishJob(project));
     }

package/src/workspace-version.ts

@@ -8,14 +8,14 @@
  * DEFAULT_VERSION} when it is absent on a fresh tree); it never rewrites it, so an
  * ordinary `bunx projen` cannot move a package version up or down.
  *
- * Only two callers change the number: `bump` (which increments it) and the
- * one-time bootstrap of a workspace that has no `VERSION` yet. Both resolve the
- * base from the remote git tags first ({@link resolveRemoteVersion}) so a release
- * cut elsewhere is respected, and fall back to the local file (or {@link
- * DEFAULT_VERSION}) when the remote is unreachable or has no tags. The remote is
- * consulted ONLY on those two paths, never on every synth/compile/commit.
+ * Only two callers change the number: the pure `bump` task used while preparing
+ * a reviewed release PR, and the one-time bootstrap of a workspace that has no
+ * `VERSION` yet. Both resolve the base from remote git tags first ({@link
+ * resolveRemoteVersion}) so a release cut elsewhere is respected, and fall back
+ * to the local file (or {@link DEFAULT_VERSION}) when the remote is unreachable
+ * or has no tags. The remote is consulted only on those paths.
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { exec } from "@dbx-tools/core";
 
@@ -30,6 +30,9 @@ const SEMVER = /^\d+\.\d+\.\d+$/;
 /** A parsed `[major, minor, patch]` tuple. */
 export type Semver = [number, number, number];
 
+/** Supported semantic release increments. */
+export type VersionLevel = "patch" | "minor" | "major";
+
 /** Parse `x.y.z` (ignoring any leading `v`/prefix), or `undefined` when it does not match. */
 export function parseSemver(raw: string): Semver | undefined {
   const m = /(\d+)\.(\d+)\.(\d+)/.exec(raw.trim());
@@ -41,6 +44,13 @@ export function compareSemver(a: Semver, b: Semver): number {
   return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
 }
 
+/** Increment a semantic version tuple by the requested release level. */
+export function incrementSemver(version: Semver, level: VersionLevel): Semver {
+  if (level === "major") return [version[0] + 1, 0, 0];
+  if (level === "minor") return [version[0], version[1] + 1, 0];
+  return [version[0], version[1], version[2] + 1];
+}
+
 /** Absolute path to the `VERSION` file for a workspace root. */
 export function versionPath(root: string): string {
   return join(root, VERSION_FILE);
@@ -70,6 +80,30 @@ export function writeWorkspaceVersion(root: string, version: string): void {
   writeFileSync(versionPath(root), `${version}\n`);
 }
 
+/**
+ * Synchronize one existing workspace manifest with the authoritative version.
+ *
+ * This covers workspace members that synthesize themselves and therefore are
+ * not child projects of the root. Missing manifests are ignored so a freshly
+ * bootstrapped extra member can create its package metadata independently.
+ */
+export function syncWorkspaceManifestVersion(manifestPath: string, version: string): boolean {
+  if (!existsSync(manifestPath)) return false;
+  const content = readFileSync(manifestPath, "utf8");
+  const manifest = JSON.parse(content) as Record<string, unknown>;
+  if (manifest.version === version) return false;
+
+  manifest.version = version;
+  const { mode } = statSync(manifestPath);
+  chmodSync(manifestPath, mode | 0o200);
+  try {
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  } finally {
+    chmodSync(manifestPath, mode);
+  }
+  return true;
+}
+
 /** Run git in `cwd`, capturing stdout and swallowing failure (offline, no repo). */
 function gitCapture(cwd: string, args: string[]): string {
   try {
@@ -138,6 +172,22 @@ export function resolveBaseVersion(
   return { version: readWorkspaceVersion(root), source: "local" };
 }
 
+/** Resolve the next release version without mutating the workspace. */
+export function resolveNextVersion(
+  root: string,
+  prefixes: readonly string[],
+  level: VersionLevel,
+  options: { fetch?: boolean } = {},
+): { base: string; version: string; source: "remote" | "local" } {
+  const base = resolveBaseVersion(root, prefixes, options);
+  const parsed = parseSemver(base.version) ?? [0, 0, 1];
+  return {
+    base: parsed.join("."),
+    version: incrementSemver(parsed, level).join("."),
+    source: base.source,
+  };
+}
+
 /**
  * Create the `VERSION` file when it does not yet exist, seeding it from the remote
  * tags (or {@link DEFAULT_VERSION} when the remote is unreachable / has no tag). An