@dbx-tools/projen 0.9.151 → 0.9.153

package/README.md

@@ -24,7 +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. 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
@@ -104,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
@@ -310,8 +320,43 @@ parameter to `Project`). Drop to `mixin.create(predicate, fn)` +
 `project.with(...)` only when you need a predicate the filters cannot express.
 
 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.
+`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. 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, 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
+`.projenrc.ts`. A workspace with one `server` package also receives standard
+`check`, `dev`, and `start` tasks unless the repository defines them.
+
+The generated `deploy` task validates with the native Bun build, then delegates
+to `appkit:deploy` unless the repository already owns `deploy`. The AppKit task
+runs `databricks apps deploy --skip-validation` with all forwarded arguments
+from an isolated source snapshot, so the Databricks CLI never runs npm locally.
+Because the remote builder selects npm when no portable pnpm lockfile is
+uploaded, the snapshot replaces `catalog:` and `workspace:` dependency protocols
+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. 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,8 @@
 // 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.151";
+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";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -36,7 +37,10 @@ export * as tsconfig from "./src/tsconfig.ts";
 export * as vscode from "./src/vscode.ts";
 export * as watch from "./src/watch.ts";
 export * as workspaceLock from "./src/workspace-lock.ts";
+export * as workspaceManifest from "./src/workspace-manifest.ts";
 export * as workspaceVersion from "./src/workspace-version.ts";
+export { AppKitWorkspace } from "./src/appkit-workspace.ts";
+export type { AppKitWorkspaceMode, AppKitWorkspaceOptions } from "./src/appkit-workspace.ts";
 export { BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE, BUN_APP_OVERRIDES, RootBunfigFile, BunfigFile, BunDevServerFile, BunBuildFile } from "./src/bun-app.ts";
 export { BUN_VERSION, MINIMUM_BUN_VERSION, BUN_VERSION_CHECK_SCRIPT } from "./src/bun-workflow.ts";
 export { DBXToolsConfigDataSchema, DBXToolsConfig } from "./src/dbx-tools-config.ts";
@@ -73,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,10 +30,11 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/cli-args": "^0.9.151",
-    "@dbx-tools/core": "^0.9.151",
-    "@dbx-tools/path": "^0.9.151",
-    "@dbx-tools/shared-core": "^0.9.151",
+    "@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",
@@ -55,11 +56,12 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.151",
+  "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

@@ -0,0 +1,181 @@
+/**
+ * AppKit workspace conventions for paired browser and server packages.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+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;
+
+/** Projects configured by the AppKit workspace owner. */
+export interface AppKitWorkspaceOptions {
+  /** Browser application packages carrying the `app` tag. */
+  readonly apps: readonly javascript.NodeProject[];
+  /** AppKit backend packages carrying the `server` tag. */
+  readonly servers: readonly javascript.NodeProject[];
+  /** Fail synthesis when an AppKit package or required entry file is missing. */
+  readonly validate?: boolean;
+}
+
+/**
+ * Own the dependencies and generated configuration shared by AppKit workspaces.
+ */
+export class AppKitWorkspace extends Component {
+  private readonly deployTask: Task;
+  private readonly serverEntrypoint?: string;
+
+  constructor(project: javascript.NodeProject, options: AppKitWorkspaceOptions) {
+    super(project);
+
+    if (options.validate) validateWorkspace(options);
+    project.gitignore.addPatterns(".databricks");
+    project.addTask("appkit:sync", {
+      description: "Synchronize installed AppKit plugin metadata",
+      exec: "appkit plugin sync --write --silent",
+    });
+    this.deployTask = project.addTask("appkit:deploy", {
+      description: "Deploy the AppKit workspace from an npm-compatible source snapshot",
+      execArgs: ["bun", "node_modules/@dbx-tools/projen/tasks/appkit-deploy.ts"],
+      receiveArgs: true,
+    });
+
+    for (const app of options.apps) configureApp(app);
+    for (const server of options.servers) configureServer(server);
+    if (options.servers.length === 1) {
+      const server = options.servers[0]!;
+      const entrypoint = serverEntrypoint(server);
+      this.serverEntrypoint = relative(project.outdir, join(server.outdir, entrypoint))
+        .split(sep)
+        .join("/");
+    }
+  }
+
+  public override preSynthesize(): void {
+    let check = this.project.tasks.tryFind("check");
+    if (!check) {
+      check = this.project.addTask("check", {
+        description: "Validate the generated workspace with Bun",
+      });
+      check.spawn(this.project.buildTask);
+    }
+    if (!this.project.tasks.tryFind("deploy")) {
+      const deploy = this.project.addTask("deploy", {
+        description: "Validate with Bun and deploy the AppKit workspace",
+      });
+      deploy.spawn(check);
+      deploy.spawn(this.deployTask);
+    }
+    if (!this.serverEntrypoint) return;
+    if (!this.project.tasks.tryFind("dev")) {
+      this.project.addTask("dev", {
+        description: "Run the AppKit server in development mode",
+        env: { NODE_ENV: "development" },
+        exec: `bun --watch ${this.serverEntrypoint}`,
+        receiveArgs: true,
+      });
+    }
+    if (!this.project.tasks.tryFind("start")) {
+      this.project.addTask("start", {
+        description: "Run the AppKit server in production mode",
+        env: { NODE_ENV: "production" },
+        exec: `bun ${this.serverEntrypoint}`,
+        receiveArgs: true,
+      });
+    }
+  }
+}
+
+/** Validate the explicit AppKit convention before generating dependent config. */
+function validateWorkspace(options: AppKitWorkspaceOptions): void {
+  const missing: string[] = [];
+  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) {
+    if (!existsSync(join(app.outdir, "index.html"))) missing.push(`${app.name}/index.html`);
+  }
+  for (const server of options.servers) {
+    const entrypoint = serverEntrypoint(server);
+    if (!existsSync(join(server.outdir, entrypoint))) {
+      missing.push(`${server.name}/${entrypoint}`);
+    }
+  }
+  if (missing.length > 0) {
+    throw new Error(`appkit: true requires ${missing.join(", ")}`);
+  }
+}
+
+/** Configure one AppKit browser application without broadening React libraries. */
+function configureApp(project: javascript.NodeProject): void {
+  project.package.addField("appkit", { autoMigrate: false });
+  project.addDeps(
+    "@databricks/appkit-ui@catalog:",
+    "@tailwindcss/vite@catalog:",
+    "tailwindcss@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");
+}
+
+/** Configure one AppKit server with the runtime dependency its Vite loader imports. */
+function configureServer(project: javascript.NodeProject): void {
+  const entrypoint = serverEntrypoint(project);
+  if (entrypoint !== project.package.manifest.main) {
+    project.package.addField("main", entrypoint);
+    project.package.addField("types", entrypoint);
+  }
+  project.addDeps("@databricks/appkit@catalog:", "@vitejs/plugin-react@catalog:");
+}
+
+/** Prefer the canonical AppKit server entry when a package still has its default barrel. */
+function serverEntrypoint(project: javascript.NodeProject): string {
+  const configured =
+    typeof project.package.manifest.main === "string" ? project.package.manifest.main : "index.ts";
+  const canonical = "src/server.ts";
+  return configured === "index.ts" && existsSync(join(project.outdir, canonical))
+    ? canonical
+    : configured;
+}

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/dbx-tools-config.ts

@@ -73,6 +73,7 @@ export class DBXToolsConfig {
     this.tags = [...(options.tags ?? [])];
     this.codegenInputs = [...(options.codegenInputs ?? [])];
     this.publishable = options.publishable ?? true;
+    project.package.addField("private", () => (this.publishable ? undefined : true));
     project.package.addField(CONFIG_KEY, () => {
       const data = this.data();
       return Object.keys(data).length === 0 ? undefined : data;

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

@@ -62,6 +62,10 @@ const DEFAULT_CATALOG: Catalog = {
   "react-dom": "~19.2.4",
   "@types/react": "^19.2.2",
   "@types/react-dom": "^19.2.2",
+  tailwindcss: "^4.3.2",
+  "@tailwindcss/vite": "^4.3.2",
+  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",
   "@types/node": "^24.6.0",

package/src/project-js.ts

@@ -15,6 +15,7 @@ import { type IConstruct } from "constructs";
 import { Component, LogLevel, Project, type Task, TextFile, javascript, typescript } from "projen";
 import { JobPermission, type JobStep } from "projen/lib/github/workflows-model";
 import type { ReleaseProjectOptions } from "projen/lib/release";
+import { AppKitWorkspace, type AppKitWorkspaceMode } from "./appkit-workspace.ts";
 import { generateBarrels, isGeneratedBarrel } from "./barrels.ts";
 
 import { BUN_APP_OVERRIDES, RootBunfigFile } from "./bun-app.ts";
@@ -39,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";
 
@@ -139,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());
@@ -603,6 +612,8 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
      * disable. Defaults to `"node"`.
      */
     readonly omitRelativePrefix?: OneOrMany<string>;
+    /** Native defaults merged into every filesystem-discovered package. */
+    readonly packageDefaults?: Omit<DiscoveredTypeScriptPackageOptions, "name">;
     /** Resolve native constructor fields before a discovered package is constructed. */
     readonly resolvePackageOptions?: (
       pkg: DiscoveredPackage,
@@ -620,6 +631,13 @@ 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.
+     */
+    readonly appkit?: AppKitWorkspaceMode;
     /**
      * Extra repo-root paths that trigger a full re-synth during `sync --watch`
      * (alongside `.projenrc.ts`). Repo-relative, e.g. `".example.projenrc.ts"`.
@@ -679,7 +697,7 @@ export class DBXToolsNodeProject
   readonly language = "javascript" as const;
   readonly scope: string;
   readonly dbxToolsConfig: DBXToolsConfig;
-  pnpmWorkspace?: PnpmWorkspaceState;
+  pnpmWorkspace: PnpmWorkspaceState;
   rootTsconfig?: DBXToolsRootTsconfig;
   readonly extraWorkspaceMembers: readonly string[];
   readonly releaseBranch: string;
@@ -1007,7 +1025,10 @@ class WorkspaceValidationTasks extends Component {
       return;
     }
     project.compileTask.execArgs(taskCommand("compile-workspace.ts"));
-    project.testTask.spawn(project.tasks.tryFind("test:all")!);
+    const testAll = project.tasks.tryFind("test:all")!;
+    const pythonTests = project.tasks.tryFind("py:test");
+    if (pythonTests) testAll.spawn(pythonTests);
+    project.testTask.spawn(testAll);
   }
 }
 
@@ -1054,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}`);
       }
@@ -1225,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(),
@@ -1253,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];
@@ -1278,10 +1302,20 @@ 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.
-  project.gitignore.addPatterns(".env", ".env.*", "!.env.example", "!.env.sample", ".idea/*");
+  project.gitignore.addPatterns(
+    ".env",
+    ".env.*",
+    "!.env.example",
+    "!.env.sample",
+    ".idea/*",
+    ".npmrc",
+  );
   for (const root of roots) {
     project.annotateGenerated(`/${root}/**/index.ts`);
     project.annotateGenerated(`/${root}/**/src/generated/**`);
@@ -1396,9 +1430,11 @@ function initProject(
       continue;
     }
     const defaultPackageName = packageNameFor(project.scope, p.relPath, omitPrefixes);
-    const packageOptions =
-      options.resolvePackageOptions?.(p, { name: defaultPackageName }) ??
-      ({ name: defaultPackageName } satisfies DiscoveredTypeScriptPackageOptions);
+    const defaults = {
+      name: defaultPackageName,
+      ...options.packageDefaults,
+    } satisfies DiscoveredTypeScriptPackageOptions;
+    const packageOptions = options.resolvePackageOptions?.(p, defaults) ?? defaults;
     new DBXToolsTypeScriptProject({
       parent: project,
       outdir: p.memberPath,
@@ -1417,6 +1453,25 @@ function initProject(
   if (enabledTagMixins.length) {
     project.with(...enabledTagMixins.map((t) => PACKAGE_TAG_MIXINS[t]));
   }
+  const appkitMode = options.appkit ?? "auto";
+  if (appkitMode !== false) {
+    const projects = [project, ...project.subprojects].filter(
+      (candidate): candidate is DBXToolsNodeProject | DBXToolsTypeScriptProject =>
+        candidate instanceof DBXToolsNodeProject || candidate instanceof DBXToolsTypeScriptProject,
+    );
+    const apps = projects.filter((candidate) => candidate.dbxToolsConfig.tags.includes("app"));
+    const servers = projects.filter((candidate) =>
+      candidate.dbxToolsConfig.tags.includes("server"),
+    );
+    const enabled = appkitMode === true || (apps.length > 0 && servers.length > 0);
+    if (enabled) {
+      new AppKitWorkspace(project, {
+        apps,
+        servers,
+        validate: appkitMode === true,
+      });
+    }
+  }
 
   new WorkspaceValidationTasks(project);
   new PrettierIgnoreGenerated(project);