@dbx-tools/projen 0.9.38 → 0.9.43

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",
@@ -75,26 +92,32 @@ export function nodeReleaseSetupSteps(project: DBXToolsJavaScriptProject): reado
   ];
 }
 
-/** 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",
-    },
   };
 }
 
 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 +129,7 @@ export function refreshReleaseDocsDependencies(project: DBXToolsJavaScriptProjec
   }
 }
 
-function verifyContextJob(
+function releaseBuildJob(
   project: DBXToolsJavaScriptProject,
   tagPrefix: string,
   releaseBranch: string,
@@ -115,12 +138,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 +187,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 +258,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 +293,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 +341,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/python-node-bindings.ts

@@ -270,6 +270,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
         };
       });
       build.onResolve({ filter: /.*/ }, ({ path }) => {
+        if (path === "zod") {
+          return {
+            path: resolve(dirname(Bun.resolveSync("zod/package.json", root)), "index.cjs"),
+          };
+        }
         if (overridesByModule.has(path)) {
           return { path, namespace: functionOverrideNamespace };
         }
@@ -586,7 +591,13 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
         }
         const parameterType = withoutUndefined(checker.getTypeAtLocation(parameter));
         const path = `${exported.sourceName}.${parameter.name.text}`;
-        const record = pythonRecordType(checker, parameterType, records, path);
+        const record = pythonRecordType(
+          checker,
+          parameterType,
+          records,
+          path,
+          declaredTypeName(parameter.type),
+        );
         const required = !parameter.questionToken && !parameter.initializer;
         return {
           javascriptName: parameter.name.text,
@@ -606,6 +617,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
         responses,
         protocols,
         `${exported.sourceName}.return`,
+        declaredTypeName(declaration.type),
       );
       typesByFunction.set(`${exported.sourceFile}#${exported.sourceName}`, {
         parameters,
@@ -636,8 +648,10 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     type: ts.Type,
     records: Map<string, PythonRecord>,
     path: string,
+    preferredName?: string,
   ): PythonRecord {
-    const name = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName();
+    const symbolName = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName();
+    const name = symbolName && symbolName !== "__type" ? symbolName : preferredName;
     if (!name || name === "__type") throw new Error(`${path} must reference a named object type`);
     const existing = records.get(name);
     if (existing) return existing;
@@ -665,13 +679,23 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     type: ts.Type,
     records: Map<string, PythonRecord>,
     path: string,
+    preferredName?: string,
   ): PythonRecord | undefined {
     if (!(type.flags & ts.TypeFlags.Object)) return undefined;
     if (checker.isArrayType(type) || type.getCallSignatures().length > 0) return undefined;
     if (checker.getIndexTypeOfType(type, ts.IndexKind.String)) return undefined;
-    const name = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName();
+    const symbolName = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName();
+    const name = symbolName && symbolName !== "__type" ? symbolName : preferredName;
     if (!name || name === "__type") return undefined;
-    return pythonRecord(checker, type, records, path);
+    return pythonRecord(checker, type, records, path, preferredName);
+  }
+
+  function declaredTypeName(node: ts.TypeNode | undefined): string | undefined {
+    if (!node) return undefined;
+    if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+      return node.typeName.text;
+    }
+    return undefined;
   }
 
   function pythonType(
@@ -715,6 +739,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     responses: Map<string, PythonResponse>,
     protocols: Map<string, PythonProtocol>,
     path: string,
+    preferredName?: string,
   ): string {
     if (type.isUnion()) {
       return pythonUnion(
@@ -839,7 +864,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       protocols.set(name, { name, methods: protocolMethods, properties: protocolProperties });
       return name;
     }
-    const name = `${pythonObjectName(type, path, "Result")}Response`;
+    const name = `${preferredName ?? pythonObjectName(type, path, "Result")}Response`;
     if (responses.has(name)) return name;
     responses.set(name, { name, fields: [] });
     const fields = properties.map((property) => {