@dbx-tools/projen 0.6.224 → 0.6.225

package/README.md

@@ -57,6 +57,9 @@ Repository policy stays in the consuming `.projenrc.ts`:
   artifact upload, and deployment without naming a docs script or output tree.
 - `releasePythonRoot` passes the actual Python package root to local release
   preparation. Omit it when the workspace has no standard Python packages.
+- `releaseSummary` controls optional AI release notes. It defaults to enabled
+  with Cursor, Codex, Claude fallback order; pass `false` to disable or provide
+  a `providers` array to choose the order/subset.
 - `pullRequestTitlePolicy` configures semantic title types and scope policy.
   Omit it or pass `false` to disable the title job.
 - `workflowCacheIgnorePaths` excludes generated output trees that may contain
@@ -441,7 +444,17 @@ it. `--message` sets the source commit message. The task never merges
 the PR unless `--approve` is passed; that option merges the release branch
 directly through GitHub's merge API so no PR checks are created. A repository
 that blocks direct merges falls back to an immediate admin-merged PR. The task
-then fast-forwards the still-active source branch to the release commit. npm
+then fast-forwards the still-active source branch to the release commit.
+
+After validation, release preparation optionally generates an immutable
+`docs/releases/v<version>.md`. It tries the installed Cursor agent first, then
+Codex, then Claude, all in non-interactive read-only modes against bounded Git
+context. An unavailable, unauthenticated, failed, or empty provider falls
+through to the next; if none works, release preparation continues without a
+summary. The same file is included in the release PR and prepended to GitHub's
+generated release notes, so repository and GitHub views share one source.
+
+npm
 uses `npm config get registry` and publishes to a local Verdaccio automatically.
 Publishable JavaScript members compile once
 from the root in parallel, then upload through a bounded pool without rerunning

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.6.224";
+export const PACKAGE_VERSION = "0.6.225";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -55,8 +55,9 @@ export { RustReleaseOs, RustReleaseCpu, UNIFFI_RELEASE_TARGETS, DBXToolsRustProj
 export type { CargoDependencyOptions, CargoDependency, RustCliOptions, RustPackageOptions, DBXToolsRustWorkspaceOptions, RustReleasePlatform, UniFFIReleaseTarget, RustBindingMapping, RustWorkspaceMapping, RustReleaseBinaryAssetMapping, RustReleaseBinaryMapping } from "./src/project-rs.ts";
 export { COMPILED_DIR, COMPILED_COMPILER_OPTIONS } from "./src/publish.ts";
 export { DBXToolsRelease } from "./src/release.ts";
-export type { ReleaseStage, ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
-export { RELEASE_TAG, RELEASE_SHA, RELEASE_VERSION } from "./src/release-dispatch.ts";
+export type { ReleaseStage, ReleaseDocsOptions, ReleaseSummaryOptions, DBXToolsReleaseOptions } from "./src/release.ts";
+export { RELEASE_TAG, RELEASE_SHA, RELEASE_VERSION, RELEASE_SUMMARY_DIRECTORY, RELEASE_SUMMARY_PROVIDER_NAMES, RELEASE_SUMMARY_FILE } from "./src/release-dispatch.ts";
+export type { ReleaseSummaryProviderName } from "./src/release-dispatch.ts";
 export type { GithubRepositoryIdentity } from "./src/release-github.ts";
 export { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS } from "./src/tags.ts";
 export type { PackageTag } from "./src/tags.ts";

package/package.json

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

package/src/project-js.ts

@@ -41,7 +41,7 @@ import {
 import { PnpmWorkspaceState, type DBXToolsPNPMWorkspaceOptions } from "./pnpm-workspace.ts";
 import type { DBXToolsProject, DBXToolsProjectOptions as CommonProjectOptions } from "./project.ts";
 import { applyCompiledPublish } from "./publish.ts";
-import { DBXToolsRelease, type ReleaseDocsOptions } from "./release.ts";
+import { DBXToolsRelease, type ReleaseDocsOptions, type ReleaseSummaryOptions } from "./release.ts";
 import { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS, type PackageTag } from "./tags.ts";
 import { DBXToolsRootTsconfig } from "./tsconfig.ts";
 import { DBXToolsVsCode } from "./vscode.ts";
@@ -621,6 +621,8 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
     readonly releaseDocs?: ReleaseDocsOptions;
     /** Python package root passed to local release preparation when configured. */
     readonly releasePythonRoot?: string;
+    /** Optional AI-generated release summary. Defaults to enabled. */
+    readonly releaseSummary?: boolean | ReleaseSummaryOptions;
     /** Set to `false` to omit normal npm workspace publication. */
     readonly nodeRelease?: boolean;
     /** Unified dbx-tools release workflow, or no release surface. Defaults to `dbx-tools`. */
@@ -1540,6 +1542,7 @@ function initProject(
       nodeRelease: options.nodeRelease,
       docs: options.releaseDocs,
       pythonRoot: options.releasePythonRoot,
+      summary: options.releaseSummary,
     });
   }
 }

package/src/project-rs.ts

@@ -19,6 +19,7 @@ import { pythonModuleName, type PythonPackageOptions } from "./project-py.ts";
 import type { DBXToolsProject } from "./project.ts";
 import {
   RELEASE_SHA,
+  RELEASE_SUMMARY_FILE,
   RELEASE_TAG,
   RELEASE_VERSION,
   releaseSourceSteps,
@@ -1359,6 +1360,7 @@ function rustGitHubReleaseJob(): Job {
         uses: "softprops/action-gh-release@v2",
         with: {
           files: "dist/rust-release/*",
+          body_path: RELEASE_SUMMARY_FILE,
           "generate-release-notes": true,
           tag_name: RELEASE_TAG,
           target_commitish: RELEASE_SHA,

package/src/release-dispatch.ts

@@ -4,6 +4,16 @@ import type { JobStep } from "projen/lib/github/workflows-model";
 export const RELEASE_TAG = "${{ needs.verify-context.outputs.release_tag }}";
 export const RELEASE_SHA = "${{ needs.verify-context.outputs.expected_sha }}";
 export const RELEASE_VERSION = "${{ needs.verify-context.outputs.release_version }}";
+export const RELEASE_SUMMARY_DIRECTORY = "docs/releases";
+export const RELEASE_SUMMARY_PROVIDER_NAMES = ["cursor", "codex", "claude"] as const;
+export type ReleaseSummaryProviderName = (typeof RELEASE_SUMMARY_PROVIDER_NAMES)[number];
+
+/** Immutable repository path for one version's release summary. */
+export function releaseSummaryFile(version: string): string {
+  return `${RELEASE_SUMMARY_DIRECTORY}/v${version.replace(/^v/, "")}.md`;
+}
+
+export const RELEASE_SUMMARY_FILE = releaseSummaryFile(RELEASE_VERSION);
 
 /** Check out and verify the immutable commit selected by the release tag. */
 export function releaseSourceSteps(): readonly JobStep[] {

package/src/release.ts

@@ -5,7 +5,12 @@ import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflo
 import { BUN_VERSION, bunCacheRestoreSteps, bunCacheSaveStep } from "./bun-workflow.ts";
 import { projectReleaseBranch, type DBXToolsJavaScriptProject } from "./project-js.ts";
 import { applyTasks, taskScript } from "./project.ts";
-import { RELEASE_VERSION, releaseSourceSteps } from "./release-dispatch.ts";
+import {
+  RELEASE_VERSION,
+  releaseSourceSteps,
+  type ReleaseSummaryProviderName,
+} from "./release-dispatch.ts";
+import { readWorkspaceVersion } from "./workspace-version.ts";
 
 const NODE_VERSION = "lts/*";
 const NPM_REGISTRY_URL = "https://registry.npmjs.org";
@@ -28,6 +33,16 @@ export interface ReleaseDocsOptions {
   readonly artifactPath: string;
 }
 
+/** Optional local AI summary generation during reviewed release preparation. */
+export interface ReleaseSummaryOptions {
+  /**
+   * Provider fallback order.
+   *
+   * @default ["cursor", "codex", "claude"]
+   */
+  readonly providers?: readonly ReleaseSummaryProviderName[];
+}
+
 /** Options for {@link DBXToolsRelease}. */
 export interface DBXToolsReleaseOptions {
   /** Git tag prefix. Defaults to `v`. */
@@ -38,6 +53,11 @@ export interface DBXToolsReleaseOptions {
   readonly docs?: ReleaseDocsOptions;
   /** Python package root passed to local release preparation. */
   readonly pythonRoot?: string;
+  /**
+   * Generate a versioned release summary locally. Defaults to enabled with the
+   * standard Cursor, Codex, Claude fallback order.
+   */
+  readonly summary?: boolean | ReleaseSummaryOptions;
 }
 
 /** Locate the unified workflow so attached language workspaces can add jobs. */
@@ -320,6 +340,13 @@ export class DBXToolsRelease extends Component {
     super(project);
     const tagPrefix = options.tagPrefix ?? "v";
     const releaseBranch = projectReleaseBranch(project);
+    const summary = options.summary ?? true;
+    const summaryArgs =
+      summary === false || (typeof summary === "object" && summary.providers?.length === 0)
+        ? ["--no-release-summary"]
+        : typeof summary === "object" && summary.providers
+          ? [`--release-summary-providers ${summary.providers.join(",")}`]
+          : [];
     releaseTagPrefixes.set(project, tagPrefix);
     if (options.nodeRelease !== false) nodeReleaseProjects.add(project);
     applyTasks(project, {
@@ -344,6 +371,7 @@ export class DBXToolsRelease extends Component {
                   ...(options.pythonRoot
                     ? [`--python-root ${JSON.stringify(options.pythonRoot)}`]
                     : []),
+                  ...summaryArgs,
                 ].join(" "),
               ),
               receiveArgs: true,
@@ -359,8 +387,10 @@ export class DBXToolsRelease extends Component {
       limitConcurrency: true,
       concurrencyOptions: { group: "release", cancelInProgress: false },
     });
+    const version = readWorkspaceVersion(project.outdir);
     workflow.runName =
-      "release ${{ github.event_name == 'push' && github.sha || inputs.release_tag }}";
+      `release ${version} ` +
+      "${{ github.event_name == 'push' && github.sha || inputs.release_tag }}";
     workflow.on({
       push: { branches: [releaseBranch], paths: ["VERSION"] },
       workflowDispatch: {

package/tasks/release-pr.ts

@@ -14,6 +14,7 @@ import { exec, project } from "@dbx-tools/core";
 import { log } from "@dbx-tools/shared-core";
 import { Command } from "commander";
 import { publishLocalRelease } from "./local-publish.ts";
+import { generateReleaseSummary } from "./release-summary.ts";
 import {
   releaseArchitectureOption,
   releaseLevelOption,
@@ -28,6 +29,10 @@ import {
   githubTokenArguments,
   githubTokenEnvironmentName,
 } from "../src/release-github.ts";
+import {
+  RELEASE_SUMMARY_PROVIDER_NAMES,
+  type ReleaseSummaryProviderName,
+} from "../src/release-dispatch.ts";
 import { readWorkspaceVersion, resolveNextVersion } from "../src/workspace-version.ts";
 
 const logger = log.logger("projen:release");
@@ -130,6 +135,22 @@ function githubAccount(root: string): {
   return { ...identity, token };
 }
 
+function releaseSummaryProviders(
+  value: string | undefined,
+): ReleaseSummaryProviderName[] | undefined {
+  if (value === undefined) return undefined;
+  const providers = value
+    .split(",")
+    .map((provider) => provider.trim())
+    .filter(Boolean);
+  for (const provider of providers) {
+    if (!RELEASE_SUMMARY_PROVIDER_NAMES.includes(provider as ReleaseSummaryProviderName)) {
+      throw new Error(`Unknown release summary provider: ${provider}`);
+    }
+  }
+  return providers as ReleaseSummaryProviderName[];
+}
+
 const program = new Command();
 program
   .description("Prepare, validate, locally publish, and open a reviewed release PR")
@@ -142,6 +163,11 @@ program
   .option("--local-registry <value>", "local npm registry: auto, false, or an explicit URL", "auto")
   .option("--local-pypi <value>", "local PyPI index: auto, false, or an explicit URL", "auto")
   .option("--python-root <path>", "Python workspace package root")
+  .option("--no-release-summary", "skip optional AI release summary generation")
+  .option(
+    "--release-summary-providers <providers>",
+    "comma-separated provider order: cursor,codex,claude",
+  )
   .option("--no-local-cargo", "skip local Cargo publication")
   .option("--approve", "merge the release branch directly into the release base")
   .action(
@@ -155,6 +181,8 @@ program
       localRegistry: string;
       localPypi: string;
       pythonRoot?: string;
+      releaseSummary: boolean;
+      releaseSummaryProviders?: string;
       localCargo: boolean;
       approve: boolean;
     }) => {
@@ -259,6 +287,14 @@ program
         localCargo: opts.localCargo,
       });
       run(releaseRoot, process.execPath, [versionCheckScript]);
+      const releaseSummary = opts.releaseSummary
+        ? await generateReleaseSummary({
+            root: releaseRoot,
+            version: next.version,
+            fromRef: `${opts.prefix}${next.base}`,
+            providers: releaseSummaryProviders(opts.releaseSummaryProviders),
+          })
+        : undefined;
 
       git(releaseRoot, ["add", "-A"]);
       const staged = git(releaseRoot, ["diff", "--cached", "--name-only"], { capture: true });
@@ -279,6 +315,7 @@ program
         `Source commit: ${git(releaseRoot, ["rev-parse", `${releaseBranch}^`], { capture: true })}`,
         "",
         "Merging this PR updates VERSION on main and starts the public release workflow.",
+        ...(releaseSummary ? ["", releaseSummary] : []),
       ].join("\n");
       const githubEnvironment = {
         ...process.env,

package/tasks/release-summary.ts

@@ -0,0 +1,270 @@
+#!/usr/bin/env -S bun
+/**
+ * Optional AI-generated release summary with CLI fallback.
+ *
+ * @module
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { exec } from "@dbx-tools/core";
+import { json, log, object, string } from "@dbx-tools/shared-core";
+import {
+  RELEASE_SUMMARY_PROVIDER_NAMES,
+  releaseSummaryFile,
+  type ReleaseSummaryProviderName,
+} from "../src/release-dispatch.ts";
+
+const logger = log.logger("projen:release-summary");
+
+export interface ReleaseSummaryProvider {
+  readonly name: ReleaseSummaryProviderName;
+  readonly command: string;
+  readonly probeArgs: readonly string[];
+  args(root: string, prompt: string): string[];
+}
+
+export const RELEASE_SUMMARY_PROVIDERS: readonly ReleaseSummaryProvider[] = [
+  {
+    name: "cursor",
+    command: "cursor",
+    probeArgs: ["agent", "--version"],
+    args: (root, prompt) => [
+      "agent",
+      "--print",
+      "--mode",
+      "ask",
+      "--output-format",
+      "stream-json",
+      "--trust",
+      "--workspace",
+      root,
+      prompt,
+    ],
+  },
+  {
+    name: "codex",
+    command: "codex",
+    probeArgs: ["--version"],
+    args: (root, prompt) => [
+      "exec",
+      "--sandbox",
+      "read-only",
+      "--skip-git-repo-check",
+      "--json",
+      "--color",
+      "never",
+      "-C",
+      root,
+      prompt,
+    ],
+  },
+  {
+    name: "claude",
+    command: "claude",
+    probeArgs: ["--version"],
+    args: (_root, prompt) => [
+      "--print",
+      "--no-session-persistence",
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      "--tools",
+      "",
+      prompt,
+    ],
+  },
+];
+
+export type ReleaseSummaryRunner = (
+  provider: ReleaseSummaryProvider,
+  root: string,
+  prompt: string,
+) => string | undefined | Promise<string | undefined>;
+
+function capture(root: string, command: string, args: string[]): string {
+  const result = exec.spawnSync(command, args, {
+    cwd: root,
+    stdout: "capture",
+    stderr: "ignore",
+    stdin: "ignore",
+    check: false,
+  });
+  return result.exitCode === 0 ? (result.stdout?.trim() ?? "") : "";
+}
+
+function contentText(value: unknown): string | undefined {
+  if (typeof value === "string") return string.trimToNull(value) ?? undefined;
+  if (!Array.isArray(value)) return undefined;
+  const text = value
+    .flatMap((item) => (object.isRecord(item) && typeof item.text === "string" ? [item.text] : []))
+    .join("");
+  return string.trimToNull(text) ?? undefined;
+}
+
+function eventText(event: Record<string, unknown>): string | undefined {
+  if (typeof event.result === "string") return string.trimToNull(event.result) ?? undefined;
+  const item = object.isRecord(event.item) ? event.item : undefined;
+  if (item?.type === "agent_message" && typeof item.text === "string") {
+    return string.trimToNull(item.text) ?? undefined;
+  }
+  const message = object.isRecord(event.message) ? event.message : undefined;
+  return contentText(message?.content);
+}
+
+function eventType(event: Record<string, unknown>): string {
+  const item = object.isRecord(event.item) ? event.item : undefined;
+  return [event.type, item?.type].filter((value) => typeof value === "string").join(":") || "event";
+}
+
+function eventDetail(event: Record<string, unknown>): string | undefined {
+  const item = object.isRecord(event.item) ? event.item : undefined;
+  for (const value of [item?.message, event.message, event.error]) {
+    if (typeof value === "string") return string.trimToNull(value) ?? undefined;
+  }
+  return undefined;
+}
+
+async function runProvider(
+  provider: ReleaseSummaryProvider,
+  root: string,
+  prompt: string,
+): Promise<string | undefined> {
+  if (!capture(root, provider.command, [...provider.probeArgs])) return undefined;
+  let summary: string | undefined;
+  const textOutput: string[] = [];
+  const process = exec.spawn(provider.command, provider.args(root, prompt), {
+    cwd: root,
+    stdout: [
+      "capture",
+      (line) => {
+        const event = json.parseRecord(line);
+        if (!event) {
+          const text = string.trimToNull(line);
+          if (text) {
+            textOutput.push(text);
+            logger.info("provider-event", { provider: provider.name, type: "text", text });
+          }
+          return;
+        }
+        const text = eventText(event);
+        const detail = eventDetail(event);
+        if (text) summary = text;
+        logger.info("provider-event", {
+          provider: provider.name,
+          type: eventType(event),
+          ...(text ? { text } : {}),
+          ...(detail ? { detail } : {}),
+        });
+      },
+    ],
+    stderr: (line) => {
+      const message = string.trimToNull(line);
+      if (message) logger.warn("provider-stderr", { provider: provider.name, message });
+    },
+    stdin: "ignore",
+    check: false,
+  });
+  const result = await process;
+  if (result.exitCode !== 0) {
+    logger.warn("provider-failed", { provider: provider.name, exitCode: result.exitCode });
+    return undefined;
+  }
+  return summary ?? (textOutput.length ? textOutput.join("\n") : undefined);
+}
+
+/** Return the first non-empty provider response in Cursor, Codex, Claude order. */
+export async function selectReleaseSummary(
+  root: string,
+  prompt: string,
+  runner: ReleaseSummaryRunner = runProvider,
+  providers: readonly ReleaseSummaryProviderName[] = RELEASE_SUMMARY_PROVIDER_NAMES,
+): Promise<{ provider: ReleaseSummaryProvider["name"]; summary: string } | undefined> {
+  for (const name of providers) {
+    const provider = RELEASE_SUMMARY_PROVIDERS.find((candidate) => candidate.name === name);
+    if (!provider) continue;
+    const summary = (await runner(provider, root, prompt))?.trim();
+    if (summary) return { provider: provider.name, summary };
+  }
+  return undefined;
+}
+
+function summaryPrompt(
+  version: string,
+  fromRef: string | undefined,
+  commits: string,
+  changedFiles: string,
+  diffStat: string,
+): string {
+  return [
+    `Write a concise user-facing Markdown release summary for dbx-tools ${version}.`,
+    "Use only the supplied Git context. Do not run commands, edit files, speculate,",
+    "mention commit hashes, use emojis, or use em/en dashes.",
+    "Return no title and no fenced block. Start with one short paragraph, then",
+    "group concrete changes under brief Markdown headings with bullets.",
+    "",
+    `Comparison base: ${fromRef ?? "repository root"}`,
+    "",
+    "Commits:",
+    commits || "(none)",
+    "",
+    "Changed files:",
+    changedFiles || "(none)",
+    "",
+    "Diff stat:",
+    diffStat || "(none)",
+  ].join("\n");
+}
+
+/** Generate one immutable versioned summary, or remove a stale retry artifact. */
+export async function generateReleaseSummary(options: {
+  readonly root: string;
+  readonly version: string;
+  readonly fromRef?: string;
+  readonly toRef?: string;
+  readonly providers?: readonly ReleaseSummaryProviderName[];
+  readonly runner?: ReleaseSummaryRunner;
+}): Promise<string | undefined> {
+  const relativeOutput = releaseSummaryFile(options.version);
+  const output = join(options.root, relativeOutput);
+  if (existsSync(output)) rmSync(output);
+  const target =
+    options.toRef && capture(options.root, "git", ["rev-parse", "--verify", options.toRef])
+      ? options.toRef
+      : "HEAD";
+  const range =
+    options.fromRef && capture(options.root, "git", ["rev-parse", "--verify", options.fromRef])
+      ? `${options.fromRef}..${target}`
+      : target;
+  const commits = capture(options.root, "git", ["log", "--no-merges", "--format=%s%n%b", range]);
+  const changedFiles = capture(options.root, "git", [
+    "diff",
+    "--name-status",
+    range,
+    "--",
+    ".",
+    `:(exclude)${relativeOutput}`,
+  ]);
+  const diffStat = capture(options.root, "git", [
+    "diff",
+    "--stat",
+    range,
+    "--",
+    ".",
+    `:(exclude)${relativeOutput}`,
+  ]);
+  const result = await selectReleaseSummary(
+    options.root,
+    summaryPrompt(options.version, options.fromRef, commits, changedFiles, diffStat),
+    options.runner,
+    options.providers,
+  );
+  if (!result) {
+    logger.info("no supported AI CLI available; skipping release summary");
+    return undefined;
+  }
+  const content = `# Release ${options.version}\n\n${result.summary.trim()}\n`;
+  mkdirSync(dirname(output), { recursive: true });
+  writeFileSync(output, content);
+  logger.info("generated", { provider: result.provider, path: output });
+  return content;
+}