patchwarden 1.5.0 → 1.5.1

package/docs/open-source-application.md

@@ -0,0 +1,162 @@
+# PatchWarden Open Source Application Brief
+
+This brief is written for programs that evaluate open source maintainer work,
+including Codex-style OSS support programs. It is evidence-oriented and avoids
+claiming adoption that has not happened yet.
+
+## Project
+
+- Repository: https://github.com/jiezeng2004-design/PatchWarden
+- Package: `patchwarden`
+- License: MIT
+- Primary language: TypeScript
+- Runtime: Node.js 18+
+- Primary maintainer: `jiezeng2004-design`
+
+PatchWarden is a local-first MCP safety and verification layer for AI coding
+agents. It lets ChatGPT, Codex, OpenCode, or another MCP client plan and review
+work while a preconfigured local agent performs bounded execution inside a
+configured workspace.
+
+## Why This Matters For OSS Maintainers
+
+AI coding workflows are becoming useful for maintainers, but many local bridges
+solve convenience by exposing an unrestricted shell or broad filesystem access.
+That is a poor default for open source work, where a maintainer may have
+credentials, release artifacts, private issue context, unpublished patches, and
+multiple repositories on the same machine.
+
+PatchWarden narrows that workflow into an auditable task channel:
+
+- workspace confinement through `workspaceRoot` and repo-scoped task paths
+- pre-registered local agents instead of model-supplied shell commands
+- exact allowlisted verification commands
+- sensitive-path blocking for `.env`, tokens, SSH keys, cookies, and credential
+  material
+- scope-violation detection for unexpected out-of-repository changes
+- structured task artifacts, diffs, verification records, and evidence packs
+- release checks that distinguish local verification from GitHub/npm truth
+
+The goal is not to replace human maintainers. The goal is to make AI-assisted
+maintenance reviewable enough for routine OSS work: small fixes, test
+generation, documentation updates, release preflight checks, and post-task
+audit.
+
+## Maintainer Role
+
+I am the primary maintainer of PatchWarden. My work includes architecture,
+security boundaries, MCP tool design, TypeScript implementation, CI, release
+checklists, documentation, issue/PR templates, and package metadata.
+
+The repository is early-stage, but it is not a throwaway demo. The project has a
+documented safety model, bilingual README files, CI across Linux and Windows, a
+private security reporting path, release notes, package verification scripts,
+and a growing control center for safe summaries, audit views, lineage, and
+evidence packs.
+
+## Current Public Evidence
+
+Snapshot checked on 2026-07-12:
+
+- GitHub repository: `jiezeng2004-design/PatchWarden`
+- Stars: 2
+- Forks: 0
+- Open issues: 9 (`#25`, `#26`, `#28`–`#34`)
+- Open pull requests: 2 (`#24`, `#37`, both draft)
+- GitHub latest release: `v1.5.0`
+- npm latest dist-tag: `patchwarden@1.5.0`
+- Local source version in `package.json`: `1.5.1`
+
+The source version is ahead of the latest public Release/npm package. Treat
+`1.5.1` as pending release work until GitHub Release and npm are verified.
+
+## Existing Project Evidence
+
+Repository-facing evidence already present:
+
+- `README.md` and `README.en.md` explain the MCP bridge model, safety boundary,
+  setup, ChatGPT/Codex/OpenCode usage, and local data handling.
+- `CHANGELOG.md` records ongoing releases from the 1.0 line through 1.5.x.
+- `SECURITY.md` directs vulnerability reports to GitHub private security
+  advisories.
+- `CONTRIBUTING.md` documents local verification and safety expectations.
+- `.github/workflows/ci.yml` runs Node 20 checks on Ubuntu and Windows, full
+  regression tests, MCP smoke tests, HTTP MCP smoke tests, redacted doctor,
+  clean package verification, npm package-surface verification, and Gitleaks.
+- `.github/ISSUE_TEMPLATE/` and `.github/PULL_REQUEST_TEMPLATE.md` guide bug,
+  feature, and safety review reports.
+- `docs/release-checklist.md` separates local validation, PR review, GitHub
+  Release, npm publish, and remote publication verification.
+- `docs/chatgpt-usage.md` documents safer ChatGPT connector usage patterns.
+- `docs/demo.md` provides a privacy-safe demo flow.
+- `docs/assets/patchwarden-chatgpt-demo.svg` provides a repository-safe visual
+  demo asset.
+- `docs/assets/patchwarden-oss-demo.gif` provides a privacy-safe animated demo
+  of the maintainer workflow. It is scripted demo material, not adoption
+  evidence.
+
+## Related Project
+
+RelayForge can be mentioned as a related local-first AI coding gateway project,
+but PatchWarden should be the primary application repository because its safety
+boundary and MCP maintainer workflow are more directly aligned with Codex-style
+OSS automation.
+
+## Honest Gaps
+
+PatchWarden should not claim broad adoption yet. The strongest current argument
+is ecosystem importance, not stars or download volume.
+
+Known gaps before submission:
+
+- collect 3 to 5 real user reports through GitHub issues or discussions
+- record a live screencast if stronger evidence is needed; a privacy-safe
+  scripted GIF now exists for the public maintainer workflow
+- finish the `1.5.1` release only after PR/CI, GitHub Release, npm, and
+  `dist-tags.latest` are all verified
+- add small contributor-friendly roadmap issues such as macOS docs, Codex CLI
+  examples, and a minimal demo repository
+
+Do not fabricate feedback, usage numbers, or third-party endorsements.
+
+## Application Statement
+
+PatchWarden addresses a growing safety gap in AI coding workflows: connecting
+ChatGPT, Codex, OpenCode, and other MCP clients to local coding agents without
+giving the upstream model unrestricted shell access. It provides workspace
+confinement, command allowlists, sensitive-path blocking, scope-violation
+detection, CI-backed regression tests, release verification, and auditable task
+evidence. As the primary maintainer, I maintain the architecture, TypeScript
+implementation, documentation, security policy, tests, release workflow, and
+review process. The project is early, with low public adoption metrics, but it
+directly supports safer OSS maintainer automation for Codex-style agents.
+
+## API Credits Use
+
+API credits would be used for maintainer automation only:
+
+- Codex-assisted pull request review
+- security regression analysis
+- release evidence review
+- documentation consistency checks
+- compatibility testing across ChatGPT, Codex, OpenCode, and MCP profiles
+- issue triage and small test generation
+
+Credits would not be used to publish releases automatically, bypass human
+confirmation, inspect private credentials, or weaken PatchWarden's safety
+boundary.
+
+## Submission Checklist
+
+- [ ] Confirm GitHub stars, forks, issues, PRs, and latest release again on the
+      day of submission.
+- [ ] Confirm `npm.cmd view patchwarden version dist-tags --json`.
+- [ ] Confirm README version text matches the intended release story.
+- [ ] Link `docs/threat-model.md`.
+- [ ] Link `docs/release-evidence.md`.
+- [ ] Link `docs/user-feedback.md` only after real feedback exists.
+- [x] Prepare a privacy-safe scripted GIF without secrets or private workspace
+      names.
+- [ ] Optionally record a live screencast for stronger external evidence.
+- [ ] Do not click any final application submit button until the maintainer has
+      reviewed the form.

package/docs/opencode-worker.md

@@ -0,0 +1,151 @@
+# OpenCode worker 集成模式
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 说明：本文描述的是 PatchWarden 将 OpenCode 作为 worker agent 的集成模式建议。
+> OpenCode 是独立的本地编程 Agent 项目，本文不声称任何官方集成关系。
+
+## OpenCode 是什么
+
+OpenCode 是面向本地开发的编程 Agent，主要能力包括：
+
+- 在本地仓库中读写文件、执行命令、运行测试。
+- 接收自然语言任务描述并产出代码改动。
+- 支持多种模型后端。
+
+OpenCode 本身是通用 Agent，默认不具备 PatchWarden 的安全边界。
+本文描述如何让 PatchWarden 作为外部监督层，OpenCode 作为受约束的 worker。
+
+## External Supervisor Pattern
+
+PatchWarden 与 OpenCode 的集成采用 **external supervisor pattern**：
+
+```
+MCP 客户端 → PatchWarden（supervisor）→ OpenCode（worker）→ workspace
+                ↑ 安全边界在此
+```
+
+- **PatchWarden 作为 supervisor**：接收 MCP 客户端的任务请求，
+  负责工作区隔离、命令允许列表、范围违规检测、证据收集。
+- **OpenCode 作为 worker**：在 PatchWarden 允许的范围内执行具体编码任务。
+- **安全边界在 PatchWarden 侧**：OpenCode 的所有文件改动与命令执行
+  必须经过 PatchWarden 的策略校验。
+
+关键点：OpenCode 不直接暴露给 MCP 客户端，而是由 PatchWarden 调度。
+这避免了 OpenCode 在无监督下执行越权操作。
+
+## 配置示例
+
+### 1. 在 PatchWarden 中注册 OpenCode agent
+
+在 `.patchwarden/config.json` 中注册 OpenCode：
+
+```json
+{
+  "workspaceRoot": "D:\\repos\\my-project",
+  "agents": [
+    {
+      "name": "opencode",
+      "type": "local-worker",
+      "command": "opencode",
+      "args": ["--no-interactive"],
+      "workspace": "D:\\repos\\my-project"
+    }
+  ],
+  "evidencePackVersion": 2,
+  "safeResult": { "maxBytes": 4096 }
+}
+```
+
+### 2. 配置 project-policy.json 约束 OpenCode 的操作范围
+
+```json
+{
+  "allowedPaths": ["src/**", "test/**", "docs/**"],
+  "allowedCommands": [
+    "npm.cmd test",
+    "npm.cmd run build",
+    "git status",
+    "git diff",
+    "opencode --no-interactive"
+  ],
+  "blockedFiles": [".env", ".env.*", "id_rsa", "*.key", "*.pem", "cookies.db"],
+  "scopeRules": {
+    "enforceDeclaredFiles": true,
+    "blockOutOfWorkspace": true
+  }
+}
+```
+
+### 3. OpenCode 在 workspace 内执行
+
+OpenCode 进程由 PatchWarden 启动并监督：
+
+```powershell
+# PatchWarden 通过 MCP 工具 run_safe_task 调度 OpenCode
+# MCP 客户端传入任务描述与声明的文件范围
+# PatchWarden 在执行前校验范围，执行中监督，执行后收集证据
+```
+
+## 工作流示例
+
+### 任务：让 OpenCode 实现一个新模块
+
+1. **MCP 客户端发起任务**：
+
+```json
+{
+  "agent": "opencode",
+  "task": "add input validation to src/handlers/user.ts",
+  "declaredFiles": ["src/handlers/user.ts", "test/handlers/user.test.ts"]
+}
+```
+
+2. **PatchWarden 校验范围**：
+
+- `src/handlers/user.ts` 与 `test/handlers/user.test.ts` 在 `allowedPaths` 内。
+- `opencode` 命令在 `allowedCommands` 内。
+- 无 `blockedFiles` 命中。
+
+3. **PatchWarden 启动 OpenCode worker**：
+
+- OpenCode 在 `workspaceRoot` 下执行。
+- OpenCode 的文件改动受 PatchWarden 监督。
+- 若 OpenCode 尝试修改未声明文件，PatchWarden 触发范围违规检测并阻断。
+
+4. **任务完成后导出证据**：
+
+```powershell
+# 产物位于 .patchwarden/evidence-packs/<lineage_id>/
+# 包含 evidence.json / EVIDENCE.md / risk.json / verify.json 等 8 个文件
+```
+
+## 安全边界
+
+PatchWarden 对 OpenCode worker 的约束包括：
+
+| 维度 | 约束 |
+| --- | --- |
+| 文件读写 | 必须在 `allowedPaths` 内，命中 `blockedFiles` 即阻断 |
+| 命令执行 | 必须在 `allowedCommands` 中（精确匹配） |
+| 工作区 | OpenCode 进程的 cwd 限定在 `workspaceRoot` 下 |
+| 越界改动 | `enforceDeclaredFiles` 为 true 时，未声明文件改动被阻断 |
+| 敏感资源 | `.env`、SSH key、cookie、token 等一律不可访问 |
+| 进程监督 | OpenCode 进程由 PatchWarden launcher 拥有，可被监督与终止 |
+
+## 注意事项
+
+- OpenCode 必须以非交互模式运行（如 `--no-interactive`），避免阻塞 PatchWarden。
+- OpenCode 的模型后端配置（API key 等）属于 OpenCode 自身配置，
+  PatchWarden 不读取也不持久化这些凭据。
+- 若 OpenCode 任务需要执行 `allowedCommands` 之外的命令，
+  应先更新 `project-policy.json` 再执行，不应临时放宽约束。
+- OpenCode worker 的 stdout / stderr 由 PatchWarden 收集为有界摘要，
+  完整日志不直接暴露给 MCP 客户端。
+- 本集成模式不修改 OpenCode 的任何行为，仅在调度与监督层面配合。
+
+## 相关文档
+
+- `docs/threat-model.md`：PatchWarden 安全契约与进程监督边界。
+- `docs/evidence-pack-schema.md`：Evidence Pack v2 文件结构。
+- `docs/why-patchwarden.md`：external supervisor pattern 的定位。
+- `docs/openhands-worker.md`：类似的 worker 集成模式（OpenHands）。

package/docs/openhands-worker.md

@@ -0,0 +1,181 @@
+# OpenHands worker 集成模式
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 说明：本文描述的是 PatchWarden 将 OpenHands 作为 worker agent 的集成模式建议。
+> OpenHands 是独立的 AI 软件开发 Agent 项目，本文不声称任何官方集成关系。
+
+## OpenHands 是什么
+
+OpenHands 是面向软件开发的 AI Agent，主要能力包括：
+
+- 在本地或容器化环境中编写、修改、调试代码。
+- 执行测试、运行构建、操作文件系统。
+- 接收自然语言任务并自主规划实现步骤。
+- 支持多种模型后端与运行时环境。
+
+OpenHands 默认以较自主的方式运行，本身不具备 PatchWarden 的安全边界。
+本文描述如何让 PatchWarden 作为外部监督层，OpenHands 作为受约束的 worker。
+
+## External Supervisor Pattern
+
+PatchWarden 与 OpenHands 的集成采用 **external supervisor pattern**：
+
+```
+MCP 客户端 → PatchWarden（supervisor）→ OpenHands（worker）→ workspace
+                ↑ 安全边界在此
+```
+
+- **PatchWarden 作为 supervisor**：接收 MCP 客户端的任务请求，
+  负责工作区隔离、命令允许列表、范围违规检测、证据收集。
+- **OpenHands 作为 worker**：在 PatchWarden 允许的范围内执行软件开发任务。
+- **安全边界在 PatchWarden 侧**：OpenHands 的所有文件改动与命令执行
+  必须经过 PatchWarden 的策略校验。
+
+关键点：OpenHands 不直接暴露给 MCP 客户端，而是由 PatchWarden 调度。
+这避免了 OpenHands 在无监督下执行越权操作或访问敏感资源。
+
+## 配置示例
+
+### 1. 在 PatchWarden 中注册 OpenHands agent
+
+在 `.patchwarden/config.json` 中注册 OpenHands：
+
+```json
+{
+  "workspaceRoot": "D:\\repos\\my-project",
+  "agents": [
+    {
+      "name": "openhands",
+      "type": "local-worker",
+      "command": "openhands",
+      "args": ["--headless", "--task"],
+      "workspace": "D:\\repos\\my-project"
+    }
+  ],
+  "evidencePackVersion": 2,
+  "safeResult": { "maxBytes": 4096 }
+}
+```
+
+### 2. 配置 project-policy.json 约束 OpenHands 的操作范围
+
+```json
+{
+  "allowedPaths": ["src/**", "test/**", "docs/**"],
+  "allowedCommands": [
+    "npm.cmd test",
+    "npm.cmd run build",
+    "git status",
+    "git diff",
+    "openhands --headless"
+  ],
+  "blockedFiles": [".env", ".env.*", "id_rsa", "*.key", "*.pem", "cookies.db"],
+  "scopeRules": {
+    "enforceDeclaredFiles": true,
+    "blockOutOfWorkspace": true
+  }
+}
+```
+
+### 3. OpenHands 在 workspace 内执行
+
+OpenHands 进程由 PatchWarden 启动并监督：
+
+```powershell
+# PatchWarden 通过 MCP 工具 run_safe_task 调度 OpenHands
+# MCP 客户端传入任务描述与声明的文件范围
+# PatchWarden 在执行前校验范围，执行中监督，执行后收集证据
+```
+
+## 工作流示例
+
+### 任务：让 OpenHands 修复一个 bug
+
+1. **MCP 客户端发起任务**：
+
+```json
+{
+  "agent": "openhands",
+  "task": "fix null pointer in src/services/auth.ts when token is missing",
+  "declaredFiles": ["src/services/auth.ts", "test/services/auth.test.ts"]
+}
+```
+
+2. **PatchWarden 校验范围**：
+
+- `src/services/auth.ts` 与 `test/services/auth.test.ts` 在 `allowedPaths` 内。
+- `openhands` 命令在 `allowedCommands` 内。
+- 无 `blockedFiles` 命中。
+
+3. **PatchWarden 启动 OpenHands worker**：
+
+- OpenHands 在 `workspaceRoot` 下以 headless 模式执行。
+- OpenHands 的文件改动受 PatchWarden 监督。
+- 若 OpenHands 尝试修改未声明文件，PatchWarden 触发范围违规检测并阻断。
+- 若 OpenHands 尝试读取 `.env` 或凭据文件，PatchWarden 立即阻断。
+
+4. **任务完成后导出证据**：
+
+```powershell
+# 产物位于 .patchwarden/evidence-packs/<lineage_id>/
+# 包含 evidence.json / EVIDENCE.md / risk.json / verify.json 等 8 个文件
+```
+
+## 安全边界
+
+PatchWarden 对 OpenHands worker 的约束包括：
+
+| 维度 | 约束 |
+| --- | --- |
+| 文件读写 | 必须在 `allowedPaths` 内，命中 `blockedFiles` 即阻断 |
+| 命令执行 | 必须在 `allowedCommands` 中（精确匹配） |
+| 工作区 | OpenHands 进程的 cwd 限定在 `workspaceRoot` 下 |
+| 越界改动 | `enforceDeclaredFiles` 为 true 时，未声明文件改动被阻断 |
+| 敏感资源 | `.env`、SSH key、cookie、token 等一律不可访问 |
+| 进程监督 | OpenHands 进程由 PatchWarden launcher 拥有，可被监督与终止 |
+| 网络访问 | 取决于 OpenHands 运行时配置，PatchWarden 不放宽命令允许列表 |
+
+## 容器化运行注意事项
+
+若 OpenHands 运行在容器中，需额外注意：
+
+- PatchWarden 监督的是宿主机上的 OpenHands 进程，
+  容器内的文件系统改动应通过挂载卷映射回 `workspaceRoot`。
+- `project-policy.json` 的 `allowedPaths` 应对应宿主机路径，
+  而非容器内路径。
+- 容器内的命令执行若需被 PatchWarden 监督，
+  应通过 OpenHands 的 headless 接口走 PatchWarden 调度，
+  而非绕过 PatchWarden 直接在容器内执行。
+
+## 注意事项
+
+- OpenHands 必须以 headless / 非交互模式运行，避免阻塞 PatchWarden。
+- OpenHands 的模型后端配置（API key 等）属于 OpenHands 自身配置，
+  PatchWarden 不读取也不持久化这些凭据。
+- 若 OpenHands 任务需要执行 `allowedCommands` 之外的命令，
+  应先更新 `project-policy.json` 再执行，不应临时放宽约束。
+- OpenHands worker 的 stdout / stderr 由 PatchWarden 收集为有界摘要，
+  完整日志不直接暴露给 MCP 客户端。
+- 本集成模式不修改 OpenHands 的任何行为，仅在调度与监督层面配合。
+
+## 与 OpenCode worker 的差异
+
+OpenHands 与 OpenCode 的集成模式在结构上一致（均采用 external supervisor pattern），
+主要差异在于：
+
+| 维度 | OpenCode | OpenHands |
+| --- | --- | --- |
+| 定位 | 本地编程 Agent | AI 软件开发 Agent |
+| 运行模式 | 通常直接在宿主机 | 支持 headless 与容器化 |
+| 自主性 | 中等，偏交互式 | 较高，偏自主规划 |
+| 适用任务 | 中小规模代码改动 | 较复杂的软件开发任务 |
+
+选择哪个 worker 取决于任务复杂度与运行时偏好，
+PatchWarden 的安全边界对两者一视同仁。
+
+## 相关文档
+
+- `docs/threat-model.md`：PatchWarden 安全契约与进程监督边界。
+- `docs/evidence-pack-schema.md`：Evidence Pack v2 文件结构。
+- `docs/why-patchwarden.md`：external supervisor pattern 的定位。
+- `docs/opencode-worker.md`：类似的 worker 集成模式（OpenCode）。

package/docs/release-evidence.md

@@ -0,0 +1,72 @@
+# PatchWarden Release Evidence
+
+This file separates local source state from public release truth. Update it
+before submitting external applications or publishing a release.
+
+## Current Snapshot
+
+Checked on 2026-07-12 from the PatchWarden workspace.
+
+| Surface | Current evidence |
+| --- | --- |
+| Local branch | `codex/evidence-pack-v2` |
+| Local `package.json` | `patchwarden@1.5.1` |
+| GitHub latest release | `v1.5.0` |
+| GitHub release URL | https://github.com/jiezeng2004-design/PatchWarden/releases/tag/v1.5.0 |
+| GitHub release published at | 2026-07-07T11:36:48Z |
+| npm latest | `patchwarden@1.5.0` |
+| npm `dist-tags.latest` | `1.5.0` |
+| GitHub stars | 2 |
+| GitHub forks | 0 |
+| Open issues | 9 (`#25`, `#26`, `#28`–`#34`) |
+| Open pull requests | 2 (`#24`, `#37`, both draft) |
+
+Conclusion: `1.5.0` is the latest verified public release. The local `1.5.1`
+source state is ahead of the public release and should be treated as pending
+until PR, CI, GitHub Release, npm, and `dist-tags.latest` are all verified.
+
+## Commands Used
+
+Windows PowerShell:
+
+```powershell
+gh repo view jiezeng2004-design/PatchWarden --json nameWithOwner,stargazerCount,forkCount,issues,pullRequests,defaultBranchRef,pushedAt,url,description,licenseInfo,repositoryTopics,latestRelease,hasDiscussionsEnabled,hasIssuesEnabled,securityPolicyUrl
+gh release view v1.5.1 --repo jiezeng2004-design/PatchWarden --json tagName,name,publishedAt,isDraft,isPrerelease,url
+gh release view --repo jiezeng2004-design/PatchWarden --json tagName,name,publishedAt,isDraft,isPrerelease,url
+npm.cmd view patchwarden version dist-tags --json --cache .\.npm-cache
+```
+
+The npm query succeeded on 2026-07-12 with the repository-local `.npm-cache`:
+`version=1.5.0`, `dist-tags.latest=1.5.0`.
+
+## Local Verification Snapshot
+
+- `npm.cmd run build`: passed.
+- `npm.cmd run test:unit`: 716 tests, 714 passed, 2 skipped, 0 failed.
+- `npm.cmd run doctor:ci`: 83 OK, 0 warnings, 0 failures.
+- `npm.cmd run verify:package`: passed; 584 package files, no private local launchers.
+- `npm.cmd test`: passed in 284.5 seconds in an approved Windows child-process
+  environment. This includes 139 security smoke checks, 716 unit tests (714
+  passed, 2 skipped), 22 lifecycle checks, doctor, tunnel/watcher supervisors,
+  Windows control, MCP manifest, brand, and 32 Control Center checks.
+- `npm.cmd run test:mcp`: passed.
+- `npm.cmd run test:http-mcp`: 13 passed, 0 failed, including owner-token checks.
+- `npm.cmd run pack:clean` was not run here because it removes and recreates
+  release artifacts; run it only in an explicitly approved release-preparation
+  workspace.
+
+## Release Verification Checklist
+
+- [ ] Confirm the target version in `package.json`.
+- [ ] Confirm `src/version.ts`, package metadata, README version text, and
+      changelog agree.
+- [ ] Run the complete local gate chain from `AGENTS.md`.
+- [ ] Open a PR and wait for the GitHub CI gate.
+- [ ] Merge only after review.
+- [ ] Create the tag from the verified merge commit.
+- [ ] Create the GitHub Release with reviewed artifacts and checksums.
+- [ ] Publish `patchwarden` to npm using process-scoped authentication.
+- [ ] Verify the remote tag, GitHub Release, npm package version, and
+      `dist-tags.latest`.
+
+Do not publish new versions under the frozen pre-rename package name.