@dbx-tools/projen 0.6.194 → 0.6.196

package/README.md

@@ -128,14 +128,20 @@ 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.
-
-The workspace generates one `release.yml` workflow for every ecosystem. An
-annotated `v*` tag starts it directly. The context job resolves the tag to a
-commit, requires the tag object to be annotated, and exposes the verified tag,
-commit, and version to every source job. A manual run accepts that same tag and
+`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 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
-packages or deploying documentation. One `release` concurrency group cancels a
-superseded run.
+packages or deploying documentation. One non-cancelling `release` concurrency
+group serializes publication.
 
 Release generation writes `release.yml` without scanning for or removing other
 workflow files. Consumers explicitly delete exact workflow files they no longer
@@ -146,15 +152,15 @@ For a separate recovery run, choose `node`, `python`, or `docs` instead of
 `all`. Node and Python recovery can supply the prior `release.yml` run ID; the
 workflow verifies that run used the commit selected by the annotated release
 tag before downloading its artifacts. Dispatch the workflow with the release
-tag as its Git ref so environment tag policies still apply. Manual recovery
+tag as its Git ref so recovery checks out the immutable release boundary. Manual recovery
 defaults to dry-run and publishes only when `dry_run` is cleared. npm retries skip an exact version only
 after the local archive integrity and repository identity match registry
 metadata. PyPI retries enable Twine's hash-aware existing-file behavior, which
 skips matching files and fails when an existing filename has different content.
 
 The Rust matrix has one row per target. Each row installs native dependencies,
-restores Cargo and sccache once, builds the Cargo workspace once, then packages
-every discovered output from that shared build. Set a source-only crate's or
+builds the Cargo workspace once, then packages every discovered output from
+that shared build. Set a source-only crate's or
 release-enabled binary's `releaseExcludeOs` package option to omit it from
 incompatible rows through Cargo `--exclude`. Release binary packaging and
 artifact upload are skipped in those rows. UniFFI crates cannot use this option
@@ -171,10 +177,11 @@ Node facades. A binary-only row therefore installs no language package tool.
 `rustVersion` remains the MSRV recorded in package manifests, while
 `releaseRustVersion` independently defaults release compilation to `stable`.
 Stable Windows rows verify and use the hosted runner's installed Rust toolchain
-and select `rust-lld` for the workspace build. Cargo registry caches
-and the `SCCACHE_GHA_VERSION` namespace stay stable per target/toolchain across
-version tags. Cache keys, restore results, sccache statistics, and phase timings
-are written to each build log. Python generation executes the already-built
+and select `rust-lld` for the workspace build. Rust release rows restore and
+update dependency-only Cargo caches in the release branch's cache scope. The
+cache key excludes workspace version changes, and manual tag recovery restores
+without saving a tag-scoped copy. There is no separate cache workflow or
+sccache layer. Phase timings are written to each build log. Python generation executes the already-built
 `target/<triple>/release/<crate>-uniffi-bindgen` directly. Artifact packaging therefore
 does no Rust compilation after the main workspace build.
 
@@ -187,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
@@ -204,7 +211,7 @@ to run the optional nonblocking registry install and import check after facade
 publication. Python combines same-run platform wheels with standard wheel and
 source builds, then publishes each distribution through its own PyPI
 trusted-publisher environment. Binding publishers wait for their dependencies.
-Trusted-publisher instructions name `release.yml` and the release tag policy.
+Trusted-publisher instructions name `release.yml` and the release branch policy.
 The docs jobs generate README and TypeScript API content and deploy GitHub Pages
 from the same workflow. When a conventional Node binding path already belongs
 to a root subproject, Rust mapping reuses that project and adds binding
@@ -381,22 +388,25 @@ 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, tag, and publish                             |
-
-`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. 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
@@ -408,12 +418,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 pushed `v*` tag is also the public release boundary. 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. Ordinary
-pushes to `main` publish none of those surfaces.
+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:
@@ -425,8 +441,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` -
@@ -448,9 +464,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.193";
+export const PACKAGE_VERSION = "0.6.196";
 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.194",
-    "@dbx-tools/path": "0.6.194",
-    "@dbx-tools/shared-core": "0.6.194",
+    "@dbx-tools/core": "0.6.196",
+    "@dbx-tools/path": "0.6.196",
+    "@dbx-tools/shared-core": "0.6.196",
     "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.194",
+  "version": "0.6.196",
   "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
-    // tag-driven `release` workflow opts in per-run via `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-py.ts

@@ -6,7 +6,7 @@ import type { IResolver } from "projen/lib/file";
 import { JobPermission } from "projen/lib/github/workflows-model";
 import { parse, stringify } from "smol-toml";
 import { BUN_VERSION, bunCacheRestoreSteps, bunCacheSaveStep } from "./bun-workflow.ts";
-import { projectRepositoryUrl } from "./project-js.ts";
+import { projectReleaseBranch, projectRepositoryUrl } from "./project-js.ts";
 import { isDBXToolsJavaScriptProject } from "./project-predicate.ts";
 import type { DBXToolsProject, DBXToolsProjectOptions } from "./project.ts";
 import { RELEASE_VERSION, releaseSourceSteps } from "./release-dispatch.ts";
@@ -14,7 +14,6 @@ import {
   releaseArtifactSteps,
   releasePublishCondition,
   releaseStageCondition,
-  releaseTagPattern,
   releaseWorkflow,
 } from "./release.ts";
 import { readWorkspaceVersion } from "./workspace-version.ts";
@@ -577,13 +576,15 @@ export class DBXToolsPythonWorkspace extends Component {
   ): void {
     const repository = this.githubRepository();
     const publications = this.trustedPublisherPublications(options);
-    const releaseTags = isDBXToolsJavaScriptProject()(project) ? releaseTagPattern(project) : "v*";
+    const releaseBranch = isDBXToolsJavaScriptProject()(project)
+      ? projectReleaseBranch(project)
+      : "main";
     const linesBeforeAuthentication = [
       "# PyPI Trusted Publisher Setup Instructions",
       "",
       "Use the system browser to audit and configure the PyPI trusted publishers below.",
       "Do not use an in-app browser or embedded webview.",
-      "Do not visit GitHub or use the GitHub API or CLI. Every required GitHub owner, repository, workflow, environment, and tag value is provided below and is authoritative.",
+      "Do not visit GitHub or use the GitHub API or CLI. Every required GitHub owner, repository, workflow, environment, and branch value is provided below and is authoritative.",
       "Use only PyPI pages for this task.",
       "",
       "## Audit and confirmation",
@@ -601,7 +602,7 @@ export class DBXToolsPythonWorkspace extends Component {
       "",
       "## GitHub environment policy",
       "",
-      `- The supplied tag policy value is ${releaseTags}.`,
+      `- The supplied branch policy value is ${releaseBranch}.`,
       "- Do not inspect or configure GitHub environments during this task.",
       "- GitHub environment administration is a separate task; use the supplied values only when comparing PyPI publisher entries.",
       "",
@@ -642,7 +643,7 @@ export class DBXToolsPythonWorkspace extends Component {
           `- Repository name: ${repository.name}`,
           "- Workflow name: release.yml",
           `- Environment name: ${publication.environment}`,
-          `- GitHub environment tag: ${releaseTags}`,
+          `- GitHub environment branch: ${releaseBranch}`,
           ...(publication.artifacts ? [`- Artifacts: ${publication.artifacts}`] : []),
           "",
         ];