@dbx-tools/projen 0.9.106 → 0.9.108

package/tasks/publish-python.ts

@@ -17,8 +17,14 @@ import {
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import * as projectUtils from "@dbx-tools/core/project-utils";
-import { Command } from "commander";
 import { parse, stringify } from "smol-toml";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions, taskPositionals } from "./cli.ts";
+import {
+  TaskDirectoriesOptionSchema,
+  TaskDryRunOptionSchema,
+  TaskOutputOptionSchema,
+} from "./options.ts";
 import { preparePythonProjectForPublication, pythonProjectInfo } from "./python-release.ts";
 import { runTaskCommand } from "../src/_task-command.ts";
 
@@ -182,56 +188,48 @@ function buildPythonProjectsInternal(
 }
 
 /** Parse command-line publication options and run the Python release task. */
-export async function main(): Promise<void> {
-  const program = new Command();
-  program
-    .argument("<version>", "Python package version")
-    .option("--index-url <url>", "devpi Simple API URL")
-    .option("--publish-url <url>", "devpi writable index URL")
-    .option("--root <path>", "Python workspace package root", "packages/py")
-    .option("--package <directory...>", "Build only selected package directories")
-    .option("--output <path>", "Build distributions into a directory without publishing")
-    .option(
-      "--package-directories",
-      "Keep each package's distributions in its own output directory",
-    )
-    .option("--dry-run", "build and inspect distributions without uploading")
-    .action(
-      (
-        version: string,
-        options: {
-          dryRun?: boolean;
-          indexUrl?: string;
-          package?: string[];
-          packageDirectories?: boolean;
-          publishUrl?: string;
-          root: string;
-          output?: string;
-        },
-      ) => {
-        if (options.output) {
-          buildPythonProjects({
-            output: options.output,
-            packages: options.package,
-            packageDirectories: options.packageDirectories,
-            root: options.root,
-            version,
-          });
-        } else {
-          if (!options.indexUrl || !options.publishUrl) {
-            throw new Error("--index-url and --publish-url are required when publishing");
-          }
-          publishPythonProjects({
-            dryRun: options.dryRun,
-            indexUrl: options.indexUrl,
-            publishUrl: options.publishUrl,
-            root: options.root,
-            version,
-          });
-        }
-      },
-    );
-  await program.parseAsync();
+export const PublishPythonOptionsSchema = z.object({
+  indexUrl: z.string().trim().min(1).optional().describe("devpi Simple API URL"),
+  publishUrl: z.string().trim().min(1).optional().describe("devpi writable index URL"),
+  root: z.string().trim().min(1).default("packages/py").describe("Python workspace package root"),
+  package: TaskDirectoriesOptionSchema.describe("Repeatable Python package directory to build"),
+  output: TaskOutputOptionSchema.describe("Build distributions into this directory"),
+  packageDirectories: z
+    .boolean()
+    .default(false)
+    .describe("Keep each package's distributions in its own output directory"),
+  dryRun: TaskDryRunOptionSchema,
+});
+
+/** Parse task options and build or publish Python workspace distributions. */
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  const command = taskCommand(
+    import.meta.url,
+    "Build or publish Python workspace distributions",
+    PublishPythonOptionsSchema,
+  ).argument("<version>", "Python package version");
+  const options = await taskOptions(command, PublishPythonOptionsSchema, args);
+  const version = String(taskPositionals(command)[0]);
+  if (options.output) {
+    buildPythonProjects({
+      output: options.output,
+      packages: options.package.length ? options.package : undefined,
+      packageDirectories: options.packageDirectories,
+      root: options.root,
+      version,
+    });
+    return;
+  }
+  if (!options.indexUrl || !options.publishUrl) {
+    throw new Error("--index-url and --publish-url are required when publishing");
+  }
+  publishPythonProjects({
+    dryRun: options.dryRun,
+    indexUrl: options.indexUrl,
+    publishUrl: options.publishUrl,
+    root: options.root,
+    version,
+  });
 }
 
-if (import.meta.main) await main();
+await runTaskMain(import.meta, main);

package/tasks/publish.ts

@@ -47,6 +47,15 @@ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync
 import { tmpdir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { asyncUtils, log, object } from "@dbx-tools/shared-core";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions, taskPositionals, taskRoot } from "./cli.ts";
+import {
+  TaskConcurrencyOptionSchema,
+  TaskDirectoriesOptionSchema,
+  TaskDryRunOptionSchema,
+  TaskOutputOptionSchema,
+  TaskRootOptionSchema,
+} from "./options.ts";
 import {
   applyPublishConfig,
   npmReleaseMatches,
@@ -100,31 +109,34 @@ function outputDirectory(root: string, value: string | undefined): string | unde
   return output;
 }
 
+export const PublishOptionsSchema = z.object({
+  root: TaskRootOptionSchema,
+  registry: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("npm registry URL")
+    .meta({ env: "NPM_CONFIG_REGISTRY" }),
+  output: TaskOutputOptionSchema,
+  exclude: TaskDirectoriesOptionSchema.describe("Repeatable workspace directory to exclude"),
+  dryRun: TaskDryRunOptionSchema,
+  skipCompile: z.boolean().default(false).describe("Reuse already validated compiled output"),
+  concurrency: TaskConcurrencyOptionSchema.default(4),
+});
+
 export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
-  const version = argv[0] && !argv[0].startsWith("--") ? argv[0] : undefined;
-  const rest = version ? argv.slice(1) : argv;
-  const root = process.cwd();
-  if (!version) {
-    logger.error(
-      "usage: bun tasks/publish.ts <version> [--registry <url>] [--output <dir>] [--exclude <dir>] [--dry-run] [--skip-compile]",
-    );
-    process.exit(1);
-  }
-  const registryIdx = rest.indexOf("--registry");
-  const registry = registryIdx >= 0 ? rest[registryIdx + 1] : undefined;
-  const outputIdx = rest.indexOf("--output");
-  const output = outputDirectory(root, outputIdx >= 0 ? rest[outputIdx + 1] : undefined);
-  const dryRun = rest.includes("--dry-run");
-  const skipCompile = rest.includes("--skip-compile");
-  const concurrencyIdx = rest.indexOf("--concurrency");
-  const parsedConcurrency = Number(concurrencyIdx >= 0 ? rest[concurrencyIdx + 1] : 4);
-  if (!Number.isInteger(parsedConcurrency) || parsedConcurrency < 1) {
-    throw new Error(`--concurrency must be a positive integer, got ${String(parsedConcurrency)}`);
-  }
-  const concurrency = parsedConcurrency;
-  const excluded = new Set(
-    rest.reduce<string[]>((acc, arg, i) => (arg === "--exclude" ? [...acc, rest[i + 1]] : acc), []),
-  );
+  const command = taskCommand(
+    import.meta.url,
+    "Build and publish the current npm workspace",
+    PublishOptionsSchema,
+  ).argument("<version>", "Workspace release version");
+  const options = await taskOptions(command, PublishOptionsSchema, argv);
+  const version = String(taskPositionals(command)[0]);
+  const root = taskRoot(options.root);
+  const output = outputDirectory(root, options.output);
+  const { registry, dryRun, skipCompile, concurrency } = options;
+  const excluded = new Set(options.exclude);
 
   const path = enrichedPath(root);
   const allMembers = recordedPackages(root)
@@ -265,4 +277,4 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
   );
 }
 
-if (import.meta.main) await main();
+await runTaskMain(import.meta, main);

package/tasks/python-node-bindings-watch.ts

@@ -3,6 +3,7 @@
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { log } from "@dbx-tools/shared-core";
+import { runTaskMain } from "./cli.ts";
 import { runTaskCommand } from "../src/_task-command.ts";
 import { repoRoot } from "../src/packages.ts";
 import {
@@ -91,4 +92,4 @@ export async function main(): Promise<void> {
   );
 }
 
-if (import.meta.main) await main();
+await runTaskMain(import.meta, main);

package/tasks/python-node-bindings.ts

@@ -6,11 +6,13 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { parseArgs } from "node:util";
 import { log, stringUtils } from "@dbx-tools/shared-core";
 import type { BunPlugin } from "bun";
 import stdLibBrowser from "node-stdlib-browser";
 import ts from "typescript";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions } from "./cli.ts";
+import { TaskCheckOptionSchema, TaskForceOptionSchema, TaskRootOptionSchema } from "./options.ts";
 import { header, makeReadonly, makeWritable } from "../src/generated.ts";
 import { publicFunctionExports } from "../src/module-exports.ts";
 import { resolveRepoRoot } from "../src/packages.ts";
@@ -34,26 +36,37 @@ const logger = log.logger("projen:python-node-bindings");
 
 type FunctionOverride = ResolvedPythonNodeFunctionOverride;
 
-function bindingIndex(value: string, count: number, project: string): number {
-  const index = Number.parseInt(value, 10);
-  if (!Number.isSafeInteger(index) || String(index) !== value || index < 0 || index >= count) {
-    throw new Error(`Node binding index ${value} is not configured for ${project}`);
+function bindingIndex(index: number, count: number, project: string): number {
+  if (index >= count) {
+    throw new Error(`Node binding index ${index} is not configured for ${project}`);
   }
   return index;
 }
 
+export const PythonNodeBindingsOptionsSchema = z.object({
+  binding: z.coerce
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe("Configured binding index within the selected project"),
+  check: TaskCheckOptionSchema,
+  force: TaskForceOptionSchema,
+  module: z.string().trim().min(1).optional().describe("Configured package module to generate"),
+  project: z.string().trim().min(1).optional().describe("Python project directory"),
+  root: TaskRootOptionSchema,
+});
+
 export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
-  const { values } = parseArgs({
+  const values = await taskOptions(
+    taskCommand(
+      import.meta.url,
+      "Generate PythonMonkey runtime and typed Python wrappers",
+      PythonNodeBindingsOptionsSchema,
+    ),
+    PythonNodeBindingsOptionsSchema,
     args,
-    options: {
-      binding: { type: "string" },
-      check: { type: "boolean" },
-      force: { type: "boolean" },
-      module: { type: "string" },
-      project: { type: "string" },
-      root: { type: "string" },
-    },
-  });
+  );
   const root = values.root ? resolve(values.root) : resolveRepoRoot();
   if (!values.project) {
     if (values.binding !== undefined || values.module !== undefined) {
@@ -1186,4 +1199,4 @@ function pythonRuntimeLoader(source: string): string {
   ].join("\n");
 }
 
-if (import.meta.main) await main();
+await runTaskMain(import.meta, main);

package/tasks/python-node-runtime-watch.ts

@@ -2,8 +2,10 @@
 /** Keep the one package-owned PythonMonkey shim runtime current. */
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { parseArgs } from "node:util";
 import { log } from "@dbx-tools/shared-core";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions } from "./cli.ts";
+import { TaskProjectOptionSchema } from "./options.ts";
 import { runTaskCommand } from "../src/_task-command.ts";
 import { repoRoot } from "../src/packages.ts";
 import { watchLoop } from "../src/watch.ts";
@@ -12,13 +14,12 @@ import { withWorkspaceMutationLock } from "../src/workspace-lock.ts";
 const logger = log.logger("projen:python-node-runtime-watch");
 
 export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
-  const { values } = parseArgs({
+  const schema = z.object({ project: TaskProjectOptionSchema });
+  const { project } = await taskOptions(
+    taskCommand(import.meta.url, "Watch and rebuild the shared Python Node runtime", schema),
+    schema,
     args,
-    options: { project: { type: "string" } },
-    strict: true,
-  });
-  const project = values.project?.trim();
-  if (!project) throw new Error("--project is required");
+  );
 
   const projectDirectory = resolve(repoRoot, project);
   const buildScript = resolve(projectDirectory, "build-runtime.ts");
@@ -37,4 +38,4 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   });
 }
 
-if (import.meta.main) await main();
+await runTaskMain(import.meta, main);

package/tasks/python-sync.ts

@@ -23,6 +23,13 @@ import { basename, dirname, join, resolve } from "node:path";
 import * as exec from "@dbx-tools/core/exec";
 import { withFileLock } from "@dbx-tools/core/file-lock";
 import { parse } from "smol-toml";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions } from "./cli.ts";
+import {
+  TaskCheckOptionSchema,
+  TaskForceOptionSchema,
+  TaskProjectOptionSchema,
+} from "./options.ts";
 import { PYTHON_GENERATED_PACKAGE, PYTHON_SYNC_PACKAGE } from "../src/generated.ts";
 
 /** AST rewriter that points absolute imports of synchronized modules at their generated package. */
@@ -50,13 +57,17 @@ interface ParsedSource {
 }
 
 export async function main(args: readonly string[] = process.argv.slice(2)): Promise<void> {
-  const projectIndex = args.indexOf("--project");
-  if (projectIndex < 0 || !args[projectIndex + 1]) {
-    throw new Error("python-sync requires --project <directory>");
-  }
-  const project = resolve(args[projectIndex + 1]!);
-  const force = args.includes("--force");
-  const check = args.includes("--check");
+  const schema = z.object({
+    project: TaskProjectOptionSchema,
+    force: TaskForceOptionSchema,
+    check: TaskCheckOptionSchema,
+  });
+  const options = await taskOptions(
+    taskCommand(import.meta.url, "Synchronize pinned Git sources into Python packages", schema),
+    schema,
+    args,
+  );
+  const project = resolve(options.project);
   const pyproject = parse(readFileSync(join(project, "pyproject.toml"), "utf8")) as {
     tool?: {
       uv?: { "build-backend"?: { "module-name"?: string; "module-root"?: string } };
@@ -73,7 +84,7 @@ export async function main(args: readonly string[] = process.argv.slice(2)): Pro
   const generatedPackage = [moduleName, PYTHON_GENERATED_PACKAGE, PYTHON_SYNC_PACKAGE].join(".");
   const generatedRoot = join(moduleRoot, ...generatedPackage.split("."));
   for (const config of configs) {
-    await synchronize(config, generatedRoot, generatedPackage, { check, force });
+    await synchronize(config, generatedRoot, generatedPackage, options);
   }
 }
 
@@ -327,4 +338,4 @@ function makeReadonly(path: string): void {
   }
 }
 
-if (import.meta.main) await main();
+await runTaskMain(import.meta, main);

package/tasks/release-options.ts

@@ -1,18 +1,27 @@
 #!/usr/bin/env -S bun
 /** Export the current annotated release tag's step selection to GitHub Actions. */
 import { appendFileSync } from "node:fs";
-import { parseArgs } from "node:util";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions } from "./cli.ts";
 import { captureTaskCommand } from "../src/_task-command.ts";
 import { parseReleaseTagAnnotation } from "../src/release-options.ts";
 
+export const ReleaseOptionsTaskSchema = z.object({
+  tag: z.string().trim().min(1).describe("Annotated release tag"),
+  output: z.string().trim().min(1).describe("GitHub Actions output file"),
+});
+
 /** Verify and export a tag policy using the shared annotated-tag contract. */
-export function main(args: string[] = process.argv.slice(2)): void {
-  const { values } = parseArgs({
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  const values = await taskOptions(
+    taskCommand(
+      import.meta.url,
+      "Export release tag selections to GitHub Actions",
+      ReleaseOptionsTaskSchema,
+    ),
+    ReleaseOptionsTaskSchema,
     args,
-    options: { tag: { type: "string" }, output: { type: "string" } },
-    strict: true,
-  });
-  if (!values.tag || !values.output) throw new Error("--tag and --output are required");
+  );
   const annotation = captureTaskCommand(
     process.cwd(),
     "git",
@@ -29,4 +38,4 @@ export function main(args: string[] = process.argv.slice(2)): void {
   );
 }
 
-if (import.meta.main) main();
+await runTaskMain(import.meta, main);

package/tasks/release-version.ts

@@ -1,11 +1,20 @@
 #!/usr/bin/env -S bun
 /** Validate one stable release version against the canonical workspace policy. */
 import { resolve } from "node:path";
-import { parseArgs } from "node:util";
 import * as projectUtils from "@dbx-tools/core/project-utils";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions } from "./cli.ts";
+import { TaskRootOptionSchema } from "./options.ts";
 import { captureTaskCommand } from "../src/_task-command.ts";
 import { compareSemver, parseSemver, type Semver } from "../src/workspace-version.ts";
 
+export const ReleaseVersionOptionsSchema = z.object({
+  version: z.string().trim().min(1).describe("Release version to validate"),
+  root: TaskRootOptionSchema,
+  prefix: z.array(z.string().trim().min(1)).default([]).describe("Allowed release tag prefix"),
+  assertNext: z.boolean().default(false).describe("Require a version newer than published tags"),
+});
+
 function publishedVersion(root: string, prefixes: readonly string[]): string | undefined {
   let best: Semver | undefined;
   for (const prefix of prefixes) {
@@ -46,23 +55,21 @@ export function assertReleaseVersion(
   }
 }
 
-export function main(args: string[] = process.argv.slice(2)): void {
-  const { values } = parseArgs({
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  const values = await taskOptions(
+    taskCommand(
+      import.meta.url,
+      "Validate a stable workspace release version",
+      ReleaseVersionOptionsSchema,
+    ),
+    ReleaseVersionOptionsSchema,
     args,
-    options: {
-      version: { type: "string" },
-      root: { type: "string" },
-      prefix: { type: "string", multiple: true },
-      "assert-next": { type: "boolean", default: false },
-    },
-    strict: true,
-  });
-  if (!values.version) throw new Error("--version is required");
+  );
   assertReleaseVersion(values.version, {
     ...(values.root ? { root: values.root } : {}),
-    ...(values.prefix ? { prefixes: values.prefix } : {}),
-    assertNext: values["assert-next"],
+    ...(values.prefix.length ? { prefixes: values.prefix } : {}),
+    assertNext: values.assertNext,
   });
 }
 
-if (import.meta.main) main();
+await runTaskMain(import.meta, main);