@dbx-tools/projen 0.6.161 → 0.6.168

package/README.md

@@ -96,10 +96,29 @@ derives the crate name and repository from the parent project. A crate containin
 automatically wires matching private Node and Python binding packages using the
 same capability name. Repository-specific dependencies and features remain
 declarative options in `.projenrc.ts`; generated bindings are built separately
-from projen synthesis.
+from projen synthesis. Target-independent Node binding TypeScript is committed
+and remains generated/read-only, while native libraries stay ignored. Node
+facades compile to `lib/` and publish JavaScript entry points that plain Node
+can load from `node_modules`. The generated barrel exports the binding API from
+the package root. Do not create a `nodeExports` binding subpath or a
+handwritten type facade.
+
+Rust dependencies between binding-enabled workspace crates become Node
+`workspace:*` and Python `internalDependencies` automatically. Python generation
+selects the owning crate and supplies `external_packages` imports. UBRN currently
+emits every linked component; the generation task discards dependency outputs
+and rewrites their imports to the owning package root, including its generated
+`uniffiModule` converter table. It never copies a dependency's records or enums.
+Foreign callback adapters must first be wrapped in an object created by their
+own native library (`createStorageHandle` for auth), because callback registries
+are library-local. Release wheels replace sibling Git requirements with matching
+native-wheel versions, and dependent publishers wait for their dependencies.
+Each crate builds its own `<crate>-uniffi-bindgen` executable so a workspace
+build has no colliding binary outputs. Packaging runs that prebuilt executable.
 
 `sync --watch` runs a focused Rust watcher beside the OpenAPI watcher. Changes
-inside an existing UniFFI crate regenerate only that crate's bindings; adding or
+inside an existing UniFFI crate regenerate that crate and its dependent bindings
+in dependency order; adding or
 removing a crate or `setup_scaffolding!()` marker triggers a full synth. Repos
 without Rust crates start no Rust watcher. When Rust projects are detected,
 Cargo is required and the focused task fails immediately if it is unavailable.
@@ -122,17 +141,28 @@ MSRV recorded in package manifests, while `releaseRustVersion` independently
 defaults release compilation to `stable`. UBRN uses that same release toolchain
 unless `ubrnRustVersion` explicitly selects another one.
 
+Generated build and release workflows share the Bun cache helpers from
+`bun-workflow.ts`. One `BUN_VERSION` value drives setup and cache keys, while a
+generated dependency-only fingerprint keeps release version bumps from
+invalidating Bun's global package cache. `node_modules` remains uncached.
+
 The final host UBRN executable is cached by pinned UBRN version, Rust toolchain,
 runner OS, and runner architecture. A hit skips both the workspace `bun install`
 and the UBRN Cargo build. Release packaging passes the cached executable directly
 to the Node binding generator and keeps the package barrel copied from source,
 so it does not need the installed projen dependency graph. A miss saves the
 validated executable immediately, before workspace build and packaging can fail.
-Cargo registry caches
+Bun runtime setup still runs in the single facade row because the binding
+generator and facade bundle are TypeScript. The bundle points its type surface
+at the committed generated source and needs no standalone TypeScript compiler
+or workspace install on a UBRN cache hit. Non-facade rows skip the complete
+Bun/UBRN path.
+Stable Windows rows verify and use the hosted runner's installed Rust toolchain
+and select `rust-lld` for the workspace build. Cargo registry caches
 and the `SCCACHE_GHA_VERSION` namespace stay stable per target/toolchain across
 version tags. Cache keys, restore results, sccache statistics, and phase timings
 are written to each build log. Python generation executes the already-built
-`target/<triple>/release/uniffi-bindgen` directly. Artifact packaging therefore
+`target/<triple>/release/<crate>-uniffi-bindgen` directly. Artifact packaging therefore
 does no Rust compilation after the main workspace build.
 
 Artifacts identify their crate, target, and type. Download-only publication

package/index.ts

@@ -5,6 +5,7 @@
 export const PACKAGE_IDENTIFIER = "@dbx-tools/projen";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
+export * as bunWorkflow from "./src/bun-workflow.ts";
 export * as clean from "./src/clean.ts";
 export * as codegen from "./src/codegen.ts";
 export * as dbxToolsConfig from "./src/dbx-tools-config.ts";
@@ -31,6 +32,8 @@ export * as vscode from "./src/vscode.ts";
 export * as watch from "./src/watch.ts";
 export * as workspaceVersion from "./src/workspace-version.ts";
 export { BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE, BUN_APP_OVERRIDES, RootBunfigFile, BunfigFile, BunDevServerFile, BunBuildFile } from "./src/bun-app.ts";
+export { BUN_VERSION } from "./src/bun-workflow.ts";
+export type { BunWorkflowCacheOptions } from "./src/bun-workflow.ts";
 export { DBXToolsConfig } from "./src/dbx-tools-config.ts";
 export type { DBXToolsConfigOptions } from "./src/dbx-tools-config.ts";
 export { resolvePkgRoot } from "./src/engine-root.ts";
@@ -55,7 +58,7 @@ export { DOWNSTREAM_RELEASE_EVENT, RUST_RELEASE_EVENT, RELEASE_TAG, RELEASE_SHA
 export { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS } from "./src/tags.ts";
 export type { PackageTag } from "./src/tags.ts";
 export { DBXToolsRootTsconfig } from "./src/tsconfig.ts";
-export { makeDefaultedInterfaceParametersOptional, addExplicitInterfaceReexports } from "./src/uniffi.ts";
+export { makeDefaultedInterfaceParametersOptional, addTypeScriptExtensionsToBindingImports, addExplicitInterfaceReexports } from "./src/uniffi.ts";
 export type { TypeScriptBindingModule } from "./src/uniffi.ts";
 export { DBXToolsVsCode } from "./src/vscode.ts";
 export type { IgnoreGroupOptions } from "./src/watch.ts";

package/package.json

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

package/src/bun-workflow.ts

@@ -0,0 +1,145 @@
+/** Shared Bun setup and package-cache steps for generated workflows. */
+import { TextFile, javascript } from "projen";
+
+export const BUN_VERSION = "1.3.14";
+
+const cacheKeyScript = `#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = process.cwd();
+const ignored = new Set([
+  ".git",
+  ".docs-build",
+  ".venv",
+  ".worktrees",
+  "coverage",
+  "dist",
+  "lib",
+  "node_modules",
+  "target",
+]);
+const manifests = [];
+const walk = (directory) => {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (ignored.has(entry.name)) continue;
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) walk(path);
+    else if (entry.name === "package.json") manifests.push(path);
+  }
+};
+walk(root);
+
+const dependencyFields = [
+  "catalog",
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "overrides",
+  "peerDependencies",
+  "peerDependenciesMeta",
+  "resolutions",
+  "trustedDependencies",
+];
+const canonical = (value) => {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => [key, canonical(child)]),
+  );
+};
+const dependencies = manifests
+  .sort()
+  .map((path) => {
+    const manifest = JSON.parse(readFileSync(path, "utf8"));
+    return [
+      path.slice(root.length + 1),
+      Object.fromEntries(
+        dependencyFields
+          .filter((field) => manifest[field] !== undefined)
+          .map((field) => [field, canonical(manifest[field])]),
+      ),
+    ];
+  });
+process.stdout.write(createHash("sha256").update(JSON.stringify(dependencies)).digest("hex"));
+`;
+
+const configured = new WeakSet<javascript.NodeProject>();
+
+function ensureCacheKeyScript(project: javascript.NodeProject): void {
+  if (configured.has(project)) return;
+  new TextFile(project.root, ".projen/bun-cache-key.mjs", {
+    lines: cacheKeyScript.trimEnd().split("\n"),
+  });
+  configured.add(project);
+}
+
+function stepCondition(condition: string | undefined, cacheMiss = false): string | undefined {
+  const expressions = [
+    condition,
+    ...(cacheMiss ? ["steps.bun_cache.outputs.cache-hit != 'true'"] : []),
+  ].filter(Boolean);
+  return expressions.length ? `\${{ ${expressions.join(" && ")} }}` : undefined;
+}
+
+export interface BunWorkflowCacheOptions {
+  readonly setupCondition?: string;
+  readonly condition?: string;
+}
+
+/** Set up Bun and restore its global package cache. */
+export function bunCacheRestoreSteps(
+  project: javascript.NodeProject,
+  options: BunWorkflowCacheOptions = {},
+): readonly Record<string, unknown>[] {
+  ensureCacheKeyScript(project);
+  const condition = stepCondition(options.condition);
+  const setupCondition = stepCondition(options.setupCondition);
+  return [
+    {
+      name: "Setup Bun",
+      ...(setupCondition ? { if: setupCondition } : {}),
+      uses: "oven-sh/setup-bun@v2",
+      with: { "bun-version": "${{ env.BUN_VERSION }}" },
+    },
+    {
+      name: "Resolve Bun cache",
+      id: "bun_cache_metadata",
+      ...(condition ? { if: condition } : {}),
+      shell: "bash",
+      run: [
+        'echo "path=$(bun pm cache)" >> "$GITHUB_OUTPUT"',
+        'echo "dependency_hash=$(node .projen/bun-cache-key.mjs)" >> "$GITHUB_OUTPUT"',
+      ].join("\n"),
+    },
+    {
+      name: "Restore Bun cache",
+      id: "bun_cache",
+      ...(condition ? { if: condition } : {}),
+      uses: "actions/cache/restore@v5",
+      with: {
+        path: "${{ steps.bun_cache_metadata.outputs.path }}",
+        key: `bun-\${{ runner.os }}-\${{ runner.arch }}-\${{ env.BUN_VERSION }}-\${{ steps.bun_cache_metadata.outputs.dependency_hash }}`,
+        "restore-keys": `bun-\${{ runner.os }}-\${{ runner.arch }}-\${{ env.BUN_VERSION }}-`,
+      },
+    },
+  ];
+}
+
+/** Save Bun's global package cache immediately after installation. */
+export function bunCacheSaveStep(
+  options: BunWorkflowCacheOptions = {},
+): Readonly<Record<string, unknown>> {
+  return {
+    name: "Save Bun cache",
+    if: stepCondition(options.condition, true),
+    uses: "actions/cache/save@v5",
+    with: {
+      path: "${{ steps.bun_cache_metadata.outputs.path }}",
+      key: "${{ steps.bun_cache.outputs.cache-primary-key }}",
+    },
+  };
+}

package/src/project-js.ts

@@ -13,6 +13,7 @@ import { ignore, match } from "@dbx-tools/path";
 import { object, string, type OneOrMany } from "@dbx-tools/shared-core";
 import { type IConstruct } from "constructs";
 import { Component, IgnoreFile, Project, type TaskOptions, javascript, typescript } from "projen";
+import type { JobStep } from "projen/lib/github/workflows-model";
 import { ReleaseTrigger } from "projen/lib/release";
 import { mixin } from "..";
 import { generateBarrels } from "./barrels.ts";
@@ -23,6 +24,7 @@ import {
   BunfigFile,
   RootBunfigFile,
 } from "./bun-app.ts";
+import { BUN_VERSION, bunCacheRestoreSteps, bunCacheSaveStep } from "./bun-workflow.ts";
 import { codegenModulePaths, generateCodegen } from "./codegen.ts";
 import { DBXToolsConfig, type DBXToolsConfigOptions } from "./dbx-tools-config.ts";
 import { resolvePkgRoot } from "./engine-root.ts";
@@ -444,13 +446,13 @@ function defaultProjectOptions(
     devDeps: ["@types/node@^24.6.0"],
     ...(isRoot
       ? {
-          prettier: true,
-          prettierOptions: {
-            settings: PRETTIER_SETTINGS,
-            ignoreFile: true,
-            ignoreFileOptions: { ignorePatterns: [...ignore.ignorePatterns({ test: false })] },
-          },
-        }
+        prettier: true,
+        prettierOptions: {
+          settings: PRETTIER_SETTINGS,
+          ignoreFile: true,
+          ignoreFileOptions: { ignorePatterns: [...ignore.ignorePatterns({ test: false })] },
+        },
+      }
       : {}),
     ...options,
     ...copiedGitIgnoreOptions(options),
@@ -493,24 +495,23 @@ function defaultTypeScriptProjectOptions(
     // ESLint is configured once on the ROOT (see initProject) and lints the whole
     // tree, so packages don't emit their own config. A caller can still override.
     eslint: false,
-    devDeps: [...(base.devDeps ?? []), "typescript@^5.9.3", "@types/bun@^1.3.14"],
+    devDeps: [...(base.devDeps ?? []), "typescript@^5.9.3", `@types/bun@${BUN_VERSION}`],
     ...options,
     ...copiedGitIgnoreOptions(options),
   };
 }
 
-// Pinned to match the subproject defaults so bun resolves a single typescript
-// across the workspace (a bare name -> `*` could pull a second, newer major).
-// `@types/bun` gives the `Bun.*` globals the server/app tags now use.
-const DEV_DEPS_ROOT: string[] = ["typescript@^5.9.3", "@types/bun@^1.3.14"];
+// Pinned to match the subproject defaults so bun resolves one TypeScript and
+// one runtime-compatible set of Bun globals across the workspace.
+const DEV_DEPS_ROOT: string[] = ["typescript@^5.9.3", `@types/bun@${BUN_VERSION}`];
 
 /** Options for {@link DBXToolsNodeProject} (the monorepo root). */
 export interface DBXToolsJavaScriptProjectOptions
   extends
-    CommonProjectOptions,
-    Partial<javascript.NodeProjectOptions>,
-    DBXToolsConfigOptions,
-    DBXToolsPNPMWorkspaceOptions {
+  CommonProjectOptions,
+  Partial<javascript.NodeProjectOptions>,
+  DBXToolsConfigOptions,
+  DBXToolsPNPMWorkspaceOptions {
   /**
    * The npm scope for generated package names (`@<scope>/<seg-...>`). Defaults to
    * the (resolved) project name; a leading `@` is optional.
@@ -591,8 +592,7 @@ export interface DBXToolsTypeScriptProjectOptions
  */
 export class DBXToolsNodeProject
   extends javascript.NodeProject
-  implements DBXToolsJavaScriptProject
-{
+  implements DBXToolsJavaScriptProject {
   readonly language = "javascript" as const;
   readonly scope: string;
   readonly dbxToolsConfig: DBXToolsConfig;
@@ -642,6 +642,24 @@ export class DBXToolsNodeProject
     initProject(this, options);
   }
 
+  public override renderWorkflowSetup(options?: javascript.RenderWorkflowSetupOptions): JobStep[] {
+    const steps = super.renderWorkflowSetup(options);
+    if (this.parent) return steps;
+    return steps.flatMap((step) => {
+      if (step.uses === "oven-sh/setup-bun@v2") return [...bunCacheRestoreSteps(this)];
+      if (step.run === "bun install") {
+        return [
+          step,
+          bunCacheSaveStep({
+            condition:
+              "github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository",
+          }),
+        ];
+      }
+      return [step];
+    }) as JobStep[];
+  }
+
   public override preSynthesize(): void {
     if (this.rootInstallOnly) this.with(ROOT_INSTALL_ONLY_MIXIN);
     super.preSynthesize();
@@ -674,8 +692,8 @@ export const ROOT_INSTALL_ONLY_MIXIN = mixin.create(
       installDependencies(trigger: unknown): void;
       logInstallTrigger(trigger: unknown): void;
     };
-    nodePackage.installDependencies = () => {};
-    nodePackage.logInstallTrigger = () => {};
+    nodePackage.installDependencies = () => { };
+    nodePackage.logInstallTrigger = () => { };
   },
 );
 
@@ -688,8 +706,7 @@ export const ROOT_INSTALL_ONLY_MIXIN = mixin.create(
  */
 export class DBXToolsTypeScriptProject
   extends typescript.TypeScriptProject
-  implements DBXToolsJavaScriptProject
-{
+  implements DBXToolsJavaScriptProject {
   readonly language = "javascript" as const;
   readonly scope: string;
   readonly dbxToolsConfig: DBXToolsConfig;
@@ -1066,6 +1083,7 @@ function initProject(
   // a plain `bun` exec rather than any wrapper: the default task is spawned by
   // nested installs/synths, and a wrapper that exported `npm_config_*` broke them.
   project.defaultTask?.reset("bun .projenrc.ts");
+  project.buildWorkflow?.workflow.file?.addOverride("jobs.build.env.BUN_VERSION", BUN_VERSION);
 
   // Pin bun's hoisted linker workspace-wide (see RootBunfigFile) so a peer dep
   // resolves to one copy and singletons/types stay coherent.

package/src/project-py.ts

@@ -683,7 +683,10 @@ export class DBXToolsPythonWorkspace extends Component {
     const linesBeforeAuthentication = [
       "# PyPI Trusted Publisher Setup Instructions",
       "",
-      "Use a browser to audit and configure the PyPI trusted publishers below.",
+      "Use the system browser to audit and configure the PyPI trusted publishers below.",
+      "Do not use an in-app browser or embedded webview.",
+      "Do not visit GitHub or use the GitHub API or CLI. Every required GitHub owner, repository, workflow, environment, and branch value is provided below and is authoritative.",
+      "Use only PyPI pages for this task.",
       "",
       "## Audit and confirmation",
       "",
@@ -691,7 +694,7 @@ export class DBXToolsPythonWorkspace extends Component {
       "",
       "- Confirm that the active PyPI account can administer the listed projects and pending publishers.",
       "- Start at https://pypi.org/manage/projects/ and determine which listed projects exist.",
-      "- Inspect every existing GitHub publisher for each project and compare its owner, repository name, workflow name, and environment name with the desired values below.",
+      "- On PyPI, inspect every existing GitHub Actions publisher for each project and compare its owner, repository name, workflow name, and environment name with the desired values below.",
       "- Identify duplicate and mismatched trusted publishers that must be replaced by removing the publisher entry and adding the correct one.",
       "- For projects that do not exist, identify the pending publisher that must be created.",
       "- Report the active account and a proposed reconciliation plan grouped by publishers that will be left unchanged, updated, replaced, created, or removed.",
@@ -700,9 +703,9 @@ export class DBXToolsPythonWorkspace extends Component {
       "",
       "## GitHub environment policy",
       "",
-      `- Configure every environment listed below to permit deployments from the ${releaseBranch} branch.`,
-      "- Branch-scoped release workflows use the environment names below; tag-only deployment policies reject their trusted-publishing jobs.",
-      "- Keep the GitHub environment name synchronized with the PyPI trusted publisher environment.",
+      `- The supplied branch policy value is ${releaseBranch}.`,
+      "- Do not inspect or configure GitHub environments during this task.",
+      "- GitHub environment administration is a separate task; use the supplied values only when comparing PyPI publisher entries.",
       "",
       "## Authentication",
       "",
@@ -714,7 +717,7 @@ export class DBXToolsPythonWorkspace extends Component {
       "",
       "## Efficient browser workflow",
       "",
-      "- Reuse or claim an existing PyPI browser tab when available.",
+      "- Reuse an existing PyPI tab in the system browser when available.",
       "- For an existing project, open its publisher page directly at https://pypi.org/manage/project/<project-name>/settings/publishing/.",
       "- For a project that does not exist, use the pending-publisher page at https://pypi.org/manage/account/publishing/.",
       "- Treat the publisher table shown after submission as authoritative confirmation of success, even if the navigation header unexpectedly appears signed out.",
@@ -769,7 +772,7 @@ export class DBXToolsPythonWorkspace extends Component {
       ],
     });
     project.root.addTask("pypiTrustedPublisherInstructions", {
-      description: "Print browser-agent instructions for PyPI trusted publishers",
+      description: "Print system-browser instructions for PyPI trusted publishers",
       exec: `node ${helper}`,
       receiveArgs: true,
     });