@dbx-tools/projen 0.9.58 → 0.9.61

package/README.md

@@ -481,8 +481,22 @@ bun run release --publish pypi --no-docs
 bun run release --no-npm --no-local-publish
 bun run release --publish local --install never
 bun run release --local-registry false --local-pypi auto
+bun run release --demo-deploy
+bun run release --no-release-notes
 ```
 
+`--demo-deploy` is off by default. After tagging and any local registry
+publication it runs `bun run demo:deploy`, which stages the AppKit demo
+and deploys it to the FEVM workspace. That step is local only and is not
+recorded in the annotated tag.
+
+After bump, release writes `docs/releases/vX.Y.Z.md` with `dbx genie exec -C
+"$PWD" --sandbox read-only --ephemeral -o`. If Genie fails or writes an empty
+file, the step keeps going with a short git-log summary. `--no-release-notes`
+skips the file. Notes are committed with the version bump and are not recorded
+in the annotated tag. They are skipped on `--no-bump` because that path
+requires an already committed tree.
+
 `--install auto` keeps Projen's normal local dependency-install behavior;
 `always` performs a manifest-resolved install first, and `never` uses dependencies already
 installed while still regenerating versioned sources. `--no-validation` skips
@@ -553,6 +567,8 @@ release [options]
 | `--docs`                              | build and deploy docs for a selected scope                                                    |
 | `--no-docs`                           | skip documentation build and deployment                                                       |
 | `--no-validation`                     | skip optional release validation tasks; version/source checks remain mandatory                |
+| `--no-release-notes`                  | skip writing docs/releases notes (Genie and git-log fallback)                                 |
+| `--demo-deploy`                       | after tagging, stage and deploy the AppKit demo app (off by default)                          |
 | `--no-local-publish`                  | skip publishing to configured local registries                                                |
 | `--local-registry <auto\|false\|url>` | local npm registry selection (default: "auto")                                                |
 | `--local-pypi <auto\|false\|url>`     | local devpi registry selection (default: "auto")                                              |

package/index.ts

@@ -3,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.58";
+export const PACKAGE_VERSION = "0.9.61";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -29,6 +29,7 @@ export * as release from "./src/release.ts";
 export * as releaseContext from "./src/release-context.ts";
 export * as releaseOptions from "./src/release-options.ts";
 export * as scaffold from "./src/scaffold.ts";
+export * as sharedCoreUsage from "./src/shared-core-usage.ts";
 export * as tags from "./src/tags.ts";
 export * as tsconfig from "./src/tsconfig.ts";
 export * as vscode from "./src/vscode.ts";
@@ -65,6 +66,8 @@ export type { ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.t
 export { RELEASE_VERSION } 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";
+export type { SharedCoreUsageKind, SharedCoreExportUsage } from "./src/shared-core-usage.ts";
 export { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS } from "./src/tags.ts";
 export type { PackageTag } from "./src/tags.ts";
 export { DBXToolsRootTsconfig } from "./src/tsconfig.ts";

package/package.json

@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "^0.9.58",
-    "@dbx-tools/path": "^0.9.58",
-    "@dbx-tools/shared-core": "^0.9.58",
+    "@dbx-tools/core": "^0.9.61",
+    "@dbx-tools/path": "^0.9.61",
+    "@dbx-tools/shared-core": "^0.9.61",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -54,7 +54,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.58",
+  "version": "0.9.61",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/_task-command.ts

@@ -69,6 +69,25 @@ export function captureTaskCommand(
   return result.exitCode === 0 ? (result.stdout?.trim() ?? "") : "";
 }
 
+/** Run a command with inherited output and return whether it exited successfully. */
+export function tryTaskCommand(
+  cwd: string,
+  command: string,
+  args: readonly string[],
+  options: TaskCommandOptions = {},
+): boolean {
+  return (
+    exec.spawnSync(executable(command), [...args], {
+      cwd,
+      env: options.env,
+      stdout: "inherit",
+      stderr: options.stderr ?? "inherit",
+      stdin: "ignore",
+      check: false,
+    }).exitCode === 0
+  );
+}
+
 /** Whether a quiet, non-interactive command exits successfully. */
 export function taskCommandSucceeds(
   cwd: string,

package/src/project-js.ts

@@ -275,7 +275,7 @@ export function projectReleaseBranch(project: DBXToolsJavaScriptProject): string
  */
 export function addPackageFiles(pkg: javascript.NodeProject, ...entries: string[]): void {
   const current = (pkg.package.manifest.files ?? []) as string[];
-  pkg.package.addField("files", [...new Set([...current, ...entries])]);
+  pkg.package.addField("files", [...object.sequence(current, entries).distinct()]);
 }
 
 /**
@@ -859,16 +859,45 @@ class GeneratedSource extends Component {
  * are the child's business - so `bun run build` at the root type-checked nothing
  * and ran no package tests. Compilation groups ordinary package tsconfigs into
  * a few TypeScript processes and runs custom package lifecycles alongside them.
- * Tests still use Bun's filtered workspace fan-out. Both read the current
- * workspace list from `package.json`, so a newly added member needs no re-synth.
- *
- * `*` matches every workspace MEMBER and never the root itself, so the test
- * task delegating to it cannot recurse. Members declared outside the scanned
- * package roots (`extraWorkspaceMembers`) are covered by both tasks.
+ * Tests use a small number of root runner groups, skip packages without tests,
+ * and expose focused, changed, unit, integration, and full tiers. The test task
+ * reads the current workspace list from `package.json`, so a newly added member
+ * needs no re-synth.
  */
 class WorkspaceValidationTasks extends Component {
   private configured = false;
 
+  public constructor(project: DBXToolsNodeProject | DBXToolsTypeScriptProject) {
+    super(project);
+    if (project.parent) return;
+    project.addTask("workspace:graph", {
+      description: "Write the workspace dependency and reverse-dependency graph",
+      execArgs: taskCommand("test-workspace.ts", "graph"),
+    });
+    project.addTask("test:focused", {
+      description: "Run tests for explicit workspace packages or paths",
+      execArgs: taskCommand("test-workspace.ts", "focused"),
+      receiveArgs: true,
+    });
+    project.addTask("test:changed", {
+      description: "Run tests for changed packages and their dependents",
+      execArgs: taskCommand("test-workspace.ts", "changed"),
+      receiveArgs: true,
+    });
+    project.addTask("test:unit", {
+      description: "Run unit tests in grouped root runners",
+      execArgs: taskCommand("test-workspace.ts", "unit"),
+    });
+    project.addTask("test:integration", {
+      description: "Run integration and packed-consumer tests",
+      execArgs: taskCommand("test-workspace.ts", "integration"),
+    });
+    project.addTask("test:all", {
+      description: "Run all JavaScript, TypeScript, and Python tests",
+      execArgs: taskCommand("test-workspace.ts", "all"),
+    });
+  }
+
   public override preSynthesize(): void {
     if (this.configured) return;
     this.configured = true;
@@ -877,7 +906,7 @@ class WorkspaceValidationTasks extends Component {
       return;
     }
     project.compileTask.execArgs(taskCommand("compile-workspace.ts"));
-    project.testTask.exec("bun run --filter '*' test");
+    project.testTask.spawn(project.tasks.tryFind("test:all")!);
   }
 }
 
@@ -1253,7 +1282,7 @@ function initProject(
   // agnostic floor is set in the child's constructor; per-tag deps/tsconfig come from
   // the PACKAGE_TAG_MIXINS applied across the subtree below.
   for (const p of scanPackages(rootAbs, roots)) {
-    const tags = [...new Set([...p.tagCandidates, ...resolveTags(p, tagPaths)])];
+    const tags = [...object.sequence(p.tagCandidates, resolveTags(p, tagPaths)).distinct()];
     const found = existing.get(p.memberPath);
     if (found) {
       found.dbxToolsConfig.tags.push(...tags);
@@ -1272,7 +1301,7 @@ function initProject(
   }
 
   // The root project may itself carry tags (via a `""`/`"."` tag-path key).
-  const rootTags = [...new Set([...(tagPaths[""] ?? []), ...(tagPaths["."] ?? [])])];
+  const rootTags = [...object.sequence(tagPaths[""], tagPaths["."]).distinct()];
   if (rootTags.length) project.dbxToolsConfig.tags.push(...rootTags);
 
   // Apply per-tag mixins across the whole subtree now that every child exists

package/src/shared-core-usage.ts

@@ -0,0 +1,190 @@
+/**
+ * Runtime-export usage for `@dbx-tools/shared-core`.
+ *
+ * Classifies each live export as production, test, package-internal, generated
+ * binding, or unused. The report is informational; architecture tests fail only
+ * unused exports and duplicated owned helpers.
+ */
+import { readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { find } from "@dbx-tools/path";
+import * as core from "@dbx-tools/shared-core";
+import { PACKAGE_IDENTIFIER, object } from "@dbx-tools/shared-core";
+import { PYTHON_GENERATED_PACKAGE } from "./generated.ts";
+import { readPackageManifest, recordedPackages, repoRoot } from "./packages.ts";
+
+/** How one runtime export is referenced in this repository. */
+export type SharedCoreUsageKind = "production" | "test" | "internal" | "binding" | "unused";
+
+/** One classified shared-core runtime export. */
+export interface SharedCoreExportUsage {
+  readonly id: string;
+  readonly namespace: string;
+  readonly name: string;
+  readonly kind: SharedCoreUsageKind;
+  readonly files: readonly string[];
+}
+
+/** Binding-safe wrappers called from generated Python even without TS imports. */
+export const SHARED_CORE_BINDING_EXPORTS = [
+  "bindings.logActiveLevel",
+  "bindings.logLevelEnabled",
+] as const;
+
+const SOURCE_PATTERN = "**/*.{ts,tsx,js,mjs}";
+const NAMESPACE_EXPORT = /^export \* as (\w+) from "\.\/src\/([^"]+)\.ts";$/gm;
+const LOCAL_OWNED_HELPER =
+  /(?:export\s+)?(?:async\s+)?function(?:\s*\*)?\s+(isRecord|sleep|escapeRegExp|trimToNull|trimToUndefined|trimToEmpty)\s*\(|(?:export\s+)?const\s+(isRecord|sleep|escapeRegExp|trimToNull|trimToUndefined|trimToEmpty)\s*=/g;
+
+/** Owners of the shared helpers; other files must import them. */
+const OWNED_HELPER_FILES = new Set([
+  "packages/js/shared/core/src/object.ts",
+  "packages/js/shared/core/src/async-utils.ts",
+  "packages/js/shared/core/src/pattern.ts",
+  "packages/js/shared/core/src/string-utils.ts",
+  "docs/scripts/repository-docs.mjs",
+]);
+
+export function sharedCorePackageDir(root: string = repoRoot): string {
+  for (const pkg of recordedPackages(root)) {
+    if (readPackageManifest(pkg.dir)?.name === PACKAGE_IDENTIFIER) return pkg.dir;
+  }
+  throw new Error(`workspace package ${PACKAGE_IDENTIFIER} is missing`);
+}
+
+function namespaceMap(coreDir: string): Readonly<Record<string, string>> {
+  const barrel = readFileSync(join(coreDir, "index.ts"), "utf8");
+  return Object.fromEntries(
+    [...barrel.matchAll(NAMESPACE_EXPORT)].map((match) => [match[1]!, match[2]!]),
+  );
+}
+
+function sourceFiles(root: string, includeGenerated: boolean): string[] {
+  const ignore = [
+    "**/node_modules/**",
+    "**/lib/**",
+    "**/.docs-build/**",
+    // Bundled PythonMonkey runtimes inline shared-core; they are not local copies.
+    "**/node_runtime/runtime.js",
+    "**/_runtime.js",
+  ];
+  if (!includeGenerated) ignore.push(`**/${PYTHON_GENERATED_PACKAGE}/**`);
+  return [...find.findFiles(SOURCE_PATTERN, { cwd: root, ignore })].sort();
+}
+
+function classifyFile(
+  relativePath: string,
+  coreDirRel: string,
+): Exclude<SharedCoreUsageKind, "unused"> {
+  if (relativePath.includes(`/${PYTHON_GENERATED_PACKAGE}/`)) return "binding";
+  if (relativePath.startsWith(`${coreDirRel}/src/`)) return "internal";
+  if (/(?:^|\/)(?:test|tests)\//.test(relativePath) || relativePath.includes(".test.")) {
+    return "test";
+  }
+  return "production";
+}
+
+function preferKind(
+  current: SharedCoreUsageKind,
+  next: Exclude<SharedCoreUsageKind, "unused">,
+): SharedCoreUsageKind {
+  const rank: Record<SharedCoreUsageKind, number> = {
+    production: 0,
+    binding: 1,
+    internal: 2,
+    test: 3,
+    unused: 4,
+  };
+  return rank[next] < rank[current] ? next : current;
+}
+
+function mentionsExport(
+  source: string,
+  namespace: string,
+  name: string,
+  moduleFile: string,
+): boolean {
+  if (source.includes(`${namespace}.${name}`)) return true;
+  const imported =
+    source.includes(`from "@dbx-tools/shared-core/${moduleFile}"`) ||
+    source.includes(`from "./${moduleFile}.ts"`) ||
+    source.includes(`from "../src/${moduleFile}.ts"`);
+  if (!imported) return false;
+  return new RegExp(`\\b${name}\\b`).test(source);
+}
+
+/** Classify every namespace runtime export against repository callers. */
+export function sharedCoreExportUsage(root: string = repoRoot): SharedCoreExportUsage[] {
+  const coreDir = sharedCorePackageDir(root);
+  const coreDirRel = relative(root, coreDir);
+  const namespaces = namespaceMap(coreDir);
+  const files = sourceFiles(root, true).map((file) => ({
+    path: relative(root, file),
+    text: readFileSync(file, "utf8"),
+  }));
+  const usage: SharedCoreExportUsage[] = [];
+  for (const [namespace, moduleFile] of Object.entries(namespaces)) {
+    const exported = core[namespace as keyof typeof core];
+    if (!exported || typeof exported !== "object") continue;
+    for (const name of Object.keys(exported).sort()) {
+      if (name === "__esModule" || name === "default") continue;
+      const id = `${namespace}.${name}`;
+      const defining = `${coreDirRel}/src/${moduleFile}.ts`;
+      const matches = files
+        .filter(({ path, text }) => {
+          if (path === defining) {
+            return (text.match(new RegExp(`\\b${name}\\b`, "g"))?.length ?? 0) > 1;
+          }
+          return mentionsExport(text, namespace, name, moduleFile);
+        })
+        .map(({ path }) => path);
+      let kind: SharedCoreUsageKind = "unused";
+      if (
+        SHARED_CORE_BINDING_EXPORTS.includes(id as (typeof SHARED_CORE_BINDING_EXPORTS)[number])
+      ) {
+        kind = "binding";
+      }
+      for (const file of matches) kind = preferKind(kind, classifyFile(file, coreDirRel));
+      usage.push({ id, namespace, name, kind, files: matches });
+    }
+  }
+  return usage.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+/** Local copies of helpers owned by shared-core. */
+export function duplicatedOwnedHelpers(root: string = repoRoot): string[] {
+  const duplicates: string[] = [];
+  for (const file of sourceFiles(root, false)) {
+    const relativePath = relative(root, file);
+    if (OWNED_HELPER_FILES.has(relativePath)) continue;
+    if (relativePath.startsWith("packages/js/shared/core/test/")) continue;
+    const text = readFileSync(file, "utf8");
+    LOCAL_OWNED_HELPER.lastIndex = 0;
+    if (LOCAL_OWNED_HELPER.test(text)) duplicates.push(relativePath);
+  }
+  return duplicates.sort();
+}
+
+/** Render a compact usage table for `shared-core:usage`. */
+export function formatSharedCoreUsage(usage: readonly SharedCoreExportUsage[]): string {
+  const counts = object.sequence(usage).group({
+    production: (row) => row.kind === "production",
+    binding: (row) => row.kind === "binding",
+    internal: (row) => row.kind === "internal",
+    test: (row) => row.kind === "test",
+    unused: (row) => row.kind === "unused",
+  });
+  const lines = [
+    `shared-core runtime exports: ${usage.length}`,
+    `  production ${counts.production.length}`,
+    `  binding ${counts.binding.length}`,
+    `  internal ${counts.internal.length}`,
+    `  test ${counts.test.length}`,
+    `  unused ${counts.unused.length}`,
+  ];
+  if (counts.unused.length > 0) {
+    lines.push("unused:");
+    for (const row of counts.unused) lines.push(`  ${row.id}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/tasks/publish.ts

@@ -46,7 +46,7 @@
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { asyncUtils, log } from "@dbx-tools/shared-core";
+import { asyncUtils, log, object } from "@dbx-tools/shared-core";
 import {
   applyPublishConfig,
   npmReleaseMatches,
@@ -169,7 +169,9 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
         `${pkg.name ?? dirname(dir)} has invalid publishConfig.access ${String(access)}`,
       );
     }
-    const compiledTargets = [...new Set(compiledPublishTargets(pkg.publishConfig))];
+    const compiledTargets = [
+      ...object.sequence(compiledPublishTargets(pkg.publishConfig)).distinct(),
+    ];
     publishable.push({
       dir,
       name: pkg.name ?? dirname(dir),

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

@@ -2,7 +2,7 @@
 /** Keep every configured Python Node bridge current with one repository watcher. */
 import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { log } from "@dbx-tools/shared-core";
+import { log, object } from "@dbx-tools/shared-core";
 import { runTaskCommand } from "../src/_task-command.ts";
 import { repoRoot } from "../src/packages.ts";
 import {
@@ -41,7 +41,7 @@ function watchPaths(configs: readonly ResolvedPythonNodeBindings[]): string[] {
   const explicitInputs = configs
     .flatMap(pythonNodeBindingWatchInputs)
     .filter((input) => !covered.some((root) => containsPath(root, input)));
-  return [...new Set([...covered, ...explicitInputs])].sort();
+  return [...object.sequence(covered, explicitInputs).distinct()].sort();
 }
 
 function selection(

package/tasks/python-registry.ts

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { net } from "@dbx-tools/shared-core";
+import { net, stringUtils } from "@dbx-tools/shared-core";
 import { parse } from "smol-toml";
 import { captureTaskCommand } from "../src/_task-command.ts";
 
@@ -120,12 +120,6 @@ export function devpiRegistry(index: string): LocalPythonRegistry | undefined {
   };
 }
 
-/** Split a whitespace-separated index list (the pip/uv env-var form). */
-function splitIndexList(value: string | undefined): string[] {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed.split(/\s+/) : [];
-}
-
 /** Read a `pip config get <key>`, treating pip's literal "undefined" as unset. */
 function pipConfig(key: string): string | undefined {
   const out = captureTaskCommand(process.cwd(), "python", ["-m", "pip", "config", "get", key]);
@@ -153,8 +147,8 @@ export function activePythonIndexes(): string[] {
   // uv: env vars first (primary, then extras), then uv.toml's index blocks.
   add(process.env.UV_DEFAULT_INDEX);
   add(process.env.UV_INDEX_URL);
-  for (const url of splitIndexList(process.env.UV_INDEX)) add(url);
-  for (const url of splitIndexList(process.env.UV_EXTRA_INDEX_URL)) add(url);
+  for (const url of stringUtils.parseList(process.env.UV_INDEX)) add(url);
+  for (const url of stringUtils.parseList(process.env.UV_EXTRA_INDEX_URL)) add(url);
   const uvConfig = process.env.UV_CONFIG_FILE ?? resolve(homedir(), ".config/uv/uv.toml");
   if (existsSync(uvConfig)) {
     for (const url of parseUvIndexes(readFileSync(uvConfig, "utf8"))) add(url);
@@ -162,9 +156,9 @@ export function activePythonIndexes(): string[] {
 
   // pip: env vars (primary + extras), then `pip config` (index-url + extra-index-url).
   add(process.env.PIP_INDEX_URL);
-  for (const url of splitIndexList(process.env.PIP_EXTRA_INDEX_URL)) add(url);
+  for (const url of stringUtils.parseList(process.env.PIP_EXTRA_INDEX_URL)) add(url);
   add(pipConfig("global.index-url"));
-  for (const url of splitIndexList(pipConfig("global.extra-index-url"))) add(url);
+  for (const url of stringUtils.parseList(pipConfig("global.extra-index-url"))) add(url);
 
   return out;
 }

package/tasks/release-notes.ts

@@ -0,0 +1,97 @@
+/**
+ * Write user-facing release notes under `docs/releases/` during `bun run release`.
+ *
+ * Prefers Genie Code (`dbx genie exec`). When that fails or writes an empty
+ * file, falls back to a short git-log summary so the release still commits notes.
+ *
+ * @module
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { log } from "@dbx-tools/shared-core";
+
+import { captureTaskCommand, tryTaskCommand } from "../src/_task-command.ts";
+
+const logger = log.logger("projen:release-notes");
+
+const GENIE_PROMPT =
+  "Compare HEAD and the working tree against the latest v* tag. Produce concise user-facing release notes. Ignore generated-file churn and test-only changes. Include breaking changes, fixes, and validation results. Do not modify files.";
+
+/** Inputs for one notes write. */
+export interface WriteReleaseNotesOptions {
+  readonly prefix: string;
+  readonly root: string;
+  readonly version: string;
+  /** Override Genie invocation; return false to force the git-log fallback. */
+  readonly runGenie?: (args: readonly string[]) => boolean;
+}
+
+/** Path of the notes file for one workspace version. */
+export function releaseNotesPath(root: string, version: string): string {
+  return join(root, "docs", "releases", `v${version}.md`);
+}
+
+/** Short markdown notes from commit subjects since the previous matching tag. */
+export function fallbackReleaseNotes(
+  version: string,
+  commits: readonly string[],
+  previousTag?: string,
+): string {
+  const range = previousTag ? `since ${previousTag}` : "in this release";
+  const items =
+    commits.length > 0
+      ? commits.map((subject) => `- ${subject}`).join("\n")
+      : "- Version bump and synchronized package metadata.";
+  return `# Release ${version}\n\ndbx-tools ${version} ${range}.\n\n${items}\n`;
+}
+
+/** Run Genie into `docs/releases/vX.Y.Z.md`, or write {@link fallbackReleaseNotes}. */
+export function writeReleaseNotes(options: WriteReleaseNotesOptions): string {
+  const { prefix, root, version } = options;
+  const destination = releaseNotesPath(root, version);
+  mkdirSync(dirname(destination), { recursive: true });
+  const relative = join("docs", "releases", `v${version}.md`);
+  const genieArgs = [
+    "exec",
+    "-C",
+    root,
+    "--sandbox",
+    "read-only",
+    "--ephemeral",
+    "-o",
+    relative,
+    GENIE_PROMPT,
+  ] as const;
+  const ran =
+    options.runGenie?.([...genieArgs]) ??
+    tryTaskCommand(root, "bun", ["run", "dbx", "genie", ...genieArgs]);
+  if (ran && readNotes(destination)) {
+    logger.info("wrote Genie release notes", { path: relative });
+    return destination;
+  }
+  const previousTag = captureTaskCommand(root, "git", [
+    "describe",
+    "--tags",
+    "--abbrev=0",
+    `--match=${prefix}*`,
+  ]);
+  const logArgs = previousTag
+    ? ["log", "--no-merges", "--pretty=format:%s", `${previousTag}..HEAD`]
+    : ["log", "--no-merges", "--pretty=format:%s", "-15"];
+  const commits = captureTaskCommand(root, "git", logArgs)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  writeFileSync(destination, fallbackReleaseNotes(version, commits, previousTag || undefined));
+  logger.warn("Genie release notes unavailable; wrote git-log summary", { path: relative });
+  return destination;
+}
+
+function readNotes(path: string): string {
+  try {
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return "";
+  }
+}

package/tasks/release.ts

@@ -4,6 +4,7 @@ import * as projectUtils from "@dbx-tools/core/project-utils";
 import { log } from "@dbx-tools/shared-core";
 import { Command, Option } from "commander";
 import { publishLocalRelease } from "./local-publish.ts";
+import { writeReleaseNotes } from "./release-notes.ts";
 import { assertReleaseVersion } from "./release-version.ts";
 import { captureTaskCommand, runTaskCommand, taskCommandSucceeds } from "../src/_task-command.ts";
 import {
@@ -105,6 +106,11 @@ export async function runRelease(
     readonly install?: ReleaseInstallMode;
     readonly pythonRoot?: string;
     readonly validationTasks?: readonly string[];
+    /** After tagging, stage and deploy the AppKit demo app. Off by default. */
+    readonly demoDeploy?: boolean;
+    /** Write `docs/releases/vX.Y.Z.md` via Genie, with a git-log fallback. On by default. */
+    readonly releaseNotes?: boolean;
+    readonly writeReleaseNotes?: typeof writeReleaseNotes;
   },
 ): Promise<string> {
   const { branch, prefix, remote, root } = options;
@@ -125,6 +131,9 @@ export async function runRelease(
   const version = readWorkspaceVersion(root);
   const tag = `${prefix}${version}`;
   assertReleaseVersion(version, { root, prefixes: [prefix], assertNext: true });
+  if ((options.releaseNotes ?? true) && (options.bump ?? true)) {
+    (options.writeReleaseNotes ?? writeReleaseNotes)({ prefix, root, version });
+  }
 
   if (taskCommandSucceeds(root, "git", ["rev-parse", "--verify", `refs/tags/${tag}`])) {
     throw new Error(`release tag ${tag} already exists`);
@@ -190,6 +199,10 @@ export async function runRelease(
     });
   }
 
+  if (options.demoDeploy) {
+    runTaskCommand(root, "bun", ["run", "demo:deploy"]);
+  }
+
   return tag;
 }
 
@@ -228,6 +241,8 @@ export function createReleaseCommand(): Command {
       "--no-validation",
       "skip optional release validation tasks; version/source checks remain mandatory",
     )
+    .option("--no-release-notes", "skip writing docs/releases notes (Genie and git-log fallback)")
+    .option("--demo-deploy", "after tagging, stage and deploy the AppKit demo app (off by default)")
     .option("--no-local-publish", "skip publishing to configured local registries")
     .option("--local-registry <auto|false|url>", "local npm registry selection", "auto")
     .option("--local-pypi <auto|false|url>", "local devpi registry selection", "auto")
@@ -245,6 +260,8 @@ export function createReleaseCommand(): Command {
           localPypi: string;
           install: ReleaseInstallMode;
           validate: string[];
+          demoDeploy?: boolean;
+          releaseNotes?: boolean;
         },
       ) => {
         await runRelease({
@@ -264,6 +281,8 @@ export function createReleaseCommand(): Command {
           docs: options.docs,
           validation: options.validation,
           validationTasks: options.validate,
+          demoDeploy: options.demoDeploy,
+          releaseNotes: options.releaseNotes,
         });
       },
     );

package/tasks/shared-core-usage.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env -S bun
+/** Print shared-core runtime-export usage by caller kind. */
+import { formatSharedCoreUsage, sharedCoreExportUsage } from "../src/shared-core-usage.ts";
+
+process.stdout.write(formatSharedCoreUsage(sharedCoreExportUsage()));

package/tasks/test-workspace.ts

@@ -0,0 +1,253 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve, sep } from "node:path";
+import * as exec from "@dbx-tools/core/exec";
+import { log, object } from "@dbx-tools/shared-core";
+
+const logger = log.logger("projen:test");
+
+interface PackageManifest {
+  readonly name?: string;
+  readonly workspaces?: readonly string[];
+  readonly dependencies?: Readonly<Record<string, string>>;
+  readonly optionalDependencies?: Readonly<Record<string, string>>;
+  readonly peerDependencies?: Readonly<Record<string, string>>;
+  readonly devDependencies?: Readonly<Record<string, string>>;
+}
+
+export interface WorkspaceGraphPackage {
+  readonly name: string;
+  readonly path: string;
+  readonly dependencies: readonly string[];
+  readonly reverseDependencies: readonly string[];
+}
+
+export interface WorkspaceGraph {
+  readonly packages: readonly WorkspaceGraphPackage[];
+}
+
+type TestMode = "focused" | "changed" | "unit" | "integration" | "all" | "graph";
+
+const PROJEN_INTEGRATION_TEST =
+  /(?:local-publish|npm-release|packed-consumer|project-py|publish|python-sync|release|root-install|sdk-boundary).*\.test\.ts$/;
+
+function readJson<T>(path: string): T {
+  return JSON.parse(readFileSync(path, "utf8")) as T;
+}
+
+function toPosix(path: string): string {
+  return path.split(sep).join("/");
+}
+
+export function workspaceGraph(root: string): WorkspaceGraph {
+  const workspace = readJson<PackageManifest>(join(root, "package.json"));
+  const packages = new Map<string, { path: string; manifest: PackageManifest }>();
+  for (const member of workspace.workspaces ?? []) {
+    const manifest = readJson<PackageManifest>(join(root, member, "package.json"));
+    if (manifest.name) packages.set(manifest.name, { path: toPosix(member), manifest });
+  }
+  const reverse = new Map<string, Set<string>>();
+  const rows = [...packages].map(([name, pkg]) => {
+    const dependencies = new Set<string>();
+    for (const field of [
+      "dependencies",
+      "optionalDependencies",
+      "peerDependencies",
+      "devDependencies",
+    ] as const) {
+      for (const dependency of Object.keys(pkg.manifest[field] ?? {})) {
+        if (!packages.has(dependency)) continue;
+        dependencies.add(dependency);
+        const dependents = reverse.get(dependency) ?? new Set<string>();
+        dependents.add(name);
+        reverse.set(dependency, dependents);
+      }
+    }
+    return { name, path: pkg.path, dependencies: [...dependencies].sort() };
+  });
+  return {
+    packages: rows
+      .map((pkg) => ({
+        ...pkg,
+        reverseDependencies: [...(reverse.get(pkg.name) ?? [])].sort(),
+      }))
+      .sort((left, right) => left.name.localeCompare(right.name)),
+  };
+}
+
+function writeGraph(root: string, graph: WorkspaceGraph): void {
+  const path = join(root, ".projen", "workspace-graph.json");
+  writeFileSync(path, `${JSON.stringify(graph, null, 2)}\n`);
+  logger.info(`wrote ${relative(root, path)}`);
+}
+
+function testFiles(directory: string): string[] {
+  if (!existsSync(directory)) return [];
+  const files: string[] = [];
+  const visit = (current: string): void => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) visit(path);
+      else if (/\.(?:test|spec)\.tsx?$/.test(entry.name)) files.push(path);
+    }
+  };
+  visit(directory);
+  return files.sort();
+}
+
+function integrationTest(path: string): boolean {
+  return (
+    path.includes(".integration.test.") ||
+    (toPosix(path).includes("/projen/test/") && PROJEN_INTEGRATION_TEST.test(basename(path)))
+  );
+}
+
+function packageForPath(graph: WorkspaceGraph, path: string): WorkspaceGraphPackage | undefined {
+  const normalized = toPosix(path);
+  return [...graph.packages]
+    .sort((left, right) => right.path.length - left.path.length)
+    .find((pkg) => normalized === pkg.path || normalized.startsWith(`${pkg.path}/`));
+}
+
+function affectedPackages(graph: WorkspaceGraph, changed: readonly string[]): Set<string> {
+  const byName = new Map(graph.packages.map((pkg) => [pkg.name, pkg]));
+  const affected = new Set<string>();
+  const pending: string[] = [];
+  for (const path of changed) {
+    const pkg = packageForPath(graph, path);
+    if (!pkg) return new Set(graph.packages.map((entry) => entry.name));
+    if (!affected.has(pkg.name)) pending.push(pkg.name);
+  }
+  while (pending.length > 0) {
+    const name = pending.pop()!;
+    if (affected.has(name)) continue;
+    affected.add(name);
+    pending.push(...(byName.get(name)?.reverseDependencies ?? []));
+  }
+  return affected;
+}
+
+function changedFiles(root: string, base?: string): string[] {
+  const candidates = base ? [base] : ["origin/main", "main", "HEAD~1"];
+  let committed: string[] = [];
+  for (const candidate of candidates) {
+    const result = exec.spawnSync("git", ["diff", "--name-only", `${candidate}...HEAD`], {
+      cwd: root,
+      stdin: "ignore",
+      stdout: "capture",
+      stderr: "ignore",
+    });
+    if (result.exitCode === 0) {
+      committed = result.stdoutLines.filter(Boolean);
+      break;
+    }
+  }
+  const working = exec.spawnSync("git", ["diff", "--name-only", "HEAD"], {
+    cwd: root,
+    stdin: "ignore",
+    stdout: "capture",
+    stderr: "ignore",
+    check: true,
+  }).stdoutLines;
+  return [...object.sequence(committed, working).filter(Boolean).distinct()].sort();
+}
+
+function selectedTests(
+  root: string,
+  graph: WorkspaceGraph,
+  mode: TestMode,
+  args: readonly string[],
+): string[] {
+  const all = [
+    ...graph.packages.flatMap((pkg) => testFiles(join(root, pkg.path, "test"))),
+    ...testFiles(join(root, "docs/scripts")),
+  ];
+  if (mode === "unit") return all.filter((path) => !integrationTest(path));
+  if (mode === "integration") return all.filter(integrationTest);
+  if (mode === "all") return all;
+
+  let names: Set<string>;
+  if (mode === "changed") {
+    const baseIndex = args.indexOf("--base");
+    const changed = changedFiles(root, baseIndex >= 0 ? args[baseIndex + 1] : undefined);
+    if (changed.length === 0) return [];
+    names = affectedPackages(graph, changed);
+  } else {
+    if (args.length === 0) throw new Error("test:focused requires a package name or path");
+    names = new Set<string>();
+    for (const value of args) {
+      const direct = graph.packages.find((pkg) => pkg.name === value);
+      const byPath = direct ?? packageForPath(graph, toPosix(relative(root, resolve(root, value))));
+      if (!byPath) throw new Error(`Unknown workspace package or path: ${value}`);
+      names.add(byPath.name);
+    }
+  }
+  const paths = new Set(graph.packages.filter((pkg) => names.has(pkg.name)).map((pkg) => pkg.path));
+  return all.filter((path) => {
+    const relativePath = toPosix(relative(root, path));
+    return [...paths].some((pkg) => relativePath.startsWith(`${pkg}/`));
+  });
+}
+
+function runnerGroup(root: string, path: string): string {
+  const relativePath = toPosix(relative(root, path));
+  if (relativePath.startsWith("packages/js/shared/")) return "browser-shared";
+  if (
+    relativePath.startsWith("packages/js/ui/") ||
+    relativePath.startsWith("packages/example/app/")
+  ) {
+    return "react-ui";
+  }
+  if (relativePath.startsWith("projen/")) return "projen";
+  if (relativePath.startsWith("docs/scripts/")) return "docs";
+  if (relativePath.startsWith("packages/example/")) return "examples";
+  return "node";
+}
+
+async function runTests(root: string, files: readonly string[]): Promise<void> {
+  if (files.length === 0) {
+    logger.info("no tests selected");
+    return;
+  }
+  const groups = new Map<string, string[]>();
+  for (const file of files) {
+    const name = runnerGroup(root, file);
+    const paths = groups.get(name) ?? [];
+    paths.push(relative(root, file));
+    groups.set(name, paths);
+  }
+  const started = performance.now();
+  const jobs = [...groups].map(async ([name, paths]) => {
+    const groupStarted = performance.now();
+    const result = await exec.spawn("bun", ["test", ...paths], {
+      cwd: root,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    const seconds = ((performance.now() - groupStarted) / 1000).toFixed(2);
+    logger.info(`${name}: ${paths.length} files in ${seconds}s`);
+    return { name, result };
+  });
+  const results = await Promise.all(jobs);
+  logger.info(
+    `selected tests: ${files.length} files in ${((performance.now() - started) / 1000).toFixed(2)}s`,
+  );
+  const failed = results.filter(({ result }) => result.exitCode !== 0);
+  if (failed.length > 0) {
+    throw new Error(`Test groups failed: ${failed.map(({ name }) => name).join(", ")}`);
+  }
+}
+
+export async function main(argv: readonly string[] = process.argv.slice(2)): Promise<void> {
+  const root = process.cwd();
+  const mode = (argv[0] ?? "all") as TestMode;
+  if (!["focused", "changed", "unit", "integration", "all", "graph"].includes(mode)) {
+    throw new Error(`Unknown test mode: ${mode}`);
+  }
+  const graph = workspaceGraph(root);
+  writeGraph(root, graph);
+  if (mode === "graph") return;
+  await runTests(root, selectedTests(root, graph, mode, argv.slice(1)));
+}
+
+if (import.meta.main) await main();

package/tasks/ui-bundle-sizes.ts

@@ -0,0 +1,22 @@
+import { resolve } from "node:path";
+
+const entries = {
+  auth: "packages/js/ui/appkit/src/auth/react/index.ts",
+  email: "packages/js/ui/appkit/src/email/react/index.ts",
+  search: "packages/js/ui/appkit/src/search/react/index.ts",
+} as const;
+
+for (const [name, entry] of Object.entries(entries)) {
+  const result = await Bun.build({
+    entrypoints: [resolve(entry)],
+    target: "browser",
+    minify: true,
+    sourcemap: "none",
+    external: ["react", "react-dom", "@databricks/*", "@dbx-tools/shared-*", "lucide-react"],
+  });
+  if (!result.success) {
+    throw new AggregateError(result.logs, `Could not build the ${name} UI subpath`);
+  }
+  const bytes = result.outputs.reduce((total, output) => total + output.size, 0);
+  console.log(`${name}: ${bytes} bytes`);
+}