@dbx-tools/projen 0.6.195 → 0.6.197

package/README.md

@@ -128,10 +128,15 @@ in dependency order; adding or
 removing a crate or `setup_scaffolding!()` marker triggers a full synth. Repos
 without Rust crates start no Rust watcher. When Rust projects are detected,
 Cargo is required and the focused task fails immediately if it is unavailable.
+`rs:bindings` is explicit rather than part of root `pre-compile`, so ordinary
+JavaScript PR builds type-check committed generated bindings without performing
+a host Rust build. Release preparation runs Cargo workspace tests and
+regenerates bindings before JavaScript validation.
 
 The workspace generates one `release.yml` workflow for every ecosystem. A push
-to the configured release branch starts it. The context job reads `VERSION`,
-creates the corresponding annotated `v*` tag, and exposes the verified tag,
+to the configured release branch starts it only when `VERSION` changed. The
+context job requires the version to differ from its parent and exceed the latest
+tag, creates the corresponding annotated `v*` tag, and exposes the verified tag,
 commit, and version to every source job. If the tag already exists, it must be
 annotated and reference the same commit. A manual run accepts that same tag and
 commit but requires dry-run mode, so it builds and validates without publishing
@@ -189,7 +194,7 @@ Set `LOCAL_CARGO_REGISTRY` to a named Cargo registry such as a loopback
 Cargo crates also publish directly to crates.io
 with `CARGO_REGISTRY_TOKEN`. Override `releaseTargets` only when a consumer has
 additional native runners; ordinary projects inherit the maintained matrix
-automatically. `bun run bump` also accepts repeatable `--os` and `--arch`
+automatically. `bun run release` also accepts repeatable `--os` and `--arch`
 selectors; every selected operating system is crossed with every selected
 architecture. Omit both filters to regenerate the complete maintained matrix.
 `DBX_TOOLS_RELEASE_PLATFORMS` can select the generated matrix without repeating
@@ -383,22 +388,27 @@ Every repo-wide task lives on the root, and the root's `compile` / `test`
 delegate with `bun run --filter '*'` rather than emitting a step per member - so
 a new package is covered without a re-synth. Work from the root:
 
-| Task              | What it does                                          |
-| ----------------- | ----------------------------------------------------- |
-| `bun run build`   | workspace `compile` + `test`; no root package fan-out |
-| `bun run compile` | `tsc --build` in each member, in parallel             |
-| `bun run test`    | `eslint` once, then each member's tests               |
-| `bun run sync`    | re-synth (`--watch` to keep synthing)                 |
-| `bun run barrels` | regenerate the read-only `index.ts` barrels           |
-| `bun run bump`    | version, commit, and push the current branch          |
-
-`bump` also mirrors a release into local registries when the active clients are
-pointed at loopback services. npm uses `npm config get registry` and publishes
-to a local Verdaccio automatically. Publishable JavaScript members compile once
+| Task                    | What it does                                            |
+| ----------------------- | ------------------------------------------------------- |
+| `bun run build`         | synth + workspace compile and tests                     |
+| `bun run compile`       | `tsc --build` in each member, in parallel               |
+| `bun run test`          | `eslint` once, then each member's tests                 |
+| `bun run sync`          | re-synth (`--watch` to keep synthing)                   |
+| `bun run barrels`       | regenerate the read-only `index.ts` barrels             |
+| `bun run bump`          | increment `VERSION` and synchronize generated versions  |
+| `bun run version:check` | verify every version surface matches `VERSION`          |
+| `bun run release`       | run full local preflight and open a reviewed release PR |
+
+`release` commits pending work on the current branch, pushes it, creates a
+dedicated `release/v<version>` branch, invokes the pure `bump` task, validates
+the complete workspace, runs local publication, and opens a PR into the
+configured release branch. `--message` sets the source commit message. The task
+never merges the PR unless `--approve` is passed; that option requests an
+immediate admin merge so the main release can start without waiting for PR
+checks. npm uses `npm config get registry` and publishes to a local Verdaccio
+automatically. Publishable JavaScript members compile once
 from the root in parallel, then upload through a bounded pool without rerunning
-their `prepack` tasks. When synth already made the manifests and Bun workspace
-lock release-current, publishing also skips redundant version stamping and the
-lockfile reinstall. Python prefers uv's default index and only
+their `prepack` tasks. Python prefers uv's default index and only
 treats a loopback `.../+simple/` URL as writable devpi; a read-only cache such as
 proxpi (`.../index/`) is deliberately ignored. The task stamps every Python
 member and its sibling dependencies to the release version, builds the workspace
@@ -410,14 +420,18 @@ Use `--local-registry false` or `--local-pypi false` to disable either local
 publish. An explicit `--local-pypi http://localhost:3141/user/index/` overrides
 auto-detection; `--python-root` defaults to `packages/py`.
 
-The configured release branch is the publication trigger. Its workflow creates
-the annotated `v*` public release boundary from `VERSION`. Available workflow
+The GitHub PR workflow runs synth plus the workspace TypeScript compile rather
+than the complete root build. Release preparation has already run Rust tests,
+binding generation, workspace tests, and local package preflight before opening
+the PR.
+
+The configured release branch publishes only when a reviewed PR changes
+`VERSION`. Its workflow creates the annotated `v*` public release boundary.
+Available workflow
 stages form the generated chain Rust -> Python -> Node -> docs: Rust builds and
 publishes native artifacts and Cargo crates, Python publishes standard
 distributions, Node publishes standard workspace packages, and docs deploys
-after publication. A stage with no corresponding outputs is omitted. Keep
-ongoing development on another branch when every release-branch update should
-publish.
+after publication. A stage with no corresponding outputs is omitted.
 
 Members intentionally keep only the tasks that something OTHER than a human
 invokes, so there is no second place to run the same thing:
@@ -429,8 +443,8 @@ invokes, so there is no second place to run the same thing:
 - `watch` - a single-package `tsc --build -w`, for narrowing a long
   edit/compile loop to one package.
 - `build` / `package` - a complete compile/test/pack lifecycle when invoked in
-  one package. Root bump deliberately bypasses these and uses filtered compile
-  plus concurrent `bun publish --ignore-scripts`. The package phase also packs
+  one package. Release preparation validates through the root's filtered tasks,
+  and publication uses concurrent `bun publish --ignore-scripts`. The package phase also packs
   with `--ignore-scripts` because its build already compiled; `prepack` remains
   available for a standalone publish that did not run `build` first.
 - `install` / `install:ci` / `default` / `pre-compile` / `post-compile` -
@@ -452,9 +466,9 @@ example apps - so the packages, the engine, and the examples always match.
 `src/workspace-version.ts` owns reading and writing it. Synth only ever reads it;
 it never resets, upgrades, or downgrades a version on its own.
 
-`bun run bump` is the only command that changes the number: it fetches the remote
-tags once, takes the highest tag across `v*` and every sibling prefix as the base
-(falling back to the local `VERSION` file when the remote is unreachable or has no
-tag), increments by `--level`, writes `VERSION`, then synths so every manifest
-copies it. The remote is consulted only on `bump` and on one-time creation of a
-missing `VERSION` file - never on an ordinary synth.
+`bun run bump` is the only command that changes the number: it fetches remote
+tags once, takes the highest `v*` tag as the base, increments by `--level`, writes
+`VERSION`, then synths so every manifest copies it. It has no git or publication
+side effects. `bun run release` invokes it while preparing the reviewed release
+PR. The remote is consulted only on `bump` and on one-time creation of a missing
+`VERSION` file, never on an ordinary synth.

package/index.ts

@@ -3,7 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/projen";
-export const PACKAGE_VERSION = "0.6.194";
+export const PACKAGE_VERSION = "0.6.197";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -64,4 +64,4 @@ export type { TypeScriptBindingModule } from "./src/uniffi.ts";
 export { DBXToolsVsCode } from "./src/vscode.ts";
 export type { IgnoreGroupOptions } from "./src/watch.ts";
 export { VERSION_FILE, DEFAULT_VERSION } from "./src/workspace-version.ts";
-export type { Semver } from "./src/workspace-version.ts";
+export type { Semver, VersionLevel } from "./src/workspace-version.ts";

package/package.json

@@ -25,9 +25,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "0.6.195",
-    "@dbx-tools/path": "0.6.195",
-    "@dbx-tools/shared-core": "0.6.195",
+    "@dbx-tools/core": "0.6.197",
+    "@dbx-tools/path": "0.6.197",
+    "@dbx-tools/shared-core": "0.6.197",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -47,7 +47,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.6.195",
+  "version": "0.6.197",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/pnpm-workspace.ts

@@ -40,6 +40,7 @@
  */
 import { relative } from "node:path";
 import { javascript, type Project } from "projen";
+import { BUN_VERSION } from "./bun-workflow.ts";
 import { toPosix } from "./packages.ts";
 
 /**
@@ -63,8 +64,8 @@ export type AllowBuilds = Record<string, boolean>;
  * always available at `catalog:` without a per-repo override.
  */
 const DEFAULT_CATALOG: Catalog = {
-  react: "^19.2.4",
-  "react-dom": "^19.2.4",
+  react: "~19.2.4",
+  "react-dom": "~19.2.4",
   "@types/react": "^19.2.2",
   "@types/react-dom": "^19.2.2",
   // Tailwind v4 compiler for bun's dev server + `Bun.build` (the `app` tag).
@@ -117,6 +118,7 @@ const DEFAULT_ALLOW_BUILDS: AllowBuilds = {
 };
 
 const DEFAULT_OVERRIDES: Readonly<Record<string, string>> = {
+  bun: BUN_VERSION,
   glob: "^13.0.0",
 };
 

package/src/project-js.ts

@@ -44,7 +44,7 @@ import { DBXToolsRelease, type ReleaseDocsOptions } from "./release.ts";
 import { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS, type PackageTag } from "./tags.ts";
 import { DBXToolsRootTsconfig } from "./tsconfig.ts";
 import { DBXToolsVsCode } from "./vscode.ts";
-import { readWorkspaceVersion } from "./workspace-version.ts";
+import { readWorkspaceVersion, syncWorkspaceManifestVersion } from "./workspace-version.ts";
 
 /**
  * The dbx-tools project surface, backed by projen's Node toolchain. A single
@@ -415,10 +415,10 @@ function defaultProjectOptions(
     // would omit the key - except that `npmProvenance` then defaults on and forces
     // the block to render, giving the root a `publishConfig` it does not have
     // today. Provenance is never written to a manifest here (projen only reads it
-    // in its own `Publisher`, and `release: false` means none exists); the
-    // The release workflow opts in per run through `npm_config_provenance`.
-    // instead, so LOCAL publishes to a verdaccio still work with no CI OIDC
-    // provider. See {@link DBXToolsRelease}.
+    // in its own `Publisher`, and `release: false` means none exists). The release
+    // workflow opts in per run through `npm_config_provenance`, so local publishes
+    // to Verdaccio still work without a CI OIDC provider. See
+    // {@link DBXToolsRelease}.
     ...(isRoot ? {} : { npmAccess: javascript.NpmAccess.PUBLIC }),
     buildWorkflow: false,
     workflowPackageCache: false,
@@ -426,8 +426,7 @@ function defaultProjectOptions(
     // The root build validates the whole workspace and must not also pack every
     // member into unused `dist/js` tarballs. Child projects keep projen's package
     // task so `bun run build` in ONE package remains a complete compile/test/pack
-    // operation. The root bump does not invoke child builds: its publish driver
-    // compiles once with filtered root tasks and packs via
+    // operation. Release publication compiles once with filtered root tasks and packs via
     // `bun publish --ignore-scripts` (see {@link applyCompiledPublish}).
     ...(isRoot ? { package: false } : {}),
     jest: false,
@@ -450,7 +449,9 @@ function defaultProjectOptions(
           prettierOptions: {
             settings: PRETTIER_SETTINGS,
             ignoreFile: true,
-            ignoreFileOptions: { ignorePatterns: [...ignore.ignorePatterns({ test: false })] },
+            ignoreFileOptions: {
+              ignorePatterns: [...ignore.ignorePatterns({ test: false, lock: true })],
+            },
           },
         }
       : {}),
@@ -656,6 +657,10 @@ export class DBXToolsNodeProject
   public override preSynthesize(): void {
     if (this.rootInstallOnly) this.with(ROOT_INSTALL_ONLY_MIXIN);
     super.preSynthesize();
+    const version = readWorkspaceVersion(this.outdir);
+    for (const member of this.extraWorkspaceMembers) {
+      syncWorkspaceManifestVersion(join(this.outdir, member, "package.json"), version);
+    }
     // Members come from the attached subprojects, which the root's scan appends
     // after construction - so the list is filled here, not in the constructor.
     // `extraWorkspaceMembers` adds self-synthesizing siblings (e.g. `projen/`).
@@ -834,6 +839,29 @@ class WorkspaceValidationTasks extends Component {
  */
 class WorkflowDefaults extends Component {
   public override preSynthesize(): void {
+    const project = this.project as javascript.NodeProject;
+    const workflow = project.buildWorkflow?.workflow;
+    if (workflow) {
+      const job = workflow.getJob("build");
+      if ("steps" in job) {
+        const mutableJob = job as unknown as { steps: JobStep[] | (() => JobStep[]) };
+        const configuredSteps = mutableJob.steps;
+        const rewrite = (steps: JobStep[]): JobStep[] =>
+          steps.map((step) =>
+            step.name === "build"
+              ? {
+                  ...step,
+                  name: "Validate generated files and types",
+                  run: "bunx projen default\nbun run compile",
+                }
+              : step,
+          );
+        mutableJob.steps =
+          typeof configuredSteps === "function"
+            ? () => rewrite(configuredSteps())
+            : rewrite(configuredSteps);
+      }
+    }
     const build = this.project.tryFindObjectFile(".github/workflows/build.yml");
     for (const job of ["build", "self-mutation"]) {
       build?.addOverride(`jobs.${job}.timeout-minutes`, 30);
@@ -890,6 +918,7 @@ class PrettierIgnoreGenerated extends Component {
   public override preSynthesize(): void {
     const prettier = javascript.Prettier.of(this.project);
     if (!prettier) return;
+    prettier.addIgnorePattern("**/src/generated/**");
     const rootAbs = resolve(this.project.outdir);
     for (const sub of this.project.subprojects) {
       if (!(sub instanceof javascript.NodeProject)) continue;
@@ -1115,7 +1144,9 @@ function initProject(
   // to re-include a file whose parent directory is excluded - so every per-file
   // `!/.github/...` negation projen emits for its own generated files silently
   // does nothing, and the file cannot be added at all.
-  project.gitignore.addPatterns(...[...ignore.ignorePatterns({ test: false, dot: false })]);
+  project.gitignore.addPatterns(
+    ...[...ignore.ignorePatterns({ test: false, dot: false, lock: true })],
+  );
   // What the dot group was actually earning here, named explicitly: secrets and
   // local editor state. Both ignore CONTENTS (`.idea/*`) rather than the
   // directory, so a later `!` negation can still reach a file inside.
@@ -1156,6 +1187,7 @@ function initProject(
     eslint.addIgnorePattern(`${root}/openapi/**`);
     eslint.addIgnorePattern(`${root}/**/index.ts`);
   }
+  eslint.addIgnorePattern("**/src/generated/**");
   eslint.addIgnorePattern("projen/index.ts");
   // The generated bun app scripts + unmanaged overrides live at the package root,
   // outside any `src/**` tsconfig include, so the type-aware parser cannot resolve
@@ -1253,9 +1285,8 @@ function initProject(
   new PrettierIgnoreGenerated(project);
 
   new GeneratedSource(project);
-  // The `bump` task (compute next version + commit + tag + push) is useful on
-  // any root; the actual publish is a tag-triggered GitHub workflow the caller
-  // authors. Independent of projen's own `release` component.
+  // Version mutation, reviewed release preparation, and public publication are
+  // separate surfaces owned by one release component.
   new DBXToolsRelease(project as DBXToolsNodeProject, {
     tagPrefix: options.releaseTagPrefix,
     nodeRelease: options.nodeRelease,

package/src/project-rs.ts

@@ -2,9 +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 { 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";
@@ -337,6 +337,19 @@ if (process.env.GITHUB_OUTPUT) {
 `;
 }
 
+/** 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;
@@ -893,17 +906,15 @@ 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) {
       new TextFile(project, ".projen/cargo-cache-key.mjs", {

package/src/release.ts

@@ -136,7 +136,7 @@ function verifyContextJob(tagPrefix: string, releaseBranch: string): Job {
         uses: "actions/checkout@v6",
         with: {
           ref: "${{ github.event_name == 'push' && github.sha || inputs.expected_sha }}",
-          "fetch-depth": 1,
+          "fetch-depth": 2,
         },
       },
       {
@@ -158,12 +158,26 @@ function verifyContextJob(tagPrefix: string, releaseBranch: string): Job {
           '  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"',
@@ -307,7 +321,7 @@ 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);
@@ -319,8 +333,25 @@ export class DBXToolsRelease extends Component {
       bump: {
         exec: taskScript(project, "bump.ts", `--prefix ${tagPrefix}`),
         receiveArgs: true,
-        description: "Bump the release version (default patch), then commit 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;
 
@@ -332,7 +363,7 @@ export class DBXToolsRelease extends Component {
     workflow.runName =
       "release ${{ github.event_name == 'push' && github.sha || inputs.release_tag }}";
     workflow.on({
-      push: { branches: [releaseBranch] },
+      push: { branches: [releaseBranch], paths: ["VERSION"] },
       workflowDispatch: {
         inputs: {
           release_tag: {

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