@dbx-tools/projen 0.9.79 → 0.9.95

package/README.md

@@ -308,6 +308,18 @@ Built-in tag mixins set runtime defaults for `shared`, `node`, `cli`, `server`,
 and `ui`. Repo-specific mixins layer package-specific dependencies,
 scripts, and generated files on top.
 
+Every workspace root exposes a generic development watcher:
+
+```sh
+bun run dev:watch [--debounce-ms 15000] [--restart-key r] <command> [args...]
+```
+
+It restarts after watched writes have been quiet for 15 seconds. Command paths,
+`--cwd`, and `--filter` identify the owning package; its transitive workspace
+dependencies are watched with the shared generated/dependency/test/temp ignores.
+Press the configured key for an immediate restart. The demo uses this task to
+run its concrete server entrypoint; the `server` tag does not assume one.
+
 AppKit 0.81's `appkitServerConfig()` is the preferred tsdown preset for a
 consumer app using conventional compiled `server/agents/*/agent.ts` entries. It
 does not replace this engine's package discovery, Bun browser build, source-run
@@ -488,11 +500,12 @@ bun run release --no-release-notes
 bun run release --release-notes-instructions "Focus on operator-visible changes."
 ```
 
-`--demo-deploy` is off by default. After tagging and any local registry
-publication it runs `bun run demo:deploy`, which stages the AppKit demo
-from locally compiled Node packages and locally built Python wheels, resolves
-the configured/default workspace profile through `@dbx-tools/auth`, and deploys
-it. That step is local only and is not recorded in the annotated tag.
+`--demo-deploy` is off by default and requires `--profile <name>`. After tagging
+and any local registry publication it runs `bun run demo:deploy`, which stages
+the AppKit demo from locally compiled Node packages and locally built Python
+wheels, resolves only the selected workspace profile through `@dbx-tools/auth`,
+force-refreshes its token with interactive login fallback, and deploys it. That
+step is local only and is not recorded in the annotated tag.
 
 After bump and configured validation, release writes
 `docs/releases/vX.Y.Z.md` with `dbx genie exec -C "$PWD" --sandbox read-only
@@ -579,6 +592,7 @@ release [options]
 | `--no-release-notes`                  | skip writing docs/releases notes (Genie and git-log fallback)                                 |
 | `--release-notes-instructions <text>` | append custom instructions to the Genie release-notes prompt                                  |
 | `--demo-deploy`                       | after tagging, stage and deploy the AppKit demo app (off by default)                          |
+| `--profile <name>`                    | Databricks CLI profile for --demo-deploy                                                      |
 | `--no-local-publish`                  | skip publishing to configured local registries                                                |
 | `--local-registry <auto\|false\|url>` | local npm registry selection (default: "auto")                                                |
 | `--local-pypi <auto\|false\|url>`     | local devpi registry selection (default: "auto")                                              |

package/index.ts

@@ -3,13 +3,14 @@
 // 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.79";
+export const PACKAGE_VERSION = "0.9.95";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
 export * as clean from "./src/clean.ts";
 export * as codegen from "./src/codegen.ts";
 export * as dbxToolsConfig from "./src/dbx-tools-config.ts";
+export * as devWatch from "./src/dev-watch.ts";
 export * as engineRoot from "./src/engine-root.ts";
 export * as generated from "./src/generated.ts";
 export * as mixin from "./src/mixin.ts";
@@ -40,6 +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 { 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,9 +30,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "^0.9.79",
-    "@dbx-tools/path": "^0.9.79",
-    "@dbx-tools/shared-core": "^0.9.79",
+    "@dbx-tools/core": "^0.9.95",
+    "@dbx-tools/path": "^0.9.95",
+    "@dbx-tools/shared-core": "^0.9.95",
     "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.79",
+  "version": "0.9.95",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/dev-watch.ts

@@ -0,0 +1,15 @@
+/** Root task and CLI defaults for the generic development command watcher. */
+
+/** Projen task exposed as `bun run dev:watch`. */
+export const DEV_WATCH_TASK = "dev:watch";
+/** Shipped task entrypoint invoked by {@link DEV_WATCH_TASK}. */
+export const DEV_WATCH_SCRIPT = "dev-watch.ts";
+/** Quiet period after the last watched change before restarting. */
+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/pnpm-workspace.ts

@@ -109,6 +109,7 @@ const DEFAULT_ALLOW_BUILDS: AllowBuilds = {
 const DEFAULT_OVERRIDES: Readonly<Record<string, string>> = {
   bun: BUN_VERSION,
   glob: "^13.0.0",
+  "p-map": "7.0.8",
 };
 
 /**

package/src/project-js.ts

@@ -21,6 +21,7 @@ import { BUN_APP_OVERRIDES, RootBunfigFile } from "./bun-app.ts";
 import { BUN_VERSION } from "./bun-workflow.ts";
 import { codegenModulePaths, generateCodegen } from "./codegen.ts";
 import { DBXToolsConfig, type DBXToolsConfigOptions } from "./dbx-tools-config.ts";
+import { DEV_WATCH_SCRIPT, DEV_WATCH_TASK } from "./dev-watch.ts";
 import { resolvePkgRoot } from "./engine-root.ts";
 import * as mixin from "./mixin.ts";
 import {
@@ -1070,6 +1071,11 @@ function resolveTags(p: DiscoveredPackage, tagPaths: Record<string, string[]>):
 function registerRootTasks(project: javascript.NodeProject): void {
   project.addTask("barrels", { execArgs: taskCommand("barrels.ts") });
   project.addTask("clean", { execArgs: taskCommand("clean.ts"), receiveArgs: true });
+  project.addTask(DEV_WATCH_TASK, {
+    description: "Restart a development command after watched changes settle",
+    execArgs: taskCommand(DEV_WATCH_SCRIPT),
+    receiveArgs: true,
+  });
   project.addTask("sync", {
     execArgs: taskCommand("sync.ts"),
     receiveArgs: true,

package/src/tags.ts

@@ -163,15 +163,11 @@ export const PACKAGE_TAG_MIXINS = {
     addPackageFiles(p, "bin");
   }),
   server: create(projectPredicate.hasTag("server"), (p) => {
-    // A Node/Express service. `dev` and `start` run `src/server.ts` directly
-    // through Bun, while package compilation remains native TypeScript.
+    // A Node/Express service. The root's generic `dev:watch` task owns watched
+    // execution because this tag cannot assume an entrypoint or command shape.
     p.addDeps("express@catalog:");
     p.addDevDeps("@types/node@catalog:", "@types/express@catalog:");
     applyCompilerOptions(p, NODE_COMPILER_OPTIONS);
-    // bun runs the server `.ts` directly (native TS, no tsx). `--watch` restarts
-    // on change - the tsx-watch replacement.
-    (p.tasks.tryFind("dev") ?? p.addTask("dev")).reset("bun --watch src/server.ts");
-    (p.tasks.tryFind("start") ?? p.addTask("start")).reset("bun src/server.ts");
   }),
   node: create(projectPredicate.hasTag("node"), (p) => {
     p.addDevDeps("@types/node@catalog:");

package/tasks/dev-watch.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env -S bun
+/** Restart a development command after relevant workspace changes settle. */
+import { isAbsolute, relative, resolve } from "node:path";
+import { configUtils } from "@dbx-tools/core";
+import * as exec from "@dbx-tools/core/exec";
+import { watch as pathWatch } from "@dbx-tools/path";
+import { log } from "@dbx-tools/shared-core";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
+import {
+  DEV_RESTART_DEBOUNCE_MS,
+  DEV_RESTART_KEY,
+  DEV_WATCH_TASK,
+  SERVER_WATCH_DISABLED_ENV,
+} from "../src/dev-watch.ts";
+import {
+  readPackageManifest,
+  recordedPackages,
+  resolveRepoRoot,
+  workspaceDependencyDirectories,
+} from "../src/packages.ts";
+
+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;
+}
+
+interface WorkspacePackage {
+  readonly dir: string;
+  readonly name?: string;
+}
+
+function debounceMilliseconds(value: string): number {
+  const parsed = configUtils.toNumber(value);
+  if (parsed === undefined || parsed < 0) {
+    throw new InvalidArgumentError("must be a non-negative number of milliseconds");
+  }
+  return parsed;
+}
+
+function singleKey(value: string): string {
+  if (Array.from(value).length !== 1) {
+    throw new InvalidArgumentError("must be exactly one character");
+  }
+  return value;
+}
+
+/** Parse watcher flags while passing every token after the command through unchanged. */
+export function parseDevWatchOptions(args: string[]): DevWatchOptions {
+  const program = new Command()
+    .name(DEV_WATCH_TASK)
+    .description("Restart a development command after watched changes settle")
+    .exitOverride()
+    .configureOutput({
+      writeErr: (message) => {
+        if (import.meta.main) process.stderr.write(message);
+      },
+    })
+    .enablePositionalOptions()
+    .passThroughOptions()
+    .addOption(
+      new Option("--debounce-ms <milliseconds>", "quiet period before restart")
+        .default(DEV_RESTART_DEBOUNCE_MS)
+        .argParser(debounceMilliseconds),
+    )
+    .addOption(
+      new Option("--restart-key <key>", "interactive immediate-restart key")
+        .default(DEV_RESTART_KEY)
+        .argParser(singleKey),
+    )
+    .addOption(
+      new Option(
+        "--server-watch-disabled",
+        `run the command once without watching (${SERVER_WATCH_DISABLED_ENV})`,
+      ),
+    )
+    .argument("<command>")
+    .argument("[args...]")
+    .parse(["bun", DEV_WATCH_TASK, ...args]);
+  const options = program.opts<{
+    debounceMs: number;
+    restartKey: string;
+    serverWatchDisabled?: boolean;
+  }>();
+  const [command, commandArgs = []] = program.processedArgs as [string, string[]?];
+  const serverWatchDisabled =
+    options.serverWatchDisabled === true ||
+    configUtils.boolean(undefined, SERVER_WATCH_DISABLED_ENV, configUtils.ENV_ONLY) === true;
+  if (serverWatchDisabled) process.env[SERVER_WATCH_DISABLED_ENV] = "1";
+  return {
+    command: [command, ...commandArgs],
+    debounceMs: options.debounceMs,
+    restartKey: options.restartKey,
+    serverWatchDisabled,
+  };
+}
+
+function containsPath(parent: string, candidate: string): boolean {
+  const rel = relative(parent, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function workspacePackages(root: string): WorkspacePackage[] {
+  return recordedPackages(root)
+    .map(({ dir }) => {
+      const name = readPackageManifest(dir)?.name;
+      return { dir, name: typeof name === "string" ? name : undefined };
+    })
+    .sort((left, right) => right.dir.length - left.dir.length);
+}
+
+function optionArgument(
+  command: readonly string[],
+  longName: string,
+  shortName?: string,
+): string | undefined {
+  for (let index = 0; index < command.length; index++) {
+    const token = command[index]!;
+    if (token === longName || (shortName !== undefined && token === shortName)) {
+      return command[index + 1];
+    }
+    if (token.startsWith(`${longName}=`)) return token.slice(longName.length + 1);
+    if (shortName !== undefined && token.startsWith(`${shortName}=`)) {
+      return token.slice(shortName.length + 1);
+    }
+  }
+  return undefined;
+}
+
+function commandWorkingDirectory(command: readonly string[], cwd: string): string {
+  const configured = optionArgument(command, "--cwd");
+  return configured ? resolve(cwd, configured) : cwd;
+}
+
+function commandPackage(
+  command: readonly string[],
+  cwd: string,
+  packages: readonly WorkspacePackage[],
+): WorkspacePackage | undefined {
+  const selected = optionArgument(command, "--filter", "-F");
+  if (selected) {
+    const filtered = packages.find(({ name }) => name === selected);
+    if (filtered) return filtered;
+  }
+
+  const commandCwd = commandWorkingDirectory(command, cwd);
+  for (const token of command) {
+    if (token.startsWith("-")) continue;
+    const candidate = resolve(commandCwd, token);
+    const owner = packages.find(({ dir }) => containsPath(dir, candidate));
+    if (owner) return owner;
+  }
+  return packages.find(({ dir }) => containsPath(dir, commandCwd));
+}
+
+/** Source directories most likely to affect the command, using workspace dependency metadata. */
+export function devWatchDirectories(
+  command: readonly string[],
+  cwd: string = process.cwd(),
+): string[] {
+  const root = resolveRepoRoot(cwd);
+  const packages = workspacePackages(root);
+  const owner = commandPackage(command, cwd, packages);
+  if (!owner) return [commandWorkingDirectory(command, cwd)];
+  const dependencies = owner.name ? workspaceDependencyDirectories(owner.name, root) : [];
+  return dependencies.length > 0 ? dependencies : [owner.dir];
+}
+
+/** 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();
+}
+
+/** Supervise one command until the user or host stops the task. */
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  let options: DevWatchOptions;
+  try {
+    options = parseDevWatchOptions(args);
+  } catch (err) {
+    if (!(err instanceof CommanderError)) throw err;
+    if (err.exitCode !== 0) process.exitCode = err.exitCode;
+    return;
+  }
+  const cwd = process.cwd();
+  if (options.serverWatchDisabled) {
+    logger.info(`${SERVER_WATCH_DISABLED_ENV} is set; running without file watching`);
+    const [command, ...commandArgs] = options.command;
+    const { exitCode } = await exec.spawn(command!, commandArgs, {
+      cwd,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+      check: false,
+    });
+    if (exitCode !== 0) process.exitCode = exitCode;
+    return;
+  }
+
+  const root = resolveRepoRoot(cwd);
+  const watchDirectories = devWatchDirectories(options.command, cwd);
+  const commandLabel = options.command.map((part) => JSON.stringify(part)).join(" ");
+  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, {
+    cwd: root,
+    ignoreInitial: true,
+  });
+
+  async function stopChild(): Promise<void> {
+    const current = child;
+    if (!current) return;
+    child = undefined;
+    try {
+      await exec.kill(current, {
+        gracefulTimeoutMs: SHUTDOWN_TIMEOUT_MS,
+        forceTimeoutMs: SHUTDOWN_TIMEOUT_MS,
+      });
+    } catch (err) {
+      logger.error("failed to stop command process tree:", err);
+    }
+  }
+
+  function startChild(reason: string): void {
+    logger.info(`${reason}; starting ${commandLabel}`);
+    const [command, ...commandArgs] = options.command;
+    const current = exec.spawn(command!, commandArgs, {
+      cwd,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+      check: false,
+    });
+    child = current;
+    void current
+      .then(({ exitCode }) => {
+        if (child !== current || stopping) return;
+        child = undefined;
+        logger.warn(
+          `command exited with code ${exitCode}; press ${JSON.stringify(options.restartKey)} or change a watched file to restart`,
+        );
+      })
+      .catch((err) => {
+        if (child !== current || stopping) return;
+        child = undefined;
+        logger.error("command failed:", err);
+      });
+  }
+
+  async function drainRestarts(): Promise<void> {
+    if (restarting) return;
+    restarting = true;
+    try {
+      while (restartReason !== undefined && !stopping) {
+        const reason = restartReason;
+        restartReason = undefined;
+        await stopChild();
+        if (!stopping) startChild(reason);
+      }
+    } finally {
+      restarting = false;
+    }
+  }
+
+  function requestRestart(reason: string): void {
+    restartReason = reason;
+    void drainRestarts();
+  }
+
+  function scheduleRestart(): void {
+    clearTimeout(timer);
+    timer = setTimeout(
+      () => requestRestart(`changes settled for ${options.debounceMs}ms`),
+      options.debounceMs,
+    );
+  }
+
+  watcher.on("all", scheduleRestart);
+  watcher.on("error", (err) => logger.error("watcher error:", err));
+  watcher.on("ready", () => {
+    const packages = watchDirectories.length;
+    logger.info(
+      `watching ${packages} workspace ${packages === 1 ? "directory" : "directories"} with ${options.debounceMs}ms restart debounce`,
+    );
+    logger.info(`press ${JSON.stringify(options.restartKey)} to restart; Ctrl-C to stop`);
+  });
+
+  const stdin = process.stdin;
+  const wasRaw = stdin.isTTY ? Boolean(stdin.isRaw) : false;
+  const onInput = (chunk: Buffer | string): void => {
+    for (const key of String(chunk)) {
+      if (key === "\u0003") {
+        void shutdown();
+        return;
+      }
+      if (isRestartKey(key, options.restartKey)) {
+        clearTimeout(timer);
+        requestRestart("manual restart requested");
+      }
+    }
+  };
+  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;
+    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();
+  }
+
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.once(signal, () => void shutdown());
+  }
+
+  requestRestart("initial start");
+  await complete;
+}
+
+if (import.meta.main) await main();

package/tasks/publish-python.ts

@@ -72,6 +72,7 @@ function pythonProjects(root: string): PythonProjectFile[] {
   return allProjects;
 }
 
+/** Build and upload every selected public Python workspace distribution. */
 export function publishPythonProjects(options: {
   readonly dryRun?: boolean;
   readonly indexUrl: string;
@@ -180,6 +181,7 @@ function buildPythonProjectsInternal(
   }
 }
 
+/** Parse command-line publication options and run the Python release task. */
 export async function main(): Promise<void> {
   const program = new Command();
   program

package/tasks/release.ts

@@ -71,7 +71,9 @@ function pushAnnotatedReleaseTag(options: {
   runTaskCommand(root, "git", ["tag", "--annotate", tag, "--message", annotation]);
   const githubAccount = projectUtils.resolveProjectGhAccount(root, { remote });
   if (!githubAccount) {
-    logger.warn("no authenticated GitHub account can access the release repository; using git push");
+    logger.warn(
+      "no authenticated GitHub account can access the release repository; using git push",
+    );
     runTaskCommand(root, "git", ["push", remote, `refs/tags/${tag}`]);
     return;
   }
@@ -228,6 +230,8 @@ export async function runRelease(
     readonly validationTasks?: readonly string[];
     /** After tagging, stage and deploy the AppKit demo app. Off by default. */
     readonly demoDeploy?: boolean;
+    /** Explicit Databricks CLI profile used by the optional demo deployment. */
+    readonly demoProfile?: string;
     /** Write `docs/releases/vX.Y.Z.md` via Genie, with a git-log fallback. On by default. */
     readonly releaseNotes?: boolean;
     /** Additional instructions appended to the standard Genie release-notes prompt. */
@@ -238,6 +242,11 @@ export async function runRelease(
   const { branch, prefix, remote, root } = options;
   const selection = releaseStepSelection(options);
   const install = options.install ?? "auto";
+  const demoProfile = options.demoProfile?.trim();
+
+  if (options.demoDeploy && !demoProfile) {
+    throw new Error("--demo-deploy requires --profile <name>");
+  }
 
   if (install === "always") runTaskCommand(root, "bun", ["install"]);
   if (selection.validation && hasPackageScript(root, "eslint:fix")) {
@@ -331,8 +340,8 @@ export async function runRelease(
     });
   }
 
-  if (options.demoDeploy) {
-    runTaskCommand(root, "bun", ["run", "demo:deploy"]);
+  if (options.demoDeploy && demoProfile) {
+    runTaskCommand(root, "bun", ["run", "demo:deploy", "--profile", demoProfile]);
   }
 
   return tag;
@@ -379,6 +388,7 @@ export function createReleaseCommand(): Command {
       "append custom instructions to the Genie release-notes prompt",
     )
     .option("--demo-deploy", "after tagging, stage and deploy the AppKit demo app (off by default)")
+    .option("--profile <name>", "Databricks CLI profile for --demo-deploy")
     .option("--no-local-publish", "skip publishing to configured local registries")
     .option("--local-registry <auto|false|url>", "local npm registry selection", "auto")
     .option("--local-pypi <auto|false|url>", "local devpi registry selection", "auto")
@@ -397,6 +407,7 @@ export function createReleaseCommand(): Command {
           install: ReleaseInstallMode;
           validate: string[];
           demoDeploy?: boolean;
+          profile?: string;
           releaseNotes?: boolean;
           releaseNotesInstructions?: string;
         },
@@ -419,6 +430,7 @@ export function createReleaseCommand(): Command {
           validation: options.validation,
           validationTasks: options.validate,
           demoDeploy: options.demoDeploy,
+          demoProfile: options.profile,
           releaseNotes: options.releaseNotes,
           releaseNotesInstructions: options.releaseNotesInstructions,
         });