@dbx-tools/projen 0.9.60 → 0.9.64

package/README.md

@@ -205,9 +205,11 @@ The workspace creates one repository-wide binding lifecycle:
 - `python-node-bindings` generates every configured bridge.
 - `python-node-bindings:check` verifies generated files and fails on stale
   `_generated/node` directories.
-- `python-node-bindings:watch` watches all configured bridges and regenerates
-  only Python projects affected by a Node package, transitive workspace
-  dependency, binding manifest, or function override change.
+- `python-node-bindings:watch` watches only configured module entrypoints and
+  their transitive workspace source imports. Tests, compiled output, generated
+  bindings, and unrelated modules do not trigger regeneration or acquire the
+  workspace mutation lock. Binding-manifest and generator changes regenerate
+  the affected projects and restart the watcher when its input graph changes.
 
 When a runtime owner is configured, the workspace also creates one shared
 runtime lifecycle:
@@ -481,12 +483,30 @@ 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
+bun run release --release-notes-instructions "Focus on operator-visible changes."
 ```
 
+`--demo-deploy` is off by default. After tagging and any local registry
+publication it runs `bun run demo:deploy`, which stages the AppKit demo
+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. `--release-notes-instructions` appends run-specific guidance to
+the standard Genie prompt. 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
-optional task checks locally and in CI, not version or immutable-source checks.
+installed while still regenerating versioned sources. Local release validation
+runs `eslint:fix` before branch preparation and bump, then runs the selected
+fail-closed tasks; CI remains check-only.
+`--no-validation` skips optional task checks locally and in CI, not version or immutable-source checks.
 `--no-docs` skips building and deploying the site, not package README validation.
 Scopes select artifacts, not the normal commit and tag-push transaction.
 The annotated tag records CI step selections, so publishing a selected scope does
@@ -553,6 +573,9 @@ 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)                                 |
+| `--release-notes-instructions <text>` | append custom instructions to the Genie release-notes prompt                                  |
+| `--demo-deploy`                       | after tagging, stage and deploy the AppKit demo app (off by default)                          |
 | `--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.60";
+export const PACKAGE_VERSION = "0.9.64";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";

package/package.json

@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "^0.9.60",
-    "@dbx-tools/path": "^0.9.60",
-    "@dbx-tools/shared-core": "^0.9.60",
+    "@dbx-tools/core": "^0.9.64",
+    "@dbx-tools/path": "^0.9.64",
+    "@dbx-tools/shared-core": "^0.9.64",
     "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.60",
+  "version": "0.9.64",
   "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/python-node-bindings.ts

@@ -1,10 +1,11 @@
 /** Shared pyproject-backed configuration for PythonMonkey Node bindings. */
-import { readFileSync, rmSync } from "node:fs";
+import { readFileSync, realpathSync, rmSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { find } from "@dbx-tools/path";
 import { object, stringUtils } from "@dbx-tools/shared-core";
 import { parse } from "smol-toml";
+import ts from "typescript";
 import { runTaskCommand } from "./_task-command.ts";
 import { resolveRepoRoot, workspaceDependencyDirectories } from "./packages.ts";
 
@@ -29,6 +30,7 @@ export interface ResolvedPythonNodeBindings {
   readonly projectDirectory: string;
   readonly pyproject: string;
   readonly runtimeOutput: string;
+  readonly watchInputs: readonly string[];
   readonly workspaceDirectories: readonly string[];
 }
 
@@ -152,7 +154,7 @@ export function resolvePythonNodeBindings(
     }
     const bindingName = nodePackageName(packageName);
     const bindingDirectory = join(moduleDirectory, "_generated", "node", bindingName);
-    return {
+    const resolved = {
       project,
       projectDirectory,
       pyproject,
@@ -177,11 +179,85 @@ export function resolvePythonNodeBindings(
       }),
       workspaceDirectories: workspaceDependencyDirectories(packageName, root),
     };
+    return {
+      ...resolved,
+      watchInputs: bindingSourceInputs(root, resolved),
+    };
   });
   validateBindings(configs);
   return configs;
 }
 
+type BindingSourceConfig = Omit<ResolvedPythonNodeBindings, "watchInputs">;
+
+/** Transitive workspace source files reachable from configured binding modules. */
+function bindingSourceInputs(root: string, config: BindingSourceConfig): string[] {
+  const allowed = config.workspaceDirectories.map(canonicalPath);
+  const packageEntrypoint = Bun.resolveSync(config.entrypoint, config.projectDirectory);
+  const entrypoints =
+    config.modules.length > 0
+      ? config.modules.map((module) => resolvePythonNodeBindingModule(packageEntrypoint, module))
+      : [packageEntrypoint];
+  const pending = [
+    ...entrypoints,
+    ...config.functionOverrides.map(({ handlerFile }) => handlerFile),
+  ];
+  const visited = new Set<string>();
+  while (pending.length > 0) {
+    const candidate = canonicalPath(pending.pop()!);
+    if (
+      visited.has(candidate) ||
+      !allowed.some((directory) => containsResolvedPath(directory, candidate))
+    ) {
+      continue;
+    }
+    visited.add(candidate);
+    let source: string;
+    try {
+      source = readFileSync(candidate, "utf8");
+    } catch {
+      continue;
+    }
+    const dependencies = ts.preProcessFile(source, true, true).importedFiles;
+    for (const dependency of dependencies) {
+      try {
+        pending.push(Bun.resolveSync(dependency.fileName, dirname(candidate)));
+      } catch {
+        // Built-ins and external packages are outside the workspace source graph.
+      }
+    }
+  }
+  return [...visited].sort().map((path) => relative(root, path));
+}
+
+/** Resolve one configured namespace from a package entrypoint barrel. */
+export function resolvePythonNodeBindingModule(entrypoint: string, module: string): string {
+  if (!/^[$A-Z_a-z][$\w]*$/.test(module)) {
+    throw new Error(`Node binding module must be a TypeScript identifier: ${module}`);
+  }
+  const source = readFileSync(entrypoint, "utf8");
+  const escaped = module.replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+  const match = new RegExp(`export\\s+\\*\\s+as\\s+${escaped}\\s+from\\s+["']([^"']+)["']`).exec(
+    source,
+  );
+  if (!match?.[1]) {
+    throw new Error(`${entrypoint} does not export namespace ${module}`);
+  }
+  return Bun.resolveSync(match[1], dirname(entrypoint));
+}
+
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+function containsResolvedPath(parent: string, candidate: string): boolean {
+  return candidate === parent || candidate.startsWith(`${parent}${sep}`);
+}
+
 /** All paths that can change a workspace-backed generated Node runtime. */
 export function pythonNodeBindingWatchInputs(config: ResolvedPythonNodeBindings): string[] {
   if (config.workspaceDirectories.length === 0) {
@@ -189,7 +265,7 @@ export function pythonNodeBindingWatchInputs(config: ResolvedPythonNodeBindings)
   }
   return [
     config.pyproject,
-    ...config.workspaceDirectories,
+    ...config.watchInputs,
     ...config.functionOverrides.map(({ handlerFile }) => handlerFile),
   ];
 }

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

@@ -1,8 +1,8 @@
 #!/usr/bin/env -S bun
 /** Keep every configured Python Node bridge current with one repository watcher. */
-import { dirname, resolve, sep } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { log, object } from "@dbx-tools/shared-core";
+import { log } from "@dbx-tools/shared-core";
 import { runTaskCommand } from "../src/_task-command.ts";
 import { repoRoot } from "../src/packages.ts";
 import {
@@ -12,36 +12,24 @@ import {
   resolveAllPythonNodeBindings,
   type ResolvedPythonNodeBindings,
 } from "../src/python-node-bindings.ts";
-import { watchLoop, watchRoots } from "../src/watch.ts";
+import { watchLoop } from "../src/watch.ts";
 import { withWorkspaceMutationLock } from "../src/workspace-lock.ts";
 
 const logger = log.logger("projen:python-node-bindings-watch");
 const generator = fileURLToPath(new URL("./python-node-bindings.ts", import.meta.url));
+const watcher = fileURLToPath(import.meta.url);
+const bindingSource = fileURLToPath(new URL("../src/python-node-bindings.ts", import.meta.url));
+const toolingInputs = [generator, watcher, bindingSource];
 
 function generate(project: string): void {
   runTaskCommand(repoRoot, "bun", [generator, "--root", repoRoot, "--project", project]);
 }
 
-function containsPath(parent: string, candidate: string): boolean {
-  const resolvedParent = resolve(parent);
-  const resolvedCandidate = resolve(candidate);
-  return (
-    resolvedCandidate === resolvedParent || resolvedCandidate.startsWith(`${resolvedParent}${sep}`)
-  );
-}
-
 /**
- * Watch broad package roots, each configured Python workspace root, and only
- * exceptional inputs such as function overrides that live outside those roots.
+ * Watch only configured manifests and transitive workspace source inputs.
  */
 function watchPaths(configs: readonly ResolvedPythonNodeBindings[]): string[] {
-  const roots = watchRoots();
-  const pythonRoots = configs.map(({ projectDirectory }) => dirname(projectDirectory));
-  const covered = [...roots, ...pythonRoots];
-  const explicitInputs = configs
-    .flatMap(pythonNodeBindingWatchInputs)
-    .filter((input) => !covered.some((root) => containsPath(root, input)));
-  return [...object.sequence(covered, explicitInputs).distinct()].sort();
+  return [...new Set([...configs.flatMap(pythonNodeBindingWatchInputs), ...toolingInputs])].sort();
 }
 
 function selection(
@@ -51,14 +39,20 @@ function selection(
   readonly all: boolean;
   readonly configs: ResolvedPythonNodeBindings[];
   readonly projects: string[];
+  readonly restart: boolean;
 } {
   const configs = resolveAllPythonNodeBindings(repoRoot);
   const manifests = new Set([...previous, ...configs].map(({ pyproject }) => resolve(pyproject)));
-  const all = changed.some((path) => manifests.has(resolve(path)));
+  const all = changed.some(
+    (path) =>
+      manifests.has(resolve(path)) ||
+      toolingInputs.some((input) => resolve(input) === resolve(path)),
+  );
   return {
     all,
     configs,
     projects: all ? [] : affectedPythonNodeBindingProjects(repoRoot, configs, changed),
+    restart: watchPaths(previous).join("\n") !== watchPaths(configs).join("\n"),
   };
 }
 
@@ -77,11 +71,15 @@ export async function main(): Promise<void> {
       if (next.all) {
         generatePythonNodeBindings(repoRoot);
         logger.success("regenerated all Python Node bindings");
-        return;
+      } else {
+        for (const project of next.projects) {
+          generate(project);
+          logger.success(`regenerated ${project} Node bindings`);
+        }
       }
-      for (const project of next.projects) {
-        generate(project);
-        logger.success(`regenerated ${project} Node bindings`);
+      if (next.restart) {
+        logger.info("binding inputs changed; restarting watcher");
+        setTimeout(() => process.exit(0), 0);
       }
     },
     {

package/tasks/python-node-bindings.ts

@@ -16,6 +16,7 @@ import { publicFunctionExports, publicNamespaceExports } from "../src/module-exp
 import { resolveRepoRoot } from "../src/packages.ts";
 import {
   generatePythonNodeBindings,
+  resolvePythonNodeBindingModule,
   resolvePythonNodeBindings,
   type ResolvedPythonNodeBindings,
   type ResolvedPythonNodeFunctionOverride,
@@ -139,7 +140,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   );
   const packageEntrypoint = Bun.resolveSync(config.entrypoint, projectDirectory);
   const entrypoint = selectedModule
-    ? resolveGeneratedModule(packageEntrypoint, selectedModule)
+    ? resolvePythonNodeBindingModule(packageEntrypoint, selectedModule)
     : packageEntrypoint;
   const functions = publicFunctionExports(entrypoint);
   if (functions.length === 0) {
@@ -217,7 +218,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     return binding.modules.length > 0
       ? binding.modules.map((module) => ({
           key: runtimeModuleName(binding, module),
-          entrypoint: resolveGeneratedModule(entrypoint, module),
+          entrypoint: resolvePythonNodeBindingModule(entrypoint, module),
         }))
       : [{ key: runtimeModuleName(binding), entrypoint }];
   });
@@ -310,7 +311,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     const packageEntrypoint = Bun.resolveSync(candidate.entrypoint, candidate.projectDirectory);
     const modules = publicNamespaceExports(packageEntrypoint).filter(
       (module) =>
-        publicFunctionExports(resolveGeneratedModule(packageEntrypoint, module)).length > 0,
+        publicFunctionExports(resolvePythonNodeBindingModule(packageEntrypoint, module)).length > 0,
     );
     return { ...candidate, modules };
   }
@@ -1220,19 +1221,4 @@ function pythonRuntimeLoader(source: string): string {
   ].join("\n");
 }
 
-function resolveGeneratedModule(entrypoint: string, module: string): string {
-  if (!/^[$A-Z_a-z][$\w]*$/.test(module)) {
-    throw new Error(`Node binding module must be a TypeScript identifier: ${module}`);
-  }
-  const source = readFileSync(entrypoint, "utf8");
-  const escaped = module.replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
-  const match = new RegExp(`export\\s+\\*\\s+as\\s+${escaped}\\s+from\\s+["']([^"']+)["']`).exec(
-    source,
-  );
-  if (!match?.[1]) {
-    throw new Error(`${entrypoint} does not export namespace ${module}`);
-  }
-  return Bun.resolveSync(match[1], dirname(entrypoint));
-}
-
 if (import.meta.main) await main();

package/tasks/release-notes.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 {
+  /** Extra agent instructions appended after the standard release-note requirements. */
+  readonly instructions?: string;
+  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;
+}
+
+/** Compose the stable release-note prompt with optional caller guidance. */
+export function releaseNotesPrompt(instructions?: string): string {
+  const additional = instructions?.trim();
+  return additional ? `${GENIE_PROMPT}\n\nAdditional instructions:\n${additional}` : GENIE_PROMPT;
+}
+
+/** 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,
+    releaseNotesPrompt(options.instructions),
+  ] 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

@@ -1,9 +1,12 @@
 #!/usr/bin/env -S bun
 /** Run the configured release transaction. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 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 {
@@ -19,6 +22,14 @@ import { readWorkspaceVersion } from "../src/workspace-version.ts";
 
 const logger = log.logger("projen:release");
 
+/** Whether the root manifest exposes one repository-owned script. */
+function hasPackageScript(root: string, name: string): boolean {
+  const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+    scripts?: Record<string, string>;
+  };
+  return Boolean(manifest.scripts?.[name]);
+}
+
 function gitHead(root: string, ref: string): string | undefined {
   if (!taskCommandSucceeds(root, "git", ["rev-parse", "--verify", ref])) return undefined;
   return captureTaskCommand(root, "git", ["rev-parse", ref], { check: true });
@@ -105,6 +116,13 @@ 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;
+    /** Additional instructions appended to the standard Genie release-notes prompt. */
+    readonly releaseNotesInstructions?: string;
+    readonly writeReleaseNotes?: typeof writeReleaseNotes;
   },
 ): Promise<string> {
   const { branch, prefix, remote, root } = options;
@@ -112,6 +130,9 @@ export async function runRelease(
   const install = options.install ?? "auto";
 
   if (install === "always") runTaskCommand(root, "bun", ["install"]);
+  if (selection.validation && hasPackageScript(root, "eslint:fix")) {
+    runTaskCommand(root, "bun", ["run", "eslint:fix"]);
+  }
 
   prepareReleaseBranch({ branch, remote, root });
 
@@ -125,6 +146,14 @@ 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,
+      instructions: options.releaseNotesInstructions,
+    });
+  }
 
   if (taskCommandSucceeds(root, "git", ["rev-parse", "--verify", `refs/tags/${tag}`])) {
     throw new Error(`release tag ${tag} already exists`);
@@ -190,6 +219,10 @@ export async function runRelease(
     });
   }
 
+  if (options.demoDeploy) {
+    runTaskCommand(root, "bun", ["run", "demo:deploy"]);
+  }
+
   return tag;
 }
 
@@ -228,6 +261,12 @@ 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(
+      "--release-notes-instructions <text>",
+      "append custom instructions to the Genie release-notes prompt",
+    )
+    .option("--demo-deploy", "after tagging, stage and deploy the AppKit demo app (off by default)")
     .option("--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 +284,9 @@ export function createReleaseCommand(): Command {
           localPypi: string;
           install: ReleaseInstallMode;
           validate: string[];
+          demoDeploy?: boolean;
+          releaseNotes?: boolean;
+          releaseNotesInstructions?: string;
         },
       ) => {
         await runRelease({
@@ -264,6 +306,9 @@ export function createReleaseCommand(): Command {
           docs: options.docs,
           validation: options.validation,
           validationTasks: options.validate,
+          demoDeploy: options.demoDeploy,
+          releaseNotes: options.releaseNotes,
+          releaseNotesInstructions: options.releaseNotesInstructions,
         });
       },
     );