@dbx-tools/projen 0.9.38 → 0.9.40

package/README.md

@@ -64,6 +64,8 @@ Repository policy stays in the consuming `.projenrc.ts`:
   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
@@ -380,17 +382,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 restores the Bun cache and 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 +432,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 +451,40 @@ 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`
+
+```text
+Usage: release [options]
+
+Prepare an annotated release and select its build and publication steps
+
+Options:
+  --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.40";
 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";
@@ -60,7 +61,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.40",
+    "@dbx-tools/path": "^0.9.40",
+    "@dbx-tools/shared-core": "^0.9.40",
     "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.40",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/project-js.ts

@@ -573,6 +573,8 @@ 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`. */
@@ -1365,6 +1367,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,
@@ -401,16 +400,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 +448,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 }}";

package/src/release-options.ts

@@ -0,0 +1,82 @@
+/**
+ * Per-run release policy shared by the Projen task and tag-triggered workflow.
+ *
+ * This module owns defaults and the annotated-tag contract. Reuse these values
+ * when adding release steps so local flags and CI cannot drift. Registry URLs
+ * and local installation choices never belong in the public tag annotation.
+ *
+ * @module
+ */
+import { json } from "@dbx-tools/shared-core";
+
+/** Publication scopes accepted by the release task; auto preserves normal publication. */
+export const RELEASE_PUBLISH_TARGETS = ["auto", "npm", "pypi", "local", "none"] as const;
+
+/** One publication scope accepted by the release task. */
+export type ReleasePublishTarget = (typeof RELEASE_PUBLISH_TARGETS)[number];
+
+/** Native Projen dependency-install modes available during local release preparation. */
+export const RELEASE_INSTALL_MODES = ["auto", "always", "never"] as const;
+
+/** Local dependency-install behavior; auto retains Projen's normal trigger policy. */
+export type ReleaseInstallMode = (typeof RELEASE_INSTALL_MODES)[number];
+
+/** CI steps selected by an immutable release annotation. */
+export interface ReleaseStepSelection {
+  readonly npm: boolean;
+  readonly pypi: boolean;
+  readonly docs: boolean;
+  readonly validation: boolean;
+}
+
+/** Flags consumed by the shared release-selection policy. */
+export interface ReleaseSelectionOptions {
+  readonly publish?: ReleasePublishTarget;
+  readonly npm?: boolean;
+  readonly pypi?: boolean;
+  readonly docs?: boolean;
+  readonly validation?: boolean;
+}
+
+const ANNOTATION_MARKER = "dbx-tools-release:";
+
+/** Derive public build/publication steps without mutating repository configuration. */
+export function releaseStepSelection(options: ReleaseSelectionOptions = {}): ReleaseStepSelection {
+  const target = options.publish ?? "auto";
+  return {
+    npm: (target === "auto" || target === "npm") && options.npm !== false,
+    pypi: (target === "auto" || target === "pypi") && options.pypi !== false,
+    docs: options.docs ?? (target !== "local" && target !== "none"),
+    validation: options.validation ?? true,
+  };
+}
+
+/** Record non-default CI selections alongside the existing annotated release tag. */
+export function releaseTagAnnotation(tag: string, selection: ReleaseStepSelection): string {
+  if (selection.npm && selection.pypi && selection.docs && selection.validation) return tag;
+  return `${tag}\n\n${ANNOTATION_MARKER} ${JSON.stringify(selection)}`;
+}
+
+/** Read the release selection, rejecting malformed or ambiguous annotated policy. */
+export function parseReleaseTagAnnotation(annotation: string): ReleaseStepSelection {
+  const selections = annotation.split("\n").filter((line) => line.startsWith(ANNOTATION_MARKER));
+  if (selections.length === 0) return releaseStepSelection();
+  if (selections.length !== 1) throw new Error("Release tag contains multiple step selections");
+  const value = json.parseRecord(selections[0]!.slice(ANNOTATION_MARKER.length));
+  if (
+    !value ||
+    Object.keys(value).length !== 4 ||
+    typeof value.npm !== "boolean" ||
+    typeof value.pypi !== "boolean" ||
+    typeof value.docs !== "boolean" ||
+    typeof value.validation !== "boolean"
+  ) {
+    throw new Error("Invalid release tag step selection");
+  }
+  return { npm: value.npm, pypi: value.pypi, docs: value.docs, validation: value.validation };
+}
+
+/** Whether the selected release should inspect and publish configured local registries. */
+export function releasePublishesLocally(target: ReleasePublishTarget = "auto"): boolean {
+  return target === "auto" || target === "local";
+}

package/src/release.ts

@@ -5,7 +5,8 @@ import { GithubWorkflow } from "projen/lib/github";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
 import { BUN_VERSION } from "./bun-workflow.ts";
 import { projectReleaseBranch, taskCommand, type DBXToolsJavaScriptProject } from "./project-js.ts";
-import { RELEASE_VERSION, releaseSourceSteps } from "./release-context.ts";
+import { RELEASE_VERSION } from "./release-context.ts";
+import type { ReleaseStepSelection } from "./release-options.ts";
 
 const NODE_VERSION = "24";
 const NPM_VERSION = "11.4.2";
@@ -17,7 +18,7 @@ const releaseWorkflows = new WeakMap<DBXToolsJavaScriptProject, GithubWorkflow>(
 export interface ReleaseDocsOptions {
   readonly siteUrl: string;
   readonly base?: string;
-  /** Repository-defined setup and generation steps run before saving the Bun cache. */
+  /** Documentation generation steps run in the shared release build after validation. */
   readonly prepareSteps: readonly JobStep[];
   /** Repository-defined documentation build and validation steps. */
   readonly buildSteps: readonly JobStep[];
@@ -37,6 +38,8 @@ export interface DBXToolsReleaseOptions {
   readonly pythonRoot?: string;
   /** Repository task names run after VERSION verification and before publication. */
   readonly validationTasks?: readonly string[];
+  /** Repository prerequisites installed before release validation and artifact builds. */
+  readonly setupSteps?: readonly JobStep[];
 }
 
 /** Locate the unified workflow when release generation is enabled. */
@@ -44,7 +47,7 @@ export function tryReleaseWorkflow(project: DBXToolsJavaScriptProject): GithubWo
   return releaseWorkflows.get(project);
 }
 
-/** Tag pattern created by release jobs and accepted by manual recovery. */
+/** Tag pattern accepted by the unified release workflow. */
 export function releaseTagPattern(project: DBXToolsJavaScriptProject): string {
   const prefix = releaseTagPrefixes.get(project);
   if (!prefix) throw new Error("Release workflow is not configured");
@@ -57,11 +60,25 @@ export function releaseCondition(prerequisites: readonly string[] = []): string
   return `\${{ always() && ${prerequisites.map((condition) => `(${condition})`).join(" && ")} }}`;
 }
 
-/** Native project setup plus npm publication authentication. */
-export function nodeReleaseSetupSteps(project: DBXToolsJavaScriptProject): readonly JobStep[] {
+/** Gate shared-build steps using the same per-run flag, preserving their existing conditions. */
+export function releaseBuildSteps(
+  flag: keyof ReleaseStepSelection,
+  steps: readonly JobStep[],
+): JobStep[] {
+  return steps.map((step) => ({
+    ...step,
+    if: `\${{ success() && steps.release.outputs.${flag} == 'true'${step.if ? ` && (${step.if.replace(/^\s*\$\{\{\s*|\s*\}\}\s*$/g, "")})` : ""} }}`,
+  }));
+}
+
+/** Artifact-only publication runtime and npm authentication; no workspace installation. */
+export function nodeReleaseSetupSteps(): readonly JobStep[] {
   return [
-    ...releaseSourceSteps(),
-    ...project.renderWorkflowSetup({ mutable: false }),
+    {
+      name: "Setup Bun",
+      uses: "oven-sh/setup-bun@v2",
+      with: { "bun-version": BUN_VERSION },
+    },
     {
       name: "Setup Node.js",
       uses: "actions/setup-node@v6",
@@ -88,13 +105,23 @@ export function uvSetupStep(): JobStep {
 }
 
 function refreshDocsRegistryDependencies(workflow: GithubWorkflow): void {
-  const docs = workflow.getJob("build-docs") as Job | undefined;
+  const docs = workflow.getJob("deploy-docs") as Job | undefined;
   if (!docs) return;
   const registryJobs = Object.keys(workflow.jobs).filter(
     (name) => name === "publish-node" || name.startsWith("publish-pypi-"),
   );
   if (registryJobs.length > 0) {
-    workflow.updateJob("build-docs", { ...docs, needs: ["verify-context", ...registryJobs] });
+    workflow.updateJob("deploy-docs", {
+      ...docs,
+      needs: ["build-release", ...registryJobs],
+      if: releaseCondition([
+        "needs['build-release'].result == 'success'",
+        "needs['build-release'].outputs.docs == 'true'",
+        ...registryJobs.map(
+          (name) => `needs['${name}'].result == 'success' || needs['${name}'].result == 'skipped'`,
+        ),
+      ]),
+    });
   }
 }
 
@@ -106,7 +133,7 @@ export function refreshReleaseDocsDependencies(project: DBXToolsJavaScriptProjec
   }
 }
 
-function verifyContextJob(
+function releaseBuildJob(
   project: DBXToolsJavaScriptProject,
   tagPrefix: string,
   releaseBranch: string,
@@ -115,12 +142,21 @@ function verifyContextJob(
   return {
     runsOn: ["ubuntu-latest"],
     permissions: { contents: JobPermission.READ },
-    timeoutMinutes: 30,
-    env: { BUN_VERSION, CI: "true" },
+    timeoutMinutes: 60,
+    env: {
+      BUN_VERSION,
+      CI: "true",
+      ...(options.docs
+        ? { DOCS_SITE_URL: options.docs.siteUrl, DOCS_BASE: options.docs.base ?? "/" }
+        : {}),
+    },
     outputs: {
       release_tag: { stepId: "release", outputName: "release_tag" },
       expected_sha: { stepId: "release", outputName: "expected_sha" },
       release_version: { stepId: "release", outputName: "release_version" },
+      npm: { stepId: "release", outputName: "npm" },
+      pypi: { stepId: "release", outputName: "pypi" },
+      docs: { stepId: "release", outputName: "docs" },
     },
     steps: [
       github.WorkflowSteps.checkout({
@@ -155,28 +191,70 @@ function verifyContextJob(
           echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
           echo "expected_sha=$RELEASE_SHA" >> "$GITHUB_OUTPUT"
           echo "release_version=$RELEASE_VERSION" >> "$GITHUB_OUTPUT"
+          bun node_modules/@dbx-tools/projen/tasks/release-options.ts --tag "$RELEASE_TAG" --output "$GITHUB_OUTPUT"
         `
           // ============================================================================
         ),
       },
-      ...(options.validationTasks ?? []).map((task) => ({
-        name: `Validate ${task}`,
-        run: `bun run ${task}`,
-      })),
+      ...(options.setupSteps ?? []),
+      ...releaseBuildSteps(
+        "validation",
+        (options.validationTasks ?? []).map((task) => ({
+          name: `Validate ${task}`,
+          run: `bun run ${task}`,
+        })),
+      ),
+      ...(options.nodeRelease === false
+        ? []
+        : releaseBuildSteps("npm", [
+            {
+              name: "Build npm archives",
+              env: { RELEASE_VERSION: "${{ steps.release.outputs.release_version }}" },
+              run: [
+                "bun run compile",
+                'bun node_modules/@dbx-tools/projen/tasks/publish.ts "$RELEASE_VERSION" --skip-compile --output .release/npm',
+                "bun build node_modules/@dbx-tools/projen/tasks/publish-npm.ts --target=bun --outfile=.release/npm/publish-npm.mjs",
+              ].join("\n"),
+            },
+            {
+              name: "Upload npm archives",
+              uses: "actions/upload-artifact@v4",
+              with: { name: "release-npm", path: ".release/npm", "if-no-files-found": "error" },
+            },
+          ])),
+      ...(options.docs
+        ? releaseBuildSteps("docs", [
+            ...options.docs.prepareSteps,
+            ...options.docs.buildSteps,
+            {
+              name: "Upload Pages artifact",
+              uses: "actions/upload-pages-artifact@v4",
+              with: { path: options.docs.artifactPath },
+            },
+          ])
+        : []),
     ],
   };
 }
 
-function nodePublishJob(project: DBXToolsJavaScriptProject): Job {
+function nodePublishJob(): Job {
   return {
-    if: releaseCondition(),
-    needs: ["verify-context"],
+    if: releaseCondition([
+      "needs['build-release'].result == 'success'",
+      "needs['build-release'].outputs.npm == 'true'",
+    ]),
+    needs: ["build-release"],
     runsOn: ["ubuntu-latest"],
     permissions: { contents: JobPermission.READ, idToken: JobPermission.WRITE },
     timeoutMinutes: 30,
     env: { BUN_VERSION, CI: "true" },
     steps: [
-      ...nodeReleaseSetupSteps(project),
+      {
+        name: "Download npm archives",
+        uses: "actions/download-artifact@v4",
+        with: { name: "release-npm", path: ".release/npm" },
+      },
+      ...nodeReleaseSetupSteps(),
       {
         name: "Publish npm workspace",
         env: {
@@ -184,47 +262,19 @@ function nodePublishJob(project: DBXToolsJavaScriptProject): Job {
           NODE_AUTH_TOKEN: "${{ secrets.NPM_TOKEN }}",
           NPM_CONFIG_PROVENANCE: "true",
         },
-        run: 'bun node_modules/@dbx-tools/projen/tasks/publish.ts "$RELEASE_VERSION" $DRY_RUN',
+        run: 'bun .release/npm/publish-npm.mjs --directory .release/npm --version "$RELEASE_VERSION"',
       },
     ],
   };
 }
 
-function addDocsJobs(
-  workflow: GithubWorkflow,
-  project: DBXToolsJavaScriptProject,
-  options: ReleaseDocsOptions,
-): void {
-  workflow.addJob("build-docs", {
-    if: releaseCondition(),
-    needs: ["verify-context"],
-    runsOn: ["ubuntu-latest"],
-    permissions: {
-      contents: JobPermission.READ,
-      pages: JobPermission.WRITE,
-      idToken: JobPermission.WRITE,
-    },
-    timeoutMinutes: 30,
-    env: {
-      BUN_VERSION,
-      DOCS_SITE_URL: options.siteUrl,
-      DOCS_BASE: options.base ?? "/",
-    },
-    steps: [
-      ...releaseSourceSteps(),
-      ...project.renderWorkflowSetup({ mutable: false }),
-      ...options.prepareSteps,
-      ...options.buildSteps,
-      {
-        name: "Upload Pages artifact",
-        uses: "actions/upload-pages-artifact@v4",
-        with: { path: options.artifactPath },
-      },
-    ],
-  });
+function addDocsJobs(workflow: GithubWorkflow): void {
   workflow.addJob("deploy-docs", {
-    if: releaseCondition(),
-    needs: ["build-docs"],
+    if: releaseCondition([
+      "needs['build-release'].result == 'success'",
+      "needs['build-release'].outputs.docs == 'true'",
+    ]),
+    needs: ["build-release"],
     environment: {
       name: "github-pages",
       url: "${{ steps.deployment.outputs.page_url }}",
@@ -247,6 +297,11 @@ function addDocsJobs(
 export class DBXToolsRelease extends Component {
   constructor(project: DBXToolsJavaScriptProject, options: DBXToolsReleaseOptions = {}) {
     super(project);
+    project.addGitIgnore(".release/");
+    const installCondition =
+      'node -e "process.exit(process.env.DBX_TOOLS_RELEASE_INSTALL === \'never\' ? 1 : 0)"';
+    project.package.installTask.addCondition(installCondition);
+    project.package.installCiTask.addCondition(installCondition);
     const tagPrefix = options.tagPrefix ?? "v";
     const releaseBranch = projectReleaseBranch(project);
     releaseTagPrefixes.set(project, tagPrefix);
@@ -290,12 +345,12 @@ export class DBXToolsRelease extends Component {
       push: { tags: [`${tagPrefix}*`] },
     });
     workflow.file?.addOverride("permissions.contents", "read");
-    workflow.addJob("verify-context", verifyContextJob(project, tagPrefix, releaseBranch, options));
+    workflow.addJob("build-release", releaseBuildJob(project, tagPrefix, releaseBranch, options));
     if (options.nodeRelease !== false) {
-      workflow.addJob("publish-node", nodePublishJob(project));
+      workflow.addJob("publish-node", nodePublishJob());
     }
     if (options.docs) {
-      addDocsJobs(workflow, project, options.docs);
+      addDocsJobs(workflow);
     }
     refreshReleaseDocsDependencies(project);
   }

package/tasks/lib/publish-python.ts

@@ -94,6 +94,8 @@ export function buildPythonProjects(options: {
   readonly allowEmpty?: boolean;
   readonly output: string;
   readonly packages?: readonly string[];
+  /** Place each package's artifacts in its directory beneath output. */
+  readonly packageDirectories?: boolean;
   readonly root: string;
   readonly version: string;
 }): void {
@@ -136,9 +138,15 @@ export function buildPythonProjects(options: {
           version: options.version,
         }),
       );
-      runTaskCommand(root, "uv", ["build", "--out-dir", output, packageRoot]);
+      const packageOutput = options.packageDirectories ? join(output, project.directory) : output;
+      runTaskCommand(root, "uv", ["build", "--out-dir", packageOutput, packageRoot]);
+      if (pythonDistributionPaths(packageOutput).length === 0) {
+        throw new Error(`No Python distributions found for ${project.name}`);
+      }
     }
-    const distributions = pythonDistributionPaths(output);
+    const distributions = options.packageDirectories
+      ? projects.flatMap((project) => pythonDistributionPaths(join(output, project.directory)))
+      : pythonDistributionPaths(output);
     if (distributions.length === 0) {
       throw new Error(`No Python distributions found in ${output}`);
     }
@@ -157,6 +165,10 @@ export async function main(): Promise<void> {
     .option("--root <path>", "Python workspace package root", "packages/py")
     .option("--package <directory...>", "Build only selected package directories")
     .option("--output <path>", "Build distributions into a directory without publishing")
+    .option(
+      "--package-directories",
+      "Keep each package's distributions in its own output directory",
+    )
     .option("--dry-run", "build and inspect distributions without uploading")
     .action(
       (
@@ -165,6 +177,7 @@ export async function main(): Promise<void> {
           dryRun?: boolean;
           indexUrl?: string;
           package?: string[];
+          packageDirectories?: boolean;
           publishUrl?: string;
           root: string;
           output?: string;
@@ -174,6 +187,7 @@ export async function main(): Promise<void> {
           buildPythonProjects({
             output: options.output,
             packages: options.package,
+            packageDirectories: options.packageDirectories,
             root: options.root,
             version,
           });

package/tasks/lib/release.ts

@@ -2,7 +2,7 @@
 /** Run the configured release transaction. */
 import * as projectUtils from "@dbx-tools/core/project-utils";
 import { log } from "@dbx-tools/shared-core";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { publishLocalRelease } from "./local-publish.ts";
 import { assertReleaseVersion } from "./release-version.ts";
 import {
@@ -11,6 +11,15 @@ import {
   taskCommandSucceeds,
 } from "../../src/_task-command.ts";
 import { readWorkspaceVersion } from "../../src/workspace-version.ts";
+import {
+  RELEASE_INSTALL_MODES,
+  RELEASE_PUBLISH_TARGETS,
+  releasePublishesLocally,
+  releaseStepSelection,
+  releaseTagAnnotation,
+  type ReleaseInstallMode,
+  type ReleaseSelectionOptions,
+} from "../../src/release-options.ts";
 
 const logger = log.logger("projen:release");
 
@@ -87,23 +96,34 @@ function prepareReleaseBranch(options: {
   runTaskCommand(root, "git", ["push", remote, `HEAD:${branch}`]);
 }
 
-export async function runRelease(options: {
-  readonly root: string;
-  readonly branch: string;
-  readonly bump?: boolean;
-  readonly prefix: string;
-  readonly remote: string;
-  readonly localPublish?: boolean;
-  readonly pythonRoot?: string;
-  readonly validationTasks?: readonly string[];
-}): Promise<string> {
+export async function runRelease(
+  options: ReleaseSelectionOptions & {
+    readonly root: string;
+    readonly branch: string;
+    readonly bump?: boolean;
+    readonly prefix: string;
+    readonly remote: string;
+    readonly localPublish?: boolean;
+    readonly localRegistry?: string;
+    readonly localPypi?: string;
+    readonly install?: ReleaseInstallMode;
+    readonly pythonRoot?: string;
+    readonly validationTasks?: readonly string[];
+  },
+): Promise<string> {
   const { branch, prefix, remote, root } = options;
+  const selection = releaseStepSelection(options);
+  const install = options.install ?? "auto";
+
+  if (install === "always") runTaskCommand(root, "bun", ["install", "--frozen-lockfile"]);
 
   prepareReleaseBranch({ branch, remote, root });
 
   runTaskCommand(root, "git", ["fetch", remote, branch, "--tags"]);
   if (options.bump ?? true) {
-    runTaskCommand(root, "bun", ["run", "bump"]);
+    runTaskCommand(root, "bun", ["run", "bump"], {
+      env: { ...process.env, DBX_TOOLS_RELEASE_INSTALL: install === "auto" ? "auto" : "never" },
+    });
   }
 
   const version = readWorkspaceVersion(root);
@@ -115,7 +135,7 @@ export async function runRelease(options: {
   }
 
   runTaskCommand(root, "bun", ["run", "version:check"]);
-  for (const task of options.validationTasks ?? []) {
+  for (const task of selection.validation ? (options.validationTasks ?? []) : []) {
     runTaskCommand(root, "bun", ["run", task]);
   }
   const status = captureTaskCommand(
@@ -145,7 +165,13 @@ export async function runRelease(options: {
     );
   }
 
-  runTaskCommand(root, "git", ["tag", "--annotate", tag, "--message", tag]);
+  runTaskCommand(root, "git", [
+    "tag",
+    "--annotate",
+    tag,
+    "--message",
+    releaseTagAnnotation(tag, selection),
+  ]);
   try {
     runTaskCommand(root, "git", ["push", "--atomic", remote, `HEAD:${branch}`, `refs/tags/${tag}`]);
   } catch (error) {
@@ -157,10 +183,10 @@ export async function runRelease(options: {
   // Restore local deploys: when a non-standard (loopback) npm or uv registry is
   // configured, publish the freshly tagged version to it directly. Detection and
   // publishing are owned by local-publish.ts; this no-ops on standard registries.
-  if (options.localPublish ?? true) {
+  if ((options.localPublish ?? true) && releasePublishesLocally(options.publish)) {
     await publishLocalRelease({
-      localPypi: "auto",
-      localRegistry: "auto",
+      localPypi: options.pypi === false ? "false" : (options.localPypi ?? "auto"),
+      localRegistry: options.npm === false ? "false" : (options.localRegistry ?? "auto"),
       pythonRoot: options.pythonRoot ?? "packages/py",
       root,
       version,
@@ -170,8 +196,11 @@ export async function runRelease(options: {
   return tag;
 }
 
-export async function main(): Promise<void> {
-  await new Command()
+/** Build the release task's native parser without executing git or registry operations. */
+export function createReleaseCommand(): Command {
+  return new Command()
+    .name("release")
+    .description("Prepare an annotated release and select its build and publication steps")
     .option("--root <path>", "repository root")
     .option("--branch <name>", "release branch", "main")
     .option("--prefix <prefix>", "release tag prefix", "v")
@@ -184,18 +213,43 @@ export async function main(): Promise<void> {
       [],
     )
     .option("--no-bump", "use an existing synchronized local version bump")
+    .addOption(
+      new Option("--publish <target>", "publication scope")
+        .choices([...RELEASE_PUBLISH_TARGETS])
+        .default("auto"),
+    )
+    .addOption(
+      new Option("--install <mode>", "local workspace dependency installation")
+        .choices([...RELEASE_INSTALL_MODES])
+        .default("auto"),
+    )
+    .option("--no-npm", "skip npm build and publication, including local npm publication")
+    .option("--no-pypi", "skip Python build and publication, including local Python publication")
+    .option("--docs", "build and deploy docs for a selected scope")
+    .option("--no-docs", "skip documentation build and deployment")
+    .option(
+      "--no-validation",
+      "skip optional release validation tasks; version/source checks remain mandatory",
+    )
     .option("--no-local-publish", "skip publishing to configured local registries")
+    .option("--local-registry <auto|false|url>", "local npm registry selection", "auto")
+    .option("--local-pypi <auto|false|url>", "local devpi registry selection", "auto")
     .action(
-      async (options: {
-        root?: string;
-        branch: string;
-        bump: boolean;
-        prefix: string;
-        remote: string;
-        pythonRoot: string;
-        localPublish: boolean;
-        validate: string[];
-      }) => {
+      async (
+        options: ReleaseSelectionOptions & {
+          root?: string;
+          branch: string;
+          bump: boolean;
+          prefix: string;
+          remote: string;
+          pythonRoot: string;
+          localPublish: boolean;
+          localRegistry: string;
+          localPypi: string;
+          install: ReleaseInstallMode;
+          validate: string[];
+        },
+      ) => {
         await runRelease({
           root: options.root ?? projectUtils.root() ?? process.cwd(),
           branch: options.branch,
@@ -204,9 +258,21 @@ export async function main(): Promise<void> {
           remote: options.remote,
           pythonRoot: options.pythonRoot,
           localPublish: options.localPublish,
+          localRegistry: options.localRegistry,
+          localPypi: options.localPypi,
+          install: options.install,
+          publish: options.publish,
+          npm: options.npm,
+          pypi: options.pypi,
+          docs: options.docs,
+          validation: options.validation,
           validationTasks: options.validate,
         });
       },
-    )
-    .parseAsync();
+    );
+}
+
+/** Execute the native release task parser. */
+export async function main(): Promise<void> {
+  await createReleaseCommand().parseAsync();
 }

package/tasks/release-options.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env -S bun
+/** Export the current annotated release tag's step selection to GitHub Actions. */
+import { appendFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { captureTaskCommand } from "../src/_task-command.ts";
+import { parseReleaseTagAnnotation } from "../src/release-options.ts";
+
+/** Verify and export a tag policy using the shared annotated-tag contract. */
+export function main(args: string[] = process.argv.slice(2)): void {
+  const { values } = parseArgs({
+    args,
+    options: { tag: { type: "string" }, output: { type: "string" } },
+    strict: true,
+  });
+  if (!values.tag || !values.output) throw new Error("--tag and --output are required");
+  const annotation = captureTaskCommand(
+    process.cwd(),
+    "git",
+    ["for-each-ref", "--format=%(contents)", `refs/tags/${values.tag}`],
+    { check: true },
+  );
+  if (!annotation) throw new Error(`Release tag ${values.tag} has no annotation`);
+  const selection = parseReleaseTagAnnotation(annotation);
+  appendFileSync(
+    values.output,
+    Object.entries(selection)
+      .map(([name, enabled]) => `${name}=${enabled}\n`)
+      .join(""),
+  );
+}
+
+if (import.meta.main) main();

package/tasks/release.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env -S bun
 import { main } from "./lib/release.ts";
 
-export { main, runRelease } from "./lib/release.ts";
+export { createReleaseCommand, main, runRelease } from "./lib/release.ts";
 
 if (import.meta.main) await main();