@akira-tl/forgerelay 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-10
+
+### Changed
+
+- Release-tag Hooks now treat `commandRegex` as a command extractor as well as a filter: a matching substring becomes Hook `payload.command`, while a different full shell request is preserved as `payload.originalCommand`. This lets stable tag pushes trigger local release gates even when an Agent wraps them in a compound shell command.
+- GitHub Release pages now use the matching `CHANGELOG.md` version section as their release notes instead of relying only on generated compare notes.
+
+### Fixed
+
+- MCP App resources now advertise a unique `_meta.ui.domain` derived from the resolved public deployment origin while preserving existing CSP, content-hashed template identity, and legacy/historical compatibility resources.
+- `forgerelay doctor` now reports the resolved MCP runtime shape, including public base URL, tool/widget modes, proxy trust, and optional artifact/subagent/Skill capability switches.
+
 ## [0.3.0] - 2026-08-10
 
 ### Added

package/capabilities/host-integration/GUIDE.md

@@ -53,7 +53,7 @@ ForgeRelay 正常会广告 content-hashed：
 ui://forgerelay/workspace-app-<hash>.html
 ```
 
-`resources/read` 应返回 `text/html;profile=mcp-app`，并且 HTML 引用的 `/mcp-app-assets/` 资源必须可达。ForgeRelay 还保留 legacy `ui://forgerelay/workspace-app.html` 和历史 `workspace-app-*.html` 兼容指针，以容忍 Host 暂时持有旧 metadata snapshot。
+`resources/list` 与 `resources/read` 的 MCP App metadata 都应包含唯一 `_meta.ui.domain`，其值来自 resolved `publicBaseUrl` 的 origin；CSP 仍使用完整 public base URL 约束资源与连接域。`resources/read` 应返回 `text/html;profile=mcp-app`，并且 HTML 引用的 `/mcp-app-assets/` 资源必须可达。ForgeRelay 还保留 legacy `ui://forgerelay/workspace-app.html` 和历史 `workspace-app-*.html` 兼容指针，以容忍 Host 暂时持有旧 metadata snapshot。
 
 需要 live trace 时，可用：
 

package/dist/cli.js

@@ -222,7 +222,14 @@ async function runDoctor() {
     try {
         const config = loadConfig();
         console.log(`Local MCP URL: http://${config.host}:${config.port}/mcp`);
+        console.log(`Public base URL: ${config.publicBaseUrl}`);
         console.log(`Public MCP URL: ${new URL("/mcp", config.publicBaseUrl).toString()}`);
+        console.log(`Tool mode: ${config.toolMode}`);
+        console.log(`Widgets: ${config.widgets}`);
+        console.log(`Trust proxy: ${config.logging.trustProxy ? "one hop" : "off"}`);
+        console.log(`Artifacts: ${config.artifactsEnabled ? "enabled" : "disabled"}`);
+        console.log(`Subagents: ${config.subagents ? "enabled" : "disabled"}`);
+        console.log(`Skills: ${config.skillsEnabled ? "enabled" : "disabled"}`);
         console.log(`Allowed roots: ${config.allowedRoots.join(", ")}`);
         console.log(`Allowed hosts: ${config.allowedHosts.join(", ")}`);
     }

package/dist/hooks.js

@@ -215,9 +215,12 @@ export class HookRunner {
         const handlers = [
             ...(this.hooks[event] ?? []).map((rule) => ({ scope: "global", rule })),
             ...(project.hooks[event] ?? []).map((rule) => ({ scope: "project", rule })),
-        ]
-            .filter(({ rule }) => hookRuleMatches(rule.matcher, invocation))
-            .flatMap(({ scope, rule }) => rule.handlers.map((handler) => ({ scope, handler })));
+        ].flatMap(({ scope, rule }) => {
+            const matchedInvocation = matchHookRule(rule.matcher, invocation);
+            if (!matchedInvocation)
+                return [];
+            return rule.handlers.map((handler) => ({ scope, handler, invocation: matchedInvocation }));
+        });
         const blocking = BLOCKING_EVENTS.has(event);
         const executions = project.diagnostic
             ? [{
@@ -230,8 +233,8 @@ export class HookRunner {
                     error: project.diagnostic,
                 }]
             : [];
-        for (const [index, { scope, handler }] of handlers.entries()) {
-            const execution = await this.runHandler(event, handler, index, invocation, scope);
+        for (const [index, { scope, handler, invocation: matchedInvocation }] of handlers.entries()) {
+            const execution = await this.runHandler(event, handler, index, matchedInvocation, scope);
             executions.push(execution);
             logEvent(this.logging, execution.status === "passed" ? "info" : "warn", "hook_call", {
                 hookEvent: event,
@@ -447,20 +450,33 @@ export async function loadProjectHookConfig(workspaceRoot) {
         ...(diagnostics.length > 0 ? { diagnostic: diagnostics.join(" | ") } : {}),
     };
 }
-function hookRuleMatches(matcher, invocation) {
+function matchHookRule(matcher, invocation) {
     if (!matcher)
-        return true;
+        return invocation;
     if (matcher.workspaceMode && invocation.workspaceMode !== matcher.workspaceMode)
-        return false;
+        return undefined;
     if (matcher.tool) {
         if (typeof invocation.payload?.tool !== "string" || invocation.payload.tool !== matcher.tool) {
-            return false;
+            return undefined;
         }
     }
+    let matchedInvocation = invocation;
     if (matcher.commandRegex) {
         const command = invocation.payload?.command;
-        if (typeof command !== "string" || !new RegExp(matcher.commandRegex).test(command)) {
-            return false;
+        if (typeof command !== "string")
+            return undefined;
+        const commandMatch = new RegExp(matcher.commandRegex).exec(command);
+        if (!commandMatch)
+            return undefined;
+        if (commandMatch[0] !== command) {
+            matchedInvocation = {
+                ...invocation,
+                payload: {
+                    ...invocation.payload,
+                    command: commandMatch[0],
+                    originalCommand: command,
+                },
+            };
         }
     }
     if (matcher.pathRegex) {
@@ -471,15 +487,15 @@ function hookRuleMatches(matcher, invocation) {
         const matchesPath = typeof path === "string" && pathPattern.test(path);
         const matchesPaths = Array.isArray(paths) && paths.some((entry) => typeof entry === "string" && new RegExp(pathRegex).test(entry));
         if (!matchesPath && !matchesPaths)
-            return false;
+            return undefined;
     }
     if (matcher.provider) {
         if (typeof invocation.payload?.provider !== "string" ||
             invocation.payload.provider !== matcher.provider) {
-            return false;
+            return undefined;
         }
     }
-    return true;
+    return matchedInvocation;
 }
 function hookEnvironment(baseEnv, event, invocation) {
     return {

package/dist/server.js

@@ -317,6 +317,9 @@ ${stylesheets}
   </body>
 </html>`;
 }
+function appDomain(config) {
+    return new URL(config.publicBaseUrl).origin;
+}
 function appCsp(config) {
     const publicBaseUrl = config.publicBaseUrl.replace(/\/+$/, "");
     return {
@@ -360,6 +363,7 @@ async function readWorkspaceAppResource(config, requestedUri, transportSessionId
                     text: workspaceAppHtml(config),
                     _meta: {
                         ui: {
+                            domain: appDomain(config),
                             csp: appCsp(config),
                         },
                     },
@@ -658,6 +662,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         description: "Interactive card for viewing ForgeRelay file diffs.",
         _meta: {
             ui: {
+                domain: appDomain(config),
                 csp: appCsp(config),
             },
         },

package/docs/configuration.md

@@ -211,7 +211,7 @@ Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；
   "event": "BeforeTool",
   "matcher": {
     "tool": "bash",
-    "commandRegex": "^git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+$"
+    "commandRegex": "git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+"
   },
   "command": "npm run release:verify",
   "timeoutSeconds": 300,
@@ -255,7 +255,7 @@ forgerelay hooks check --project /path/to/project
 | 字段 | 匹配方式 |
 | --- | --- |
 | `tool` | 精确匹配 MCP tool 名称。 |
-| `commandRegex` | 对 tool payload 中的 `command` 做 JavaScript 正则匹配。 |
+| `commandRegex` | 对 tool payload 中的 `command` 做 JavaScript 正则匹配；命中后 Hook 收到的 `payload.command` 是实际匹配片段，完整原命令在片段不等于整串命令时保留为 `payload.originalCommand`。 |
 | `pathRegex` | 对 payload 中的 `path` 或 `paths` 做正则匹配。 |
 | `provider` | 精确匹配 subagent provider。 |
 | `workspaceMode` | `checkout` 或 `worktree`。 |

package/docs/debugging.md

@@ -60,7 +60,7 @@ The acceptance checks:
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
 5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
 6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, canonical `processId` plus the deprecated `sessionId` compatibility alias, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-workspace schema, and MCP App tool metadata;
-7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
+7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, the unique app domain plus CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
 8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessManager`, and a deliberate failed `edit`;
 9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP transport session, plus rejection of an arbitrary path outside the workspace/temp roots;
 10. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;

package/docs/roadmap.md

@@ -104,29 +104,75 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 
 ## 0.3 — MCP loading 与渐进式能力披露
 
-0.3 的目标是缩小 MCP 首次加载时注入给 Agent 的上下文，同时保持工具可调用性、安全边界和 Host 编排权不变。ForgeRelay 不再把所有低频能力说明都塞进 server instructions 或工具 description，而是把模型接口拆成三层：
+0.3 的目标是把 ForgeRelay 的 MCP interface 做成一个深而稳定的模型接口：普通编码 primitive 始终直接可见，低频知识与低频 action 都按需披露，新增 ForgeRelay 能力不再线性扩大 Host 首次加载的 `tools/list` 与 instructions。
 
-- `tools/list` 继续暴露真实可调用 primitive，并只携带调用该工具所必需的简洁语义；
-- `open_workspace` 返回紧凑的 server/capability 摘要与版本指纹，帮助 Agent 发现能力，并识别 Host 持有旧 tool schema snapshot 的情况；
-- ForgeRelay-owned capability guide 提供低频能力的完整说明，由 Agent 在任务相关时显式 `read`，而不是首次连接时自动注入。
+0.3.0 已完成第一阶段：压缩 server instructions、由 `open_workspace` 返回 version/capability fingerprint、通过 advertised path + `read` 按需加载 ForgeRelay-owned capability guide，并用 fingerprint 与 Host `tools/list` 的差异诊断 stale Host metadata。Capability guide 与 Skill 的语义所有权保持区分：Skill 描述用户、项目或生态工作流；Capability guide 描述 ForgeRelay 自身、与版本绑定的产品能力。
 
-首版优先复用现有 Skill-style 的 advertised path / `read` 授权机制，而不是新增第二套文档加载协议。Capability guide 与 Skill 的语义所有权保持区分：Skill 描述用户、项目或生态工作流；capability guide 描述 ForgeRelay 自身、与版本绑定的产品能力。
+0.3 后续阶段采用 ADR-0002 的接口形状。Canonical Core tool surface 最终固定为：
 
-Core Capability Contract 必须始终内联保留至少这些信息：
+```text
+open_workspace
+close_workspace
+read
+write
+edit
+rename
+delete
+bash
+capability
+```
+
+其中 `open_workspace` 负责 Workspace 生命周期入口与轻量 Capability catalog；`capability` 是唯一低频 Capability gateway；`bash` 同时承担命令启动与后续 process interaction；Managed worktree 是 Workspace 的 backing mode，由 `close_workspace` 统一完成关闭/finalize lifecycle。Capability registry 只能暴露显式注册、带输入约束、可用性和 guide metadata 的 ForgeRelay capability，不能退化成任意 RPC、URL dispatcher 或 shell 后门。
+
+### 0.3.1 — MCP App 与诊断补丁
+
+在不改变主 tool surface 的前提下先修 0.3.0 发布后真实 Host 暴露的问题：
+
+- 为 MCP App resource 补齐 Host submission 所需的 widget/app domain metadata，并保持现有 CSP、content-hash URI 与 compatibility resource contract；
+- `forgerelay doctor` 显示解析后的 MCP 运行形态，例如 tool mode、widgets、public URL、proxy trust 与可选 capability 开关，避免“功能代码存在但当前实例未启用”只能靠源码排查；
+- 补齐 release/Host integration 的诊断与验收用例，但不在这一版重塑 tool schema。
+
+### 0.3.2 — Capability Registry 与 Gateway
+
+建立新的低频 action seam，但保留现有公开工具作为迁移兼容：
+
+- 新建 ForgeRelay-owned Capability registry，每项至少声明稳定 name、简短 description、availability、input contract、guide metadata 与 handler；
+- 新增唯一 MCP tool `capability`，提供紧凑的 `describe` / `run` 语义；
+- `open_workspace` 返回轻量 Capability catalog，只做发现，不复制完整 schema、示例或 guide 正文；
+- Agent 已熟悉某项 capability 时可以直接执行；不熟悉时先 `describe`，再按返回的 guide path 使用 `read` 获取详细说明；
+- 选择一组低风险、当前主要依赖 CLI 的检查型能力作为 tracer bullet，验证 registry、Hooks、日志、错误和 Host card contract，而不是一开始迁移所有功能。
+
+### 0.3.3 — 低频 Action 迁入 Gateway
+
+用真实现有能力验证 Gateway 能承载持续扩展，而不是只做一层转发：
+
+- 将 change review 收口为如 `review.changes` 的 registered capability；
+- 将 native artifact ingress 收口为如 `artifact.download` 的 registered capability；
+- 适合 Agent 主动调用的 Hook inspection/check 等低频操作进入同一 namespace model；
+- Capability guide 与 catalog/registry 建立一一可追踪关系，availability 由运行时条件决定；
+- `show_changes`、`download_artifact` 等旧 dedicated MCP tools 在迁移窗口内只作为兼容入口，不再作为长期接口设计。
 
-- `workspaceId` 生命周期与 workspace 复用规则；
-- 常用文件读写改、`rename` 同时承担 move/rename、删除的核心语义；
-- shell 以本地用户权限执行且不是 OS sandbox；
-- `processId` / `write_stdin` 的基本长进程语义；
-- Hook 阻断结果必须对 Agent 可见；
-- 关键 mutation/safety invariant；
-- `close_workspace` 与 `close_worktree` 的区别。
+### 0.3.4 — Workspace 与 Process 生命周期收敛
 
-适合按需读取的首批领域包括：生命周期 Hooks、managed worktree 高级流程、subagents、artifact/review 工作流、debug/MCP App、OAuth/deployment，以及 shell/PTTY/process 的低频边界情况。首个实现切片迁移 Hooks 与 managed worktree 高级说明；第二切片继续覆盖 subagents、artifact/review、Host/OAuth/MCP App integration 与 shell/PTTY/process，并把历史 bundled `subagent-delegation` Skill 的默认自动发现迁回 ForgeRelay-owned capability guide。必要安全语义始终保留在 core contract 或真实 tool schema/description 中。
+移除两个泄漏内部实现的 public lifecycle tool：
 
-Capability/version fingerprint 必须是轻量、语义化、稳定的摘要，不复制完整 `tools/list`。当 server 报告的能力与 Host 当前暴露的 tool snapshot 明显不一致时，Agent 应能判断为 Host metadata stale，并建议刷新 MCP 或开启新会话，而不是错误断言 ForgeRelay 缺少能力。
+- `bash` 成为 Process Manager 的唯一公开 interface；`action="run"` 启动命令，`action="process"` 使用 `processId` 查看、等待、输入、调整 PTY 或中断已有进程；内部 ProcessManager 可以继续保留更细的方法，但 Host 不再需要学习 `write_stdin`；
+- `close_workspace` 成为唯一 workspace 关闭入口；checkout 直接释放，managed-worktree-backed Workspace 在同一接口内执行 BeforeWorktreeClose、commit/integrate/cleanup、AfterWorktreeClose 并关闭 Workspace；
+- 从 canonical MCP surface 删除 `write_stdin` 与 `close_worktree`，同时清理对应 server instructions、fingerprint 和 capability guide 中的旧心智模型；
+- 保留 `processId` 作为运行中进程的 opaque handle，保留 worktree 作为 Workspace 的可观察 backing metadata，而不是第二套 Host lifecycle。
 
-0.3 不隐藏 callable tool，不增加隐式 autonomous workflow，也不把 Host Refresh/session 行为归到 ForgeRelay。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
+### 0.3.5 — Canonical MCP Surface 收口
+
+完成 0.3 的接口稳定化与真实 Host 验收：
+
+- regular ForgeRelay MCP surface 收口为 9 个 canonical tools；`minimal/full` 不再通过增减 `grep/glob/ls` 改变主产品心智模型，搜索与目录检查可由 `bash` 承担；
+- 评估并隔离 `codex` compatibility surface，使其作为明确 adapter 存在，而不是反向定义 ForgeRelay canonical interface；
+- 删除已经完成迁移的 dedicated low-frequency tool aliases，确保新增 Capability 不再扩大常驻 tool count；
+- 简化 fingerprint，使其用于版本/运行时能力摘要与 stale-Host 诊断，而不是重新枚举 tool implementation；
+- 对 `open_workspace → catalog → capability describe/read/run`、managed worktree close、长进程 interaction、review/artifact capability、MCP App 与 stale-schema 情况做 7677 acceptance 和新 Host 会话验收；
+- 0.3.5 通过后，0.3 的 MCP progressive-disclosure 主题视为完成，0.4 回到原定 LSP code intelligence v1。
+
+必要安全语义始终留在 Core tool interface、Capability contract 或自动 Hook report 中；渐进式披露不能成为隐藏权限、隐式 autonomous workflow 或绕过 allowed roots/auth 的机制。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
 
 ## 0.4 — LSP code intelligence v1
 
@@ -151,20 +197,7 @@ Initial operations:
 - workspace symbols;
 - hover/type information.
 
-Prefer one deep MCP capability such as:
-
-```text
-code_intelligence({
-  workspaceId,
-  operation,
-  path,
-  line,
-  column,
-  query
-})
-```
-
-rather than one MCP tool per language or language-server method.
+Expose code intelligence through the Capability Gateway established in 0.3 rather than adding another top-level MCP tool. A representative registered capability may look like `code.intelligence`, with its language-server operation/path/position/query fields carried inside the capability arguments. The exact LSP contract remains 0.4 work; the stable Core tool surface does not change per language or language-server method.
 
 Candidate servers include `typescript-language-server`/tsserver, Pyright,
 `rust-analyzer`, `gopls`, and `clangd`, but ForgeRelay should treat server
@@ -176,22 +209,7 @@ ForgeRelay already owns provider adapters and resumable local agent sessions.
 The next step is to remove the current `bash -> forgerelay agents ...` indirection
 for MCP hosts.
 
-A compact interface should reuse the existing provider adapter registry:
-
-```text
-subagent({
-  action: "run" | "list" | "show" | "cancel",
-  workspaceId,
-  profile,
-  provider,
-  prompt,
-  agentId
-})
-```
-
-The parent agent chooses an available provider/profile such as Codex or Claude.
-ForgeRelay launches, tracks, resumes, and cancels the provider-backed worker when
-the underlying provider supports those operations.
+First-class subagent operations should reuse the Capability Gateway established in 0.3 rather than add another top-level MCP tool. The exact registered names, action semantics and provider/session contract remain 0.5 design work. The parent agent will continue choosing from available provider/profile metadata while ForgeRelay owns provider-backed worker lifecycle state.
 
 This is intentionally provider-backed delegation, not an attempt to emulate a
 host-native subagent implementation.

package/docs/setup.md

@@ -120,7 +120,9 @@ npx @akira-tl/forgerelay doctor
 ```
 
 The doctor command reports the resolved config, Node runtime, platform, Git,
-Bash, public URL, allowed hosts, and native SQLite dependency status.
+Bash, public URL, allowed hosts, native SQLite dependency status, and the MCP
+shape ForgeRelay will expose: tool mode, widget mode, one-hop proxy trust, and
+whether optional artifact, subagent, and Skill capabilities are enabled.
 
 ## Running from a local checkout
 

package/docs/versioning.md

@@ -168,7 +168,9 @@ npm publishing token.
    git push origin v0.2.0
    ```
 
-The tag push is the publication action.
+The tag push is the publication action. The release workflow publishes npm only after cloud CI passes, then extracts the matching `CHANGELOG.md` release section as the GitHub Release body. Keep `Unreleased` user-facing and structured (`Added`, `Changed`, `Fixed`, `Security`) because those notes are what users see on the Release page.
+
+Project release Hooks match the stable tag-push command as a substring of the ForgeRelay shell request. A compound command is allowed: when `commandRegex` matches `git push origin vX.Y.Z`, the Hook receives that matched command as `FORGERELAY_HOOK_PAYLOAD.command` and retains the complete shell request as `originalCommand` when they differ.
 
 ## Attribution guardrails
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -45,6 +45,18 @@ const { env } = createDebugEnvironment({
   hookLog,
   widgets: "full",
 });
+const doctor = spawnSync(process.execPath, ["--import", "tsx", "src/cli.ts", "doctor"], {
+  cwd: repoRoot,
+  env,
+  encoding: "utf8",
+});
+assert.equal(doctor.status, 0, doctor.stderr);
+assert.match(doctor.stdout, /Public base URL: http:\/\/127\.0\.0\.1:7677/);
+assert.match(doctor.stdout, /Tool mode: full/);
+assert.match(doctor.stdout, /Widgets: full/);
+assert.match(doctor.stdout, /Trust proxy: off/);
+pass("doctor resolved MCP shape", "public URL + tool/widgets/proxy state");
+
 const server = spawn(process.execPath, ["--import", "tsx", "src/cli.ts", "serve"], {
   cwd: repoRoot,
   env,
@@ -161,7 +173,9 @@ try {
     method: "resources/list",
     params: {},
   }).message.result.resources;
-  assert.ok(resources.some((resource) => resource.uri === templateUri));
+  const currentResource = resources.find((resource) => resource.uri === templateUri);
+  assert.ok(currentResource);
+  assert.equal(currentResource._meta?.ui?.domain, debugBaseUrl);
   assert.ok(resources.some((resource) => resource.uri === "ui://forgerelay/workspace-app.html"));
 
   const resourceTemplates = mcpRequest(oauth.accessToken, sessionId, {
@@ -185,6 +199,7 @@ try {
   assert.equal(template.uri, templateUri);
   assert.equal(template.mimeType, "text/html;profile=mcp-app");
   assert.match(template.text ?? "", /<script type="module" crossorigin src="[^"]+\/mcp-app-assets\//);
+  assert.equal(template._meta?.ui?.domain, debugBaseUrl);
   assert.ok(template._meta?.ui?.csp?.resourceDomains?.includes(debugBaseUrl));
   const scriptUrl = template.text?.match(/<script type="module" crossorigin src="([^"]+)"/)?.[1];
   assert.ok(scriptUrl);
@@ -655,8 +670,9 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
     [
       'import { writeFileSync } from "node:fs";',
       'const payload = process.env.FORGERELAY_HOOK_PAYLOAD ?? "{}";',
+      'const parsed = JSON.parse(payload);',
       'writeFileSync("release-ci-ran.txt", payload);',
-      'if (JSON.parse(payload).command === "git push origin v0.2.1") process.exit(17);',
+      'if (parsed.command === "git push origin v0.2.1") process.exit(17);',
       "",
     ].join("\n"),
   );
@@ -664,7 +680,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
     join(releaseProject, ".forgerelay", "hooks", "release-tag-local-ci.json"),
     JSON.stringify({
       event: "BeforeTool",
-      matcher: { tool: "bash", commandRegex: "^git push origin v0\\.2\\.[01]$" },
+      matcher: { tool: "bash", commandRegex: "git push origin v0\\.2\\.[01]" },
       command: "node .forgerelay/release-check.mjs",
       timeoutSeconds: 30,
       report: true,
@@ -682,11 +698,17 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
 
   const pushed = callTool(accessToken, sessionId, 12, "bash", {
     workspaceId: releaseWorkspaceId,
-    command: "git push origin v0.2.0",
+    command: "git status --short && git push origin v0.2.0 && echo release-pushed",
   });
   assert.equal(pushed.isError, undefined);
   assert.match(toolText(pushed), /release-tag-local-ci \(BeforeTool, project\) passed/);
   assert.ok(existsSync(join(releaseProject, "release-ci-ran.txt")));
+  assert.deepEqual(JSON.parse(readFileSync(join(releaseProject, "release-ci-ran.txt"), "utf8")), {
+    tool: "bash",
+    command: "git push origin v0.2.0",
+    workingDirectory: ".",
+    originalCommand: "git status --short && git push origin v0.2.0 && echo release-pushed",
+  });
   assert.equal(
     gitOutput(releaseRemote, ["rev-parse", "refs/tags/v0.2.0"], { gitDir: true }),
     gitOutput(releaseProject, ["rev-parse", "v0.2.0"]),
@@ -694,7 +716,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
 
   const blocked = callTool(accessToken, sessionId, 13, "bash", {
     workspaceId: releaseWorkspaceId,
-    command: "git push origin v0.2.1",
+    command: "git status --short && git push origin v0.2.1 && echo should-not-run",
   });
   assert.equal(blocked.isError, true);
   assert.match(toolText(blocked), /release-tag-local-ci.*failed/);

package/scripts/release-version.mjs

@@ -46,8 +46,20 @@ switch (command) {
     await prepareRelease(state, incrementVersion(state.pkg.version, bump), dryRun);
     break;
   }
+  case "notes": {
+    checkState(state);
+    if (!value) fail("usage: node scripts/release-version.mjs notes vX.Y.Z");
+    const version = value.startsWith("v") ? value.slice(1) : value;
+    if (!stableVersionPattern.test(version)) {
+      fail(`release notes version ${JSON.stringify(value)} must be vX.Y.Z or X.Y.Z`);
+    }
+    const body = getReleaseBody(state.changelog, version);
+    if (!body) fail(`CHANGELOG.md has no release notes for ${version}`);
+    process.stdout.write(`${body}\n`);
+    break;
+  }
   default:
-    fail(`unknown release command ${JSON.stringify(command)}; expected check, tag, or next`);
+    fail(`unknown release command ${JSON.stringify(command)}; expected check, tag, next, or notes`);
 }
 
 async function readState() {
@@ -182,6 +194,17 @@ function getUnreleasedBody(changelog) {
   return changelog.slice(bodyStart, bodyEnd).trim();
 }
 
+function getReleaseBody(changelog, version) {
+  const heading = `## [${version}]`;
+  const headingIndex = changelog.indexOf(heading);
+  if (headingIndex < 0) return "";
+  const headingEnd = changelog.indexOf("\n", headingIndex);
+  const bodyStart = headingEnd < 0 ? changelog.length : headingEnd + 1;
+  const nextHeadingIndex = changelog.indexOf("\n## [", bodyStart);
+  const bodyEnd = nextHeadingIndex < 0 ? changelog.length : nextHeadingIndex;
+  return changelog.slice(bodyStart, bodyEnd).trim();
+}
+
 function incrementVersion(version, bump) {
   const match = version.match(stableVersionPattern);
   if (!match) fail(`cannot increment invalid stable version ${JSON.stringify(version)}`);