@dbx-tools/projen 0.9.152 → 0.9.153

package/README.md

@@ -24,10 +24,13 @@ packages. It can also generate Zod schemas from declarations and coordinate
 generated-file cleanup and watch tasks.
 
 Every `src`-bearing folder under the configured roots becomes a
-`DBXToolsTypeScriptProject`. Folder path drives package name and runtime tags.
+`DBXToolsTypeScriptProject`. `packages/js` is selected automatically when it
+exists; otherwise discovery uses `packages`. Folder path drives package name and
+runtime tags.
 Use `packageDefaults` for native options shared by every discovered package,
 such as `{ publishable: false }`; reserve `resolvePackageOptions` for genuine
-per-package differences.
+per-package differences. Use `rootTsconfig` only for repository-wide compiler
+differences; root tests, Bun/Node types, and React JSX are already included.
 
 Use `DBXToolsTypeScriptProject` itself as the root when one package needs the
 same Bun workspace, repository, task, and release defaults without a separate
@@ -107,7 +110,11 @@ new projectPy.DBXToolsPythonWorkspace(root, {
 ```
 
 Distribution names and modules come from the parent scope plus each package
-directory. The repository comes from the parent project metadata or Git remote.
+directory. Direct children of the Python root that contain `src/` are discovered
+automatically; `packages` only needs entries whose metadata differs from the
+generated defaults. Set `discoverPackages: false` for a fully explicit list.
+The repository comes from the parent project metadata, existing generated root
+manifest, or Git remote.
 `internalDependencies` renders standalone Git `#subdirectory=` requirements
 without repeating repository coordinates. Pass `repository`, `name`, or
 `module` only to override those conventions. `root.vscode` is Projen's existing
@@ -315,13 +322,18 @@ parameter to `Project`). Drop to `mixin.create(predicate, fn)` +
 Built-in tag mixins set runtime defaults for `shared`, `node`, `cli`, `server`,
 `ui`, and `app`. Repo-specific mixins layer package-specific dependencies,
 scripts, and generated files on top. `ui` is for reusable React component
-libraries. `app` owns a Bun-built browser application.
+libraries. `app` owns a Bun-built browser application. Terminal
+`packages/**/app` and `packages/**/server` directories select those specific
+roles instead of inheriting a generic `ui` or `node` ancestor.
 
 AppKit mode defaults to `auto`: when the workspace has both `app` and `server`
 packages, the engine adds the AppKit, Vite, React plugin, and Tailwind
 dependencies to the package that uses each one. It also disables AppKit's
 package migration, includes the Vite and generated-type inputs in the browser
-tsconfig, adds `appkit:sync`, and ignores local Databricks state. Set
+tsconfig, generates a read-only monorepo-safe `vite.config.ts`, adds
+`appkit:sync`, and ignores local Databricks state. Put repository-specific Vite
+settings in the optional unmanaged `vite.config.override.ts`; the generated
+config merges it over the engine defaults. Set
 `appkit: false` to disable this ownership. Set `appkit: true` to require AppKit
 and fail synthesis when either package role or its required entry files are
 missing. Keep application-specific UI and server dependencies in the consuming
@@ -338,8 +350,12 @@ with concrete versions and keeps every manifest stable through upload. The
 generated working tree is never modified. The task passes an explicit profile,
 using the supplied flag or resolving one through `@dbx-tools/auth`, and fails
 before staging when neither profile nor complete environment credentials are
-available. A repository-owned deployment flow can run its own Bun checks and
-spawn `appkit:deploy` for the upload step instead of maintaining staging or
+available. It validates the bundle strictly, removes only stale direct-engine
+state from the temporary snapshot, and defaults to active-run protection while
+skipping duplicate npm validation and tests. If deployment or app startup
+fails, the task prints the current Databricks App logs before returning the
+original failure. A repository-owned deployment flow can run its own Bun checks
+and spawn `appkit:deploy` for the upload step instead of maintaining staging or
 materialization code.
 
 Every workspace root exposes a generic development watcher:

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.152";
+export const PACKAGE_VERSION = "0.9.153";
 export * as appkitWorkspace from "./src/appkit-workspace.ts";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
@@ -77,6 +77,7 @@ export type { SharedCoreUsageKind, SharedCoreExportUsage } from "./src/shared-co
 export { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS } from "./src/tags.ts";
 export type { PackageTag } from "./src/tags.ts";
 export { DBXToolsRootTsconfig } from "./src/tsconfig.ts";
+export type { DBXToolsRootTsconfigOptions } from "./src/tsconfig.ts";
 export type { IgnoreGroupOptions, WatchLoopOptions } from "./src/watch.ts";
 export type { WorkspaceMutationLockOptions } from "./src/workspace-lock.ts";
 export { VERSION_FILE, DEFAULT_VERSION } from "./src/workspace-version.ts";

package/package.json

@@ -30,11 +30,11 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/auth": "^0.9.152",
-    "@dbx-tools/cli-args": "^0.9.152",
-    "@dbx-tools/core": "^0.9.152",
-    "@dbx-tools/path": "^0.9.152",
-    "@dbx-tools/shared-core": "^0.9.152",
+    "@dbx-tools/auth": "^0.9.153",
+    "@dbx-tools/cli-args": "^0.9.153",
+    "@dbx-tools/core": "^0.9.153",
+    "@dbx-tools/path": "^0.9.153",
+    "@dbx-tools/shared-core": "^0.9.153",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -56,11 +56,12 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.152",
+  "version": "0.9.153",
   "types": "index.ts",
   "type": "module",
   "exports": {
     ".": "./index.ts",
+    "./pypi-trusted-publisher-instructions": "./tasks/pypi-trusted-publisher-instructions.ts",
     "./python-release-packaging": "./tasks/publish-python.ts",
     "./release-packaging": "./tasks/publish-npm.ts",
     "./package.json": "./package.json"

package/src/appkit-workspace.ts

@@ -4,8 +4,9 @@
  * @module
  */
 import { existsSync } from "node:fs";
-import { join, relative, sep } from "node:path";
-import { Component, type Task, javascript, typescript } from "projen";
+import { basename, join, relative, sep } from "node:path";
+import { Component, type Task, TextFile, javascript, typescript } from "projen";
+import { headerLines } from "./generated.ts";
 
 /** AppKit workspace discovery and validation mode. */
 export type AppKitWorkspaceMode = "auto" | boolean;
@@ -94,9 +95,7 @@ function validateWorkspace(options: AppKitWorkspaceOptions): void {
   if (options.apps.length === 0) missing.push("an `app` package");
   if (options.servers.length === 0) missing.push("a `server` package");
   for (const app of options.apps) {
-    for (const file of ["index.html", "vite.config.ts"]) {
-      if (!existsSync(join(app.outdir, file))) missing.push(`${app.name}/${file}`);
-    }
+    if (!existsSync(join(app.outdir, "index.html"))) missing.push(`${app.name}/index.html`);
   }
   for (const server of options.servers) {
     const entrypoint = serverEntrypoint(server);
@@ -117,11 +116,47 @@ function configureApp(project: javascript.NodeProject): void {
     "@tailwindcss/vite@catalog:",
     "tailwindcss@catalog:",
   );
-  project.addDevDeps("vite@catalog:");
+  project.addDevDeps("@databricks/appkit@catalog:", "vite@catalog:");
+  const typesDirectory = `${basename(project.outdir)}/shared/appkit-types`;
+  new TextFile(project, "vite.config.ts", {
+    marker: true,
+    readonly: true,
+    lines: [
+      ...headerLines({ tool: "projen", source: ".projenrc.ts" }),
+      'import { existsSync } from "node:fs";',
+      'import { appKitServingTypesPlugin, appKitTypesPlugin } from "@databricks/appkit";',
+      'import tailwindcss from "@tailwindcss/vite";',
+      'import { defineConfig, mergeConfig, type UserConfig } from "vite";',
+      "",
+      `const appKitTypesDirectory = ${JSON.stringify(typesDirectory)};`,
+      'const overrideUrl = new URL("./vite.config.override.ts", import.meta.url);',
+      "const override = existsSync(overrideUrl)",
+      "  ? ((await import(overrideUrl.href)).default as UserConfig)",
+      "  : {};",
+      "",
+      "export default defineConfig(",
+      "  mergeConfig(",
+      "    {",
+      "      plugins: [",
+      "        tailwindcss(),",
+      "        appKitTypesPlugin({",
+      "          outFile: `${appKitTypesDirectory}/analytics.d.ts`,",
+      "        }),",
+      "        appKitServingTypesPlugin({",
+      "          outFile: `${appKitTypesDirectory}/serving.d.ts`,",
+      "        }),",
+      "      ],",
+      "    },",
+      "    override,",
+      "  ),",
+      ");",
+    ],
+  });
 
   if (!(project instanceof typescript.TypeScriptProject)) return;
   project.tsconfig?.file.addOverride("compilerOptions.rootDir", ".");
   project.tsconfig?.addInclude("vite.config.ts");
+  project.tsconfig?.addInclude("vite.config.override.ts");
   project.tsconfig?.addInclude("shared/appkit-types");
 }
 

package/src/bun-app.ts

@@ -24,6 +24,7 @@
  */
 import { stringUtils } from "@dbx-tools/shared-core";
 import { type Project, TextFile } from "projen";
+import { header, headerLines } from "./generated.ts";
 
 /** Unmanaged dev-server override module, merged over the generated options if present. */
 export const BUN_DEV_OVERRIDE = "bun-dev.override.ts";
@@ -31,6 +32,8 @@ export const BUN_DEV_OVERRIDE = "bun-dev.override.ts";
 export const BUN_BUILD_OVERRIDE = "bun-build.override.ts";
 /** Unmanaged generated-script overrides excluded from formatting and linting. */
 export const BUN_APP_OVERRIDES = [BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE];
+const PROJEN_HEADER = { tool: "projen", source: ".projenrc.ts" } as const;
+const PROJEN_TS_HEADER = header(PROJEN_HEADER).trimEnd().replaceAll("\n", "\n      ");
 
 /**
  * Root `bunfig.toml`: pin bun's HOISTED linker workspace-wide.
@@ -49,7 +52,7 @@ export class RootBunfigFile extends TextFile {
       marker: false,
       readonly: true,
       lines: [
-        '# ~~ Generated by projen. To modify, edit .projenrc.ts and run "bunx projen".',
+        ...headerLines({ ...PROJEN_HEADER, comment: "#" }),
         "# Hoisted (flat) node_modules so a peer dep like @mastra/core resolves to ONE",
         "# copy - the isolated default splits it into peer-hash variants and breaks",
         "# identity-based singletons + cross-package types.",
@@ -76,6 +79,7 @@ export class BunfigFile extends TextFile {
       marker: true,
       readonly: true,
       lines: [
+        ...headerLines({ ...PROJEN_HEADER, comment: "#" }),
         "# Tailwind v4 for the dev server (Bun.serve reads [serve.static] plugins).",
         "# Production build applies the plugin via Bun.build's API in build.ts - the",
         "# `bun build` CLI does not load bunfig plugins, so there is no [build] here.",
@@ -94,6 +98,7 @@ export class BunDevServerFile extends TextFile {
     const source = (
       // ============================================================================
       /*ts*/`
+      ${PROJEN_TS_HEADER}
       import { existsSync } from "node:fs";
       import index from "./index.html";
 
@@ -135,6 +140,7 @@ export class BunBuildFile extends TextFile {
       String.raw
       // ============================================================================
       /*ts*/`
+      ${PROJEN_TS_HEADER}
       import { existsSync } from "node:fs";
       import { cp, rm } from "node:fs/promises";
       import { basename } from "node:path";

package/src/generated.ts

@@ -10,8 +10,8 @@
  */
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 
-/** First line of every banner {@link header} builds. */
-const MARKER = "// GENERATED by";
+/** Tool-owned marker text shared by every supported comment style. */
+const MARKER = "GENERATED by";
 
 /** Python subpackage, under a package's module directory, that holds all toolchain output. */
 export const PYTHON_GENERATED_PACKAGE = "_generated";
@@ -34,6 +34,8 @@ export function makeReadonly(file: string): void {
 
 /** Inputs for the durable generated-file banner. */
 export interface HeaderOpts {
+  /** Line-comment prefix. Defaults to `//`. */
+  readonly comment?: "//" | "#";
   /** What produced the file, e.g. `"projen watch"`. */
   readonly tool: string;
   /** What the file is derived from, e.g. `"the exporting modules beside it"`. */
@@ -42,12 +44,18 @@ export interface HeaderOpts {
 
 /** Build the do-not-edit banner (line comments, for TS/JS). */
 export function header(opts: HeaderOpts): string {
-  const lines = [`${MARKER} ${opts.tool} - DO NOT EDIT.`];
-  if (opts.source) lines.push(`// Regenerated from ${opts.source}.`);
-  lines.push("// Hand edits are overwritten on the next watch; this file is read-only.");
+  const comment = opts.comment ?? "//";
+  const lines = [`${comment} ${MARKER} ${opts.tool} - DO NOT EDIT.`];
+  if (opts.source) lines.push(`${comment} Regenerated from ${opts.source}.`);
+  lines.push(`${comment} Hand edits are overwritten on the next watch; this file is read-only.`);
   return `${lines.join("\n")}\n`;
 }
 
+/** Build a generated banner as lines for Projen file components. */
+export function headerLines(opts: HeaderOpts): string[] {
+  return header(opts).trimEnd().split("\n");
+}
+
 /**
  * True if the file exists and carries the do-not-edit banner {@link header}
  * writes - i.e. a toolchain wrote it and a hand edit would be overwritten.
@@ -61,7 +69,8 @@ export function isGenerated(file: string): boolean {
   try {
     const source = readFileSync(file, "utf8");
     return (
-      source.startsWith(MARKER) ||
+      source.startsWith(`// ${MARKER}`) ||
+      source.startsWith(`# ${MARKER}`) ||
       source.startsWith("// ~~ Generated by projen") ||
       source.startsWith("# ~~ Generated by projen") ||
       /"\/\/"\s*:\s*"~~ Generated by projen/.test(source)
@@ -78,7 +87,7 @@ export function isGenerated(file: string): boolean {
 export function stampGenerated(file: string, opts: HeaderOpts): void {
   makeWritable(file);
   const body = readFileSync(file, "utf8");
-  const next = body.startsWith(MARKER) ? body : `${header(opts)}\n${body}`;
+  const next = isGenerated(file) ? body : `${header(opts)}\n${body}`;
   writeFileSync(file, next);
   makeReadonly(file);
 }

package/src/packages.ts

@@ -146,11 +146,16 @@ export class DiscoveredPackage {
 
   /**
    * Tag candidates from nesting under the discovery root: cumulative kebab-case join
-   * of every ancestor folder, excluding the leaf package folder when depth >= 2
+   * of every ancestor folder, excluding the leaf package folder when depth >= 2.
+   * Terminal `app` and `server` directories are runtime roles and replace their
+   * generic ancestor (`ui/app` -> `app`, `node/server` -> `server`).
+   * Other paths keep cumulative tags
    * (`shared/path/coolDude/another` -> `[shared, shared-path, shared-path-cool-dude]`).
    * Matched against `packageTagPaths` to resolve applied mixin tags.
    */
   get tagCandidates(): string[] {
+    const leaf = stringUtils.toSlug(this.name);
+    if (leaf === "app" || leaf === "server") return [leaf];
     return nestingTagsFromSegments(this.relSegments);
   }
 }

package/src/pnpm-workspace.ts

@@ -64,7 +64,7 @@ const DEFAULT_CATALOG: Catalog = {
   "@types/react-dom": "^19.2.2",
   tailwindcss: "^4.3.2",
   "@tailwindcss/vite": "^4.3.2",
-  vite: "^7.2.4",
+  vite: "npm:rolldown-vite@7.1.14",
   "@vitejs/plugin-react": "^5.1.1",
   // Tailwind v4 compiler for bun's dev server + `Bun.build` (the `app` tag).
   "bun-plugin-tailwind": "^0.1.2",

package/src/project-js.ts

@@ -40,7 +40,7 @@ import { applyCompiledPublish } from "./publish.ts";
 import { generatePythonNodeBindings } from "./python-node-bindings.ts";
 import { DBXToolsRelease, type ReleaseDocsOptions } from "./release.ts";
 import { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS, type PackageTag } from "./tags.ts";
-import { DBXToolsRootTsconfig } from "./tsconfig.ts";
+import { DBXToolsRootTsconfig, type DBXToolsRootTsconfigOptions } from "./tsconfig.ts";
 import { configureVsCode } from "./vscode.ts";
 import { readWorkspaceVersion, syncWorkspaceManifestVersion } from "./workspace-version.ts";
 
@@ -140,7 +140,15 @@ function repositoryOptions(
   options: DBXToolsJavaScriptProjectOptions,
 ): Pick<javascript.NodeProjectOptions, "repository" | "repositoryDirectory"> {
   const workspaceRoot = resolve(options.parent?.root.outdir ?? options.outdir ?? process.cwd());
-  const repository = options.repository ?? projectUtils.repositoryUrl(workspaceRoot, "npm");
+  const existingRepository = readPackageManifest(workspaceRoot)?.repository;
+  const existingRepositoryUrl =
+    typeof existingRepository === "string"
+      ? existingRepository
+      : object.isRecord(existingRepository)
+        ? stringUtils.trimToNull(existingRepository.url)
+        : undefined;
+  const repository =
+    options.repository ?? projectUtils.repositoryUrl(workspaceRoot, "npm") ?? existingRepositoryUrl;
   const projectRoot = options.parent
     ? resolve(options.parent.outdir, options.outdir ?? ".")
     : resolve(options.outdir ?? process.cwd());
@@ -623,6 +631,8 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
      * a list = only those tags.
      */
     readonly defaultTagMixins?: false | PackageTag[];
+    /** Overrides for the generated repository-root TypeScript program. */
+    readonly rootTsconfig?: DBXToolsRootTsconfigOptions;
     /**
      * Apply AppKit conventions to `app` and `server` packages. Defaults to
      * `auto`; `true` also validates the required package roles and entry files.
@@ -1065,6 +1075,7 @@ class PrettierIgnoreGenerated extends Component {
       if (!(sub instanceof DBXToolsTypeScriptProject)) continue;
       const rel = toPosix(relative(rootAbs, sub.outdir));
       prettier.addIgnorePattern(`${rel}/index.ts`);
+      prettier.addIgnorePattern(`${rel}/src/**/index.ts`);
       for (const module of codegenModulePaths(sub.dbxToolsConfig.codegenInputs)) {
         prettier.addIgnorePattern(`${rel}/${module}`);
       }
@@ -1236,7 +1247,7 @@ function initProject(
   }
 
   if (project instanceof DBXToolsNodeProject) {
-    project.rootTsconfig = new DBXToolsRootTsconfig(project);
+    project.rootTsconfig = new DBXToolsRootTsconfig(project, options.rootTsconfig);
   }
   const projenrc = new typescript.ProjenrcTs(project, {
     runner: typescript.TypeScriptRunner.nodejs(),
@@ -1264,7 +1275,9 @@ function initProject(
   // lockfiles, so the CI-named install task must resolve from manifests as well.
   project.package.installCiTask.reset("bun install");
   configureRootBunRuntime(project);
-  const roots = options.packageRoots ?? DEFAULT_PACKAGE_ROOTS;
+  const roots =
+    options.packageRoots ??
+    (existsSync(resolve(project.outdir, "packages/js")) ? ["packages/js"] : DEFAULT_PACKAGE_ROOTS);
   project.dbxToolsConfig.packageRoots = [...roots];
   if (options.syncResynthPaths?.length) {
     project.dbxToolsConfig.syncResynthPaths = [...options.syncResynthPaths];
@@ -1289,6 +1302,9 @@ function initProject(
   project.gitignore.addPatterns(
     ...[...ignore.ignorePatterns({ test: false, dot: false, lock: true })],
   );
+  // The generic compiled-output pattern `**/lib/**` must not hide authored
+  // modules beneath a package's `src/lib/`.
+  project.gitignore.include("**/src/lib/**");
   // What the dot group was actually earning here, named explicitly: secrets and
   // local editor state. Both ignore CONTENTS (`.idea/*`) rather than the
   // directory, so a later `!` negation can still reach a file inside.

package/src/project-py.ts

@@ -1,9 +1,11 @@
 /** Reusable uv workspace generation for Python packages hosted in a projen tree. */
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
 import * as projectUtils from "@dbx-tools/core/project-utils";
 import { stringUtils, type OneOrMany } from "@dbx-tools/shared-core";
 import { Component, License, TextFile, type Project, github, javascript, python } from "projen";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
-import { PYTHON_GENERATED_PACKAGE } from "./generated.ts";
+import { header, PYTHON_GENERATED_PACKAGE } from "./generated.ts";
 import { LICENSE, projectRepositoryUrl, taskCommand } from "./project-js.ts";
 import { isDBXToolsJavaScriptProject } from "./project-predicate.ts";
 import type { DBXToolsProject, DBXToolsProjectOptions } from "./project.ts";
@@ -107,7 +109,10 @@ interface PythonPublication {
 
 /** Options for {@link DBXToolsPythonWorkspace}. */
 export interface DBXToolsPythonWorkspaceOptions {
-  readonly packages: readonly PythonPackageOptions[];
+  /** Package-specific options merged over packages discovered under the Python root. */
+  readonly packages?: readonly PythonPackageOptions[];
+  /** Discover direct child directories containing `src/`. Defaults to true. */
+  readonly discoverPackages?: boolean;
   readonly repository?: PythonRepositoryOptions;
   /** Repository-relative Python package root. Defaults to `packages/py`. */
   readonly root?: string;
@@ -214,6 +219,15 @@ export function pythonModuleName(scope: string, directory: string): string {
   return [scope, ...directory.split("/")].map((part) => part.replaceAll("-", "_")).join(".");
 }
 
+/** Discover direct Python workspace members by their conventional source directory. */
+function discoverPythonPackages(root: string): string[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(resolve(root, entry.name, "src")))
+    .map((entry) => entry.name)
+    .sort();
+}
+
 /** A Python package implemented with projen's `PythonProject` and uv backend. */
 export class DBXToolsPythonProject extends python.PythonProject implements DBXToolsProject {
   readonly language = "python" as const;
@@ -349,11 +363,30 @@ export class DBXToolsPythonWorkspace extends Component {
       ref: options.repository?.ref ?? "main",
       root: options.root ?? options.repository?.root ?? "packages/py",
     };
-    const packageIdentities: ResolvedPythonPackageOptions[] = options.packages.map((pkg) => ({
-      ...pkg,
-      name: pkg.name ?? `${scope}-${stringUtils.toSlug(pkg.directory)}`,
-      module: pkg.module ?? pythonModuleName(scope, pkg.directory),
-    }));
+    const configuredPackages = new Map((options.packages ?? []).map((pkg) => [pkg.directory, pkg]));
+    const discoveredDirectories =
+      options.discoverPackages === false
+        ? []
+        : discoverPythonPackages(resolve(project.outdir, this.repository.root));
+    const directories = [
+      ...configuredPackages.keys(),
+      ...discoveredDirectories.filter((directory) => !configuredPackages.has(directory)),
+    ];
+    const packageIdentities: ResolvedPythonPackageOptions[] = directories.map((directory) => {
+      const pkg = configuredPackages.get(directory);
+      return {
+        directory,
+        description: `${scope} ${directory} Python package.`,
+        ...pkg,
+        name: pkg?.name ?? `${scope}-${stringUtils.toSlug(directory)}`,
+        module: pkg?.module ?? pythonModuleName(scope, directory),
+      };
+    });
+    if (packageIdentities.length === 0) {
+      throw new Error(
+        `No Python packages were configured or discovered under ${this.repository.root}`,
+      );
+    }
     const configuredNodeRuntimes = packageIdentities.filter(({ nodeRuntime }) => nodeRuntime);
     if (configuredNodeRuntimes.length > 1) {
       throw new Error("A Python workspace can configure only one shared Node runtime package");
@@ -760,26 +793,24 @@ export class DBXToolsPythonWorkspace extends Component {
       }),
     ];
     const helper = ".projen/pypi-trusted-publisher-instructions.mjs";
+    const helperHeader = header({ tool: "projen", source: ".projenrc.ts" })
+      .trimEnd()
+      .replaceAll("\n", "\n          ");
     new TextFile(project.root, helper, {
+      marker: true,
+      readonly: true,
       // prettier-ignore
       lines: stringUtils.dedent(
         // ============================================================================
         /*js*/`
           #!/usr/bin/env bun
-          import { parseArgs } from "node:util";
+          ${helperHeader}
+          import { printPypiTrustedPublisherInstructions } from "@dbx-tools/projen/pypi-trusted-publisher-instructions";
 
-          const { values } = parseArgs({
-            options: { secretFile: { type: "string" } },
+          await printPypiTrustedPublisherInstructions({
+            beforeAuthentication: ${JSON.stringify(linesBeforeAuthentication)},
+            afterAuthentication: ${JSON.stringify(linesAfterAuthentication)},
           });
-          const beforeAuthentication = ${JSON.stringify(linesBeforeAuthentication)};
-          const afterAuthentication = ${JSON.stringify(linesAfterAuthentication)};
-          const authentication = values.secretFile
-            ? [
-                \`- If browser authentication is required, read credentials from \${values.secretFile} directly into the browser without printing, logging, or exposing secret values.\`,
-                \`- If \${values.secretFile} is absent, invalid, or insufficient for authentication, pause and ask the user to complete authentication.\`,
-              ]
-            : ["- If browser authentication is required, pause and ask the user to complete authentication."];
-          process.stdout.write(\`\${[...beforeAuthentication, ...authentication, ...afterAuthentication].join("\\n").trimEnd()}\\n\`);
         `
         // ============================================================================
       ).split("\n"),

package/src/tsconfig.ts

@@ -3,6 +3,12 @@
  */
 import { Component, type Project, javascript, typescript } from "projen";
 
+/** Consumer overrides for the repository-root TypeScript program. */
+export interface DBXToolsRootTsconfigOptions {
+  readonly compilerOptions?: javascript.TypeScriptCompilerOptions;
+  readonly include?: readonly string[];
+}
+
 /**
  * Compiler options for the ROOT program only (`.projenrc.ts` + the engine as
  * seen from the root). Each package owns its own projen-generated
@@ -40,7 +46,7 @@ export class DBXToolsRootTsconfig extends Component {
   /** Root program config inherited by the generated Projen config. */
   readonly config?: javascript.TypescriptConfig;
 
-  constructor(scope: Project) {
+  constructor(scope: Project, options: DBXToolsRootTsconfigOptions = {}) {
     super(scope);
 
     if (scope instanceof typescript.TypeScriptProject) {
@@ -57,8 +63,9 @@ export class DBXToolsRootTsconfig extends Component {
         lib: ["ESNext"],
         types: ["node", "bun"],
         jsx: javascript.TypeScriptJsxMode.REACT_JSX,
+        ...options.compilerOptions,
       },
-      include: [".projenrc.ts", "test/**/*.ts", "test/**/*.tsx"],
+      include: [".projenrc.ts", "test/**/*.ts", "test/**/*.tsx", ...(options.include ?? [])],
       exclude: ["node_modules", "**/dist", "**/node_modules"],
     });
   }

package/src/workspace-manifest.ts

@@ -43,6 +43,10 @@ export function materializeWorkspaceManifest(
     workspace.catalog && typeof workspace.catalog === "object"
       ? (workspace.catalog as Readonly<Record<string, unknown>>)
       : {};
+  const overrides =
+    workspace.overrides && typeof workspace.overrides === "object"
+      ? (workspace.overrides as Readonly<Record<string, unknown>>)
+      : {};
   if (typeof version !== "string" || !version) {
     throw new Error("Workspace manifest has no version");
   }
@@ -52,7 +56,7 @@ export function materializeWorkspaceManifest(
     manifest[field] = Object.fromEntries(
       Object.entries(dependencies).map(([name, value]) => [
         name,
-        materializeDependency(name, value, version, catalog),
+        materializeDependency(name, value, version, catalog, overrides),
       ]),
     );
   }
@@ -134,7 +138,12 @@ function materializeDependency(
   value: unknown,
   version: string,
   catalog: Readonly<Record<string, unknown>>,
+  overrides: Readonly<Record<string, unknown>>,
 ): unknown {
+  const override = overrides[name];
+  if (typeof override === "string" && override && !override.startsWith("$")) {
+    return override;
+  }
   if (value === "catalog:") {
     const resolved = catalog[name];
     if (typeof resolved !== "string" || !resolved) {

package/tasks/appkit-deploy.ts

@@ -1,16 +1,77 @@
 #!/usr/bin/env -S bun
 /** Deploy an AppKit workspace through npm-compatible temporary manifests. */
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { profile } from "@dbx-tools/auth";
+import { serializeArgs } from "@dbx-tools/cli-args";
 import * as exec from "@dbx-tools/core/exec";
-import { runTaskMain } from "./cli.ts";
+import { errorUtils, log } from "@dbx-tools/shared-core";
+import { z } from "zod";
+import { runTaskMain, taskCommand, taskOptions } from "./cli.ts";
 import { withStagedWorkspaceManifests } from "../src/workspace-manifest.ts";
 
+const logger = log.logger("projen:appkit-deploy");
+
+export const AppKitDeployContextOptionsSchema = z.object({
+  target: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Databricks bundle target")
+    .meta({ env: [], short: "t" }),
+  profile: z.string().trim().min(1).optional().describe("Databricks CLI profile").meta({
+    env: [],
+    helpDefault: false,
+    short: "p",
+  }),
+  var: z
+    .array(z.string().trim().min(1))
+    .default([])
+    .describe("Databricks bundle variable assignment")
+    .meta({ env: [] }),
+});
+
+export const AppKitDeployOptionsSchema = AppKitDeployContextOptionsSchema.extend({
+  autoApprove: z
+    .boolean()
+    .default(false)
+    .describe("Skip interactive deployment approval")
+    .meta({ env: [] }),
+  failOnActiveRuns: z
+    .boolean()
+    .default(true)
+    .describe("Fail when bundle jobs or pipelines are active")
+    .meta({ env: [] }),
+  skipTests: z
+    .boolean()
+    .default(true)
+    .describe("Skip Databricks CLI tests after the Bun validation")
+    .meta({ env: [] }),
+  skipValidation: z
+    .boolean()
+    .default(true)
+    .describe("Skip Databricks CLI npm validation after the Bun validation")
+    .meta({ env: [] }),
+});
+
+export type AppKitDeployOptions = z.output<typeof AppKitDeployOptionsSchema>;
+
+interface DeployCommandResult {
+  readonly exitCode: number;
+  readonly stderr?: string;
+  readonly stdout?: string;
+}
+
 /** Effects accepted by the AppKit deploy task for focused tests. */
 export interface AppKitDeployDependencies {
   readonly environment?: NodeJS.ProcessEnv;
+  readonly logs?: (args: readonly string[], cwd: string) => Promise<DeployCommandResult>;
+  readonly plan?: (args: readonly string[], cwd: string) => Promise<DeployCommandResult>;
   readonly root?: string;
   readonly resolveProfile?: () => string | undefined;
-  readonly run?: (args: readonly string[], cwd: string) => Promise<{ readonly exitCode: number }>;
+  readonly run?: (args: readonly string[], cwd: string) => Promise<DeployCommandResult>;
+  readonly validate?: (args: readonly string[], cwd: string) => Promise<DeployCommandResult>;
 }
 
 /** Run Databricks Apps deploy while generated workspace manifests are materialized. */
@@ -19,7 +80,42 @@ export async function deployApp(
   dependencies: AppKitDeployDependencies = {},
 ): Promise<void> {
   const root = dependencies.root ?? process.cwd();
-  const deployArgs = resolveDeployArgs(args, dependencies);
+  const options = await resolveDeployOptions(args, dependencies);
+  const context = AppKitDeployContextOptionsSchema.parse({
+    target: options.target,
+    profile: options.profile,
+    var: options.var,
+  });
+  const contextArgs = serializeArgs(context);
+  const deployArgs = serializeArgs({
+    ...context,
+    ...(options.autoApprove ? { autoApprove: true } : {}),
+    ...(options.failOnActiveRuns ? { failOnActiveRuns: true } : {}),
+    ...(options.skipTests ? { skipTests: true } : {}),
+    ...(options.skipValidation ? { skipValidation: true } : {}),
+  });
+  const validate =
+    dependencies.validate ??
+    (dependencies.run
+      ? undefined
+      : (validateArgs: readonly string[], cwd: string) =>
+          exec.spawn(
+            "databricks",
+            ["bundle", "validate", ...serializeArgs({ strict: true }), ...validateArgs],
+            {
+              cwd,
+              env: dependencies.environment ?? process.env,
+              stdin: "ignore",
+              stdout: "inherit",
+              stderr: "inherit",
+            },
+          ));
+  if (validate) {
+    const validation = await validate(contextArgs, root);
+    if (validation.exitCode !== 0) {
+      throw new Error(`databricks bundle validate exited with code ${validation.exitCode}`);
+    }
+  }
   const run =
     dependencies.run ??
     ((deployArgs: readonly string[], cwd: string) =>
@@ -31,40 +127,119 @@ export async function deployApp(
         stderr: "inherit",
       }));
   await withStagedWorkspaceManifests(root, async (stage) => {
+    await reconcileStagedBundleState(stage, contextArgs, options.target, dependencies);
     const result = await run(deployArgs, stage);
     if (result.exitCode !== 0) {
+      await printAppLogs(contextArgs, stage, dependencies);
       throw new Error(`databricks apps deploy exited with code ${result.exitCode}`);
     }
   });
 }
 
-function resolveDeployArgs(
+async function reconcileStagedBundleState(
+  stage: string,
+  contextArgs: readonly string[],
+  target: string | undefined,
+  dependencies: AppKitDeployDependencies,
+): Promise<void> {
+  const plan =
+    dependencies.plan ??
+    (dependencies.run
+      ? undefined
+      : (args: readonly string[], cwd: string) =>
+          Promise.resolve(
+            exec.spawnSync(
+              "databricks",
+              ["bundle", "plan", ...serializeArgs({ quiet: true }), ...args],
+              {
+                cwd,
+                env: dependencies.environment ?? process.env,
+                stdin: "ignore",
+                stdout: "capture",
+                stderr: "capture",
+              },
+            ),
+          ));
+  if (!plan) return;
+  const result = await plan(contextArgs, stage);
+  if (result.exitCode === 0) return;
+  const output = `${result.stderr ?? ""}\n${result.stdout ?? ""}`.toLowerCase();
+  if (
+    !output.includes("lineage mismatch in state files") ||
+    !output.includes("remote direct state")
+  ) {
+    return;
+  }
+  if (!target) return;
+  const state = join(stage, ".databricks", "bundle", target, "resources.json");
+  if (!existsSync(state)) return;
+  rmSync(state);
+  logger.warn("Removed stale staged bundle state", { target });
+}
+
+async function printAppLogs(
+  contextArgs: readonly string[],
+  cwd: string,
+  dependencies: AppKitDeployDependencies,
+): Promise<void> {
+  logger.error("Databricks Apps deployment failed; recent app logs follow");
+  const showLogs =
+    dependencies.logs ??
+    ((args: readonly string[], logsCwd: string) =>
+      exec.spawn("databricks", ["apps", "logs", ...serializeArgs({ tailLines: 200 }), ...args], {
+        cwd: logsCwd,
+        env: dependencies.environment ?? process.env,
+        stdin: "ignore",
+        stdout: "inherit",
+        stderr: "inherit",
+      }));
+  try {
+    const result = await showLogs(contextArgs, cwd);
+    if (result.exitCode !== 0) {
+      logger.warn("Could not read Databricks App logs", { exitCode: result.exitCode });
+    }
+  } catch (error) {
+    logger.warn("Could not read Databricks App logs", {
+      message: errorUtils.toError(error).message,
+    });
+  }
+}
+
+async function resolveDeployOptions(
   args: readonly string[],
   dependencies: AppKitDeployDependencies,
-): readonly string[] {
-  const environment = dependencies.environment ?? process.env;
-  const hasProfile = args.some(
-    (argument) =>
-      argument === "--profile" || argument === "-p" || argument.startsWith("--profile="),
+): Promise<AppKitDeployOptions> {
+  const parsed = await taskOptions(
+    taskCommand(
+      import.meta.url,
+      "Validate and deploy an AppKit workspace through Databricks Apps",
+      AppKitDeployOptionsSchema,
+    ),
+    AppKitDeployOptionsSchema,
+    args,
   );
+  const environment = dependencies.environment ?? process.env;
   const hasEnvironmentAuth =
     Boolean(environment.DATABRICKS_HOST) &&
     (Boolean(environment.DATABRICKS_TOKEN) ||
       (Boolean(environment.DATABRICKS_CLIENT_ID) && Boolean(environment.DATABRICKS_CLIENT_SECRET)));
+  const configuredProfile = environment.DATABRICKS_CONFIG_PROFILE ?? environment.DATABRICKS_PROFILE;
   const resolvedProfile =
-    hasProfile || hasEnvironmentAuth
+    parsed.profile ??
+    configuredProfile ??
+    (hasEnvironmentAuth
       ? undefined
-      : (dependencies.resolveProfile ?? (() => profile.resolveProfile()?.name))();
-  if (!hasProfile && !hasEnvironmentAuth && !resolvedProfile) {
+      : (dependencies.resolveProfile ?? (() => profile.resolveProfile()?.name))());
+  if (!hasEnvironmentAuth && !resolvedProfile) {
     throw new Error(
       "Select a Databricks profile with --profile or configure Databricks environment credentials",
     );
   }
-  return [
-    ...(args.includes("--skip-validation") ? [] : ["--skip-validation"]),
-    ...args,
-    ...(resolvedProfile ? ["--profile", resolvedProfile] : []),
-  ];
+  return AppKitDeployOptionsSchema.parse({
+    ...parsed,
+    target: parsed.target ?? environment.DATABRICKS_BUNDLE_TARGET,
+    profile: resolvedProfile,
+  });
 }
 
 await runTaskMain(import.meta, () => deployApp(process.argv.slice(2)));

package/tasks/pypi-trusted-publisher-instructions.ts

@@ -0,0 +1,54 @@
+/** Parse and print generated PyPI trusted-publisher setup instructions. */
+import { z } from "zod";
+import { taskCommand, taskOptions } from "./cli.ts";
+
+export const PypiTrustedPublisherInstructionsOptionsSchema = z
+  .object({
+    secretFile: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe("Credential file used only when browser authentication is required")
+      .meta({ env: [], helpDefault: false, short: false }),
+  })
+  .describe("Options for rendering PyPI trusted-publisher setup instructions");
+
+/** Project-specific instruction sections wrapped around browser authentication guidance. */
+export interface PypiTrustedPublisherInstructions {
+  readonly afterAuthentication: readonly string[];
+  readonly beforeAuthentication: readonly string[];
+}
+
+/** Parse task options and write the complete trusted-publisher instructions. */
+export async function printPypiTrustedPublisherInstructions(
+  instructions: PypiTrustedPublisherInstructions,
+  argv: readonly string[] = process.argv.slice(2),
+): Promise<void> {
+  const { secretFile } = await taskOptions(
+    taskCommand(
+      import.meta.url,
+      "Print system-browser instructions for PyPI trusted publishers",
+      PypiTrustedPublisherInstructionsOptionsSchema,
+    ),
+    PypiTrustedPublisherInstructionsOptionsSchema,
+    argv,
+  );
+  const authentication = secretFile
+    ? [
+        `- If browser authentication is required, read credentials from ${secretFile} directly into the browser without printing, logging, or exposing secret values.`,
+        `- If ${secretFile} is absent, invalid, or insufficient for authentication, pause and ask the user to complete authentication.`,
+      ]
+    : [
+        "- If browser authentication is required, pause and ask the user to complete authentication.",
+      ];
+  process.stdout.write(
+    `${[
+      ...instructions.beforeAuthentication,
+      ...authentication,
+      ...instructions.afterAuthentication,
+    ]
+      .join("\n")
+      .trimEnd()}\n`,
+  );
+}

package/tasks/python-node-bindings.ts

@@ -13,7 +13,7 @@ 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 { header, headerLines, makeReadonly, makeWritable } from "../src/generated.ts";
 import { publicFunctionExports } from "../src/module-exports.ts";
 import { resolveRepoRoot } from "../src/packages.ts";
 import {
@@ -434,9 +434,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       section.includes("Callable["),
     );
     return [
-      "# GENERATED by projen/tasks/python-node-bindings.ts - DO NOT EDIT.",
-      `# Regenerated from ${source}.`,
-      "# Hand edits are overwritten; this file is read-only.",
+      ...headerLines({
+        comment: "#",
+        tool: "projen/tasks/python-node-bindings.ts",
+        source,
+      }),
       "",
       "from __future__ import annotations",
       "",
@@ -1162,9 +1164,11 @@ function removeEmptyDirectories(directory: string): void {
 
 function pythonRuntimeLoader(source: string): string {
   return [
-    "# GENERATED by projen/tasks/python-node-bindings.ts - DO NOT EDIT.",
-    `# Regenerated from ${source}.`,
-    "# Hand edits are overwritten; this file is read-only.",
+    ...headerLines({
+      comment: "#",
+      tool: "projen/tasks/python-node-bindings.ts",
+      source,
+    }),
     "",
     "from __future__ import annotations",
     "",