@dbx-tools/projen 0.6.230 → 0.8.0

package/README.md

@@ -194,6 +194,12 @@ archive content and repository identity, PyPI uses hash-aware existing-file
 behavior, Cargo checks existing versions, and GitHub assets upload to the
 component release.
 
+Set `releaseSyncBranch` when a repository retains a long-lived source branch.
+After publication the workflow fast-forwards a branch that is behind, skips a
+branch that already contains released `main`, and merges `main` into a diverged
+branch when the merge is conflict-free. Missing branches and conflicted merges
+are left untouched.
+
 The Rust matrix has one row per target. Each row installs native dependencies,
 builds the Cargo workspace once, then packages every discovered output from
 that shared build. Set a source-only crate's or
@@ -441,18 +447,23 @@ a new package is covered without a re-synth. Work from the root:
 | `bun run release:bootstrap` | initialize writable Release Please state once         |
 | `bun run release:plan`      | emit the affected component and publication plan      |
 | `bun run version:check`     | verify every package against its owning release unit  |
-| `bun run release`           | refresh Release Please PRs, tags, and GitHub Releases |
-
-`release` runs the pinned Release Please library with the generated
-cross-language graph plugin. Direct changes retain their conventional semantic
-increment, while required dependents receive patches. The combined release PR
-is reconciled by Projen before review. Merging it creates component tags and
-GitHub Releases, then the affected plan selects publication jobs.
-
-Each changed component receives
-`docs/releases/<component>-v<version>.md`. Summary generation tries Cursor,
-Codex, and Claude in order, logs provider events, and falls back to Git. The
-committed file becomes that component's GitHub Release body.
+| `bun run release`           | commit, annotate, and push one source release request |
+| `bun run release:refresh`   | refresh Release Please PRs, tags, and releases        |
+
+`release` first proves the branch differs from `main`; an unchanged branch exits
+before notes, AI, commits, pushes, or PR creation. It commits dirty source,
+writes custom `--notes` / `--notes-file` content or a bounded Cursor, Codex,
+Claude, then Git fallback to `.release-notes/requests/<branch>.md`, adds one
+request commit, and pushes. The generated request workflow creates or updates
+the source PR. `--approve` enables auto-merge after checks.
+
+After the source PR merges, Release Please retains direct conventional semantic
+increments and applies required dependent patches. Reconciliation copies the
+readable request Markdown into one temporary
+`.release-notes/final/<component>-v<version>.md` per affected component and
+deletes the consumed request file in the release PR. Publication applies each
+file to its matching GitHub Release, then removes the temporary notes tree in a
+cleanup commit. Request and final notes never count as source changes.
 
 The GitHub PR workflow runs the explicit `pr:validate` task through Projen's
 public `BuildWorkflow` `buildTask` option. That task runs synth plus the

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.230";
+export const PACKAGE_VERSION = "0.8.0";
 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

@@ -50,7 +50,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.6.230",
+  "version": "0.8.0",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/project-js.ts

@@ -634,6 +634,8 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
     readonly releaseValidationTasks?: readonly string[];
     /** Optional AI-generated release summary. Defaults to enabled. */
     readonly releaseSummary?: boolean | ReleaseSummaryOptions;
+    /** Existing source branch safely fast-forwarded after an independent release. */
+    readonly releaseSyncBranch?: string | false;
     /** 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`. */
@@ -1601,6 +1603,7 @@ function initProject(
       pythonRoot: options.releasePythonRoot,
       validationTasks: options.releaseValidationTasks,
       summary: options.releaseSummary,
+      syncBranch: options.releaseSyncBranch,
     });
   }
 }

package/src/release.ts

@@ -56,6 +56,12 @@ export interface DBXToolsReleaseOptions {
   readonly pythonRoot?: string;
   /** Repository task names run in the release worktree before expensive validation and publication. */
   readonly validationTasks?: readonly string[];
+  /**
+   * Existing source branch safely fast-forwarded after publication.
+   *
+   * Missing or diverged branches are left untouched.
+   */
+  readonly syncBranch?: string | false;
   /**
    * Generate a versioned release summary locally. Defaults to enabled with the
    * standard Cursor, Codex, Claude fallback order.
@@ -389,7 +395,7 @@ function independentReleasePleaseJob(project: DBXToolsJavaScriptProject, branch:
         id: "changes",
         shell: "bash",
         run: [
-          "if git diff --quiet HEAD^ HEAD -- README.md AGENTS.md ':(glob)**/README.md' docs; then",
+          "if git diff --quiet HEAD^ HEAD -- README.md AGENTS.md ':(glob)**/README.md' docs ':(exclude)docs/releases/**' ':(exclude).release-notes/**'; then",
           '  echo "docs_changed=false" >> "$GITHUB_OUTPUT"',
           "else",
           '  echo "docs_changed=true" >> "$GITHUB_OUTPUT"',
@@ -438,6 +444,86 @@ function independentReleasePleaseJob(project: DBXToolsJavaScriptProject, branch:
   };
 }
 
+function configureReleaseRequestWorkflow(
+  project: DBXToolsJavaScriptProject,
+  baseBranch: string,
+): void {
+  if (!project.github) return;
+  const workflow = new GithubWorkflow(project.github, "release-request", {
+    fileName: "release-request.yml",
+    limitConcurrency: true,
+    concurrencyOptions: {
+      group: "release-request-${{ github.ref_name }}",
+      cancelInProgress: false,
+    },
+  });
+  workflow.runName = "release request ${{ github.ref_name }}";
+  workflow.on({ push: {} });
+  workflow.file?.addOverride("permissions.contents", "read");
+  workflow.addJob("request", {
+    if: `\${{ github.ref_name != '${baseBranch}' }}`,
+    runsOn: ["ubuntu-latest"],
+    permissions: {
+      contents: JobPermission.READ,
+      pullRequests: JobPermission.WRITE,
+    },
+    steps: [
+      {
+        name: "Checkout source branch",
+        uses: "actions/checkout@v6",
+        with: { "fetch-depth": 2 },
+      },
+      {
+        name: "Read release request",
+        id: "request",
+        shell: "bash",
+        run: [
+          'MESSAGE="$(git log -1 --format=%B)"',
+          'if ! grep -q "^Release-Request: true$" <<<"$MESSAGE"; then',
+          '  echo "requested=false" >> "$GITHUB_OUTPUT"',
+          "  exit 0",
+          "fi",
+          `git fetch origin ${JSON.stringify(baseBranch)}`,
+          `if git diff --quiet "origin/${baseBranch}...HEAD"; then`,
+          '  echo "requested=false" >> "$GITHUB_OUTPUT"',
+          "  exit 0",
+          "fi",
+          'echo "requested=true" >> "$GITHUB_OUTPUT"',
+          'echo "branch=$(git branch --show-current)" >> "$GITHUB_OUTPUT"',
+          'echo "approve=$(sed -n \'s/^Release-Approve: //p\' <<<"$MESSAGE" | tail -1)" >> "$GITHUB_OUTPUT"',
+          'echo "notes_path=$(sed -n \'s/^Release-Notes-Path: //p\' <<<"$MESSAGE" | tail -1)" >> "$GITHUB_OUTPUT"',
+          'echo "title=$(git log -1 --skip=1 --format=%s)" >> "$GITHUB_OUTPUT"',
+        ].join("\n"),
+      },
+      {
+        name: "Create or update source pull request",
+        if: "${{ steps.request.outputs.requested == 'true' }}",
+        env: {
+          GH_TOKEN: "${{ github.token }}",
+          SOURCE_BRANCH: "${{ steps.request.outputs.branch }}",
+          BASE_BRANCH: baseBranch,
+          TITLE: "${{ steps.request.outputs.title }}",
+          NOTES_PATH: "${{ steps.request.outputs.notes_path }}",
+          APPROVE: "${{ steps.request.outputs.approve }}",
+        },
+        shell: "bash",
+        run: [
+          'test -f "$NOTES_PATH"',
+          'NOTES="$(cat "$NOTES_PATH")"',
+          'BODY="$(printf \'## Release notes\\n\\n%s\\n\' "$NOTES")"',
+          'PR="$(gh pr list --head "$SOURCE_BRANCH" --base "$BASE_BRANCH" --state open --json number --jq \'.[0].number // empty\')"',
+          'if [ -n "$PR" ]; then',
+          '  gh pr edit "$PR" --title "$TITLE" --body "$BODY"',
+          "else",
+          '  PR="$(gh pr create --head "$SOURCE_BRANCH" --base "$BASE_BRANCH" --title "$TITLE" --body "$BODY" --json number --jq .number)"',
+          "fi",
+          'if [ "$APPROVE" = "true" ]; then gh pr merge "$PR" --auto --merge; fi',
+        ].join("\n"),
+      },
+    ],
+  });
+}
+
 function independentReleasePlanJob(project: DBXToolsJavaScriptProject): Job {
   return {
     if: "${{ always() && (github.event_name == 'workflow_dispatch' || needs.release-please.outputs.releases_created == 'true' || needs.release-please.outputs.docs_changed == 'true' || needs.release-please.outputs.recovery_requested == 'true') }}",
@@ -557,10 +643,28 @@ function independentReleaseNotesJob(project: DBXToolsJavaScriptProject): Job {
           "jq -c '.units[]' dist/release-plan.json | while read -r UNIT; do",
           '  COMPONENT="$(jq -r .component <<<"$UNIT")"',
           '  VERSION="$(jq -r .newVersion <<<"$UNIT")"',
-          '  gh release edit "$COMPONENT-v$VERSION" --notes-file "docs/releases/$COMPONENT-v$VERSION.md"',
+          '  gh release edit "$COMPONENT-v$VERSION" --notes-file ".release-notes/final/$COMPONENT-v$VERSION.md"',
           "done",
         ].join("\n"),
       },
+      {
+        name: "Remove consumed release notes",
+        shell: "bash",
+        run: [
+          `git fetch origin ${JSON.stringify(projectReleaseBranch(project))}`,
+          `if [ "$(git rev-parse origin/${projectReleaseBranch(project)})" != "$(git rev-parse HEAD)" ]; then`,
+          '  echo "::warning::main advanced before release-note cleanup; leaving temporary notes for the next release"',
+          "  exit 0",
+          "fi",
+          "git rm -r --ignore-unmatch .release-notes",
+          "if ! git diff --cached --quiet; then",
+          '  git config user.name "github-actions[bot]"',
+          '  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
+          '  git commit -m "chore: remove consumed release notes"',
+          `  git push origin "HEAD:${projectReleaseBranch(project)}"`,
+          "fi",
+        ].join("\n"),
+      },
     ],
   };
 }
@@ -571,7 +675,7 @@ function addIndependentDocsJobs(
   options: ReleaseDocsOptions,
 ): void {
   workflow.addJob("build-docs", {
-    if: "${{ needs.release-plan.outputs.docs == 'true' && needs.publication-complete.result == 'success' && (github.event_name == 'push' || inputs.stage == 'all' || inputs.stage == 'docs') }}",
+    if: "${{ always() && needs['release-plan'].outputs.docs == 'true' && needs['publication-complete'].result == 'success' && (github.event_name == 'push' || inputs.stage == 'all' || inputs.stage == 'docs') }}",
     needs: ["release-plan", "publication-complete"],
     runsOn: ["ubuntu-latest"],
     permissions: {
@@ -617,6 +721,49 @@ function addIndependentDocsJobs(
   });
 }
 
+function addIndependentBranchSyncJob(workflow: GithubWorkflow, branch: string): void {
+  workflow.addJob("sync-release-branch", {
+    if: "${{ always() && github.event_name == 'push' && needs['publication-complete'].result == 'success' }}",
+    needs: ["publication-complete"],
+    runsOn: ["ubuntu-latest"],
+    permissions: { contents: JobPermission.WRITE },
+    steps: [
+      {
+        name: "Checkout released main",
+        uses: "actions/checkout@v6",
+        with: { "fetch-depth": 0 },
+      },
+      {
+        name: `Safely sync ${branch}`,
+        shell: "bash",
+        env: { SOURCE_BRANCH: branch },
+        run: [
+          'if ! git ls-remote --exit-code --heads origin "refs/heads/$SOURCE_BRANCH" >/dev/null 2>&1; then',
+          '  echo "source branch $SOURCE_BRANCH no longer exists; nothing to sync"',
+          "  exit 0",
+          "fi",
+          'git fetch origin "refs/heads/$SOURCE_BRANCH:refs/remotes/origin/$SOURCE_BRANCH"',
+          'if git merge-base --is-ancestor "origin/$SOURCE_BRANCH" HEAD; then',
+          '  git push origin "HEAD:refs/heads/$SOURCE_BRANCH"',
+          'elif git merge-base --is-ancestor HEAD "origin/$SOURCE_BRANCH"; then',
+          '  echo "source branch $SOURCE_BRANCH already contains released main"',
+          "else",
+          '  git config user.name "github-actions[bot]"',
+          '  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
+          '  git switch --force-create "$SOURCE_BRANCH" "origin/$SOURCE_BRANCH"',
+          '  if git merge --no-ff --no-edit "$GITHUB_SHA"; then',
+          '    git push origin "HEAD:refs/heads/$SOURCE_BRANCH"',
+          "  else",
+          "    git merge --abort",
+          '    echo "::warning::source branch $SOURCE_BRANCH has merge conflicts with released main; leaving it untouched"',
+          "  fi",
+          "fi",
+        ].join("\n"),
+      },
+    ],
+  });
+}
+
 class IndependentReleaseFinalizer extends Component {
   private finalized = false;
 
@@ -624,6 +771,7 @@ class IndependentReleaseFinalizer extends Component {
     project: DBXToolsJavaScriptProject,
     private readonly workflow: GithubWorkflow,
     private readonly docs: ReleaseDocsOptions | undefined,
+    private readonly syncBranch: string | undefined,
   ) {
     super(project);
   }
@@ -645,6 +793,9 @@ class IndependentReleaseFinalizer extends Component {
     if (this.docs) {
       addIndependentDocsJobs(this.workflow, this.project as DBXToolsJavaScriptProject, this.docs);
     }
+    if (this.syncBranch) {
+      addIndependentBranchSyncJob(this.workflow, this.syncBranch);
+    }
   }
 }
 
@@ -665,9 +816,14 @@ function configureIndependentRelease(
       description: "Build the affected release plan",
     },
     release: {
+      exec: taskScript(project, "release-request.ts", `--base ${JSON.stringify(branch)}`),
+      receiveArgs: true,
+      description: "Commit, annotate, and push a source release request",
+    },
+    "release:refresh": {
       exec: taskScript(project, "release-please.ts", `--target-branch ${JSON.stringify(branch)}`),
       receiveArgs: true,
-      description: "Refresh independent release PRs, tags, and GitHub Releases",
+      description: "Refresh Release Please PRs, tags, and GitHub Releases",
     },
   });
   if (!project.github) return;
@@ -713,7 +869,8 @@ function configureIndependentRelease(
     workflow.addJob("publish-node", independentNodePublishJob(project));
     registerIndependentPublicationJob(workflow, "publish-node");
   }
-  new IndependentReleaseFinalizer(project, workflow, options.docs);
+  new IndependentReleaseFinalizer(project, workflow, options.docs, options.syncBranch || undefined);
+  configureReleaseRequestWorkflow(project, branch);
   releaseWorkflows.set(project, workflow);
 }
 

package/tasks/release-request.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env -S bun
+/** Commit and push a source branch for the generated release-request workflow. */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { exec, project } from "@dbx-tools/core";
+import { log, string } from "@dbx-tools/shared-core";
+import { Command } from "commander";
+import { selectReleaseSummary } from "./release-summary.ts";
+
+const logger = log.logger("projen:release-request");
+
+export interface PrepareReleaseRequestOptions {
+  readonly root: string;
+  readonly baseBranch: string;
+  readonly approve?: boolean;
+  readonly message?: string;
+  readonly notes?: string;
+  readonly notesFile?: string;
+  readonly push?: boolean;
+  readonly synthesize?: boolean;
+  readonly generateNotes?: (root: string, range: string) => Promise<string>;
+}
+
+/** Commit real changes, attach notes to one request commit, and push the branch. */
+export async function prepareReleaseRequest(
+  options: PrepareReleaseRequestOptions,
+): Promise<boolean> {
+  const root = resolve(options.root);
+  const branch = capture(root, ["branch", "--show-current"]);
+  if (!branch) throw new Error("Release requests require a named source branch");
+  if (options.push !== false) {
+    run(root, ["fetch", "origin", options.baseBranch]);
+  }
+  const baseRef = options.push === false ? options.baseBranch : `origin/${options.baseBranch}`;
+  if (options.synthesize !== false) {
+    exec.spawnSync(process.execPath, ["x", "projen"], {
+      cwd: root,
+      stdout: "inherit",
+      stderr: "inherit",
+      stdin: "ignore",
+      check: true,
+    });
+  }
+  const dirty = capture(root, ["status", "--porcelain"]);
+  if (dirty) {
+    const message = options.message ?? "fix: prepare release";
+    if (!isReleasableMessage(message)) {
+      throw new Error("Release commit message must use fix, feat, or a breaking-change marker");
+    }
+    run(root, ["add", "-A"]);
+    run(root, ["commit", "-m", message]);
+  }
+  const ahead = Number(capture(root, ["rev-list", "--count", `${baseRef}..HEAD`]));
+  if (!Number.isInteger(ahead) || ahead < 1) {
+    logger.info("no changes from release base; skipping release request", {
+      branch,
+      base: options.baseBranch,
+    });
+    return false;
+  }
+  const messages = capture(root, ["log", "--format=%B%x00", `${baseRef}..HEAD`]);
+  if (!messages.split("\0").some(isReleasableMessage)) {
+    logger.info("branch has no releasable conventional commits; skipping release request", {
+      branch,
+    });
+    return false;
+  }
+  const latest = capture(root, ["log", "-1", "--format=%B"]);
+  if (/^Release-Request:\s*true$/m.test(latest)) {
+    logger.info("release request already exists at branch head; skipping", { branch });
+    return false;
+  }
+  if (branch === options.baseBranch) {
+    throw new Error(`Release requests must run from a branch other than ${options.baseBranch}`);
+  }
+
+  const customNotes = string.trimToNull(
+    options.notesFile ? readFileSync(resolve(root, options.notesFile), "utf8") : options.notes,
+  );
+  const notes =
+    customNotes ??
+    (await (options.generateNotes ?? generateRequestNotes)(root, `${baseRef}..HEAD`));
+  const notesPath = `.release-notes/requests/${branch.replace(/[^a-zA-Z0-9-]+/g, "-")}.md`;
+  const absoluteNotesPath = resolve(root, notesPath);
+  mkdirSync(dirname(absoluteNotesPath), { recursive: true });
+  writeFileSync(absoluteNotesPath, `# Release request: ${branch}\n\n${notes.trim()}\n`);
+  run(root, ["add", notesPath]);
+  run(root, [
+    "commit",
+    "-m",
+    "chore: request release",
+    "-m",
+    [
+      "Release-Request: true",
+      `Release-Source-Branch: ${branch}`,
+      `Release-Approve: ${options.approve === true}`,
+      `Release-Notes-Path: ${notesPath}`,
+    ].join("\n"),
+  ]);
+  if (options.push !== false) run(root, ["push", "--set-upstream", "origin", branch]);
+  logger.success("release request pushed", { branch, approve: options.approve === true });
+  return true;
+}
+
+/** Whether one conventional commit can produce a Release Please increment. */
+export function isReleasableMessage(message: string): boolean {
+  return (
+    /^(?:fix|feat)(?:\([^)\r\n]+\))?!?:/m.test(message) || /^BREAKING[ -]CHANGE:/m.test(message)
+  );
+}
+
+async function generateRequestNotes(root: string, range: string): Promise<string> {
+  const commits = capture(root, ["log", "--no-merges", "--format=%s%n%b", range]);
+  const files = capture(root, ["diff", "--name-status", range, "--", "."]);
+  const result = await selectReleaseSummary(
+    root,
+    [
+      "Write concise release-request notes for the reviewed changes below.",
+      "Focus on user-visible behavior and important compatibility details.",
+      "",
+      "Commits:",
+      commits,
+      "",
+      "Files:",
+      files,
+    ].join("\n"),
+  );
+  if (result?.summary.trim()) return result.summary.trim();
+  const subjects = capture(root, ["log", "--no-merges", "--format=- %s", range]);
+  return subjects || "Release source changes are ready for review.";
+}
+
+function capture(root: string, args: string[]): string {
+  return (
+    exec
+      .spawnSync("git", args, {
+        cwd: root,
+        stdout: "capture",
+        stderr: "inherit",
+        stdin: "ignore",
+        check: true,
+      })
+      .stdout?.trim() ?? ""
+  );
+}
+
+function run(root: string, args: string[]): void {
+  exec.spawnSync("git", args, {
+    cwd: root,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "ignore",
+    check: true,
+  });
+}
+
+if (import.meta.main) {
+  await new Command()
+    .option("--base <branch>", "release target branch", "main")
+    .option("--approve", "enable merge-queue or auto-merge for the source PR")
+    .option("--message <message>", "commit message for uncommitted source changes")
+    .option("--notes <notes>", "custom release notes")
+    .option("--notes-file <path>", "read custom release notes from a file")
+    .action(
+      async (options: {
+        base: string;
+        approve?: boolean;
+        message?: string;
+        notes?: string;
+        notesFile?: string;
+      }) => {
+        if (options.notes && options.notesFile) {
+          throw new Error("Use --notes or --notes-file, not both");
+        }
+        await prepareReleaseRequest({
+          root: project.root() ?? process.cwd(),
+          baseBranch: options.base,
+          approve: options.approve,
+          message: options.message,
+          notes: options.notes,
+          notesFile: options.notesFile,
+        });
+      },
+    )
+    .parseAsync();
+}

package/tasks/release-summary-units.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env -S bun
 /** Generate component-qualified release notes from an affected release plan. */
 
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { exec } from "@dbx-tools/core";
 import { log } from "@dbx-tools/shared-core";
 import { Command } from "commander";
 import { generateReleaseSummary } from "./release-summary.ts";
@@ -23,22 +24,59 @@ if (import.meta.main) {
       const graph = JSON.parse(
         readFileSync(resolve(root, ".projen/release-units.json"), "utf8"),
       ) as ReleaseUnitGraph;
+      const request = requestNotes(root);
       for (const planned of plan.units) {
         const unit = graph.units.find((candidate) => candidate.id === planned.id);
         if (!unit) throw new Error(`Release plan references unknown unit ${planned.id}`);
         const paths = graph.projects
           .filter((project) => project.unit === unit.id)
           .map((project) => project.path);
+        const componentTag = `${planned.component}-v${planned.oldVersion}`;
+        const fromRef = gitCapture(root, ["rev-parse", "--verify", componentTag])
+          ? componentTag
+          : options.fromRef;
         await generateReleaseSummary({
           root,
           component: planned.component,
           version: planned.newVersion,
           paths,
-          fromRef: options.fromRef,
+          customSummary: request.summary,
+          outputFile: `.release-notes/final/${planned.component}-v${planned.newVersion}.md`,
+          fromRef,
           toRef: options.toRef,
         });
       }
+      for (const path of request.paths) rmSync(path);
       logger.success(`generated ${plan.units.length} component release summaries`);
     })
     .parseAsync();
 }
+
+function requestNotes(root: string): { summary?: string; paths: string[] } {
+  const directory = resolve(root, ".release-notes/requests");
+  if (!existsSync(directory)) return { paths: [] };
+  const paths = readdirSync(directory)
+    .filter((name) => name.endsWith(".md"))
+    .sort()
+    .map((name) => join(directory, name));
+  const summary = paths
+    .map((path) =>
+      readFileSync(path, "utf8")
+        .replace(/^# .+\n+/, "")
+        .trim(),
+    )
+    .filter(Boolean)
+    .join("\n\n");
+  return { ...(summary ? { summary } : {}), paths };
+}
+
+function gitCapture(root: string, args: string[]): string {
+  const result = exec.spawnSync("git", args, {
+    cwd: root,
+    stdout: "capture",
+    stderr: "ignore",
+    stdin: "ignore",
+    check: false,
+  });
+  return result.exitCode === 0 ? (result.stdout?.trim() ?? "") : "";
+}

package/tasks/release-summary.ts

@@ -265,12 +265,15 @@ export async function generateReleaseSummary(options: {
   readonly version: string;
   readonly component?: string;
   readonly paths?: readonly string[];
+  readonly customSummary?: string;
+  readonly outputFile?: string;
   readonly fromRef?: string;
   readonly toRef?: string;
   readonly providers?: readonly ReleaseSummaryProviderName[];
   readonly runner?: ReleaseSummaryRunner;
 }): Promise<string | undefined> {
-  const relativeOutput = releaseSummaryFile(options.version, options.component);
+  const relativeOutput =
+    options.outputFile ?? releaseSummaryFile(options.version, options.component);
   const output = join(options.root, relativeOutput);
   if (existsSync(output)) rmSync(output);
   const target =
@@ -306,15 +309,21 @@ export async function generateReleaseSummary(options: {
     ...scopedPaths,
     `:(exclude)${relativeOutput}`,
   ]);
-  const result = await selectReleaseSummary(
-    options.root,
-    summaryPrompt(options.version, options.fromRef, commits, changedFiles, diffStat),
-    options.runner,
-    options.providers,
-  );
-  const summary = result?.summary ?? gitSummary(options.version, commits, changedFiles);
-  const provider = result?.provider ?? "git";
-  if (!result) logger.info("AI providers unavailable; using Git release summary");
+  const customSummary = string.trimToNull(options.customSummary);
+  const result = customSummary
+    ? undefined
+    : await selectReleaseSummary(
+        options.root,
+        summaryPrompt(options.version, options.fromRef, commits, changedFiles, diffStat),
+        options.runner,
+        options.providers,
+      );
+  const summary =
+    customSummary ?? result?.summary ?? gitSummary(options.version, commits, changedFiles);
+  const provider = customSummary ? "custom" : (result?.provider ?? "git");
+  if (!customSummary && !result) {
+    logger.info("AI providers unavailable; using Git release summary");
+  }
   const content = `# Release ${options.component ? `${options.component} ` : ""}${options.version}\n\n${summary.trim()}\n`;
   mkdirSync(dirname(output), { recursive: true });
   writeFileSync(output, content);