@dbx-tools/projen 0.9.152 → 0.9.154

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:
@@ -585,11 +601,14 @@ site. Install validation prerequisites through `releaseSetupSteps`.
 Publication jobs download the resulting artifacts rather than rebuilding the
 workspace. Each Python package retains its own publishing environment and waits
 for its package dependencies to publish. The npm job uses the bundled archive
-publisher without a checkout or workspace install. Pages deploys the already
-built site after registry publication succeeds. Local npm and Python registry publication remains available
-through the direct local publication tooling. Those local publishers run
-concurrently; a failure or release termination stops every live publisher before
-the command returns.
+publisher without a checkout or workspace install. After all selected public
+publishers finish, one verifier downloads the complete release artifact set and
+polls only unresolved packages concurrently. It validates npm tarball contents
+and PyPI distribution hashes before Pages deploys the already built site. Local
+npm and Python registry publication remains available through the direct local
+publication tooling and does not wait for registry propagation. Those local
+publishers run concurrently; a failure or release termination stops every live
+publisher before the command returns.
 
 The default release publishes npm, Python, and docs, then publishes to
 configured local registries. Use `bun run release --help` or the generated

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.154";
 export * as appkitWorkspace from "./src/appkit-workspace.ts";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
@@ -69,7 +69,7 @@ export { PYTHON_NODE_RUNTIME_DISTRIBUTION, PYTHON_NODE_RUNTIME_MODULE, PYTHON_NO
 export type { PythonNodeRuntimeOptions } from "./src/python-node-runtime.ts";
 export { DBXToolsRelease } from "./src/release.ts";
 export type { ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
-export { RELEASE_VERSION, RELEASE_WORKFLOW_FILE } from "./src/release-context.ts";
+export { RELEASE_VERSION, RELEASE_WORKFLOW_FILE, PUBLIC_NPM_REGISTRY_URL, PUBLIC_PYPI_REGISTRY_URL } from "./src/release-context.ts";
 export { RELEASE_PUBLISH_TARGETS, RELEASE_INSTALL_MODES, ReleaseStepSelectionSchema } from "./src/release-options.ts";
 export type { ReleasePublishTarget, ReleaseInstallMode, ReleaseStepSelection, ReleaseSelectionOptions } from "./src/release-options.ts";
 export { SHARED_CORE_BINDING_EXPORTS } from "./src/shared-core-usage.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.154",
+    "@dbx-tools/cli-args": "^0.9.154",
+    "@dbx-tools/core": "^0.9.154",
+    "@dbx-tools/path": "^0.9.154",
+    "@dbx-tools/shared-core": "^0.9.154",
     "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.154",
   "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";
@@ -17,6 +19,7 @@ import {
   PythonNodeRuntime,
 } from "./python-node-runtime.ts";
 import {
+  refreshPublicationVerification,
   refreshReleaseDocsDependencies,
   releaseCondition,
   releaseBuildSteps,
@@ -107,7 +110,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 +220,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 +364,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");
@@ -672,6 +706,7 @@ export class DBXToolsPythonWorkspace extends Component {
         ],
       });
     }
+    refreshPublicationVerification(project);
     refreshReleaseDocsDependencies(project);
   }
 
@@ -760,26 +795,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/release-context.ts

@@ -3,3 +3,7 @@
 export const RELEASE_VERSION = "${{ needs.build-release.outputs.release_version }}";
 /** Generated GitHub Actions workflow triggered by release tags. */
 export const RELEASE_WORKFLOW_FILE = "release.yml";
+/** Public npm registry queried after npm publication completes. */
+export const PUBLIC_NPM_REGISTRY_URL = "https://registry.npmjs.org";
+/** Public PyPI JSON API queried after Python publication completes. */
+export const PUBLIC_PYPI_REGISTRY_URL = "https://pypi.org/pypi";