@dbx-tools/projen 0.9.40 → 0.9.46

package/src/project-py.ts

@@ -1,9 +1,9 @@
 /** Reusable uv workspace generation for Python packages hosted in a projen tree. */
 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 { Component, License, TextFile, type Project, github, javascript, python } from "projen";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
-import { DBX_TOOLS_LICENSE, projectRepositoryUrl } from "./project-js.ts";
+import { 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";
@@ -29,17 +29,17 @@ export interface PythonPackageOptions extends DBXToolsProjectOptions {
   readonly directory: string;
   readonly name?: string;
   readonly module?: string;
-  /** Python import root. Defaults to `generated-src` for generated packages, otherwise `src`. */
+  /** Python source root passed to uv_build. Defaults to `src`. */
   readonly moduleRoot?: string;
   readonly description: string;
   readonly dependencies?: readonly string[];
   /** Workspace package directories rendered as standalone Git dependencies. */
   readonly internalDependencies?: readonly string[];
   readonly scripts?: Readonly<Record<string, string>>;
+  /** GitHub environment used to publish this distribution to PyPI. */
+  readonly releaseEnvironment?: string;
   /** One or more build-time Node packages embedded through PythonMonkey. */
   readonly nodeBindings?: OneOrMany<PythonNodeBindingsOptions>;
-  /** Generated source files excluded from strict static analysis. Package-relative. */
-  readonly generatedSources?: readonly string[];
 }
 
 interface ResolvedPythonPackageOptions extends PythonPackageOptions {
@@ -59,8 +59,6 @@ export interface DBXToolsPythonProjectOptions extends DBXToolsProjectOptions {
 
 /** Python release workflow configuration. */
 export interface PythonReleaseOptions {
-  /** GitHub environment by Python distribution name. Defaults to `pypi-<name>`. */
-  readonly environments?: Readonly<Record<string, string>>;
   readonly environmentUrl?: string;
 }
 
@@ -83,13 +81,15 @@ export interface DBXToolsPythonWorkspaceOptions {
   /** uv strategy for repositories that intentionally use multiple trusted indexes. */
   readonly indexStrategy?: "first-index" | "unsafe-first-match" | "unsafe-best-match";
   readonly ruffTarget?: string;
+  /** Python version installed in validation, documentation, and release workflows. */
+  readonly workflowPythonVersion?: string;
   readonly workspaceName?: string;
   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[];
   readonly interpreterPath?: string | false;
   readonly release?: boolean | PythonReleaseOptions;
 }
@@ -100,6 +100,72 @@ const DEFAULT_DEV_DEPENDENCIES = [
   "pyyaml>=6.0,<7",
   "ruff>=0.12,<1",
 ] as const;
+const DEFAULT_RUFF_TARGET = "py310";
+const RELEASE_SETUP_CONDITION =
+  "${{ steps.release.outputs.validation == 'true' || steps.release.outputs.docs == 'true' || steps.release.outputs.pypi == 'true' }}";
+
+/** Convert Ruff's `py311` target spelling to the setup-python `3.11` spelling. */
+function pythonVersionFromRuffTarget(target: string): string {
+  const match = /^py(\d)(\d{1,2})$/.exec(target);
+  if (!match) throw new Error(`Cannot derive a workflow Python version from Ruff target ${target}`);
+  return `${match[1]}.${match[2]}`;
+}
+
+/** Python and uv setup steps, optionally gated by a workflow expression. */
+function pythonSetupSteps(pythonVersion: string, condition?: string): JobStep[] {
+  return [
+    {
+      name: "Setup Python",
+      uses: github.ActionRefs.ACTIONS_SETUP_PYTHON,
+      ...(condition ? { if: condition } : {}),
+      with: { "python-version": pythonVersion },
+    },
+    {
+      ...uvSetupStep(),
+      ...(condition ? { if: condition } : {}),
+    },
+  ];
+}
+
+/** Materialize Projen's lazily rendered native build steps before extending them. */
+function resolvedJobSteps(job: Job): JobStep[] {
+  const steps = (job as unknown as { steps: JobStep[] | (() => JobStep[]) }).steps;
+  return typeof steps === "function" ? steps() : steps;
+}
+
+function missingSetupSteps(job: Job, setupSteps: readonly JobStep[]): JobStep[] {
+  const actionName = (step: JobStep): string | undefined => step.uses?.split("@", 1)[0];
+  const existing = new Set(resolvedJobSteps(job).map(actionName));
+  return setupSteps.filter((step) => !existing.has(actionName(step)));
+}
+
+/**
+ * Ensure Python and uv are available before validation, docs, and packaging.
+ *
+ * The Python workspace owns these prerequisites. Existing action steps are
+ * reused so repository-specific setup can override a version without causing a
+ * duplicate installation.
+ */
+function withPythonBuildSetup(job: Job, pythonVersion: string): Job {
+  const setupSteps = missingSetupSteps(
+    job,
+    pythonSetupSteps(pythonVersion, RELEASE_SETUP_CONDITION),
+  );
+  if (setupSteps.length === 0) return job;
+  const steps = resolvedJobSteps(job);
+  const verificationIndex = steps.findIndex((step) => step.name === "Verify release context");
+  const validationIndex = steps.findIndex((step) => step.name?.startsWith("Validate "));
+  const insertionIndex =
+    verificationIndex >= 0
+      ? verificationIndex + 1
+      : validationIndex < 0
+        ? steps.length
+        : validationIndex;
+  return {
+    ...job,
+    steps: [...steps.slice(0, insertionIndex), ...setupSteps, ...steps.slice(insertionIndex)],
+  };
+}
 
 /** Repository-relative path for a Python package directory. */
 export function pythonPackagePath(repository: PythonRepositoryOptions, directory: string): string {
@@ -129,7 +195,7 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
       authorEmail: "",
       version: options.version,
       description: pkg.description,
-      license: DBX_TOOLS_LICENSE,
+      license: LICENSE,
       github: false,
       sample: false,
       pytest: false,
@@ -169,7 +235,7 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
         },
       },
     });
-    new License(this, { spdx: DBX_TOOLS_LICENSE });
+    new License(this, { spdx: LICENSE });
     this.packageOptions = pkg;
     if (!(this.packagingManager instanceof python.Uv)) {
       throw new Error(`Expected uv packaging for ${pkg.name}`);
@@ -200,12 +266,19 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
 /**
  * Generates a root uv workspace, projen-native Python member projects, Python
  * tasks, editor interpreter selection, and an optional publishing workflow.
+ *
+ * Native `PythonProject` and `PyprojectTomlFile` continue to own each package
+ * and TOML rendering. This component owns only the unsupported remainder:
+ * attaching several uv members to an existing JavaScript root and adding their
+ * dependency-ordered artifacts to the repository's shared tag release.
  */
 export class DBXToolsPythonWorkspace extends Component {
   readonly packages: readonly DBXToolsPythonProject[];
   readonly repository: Required<PythonRepositoryOptions>;
   readonly requiresPython: string;
   readonly version: string;
+  /** Exact Python version used by the shared release build. */
+  readonly workflowPythonVersion: string;
   readonly file: python.PyprojectTomlFile;
 
   constructor(project: javascript.NodeProject, options: DBXToolsPythonWorkspaceOptions) {
@@ -248,6 +321,9 @@ export class DBXToolsPythonWorkspace extends Component {
     }));
     const resolvedOptions = { ...options, packages };
     this.requiresPython = options.requiresPython ?? ">=3.10";
+    this.workflowPythonVersion =
+      options.workflowPythonVersion ??
+      pythonVersionFromRuffTarget(options.ruffTarget ?? DEFAULT_RUFF_TARGET);
     this.version = readWorkspaceVersion(project.outdir);
     this.file = this.emitWorkspace(project, resolvedOptions, scope);
     this.packages = packages.map(
@@ -283,10 +359,11 @@ export class DBXToolsPythonWorkspace extends Component {
       `${this.repository.root}/**/dist/`,
     );
     this.addTasks(project, resolvedOptions);
+    this.addBuildWorkflowSetup(project);
 
     const configuredReleaseOptions = options.release === true ? {} : options.release || {};
     const releaseOptions = { ...configuredReleaseOptions };
-    this.addTrustedPublisherInstructionsTask(project, releaseOptions);
+    this.addTrustedPublisherInstructionsTask(project);
 
     const interpreterPath = options.interpreterPath ?? "${workspaceFolder}/.venv/bin/python";
     if (interpreterPath !== false) {
@@ -336,7 +413,7 @@ export class DBXToolsPythonWorkspace extends Component {
           },
         },
         ruff: {
-          "target-version": options.ruffTarget ?? "py310",
+          "target-version": options.ruffTarget ?? DEFAULT_RUFF_TARGET,
           "line-length": 100,
           lint: {
             "per-file-ignores": perFileIgnores,
@@ -347,17 +424,16 @@ export class DBXToolsPythonWorkspace extends Component {
     if (options.indexStrategy) {
       file.addOverride("tool.uv.index-strategy", options.indexStrategy);
     }
-    file.addOverride("tool.pyrefly.ignore-errors-in-generated-code", true);
-    const projectExcludes = [
-      ...(options.pyreflyProjectExcludes ?? []),
+    const ruffExcludes = [
+      ...(options.ruffExcludes ?? []),
       ...options.packages.flatMap((pkg) =>
-        [...(pkg.generatedSources ?? []), ...pythonNodeGeneratedSources(pkg)].map(
+        pythonNodeGeneratedSources(pkg).map(
           (source) => `${this.repository.root}/${pkg.directory}/${source}`,
         ),
       ),
     ];
-    if (projectExcludes.length) {
-      file.addOverride("tool.pyrefly.project-excludes", [...new Set(projectExcludes)]);
+    if (ruffExcludes.length) {
+      file.addOverride("tool.ruff.exclude", [...new Set(ruffExcludes)]);
     }
     file.addOverride(
       "tool.uv.sources",
@@ -377,10 +453,11 @@ export class DBXToolsPythonWorkspace extends Component {
       exec: "uv run pytest",
       description: "Run Python workspace tests",
     });
-    project.addTask("py:lint", {
+    const lint = project.addTask("py:lint", {
       exec: `uv run ruff check ${lintPaths.join(" ")}`,
       description: "Lint Python workspace packages",
     });
+    lint.exec(`uv run ruff format --check ${lintPaths.join(" ")}`);
     project.addTask("py:format", {
       exec: `uv run ruff format ${lintPaths.join(" ")}`,
       description: "Format Python workspace packages",
@@ -391,19 +468,37 @@ export class DBXToolsPythonWorkspace extends Component {
     });
   }
 
+  /** Add Python prerequisites to Projen's native build workflow when enabled. */
+  private addBuildWorkflowSetup(project: javascript.NodeProject): void {
+    const workflow = project.buildWorkflow?.workflow;
+    const jobId = project.buildWorkflowJobId;
+    if (!workflow || !jobId) return;
+    const job = workflow.getJob(jobId) as Job | undefined;
+    if (!job) return;
+    const setupSteps = missingSetupSteps(job, pythonSetupSteps(this.workflowPythonVersion));
+    if (setupSteps.length === 0) return;
+    const steps = resolvedJobSteps(job);
+    const buildIndex = steps.findIndex((step) => step.name === "build");
+    const insertionIndex = buildIndex < 0 ? steps.length : buildIndex;
+    workflow.updateJob(jobId, {
+      ...job,
+      steps: [...steps.slice(0, insertionIndex), ...setupSteps, ...steps.slice(insertionIndex)],
+    });
+  }
+
   private addReleaseWorkflow(project: javascript.NodeProject, options: PythonReleaseOptions): void {
     if (!project.github || !isDBXToolsJavaScriptProject()(project)) return;
-    const publications = this.publications(options);
+    const publications = this.publications();
     const allPublications = publications;
     if (allPublications.length === 0) return;
     const workflow = tryReleaseWorkflow(project);
     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 configuredBuild = workflow.getJob("build-release") as Job | undefined;
+    if (!configuredBuild) throw new Error("Python release requires the shared release build job");
+    const build = withPythonBuildSetup(configuredBuild, this.workflowPythonVersion);
     const pythonSteps: JobStep[] = [
-      uvSetupStep(),
       {
         name: "Build Python distributions",
         env: { RELEASE_VERSION: "${{ steps.release.outputs.release_version }}" },
@@ -416,7 +511,7 @@ export class DBXToolsPythonWorkspace extends Component {
       },
       ...allPublications.map((publication) => ({
         name: `Upload ${publication.distribution} distributions`,
-        uses: "actions/upload-artifact@v4",
+        uses: github.ActionRefs.ACTIONS_UPLOAD_ARTIFACT,
         with: {
           name: `release-python-${publication.directory}`,
           path: `.release/python/${publication.directory}`,
@@ -451,7 +546,7 @@ export class DBXToolsPythonWorkspace extends Component {
         steps: [
           {
             name: `Download ${publication.distribution} distributions`,
-            uses: "actions/download-artifact@v4",
+            uses: github.ActionRefs.ACTIONS_DOWNLOAD_ARTIFACT,
             with: {
               name: `release-python-${publication.directory}`,
               path: `dist/${publication.directory}`,
@@ -462,7 +557,6 @@ export class DBXToolsPythonWorkspace extends Component {
             uses: "pypa/gh-action-pypi-publish@release/v1",
             with: {
               "packages-dir": `dist/${publication.directory}`,
-              "skip-existing": true,
             },
           },
         ],
@@ -471,22 +565,18 @@ export class DBXToolsPythonWorkspace extends Component {
     refreshReleaseDocsDependencies(project);
   }
 
-  private publications(options: PythonReleaseOptions): readonly PythonPublication[] {
+  private publications(): readonly PythonPublication[] {
     return this.packages.map((pkg) => ({
       directory: pkg.packageOptions.directory,
       distribution: pkg.packageOptions.name,
-      environment:
-        options.environments?.[pkg.packageOptions.name] ?? `pypi-${pkg.packageOptions.name}`,
+      environment: pkg.packageOptions.releaseEnvironment ?? `pypi-${pkg.packageOptions.name}`,
       dependencies: pkg.packageOptions.internalDependencies,
     }));
   }
 
-  private addTrustedPublisherInstructionsTask(
-    project: javascript.NodeProject,
-    options: PythonReleaseOptions,
-  ): void {
+  private addTrustedPublisherInstructionsTask(project: javascript.NodeProject): void {
     const repository = this.githubRepository();
-    const publications = this.publications(options);
+    const publications = this.publications();
     const releaseTag =
       isDBXToolsJavaScriptProject()(project) && tryReleaseWorkflow(project)
         ? releaseTagPattern(project)
@@ -566,7 +656,7 @@ export class DBXToolsPythonWorkspace extends Component {
       lines: stringUtils.dedent(
         // ============================================================================
         /*js*/`
-          #!/usr/bin/env node
+          #!/usr/bin/env bun
           import { parseArgs } from "node:util";
 
           const { values } = parseArgs({
@@ -587,7 +677,7 @@ export class DBXToolsPythonWorkspace extends Component {
     });
     project.root.addTask("pypiTrustedPublisherInstructions", {
       description: "Print system-browser instructions for PyPI trusted publishers",
-      exec: `node ${helper}`,
+      exec: `bun ${helper}`,
       receiveArgs: true,
     });
   }

package/src/publish.ts

@@ -9,11 +9,10 @@
  * (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so a published package whose
  * entry point is `index.ts` is unloadable by anything that is not a bundler.
  *
- * pnpm resolves both at once. It substitutes `publishConfig`'s `main`/`types`/
- * `bin`/`exports` into the manifest at pack time and drops `publishConfig`
- * itself, so the workspace keeps its source entry points while the tarball
- * advertises the compiled ones. Nothing here changes how the repo builds or
- * type-checks; it only changes what `pnpm pack` writes.
+ * `publishConfig` records the compiled `main`/`types`/`bin`/`exports` tree while
+ * the workspace keeps its source entry points. The release packer applies that
+ * record inside each archive because Bun does not perform npm's publishConfig
+ * substitution itself. The checkout remains source-first.
  *
  * Two compiler options make the emitted tree loadable, both native `tsc`:
  *
@@ -56,14 +55,18 @@ export const COMPILED_COMPILER_OPTIONS: javascript.TypeScriptCompilerOptions = {
  * Everything does EXCEPT the `ui` tag, and the exclusion is about consumers
  * rather than convenience. The problem being solved is that Node cannot load raw
  * TypeScript - but a browser package is never loaded by Node. UI packages reach
- * their consumer through Vite, which reads their source happily, and they export
- * `./styles.css` plus raw SVG assets that `tsc` does not copy and could not
- * rewrite. Compiling them would mean a real asset pipeline (Vite library mode)
- * to solve a problem they do not have.
+ * their consumer through a browser bundler, which reads their source, and they
+ * export `./styles.css` plus raw SVG assets that `tsc` does not copy and could
+ * not rewrite. Compiling them would require an asset-aware library pipeline to
+ * solve a problem they do not have.
  */
 export function publishesCompiled(pkg: javascript.NodeProject): boolean {
   if (!(pkg instanceof typescript.TypeScriptProject) || !pkg.parent) return false;
-  return isDBXToolsJavaScriptProject()(pkg) && !pkg.dbxToolsConfig.tags.includes("ui");
+  return (
+    isDBXToolsJavaScriptProject()(pkg) &&
+    pkg.dbxToolsConfig.publishable &&
+    !pkg.dbxToolsConfig.tags.includes("ui")
+  );
 }
 
 /** The `./lib/...` stem of a source path, or `undefined` if it is not TypeScript. */

package/src/python-node-bindings.ts

@@ -8,6 +8,7 @@ import { parse } from "smol-toml";
 import { runTaskCommand } from "./_task-command.ts";
 import { resolveRepoRoot, workspaceDependencyDirectories } from "./packages.ts";
 
+/** Resolved function replacement consumed while generating one PythonMonkey bundle. */
 export interface ResolvedPythonNodeFunctionOverride {
   readonly handlerExport: string;
   readonly handlerFile: string;
@@ -15,6 +16,7 @@ export interface ResolvedPythonNodeFunctionOverride {
   readonly targetModule: string;
 }
 
+/** Fully resolved pyproject binding configuration consumed by the runtime generator. */
 export interface ResolvedPythonNodeBindings {
   readonly bindingDirectory: string;
   readonly bindingName: string;

package/src/python-node-bundle.ts

@@ -1,3 +1,9 @@
+/**
+ * Projen task wiring for pyproject-driven PythonMonkey runtime generation.
+ *
+ * Type extraction and bundle emission remain in the executable generator; this
+ * component owns only typed configuration and generate/check task registration.
+ */
 import { Component, type Project, type Task } from "projen";
 import { taskCommand } from "./project-js.ts";
 

package/src/release-options.ts

@@ -8,6 +8,7 @@
  * @module
  */
 import { json } from "@dbx-tools/shared-core";
+import { z } from "zod";
 
 /** Publication scopes accepted by the release task; auto preserves normal publication. */
 export const RELEASE_PUBLISH_TARGETS = ["auto", "npm", "pypi", "local", "none"] as const;
@@ -22,12 +23,19 @@ export const RELEASE_INSTALL_MODES = ["auto", "always", "never"] as const;
 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;
-}
+export const ReleaseStepSelectionSchema = z
+  .object({
+    npm: z.boolean().describe("Build and publish npm artifacts."),
+    pypi: z.boolean().describe("Build and publish Python artifacts."),
+    docs: z.boolean().describe("Build and deploy documentation."),
+    validation: z.boolean().describe("Run repository validation tasks."),
+  })
+  .strict()
+  .readonly()
+  .describe("Immutable CI steps recorded in an annotated release tag.");
+
+/** CI steps selected by an immutable release annotation. */
+export type ReleaseStepSelection = z.infer<typeof ReleaseStepSelectionSchema>;
 
 /** Flags consumed by the shared release-selection policy. */
 export interface ReleaseSelectionOptions {
@@ -63,17 +71,9 @@ export function parseReleaseTagAnnotation(annotation: string): ReleaseStepSelect
   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 };
+  const parsed = ReleaseStepSelectionSchema.safeParse(value);
+  if (!parsed.success) throw new Error("Invalid release tag step selection");
+  return parsed.data;
 }
 
 /** Whether the selected release should inspect and publish configured local registries. */

package/src/release.ts

@@ -1,4 +1,15 @@
-/** Unified default-branch release workflow generation. */
+/**
+ * Unified annotated-tag release workflow generation.
+ *
+ * Projen's native `Release` owns a different lifecycle: it calculates versions
+ * from commits, generates changelogs and GitHub Releases, and publishes Publib's
+ * ecosystem-specific artifact tree from branch workflows. This repository
+ * instead creates one reviewed `VERSION` commit and annotated `v*` tag locally,
+ * requires that tag to equal `origin/main`, omits GitHub Releases, and builds
+ * npm, Python, and documentation artifacts once before isolated publication
+ * jobs download them. `DBXToolsRelease` therefore remains separate while native
+ * workflow and project primitives own the YAML model and setup steps.
+ */
 import { stringUtils } from "@dbx-tools/shared-core";
 import { Component, github } from "projen";
 import { GithubWorkflow } from "projen/lib/github";
@@ -40,6 +51,8 @@ export interface DBXToolsReleaseOptions {
   readonly validationTasks?: readonly string[];
   /** Repository prerequisites installed before release validation and artifact builds. */
   readonly setupSteps?: readonly JobStep[];
+  /** Repository-specific synthesis commands run before the root Projen synthesis check. */
+  readonly synthesisCommands?: readonly string[];
 }
 
 /** Locate the unified workflow when release generation is enabled. */
@@ -76,12 +89,12 @@ export function nodeReleaseSetupSteps(): readonly JobStep[] {
   return [
     {
       name: "Setup Bun",
-      uses: "oven-sh/setup-bun@v2",
+      uses: github.ActionRefs.OVEN_SH_SETUP_BUN,
       with: { "bun-version": BUN_VERSION },
     },
     {
       name: "Setup Node.js",
-      uses: "actions/setup-node@v6",
+      uses: github.ActionRefs.ACTIONS_SETUP_NODE,
       with: {
         "node-version": NODE_VERSION,
         "registry-url": NPM_REGISTRY_URL,
@@ -92,15 +105,11 @@ export function nodeReleaseSetupSteps(): readonly JobStep[] {
   ];
 }
 
-/** Install uv and restore its download/build cache using Python manifests. */
+/** Install uv for Python release builds. */
 export function uvSetupStep(): JobStep {
   return {
     name: "Setup uv",
     uses: "astral-sh/setup-uv@v7",
-    with: {
-      "enable-cache": true,
-      "cache-dependency-glob": "**/pyproject.toml",
-    },
   };
 }
 
@@ -144,7 +153,6 @@ function releaseBuildJob(
     permissions: { contents: JobPermission.READ },
     timeoutMinutes: 60,
     env: {
-      BUN_VERSION,
       CI: "true",
       ...(options.docs
         ? { DOCS_SITE_URL: options.docs.siteUrl, DOCS_BASE: options.docs.base ?? "/" }
@@ -166,7 +174,7 @@ function releaseBuildJob(
           fetchDepth: 0,
         },
       }),
-      ...project.renderWorkflowSetup({ mutable: false }),
+      ...project.renderWorkflowSetup({ mutable: true }),
       {
         name: "Verify release context",
         id: "release",
@@ -196,6 +204,15 @@ function releaseBuildJob(
           // ============================================================================
         ),
       },
+      {
+        name: "Verify generated sources",
+        run: [
+          ...(options.synthesisCommands ?? []),
+          "bunx projen",
+          "git diff --ignore-space-at-eol --exit-code",
+        ].join("\n"),
+      },
+      { name: "Verify workspace versions", run: "bun run version:check" },
       ...(options.setupSteps ?? []),
       ...releaseBuildSteps(
         "validation",
@@ -218,7 +235,7 @@ function releaseBuildJob(
             },
             {
               name: "Upload npm archives",
-              uses: "actions/upload-artifact@v4",
+              uses: github.ActionRefs.ACTIONS_UPLOAD_ARTIFACT,
               with: { name: "release-npm", path: ".release/npm", "if-no-files-found": "error" },
             },
           ])),
@@ -247,11 +264,11 @@ function nodePublishJob(): Job {
     runsOn: ["ubuntu-latest"],
     permissions: { contents: JobPermission.READ, idToken: JobPermission.WRITE },
     timeoutMinutes: 30,
-    env: { BUN_VERSION, CI: "true" },
+    env: { CI: "true" },
     steps: [
       {
         name: "Download npm archives",
-        uses: "actions/download-artifact@v4",
+        uses: github.ActionRefs.ACTIONS_DOWNLOAD_ARTIFACT,
         with: { name: "release-npm", path: ".release/npm" },
       },
       ...nodeReleaseSetupSteps(),
@@ -299,7 +316,7 @@ export class DBXToolsRelease extends Component {
     super(project);
     project.addGitIgnore(".release/");
     const installCondition =
-      'node -e "process.exit(process.env.DBX_TOOLS_RELEASE_INSTALL === \'never\' ? 1 : 0)"';
+      "bun -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";

package/src/scaffold.ts

@@ -9,11 +9,9 @@ import { repoRoot } from "./packages.ts";
  * Re-run projen synth by executing `.projenrc.ts` with the CURRENT runtime (no
  * projen network re-exec).
  *
- * The TypeScript loader is chosen by which runtime is running: bun executes
- * `.ts` natively, while node needs `--import tsx`. Passing `--import tsx` to bun
- * fails outright (`Cannot find module './cjs/index.cjs'`), which is what broke
- * `sync` once the repo moved onto bun - `process.execPath` is bun here, so the
- * flag was aimed at the one runtime that cannot take it.
+ * dbx-tools tasks are Bun entrypoints, so the current runtime executes the
+ * TypeScript definition directly. A Node fallback would require an additional
+ * loader that no generated task or supported workflow uses.
  *
  * `post: true` runs the full flow - projen's post-synth `bun install` AND the
  * post-synth barrels component - which is what the one-shot `sync` task
@@ -33,6 +31,5 @@ export function runSynth(options: { post?: boolean } = {}): void {
   if (options.post) delete env.PROJEN_DISABLE_POST;
   else env.PROJEN_DISABLE_POST = "true";
   const projenrc = join(repoRoot, ".projenrc.ts");
-  const args = process.versions.bun ? [projenrc] : ["--import", "tsx", projenrc];
-  runTaskCommand(repoRoot, process.execPath, args, { env });
+  runTaskCommand(repoRoot, process.execPath, [projenrc], { env });
 }

package/src/tags.ts

@@ -34,7 +34,7 @@ const NODE_COMPILER_OPTIONS: javascript.TypeScriptCompilerOptions = {
   types: ["node"],
 };
 
-/** The DOM-capable lib list shared by the browser tags (`ui`, `openapi`). */
+/** DOM-capable libraries shared by browser packages. */
 const DOM_LIB = ["ES2022", "DOM", "DOM.Iterable"];
 
 function removeNodeTypes(project: javascript.NodeProject): void {
@@ -144,7 +144,7 @@ export const PACKAGE_TAG_MIXINS = {
     // register and no launcher shim to generate. In a WORKSPACE checkout the
     // manifest still points at the `.ts` entry, which Node type-strips on its own
     // because the package is not under `node_modules`.
-    p.addDeps("commander@catalog:");
+    p.addDeps("commander@catalog:", "zod@catalog:");
     p.addDevDeps("@types/node@catalog:");
     // A CLI compiles code OUTSIDE `src/` - its root `index.ts` barrel and the
     // `bin/` entries - which the src-only tag default doesn't reach.
@@ -163,15 +163,11 @@ export const PACKAGE_TAG_MIXINS = {
     addPackageFiles(p, "bin");
   }),
   server: create(projectPredicate.hasTag("server"), (p) => {
-    // A Node/Express service. tsoa's decorators (@Route/@Get/...) also drive
-    // the `openapi` task (spec + client); experimentalDecorators lets them
-    // type-check. `dev`/`start` run the app's `src/server.ts` with tsx.
-    p.addDeps("express@catalog:", "tsoa@catalog:");
+    // A Node/Express service. `dev` and `start` run `src/server.ts` directly
+    // through Bun, while package compilation remains native TypeScript.
+    p.addDeps("express@catalog:");
     p.addDevDeps("@types/node@catalog:", "@types/express@catalog:");
-    applyCompilerOptions(p, {
-      ...NODE_COMPILER_OPTIONS,
-      experimentalDecorators: true,
-    });
+    applyCompilerOptions(p, NODE_COMPILER_OPTIONS);
     // bun runs the server `.ts` directly (native TS, no tsx). `--watch` restarts
     // on change - the tsx-watch replacement.
     (p.tasks.tryFind("dev") ?? p.addTask("dev")).reset("bun --watch src/server.ts");
@@ -185,12 +181,6 @@ export const PACKAGE_TAG_MIXINS = {
     removeNodeTypes(p);
     applyCompilerOptions(p, AGNOSTIC_COMPILER_OPTIONS);
   }),
-  openapi: create(projectPredicate.hasTag("openapi"), (p) => {
-    removeNodeTypes(p);
-    p.addDeps("openapi-fetch@catalog:");
-    applyCompilerOptions(p, { target: "ES2022", lib: [...DOM_LIB], types: [] });
-    addPackageFiles(p, "openapi.json");
-  }),
 } satisfies Record<string, ConstructsMixin>;
 
 /** A known tag name (a key of {@link PACKAGE_TAG_MIXINS}). */