@dbx-tools/projen 0.9.38 → 0.9.43

package/README.md

@@ -58,16 +58,16 @@ workflow.
 Repository policy stays in the consuming `.projenrc.ts`:
 
 - `releaseDocs` supplies repository-defined preparation and build steps plus
-  the Pages artifact path. The engine adds release checkout, Bun caching,
-  artifact upload, and deployment without naming a docs script or output tree.
+  the Pages artifact path. The engine adds release checkout, artifact upload,
+  and deployment without naming a docs script or output tree.
 - `releasePythonRoot` passes the actual Python package root to local release
   preparation. Omit it when the workspace has no standard Python packages.
 - `releaseValidationTasks` names repository tasks that must pass in tag CI
   before release artifacts are built and published.
+- `releaseSetupSteps` installs any extra validation/build prerequisites in the
+  shared release job before the validation tasks run.
 - `pullRequestTitlePolicy` configures semantic title types and scope policy.
   Omit it or pass `false` to disable the title job.
-- `workflowCacheIgnorePaths` excludes generated output trees that may contain
-  package manifests from the dependency-only Bun cache key.
 - `extraWorkspaceMembers` declares self-synthesizing tooling packages outside
   `packageRoots`. Their version, generated entrypoint, formatting, linting, and
   workspace membership are derived from that declaration.
@@ -380,17 +380,45 @@ list, so a new package is covered without a re-synth. Work from the root:
 | `bun run version:check` | verify every generated version against `VERSION`    |
 | `bun run release`       | run the configured release transaction              |
 
-Run exactly `bun run release` from any branch. Pending changes are committed and
+Run `bun run release` from any branch. Pending changes are committed and
 the current branch is pushed first. A non-`main` branch then fast-forwards
 `main`; the command fails without creating a merge commit if either branch has
 diverged. From `main`, it calls the existing `bump` task, commits the generated
 version changes, pushes `main`, and pushes the matching annotated `vX.Y.Z` tag.
 Pass `--no-bump` only to release an existing synchronized local bump. The tag
-workflow verifies that the tag points at the exact `origin/main` commit,
-publishes npm and PyPI directly from that checkout, then builds and deploys
-documentation. Local npm and Python registry publication remains available
+workflow verifies that the tag points at the exact `origin/main` commit. One
+`build-release` job installs workspace dependencies, runs validation, packs the
+npm archives, builds all Python distributions, and builds the documentation
+site. Install validation prerequisites through `releaseSetupSteps`;
+`releaseDocs.prepareSteps` runs after validation.
+
+Publication jobs download the resulting artifacts rather than rebuilding the
+workspace. Each Python package retains its own publishing environment and waits
+for its package dependencies to publish. The npm job uses the bundled archive
+publisher without a checkout or workspace install. Pages deploys the already
+built site after registry publication succeeds. Local npm and Python registry publication remains available
 through the direct local publication tooling.
 
+The default release still publishes npm, Python, and docs, then publishes to
+configured local registries automatically. Select a scope or disable individual
+steps for one run without changing the Projen definition:
+
+```sh
+bun run release --publish pypi --no-docs
+bun run release --no-npm --no-local-publish
+bun run release --publish local --install never
+bun run release --local-registry false --local-pypi auto
+```
+
+`--install auto` keeps Projen's normal local dependency-install behavior;
+`always` performs a frozen install first, and `never` uses dependencies already
+installed while still regenerating versioned sources. `--no-validation` skips
+optional task checks locally and in CI, not version or immutable-source checks.
+`--no-docs` skips building and deploying the site, not package README validation.
+Scopes select artifacts, not the normal commit and tag-push transaction.
+The annotated tag records CI step selections, so publishing a selected scope does
+not change the next release's defaults. Local registry URLs stay local.
+
 Members intentionally keep only the tasks that something OTHER than a human
 invokes, so there is no second place to run the same thing:
 
@@ -402,7 +430,7 @@ invokes, so there is no second place to run the same thing:
   edit/compile loop to one package.
 - `build` / `package` - a complete compile/test/pack lifecycle when invoked in
   one package. Release preparation validates through the root's filtered tasks,
-  and publication concurrently uploads archives that were each packed and
+  and publication uploads archives that were each packed and
   validated once with lifecycle scripts disabled. 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.
@@ -421,3 +449,39 @@ from the root instead.
 Projen-owned and reproduce it exactly across JavaScript and Python packages.
 Release jobs publish the generated workspace inventory in dependency-safe
 workflow order without introducing another version owner.
+
+<!-- cli-reference:start -->
+
+## Command Reference
+
+### `release`
+
+Prepare an annotated release and select its build and publication steps
+
+```sh
+release [options]
+```
+
+#### Options
+
+| Option                                | Description                                                                                   |
+| ------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `--root <path>`                       | repository root                                                                               |
+| `--branch <name>`                     | release branch (default: "main")                                                              |
+| `--prefix <prefix>`                   | release tag prefix (default: "v")                                                             |
+| `--remote <name>`                     | git remote (default: "origin")                                                                |
+| `--python-root <path>`                | Python package root for local publish (default: "packages/py")                                |
+| `--validate <task>`                   | task to run before pushing (default: [])                                                      |
+| `--no-bump`                           | use an existing synchronized local version bump                                               |
+| `--publish <target>`                  | publication scope (choices: "auto", "npm", "pypi", "local", "none", default: "auto")          |
+| `--install <mode>`                    | local workspace dependency installation (choices: "auto", "always", "never", default: "auto") |
+| `--no-npm`                            | skip npm build and publication, including local npm publication                               |
+| `--no-pypi`                           | skip Python build and publication, including local Python publication                         |
+| `--docs`                              | build and deploy docs for a selected scope                                                    |
+| `--no-docs`                           | skip documentation build and deployment                                                       |
+| `--no-validation`                     | skip optional release validation tasks; version/source checks remain mandatory                |
+| `--no-local-publish`                  | skip publishing to configured local registries                                                |
+| `--local-registry <auto\|false\|url>` | local npm registry selection (default: "auto")                                                |
+| `--local-pypi <auto\|false\|url>`     | local devpi registry selection (default: "auto")                                              |
+
+<!-- cli-reference:end -->

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.9.38";
+export const PACKAGE_VERSION = "0.9.43";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -27,6 +27,7 @@ export * as pythonNodeBindings from "./src/python-node-bindings.ts";
 export * as pythonNodeBundle from "./src/python-node-bundle.ts";
 export * as release from "./src/release.ts";
 export * as releaseContext from "./src/release-context.ts";
+export * as releaseOptions from "./src/release-options.ts";
 export * as scaffold from "./src/scaffold.ts";
 export * as tags from "./src/tags.ts";
 export * as tsconfig from "./src/tsconfig.ts";
@@ -36,7 +37,6 @@ export * as workspaceLock from "./src/workspace-lock.ts";
 export * as workspaceVersion from "./src/workspace-version.ts";
 export { BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE, BUN_APP_OVERRIDES, RootBunfigFile, BunfigFile, BunDevServerFile, BunBuildFile } from "./src/bun-app.ts";
 export { BUN_VERSION } from "./src/bun-workflow.ts";
-export type { BunWorkflowCacheOptions } from "./src/bun-workflow.ts";
 export { DBXToolsConfig } from "./src/dbx-tools-config.ts";
 export type { DBXToolsConfigOptions } from "./src/dbx-tools-config.ts";
 export { resolvePkgRoot } from "./src/engine-root.ts";
@@ -60,7 +60,9 @@ export { PythonNodeBundle } from "./src/python-node-bundle.ts";
 export type { PythonNodeFunctionOverride, PythonNodeBindingsOptions, PythonNodeBundleOptions } from "./src/python-node-bundle.ts";
 export { DBXToolsRelease } from "./src/release.ts";
 export type { ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
-export { RELEASE_TAG, RELEASE_SHA, RELEASE_VERSION } from "./src/release-context.ts";
+export { RELEASE_VERSION } from "./src/release-context.ts";
+export { RELEASE_PUBLISH_TARGETS, RELEASE_INSTALL_MODES } from "./src/release-options.ts";
+export type { ReleasePublishTarget, ReleaseInstallMode, ReleaseStepSelection, ReleaseSelectionOptions } from "./src/release-options.ts";
 export { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS } from "./src/tags.ts";
 export type { PackageTag } from "./src/tags.ts";
 export { DBXToolsRootTsconfig } from "./src/tsconfig.ts";

package/package.json

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

package/src/bun-workflow.ts

@@ -1,172 +1,12 @@
-/** Shared Bun setup and package-cache steps for generated workflows. */
-import { stringUtils } from "@dbx-tools/shared-core";
-import { TextFile, javascript } from "projen";
+/** Shared Bun setup for generated workflows. */
 
 export const BUN_VERSION = "1.3.14";
 
-const DEFAULT_CACHE_IGNORE_PATHS = [
-  ".git",
-  ".venv",
-  ".worktrees",
-  "coverage",
-  "dist",
-  "lib",
-  "node_modules",
-  "target",
-] as const;
-
-function cacheKeyScript(extraIgnorePaths: readonly string[]): string {
-  const ignorePaths = [...new Set(extraIgnorePaths)].sort();
-  // prettier-ignore
-  const source = (
-    // ============================================================================
-    /*js*/`
-  #!/usr/bin/env node
-  import { createHash } from "node:crypto";
-  import { readdirSync, readFileSync } from "node:fs";
-  import { join, sep } from "node:path";
-
-  const root = process.cwd();
-  const ignoredNames = new Set(${JSON.stringify(DEFAULT_CACHE_IGNORE_PATHS)});
-  const ignoredPaths = new Set(${JSON.stringify(ignorePaths)});
-  const manifests = [];
-  const walk = (directory) => {
-    for (const entry of readdirSync(directory, { withFileTypes: true })) {
-      const path = join(directory, entry.name);
-      const relativePath = path.slice(root.length + 1).split(sep).join("/");
-      if (ignoredNames.has(entry.name) || ignoredPaths.has(relativePath)) continue;
-      if (entry.isDirectory()) walk(path);
-      else if (entry.name === "package.json") manifests.push(path);
-    }
-  };
-  walk(root);
-
-  const dependencyFields = [
-    "catalog",
-    "dependencies",
-    "devDependencies",
-    "optionalDependencies",
-    "overrides",
-    "peerDependencies",
-    "peerDependenciesMeta",
-    "resolutions",
-    "trustedDependencies",
-  ];
-  const canonical = (value) => {
-    if (Array.isArray(value)) return value.map(canonical);
-    if (!value || typeof value !== "object") return value;
-    return Object.fromEntries(
-      Object.entries(value)
-        .sort(([left], [right]) => left.localeCompare(right))
-        .map(([key, child]) => [key, canonical(child)]),
-    );
-  };
-  const dependencies = manifests
-    .sort()
-    .map((path) => {
-      const manifest = JSON.parse(readFileSync(path, "utf8"));
-      return [
-        path.slice(root.length + 1),
-        Object.fromEntries(
-          dependencyFields
-            .filter((field) => manifest[field] !== undefined)
-            .map((field) => [field, canonical(manifest[field])]),
-        ),
-      ];
-    });
-  process.stdout.write(createHash("sha256").update(JSON.stringify(dependencies)).digest("hex"));
-  `
-    // ============================================================================
-  );
-  return stringUtils.dedent(source, { trimEnd: false });
-}
-
-const configured = new WeakMap<javascript.NodeProject, string>();
-
-function ensureCacheKeyScript(
-  project: javascript.NodeProject,
-  ignorePaths: readonly string[],
-): void {
-  const root = project.root as javascript.NodeProject;
-  const key = JSON.stringify([...new Set(ignorePaths)].sort());
-  const existing = configured.get(root);
-  if (existing !== undefined) {
-    if (existing !== key) {
-      throw new Error("Bun workflow cache ignore paths must be consistent across one project");
-    }
-    return;
-  }
-  new TextFile(root, ".projen/bun-cache-key.mjs", {
-    lines: cacheKeyScript(ignorePaths).trimEnd().split("\n"),
-  });
-  configured.set(root, key);
-}
-
-function stepCondition(condition: string | undefined, cacheMiss = false): string | undefined {
-  const expressions = [
-    condition,
-    ...(cacheMiss ? ["steps.bun_cache.outputs.cache-hit != 'true'"] : []),
-  ].filter(Boolean);
-  return expressions.length ? `\${{ ${expressions.join(" && ")} }}` : undefined;
-}
-
-export interface BunWorkflowCacheOptions {
-  readonly setupCondition?: string;
-  readonly condition?: string;
-  /** Repository-relative output paths excluded from dependency manifest hashing. */
-  readonly ignorePaths?: readonly string[];
-}
-
-/** Set up Bun and restore its global package cache. */
-export function bunCacheRestoreSteps(
-  project: javascript.NodeProject,
-  options: BunWorkflowCacheOptions = {},
-): readonly Record<string, unknown>[] {
-  ensureCacheKeyScript(project, options.ignorePaths ?? []);
-  const condition = stepCondition(options.condition);
-  const setupCondition = stepCondition(options.setupCondition);
-  return [
-    {
-      name: "Setup Bun",
-      ...(setupCondition ? { if: setupCondition } : {}),
-      uses: "oven-sh/setup-bun@v2",
-      with: { "bun-version": "${{ env.BUN_VERSION }}" },
-    },
-    {
-      name: "Resolve Bun cache",
-      id: "bun_cache_metadata",
-      ...(condition ? { if: condition } : {}),
-      shell: "bash",
-      run: [
-        'echo "path=$(bun pm cache)" >> "$GITHUB_OUTPUT"',
-        'echo "dependency_hash=$(node .projen/bun-cache-key.mjs)" >> "$GITHUB_OUTPUT"',
-      ].join("\n"),
-    },
-    {
-      name: "Restore Bun cache",
-      id: "bun_cache",
-      ...(condition ? { if: condition } : {}),
-      uses: "actions/cache/restore@v5",
-      with: {
-        path: "${{ steps.bun_cache_metadata.outputs.path }}",
-        key: `bun-\${{ runner.os }}-\${{ runner.arch }}-\${{ env.BUN_VERSION }}-\${{ steps.bun_cache_metadata.outputs.dependency_hash }}`,
-        "restore-keys": `bun-\${{ runner.os }}-\${{ runner.arch }}-\${{ env.BUN_VERSION }}-`,
-      },
-    },
-  ];
-}
-
-/** Save Bun's global package cache immediately after installation. */
-export function bunCacheSaveStep(
-  options: BunWorkflowCacheOptions = {},
-): Readonly<Record<string, unknown>> {
+/** Install the pinned Bun version. */
+export function bunSetupStep(): Readonly<Record<string, unknown>> {
   return {
-    name: "Save Bun cache",
-    if: stepCondition(options.condition, true),
-    uses: "actions/cache/save@v5",
-    with: {
-      path: "${{ steps.bun_cache_metadata.outputs.path }}",
-      key: "${{ steps.bun_cache.outputs.cache-primary-key }}",
-    },
+    name: "Setup Bun",
+    uses: "oven-sh/setup-bun@v2",
+    with: { "bun-version": "${{ env.BUN_VERSION }}" },
   };
 }

package/src/codegen.ts

@@ -316,9 +316,9 @@ function generatePackage(
     const sourceText = preprocess(stripImports(tsRuntime, sourcePath));
     const { getZodSchemasFile, getInferredTypes, errors } = generate({
       sourceText,
-      // Carry JSDoc through so the `@description` tag stays visible alongside
-      // the matching `.describe(...)`.
-      keepComments: true,
+      // JSDoc is rewritten to `@description` so ts-to-zod emits `.describe()`.
+      // Keep the generated module comment-free; Zod owns the prose.
+      keepComments: false,
     });
     if (errors.length) {
       for (const err of errors) logger.warn(`${destination} from ${source}: ${err}`);

package/src/project-js.ts

@@ -18,7 +18,7 @@ import type { ReleaseProjectOptions } from "projen/lib/release";
 import { generateBarrels } from "./barrels.ts";
 
 import { BUN_APP_OVERRIDES, RootBunfigFile } from "./bun-app.ts";
-import { BUN_VERSION, bunCacheRestoreSteps, bunCacheSaveStep } from "./bun-workflow.ts";
+import { BUN_VERSION, bunSetupStep } from "./bun-workflow.ts";
 import { codegenModulePaths, generateCodegen } from "./codegen.ts";
 import { DBXToolsConfig, type DBXToolsConfigOptions } from "./dbx-tools-config.ts";
 import { resolvePkgRoot } from "./engine-root.ts";
@@ -61,8 +61,6 @@ export interface DBXToolsJavaScriptProject extends DBXToolsProject, javascript.N
   pnpmWorkspace?: PnpmWorkspaceState;
   /** Root projenrc tsconfigs - only a tree ROOT has one. */
   rootTsconfig?: DBXToolsRootTsconfig;
-  /** Repository outputs excluded from generated workflow dependency-cache hashing. */
-  readonly workflowCacheIgnorePaths: readonly string[];
 }
 
 /** Parsed npm package identifier: optional scope plus the unscoped package name. */
@@ -573,14 +571,14 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
     readonly releasePythonRoot?: string;
     /** Repository task names run during local release preparation before publication. */
     readonly releaseValidationTasks?: readonly string[];
+    /** Release build prerequisites installed before repository validation tasks. */
+    readonly releaseSetupSteps?: readonly JobStep[];
     /** Set to `false` to omit normal npm workspace publication. */
     readonly nodeRelease?: boolean;
     /** Unified dbx-tools release workflow, or no release surface. Defaults to `dbx-tools`. */
     readonly releaseMode?: DBXToolsReleaseMode;
     /** Prefix for generated release tags. Defaults to `v`. */
     readonly releaseTagPrefix?: string;
-    /** Repository output paths excluded from generated workflow dependency-cache hashing. */
-    readonly workflowCacheIgnorePaths?: readonly string[];
     /**
      * Extra workspace member paths (repo-relative, POSIX) to list in the workspace
      * config ALONGSIDE the discovered `packageRoots` members - for a package that
@@ -607,16 +605,6 @@ export type DBXToolsTypeScriptProjectOptions = Partial<
 > &
   DBXToolsJavaScriptProjectOptions;
 
-const initializingWorkflowCachePaths = new Map<string, readonly string[]>();
-
-function configuredOutdir(
-  options: Pick<DBXToolsJavaScriptProjectOptions, "parent" | "outdir">,
-): string {
-  return options.parent
-    ? resolve(options.parent.outdir, options.outdir ?? ".")
-    : resolve(options.outdir ?? process.cwd());
-}
-
 /**
  * A monorepo root. Scans `packageRoots` and appends a
  * {@link DBXToolsTypeScriptProject} per `src`-bearing folder, then emits the
@@ -633,7 +621,6 @@ export class DBXToolsNodeProject
   rootTsconfig?: DBXToolsRootTsconfig;
   readonly extraWorkspaceMembers: readonly string[];
   readonly releaseBranch: string;
-  readonly workflowCacheIgnorePaths: readonly string[];
   private readonly rootInstallOnly: boolean;
 
   constructor(options: DBXToolsJavaScriptProjectOptions = {}) {
@@ -646,8 +633,6 @@ export class DBXToolsNodeProject
     // into `package.json` (`workspaces`/`catalog`) for bun to read. The
     // `pnpm-workspace.yaml` is still emitted for the Databricks Apps pnpm install.
     const pnpmWorkspace = new PnpmWorkspaceState(options);
-    const outdir = configuredOutdir(options);
-    initializingWorkflowCachePaths.set(outdir, options.workflowCacheIgnorePaths ?? []);
     super({
       ...defaultProjectOptions(options),
       pnpmOptions: {
@@ -666,8 +651,6 @@ export class DBXToolsNodeProject
     this.scope = scope;
     this.extraWorkspaceMembers = options.extraWorkspaceMembers ?? [];
     this.releaseBranch = options.defaultReleaseBranch ?? "main";
-    this.workflowCacheIgnorePaths = options.workflowCacheIgnorePaths ?? [];
-    initializingWorkflowCachePaths.delete(outdir);
     this.rootInstallOnly = options.rootInstallOnly !== false;
     this.dbxToolsConfig = new DBXToolsConfig(this, options);
     initProject(this, options);
@@ -676,28 +659,10 @@ export class DBXToolsNodeProject
   public override renderWorkflowSetup(options?: javascript.RenderWorkflowSetupOptions): JobStep[] {
     const steps = super.renderWorkflowSetup(options);
     if (this.parent) return steps;
-    return steps.flatMap((step) => {
-      if (step.uses?.startsWith("oven-sh/setup-bun@")) {
-        return [
-          ...bunCacheRestoreSteps(this, {
-            ignorePaths:
-              this.workflowCacheIgnorePaths ??
-              initializingWorkflowCachePaths.get(resolve(this.outdir)) ??
-              [],
-          }),
-        ];
-      }
-      if (step.run?.startsWith("bun install")) {
-        return [
-          step,
-          bunCacheSaveStep({
-            condition:
-              "github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository",
-          }),
-        ];
-      }
-      return [step];
-    }) as JobStep[];
+    return [
+      bunSetupStep() as JobStep,
+      ...steps.filter((step) => !step.uses?.startsWith("oven-sh/setup-bun@")),
+    ];
   }
 
   public override preSynthesize(): void {
@@ -752,7 +717,6 @@ export class DBXToolsTypeScriptProject
   rootTsconfig?: DBXToolsRootTsconfig;
   readonly extraWorkspaceMembers: readonly string[];
   readonly releaseBranch: string;
-  readonly workflowCacheIgnorePaths: readonly string[];
   private readonly rootInstallOnly: boolean;
 
   constructor(options: DBXToolsTypeScriptProjectOptions) {
@@ -793,7 +757,6 @@ export class DBXToolsTypeScriptProject
     this.scope = scope;
     this.extraWorkspaceMembers = options.extraWorkspaceMembers ?? [];
     this.releaseBranch = options.defaultReleaseBranch ?? "main";
-    this.workflowCacheIgnorePaths = options.workflowCacheIgnorePaths ?? [];
     this.rootInstallOnly = options.rootInstallOnly !== false;
     // Pairs with `jsx` in SHARED_COMPILER_OPTIONS: projen's default `include` is
     // `src/**/*.ts` only, which silently omits a `.tsx` file from the program
@@ -1365,6 +1328,7 @@ function initProject(
       docs: options.releaseDocs,
       pythonRoot: options.releasePythonRoot,
       validationTasks: options.releaseValidationTasks,
+      setupSteps: options.releaseSetupSteps,
     });
   }
 }

package/src/project-py.ts

@@ -2,16 +2,15 @@
 import * as projectUtils from "@dbx-tools/core/project-utils";
 import { stringUtils, type OneOrMany } from "@dbx-tools/shared-core";
 import { Component, License, TextFile, type Project, javascript, python } from "projen";
-import { JobPermission } from "projen/lib/github/workflows-model";
-import { BUN_VERSION } from "./bun-workflow.ts";
+import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
 import { DBX_TOOLS_LICENSE, projectRepositoryUrl } from "./project-js.ts";
 import { isDBXToolsJavaScriptProject } from "./project-predicate.ts";
 import type { DBXToolsProject, DBXToolsProjectOptions } from "./project.ts";
 import { PythonNodeBundle, type PythonNodeBindingsOptions } from "./python-node-bundle.ts";
-import { RELEASE_VERSION, releaseSourceSteps } from "./release-context.ts";
 import {
   refreshReleaseDocsDependencies,
   releaseCondition,
+  releaseBuildSteps,
   releaseTagPattern,
   tryReleaseWorkflow,
   uvSetupStep,
@@ -88,6 +87,8 @@ export interface DBXToolsPythonWorkspaceOptions {
   readonly devDependencies?: readonly string[];
   readonly testPaths?: readonly string[];
   readonly lintPaths?: readonly string[];
+  /** Repository-relative paths Ruff must not lint or format. */
+  readonly ruffExcludes?: readonly string[];
   readonly ruffPerFileIgnores?: Readonly<Record<string, readonly string[]>>;
   /** Generated Python implementation files Pyrefly should resolve but not type-check. */
   readonly pyreflyProjectExcludes?: readonly string[];
@@ -348,6 +349,17 @@ export class DBXToolsPythonWorkspace extends Component {
     if (options.indexStrategy) {
       file.addOverride("tool.uv.index-strategy", options.indexStrategy);
     }
+    const ruffExcludes = [
+      ...(options.ruffExcludes ?? []),
+      ...options.packages.flatMap((pkg) =>
+        pythonNodeGeneratedSources(pkg).map(
+          (source) => `${this.repository.root}/${pkg.directory}/${source}`,
+        ),
+      ),
+    ];
+    if (ruffExcludes.length) {
+      file.addOverride("tool.ruff.exclude", [...new Set(ruffExcludes)]);
+    }
     file.addOverride("tool.pyrefly.ignore-errors-in-generated-code", true);
     const projectExcludes = [
       ...(options.pyreflyProjectExcludes ?? []),
@@ -401,16 +413,45 @@ export class DBXToolsPythonWorkspace extends Component {
     if (!workflow) {
       throw new Error("Python release requires the root dbx-tools release mode");
     }
+    const build = workflow.getJob("build-release") as Job | undefined;
+    if (!build) throw new Error("Python release requires the shared release build job");
+    const pythonSteps: JobStep[] = [
+      uvSetupStep(),
+      {
+        name: "Build Python distributions",
+        env: { RELEASE_VERSION: "${{ steps.release.outputs.release_version }}" },
+        run: [
+          'bun node_modules/@dbx-tools/projen/tasks/publish-python.ts "$RELEASE_VERSION"',
+          `--root ${JSON.stringify(this.repository.root)}`,
+          `--package ${allPublications.map((publication) => JSON.stringify(publication.directory)).join(" ")}`,
+          "--output .release/python --package-directories",
+        ].join(" \\\n  "),
+      },
+      ...allPublications.map((publication) => ({
+        name: `Upload ${publication.distribution} distributions`,
+        uses: "actions/upload-artifact@v4",
+        with: {
+          name: `release-python-${publication.directory}`,
+          path: `.release/python/${publication.directory}`,
+          "if-no-files-found": "error",
+        },
+      })),
+    ];
+    workflow.updateJob("build-release", {
+      ...build,
+      steps: [...build.steps, ...releaseBuildSteps("pypi", pythonSteps)],
+    });
     for (const publication of allPublications) {
       const dependencyJobs = (publication.dependencies ?? []).map(
         (dependency) => `publish-pypi-${dependency}`,
       );
       workflow.addJob(`publish-pypi-${publication.directory}`, {
         if: releaseCondition([
-          "needs.verify-context.result == 'success'",
+          "needs.build-release.result == 'success'",
+          "needs.build-release.outputs.pypi == 'true'",
           ...dependencyJobs.map((job) => `needs['${job}'].result == 'success'`),
         ]),
-        needs: ["verify-context", ...dependencyJobs],
+        needs: ["build-release", ...dependencyJobs],
         environment: {
           name: publication.environment,
           url:
@@ -420,20 +461,14 @@ export class DBXToolsPythonWorkspace extends Component {
         runsOn: ["ubuntu-latest"],
         permissions: { idToken: JobPermission.WRITE },
         timeoutMinutes: 10,
-        env: { BUN_VERSION },
         steps: [
-          ...releaseSourceSteps(),
-          ...project.renderWorkflowSetup({ mutable: false }),
-          uvSetupStep(),
           {
-            name: `Build ${publication.distribution} distributions`,
-            env: { RELEASE_VERSION },
-            run: [
-              'bun node_modules/@dbx-tools/projen/tasks/publish-python.ts "$RELEASE_VERSION"',
-              `--root ${JSON.stringify(this.repository.root)}`,
-              `--package ${JSON.stringify(publication.directory)}`,
-              `--output dist/${publication.directory}`,
-            ].join(" \\\n  "),
+            name: `Download ${publication.distribution} distributions`,
+            uses: "actions/download-artifact@v4",
+            with: {
+              name: `release-python-${publication.directory}`,
+              path: `dist/${publication.directory}`,
+            },
           },
           {
             name: `Publish ${publication.distribution} to PyPI`,

package/src/release-context.ts

@@ -1,34 +1,3 @@
 /** Verified release context shared by every job in the unified workflow. */
-import { github } from "projen";
-import type { JobStep } from "projen/lib/github/workflows-model";
-
-export const RELEASE_TAG = "${{ needs.verify-context.outputs.release_tag }}";
-export const RELEASE_SHA = "${{ needs.verify-context.outputs.expected_sha }}";
-export const RELEASE_VERSION = "${{ needs.verify-context.outputs.release_version }}";
-
-/** Check out and verify the immutable commit selected by the release tag. */
-export function releaseSourceSteps(): readonly JobStep[] {
-  return [
-    github.WorkflowSteps.checkout({
-      name: "Checkout release commit",
-      with: {
-        ref: RELEASE_SHA,
-        fetchDepth: 1,
-      },
-    }),
-    {
-      name: "Verify release source",
-      shell: "bash",
-      env: {
-        RELEASE_TAG,
-        EXPECTED_SHA: RELEASE_SHA,
-      },
-      run: [
-        '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}")" = "$EXPECTED_SHA"',
-        'test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"',
-      ].join("\n"),
-    },
-  ];
-}
+/** Version verified by the shared build that produced every publication artifact. */
+export const RELEASE_VERSION = "${{ needs.build-release.outputs.release_version }}";