@dbx-tools/projen 0.9.31 → 0.9.36

package/README.md

@@ -125,63 +125,71 @@ VS Code component; dbx-tools reuses it rather than constructing a second
 
 ### Bundle Node Code For PythonMonkey
 
-Add `nodeBindings` to any `DBXToolsPythonWorkspace` package to generate a
-committed CommonJS runtime and async Python wrappers from a public Node package.
-The configuration is written to `pyproject.toml`, so the generation task also
-works in consuming repositories after `@dbx-tools/projen` is installed.
+Add `nodeBindings` to any `DBXToolsPythonWorkspace` package to generate
+committed CommonJS runtimes and Python wrappers from public Node packages. Pass
+one binding object or an array. Projen writes one
+`[tool.dbx_tools.node_bindings]` table or multiple
+`[[tool.dbx_tools.node_bindings]]` tables accordingly, so generation also works
+in consuming repositories after `@dbx-tools/projen` is installed.
 
 ```ts
 new project.DBXToolsPythonWorkspace(root, {
   root: "packages/py",
   packages: [
     {
-      directory: "auth",
-      description: "Python bindings for example auth",
-      nodeBindings: {
-        package: "@example/auth",
-        layout: "package",
-        private: false,
-        shimRoot: "projen/shims/python-node",
-        functionOverrides: [
-          {
-            module: "@example/core/file-lock",
-            export: "acquireFileLock",
-            handler: "projen/shims/python-node/file-lock.ts",
-          },
-        ],
-      },
+      directory: "postgres",
+      description: "Python bindings for example Postgres helpers",
+      nodeBindings: [
+        {
+          package: "@example/postgres",
+          modules: ["identity", "config"],
+        },
+        {
+          package: "@example/lakebase",
+          modules: ["address"],
+        },
+      ],
     },
   ],
 });
 ```
 
-`layout: "package"` owns the complete Python package under `generated-src`.
-Use the default `layout: "submodule"` to place generated bindings under
-`<module>._generated` beside handwritten source. Generated wrappers convert
-public function names to `snake_case`, await promises, recursively convert plain
-records and arrays, and proxy returned JavaScript class instances with
-`snake_case` async methods.
-
-Set `private: true` to keep every generated symbol out of the generated
-`__init__.py`. The runtime and `node_bindings.py` remain available for a
-handwritten consuming package to import selectively. The default is `false`.
+Bindings always live under
+`<python-module>/_generated/node/`. Each Python package receives one shared
+`_runtime.js`; typed wrappers live under `<node-package>/<module>.py`. This
+preserves Node module singleton identity across all bindings in the Python
+process. The intermediate directories remain implicit namespace packages with
+no generated `__init__.py`. Omit `modules` to discover every exported package
+namespace that contains plain functions, or supply one module string or an array
+explicitly.
+Generated wrappers convert public function names to `snake_case`, preserve
+synchronous functions, await promises, recursively convert plain records and
+arrays, and proxy returned JavaScript class instances with `snake_case` async
+methods.
 
 Every function parameter is resolved through the TypeScript compiler API and
 rendered with its Python-equivalent name and type. Supported record types become
 keyword-only Python dataclasses, nested records become nested dataclasses, and a
 same-named exported companion's `defaults()` method supplies field defaults. A
-trailing optional record can be passed as the dataclass, a dictionary, or direct
-snake-case keyword fields. Generation fails with the property path when a type
-cannot be represented safely in Python.
+record parameter can be passed as the generated dataclass or a dictionary.
+Generation fails with the property path when a type cannot be represented safely
+in Python.
 
 Return types use the same compiler model. Plain records become generated
 `TypedDict` responses, returned clients and class instances become `Protocol`
 types with typed async methods, and primitives, arrays, maps, promises, and
 optional values retain their corresponding Python annotations.
 
-The workspace creates `<name>:python-runtime`,
-`<name>:python-runtime:check`, and, for workspace Node dependencies,
-`<name>:python-runtime:watch`. The root sync watcher includes the watch task.
+The generator resolves portable Node built-ins through standard browser
+polyfills. Python-host-backed adapters for process execution, files, crypto,
+OS values, and process state are included automatically, so packages do not
+configure a shim directory.
+
+The workspace creates `<name>:python-runtime` and
+`<name>:python-runtime:check`. Full synthesis regenerates bindings and removes
+stale `_generated/node` trees by reconciling them with the current
+`pyproject.toml` files, including the resynthesis triggered by a `.projenrc.ts`
+change.
 Built-in shims can make ordinary Node imports work under PythonMonkey.
 `functionOverrides` replaces named exports only in the generated runtime, so the
 Node package does not gain Python callbacks or alternate source files. A
@@ -264,15 +272,14 @@ barrels.generateBarrels();
 
 `generateCodegen()` reads `package.json` `codegen.inputs` and writes generated
 schema modules. They are written read-only, and the root ESLint task runs with
-`--fix` (which fails on a read-only file), so each generated module is added to
+an explicit separate fix task, so each generated module is added to
 `ignorePatterns` at synth - named individually via `codegen.codegenModulePaths()`,
 never as a blanket `<package>/src/**`. A codegen package may hold hand-written
 modules beside its generated ones, and those must stay linted.
 
 `generateBarrels()` writes package-root `index.ts` barrels with module
-namespaces, flat unique type exports, `PACKAGE_IDENTIFIER`, and
-`PACKAGE_VERSION`, returning the number that actually changed. A name two
-modules both declare is ambiguous and stays namespace-only —
+namespaces, flat unique type exports, and `PACKAGE_IDENTIFIER`, returning the
+number that actually changed. A name two modules both declare is ambiguous and stays namespace-only,
 except when one of them is generated: the hand-written module is the curated view
 of the generated shape (`shared-genie`'s `genie-model.ts` extends its own
 codegen'd `dashboards.ts`), so it owns the name and stays hoisted. A barrel whose export surface is unchanged is left untouched,
@@ -325,10 +332,7 @@ tree ROOT only; a member package never gets a nested one.
 import { clean, watch } from "@dbx-tools/projen";
 
 const generated = clean.listGeneratedFiles();
-watch.watchLoop({
-  roots: watch.watchRoots(),
-  onChange: async (files) => console.log(files),
-});
+watch.watchLoop("workspace", watch.watchRoots(), async (files) => refresh(files));
 ```
 
 Use these modules for maintenance tasks that should follow the same generated
@@ -346,7 +350,6 @@ file contract as the CLI.
 - `barrels` / `moduleExports` - public entrypoint generation.
 - `codegen` - `.d.ts` to zod schema generation.
 - `openapi` - tsoa/OpenAPI package generation.
-- `releaseCatalog` - cross-language package ownership and publication order.
 - `bunApp` / `tsconfig` / `vscode` - generated support files/components.
 - `generated` / `clean` / `watch` / `scaffold` - read-only file ownership,
   cleanup, watchers, and synth orchestration.
@@ -366,24 +369,27 @@ packages in up to four `tsc --build` processes and runs custom compile tasks alo
 `test` delegates with `bun run --filter '*'`. Both read the current workspace
 list, so a new package is covered without a re-synth. Work from the root:
 
-| Task                           | What it does                                         |
-| ------------------------------ | ---------------------------------------------------- |
-| `bun run build`                | synth + workspace compile and tests                  |
-| `bun run compile`              | Batched `tsc --build` plus custom member compiles    |
-| `bun run test`                 | `eslint` once, then each member's tests              |
-| `bun run sync`                 | re-synth (`--watch` to keep synthing)                |
-| `bun run barrels`              | regenerate the read-only `index.ts` barrels          |
-| `bun run bump`                 | increment `VERSION` and regenerate version surfaces  |
-| `bun run version:check`        | verify every generated version against `VERSION`     |
-| `bun run release`              | run the configured release transaction                |
-
-Run exactly `bun run release` from a clean `main`. It calls the existing `bump`
-task, commits the generated version changes, pushes `main`, and pushes the
-matching annotated `vX.Y.Z` tag. Pass `--no-bump` only to release an existing
-synchronized local bump. The tag workflow verifies that the tag points at the
-exact `origin/main` commit, publishes npm and PyPI directly from that checkout,
-then builds and deploys documentation. Local npm and Python registry publication
-remains available through the direct local publication tooling.
+| Task                    | What it does                                        |
+| ----------------------- | --------------------------------------------------- |
+| `bun run build`         | synth + workspace compile and tests                 |
+| `bun run compile`       | Batched `tsc --build` plus custom member compiles   |
+| `bun run test`          | `eslint` once, then each member's tests             |
+| `bun run sync`          | re-synth (`--watch` to keep synthing)               |
+| `bun run barrels`       | regenerate the read-only `index.ts` barrels         |
+| `bun run bump`          | increment `VERSION` and regenerate version surfaces |
+| `bun run version:check` | verify every generated version against `VERSION`    |
+| `bun run release`       | run the configured release transaction              |
+
+Run exactly `bun run release` from any branch. Pending changes are committed and
+the current branch is pushed first. A non-`main` branch then fast-forwards
+`main`; the command fails without creating a merge commit if either branch has
+diverged. From `main`, it calls the existing `bump` task, commits the generated
+version changes, pushes `main`, and pushes the matching annotated `vX.Y.Z` tag.
+Pass `--no-bump` only to release an existing synchronized local bump. The tag
+workflow verifies that the tag points at the exact `origin/main` commit,
+publishes npm and PyPI directly from that checkout, then builds and deploys
+documentation. Local npm and Python registry publication remains available
+through the direct local publication tooling.
 
 Members intentionally keep only the tasks that something OTHER than a human
 invokes, so there is no second place to run the same thing:
@@ -412,6 +418,6 @@ from the root instead.
 ## Versioning
 
 `VERSION` is the language-neutral version seam. Real package manifests remain
-Projen-owned and reproduce it exactly across JavaScript and Python packages. Package and
-artifact discovery still supplies publication order and target inventory; it
-does not create independent version ownership.
+Projen-owned and reproduce it exactly across JavaScript and Python packages.
+Release jobs publish the generated workspace inventory in dependency-safe
+workflow order without introducing another version owner.

package/index.ts

@@ -3,7 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/projen";
-export const PACKAGE_VERSION = "0.9.31";
+export const PACKAGE_VERSION = "0.9.36";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -26,7 +26,6 @@ export * as publish from "./src/publish.ts";
 export * as pythonNodeBindings from "./src/python-node-bindings.ts";
 export * as pythonNodeBundle from "./src/python-node-bundle.ts";
 export * as release from "./src/release.ts";
-export * as releaseCatalog from "./src/release-catalog.ts";
 export * as releaseContext from "./src/release-context.ts";
 export * as scaffold from "./src/scaffold.ts";
 export * as tags from "./src/tags.ts";
@@ -50,23 +49,21 @@ export { PnpmWorkspaceState } from "./src/pnpm-workspace.ts";
 export type { Catalog, AllowBuilds, DBXToolsPNPMWorkspaceOptions } from "./src/pnpm-workspace.ts";
 export type { DBXToolsProjectLanguage, DBXToolsProjectOptions, DBXToolsProject, ApplyToProjectsOptions } from "./src/project.ts";
 export { PackageIdentifier, DBX_TOOLS_LICENSE, DBXToolsNodeProject, ROOT_INSTALL_ONLY_MIXIN, DBXToolsTypeScriptProject } from "./src/project-js.ts";
-export type { DBXToolsJavaScriptProject, DBXToolsReleaseMode, PullRequestTitlePolicyOptions, DBXToolsJavaScriptProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project-js.ts";
+export type { DBXToolsJavaScriptProject, DBXToolsReleaseMode, DBXToolsJavaScriptProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project-js.ts";
 export { DBXToolsPythonProject, DBXToolsPythonWorkspace } from "./src/project-py.ts";
-export type { PythonRepositoryOptions, PythonPackageOptions, PythonTrustedPublisherOptions, DBXToolsPythonProjectOptions, PythonReleaseOptions, DBXToolsPythonWorkspaceOptions } from "./src/project-py.ts";
+export type { PythonRepositoryOptions, PythonPackageOptions, DBXToolsPythonProjectOptions, PythonReleaseOptions, DBXToolsPythonWorkspaceOptions } from "./src/project-py.ts";
 export { PROJEN_VERSION } from "./src/projen-version.ts";
 export { COMPILED_DIR, COMPILED_COMPILER_OPTIONS } from "./src/publish.ts";
+export { PYTHON_NODE_SHIM_ROOT } from "./src/python-node-bindings.ts";
 export type { ResolvedPythonNodeFunctionOverride, ResolvedPythonNodeBindings } from "./src/python-node-bindings.ts";
 export { PythonNodeBundle } from "./src/python-node-bundle.ts";
 export type { PythonNodeFunctionOverride, PythonNodeBindingsOptions, PythonNodeBundleOptions } from "./src/python-node-bundle.ts";
 export { DBXToolsRelease } from "./src/release.ts";
-export type { ReleaseStage, ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
-export { DBXToolsReleaseCatalog } from "./src/release-catalog.ts";
-export type { ReleaseProjectLanguage, ReleaseArtifactKind, ReleaseEdgeKind, ReleasePropagation, ReleaseUnitRule, DBXToolsReleaseCatalogOptions, ReleaseDependencyInput, ReleaseProjectRegistration, ExternalReleaseProjectRegistration, ReleaseArtifactRegistration, ReleaseProjectNode, ReleaseArtifact, ReleaseDependencyEdge, ReleaseUnit, ReleaseUnitGraph } from "./src/release-catalog.ts";
+export type { ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
 export { RELEASE_TAG, RELEASE_SHA, RELEASE_VERSION } from "./src/release-context.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";
-export { DBXToolsVsCode } from "./src/vscode.ts";
 export type { IgnoreGroupOptions, WatchLoopOptions } from "./src/watch.ts";
 export type { WorkspaceMutationLockOptions } from "./src/workspace-lock.ts";
 export { VERSION_FILE, DEFAULT_VERSION } from "./src/workspace-version.ts";

package/package.json

@@ -24,28 +24,28 @@
   "devDependencies": {
     "@types/node": "^24.6.0",
     "@types/semver": "^7.7.1",
-    "constructs": "^10.0.0",
     "projen": "0.103.27",
-    "tsoa": "^6.6.0",
-    "typescript": "^5.9.3"
+    "tsoa": "^6.6.0"
   },
   "peerDependencies": {
     "projen": "^0.103.27"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "^0.9.31",
-    "@dbx-tools/path": "^0.9.31",
-    "@dbx-tools/shared-core": "^0.9.31",
+    "@dbx-tools/core": "^0.9.36",
+    "@dbx-tools/path": "^0.9.36",
+    "@dbx-tools/shared-core": "^0.9.36",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
     "is-identifier": "^1",
+    "node-stdlib-browser": "^1.3.1",
     "openapi-typescript": "^7.13.0",
     "oxc-parser": "^0.90.0",
     "semver": "^7.7.3",
     "smol-toml": "1.8.0",
     "ts-to-zod": "^5.1.0",
+    "typescript": "^5.9.3",
     "yaml": "^2.9.0"
   },
   "devEngines": {
@@ -56,11 +56,12 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.31",
+  "version": "0.9.36",
   "types": "index.ts",
   "type": "module",
   "exports": {
     ".": "./index.ts",
+    "./release-packaging": "./tasks/lib/publish-npm.ts",
     "./package.json": "./package.json"
   },
   "files": [

package/src/_task-command.ts

@@ -12,13 +12,6 @@ export interface CaptureTaskCommandOptions extends TaskCommandOptions {
   readonly check?: boolean;
 }
 
-export type ProbeTaskCommandOptions = TaskCommandOptions;
-
-export interface LoggedTaskCommandOptions extends TaskCommandOptions {
-  /** Receive normalized stdout and stderr lines after the command exits. */
-  readonly onLine: (line: string) => void;
-}
-
 function executable(command: string): string {
   return command === "bun" && process.versions.bun ? process.execPath : command;
 }
@@ -76,47 +69,6 @@ export function captureTaskCommand(
   return result.exitCode === 0 ? (result.stdout?.trim() ?? "") : "";
 }
 
-/** Capture trimmed stdout while preserving command failure as `undefined`. */
-export function probeTaskCommand(
-  cwd: string,
-  command: string,
-  args: readonly string[],
-  options: ProbeTaskCommandOptions = {},
-): string | undefined {
-  const result = exec.spawnSync(executable(command), [...args], {
-    cwd,
-    env: options.env,
-    stdout: "capture",
-    stderr: options.stderr ?? "ignore",
-    stdin: "ignore",
-    check: false,
-  });
-  return result.exitCode === 0 ? (result.stdout?.trim() ?? "") : undefined;
-}
-
-/** Run a checked command while routing captured output through one line policy. */
-export function runLoggedTaskCommand(
-  cwd: string,
-  command: string,
-  args: readonly string[],
-  options: LoggedTaskCommandOptions,
-): void {
-  const result = exec.spawnSync(executable(command), [...args], {
-    cwd,
-    env: options.env,
-    stdout: "capture",
-    stderr: "capture",
-    stdin: "ignore",
-    check: false,
-  });
-  for (const line of [...result.stdoutLines, ...result.stderrLines]) {
-    if (line) options.onLine(line);
-  }
-  if (result.exitCode !== 0) {
-    throw new Error(`${command} exited with ${result.exitCode}`);
-  }
-}
-
 /** Whether a quiet, non-interactive command exits successfully. */
 export function taskCommandSucceeds(
   cwd: string,
@@ -135,30 +87,3 @@ export function taskCommandSucceeds(
     }).exitCode === 0
   );
 }
-
-/** Run Git with the shared non-interactive checked command policy. */
-export function runGitTaskCommand(
-  cwd: string,
-  args: readonly string[],
-  options: TaskCommandOptions = {},
-): void {
-  runTaskCommand(cwd, "git", args, options);
-}
-
-/** Capture Git output, returning an empty string for optional offline probes. */
-export function captureGitTaskCommand(
-  cwd: string,
-  args: readonly string[],
-  options: CaptureTaskCommandOptions = {},
-): string {
-  return captureTaskCommand(cwd, "git", args, options);
-}
-
-/** Whether a quiet Git command succeeds. */
-export function gitTaskCommandSucceeds(
-  cwd: string,
-  args: readonly string[],
-  options: Pick<TaskCommandOptions, "env"> = {},
-): boolean {
-  return taskCommandSucceeds(cwd, "git", args, options);
-}

package/src/barrels.ts

@@ -29,10 +29,8 @@
  * `export { ... }`. The module namespaces stay either way, so a namespaced call
  * site keeps working.
  *
- * Every generated barrel also exports `PACKAGE_IDENTIFIER` and
- * `PACKAGE_VERSION` from the package's own `package.json`. Runtime helpers can
- * retain package identity without trying to recover it from an ESM namespace
- * object or loader function.
+ * Every generated barrel also exports `PACKAGE_IDENTIFIER` and `PACKAGE_VERSION`
+ * from the package's own `package.json`.
  *
  * Uniqueness is tallied over types and values TOGETHER: a name carried by two
  * modules is ambiguous whichever kind it is, and hoisting one module's value
@@ -111,10 +109,10 @@ const BARREL_HEADER: HeaderOpts = {
 
 /** Generated package metadata exports, reserved against source-module hoisting. */
 const PACKAGE_IDENTIFIER_EXPORT = "PACKAGE_IDENTIFIER";
-const PACKAGE_VERSION_EXPORT = "PACKAGE_VERSION";
 const PACKAGE_IDENTIFIER_LINE = `export const ${PACKAGE_IDENTIFIER_EXPORT} = "";`;
-const PACKAGE_VERSION_LINE = `export const ${PACKAGE_VERSION_EXPORT} = "";`;
 const PACKAGE_IDENTIFIER_LINE_RE = /^export const PACKAGE_IDENTIFIER = .*;$/m;
+const PACKAGE_VERSION_EXPORT = "PACKAGE_VERSION";
+const PACKAGE_VERSION_LINE = `export const ${PACKAGE_VERSION_EXPORT} = "";`;
 const PACKAGE_VERSION_LINE_RE = /^export const PACKAGE_VERSION = .*;$/m;
 
 /** `config-tools` / `config_tools` -> `configTools`; `local-fs` -> `localFS`. */
@@ -123,7 +121,8 @@ function moduleSegmentToCamel(segment: string): string {
     ...stringUtils.tokenizeWithOptions({ lowerCase: true, capitalize: true }, segment),
   ];
   if (tokens.length === 0) return segment;
-  const [first, ...rest] = tokens;
+  const first = tokens[0]!;
+  const rest = tokens.slice(1);
   // Standalone acronym modules (`fs`, `ai`) stay lowercase so they match
   // Node-style namespaces (`import * as fs`). Trailing / mid acronyms keep
   // their override casing (`localFS`).
@@ -274,7 +273,7 @@ function customExportNames(file: string): Set<string> {
  */
 function mergeCustomExports(content: string, pkgDir: string): string {
   const customPath = join(pkgDir, CUSTOM_EXPORTS_FILE);
-  if (!existsSync(customPath) || isLegacyBindingsExport(customPath)) return content;
+  if (!existsSync(customPath)) return content;
   const overridden = customExportNames(customPath);
   const kept = content.split("\n").filter((line) => {
     const ns = /^export \* as (\w+) from /.exec(line)?.[1];
@@ -283,12 +282,11 @@ function mergeCustomExports(content: string, pkgDir: string): string {
   return `${kept.join("\n").replace(/\n+$/, "")}\nexport * from "./exports.ts";\n`;
 }
 
-function isLegacyBindingsExport(file: string): boolean {
-  return readFileSync(file, "utf8").trim() === 'export * from "./src/bindings.ts";';
-}
-
-/** Read the authoritative npm package name and version emitted by the package project. */
-function packageMetadata(pkgDir: string): { identifier: string; version: string } {
+/** Read the authoritative npm package metadata emitted by the package project. */
+function packageMetadata(pkgDir: string): {
+  identifier: string;
+  version: string;
+} {
   const manifestPath = join(pkgDir, "package.json");
   const manifest = existsSync(manifestPath)
     ? json.parseRecord(readFileSync(manifestPath, "utf8"))
@@ -404,10 +402,7 @@ function generateForPackage(pkgDir: string): number {
   // Hoist package-unique named exports to the top level. Names a hand-authored
   // `exports.ts` declares are suppressed so that file stays authoritative.
   const customPath = join(pkgDir, CUSTOM_EXPORTS_FILE);
-  const suppress =
-    existsSync(customPath) && !isLegacyBindingsExport(customPath)
-      ? customExportNames(customPath)
-      : new Set<string>();
+  const suppress = existsSync(customPath) ? customExportNames(customPath) : new Set<string>();
   suppress.add(PACKAGE_IDENTIFIER_EXPORT);
   suppress.add(PACKAGE_VERSION_EXPORT);
   content = hoistUniqueExports(content, pkgDir, suppress);
@@ -415,11 +410,8 @@ function generateForPackage(pkgDir: string): number {
   content = mergeCustomExports(content, pkgDir);
 
   // Package metadata is blanked for the structural comparison, then restored
-  // from package.json so a version-only change still rewrites the barrel.
-  // If the structural result and package metadata match what's on disk, leave
-  // the file and its read-only bit untouched and report no change (0). This
-  // keeps the watcher quiet on ordinary in-file edits while allowing a version
-  // bump to update PACKAGE_VERSION.
+  // from package.json. If the result matches what's on disk, leave the file and
+  // its read-only bit untouched and report no change.
   content = `${content.replace(/\n+$/, "")}\n`;
   const template = `${header(BARREL_HEADER)}\n${content}`;
   const next = withPackageMetadata(template, pkgDir);

package/src/bun-app.ts

@@ -14,10 +14,9 @@
  *   JS API, NOT the `bun build` CLI, which does not load it), plus Vite-compatible
  *   staging of an optional `public/` directory.
  *
- * Each file supports an unmanaged OVERRIDE beside it (`bunfig.override.toml`,
- * `bun-dev.override.ts`, `bun-build.override.ts`): the dev/build scripts import
- * the override's default export and merge it over the generated options, so a
- * package tweaks its server/bundle WITHOUT editing the projen-owned file.
+ * The dev and build scripts support unmanaged `bun-dev.override.ts` and
+ * `bun-build.override.ts` modules beside them. Each script imports the override's
+ * default export and merges it over the generated options.
  *
  * bun runs these `.ts` files directly. Being package-ROOT files (not under
  * `src/`), they are outside the package's `tsconfig` include, so their `Bun.*`
@@ -30,8 +29,8 @@ import { type Project, TextFile } from "projen";
 export const BUN_DEV_OVERRIDE = "bun-dev.override.ts";
 /** Unmanaged build override module, merged over the generated options if present. */
 export const BUN_BUILD_OVERRIDE = "bun-build.override.ts";
-/** Unmanaged bunfig override (documented; merging TOML is left to the user). */
-export const BUN_APP_OVERRIDES = ["bunfig.override.toml", BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE];
+/** Unmanaged generated-script overrides excluded from formatting and linting. */
+export const BUN_APP_OVERRIDES = [BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE];
 
 /**
  * Root `bunfig.toml`: pin bun's HOISTED linker workspace-wide.

package/src/clean.ts

@@ -5,13 +5,9 @@
  * `@clack/prompts` multiselect picker with all preselected, the TTY guard) lives in
  * `tasks/clean.ts`, which forwards to these functions.
  *
- * "Generated" is detected structurally, not by a hardcoded list: every file this
- * toolchain writes is set READ-ONLY (projen's own config + the generated barrels; see
- * {@link isReadonly}), while every hand-authored source stays writable. So a read-only
- * file under the repo is a clean target - EXCEPT anything inside a dot-prefixed folder
- * (`.projen`, `.vscode`, `.git`, ...) and `.gitignore` itself, which clean always leaves
- * alone (projen re-syncs `.projen`/`.vscode` on the next synth). `node_modules` is
- * enumerated separately (see {@link listNodeModulesDirs}) as whole directories.
+ * Generated files come from Projen's `.projen/files.json` inventories plus the
+ * durable header used by dynamic dbx-tools generators. File mode is edit
+ * protection only and is never treated as ownership evidence.
  *
  * Deleting only generated files is never destructive to the ability to regenerate:
  * `.projenrc.ts` imports the engine by SOURCE path (relative into the repo, e.g.
@@ -21,10 +17,11 @@
  * `bun install` first - the engine's runtime deps live there - so a clean that takes
  * `node_modules` must be followed by reinstall, then re-synth.
  */
-import { existsSync, rmSync, statSync } from "node:fs";
-import { basename, join, relative } from "node:path";
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { find } from "@dbx-tools/path";
-import { isReadonly, makeWritable } from "./generated.ts";
+import { json } from "@dbx-tools/shared-core";
+import { isGenerated, makeWritable } from "./generated.ts";
 import { resolveRepoRoot, toPosix } from "./packages.ts";
 
 /**
@@ -35,16 +32,41 @@ import { resolveRepoRoot, toPosix } from "./packages.ts";
 const CLEAN_SKIP_FILES: ReadonlySet<string> = new Set([".gitignore"]);
 
 /**
- * Every generated (read-only) file in the workspace, as absolute paths sorted by
+ * Every generated file in the workspace, as absolute paths sorted by
  * repo-relative posix path. Skips vendor/build/VCS dirs via node-path's built-in
  * ignores AND every dot-prefixed folder (`.projen`, `.vscode`, `.github`, ...), and
  * {@link CLEAN_SKIP_FILES} entry (`.gitignore`).
  */
+function nativeGeneratedFiles(root: string): string[] {
+  const files = new Set<string>();
+  for (const manifestPath of find.findFiles("**/.projen/files.json", {
+    cwd: root,
+    ignoreOptions: { dot: false },
+  })) {
+    const manifest = json.parseRecord(readFileSync(resolve(root, manifestPath), "utf8"));
+    const projectRoot = dirname(dirname(resolve(root, manifestPath)));
+    const entries = manifest?.files;
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (typeof entry === "string") files.add(resolve(projectRoot, entry));
+    }
+  }
+  return [...files];
+}
+
 export function listGeneratedFiles(root: string = resolveRepoRoot()): string[] {
   const rel = (f: string): string => toPosix(relative(root, f));
-  return [...find.findFiles("**/*", { cwd: root })]
+  const custom = [...find.findFiles("**/*", { cwd: root })]
     .map((f) => join(root, f))
-    .filter(isReadonly)
+    .filter(isGenerated);
+  return [...new Set([...nativeGeneratedFiles(root), ...custom])]
+    .filter(existsSync)
+    .filter(
+      (file) =>
+        !rel(file)
+          .split("/")
+          .some((part) => part.startsWith(".")),
+    )
     .filter((f) => !CLEAN_SKIP_FILES.has(basename(f)))
     .sort((a, b) => rel(a).localeCompare(rel(b)));
 }
@@ -74,15 +96,19 @@ export function listNodeModulesDirs(root: string = resolveRepoRoot()): string[]
  */
 export function removePaths(paths: readonly string[]): number {
   let removed = 0;
+  const failures: unknown[] = [];
   for (const path of paths) {
     try {
       if (!existsSync(path)) continue;
       if (statSync(path).isFile()) makeWritable(path);
       rmSync(path, { recursive: true, force: true });
       removed++;
-    } catch {
-      // Already gone, or racing the watcher - nothing to do.
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") failures.push(error);
     }
   }
+  if (failures.length > 0) {
+    throw new AggregateError(failures, `Could not remove ${failures.length} selected path(s)`);
+  }
   return removed;
 }

package/src/codegen.ts

@@ -49,7 +49,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { log, object } from "@dbx-tools/shared-core";
 import type * as ts from "typescript";
 import { lazyRequire } from "./_lazy-require.ts";
-import { header, isReadonly, makeReadonly, makeWritable } from "./generated.ts";
+import { header, makeReadonly, makeWritable } from "./generated.ts";
 import { readPackageManifest, recordedPackages, resolveRepoRoot } from "./packages.ts";
 
 const logger = log.logger("projen:codegen");
@@ -266,11 +266,10 @@ function inlineInferredTypes(inferredFile: string): string {
     .trim();
 }
 
-/** True if `<srcDir>/<file>` is a codegen-generated module (read-only + our header). */
+/** True if `<srcDir>/<file>` carries the codegen ownership header. */
 function isGeneratedModule(srcDir: string, file: string): boolean {
   if (!file.endsWith(".ts")) return false;
   const path = join(srcDir, file);
-  if (!isReadonly(path)) return false;
   try {
     return readFileSync(path, "utf8").startsWith("// GENERATED by projen synth (codegen:");
   } catch {