@dbx-tools/projen 0.6.152 → 0.6.158

package/README.md

@@ -61,38 +61,38 @@ headers.
 import { project, projectPy } from "@dbx-tools/projen";
 
 const root = new project.DBXToolsNodeProject({ name: "my-apps" });
-const repository = {
-  url: "https://github.com/example/my-apps.git",
-  ref: "main",
-  root: "python/packages",
-} as const;
 
 new projectPy.DBXToolsPythonWorkspace(root, {
-  repository,
+  root: "python/packages",
   packages: [
     {
       directory: "core",
-      name: "my-apps-core",
-      module: "my_apps.core",
       description: "Shared Python helpers",
     },
+    {
+      directory: "service",
+      description: "Python service",
+      internalDependencies: ["core"],
+    },
   ],
-  interpreterPath: "${workspaceFolder}/python/.venv/bin/python",
   release: true,
 });
 ```
 
-Use `projectPy.pythonGitDependency(repository, name, directory)` for an internal
-dependency that must also resolve when a package is installed directly through a
-Git `#subdirectory=` URL. `root.vscode` is projen's existing VS Code component;
-dbx-tools reuses it rather than constructing a second `.vscode/settings.json`
-owner.
+Distribution names and modules come from the parent scope plus each package
+directory. The repository comes from the parent project metadata or Git remote.
+`internalDependencies` renders standalone Git `#subdirectory=` requirements
+without repeating repository coordinates. Pass `repository`, `name`, or
+`module` only to override those conventions. `root.vscode` is projen's existing
+VS Code component; dbx-tools reuses it rather than constructing a second
+`.vscode/settings.json` owner.
 
 ## Add A Rust Workspace
 
-`DBXToolsRustWorkspace` discovers every source-bearing folder under
-`packages/rs`, generates its Cargo manifest, and derives the crate name from the
-root scope plus folder name. A crate containing `uniffi::setup_scaffolding!()`
+`DBXToolsRustWorkspace` discovers every source-bearing folder under its
+configurable `root` (default `packages/rs`), generates its Cargo manifest, and
+derives the crate name and repository from the parent project. A crate containing
+`uniffi::setup_scaffolding!()`
 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
@@ -104,26 +104,63 @@ 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.
 
-The workspace also generates a `rust-release` workflow from those discovered
-UniFFI crates. It builds Linux x64/arm64, macOS x64/arm64, and Windows x64.
-Node publishes a small facade plus optional OS/CPU packages, so npm installs
-only the matching native library. Python publishes one platform-tagged wheel
-per target, so pip follows the same thin-install model.
-
-Set the repository variable `LOCAL_REPOSITORIES=true` to enable the generated
-self-hosted mirror job. Configure `LOCAL_NPM_REGISTRY` and
+The workspace also generates a `rust-release` workflow from discovered crates,
+UniFFI bindings, and release-enabled binaries. The root `release-dispatch`
+workflow resolves the annotated release tag and sends the tag plus commit SHA to
+`rust-release` when Rust is present. The Rust workflow runs in the configured release
+branch cache scope, checks out the supplied SHA, fetches the tag, and requires
+both the tag target and `HEAD` to equal that SHA before building. Its matrix has
+one row per target. Each row installs native dependencies and restores
+Cargo/sccache once,
+builds the Rust workspace once, then packages every discovered output from that
+shared build. Bun and the workspace install are present only when a Node binding
+needs TypeScript generation; uv is present only when a Python wheel is needed.
+A binary-only workspace therefore installs neither. `rustVersion` remains the
+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.
+
+The Node generator's Rust CLI can be cached under one target directory keyed by
+its pinned UBRN version, Rust version, runner OS, and runner architecture. Set
+the repository variable `CACHE_UBRN_TARGET=true` to enable that archive while
+comparing its transfer cost with the default sccache-only path. 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
+does no Rust compilation after the main workspace build.
+
+Artifacts identify their crate, target, and type. Download-only publication
+jobs publish native npm platform archives before the facade and publish
+platform-tagged Python wheels without checkout, Bun, or `bun install`.
+Non-private Cargo crates publish from a source-only job with
+`cargo publish --no-verify`; GitHub Release uploads likewise consume prebuilt
+binary artifacts without reinstalling a toolchain.
+
+Set the repository variable `LOCAL_REPOSITORIES=true` to enable generated
+self-hosted publication from the prebuilt artifacts. Configure `LOCAL_NPM_REGISTRY` and
 `LOCAL_PYPI_PUBLISH_URL` with their matching `LOCAL_*` credentials. Set
 `LOCAL_CARGO_REGISTRY` to a named Cargo registry such as a loopback
-[Kellnr](https://kellnr.io/) instance and provide `LOCAL_CARGO_TOKEN`. The runner
-detects its OS, architecture, libc, Rust target, and Python wheel tag and builds
-only that native target. Public Cargo crates also publish directly to crates.io
+[Kellnr](https://kellnr.io/) instance and provide `LOCAL_CARGO_TOKEN`. Public
+Cargo crates also publish directly to crates.io
 with `CARGO_REGISTRY_TOKEN`. Override `releaseTargets` only when a consumer has
 additional native runners; ordinary projects inherit the maintained matrix
-automatically.
-
-Private Python projects are marked with `[tool.dbx-tools] private = true`. They
-are excluded from the uv workspace, documentation, and Python release workflow
-until their native artifact publishing matrix is enabled.
+automatically. `bun run bump` also accepts repeatable `--os` and `--arch`
+selectors; every selected operating system is crossed with every selected
+architecture. Omit both filters to regenerate the complete maintained matrix.
+`DBX_TOOLS_RELEASE_PLATFORMS` can select the generated matrix without repeating
+environment parsing in a consumer.
+
+Private Python binding projects are marked with `[tool.dbx-tools] private =
+true`. They stay out of the standard uv/Python release and docs surfaces;
+`rust-release` publishes their prebuilt native wheels directly.
+After Rust's public artifacts finish, it dispatches the downstream `release`
+event. Python, Node, standalone Node, and docs consume that event independently
+and start together with the same verified tag and SHA. Without Rust,
+`release-dispatch` sends that event immediately. Configure release GitHub
+environments to permit the generated release branch; the trusted-publisher
+instructions list that branch with the workflow and environment identity PyPI
+verifies.
 
 ## Customize Packages With Mixins
 
@@ -139,6 +176,10 @@ projenProject.applyToProjects(project, { tags: "shared" }, (pkg) => {
 project.synth();
 ```
 
+Use `projectJs.addOptionalPeer(pkg, specifier)` for an optional peer that must
+also resolve during local development. It writes the peer metadata and matching
+development dependency without turning the peer into a runtime dependency.
+
 `applyToProjects` AND-s its globs (prefix a glob with `!` to negate) into one
 predicate over the DBXTools child packages, then applies it as a `constructs`
 mixin across the subtree. Filter on the folder (`path`), the tags (`tags`), or
@@ -318,10 +359,12 @@ Use `--local-registry false` or `--local-pypi false` to disable either local
 publish. An explicit `--local-pypi http://localhost:3141/user/index/` overrides
 auto-detection; `--python-root` defaults to `packages/py`.
 
-The pushed `v*` tag is also the public release boundary: it triggers npm
-publishing, stamps and publishes every Python distribution to PyPI, and rebuilds
-and deploys the documentation site. Ordinary pushes to `main` publish none of
-those surfaces.
+The pushed `v*` tag is also the public release boundary. Available workflow
+stages form the generated chain Rust -> Python -> Node -> docs: Rust builds and
+publishes native artifacts and Cargo crates, Python publishes standard
+distributions, Node publishes standard workspace packages, and docs deploys
+after publication. A stage with no corresponding outputs is omitted. Ordinary
+pushes to `main` publish none of those surfaces.
 
 Members intentionally keep only the tasks that something OTHER than a human
 invokes, so there is no second place to run the same thing:

package/index.ts

@@ -22,6 +22,7 @@ export * as projectPy from "./src/project-py.ts";
 export * as projectRs from "./src/project-rs.ts";
 export * as publish from "./src/publish.ts";
 export * as release from "./src/release.ts";
+export * as releaseDispatch from "./src/release-dispatch.ts";
 export * as scaffold from "./src/scaffold.ts";
 export * as tags from "./src/tags.ts";
 export * as tsconfig from "./src/tsconfig.ts";
@@ -50,6 +51,7 @@ export type { CargoDependencyOptions, CargoDependency, RustPackageOptions, DBXTo
 export { COMPILED_DIR, COMPILED_COMPILER_OPTIONS } from "./src/publish.ts";
 export { DBXToolsRelease } from "./src/release.ts";
 export type { StandaloneRelease, DBXToolsReleaseOptions } from "./src/release.ts";
+export { DOWNSTREAM_RELEASE_EVENT, RUST_RELEASE_EVENT, RELEASE_TAG, RELEASE_SHA } from "./src/release-dispatch.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

@@ -26,9 +26,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "0.6.152",
-    "@dbx-tools/path": "0.6.152",
-    "@dbx-tools/shared-core": "0.6.152",
+    "@dbx-tools/core": "0.6.158",
+    "@dbx-tools/path": "0.6.158",
+    "@dbx-tools/shared-core": "0.6.158",
     "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.152",
+  "version": "0.6.158",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/pnpm-workspace.ts

@@ -101,7 +101,10 @@ const DEFAULT_CATALOG: Catalog = {
  * workspace with an "Ignored build scripts" warning on its first install.
  */
 const DEFAULT_ALLOW_BUILDS: AllowBuilds = {
+  "@databricks/appkit": true,
+  "@databricks/appkit-ui": true,
   esbuild: true,
+  protobufjs: true,
   "unrs-resolver": true,
   // The `bun` npm package (a peer of `bun-plugin-tailwind`) ships a `bun.exe`
   // placeholder and downloads the real platform binary in its postinstall. Left
@@ -113,6 +116,10 @@ const DEFAULT_ALLOW_BUILDS: AllowBuilds = {
   "onnxruntime-node": true,
 };
 
+const DEFAULT_OVERRIDES: Readonly<Record<string, string>> = {
+  glob: "^13.0.0",
+};
+
 /**
  * pnpm settings this engine applies to every workspace, beyond members, catalog,
  * and allowances. Each is stated because pnpm's own default is the weaker choice
@@ -173,7 +180,7 @@ export class PnpmWorkspaceState {
     this.allowBuilds = { ...DEFAULT_ALLOW_BUILDS, ...options.allowBuilds };
     // Seeded even when empty so `addOverride` has a reference projen already
     // captured; projen's `omitEmpty` drops the key while it stays empty.
-    this.overrides = { ...options.workspaceYaml?.overrides };
+    this.overrides = { ...DEFAULT_OVERRIDES, ...options.workspaceYaml?.overrides };
     this.options = {
       ...DEFAULT_WORKSPACE_YAML,
       ...options.workspaceYaml,

package/src/project-js.ts

@@ -236,6 +236,46 @@ export function addExports(pkg: javascript.NodeProject, exports: Record<string,
   });
 }
 
+function dependencyName(spec: string): string {
+  if (!spec.startsWith("@")) return spec.split("@", 1)[0]!;
+  const versionSeparator = spec.indexOf("@", spec.indexOf("/") + 1);
+  return versionSeparator < 0 ? spec : spec.slice(0, versionSeparator);
+}
+
+/** Add an optional peer and make it available while developing the package. */
+export function addOptionalPeer(pkg: javascript.NodeProject, spec: string): void {
+  const name = dependencyName(spec);
+  const current = object.isRecord(pkg.package.manifest.peerDependenciesMeta)
+    ? pkg.package.manifest.peerDependenciesMeta
+    : {};
+  pkg.addPeerDeps(spec);
+  pkg.package.addField("peerDependenciesMeta", {
+    ...current,
+    [name]: { optional: true },
+  });
+  pkg.addDevDeps(spec);
+}
+
+/** Resolve repository metadata already configured on a Node project. */
+export function projectRepositoryUrl(project: javascript.NodeProject): string | undefined {
+  const repository = project.package.manifest.repository;
+  const configured =
+    typeof repository === "string"
+      ? repository
+      : object.isRecord(repository)
+        ? (string.trimToNull(repository.url) ?? undefined)
+        : undefined;
+  return configured?.replace(/^git\+/, "").replace(/\.git$/, "");
+}
+
+/** Resolve the branch release workflows use for a generated project. */
+export function projectReleaseBranch(project: javascript.NodeProject): string {
+  return (
+    (project as javascript.NodeProject & { readonly releaseBranch?: string }).releaseBranch ??
+    "main"
+  );
+}
+
 /**
  * MERGE entries onto a package's npm `files` allowlist - the only paths that
  * ship in the published tarball. npm always includes `package.json`, `README`,
@@ -379,6 +419,7 @@ function defaultProjectOptions(
     // provider. See {@link DBXToolsRelease}.
     ...(isRoot ? {} : { npmAccess: javascript.NpmAccess.PUBLIC }),
     buildWorkflow: false,
+    workflowPackageCache: false,
     release: false,
     // The root build validates the whole workspace and must not also pack every
     // member into unused `dist/js` tarballs. Child projects keep projen's package
@@ -518,7 +559,7 @@ export interface DBXToolsJavaScriptProjectOptions
   /** Workflow that must finish successfully before the main Node release runs. */
   readonly releaseUpstreamWorkflow?: string;
   /** Main Node release workflow name. Defaults to `node-release`. */
-  readonly releaseWorkflowName?: string | false;
+  readonly nodeReleaseWorkflowName?: string | false;
   /**
    * Extra workspace member paths (repo-relative, POSIX) to list in the workspace
    * config ALONGSIDE the discovered `packageRoots` members - for a package that
@@ -558,7 +599,8 @@ export class DBXToolsNodeProject
   pnpmWorkspace?: PnpmWorkspaceState;
   rootTsconfig?: DBXToolsRootTsconfig;
   vsCode?: DBXToolsVsCode;
-  private readonly extraWorkspaceMembers: readonly string[];
+  readonly extraWorkspaceMembers: readonly string[];
+  readonly releaseBranch: string;
   private readonly rootInstallOnly: boolean;
 
   constructor(options: DBXToolsJavaScriptProjectOptions = {}) {
@@ -594,6 +636,7 @@ export class DBXToolsNodeProject
     this.package.addField("version", readWorkspaceVersion(this.outdir));
     this.scope = scope;
     this.extraWorkspaceMembers = options.extraWorkspaceMembers ?? [];
+    this.releaseBranch = options.defaultReleaseBranch ?? "main";
     this.rootInstallOnly = options.rootInstallOnly !== false;
     this.dbxToolsConfig = new DBXToolsConfig(this, options);
     initProject(this, options);
@@ -772,13 +815,13 @@ class WorkspaceValidationTasks extends Component {
 }
 
 /**
- * Bound the default validation workflows when a root opts into them.
+ * Apply bounded, read-only, supersedable defaults to validation workflows.
  *
  * Projen otherwise leaves jobs at GitHub's six-hour ceiling. Missing workflows
  * are a no-op, so roots that keep the engine defaults (`github`/build workflow
  * off) do not gain new files.
  */
-class WorkflowTimeouts extends Component {
+class WorkflowDefaults extends Component {
   public override preSynthesize(): void {
     const build = this.project.tryFindObjectFile(".github/workflows/build.yml");
     for (const job of ["build", "self-mutation"]) {
@@ -787,6 +830,14 @@ class WorkflowTimeouts extends Component {
     this.project
       .tryFindObjectFile(".github/workflows/pull-request-lint.yml")
       ?.addOverride("jobs.validate.timeout-minutes", 10);
+    for (const name of ["build", "pull-request-lint"]) {
+      const workflow = this.project.tryFindObjectFile(`.github/workflows/${name}.yml`);
+      workflow?.addOverride("permissions", { contents: "read" });
+      workflow?.addOverride("concurrency", {
+        group: "${{ github.workflow }}-${{ github.ref }}",
+        "cancel-in-progress": true,
+      });
+    }
   }
 }
 
@@ -838,6 +889,10 @@ class PrettierIgnoreGenerated extends Component {
         prettier.addIgnorePattern(`${rel}/${module}`);
       }
     }
+    const extraMembers = (this.project as DBXToolsNodeProject).extraWorkspaceMembers ?? [];
+    for (const member of extraMembers) {
+      prettier.addIgnorePattern(`${member}/index.ts`);
+    }
   }
 }
 
@@ -1020,7 +1075,7 @@ function initProject(
   // always apply; the self-dep is added only when the engine is an installed pkg.
   const selfDep = engineSelfDependency(project);
   if (selfDep) project.addDevDeps(selfDep);
-  project.addDevDeps(...DEV_DEPS_ROOT);
+  project.addDevDeps(...DEV_DEPS_ROOT, "concurrently@catalog:");
   configureRootPackage(project);
   // Root carries the bare `repository` (no `directory`); children add their subpath.
   applyRepository(project, options.repository);
@@ -1057,6 +1112,11 @@ function initProject(
     project.annotateGenerated(`/${root}/**/index.ts`);
     project.annotateGenerated(`/${root}/openapi/**`);
   }
+  const extraWorkspaceMembers =
+    project instanceof DBXToolsNodeProject ? project.extraWorkspaceMembers : [];
+  for (const member of extraWorkspaceMembers) {
+    project.annotateGenerated(`/${member}/index.ts`);
+  }
 
   // ESLint lives ONLY on the root and lints every package. `projectService` resolves
   // each file to its own package tsconfig (so type-aware rules work tree-wide), and
@@ -1177,7 +1237,7 @@ function initProject(
   }
 
   new WorkspaceValidationTasks(project);
-  new WorkflowTimeouts(project);
+  new WorkflowDefaults(project);
   new PrettierIgnoreGenerated(project);
 
   new GeneratedSource(project);
@@ -1188,7 +1248,7 @@ function initProject(
     tagPrefix: options.releaseTagPrefix,
     standaloneReleases: options.standaloneReleases,
     upstreamWorkflow: options.releaseUpstreamWorkflow,
-    workflowName: options.releaseWorkflowName,
+    workflowName: options.nodeReleaseWorkflowName ?? options.releaseWorkflowName,
   });
 }