@dbx-tools/projen 0.9.51 → 0.9.58

package/README.md

@@ -135,6 +135,13 @@ in consuming repositories after `@dbx-tools/projen` is installed.
 new project.DBXToolsPythonWorkspace(root, {
   root: "packages/py",
   packages: [
+    {
+      directory: "node-runtime",
+      name: "dbx-tools-node-runtime",
+      module: "dbx_tools.node_runtime",
+      description: "Shared PythonMonkey runtime and lazy Node.js bootstrap",
+      nodeRuntime: true,
+    },
     {
       directory: "postgres",
       description: "Python bindings for example Postgres helpers",
@@ -180,18 +187,40 @@ types with typed async methods, and primitives, arrays, maps, promises, and
 optional values retain their corresponding Python annotations.
 
 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`, `<name>:python-runtime:check`,
-and `<name>:python-runtime:watch`. The focused watcher regenerates a Python
-project when its bound Node package, a transitive workspace dependency, its
-binding configuration, a function override, or a shared shim changes.
-`bun run sync --watch` supervises this watcher alongside Projen and barrel
-generation. 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.
+polyfills. Generated bundles proxy Python-host-backed built-ins to
+`dbx-tools-node-runtime`, which owns the process, file, crypto, OS, abort,
+headers, and runtime bootstrap shims. Packages do not configure or copy a shim
+directory, and their generated Python loader imports the shared runtime package.
+
+`nodeRuntime: true` identifies the one workspace package that owns
+`build-runtime.ts`, `shims/`, the generated `runtime.js`, PythonMonkey bootstrap,
+and bundle loading. Its distribution and module must be
+`dbx-tools-node-runtime` and `dbx_tools.node_runtime`. Packages with
+`nodeBindings` automatically depend on that workspace member. When the workspace
+does not publish the runtime itself, they receive the matching external
+`dbx-tools-node-runtime` dependency instead.
+
+The workspace creates one repository-wide binding lifecycle:
+
+- `python-node-bindings` generates every configured bridge.
+- `python-node-bindings:check` verifies generated files and fails on stale
+  `_generated/node` directories.
+- `python-node-bindings:watch` watches all configured bridges and regenerates
+  only Python projects affected by a Node package, transitive workspace
+  dependency, binding manifest, or function override change.
+
+When a runtime owner is configured, the workspace also creates one shared
+runtime lifecycle:
+
+- `python-node-runtime` runs the package-owned `build-runtime.ts`.
+- `python-node-runtime:check` verifies the committed `runtime.js`.
+- `python-node-runtime:watch` watches `build-runtime.ts` and `shims/` and runs
+  the same package-owned builder.
+
+`bun run sync --watch` supervises both generic watchers alongside the existing
+`projenrc` and `barrels` watchers. No per-Python-package watcher tasks are
+created. Full synthesis regenerates every binding and reconciles stale
+`_generated/node` trees with the current `pyproject.toml` files.
 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
@@ -215,7 +244,7 @@ subset of a Git repository instead of exposing a direct URL dependency:
       include: ["driver.py", "operations/**/*.py"],
       exclude: ["**/test_*.py"],
       replace: {
-        "from driver.": "from example.service._generated.sync.upstream_driver.",
+        "DEFAULT_TIMEOUT = 30": "DEFAULT_TIMEOUT = 120",
       },
     },
   ],
@@ -225,8 +254,18 @@ subset of a Git repository instead of exposing a direct URL dependency:
 Each source is written beneath
 `<python-module>/_generated/sync/<name-or-owner-repository-hash>`. The generated
 package task parses pip-style Git sources, filters files with the configured
-globs, verifies every replacement matched, records the options and resolved
-commit in `.sync.json`, and recursively marks the result read-only.
+globs, applies and verifies every literal `replace` patch, records the options
+and resolved commit in `.sync.json`, and recursively marks the result read-only.
+
+Do not hard-code the generated package path in `replace`. `localizeImports`
+(on by default for identifier names) parses each file with the Python AST and
+rewrites absolute imports of synchronized modules, whether upstream imports them
+bare (`from operations.base import X`) or under the subdirectory's dotted path
+(`from src.driver.operations.base import X`). It also rewrites constant
+`__import__` and `importlib.import_module` arguments. Pass a list of upstream
+module names to rewrite only those (each must match), or `false` to keep upstream
+imports. The import prefix comes from the same constants as the output path, so
+renaming the module or generated directory flows through without config edits.
 
 Synchronization uses a check-lock-check sequence and an atomic directory
 replacement. A current pinned commit performs no network request. Branches and
@@ -390,7 +429,8 @@ file contract as the CLI.
 - `engineRoot` - engine package root resolution for bootstrapped repos.
 
 The engine registers its commands as projen tasks on the workspace root, so run
-them with `bun run <task>` - `sync` (add `--watch`), `barrels`, and `clean`.
+them with `bun run <task>` - `sync` (add `--watch`), `barrels`, `clean`, and the
+configured `python-node-bindings:*` and `python-node-runtime:*` lifecycles.
 [`@dbx-tools/cli`](../packages/js/cli/dbx-tools) is only needed to
 bootstrap a folder that has no `.projenrc.ts` or toolchain yet.
 

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.51";
+export const PACKAGE_VERSION = "0.9.58";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -23,7 +23,8 @@ export * as projectPy from "./src/project-py.ts";
 export * as projenVersion from "./src/projen-version.ts";
 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 pythonNodeBindingsComponent from "./src/python-node-bindings-component.ts";
+export * as pythonNodeRuntime from "./src/python-node-runtime.ts";
 export * as release from "./src/release.ts";
 export * as releaseContext from "./src/release-context.ts";
 export * as releaseOptions from "./src/release-options.ts";
@@ -39,6 +40,7 @@ export { BUN_VERSION } from "./src/bun-workflow.ts";
 export { DBXToolsConfigDataSchema, DBXToolsConfig } from "./src/dbx-tools-config.ts";
 export type { DBXToolsConfigOptions, DBXToolsConfigData } from "./src/dbx-tools-config.ts";
 export { resolvePkgRoot } from "./src/engine-root.ts";
+export { PYTHON_GENERATED_PACKAGE, PYTHON_SYNC_PACKAGE } from "./src/generated.ts";
 export type { HeaderOpts } from "./src/generated.ts";
 export type { ConstructsMixin } from "./src/mixin.ts";
 export type { ModuleStatement, ModuleExport, PublicFunctionExport } from "./src/module-exports.ts";
@@ -53,10 +55,11 @@ export { DBXToolsPythonProject, DBXToolsPythonWorkspace } from "./src/project-py
 export type { PythonRepositoryOptions, PythonPackageOptions, PythonSourceSyncOptions, 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 type { ResolvedPythonNodeFunctionOverride, ResolvedPythonNodeBindings, GeneratePythonNodeBindingsOptions } from "./src/python-node-bindings.ts";
+export { PYTHON_NODE_BINDINGS_TASK, PYTHON_NODE_BINDINGS_CHECK_TASK, PYTHON_NODE_BINDINGS_WATCH_TASK, PythonNodeBindings } from "./src/python-node-bindings-component.ts";
+export type { PythonNodeFunctionOverride, PythonNodeBindingsOptions, PythonNodeBindingsComponentOptions } from "./src/python-node-bindings-component.ts";
+export { PYTHON_NODE_RUNTIME_DISTRIBUTION, PYTHON_NODE_RUNTIME_MODULE, PYTHON_NODE_RUNTIME_TASK, PYTHON_NODE_RUNTIME_CHECK_TASK, PYTHON_NODE_RUNTIME_WATCH_TASK, PythonNodeRuntime } from "./src/python-node-runtime.ts";
+export type { PythonNodeRuntimeOptions } from "./src/python-node-runtime.ts";
 export { DBXToolsRelease } from "./src/release.ts";
 export type { ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
 export { RELEASE_VERSION } from "./src/release-context.ts";

package/package.json

@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "^0.9.51",
-    "@dbx-tools/path": "^0.9.51",
-    "@dbx-tools/shared-core": "^0.9.51",
+    "@dbx-tools/core": "^0.9.58",
+    "@dbx-tools/path": "^0.9.58",
+    "@dbx-tools/shared-core": "^0.9.58",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -54,7 +54,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.51",
+  "version": "0.9.58",
   "types": "index.ts",
   "type": "module",
   "exports": {
@@ -65,8 +65,7 @@
   "files": [
     "index.ts",
     "src",
-    "tasks",
-    "shims/python-node"
+    "tasks"
   ],
   "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
 }

package/src/dbx-tools-config.ts

@@ -38,6 +38,11 @@ export const DBXToolsConfigDataSchema = z
       .readonly()
       .optional()
       .describe("Additional paths that trigger watcher resynthesis."),
+    syncWatchTasks: z
+      .array(z.string().min(1))
+      .readonly()
+      .optional()
+      .describe("Projen tasks supervised by `sync --watch`."),
   })
   .strict()
   .readonly()
@@ -58,6 +63,8 @@ export class DBXToolsConfig {
   publishable: boolean;
   /** Additional repository paths that trigger watcher resynthesis. */
   syncResynthPaths?: string[];
+  /** Projen tasks supervised by `sync --watch`. */
+  readonly syncWatchTasks: string[] = [];
 
   constructor(
     readonly project: javascript.NodeProject,
@@ -82,6 +89,7 @@ export class DBXToolsConfig {
       ...(!this.publishable ? { publishable: false } : {}),
       ...(this.packageRoots?.length ? { packageRoots: this.packageRoots } : {}),
       ...(this.syncResynthPaths?.length ? { syncResynthPaths: this.syncResynthPaths } : {}),
+      ...(this.syncWatchTasks.length ? { syncWatchTasks: [...new Set(this.syncWatchTasks)] } : {}),
     });
   }
 }

package/src/generated.ts

@@ -13,6 +13,12 @@ import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 /** First line of every banner {@link header} builds. */
 const MARKER = "// GENERATED by";
 
+/** Python subpackage, under a package's module directory, that holds all toolchain output. */
+export const PYTHON_GENERATED_PACKAGE = "_generated";
+
+/** {@link PYTHON_GENERATED_PACKAGE} child holding upstream sources written by `python-sync`. */
+export const PYTHON_SYNC_PACKAGE = "sync";
+
 const READONLY = 0o444;
 const WRITABLE = 0o644;
 

package/src/packages.ts

@@ -280,6 +280,12 @@ export function syncResynthPaths(projectRoot: string = resolveRepoRoot()): strin
   return Array.isArray(paths) ? stringUtils.parseList(paths.map((p) => String(p))) : [];
 }
 
+/** Projen task names supervised as focused processes by `sync --watch`. */
+export function syncWatchTasks(projectRoot: string = resolveRepoRoot()): string[] {
+  const tasks = readDbxToolsConfig(projectRoot)?.syncWatchTasks;
+  return Array.isArray(tasks) ? stringUtils.parseList(tasks.map((task) => String(task))) : [];
+}
+
 /**
  * The recorded workspace members from `pnpm-workspace.yaml` (the source of truth),
  * each augmented with the `tags` read back from its `package.json`. This is what

package/src/project-py.ts

@@ -3,10 +3,19 @@ import * as projectUtils from "@dbx-tools/core/project-utils";
 import { stringUtils, type OneOrMany } from "@dbx-tools/shared-core";
 import { Component, License, TextFile, type Project, github, javascript, python } from "projen";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
+import { PYTHON_GENERATED_PACKAGE } from "./generated.ts";
 import { LICENSE, projectRepositoryUrl, taskCommand } from "./project-js.ts";
 import { isDBXToolsJavaScriptProject } from "./project-predicate.ts";
 import type { DBXToolsProject, DBXToolsProjectOptions } from "./project.ts";
-import { PythonNodeBundle, type PythonNodeBindingsOptions } from "./python-node-bundle.ts";
+import {
+  PythonNodeBindings,
+  type PythonNodeBindingsOptions,
+} from "./python-node-bindings-component.ts";
+import {
+  PYTHON_NODE_RUNTIME_DISTRIBUTION,
+  PYTHON_NODE_RUNTIME_MODULE,
+  PythonNodeRuntime,
+} from "./python-node-runtime.ts";
 import {
   refreshReleaseDocsDependencies,
   releaseCondition,
@@ -33,6 +42,8 @@ export interface PythonPackageOptions extends DBXToolsProjectOptions {
   readonly moduleRoot?: string;
   readonly description: string;
   readonly dependencies?: readonly string[];
+  /** Named PEP 621 optional dependency groups emitted under `project.optional-dependencies`. */
+  readonly optionalDependencies?: Readonly<Record<string, readonly string[]>>;
   /** Development dependencies emitted only in this package's dependency group. */
   readonly devDependencies?: readonly string[];
   /** Workspace package directories rendered as standalone Git dependencies. */
@@ -40,6 +51,8 @@ export interface PythonPackageOptions extends DBXToolsProjectOptions {
   readonly scripts?: Readonly<Record<string, string>>;
   /** GitHub environment used to publish this distribution to PyPI. */
   readonly releaseEnvironment?: string;
+  /** Mark this package as the shared PythonMonkey runtime and Node shim owner. */
+  readonly nodeRuntime?: boolean;
   /** One or more build-time Node packages embedded through PythonMonkey. */
   readonly nodeBindings?: OneOrMany<PythonNodeBindingsOptions>;
   /** Pinned Git source subsets synchronized into this package's generated tree. */
@@ -52,7 +65,17 @@ export interface PythonSourceSyncOptions {
   readonly source: string;
   readonly include?: readonly string[];
   readonly exclude?: readonly string[];
+  /** Literal text patches applied to each synchronized `.py` file before import localization. */
   readonly replace?: Readonly<Record<string, string>>;
+  /**
+   * Rewrite absolute imports of synchronized modules to the generated package they now
+   * live in, using the Python AST. `true` detects every top-level synchronized module,
+   * importable either bare (`config.schema`) or under the source subdirectory's dotted
+   * path (`graphiti_core.driver.postgraph`). A list names the upstream modules to rewrite
+   * instead, and each entry must match at least one import. Defaults to `true` when the
+   * sync `name` is a Python identifier; set `false` to keep upstream imports unchanged.
+   */
+  readonly localizeImports?: boolean | readonly string[];
 }
 
 interface ResolvedPythonPackageOptions extends PythonPackageOptions {
@@ -231,6 +254,7 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
           licenseFiles: ["LICENSE"],
           requiresPython: options.requiresPython,
           dependencies: [...(pkg.dependencies ?? [])],
+          optionalDependencies: pkg.optionalDependencies,
           scripts: pkg.scripts,
           urls: {
             Source: `${options.repository.url.replace(/\.git$/, "")}/tree/${options.repository.ref}/${pythonPackagePath(options.repository, pkg.directory)}`,
@@ -271,7 +295,13 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
       );
     }
     if (pkg.sync?.length) {
-      this.uv.file.addOverride("tool.dbx_tools.sync", [...pkg.sync]);
+      this.uv.file.addOverride(
+        "tool.dbx_tools.sync",
+        pkg.sync.map(({ localizeImports, ...sync }) => ({
+          ...sync,
+          ...(localizeImports === undefined ? {} : { localize_imports: localizeImports }),
+        })),
+      );
     }
     this.uv.file.readonly = true;
 
@@ -324,28 +354,64 @@ export class DBXToolsPythonWorkspace extends Component {
       name: pkg.name ?? `${scope}-${stringUtils.toSlug(pkg.directory)}`,
       module: pkg.module ?? pythonModuleName(scope, pkg.directory),
     }));
+    const configuredNodeRuntimes = packageIdentities.filter(({ nodeRuntime }) => nodeRuntime);
+    if (configuredNodeRuntimes.length > 1) {
+      throw new Error("A Python workspace can configure only one shared Node runtime package");
+    }
+    const configuredNodeRuntime = configuredNodeRuntimes[0];
+    if (
+      configuredNodeRuntime &&
+      (configuredNodeRuntime.name !== PYTHON_NODE_RUNTIME_DISTRIBUTION ||
+        configuredNodeRuntime.module !== PYTHON_NODE_RUNTIME_MODULE)
+    ) {
+      throw new Error(
+        `The shared Node runtime package must use distribution ${PYTHON_NODE_RUNTIME_DISTRIBUTION} ` +
+          `and module ${PYTHON_NODE_RUNTIME_MODULE}`,
+      );
+    }
+    this.version = readWorkspaceVersion(project.outdir);
     const packagesByDirectory = new Map(packageIdentities.map((pkg) => [pkg.directory, pkg]));
-    const packages = packageIdentities.map((pkg) => ({
-      ...pkg,
-      dependencies: [
+    const nodeRuntimePackage = configuredNodeRuntime;
+    const packages = packageIdentities.map((pkg) => {
+      const usesNodeRuntime = pythonNodeBindings(pkg).length > 0;
+      const internalDependencies = [
+        ...new Set([
+          ...(pkg.internalDependencies ?? []),
+          ...(usesNodeRuntime &&
+          nodeRuntimePackage &&
+          nodeRuntimePackage.directory !== pkg.directory
+            ? [nodeRuntimePackage.directory]
+            : []),
+        ]),
+      ];
+      const dependencies = [
         ...(pkg.dependencies ?? []),
-        ...(pkg.internalDependencies ?? []).map((directory) => {
+        ...internalDependencies.map((directory) => {
           const dependency = packagesByDirectory.get(directory);
           if (!dependency) {
             throw new Error(
               `Python package ${pkg.directory} references unknown internal package ${directory}`,
             );
           }
-          return dependency.name;
+          return usesNodeRuntime && dependency.name === PYTHON_NODE_RUNTIME_DISTRIBUTION
+            ? `${dependency.name}==${this.version}`
+            : dependency.name;
         }),
-      ],
-    }));
+        ...(usesNodeRuntime && !nodeRuntimePackage
+          ? [`${PYTHON_NODE_RUNTIME_DISTRIBUTION}==${this.version}`]
+          : []),
+      ];
+      return {
+        ...pkg,
+        dependencies: [...new Set(dependencies)],
+        internalDependencies,
+      };
+    });
     const resolvedOptions = { ...options, packages };
     this.requiresPython = options.requiresPython ?? ">=3.10";
     this.workflowPythonVersion =
       options.workflowPythonVersion ??
       pythonVersionFromRuffTarget(options.ruffTarget ?? DEFAULT_RUFF_TARGET);
-    this.version = readWorkspaceVersion(project.outdir);
     this.file = this.emitWorkspace(project, resolvedOptions, scope);
     this.packages = packages.map(
       (pkg) =>
@@ -357,13 +423,19 @@ export class DBXToolsPythonWorkspace extends Component {
           version: this.version,
         }),
     );
-    for (const pkg of this.packages) {
-      const bindings = pythonNodeBindings(pkg.packageOptions);
-      if (bindings.length === 0) continue;
-      new PythonNodeBundle(project, {
-        name: pkg.packageOptions.directory,
-        projectDirectory: pythonPackagePath(this.repository, pkg.packageOptions.directory),
+    const syncWatchTasks: string[] = [];
+    if (configuredNodeRuntime) {
+      const runtime = new PythonNodeRuntime(project, {
+        projectDirectory: pythonPackagePath(this.repository, configuredNodeRuntime.directory),
       });
+      syncWatchTasks.push(runtime.watchTask.name);
+    }
+    if (this.packages.some((pkg) => pythonNodeBindings(pkg.packageOptions).length > 0)) {
+      const bindings = new PythonNodeBindings(project);
+      syncWatchTasks.push(bindings.watchTask.name);
+    }
+    if (syncWatchTasks.length && isDBXToolsJavaScriptProject()(project)) {
+      project.dbxToolsConfig.syncWatchTasks.push(...syncWatchTasks);
     }
     for (const pkg of this.packages) {
       if (!pkg.packageOptions.sync?.length) continue;
@@ -681,7 +753,6 @@ export class DBXToolsPythonWorkspace extends Component {
           `- Repository name: ${repository.name}`,
           "- Workflow name: release.yml",
           `- Environment name: ${publication.environment}`,
-          `- GitHub environment tag: ${releaseTag}`,
           "",
         ];
       }),
@@ -759,5 +830,5 @@ function pythonNodeGeneratedSources(pkg: ResolvedPythonPackageOptions): string[]
   if (bindings.length === 0) return [];
   const moduleRoot = pkg.moduleRoot ?? "src";
   const moduleDirectory = `${moduleRoot}/${pkg.module.replaceAll(".", "/")}`;
-  return [`${moduleDirectory}/_generated/**`];
+  return [`${moduleDirectory}/${PYTHON_GENERATED_PACKAGE}/**`];
 }

package/src/project.ts

@@ -12,7 +12,8 @@ import * as projectPredicate from "./project-predicate.ts";
 
 export * from "./project-js.ts";
 export * from "./project-py.ts";
-export * from "./python-node-bundle.ts";
+export * from "./python-node-bindings-component.ts";
+export * from "./python-node-runtime.ts";
 
 /** Runtime family implemented by a dbx-tools project. */
 export type DBXToolsProjectLanguage = "javascript" | "python";

package/src/python-node-bindings-component.ts

@@ -0,0 +1,71 @@
+/** Projen task wiring for repository-wide PythonMonkey Node binding generation. */
+import { Component, type Project, type Task } from "projen";
+import { taskCommand } from "./project-js.ts";
+
+/** Repository-wide task that regenerates every configured Python Node bridge. */
+export const PYTHON_NODE_BINDINGS_TASK = "python-node-bindings";
+
+/** Repository-wide task that verifies every generated Python Node bridge. */
+export const PYTHON_NODE_BINDINGS_CHECK_TASK = `${PYTHON_NODE_BINDINGS_TASK}:check`;
+
+/** Repository-wide task that watches every configured Python Node bridge. */
+export const PYTHON_NODE_BINDINGS_WATCH_TASK = `${PYTHON_NODE_BINDINGS_TASK}:watch`;
+
+/** One function replaced only in a generated PythonMonkey bundle. */
+export interface PythonNodeFunctionOverride {
+  /** Module specifier imported by the ordinary Node source. */
+  readonly module: string;
+  /** Named export to replace. */
+  readonly export: string;
+  /** Repository-relative TypeScript file containing the replacement. */
+  readonly handler: string;
+  /** Named export in {@link handler}. Defaults to {@link export}. */
+  readonly handlerExport?: string;
+}
+
+/** Node package embedded into one Python distribution through PythonMonkey. */
+export interface PythonNodeBindingsOptions {
+  /** Public Node package specifier, such as `@dbx-tools/auth`. */
+  readonly package: string;
+  /** Optional portable package subpath to bind. Defaults to {@link package}. */
+  readonly entrypoint?: string;
+  /** Automatically generated root namespace modules to bind independently. */
+  readonly modules?: readonly string[];
+  /** Functions replaced only while generating the Python runtime. */
+  readonly functionOverrides?: readonly PythonNodeFunctionOverride[];
+}
+
+/** Options for repository-wide PythonMonkey Node binding tasks. */
+export interface PythonNodeBindingsComponentOptions {
+  /** Add the repository-wide freshness check to the test task. Defaults to true. */
+  readonly test?: boolean;
+}
+
+/**
+ * Registers one build, freshness, and watch lifecycle for every configured
+ * `[tool.dbx_tools.node_bindings]` table in the repository.
+ */
+export class PythonNodeBindings extends Component {
+  readonly buildTask: Task;
+  readonly checkTask: Task;
+  readonly watchTask: Task;
+
+  constructor(project: Project, options: PythonNodeBindingsComponentOptions = {}) {
+    super(project);
+    const command = taskCommand("python-node-bindings.ts");
+    this.buildTask = project.addTask(PYTHON_NODE_BINDINGS_TASK, {
+      description: "Generate every configured Python Node binding",
+      execArgs: command,
+    });
+    this.checkTask = project.addTask(PYTHON_NODE_BINDINGS_CHECK_TASK, {
+      description: "Verify every configured Python Node binding is current",
+      execArgs: [...command, "--check"],
+    });
+    this.watchTask = project.addTask(PYTHON_NODE_BINDINGS_WATCH_TASK, {
+      description: "Watch and regenerate affected Python Node bindings",
+      execArgs: taskCommand("python-node-bindings-watch.ts"),
+    });
+    project.preCompileTask.spawn(this.buildTask);
+    if (options.test ?? true) project.testTask.spawn(this.checkTask);
+  }
+}

package/src/python-node-bindings.ts

@@ -32,14 +32,17 @@ export interface ResolvedPythonNodeBindings {
   readonly workspaceDirectories: readonly string[];
 }
 
-/** Standard PythonMonkey host adapters shipped with the binding generator. */
-export const PYTHON_NODE_SHIM_ROOT = resolve(
-  dirname(fileURLToPath(import.meta.url)),
-  "../shims/python-node",
-);
-
-/** Regenerate every pyproject-configured Node binding in a repository. */
-export function generatePythonNodeBindings(projectRoot: string = resolveRepoRoot()): void {
+/** Options for repository-wide Python Node binding generation. */
+export interface GeneratePythonNodeBindingsOptions {
+  /** Verify generated output without changing it. */
+  readonly check?: boolean;
+}
+
+/** Generate or verify every pyproject-configured Node binding in a repository. */
+export function generatePythonNodeBindings(
+  projectRoot: string = resolveRepoRoot(),
+  options: GeneratePythonNodeBindingsOptions = {},
+): void {
   const task = resolve(dirname(fileURLToPath(import.meta.url)), "../tasks/python-node-bindings.ts");
   const configuredProjects = pythonNodeBindingProjects(projectRoot);
   const directories = new Set<string>();
@@ -48,16 +51,38 @@ export function generatePythonNodeBindings(projectRoot: string = resolveRepoRoot
       directories.add(relative(projectRoot, join(config.moduleDirectory, "_generated", "node")));
     }
   }
-  for (const directory of existingBindingDirectories(projectRoot)) {
-    if (!directories.has(directory)) {
-      rmSync(resolve(projectRoot, directory), { recursive: true, force: true });
-    }
+  const stale = existingBindingDirectories(projectRoot).filter(
+    (directory) => !directories.has(directory),
+  );
+  if (stale.length > 0 && options.check) {
+    throw new Error(
+      `Generated Node binding directories are stale:\n${stale.map((directory) => `  ${directory}`).join("\n")}`,
+    );
+  }
+  for (const directory of stale) {
+    rmSync(resolve(projectRoot, directory), { recursive: true, force: true });
   }
   for (const project of configuredProjects) {
-    runTaskCommand(projectRoot, "bun", [task, "--root", projectRoot, "--project", project]);
+    runTaskCommand(projectRoot, "bun", [
+      task,
+      "--root",
+      projectRoot,
+      "--project",
+      project,
+      ...(options.check ? ["--check"] : []),
+    ]);
   }
 }
 
+/** Resolve every configured binding in a repository. */
+export function resolveAllPythonNodeBindings(
+  projectRoot: string = resolveRepoRoot(),
+): ResolvedPythonNodeBindings[] {
+  return pythonNodeBindingProjects(projectRoot).flatMap((project) =>
+    resolvePythonNodeBindings(projectRoot, project),
+  );
+}
+
 /** Repository-relative Python projects that configure generated Node bindings. */
 export function pythonNodeBindingProjects(projectRoot: string): string[] {
   return [
@@ -165,7 +190,6 @@ export function pythonNodeBindingWatchInputs(config: ResolvedPythonNodeBindings)
   return [
     config.pyproject,
     ...config.workspaceDirectories,
-    PYTHON_NODE_SHIM_ROOT,
     ...config.functionOverrides.map(({ handlerFile }) => handlerFile),
   ];
 }

package/src/python-node-runtime.ts

@@ -0,0 +1,56 @@
+/** Projen task wiring for the shared PythonMonkey Node runtime package. */
+import { Component, type Project, type Task } from "projen";
+import { taskCommand } from "./project-js.ts";
+
+/** Published Python distribution imported by every generated Node binding loader. */
+export const PYTHON_NODE_RUNTIME_DISTRIBUTION = "dbx-tools-node-runtime";
+
+/** Python module that owns the shared PythonMonkey runtime and Node shims. */
+export const PYTHON_NODE_RUNTIME_MODULE = "dbx_tools.node_runtime";
+
+/** Repository-wide task that builds the shared Python Node runtime. */
+export const PYTHON_NODE_RUNTIME_TASK = "python-node-runtime";
+
+/** Repository-wide task that verifies the shared Python Node runtime. */
+export const PYTHON_NODE_RUNTIME_CHECK_TASK = `${PYTHON_NODE_RUNTIME_TASK}:check`;
+
+/** Repository-wide task that watches the shared Python Node runtime. */
+export const PYTHON_NODE_RUNTIME_WATCH_TASK = `${PYTHON_NODE_RUNTIME_TASK}:watch`;
+
+/** Options for the package that owns the shared PythonMonkey runtime. */
+export interface PythonNodeRuntimeOptions {
+  /** Repository-relative Python project containing `build-runtime.ts` and `shims/`. */
+  readonly projectDirectory: string;
+}
+
+/**
+ * Registers the shared runtime's build, freshness, and watch lifecycle.
+ *
+ * The runtime package owns the build script, shim sources, generated `runtime.js`,
+ * PythonMonkey bootstrap, and bundle loader. This component only connects those
+ * package-owned operations to Projen's native task graph.
+ */
+export class PythonNodeRuntime extends Component {
+  readonly buildTask: Task;
+  readonly checkTask: Task;
+  readonly watchTask: Task;
+
+  constructor(project: Project, options: PythonNodeRuntimeOptions) {
+    super(project);
+    const buildCommand = ["bun", `${options.projectDirectory}/build-runtime.ts`];
+    this.buildTask = project.addTask(PYTHON_NODE_RUNTIME_TASK, {
+      description: "Build the shared PythonMonkey Node runtime",
+      execArgs: buildCommand,
+    });
+    this.checkTask = project.addTask(PYTHON_NODE_RUNTIME_CHECK_TASK, {
+      description: "Verify the shared PythonMonkey Node runtime is current",
+      execArgs: [...buildCommand, "--check"],
+    });
+    this.watchTask = project.addTask(PYTHON_NODE_RUNTIME_WATCH_TASK, {
+      description: "Watch and rebuild the shared PythonMonkey Node runtime",
+      execArgs: taskCommand("python-node-runtime-watch.ts", "--project", options.projectDirectory),
+    });
+    project.preCompileTask.spawn(this.buildTask);
+    project.testTask.spawn(this.checkTask);
+  }
+}