@dbx-tools/projen 0.9.19 → 0.9.28

package/src/project-py.ts

@@ -6,20 +6,16 @@ import { JobPermission } from "projen/lib/github/workflows-model";
 import { BUN_VERSION, bunCacheRestoreSteps, bunCacheSaveStep } from "./bun-workflow.ts";
 import { DBX_TOOLS_LICENSE, projectRepositoryUrl } from "./project-js.ts";
 import { isDBXToolsJavaScriptProject } from "./project-predicate.ts";
+import { hasWorkspaceNodePackage } from "./python-node-bindings.ts";
+import { PythonNodeBundle, type PythonNodeBindingsOptions } from "./python-node-bundle.ts";
 import type { DBXToolsProject, DBXToolsProjectOptions } from "./project.ts";
+import { RELEASE_VERSION, releaseSourceSteps } from "./release-context.ts";
 import {
-  RELEASE_SHA,
-  RELEASE_TAG,
-  RELEASE_VERSION,
-  releaseSourceSteps,
-} from "./release-dispatch.ts";
-import {
-  independentReleaseSetupSteps,
-  registerIndependentPublicationJob,
+  refreshReleaseDocsDependencies,
   releaseTagPattern,
   releasePublishCondition,
-  releaseStageCondition,
   tryReleaseWorkflow,
+  uvSetupStep,
 } from "./release.ts";
 import { readWorkspaceVersion } from "./workspace-version.ts";
 
@@ -35,13 +31,15 @@ export interface PythonPackageOptions extends DBXToolsProjectOptions {
   readonly directory: string;
   readonly name?: string;
   readonly module?: string;
+  /** Python import root. Defaults to `generated-src` for generated packages, otherwise `src`. */
+  readonly moduleRoot?: string;
   readonly description: string;
   readonly dependencies?: readonly string[];
   /** Workspace package directories rendered as standalone Git dependencies. */
   readonly internalDependencies?: readonly string[];
   readonly scripts?: Readonly<Record<string, string>>;
-  /** Publish this package through the Rust UniFFI release flow instead of the Python workflow. */
-  readonly uniffi?: boolean;
+  /** Build-time Node package embedded through PythonMonkey. */
+  readonly nodeBindings?: PythonNodeBindingsOptions;
   /** Generated source files excluded from strict static analysis. Package-relative. */
   readonly generatedSources?: readonly string[];
   /** Trusted publisher used outside the standard Python release workflow. */
@@ -114,8 +112,6 @@ const DEFAULT_DEV_DEPENDENCIES = [
   "ruff>=0.12,<1",
 ] as const;
 
-const quote = (value: string): string => JSON.stringify(value);
-
 /** Repository-relative path for a Python package directory. */
 export function pythonPackagePath(repository: PythonRepositoryOptions, directory: string): string {
   return `${repository.root ?? "packages/py"}/${directory}`;
@@ -197,7 +193,8 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
         uv: {
           buildBackend: {
             moduleName: pkg.module,
-            moduleRoot: "src",
+            moduleRoot:
+              pkg.moduleRoot ?? (pkg.nodeBindings?.layout === "package" ? "generated-src" : "src"),
             namespace: true,
           },
         },
@@ -214,8 +211,24 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
     if (pkg.scripts) {
       this.uv.file.addOverride("project.scripts", pkg.scripts);
     }
-    if (pkg.uniffi !== undefined) {
-      this.uv.file.addOverride("tool.dbx_tools.config.uniffi", pkg.uniffi);
+    if (pkg.nodeBindings) {
+      this.uv.file.addOverride("tool.dbx_tools.node_bindings", {
+        package: pkg.nodeBindings.package,
+        ...(pkg.nodeBindings.entrypoint ? { entrypoint: pkg.nodeBindings.entrypoint } : {}),
+        ...(pkg.nodeBindings.layout ? { layout: pkg.nodeBindings.layout } : {}),
+        ...(pkg.nodeBindings.private ? { private: true } : {}),
+        ...(pkg.nodeBindings.shimRoot ? { shim_root: pkg.nodeBindings.shimRoot } : {}),
+        ...(pkg.nodeBindings.functionOverrides?.length
+          ? {
+              function_overrides: pkg.nodeBindings.functionOverrides.map((override) => ({
+                module: override.module,
+                export: override.export,
+                handler: override.handler,
+                ...(override.handlerExport ? { handler_export: override.handlerExport } : {}),
+              })),
+            }
+          : {}),
+      });
     }
     this.uv.file.readonly = true;
 
@@ -279,10 +292,7 @@ export class DBXToolsPythonWorkspace extends Component {
     }));
     const resolvedOptions = { ...options, packages };
     this.requiresPython = options.requiresPython ?? ">=3.10";
-    this.version =
-      isDBXToolsJavaScriptProject()(project) && project.releaseCatalog.mode === "independent"
-        ? "0.0.0"
-        : readWorkspaceVersion(project.outdir);
+    this.version = readWorkspaceVersion(project.outdir);
     this.file = this.emitWorkspace(project, resolvedOptions, scope);
     this.packages = packages.map(
       (pkg) =>
@@ -300,6 +310,14 @@ export class DBXToolsPythonWorkspace extends Component {
             : this.version,
         }),
     );
+    for (const pkg of this.packages) {
+      if (!pkg.packageOptions.nodeBindings) continue;
+      new PythonNodeBundle(project, {
+        name: pkg.packageOptions.directory,
+        projectDirectory: pythonPackagePath(this.repository, pkg.packageOptions.directory),
+        watch: hasWorkspaceNodePackage(project, pkg.packageOptions.nodeBindings.package),
+      });
+    }
     if (isDBXToolsJavaScriptProject()(project)) {
       for (const pkg of this.packages) {
         project.releaseCatalog.registerProject(pkg, {
@@ -321,7 +339,7 @@ export class DBXToolsPythonWorkspace extends Component {
             return {
               target: dependency.name,
               kind: "runtime" as const,
-              requirement: pythonReleaseRequirement(version, dependency.uniffi === true),
+              requirement: pythonReleaseRequirement(version),
               propagation: "outside-range" as const,
               publishOrder: true,
               internal: true,
@@ -372,7 +390,9 @@ export class DBXToolsPythonWorkspace extends Component {
 
   private emitWorkspace(
     project: javascript.NodeProject,
-    options: DBXToolsPythonWorkspaceOptions,
+    options: Omit<DBXToolsPythonWorkspaceOptions, "packages"> & {
+      readonly packages: readonly ResolvedPythonPackageOptions[];
+    },
     scope: string,
   ): python.PyprojectTomlFile {
     const testPaths = options.testPaths ?? [this.repository.root];
@@ -416,7 +436,7 @@ export class DBXToolsPythonWorkspace extends Component {
     const projectExcludes = [
       ...(options.pyreflyProjectExcludes ?? []),
       ...options.packages.flatMap((pkg) =>
-        (pkg.generatedSources ?? []).map(
+        [...(pkg.generatedSources ?? []), ...pythonNodeGeneratedSources(pkg)].map(
           (source) => `${this.repository.root}/${pkg.directory}/${source}`,
         ),
       ),
@@ -459,154 +479,12 @@ export class DBXToolsPythonWorkspace extends Component {
   private addReleaseWorkflow(project: javascript.NodeProject, options: PythonReleaseOptions): void {
     if (!project.github || !isDBXToolsJavaScriptProject()(project)) return;
     const publications = this.publications(options);
-    const uniffiPublications = this.uniffiPublications(options);
-    const allPublications = [...publications, ...uniffiPublications];
+    const allPublications = publications;
     if (allPublications.length === 0) return;
-    const usesRustArtifacts = uniffiPublications.length > 0;
     const workflow = tryReleaseWorkflow(project);
     if (!workflow) {
       throw new Error("Python release requires the root dbx-tools release mode");
     }
-    if (project.releaseCatalog.mode === "independent") {
-      workflow.addJob("build-python", {
-        if: usesRustArtifacts
-          ? "${{ always() && needs.release-plan.outputs.python == 'true' && needs.rust-build.result != 'failure' && needs.rust-build.result != 'cancelled' && (github.event_name == 'push' || inputs.stage == 'all' || inputs.stage == 'python') }}"
-          : "${{ needs.release-plan.outputs.python == 'true' && (github.event_name == 'push' || inputs.stage == 'all' || inputs.stage == 'python') }}",
-        needs: ["release-plan", ...(usesRustArtifacts ? ["rust-build"] : [])],
-        runsOn: ["ubuntu-latest"],
-        permissions: { actions: JobPermission.READ, contents: JobPermission.READ },
-        timeoutMinutes: 20,
-        env: { BUN_VERSION },
-        steps: [
-          ...independentReleaseSetupSteps(project),
-          { name: "Setup uv", uses: "astral-sh/setup-uv@v7" },
-          ...uniffiPublications.map((publication) => ({
-            name: `Download ${publication.distribution} native wheels`,
-            uses: "actions/download-artifact@v8",
-            with: {
-              pattern: `${publication.distribution}--*--python-wheel`,
-              path: `dist/${publication.directory}`,
-              "merge-multiple": true,
-            },
-          })),
-          {
-            name: "Build affected distributions",
-            shell: "bash",
-            run: publications
-              .map(
-                (publication) =>
-                  `if jq -e --arg package ${quote(publication.distribution)} '.pythonPackages[] | select(.identity == $package)' dist/release-plan.json >/dev/null; then uv build --package ${quote(publication.distribution)} --out-dir dist/${publication.directory}; fi`,
-              )
-              .join("\n"),
-          },
-          {
-            name: "Validate affected distributions",
-            run: "find dist -type f \\( -name '*.whl' -o -name '*.tar.gz' \\) -print0 | xargs -0 uvx twine check",
-          },
-          {
-            name: "Upload distributions",
-            uses: "actions/upload-artifact@v7",
-            with: { name: "python-distributions", path: "dist", "retention-days": 7 },
-          },
-        ],
-      });
-      for (const publication of allPublications) {
-        const dependencyJobs = (publication.dependencies ?? []).map(
-          (dependency) => `publish-pypi-${dependency}`,
-        );
-        const dependencyCondition = dependencyJobs
-          .map((job) => `needs.${job}.result != 'failure' && needs.${job}.result != 'cancelled'`)
-          .join(" && ");
-        workflow.addJob(`publish-pypi-${publication.directory}`, {
-          if: `\${{ always() && needs.build-python.result == 'success' && contains(needs.release-plan.outputs.python_packages, '"identity":"${publication.distribution}"') && (github.event_name == 'push' || inputs.stage == 'all' || inputs.stage == 'python')${dependencyCondition ? ` && ${dependencyCondition}` : ""} }}`,
-          needs: ["release-plan", "build-python", ...dependencyJobs],
-          environment: {
-            name: publication.environment,
-            url:
-              options.environmentUrl ??
-              `https://pypi.org/project/${publication.distribution.replaceAll("_", "-")}/`,
-          },
-          runsOn: ["ubuntu-latest"],
-          permissions: { idToken: JobPermission.WRITE },
-          timeoutMinutes: 10,
-          steps: [
-            {
-              name: "Download distributions",
-              uses: "actions/download-artifact@v8",
-              with: { name: "python-distributions", path: "dist" },
-            },
-            {
-              name: `Publish ${publication.distribution} to PyPI`,
-              uses: "pypa/gh-action-pypi-publish@release/v1",
-              with: {
-                "packages-dir": `dist/${publication.directory}`,
-                "skip-existing": true,
-              },
-            },
-          ],
-        });
-        registerIndependentPublicationJob(workflow, `publish-pypi-${publication.directory}`);
-      }
-      return;
-    }
-    workflow.addJob("build-python", {
-      if: releaseStageCondition("python", ["needs.verify-context.result == 'success'"]),
-      needs: ["verify-context"],
-      runsOn: ["ubuntu-latest"],
-      permissions: { contents: JobPermission.READ },
-      timeoutMinutes: 20,
-      env: { BUN_VERSION },
-      steps: [
-        ...releaseSourceSteps(),
-        ...bunCacheRestoreSteps(project, {
-          ignorePaths: project.workflowCacheIgnorePaths,
-        }),
-        { name: "Setup uv", uses: "astral-sh/setup-uv@v7" },
-        { name: "Install release helpers", run: "bun install" },
-        bunCacheSaveStep(),
-        {
-          name: "Download approved Python distributions",
-          env: { GH_TOKEN: "${{ github.token }}", RELEASE_TAG },
-          run: [
-            "rm -rf dist/release-download",
-            "mkdir -p dist/release-download",
-            'gh release download "$RELEASE_TAG" --pattern release-manifest.json --pattern SHA256SUMS --pattern "*.whl" --pattern "*.tar.gz" --dir dist/release-download',
-          ].join("\n"),
-        },
-        ...allPublications.map((publication) => ({
-          name: `Select ${publication.distribution} distributions`,
-          env: {
-            PACKAGE_NAME: publication.distribution.replaceAll("_", "-").toLowerCase(),
-            RELEASE_SHA,
-            RELEASE_TAG,
-            RELEASE_VERSION,
-          },
-          run: [
-            "bun node_modules/@dbx-tools/projen/tasks/release-manifest.ts verify \\",
-            "  --directory dist/release-download \\",
-            '  --tag "$RELEASE_TAG" \\',
-            '  --sha "$RELEASE_SHA" \\',
-            '  --version "$RELEASE_VERSION" \\',
-            "  --kind pypi \\",
-            '  --package "$PACKAGE_NAME" \\',
-            `  --output dist/${publication.directory}`,
-          ].join("\n"),
-        })),
-        {
-          name: "Validate approved distributions",
-          run: `find ${allPublications.map((publication) => `dist/${publication.directory}`).join(" ")} -type f \\( -name '*.whl' -o -name '*.tar.gz' \\) -print0 | xargs -0 uvx twine check`,
-        },
-        {
-          name: "Upload distributions",
-          uses: "actions/upload-artifact@v7",
-          with: {
-            name: "python-distributions",
-            path: allPublications.map((publication) => `dist/${publication.directory}`).join("\n"),
-            "retention-days": 7,
-          },
-        },
-      ],
-    });
     for (const publication of allPublications) {
       const dependencyJobs = (publication.dependencies ?? []).map(
         (dependency) => `publish-pypi-${dependency}`,
@@ -614,10 +492,9 @@ export class DBXToolsPythonWorkspace extends Component {
       workflow.addJob(`publish-pypi-${publication.directory}`, {
         if: releasePublishCondition("python", [
           "needs.verify-context.result == 'success'",
-          "needs.build-python.result == 'success'",
           ...dependencyJobs.map((job) => `needs['${job}'].result == 'success'`),
         ]),
-        needs: ["verify-context", "build-python", ...dependencyJobs],
+        needs: ["verify-context", ...dependencyJobs],
         environment: {
           name: publication.environment,
           url:
@@ -627,11 +504,24 @@ export class DBXToolsPythonWorkspace extends Component {
         runsOn: ["ubuntu-latest"],
         permissions: { idToken: JobPermission.WRITE },
         timeoutMinutes: 10,
+        env: { BUN_VERSION },
         steps: [
+          ...releaseSourceSteps(),
+          ...bunCacheRestoreSteps(project, {
+            ignorePaths: project.workflowCacheIgnorePaths,
+          }),
+          uvSetupStep(),
+          { name: "Install release helpers", run: "bun install --frozen-lockfile" },
+          bunCacheSaveStep(),
           {
-            name: "Download distributions",
-            uses: "actions/download-artifact@v8",
-            with: { name: "python-distributions", path: "dist" },
+            name: `Build ${publication.distribution} distributions`,
+            env: { RELEASE_VERSION },
+            run: [
+              'bun node_modules/@dbx-tools/projen/tasks/publish-python.ts "$RELEASE_VERSION"',
+              `--root ${JSON.stringify(this.repository.root)}`,
+              `--package ${JSON.stringify(publication.directory)}`,
+              `--output dist/${publication.directory}`,
+            ].join(" \\\n  "),
           },
           {
             name: `Publish ${publication.distribution} to PyPI`,
@@ -644,32 +534,17 @@ export class DBXToolsPythonWorkspace extends Component {
         ],
       });
     }
+    refreshReleaseDocsDependencies(project);
   }
 
   private publications(options: PythonReleaseOptions): readonly PythonPublication[] {
-    return this.packages
-      .filter((pkg) => pkg.packageOptions.uniffi !== true)
-      .map((pkg) => ({
-        directory: pkg.packageOptions.directory,
-        distribution: pkg.packageOptions.name,
-        environment:
-          options.environments?.[pkg.packageOptions.name] ?? `pypi-${pkg.packageOptions.name}`,
-      }));
-  }
-
-  private uniffiPublications(options: PythonReleaseOptions): readonly PythonPublication[] {
-    return this.packages
-      .filter((pkg) => pkg.packageOptions.uniffi === true)
-      .map((pkg) => ({
-        directory: pkg.packageOptions.directory,
-        distribution: pkg.packageOptions.name,
-        environment:
-          pkg.packageOptions.trustedPublisher?.environment ??
-          options.environments?.[pkg.packageOptions.name] ??
-          `pypi-${pkg.packageOptions.name}`,
-        artifacts: pkg.packageOptions.trustedPublisher?.artifacts,
-        dependencies: pkg.packageOptions.internalDependencies,
-      }));
+    return this.packages.map((pkg) => ({
+      directory: pkg.packageOptions.directory,
+      distribution: pkg.packageOptions.name,
+      environment:
+        options.environments?.[pkg.packageOptions.name] ?? `pypi-${pkg.packageOptions.name}`,
+      dependencies: pkg.packageOptions.internalDependencies,
+    }));
   }
 
   private trustedPublisherPublications(
@@ -697,11 +572,10 @@ export class DBXToolsPythonWorkspace extends Component {
   ): void {
     const repository = this.githubRepository();
     const publications = this.trustedPublisherPublications(options);
-    const releaseTag = isDBXToolsJavaScriptProject()(project)
-      ? project.releaseCatalog.mode === "independent"
-        ? "*-v*"
-        : releaseTagPattern(project)
-      : "v*";
+    const releaseTag =
+      isDBXToolsJavaScriptProject()(project) && tryReleaseWorkflow(project)
+        ? releaseTagPattern(project)
+        : "v*";
     const linesBeforeAuthentication = [
       "# PyPI Trusted Publisher Setup Instructions",
       "",
@@ -814,3 +688,17 @@ export class DBXToolsPythonWorkspace extends Component {
     return { owner: match[1], name: match[2] };
   }
 }
+
+function pythonNodeGeneratedSources(pkg: ResolvedPythonPackageOptions): string[] {
+  if (!pkg.nodeBindings) return [];
+  const moduleRoot =
+    pkg.moduleRoot ?? (pkg.nodeBindings.layout === "package" ? "generated-src" : "src");
+  const moduleDirectory = `${moduleRoot}/${pkg.module.replaceAll(".", "/")}`;
+  const generatedDirectory =
+    pkg.nodeBindings.layout === "package" ? moduleDirectory : `${moduleDirectory}/_generated`;
+  return [
+    `${generatedDirectory}/_runtime.js`,
+    `${generatedDirectory}/node_bindings.py`,
+    `${generatedDirectory}/__init__.py`,
+  ];
+}

package/src/project.ts

@@ -12,10 +12,10 @@ import * as projectPredicate from "./project-predicate.ts";
 
 export * from "./project-js.ts";
 export * from "./project-py.ts";
-export * from "./project-rs.ts";
+export * from "./python-node-bundle.ts";
 
 /** Runtime family implemented by a dbx-tools project. */
-export type DBXToolsProjectLanguage = "javascript" | "python" | "rust";
+export type DBXToolsProjectLanguage = "javascript" | "python";
 
 /** Options shared by every dbx-tools project implementation. */
 export interface DBXToolsProjectOptions extends Partial<

package/src/python-node-bindings.ts

@@ -0,0 +1,138 @@
+/** Shared pyproject-backed configuration for PythonMonkey Node bindings. */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { object } from "@dbx-tools/shared-core";
+import type { Project } from "projen";
+import { parse } from "smol-toml";
+import { workspaceDependencyDirectories } from "./packages.ts";
+
+export interface ResolvedPythonNodeFunctionOverride {
+  readonly handlerExport: string;
+  readonly handlerFile: string;
+  readonly targetExport: string;
+  readonly targetModule: string;
+}
+
+export interface ResolvedPythonNodeBindings {
+  readonly bindingsPackageOutput: string;
+  readonly bindingsOutput: string;
+  readonly functionOverrides: readonly ResolvedPythonNodeFunctionOverride[];
+  readonly entrypoint: string;
+  readonly moduleDirectory: string;
+  readonly layout: "package" | "submodule";
+  readonly private: boolean;
+  readonly package: string;
+  readonly project: string;
+  readonly projectDirectory: string;
+  readonly pyproject: string;
+  readonly runtimeOutput: string;
+  readonly shimRoot?: string;
+  readonly workspaceDirectories: readonly string[];
+}
+
+/** Resolve one Python package's Node binding configuration and conventional outputs. */
+export function resolvePythonNodeBindings(
+  root: string,
+  project: string,
+): ResolvedPythonNodeBindings {
+  const projectDirectory = resolve(root, project);
+  const pyproject = resolve(projectDirectory, "pyproject.toml");
+  const manifest = record(parse(readFileSync(pyproject, "utf8")), "pyproject.toml");
+  const tool = record(manifest.tool, "tool");
+  const dbxTools = record(tool.dbx_tools, "tool.dbx_tools");
+  const bindings = record(dbxTools.node_bindings, "tool.dbx_tools.node_bindings");
+  const uv = record(tool.uv, "tool.uv");
+  const backend = record(uv["build-backend"], "tool.uv.build-backend");
+  const packageName = requiredString(bindings.package, "tool.dbx_tools.node_bindings.package");
+  const entrypoint =
+    optionalString(bindings.entrypoint, "tool.dbx_tools.node_bindings.entrypoint") ?? packageName;
+  const layout = nodeBindingsLayout(bindings.layout);
+  const moduleName = requiredString(backend["module-name"], "tool.uv.build-backend.module-name");
+  const moduleRoot = requiredString(backend["module-root"], "tool.uv.build-backend.module-root");
+  const configuredOverrides = bindings.function_overrides ?? [];
+  if (!Array.isArray(configuredOverrides)) {
+    throw new Error("tool.dbx_tools.node_bindings.function_overrides must be an array");
+  }
+  const moduleDirectory = resolve(projectDirectory, moduleRoot, ...moduleName.split("."));
+  const generatedDirectory =
+    layout === "package" ? moduleDirectory : join(moduleDirectory, "_generated");
+  const shimRoot = optionalString(bindings.shim_root, "tool.dbx_tools.node_bindings.shim_root");
+  return {
+    project,
+    projectDirectory,
+    pyproject,
+    package: packageName,
+    entrypoint,
+    layout,
+    private: optionalBoolean(bindings.private, "tool.dbx_tools.node_bindings.private") ?? false,
+    moduleDirectory,
+    runtimeOutput: join(generatedDirectory, "_runtime.js"),
+    bindingsOutput: join(generatedDirectory, "node_bindings.py"),
+    bindingsPackageOutput: join(generatedDirectory, "__init__.py"),
+    ...(shimRoot ? { shimRoot: resolve(root, shimRoot) } : {}),
+    functionOverrides: configuredOverrides.map((candidate, index) => {
+      const path = `tool.dbx_tools.node_bindings.function_overrides[${index}]`;
+      const override = record(candidate, path);
+      const targetExport = requiredString(override.export, `${path}.export`);
+      return {
+        targetModule: requiredString(override.module, `${path}.module`),
+        targetExport,
+        handlerFile: resolve(root, requiredString(override.handler, `${path}.handler`)),
+        handlerExport:
+          optionalString(override.handler_export, `${path}.handler_export`) ?? targetExport,
+      };
+    }),
+    workspaceDirectories: workspaceDependencyDirectories(packageName, root),
+  };
+}
+
+function nodeBindingsLayout(value: unknown): "package" | "submodule" {
+  if (value === undefined) return "submodule";
+  if (value === "package" || value === "submodule") return value;
+  throw new Error("tool.dbx_tools.node_bindings.layout must be package or submodule");
+}
+
+/** All paths that can change a workspace-backed generated Node runtime. */
+export function pythonNodeBindingWatchInputs(config: ResolvedPythonNodeBindings): string[] {
+  if (config.workspaceDirectories.length === 0) {
+    throw new Error(`${config.package} is not a workspace package and cannot be watched`);
+  }
+  return [
+    config.pyproject,
+    ...config.workspaceDirectories,
+    ...(config.shimRoot ? [config.shimRoot] : []),
+    ...config.functionOverrides.map(({ handlerFile }) => handlerFile),
+  ];
+}
+
+/** Whether a Projen tree already contains the configured Node package. */
+export function hasWorkspaceNodePackage(project: Project, packageName: string): boolean {
+  return (
+    project.name === packageName || project.subprojects.some((child) => child.name === packageName)
+  );
+}
+
+function record(value: unknown, path: string): Record<string, unknown> {
+  if (!object.isRecord(value)) throw new Error(`${path} must be a table`);
+  return value;
+}
+
+function requiredString(value: unknown, path: string): string {
+  const parsed = optionalString(value, path);
+  if (!parsed) throw new Error(`${path} must be a non-empty string`);
+  return parsed;
+}
+
+function optionalString(value: unknown, path: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${path} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalBoolean(value: unknown, path: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new Error(`${path} must be a boolean`);
+  return value;
+}

package/src/python-node-bundle.ts

@@ -0,0 +1,92 @@
+import { Component, type Project, type Task } from "projen";
+import { taskScript } from "./project-js.ts";
+import { isDBXToolsJavaScriptProject } from "./project-predicate.ts";
+
+/** 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;
+  /** Generated bindings own the package or live under `_generated`. Defaults to `submodule`. */
+  readonly layout?: "package" | "submodule";
+  /** Keep generated symbols out of the generated package `__init__`. Defaults to false. */
+  readonly private?: boolean;
+  /** Repository-relative directory containing Node built-in shims. */
+  readonly shimRoot?: string;
+  /** Functions replaced only while generating the Python runtime. */
+  readonly functionOverrides?: readonly PythonNodeFunctionOverride[];
+}
+
+/** Options for pyproject-driven PythonMonkey generation tasks. */
+export interface PythonNodeBundleOptions {
+  /** Stable task-name prefix, such as `auth`. */
+  readonly name: string;
+  /** Repository-relative Python project containing `pyproject.toml`. */
+  readonly projectDirectory: string;
+  /** Add the freshness check to the project's test task. Defaults to true. */
+  readonly test?: boolean;
+  /** Regenerate during the root workspace watch loop. Defaults to false. */
+  readonly watch?: boolean;
+}
+
+/** Owns paired generation and freshness-check tasks for one Python package. */
+export class PythonNodeBundle extends Component {
+  readonly buildTask: Task;
+  readonly checkTask: Task;
+  readonly watchTask?: Task;
+
+  constructor(project: Project, options: PythonNodeBundleOptions) {
+    super(project);
+    const command = taskScript(
+      project,
+      "python-node-bindings.ts",
+      `--project ${shellQuote(options.projectDirectory)}`,
+    );
+    this.buildTask = project.addTask(`${options.name}:python-runtime`, {
+      description: `Generate Node bindings for Python package ${options.name}`,
+      exec: command,
+    });
+    this.checkTask = project.addTask(`${options.name}:python-runtime:check`, {
+      description: `Verify generated Node bindings for Python package ${options.name}`,
+      exec: `${command} --check`,
+    });
+    if (options.test ?? true) project.testTask.spawn(this.checkTask);
+    if (options.watch) {
+      this.watchTask = project.addTask(`${options.name}:python-runtime:watch`, {
+        description: `Regenerate Node bindings for Python package ${options.name} on changes`,
+        exec: taskScript(
+          project,
+          "python-node-bindings-watch.ts",
+          `--project ${shellQuote(options.projectDirectory)}`,
+        ),
+      });
+      if (isDBXToolsJavaScriptProject()(project)) {
+        const configured = project.dbxToolsConfig.pythonNodeBindings;
+        const projects = Array.isArray(configured)
+          ? configured.filter((value): value is string => typeof value === "string")
+          : [];
+        project.dbxToolsConfig.pythonNodeBindings = [
+          ...new Set([...projects, options.projectDirectory]),
+        ];
+      }
+    }
+  }
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:@=+#-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}