@dbx-tools/projen 0.9.119 → 0.9.120

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.119";
+export const PACKAGE_VERSION = "0.9.120";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -41,7 +41,7 @@ export { BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE, BUN_APP_OVERRIDES, RootBunfigFile
 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 { DEV_WATCH_TASK, DEV_WATCH_SCRIPT, DEV_RESTART_DEBOUNCE_MS, DEV_RESTART_KEY, SERVER_WATCH_DISABLED_ENV } from "./src/dev-watch.ts";
+export { DEV_WATCH_TASK, DEV_WATCH_SCRIPT, DEV_RESTART_DEBOUNCE_MS, DEV_RESTART_KEY } from "./src/dev-watch.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";

package/package.json

@@ -30,10 +30,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/cli-args": "^0.9.119",
-    "@dbx-tools/core": "^0.9.119",
-    "@dbx-tools/path": "^0.9.119",
-    "@dbx-tools/shared-core": "^0.9.119",
+    "@dbx-tools/cli-args": "^0.9.120",
+    "@dbx-tools/core": "^0.9.120",
+    "@dbx-tools/path": "^0.9.120",
+    "@dbx-tools/shared-core": "^0.9.120",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -55,7 +55,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.119",
+  "version": "0.9.120",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/barrels.ts

@@ -339,14 +339,14 @@ export function isGeneratedBarrel(file: string): boolean {
 
 /** Public direct modules and child-directory facades for one generated barrel. */
 function barrelCandidates(barrelDir: string): string[] {
-  const files = [...find.findFiles("*", { cwd: barrelDir })]
+  const files = [...find.findFilesSync("*", { cwd: barrelDir })]
     .map(toPosix)
     .filter((file) => !file.includes("/"))
     .filter((file) => file !== "index.ts" && file !== CUSTOM_EXPORTS_FILE)
     .filter((file) => isModuleFile(file))
     .filter((file) => !isExcluded(file, barrelDir))
     .filter((file) => hasExport(join(barrelDir, file)));
-  const childIndexes = [...find.findFiles("*/index.ts", { cwd: barrelDir })]
+  const childIndexes = [...find.findFilesSync("*/index.ts", { cwd: barrelDir })]
     .map(toPosix)
     .filter((file) => file.split("/").length === 2)
     .filter((file) => !isExcluded(file, barrelDir))
@@ -424,7 +424,7 @@ function generateForPackage(pkgDir: string): number {
   const srcDir = join(pkgDir, "src");
   if (!existsSync(srcDir)) return 0;
 
-  const sourceFiles = [...find.findFiles("**/*", { cwd: srcDir })]
+  const sourceFiles = [...find.findFilesSync("**/*", { cwd: srcDir })]
     .map(toPosix)
     .filter((file) => isModuleFile(file) || /(^|\/)index\.ts$/.test(file));
   const manifest = json.parseRecord(readFileSync(join(pkgDir, "package.json"), "utf8"));

package/src/clean.ts

@@ -37,9 +37,9 @@ const CLEAN_SKIP_FILES: ReadonlySet<string> = new Set([".gitignore"]);
  * ignores AND every dot-prefixed folder (`.projen`, `.vscode`, `.github`, ...), and
  * {@link CLEAN_SKIP_FILES} entry (`.gitignore`).
  */
-function nativeGeneratedFiles(root: string): string[] {
+async function nativeGeneratedFiles(root: string): Promise<string[]> {
   const files = new Set<string>();
-  for (const manifestPath of find.findFiles("**/.projen/files.json", {
+  for await (const manifestPath of find.findFiles("**/.projen/files.json", {
     cwd: root,
     ignoreOptions: { dot: false },
   })) {
@@ -54,12 +54,14 @@ function nativeGeneratedFiles(root: string): string[] {
   return [...files];
 }
 
-export function listGeneratedFiles(root: string = resolveRepoRoot()): string[] {
+export async function listGeneratedFiles(root: string = resolveRepoRoot()): Promise<string[]> {
   const rel = (f: string): string => toPosix(relative(root, f));
-  const custom = [...find.findFiles("**/*", { cwd: root })]
-    .map((f) => join(root, f))
-    .filter(isGenerated);
-  return [...new Set([...nativeGeneratedFiles(root), ...custom])]
+  const custom: string[] = [];
+  for await (const file of find.findFiles("**/*", { cwd: root })) {
+    const absolute = join(root, file);
+    if (isGenerated(absolute)) custom.push(absolute);
+  }
+  return [...new Set([...(await nativeGeneratedFiles(root)), ...custom])]
     .filter(existsSync)
     .filter(
       (file) =>
@@ -79,12 +81,17 @@ export function listGeneratedFiles(root: string = resolveRepoRoot()): string[] {
  * own - removing the top-level dir takes it along. Other vendor/build/VCS dirs are
  * skipped for speed.
  */
-export function listNodeModulesDirs(root: string = resolveRepoRoot()): string[] {
+export async function listNodeModulesDirs(root: string = resolveRepoRoot()): Promise<string[]> {
   if (!existsSync(root)) return [];
   const rel = (f: string): string => toPosix(relative(root, f));
-  return [...find.findFiles("**/node_modules", { cwd: root, ignoreOptions: { dot: false } })]
-    .map((match) => join(root, match))
-    .sort((a, b) => rel(a).localeCompare(rel(b)));
+  const directories: string[] = [];
+  for await (const match of find.findFiles("**/node_modules", {
+    cwd: root,
+    ignoreOptions: { dot: false },
+  })) {
+    directories.push(join(root, match));
+  }
+  return directories.sort((a, b) => rel(a).localeCompare(rel(b)));
 }
 
 /**

package/src/dev-watch.ts

@@ -8,8 +8,3 @@ export const DEV_WATCH_SCRIPT = "dev-watch.ts";
 export const DEV_RESTART_DEBOUNCE_MS = 15_000;
 /** Interactive key that requests an immediate restart. */
 export const DEV_RESTART_KEY = "r";
-/**
- * Process environment that skips wrapping or running the file watcher.
- * Parsed with `configUtils.boolean` (`1` / `true` / `yes` disable watch).
- */
-export const SERVER_WATCH_DISABLED_ENV = "SERVER_WATCH_DISABLED";

package/src/packages.ts

@@ -174,7 +174,7 @@ function packageOfMember(projectRoot: string, member: string): DiscoveredPackage
 }
 
 /**
- * Package dirs under `rootAbs`, found with a single `find.findFiles` scan from
+ * Package dirs under `rootAbs`, found with a single `find.findFilesSync` scan from
  * `@dbx-tools/path` for module files beneath any `src/`. A package is the
  * folder that OWNS the `src/` - the segments before the FIRST `src/` - so a package's
  * own subfolders never become nested packages (outermost wins). Barrels/tests/decls
@@ -184,7 +184,7 @@ function packageOfMember(projectRoot: string, member: string): DiscoveredPackage
  */
 function collectPackageDirs(rootAbs: string): string[] {
   const owners = new Set<string>();
-  for (const file of find.findFiles(SRC_MODULE_GLOB, { cwd: rootAbs })) {
+  for (const file of find.findFilesSync(SRC_MODULE_GLOB, { cwd: rootAbs })) {
     if (!isModuleFile(file)) continue;
     const segs = toPosix(file).split("/");
     const srcIdx = segs.indexOf("src");

package/src/python-node-bindings.ts

@@ -328,7 +328,7 @@ export function resolveAllPythonNodeBindings(
 export function pythonNodeBindingProjects(projectRoot: string): string[] {
   return [
     ...find
-      .findFiles("**/pyproject.toml", { cwd: projectRoot })
+      .findFilesSync("**/pyproject.toml", { cwd: projectRoot })
       .filter((file) => {
         const manifest = parse(readFileSync(resolve(projectRoot, file), "utf8")) as {
           tool?: { dbx_tools?: { node_bindings?: unknown } };

package/src/shared-core-usage.ts

@@ -6,7 +6,7 @@
  * unused exports and duplicated owned helpers.
  */
 import { readFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { find } from "@dbx-tools/path";
 import * as core from "@dbx-tools/shared-core";
 import { PACKAGE_IDENTIFIER, object } from "@dbx-tools/shared-core";
@@ -59,7 +59,7 @@ function namespaceMap(coreDir: string): Readonly<Record<string, string>> {
   );
 }
 
-function sourceFiles(root: string, includeGenerated: boolean): string[] {
+async function sourceFiles(root: string, includeGenerated: boolean): Promise<string[]> {
   const ignore = [
     "**/node_modules/**",
     "**/lib/**",
@@ -69,7 +69,11 @@ function sourceFiles(root: string, includeGenerated: boolean): string[] {
     "**/_runtime.js",
   ];
   if (!includeGenerated) ignore.push(`**/${PYTHON_GENERATED_PACKAGE}/**`);
-  return [...find.findFiles(SOURCE_PATTERN, { cwd: root, ignore })].sort();
+  const files: string[] = [];
+  for await (const file of find.findFiles(SOURCE_PATTERN, { cwd: root, ignore })) {
+    files.push(resolve(root, file));
+  }
+  return files.sort();
 }
 
 function classifyFile(
@@ -114,11 +118,13 @@ function mentionsExport(
 }
 
 /** Classify every namespace runtime export against repository callers. */
-export function sharedCoreExportUsage(root: string = repoRoot): SharedCoreExportUsage[] {
+export async function sharedCoreExportUsage(
+  root: string = repoRoot,
+): Promise<SharedCoreExportUsage[]> {
   const coreDir = sharedCorePackageDir(root);
   const coreDirRel = relative(root, coreDir);
   const namespaces = namespaceMap(coreDir);
-  const files = sourceFiles(root, true).map((file) => ({
+  const files = (await sourceFiles(root, true)).map((file) => ({
     path: relative(root, file),
     text: readFileSync(file, "utf8"),
   }));
@@ -152,9 +158,9 @@ export function sharedCoreExportUsage(root: string = repoRoot): SharedCoreExport
 }
 
 /** Local copies of helpers owned by shared-core. */
-export function duplicatedOwnedHelpers(root: string = repoRoot): string[] {
+export async function duplicatedOwnedHelpers(root: string = repoRoot): Promise<string[]> {
   const duplicates: string[] = [];
-  for (const file of sourceFiles(root, false)) {
+  for (const file of await sourceFiles(root, false)) {
     const relativePath = relative(root, file);
     if (OWNED_HELPER_FILES.has(relativePath)) continue;
     if (relativePath.startsWith("packages/js/shared/core/test/")) continue;

package/src/watch.ts

@@ -17,7 +17,7 @@
  */
 import { isAbsolute, resolve } from "node:path";
 import { watch as pathWatch } from "@dbx-tools/path";
-import { asyncUtils, log } from "@dbx-tools/shared-core";
+import { asyncUtils, errorUtils, log } from "@dbx-tools/shared-core";
 import { isGeneratedFile, recordedRoots, repoRoot } from "./packages.ts";
 import { withWorkspaceMutationLock } from "./workspace-lock.ts";
 
@@ -90,12 +90,12 @@ export interface WatchLoopOptions {
   check?: (changed: string[]) => boolean | Promise<boolean>;
 }
 
-export function watchLoop(
+export async function watchLoop(
   tag: string,
   paths: string[],
   onBatch: (changed: string[]) => void | Promise<void>,
   config: WatchLoopOptions = {},
-): void {
+): Promise<void> {
   const { ignoreOptions, check } = config;
   const pending = new Set<string>();
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -119,7 +119,7 @@ export function watchLoop(
         });
       }
     } catch (err) {
-      logger.error(`${tag} cycle failed:`, err instanceof Error ? err.message : err);
+      logger.error(`${tag} cycle failed`, { error: errorUtils.toError(err) });
     } finally {
       running = false;
       if (rerun) {
@@ -129,7 +129,7 @@ export function watchLoop(
     }
   }
 
-  const watcher = pathWatch.watchFiles(paths, {
+  const watcher = await pathWatch.watchFiles(paths, {
     cwd: repoRoot,
     ignoreInitial: true,
     ignore: (path) => ignoredPath(path),
@@ -156,7 +156,7 @@ export function watchLoop(
     timer = setTimeout(() => void flush(), DEBOUNCE_MS);
   });
   watcher.on("error", (err) => {
-    logger.error(`${tag} watcher error:`, err);
+    logger.error(`${tag} watcher error`, { error: errorUtils.toError(err) });
     const code = (err as NodeJS.ErrnoException | undefined)?.code;
     if (code === undefined || !FATAL_WATCH_ERROR_CODES.has(code)) return;
     logger.error(`${tag}: ${code} leaves the watcher blind - exiting so it is restarted`);

package/tasks/barrels.ts

@@ -57,7 +57,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     // Watch the package roots; a source edit inside a package rebuilds just that
     // package's `index.ts` barrel (no re-synth - the projenrc watcher owns that).
     // watchLoop already drops generated paths, so a barrel write never re-triggers us.
-    watchLoop(
+    await watchLoop(
       "barrels",
       watchRoots(),
       (changed) => {

package/tasks/clean.ts

@@ -27,8 +27,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     args,
   );
 
-  const files = listGeneratedFiles();
-  const nodeModules = listNodeModulesDirs();
+  const [files, nodeModules] = await Promise.all([listGeneratedFiles(), listNodeModulesDirs()]);
   const targets = [...files, ...nodeModules];
 
   if (targets.length === 0) {

package/tasks/compile-workspace.ts

@@ -4,7 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { join, resolve } from "node:path";
 import * as exec from "@dbx-tools/core/exec";
-import { log } from "@dbx-tools/shared-core";
+import { errorUtils, log } from "@dbx-tools/shared-core";
 import { runTaskMain } from "./cli.ts";
 
 const logger = log.logger("projen:compile");
@@ -116,7 +116,9 @@ export async function main(): Promise<void> {
   let failed = false;
   for (const [index, result] of results.entries()) {
     if (result.status === "rejected") {
-      logger.error(`${jobs[index]!.name} compile failed:`, result.reason);
+      logger.error(`${jobs[index]!.name} compile failed`, {
+        error: errorUtils.toError(result.reason),
+      });
       failed = true;
     } else if (result.value.exitCode !== 0) {
       logger.error(`${jobs[index]!.name} compile exited with ${result.value.exitCode}`);

package/tasks/dev-watch.ts

@@ -1,18 +1,14 @@
 #!/usr/bin/env -S bun
 /** Restart a development command after relevant workspace changes settle. */
 import { isAbsolute, relative, resolve } from "node:path";
+import { serializeArgs } from "@dbx-tools/cli-args";
 import * as exec from "@dbx-tools/core/exec";
 import { watch as pathWatch } from "@dbx-tools/path";
-import { log } from "@dbx-tools/shared-core";
+import { asyncUtils, errorUtils, log } from "@dbx-tools/shared-core";
 import { CommanderError } from "commander";
 import { z } from "zod";
 import { parsedTaskOptions, runTaskMain, taskCommand, taskPositionals } from "./cli.ts";
-import {
-  DEV_RESTART_DEBOUNCE_MS,
-  DEV_RESTART_KEY,
-  DEV_WATCH_TASK,
-  SERVER_WATCH_DISABLED_ENV,
-} from "../src/dev-watch.ts";
+import { DEV_RESTART_DEBOUNCE_MS, DEV_RESTART_KEY, DEV_WATCH_TASK } from "../src/dev-watch.ts";
 import {
   readPackageManifest,
   recordedPackages,
@@ -23,33 +19,41 @@ import {
 const logger = log.logger("projen:dev-watch");
 const SHUTDOWN_TIMEOUT_MS = 2_000;
 
-export interface DevWatchOptions {
-  readonly command: readonly string[];
-  readonly debounceMs: number;
-  readonly restartKey: string;
-  /** When true, run the command once and skip file-change restarts. */
-  readonly serverWatchDisabled: boolean;
-}
-
 export const DevWatchOptionsSchema = z.object({
   debounceMs: z.coerce
     .number()
     .int()
     .nonnegative("Debounce must be a non-negative number of milliseconds")
     .default(DEV_RESTART_DEBOUNCE_MS)
-    .describe("Quiet period before restarting the command"),
+    .describe("Quiet period before restarting the command")
+    .meta({ short: false }),
   restartKey: z
     .string()
     .refine((value) => Array.from(value).length === 1, "Restart key must be exactly one character")
     .default(DEV_RESTART_KEY)
     .describe("Interactive immediate-restart key"),
-  serverWatchDisabled: z
+  watchDisable: z
     .boolean()
     .default(false)
-    .describe("Run the command once without watching")
-    .meta({ env: SERVER_WATCH_DISABLED_ENV }),
+    .describe("Run the command once without watching files or restarting on changes")
+    .meta({ env: "DEV_WATCH_DISABLE", short: "d" }),
+  watchInclude: z
+    .array(z.string())
+    .default([])
+    .describe("Glob patterns to watch; replaces the default workspace-package directories")
+    .meta({ env: "DEV_WATCH_INCLUDE", short: "i" }),
+  watchExclude: z
+    .array(z.string())
+    .default([])
+    .describe("Glob patterns to ignore after the include set is chosen")
+    .meta({ env: "DEV_WATCH_EXCLUDE", short: "e" }),
 });
 
+/** Parsed watcher flags plus the pass-through command argv. */
+export type DevWatchOptions = z.output<typeof DevWatchOptionsSchema> & {
+  readonly command: readonly string[];
+};
+
 interface WorkspacePackage {
   readonly dir: string;
   readonly name?: string;
@@ -76,15 +80,50 @@ export function parseDevWatchOptions(args: readonly string[]): DevWatchOptions {
     .parse([...args], { from: "user" });
   const options = parsedTaskOptions(program, DevWatchOptionsSchema);
   const [command, commandArgs = []] = taskPositionals(program) as [string, string[]?];
-  if (options.serverWatchDisabled) process.env[SERVER_WATCH_DISABLED_ENV] = "1";
   return {
+    ...options,
     command: [command, ...commandArgs],
-    debounceMs: options.debounceMs,
-    restartKey: options.restartKey,
-    serverWatchDisabled: options.serverWatchDisabled,
   };
 }
 
+/** Watcher flags the root demo may forward into a nested `dev:watch`. */
+export type DevWatchForwardOptions = Pick<
+  DevWatchOptions,
+  "watchDisable" | "watchInclude" | "watchExclude"
+>;
+
+/**
+ * Parse `--watch-disable` / `--watch-include` / `--watch-exclude` from argv that
+ * may contain unrelated tokens (the root demo forwards only these flags).
+ */
+export function parseWatchGlobOptions(args: readonly string[]): DevWatchForwardOptions {
+  const program = taskCommand(
+    import.meta.url,
+    "Restart a development command after watched changes settle",
+    DevWatchOptionsSchema,
+  )
+    .name(DEV_WATCH_TASK)
+    .exitOverride()
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .parse([...args], { from: "user" });
+  const options = parsedTaskOptions(program, DevWatchOptionsSchema);
+  return {
+    watchDisable: options.watchDisable,
+    watchInclude: options.watchInclude,
+    watchExclude: options.watchExclude,
+  };
+}
+
+/** Serialize forwarded watcher flags for a nested `dev:watch`. */
+export function serializedWatchGlobArgs(options: DevWatchForwardOptions): string[] {
+  return serializeArgs({
+    ...(options.watchDisable ? { watchDisable: true } : {}),
+    watchInclude: options.watchInclude,
+    watchExclude: options.watchExclude,
+  });
+}
+
 function containsPath(parent: string, candidate: string): boolean {
   const rel = relative(parent, candidate);
   return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
@@ -156,6 +195,23 @@ export function devWatchDirectories(
   return dependencies.length > 0 ? dependencies : [owner.dir];
 }
 
+/**
+ * Choose watch paths for {@link pathWatch.watchFiles}.
+ * Default workspace-package directories apply until `--watch-include` is set;
+ * `--watch-exclude` is always passed through as ignore globs.
+ */
+export function devWatchTargets(
+  command: readonly string[],
+  cwd: string,
+  include: readonly string[] = [],
+  exclude: readonly string[] = [],
+): { paths: readonly string[]; ignore: readonly string[] } {
+  return {
+    paths: include.length > 0 ? [...include] : devWatchDirectories(command, cwd),
+    ignore: [...exclude],
+  };
+}
+
 /** Compare one raw terminal character with the configured restart key. */
 export function isRestartKey(key: string, restartKey: string): boolean {
   return key === restartKey || key.toLocaleLowerCase() === restartKey.toLocaleLowerCase();
@@ -172,12 +228,13 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     return;
   }
   const cwd = process.cwd();
-  if (options.serverWatchDisabled) {
-    logger.info(`${SERVER_WATCH_DISABLED_ENV} is set; running without file watching`);
+  const commandLabel = options.command.map((part) => JSON.stringify(part)).join(" ");
+  if (options.watchDisable) {
+    logger.info(`watch disabled; running ${commandLabel}`);
     const [command, ...commandArgs] = options.command;
     const { exitCode } = await exec.spawn(command!, commandArgs, {
       cwd,
-      stdin: "ignore",
+      stdin: "inherit",
       stdout: "inherit",
       stderr: "inherit",
       check: false,
@@ -187,19 +244,37 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   }
 
   const root = resolveRepoRoot(cwd);
-  const watchDirectories = devWatchDirectories(options.command, cwd);
-  const commandLabel = options.command.map((part) => JSON.stringify(part)).join(" ");
+  const { paths: watchPaths, ignore: watchIgnore } = devWatchTargets(
+    options.command,
+    cwd,
+    options.watchInclude,
+    options.watchExclude,
+  );
   let child: exec.ChildProcessResult | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let restartReason: string | undefined;
   let restarting = false;
   let stopping = false;
 
-  const watcher = pathWatch.watchFiles(watchDirectories, {
+  const watcher = await pathWatch.watchFiles([...watchPaths], {
     cwd: root,
+    ignore: watchIgnore.length > 0 ? [...watchIgnore] : undefined,
     ignoreInitial: true,
+    ignoreOptions: {
+      git: true,
+    },
   });
 
+  function interruptChild(): void {
+    const current = child;
+    if (!current?.pid) return;
+    try {
+      current.kill("SIGINT");
+    } catch {
+      // The command already exited.
+    }
+  }
+
   async function stopChild(): Promise<void> {
     const current = child;
     if (!current) return;
@@ -210,7 +285,9 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
         forceTimeoutMs: SHUTDOWN_TIMEOUT_MS,
       });
     } catch (err) {
-      logger.error("failed to stop command process tree:", err);
+      logger.error("failed to stop command process tree", {
+        error: errorUtils.toError(err),
+      });
     }
   }
 
@@ -236,7 +313,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       .catch((err) => {
         if (child !== current || stopping) return;
         child = undefined;
-        logger.error("command failed:", err);
+        logger.error("command failed", { error: errorUtils.toError(err) });
       });
   }
 
@@ -269,11 +346,12 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   }
 
   watcher.on("all", scheduleRestart);
-  watcher.on("error", (err) => logger.error("watcher error:", err));
+  watcher.on("error", (err) => logger.error("watcher error", { error: errorUtils.toError(err) }));
   watcher.on("ready", () => {
-    const packages = watchDirectories.length;
+    const count = watchPaths.length;
+    const source = options.watchInclude.length > 0 ? "include glob" : "workspace directory";
     logger.info(
-      `watching ${packages} workspace ${packages === 1 ? "directory" : "directories"} with ${options.debounceMs}ms restart debounce`,
+      `watching ${count} ${source}${count === 1 ? "" : "s"} with ${options.debounceMs}ms restart debounce`,
     );
     logger.info(`press ${JSON.stringify(options.restartKey)} to restart; Ctrl-C to stop`);
   });
@@ -292,33 +370,37 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       }
     }
   };
+
+  function restoreStdin(): void {
+    stdin.off("data", onInput);
+    if (stdin.isTTY) stdin.setRawMode(wasRaw);
+    stdin.pause();
+  }
+
   if (stdin.isTTY) stdin.setRawMode(true);
   stdin.resume();
   stdin.on("data", onInput);
 
-  let finish!: () => void;
-  const complete = new Promise<void>((resolveComplete) => {
-    finish = resolveComplete;
-  });
-
-  async function shutdown(): Promise<void> {
-    if (stopping) return;
+  async function shutdown(exitCode = 0): Promise<void> {
+    if (stopping) process.exit(exitCode || 130);
     stopping = true;
     clearTimeout(timer);
     restartReason = undefined;
-    stdin.off("data", onInput);
-    if (stdin.isTTY) stdin.setRawMode(wasRaw);
-    stdin.pause();
-    await Promise.allSettled([watcher.close(), stopChild()]);
-    finish();
+    restoreStdin();
+    interruptChild();
+    await Promise.race([
+      Promise.allSettled([watcher.close(), stopChild()]),
+      asyncUtils.sleep(SHUTDOWN_TIMEOUT_MS),
+    ]);
+    process.exit(exitCode);
   }
 
   for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-    process.once(signal, () => void shutdown());
+    process.on(signal, () => void shutdown());
   }
 
   requestRestart("initial start");
-  await complete;
+  await new Promise<void>(() => {});
 }
 
 await runTaskMain(import.meta, main);

package/tasks/projenrc.ts

@@ -26,8 +26,8 @@ function resynthWatchPaths(): string[] {
 // makes the watch intelligent vs stock `projen --watch`, which re-synths on any tree
 // change. `{ dot: false }` keeps the default dotfile ignore group from pruning dotfile
 // targets. (A one-shot "projenrc" is just a synth, i.e. `bun run default`.)
-export function main(): void {
-  watchLoop(
+export async function main(): Promise<void> {
+  await watchLoop(
     "projenrc",
     resynthWatchPaths(),
     () => {

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

@@ -63,7 +63,7 @@ export async function main(): Promise<void> {
   await withWorkspaceMutationLock(repoRoot, () => generatePythonNodeBindings(repoRoot));
   logger.success("generated all Python Node bindings");
 
-  watchLoop(
+  await watchLoop(
     "python-node-bindings",
     watchPaths(configs),
     (changed) => {

package/tasks/python-node-bindings.ts

@@ -690,7 +690,8 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     path: string,
     preferredName?: string,
   ): PythonRecord | undefined {
-    if (!(type.flags & ts.TypeFlags.Object)) return undefined;
+    // Named intersections (`Omit<...> & { nested?: Named }`) are records.
+    if (!(type.flags & ts.TypeFlags.Object) && !type.isIntersection()) return undefined;
     if (checker.isArrayType(type) || type.getCallSignatures().length > 0) return undefined;
     if (checker.getIndexTypeOfType(type, ts.IndexKind.String)) return undefined;
     const symbolName = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName();

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

@@ -32,7 +32,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   await withWorkspaceMutationLock(repoRoot, build);
   logger.success("built shared Python Node runtime");
 
-  watchLoop("python-node-runtime", [buildScript, shimDirectory], () => {
+  await watchLoop("python-node-runtime", [buildScript, shimDirectory], () => {
     build();
     logger.success("rebuilt shared Python Node runtime");
   });

package/tasks/release.ts

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import * as projectUtils from "@dbx-tools/core/project-utils";
-import { log } from "@dbx-tools/shared-core";
+import { errorUtils, log } from "@dbx-tools/shared-core";
 import type { Command } from "commander";
 import { z } from "zod";
 import { parsedTaskOptions, runTaskMain, taskCommand } from "./cli.ts";
@@ -149,7 +149,7 @@ function pushAnnotatedReleaseTag(options: {
   } catch (error) {
     if (remoteRefCreated) throw error;
     logger.warn("GitHub API tag creation failed; using git push", {
-      error,
+      error: errorUtils.toError(error),
       repository: githubAccount.remote.repository,
     });
     runTaskCommand(root, "git", ["push", remote, `refs/tags/${tag}`]);

package/tasks/shared-core-usage.ts

@@ -3,8 +3,8 @@
 import { runTaskMain } from "./cli.ts";
 import { formatSharedCoreUsage, sharedCoreExportUsage } from "../src/shared-core-usage.ts";
 
-export function main(): void {
-  process.stdout.write(formatSharedCoreUsage(sharedCoreExportUsage()));
+export async function main(): Promise<void> {
+  process.stdout.write(formatSharedCoreUsage(await sharedCoreExportUsage()));
 }
 
 await runTaskMain(import.meta, main);

package/tasks/sync.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S bun
 /** Synthesize once or supervise Projen, barrels, and registered focused watchers. */
 import { fileURLToPath } from "node:url";
-import { log } from "@dbx-tools/shared-core";
+import { errorUtils, log } from "@dbx-tools/shared-core";
 import concurrently from "concurrently";
 import { z } from "zod";
 import { runTaskMain, taskCommand, taskOptions } from "./cli.ts";
@@ -84,10 +84,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     } catch (err) {
       // A tree that doesn't synth is precisely when the watcher is most useful: the edit
       // that repairs it is the one the projenrc watcher is sitting there waiting for.
-      logger.error(
-        "initial sync failed - watching anyway:",
-        err instanceof Error ? err.message : err,
-      );
+      logger.error("initial sync failed - watching anyway", { error: errorUtils.toError(err) });
     }
 
     const watchers = [

package/tasks/version-check.ts

@@ -24,7 +24,7 @@ function pythonVersion(path: string): string | undefined {
   return typeof manifest.project?.version === "string" ? manifest.project.version : undefined;
 }
 
-export function main(): void {
+export async function main(): Promise<void> {
   const root = projectUtils.root() ?? process.cwd();
   const version = readWorkspaceVersion(root);
   const mismatches: string[] = [];
@@ -37,7 +37,7 @@ export function main(): void {
     check(`${pkg.path}/package.json`, manifestVersion(join(pkg.dir, "package.json")));
   }
 
-  for (const path of find.findFiles("**/pyproject.toml", { cwd: root })) {
+  for await (const path of find.findFiles("**/pyproject.toml", { cwd: root })) {
     check(path, pythonVersion(join(root, path)));
   }
   if (mismatches.length > 0) {