proof-pr 0.1.13 → 0.1.15

package/README.md

@@ -12,7 +12,7 @@ ProofPR 是给开源维护者和工程团队使用的 PR 证据门禁。它在
 npx proof-pr@latest --version
 ```
 
-当前应输出 `0.1.13`。
+当前应输出 `0.1.15`。
 
 不知道用哪个功能时：
 
@@ -22,13 +22,26 @@ npx proof-pr@latest
 npx proof-pr@latest guide
 ```
 
+不接入仓库，先体验报告：
+
+```bash
+npx proof-pr@latest demo workflow --locale zh-CN
+npx proof-pr@latest demo --list
+```
+
 初始化配置和 GitHub Action：
 
 ```bash
 npx proof-pr@latest init
 ```
 
-这个命令会生成 `.proofpr.yml` 和 `.github/workflows/proofpr.yml`，提交后打开 PR 即可看到报告。
+这个命令会生成 `.proofpr.yml`、`.github/workflows/proofpr.yml` 和 `.github/pull_request_template.md`，提交后打开 PR 即可看到报告。
+
+已接入仓库单独补 PR 模板：
+
+```bash
+npx proof-pr@latest template
+```
 
 体检接入状态：
 
@@ -36,7 +49,7 @@ npx proof-pr@latest init
 npx proof-pr@latest doctor
 ```
 
-这个命令会检查配置文件、workflow、Action 版本、PR 权限和本地 diff 是否可读。
+这个命令会检查配置文件、workflow、PR 模板、Action 版本、PR 权限和本地 diff 是否可读。
 
 本地扫描当前分支：
 
@@ -47,7 +60,7 @@ npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN
 扫描内置案例：
 
 ```bash
-npx proof-pr@latest scan --diff-file examples/cases/workflow-untrusted-checkout.diff --locale zh-CN
+npx proof-pr@latest demo workflow --locale zh-CN
 ```
 
 生成独立 HTML 可视化报告：
@@ -65,7 +78,7 @@ npx proof-pr@latest benchmark --cases benchmarks/cases
 ## GitHub Action
 
 ```yaml
-- uses: linsk27/proof-pr@v0.1.13
+- uses: linsk27/proof-pr@v0.1.15
   with:
     fail-on: high
     comment: "true"

package/dist/index.js

@@ -25728,7 +25728,131 @@ function dedupeFindings(findings) {
 
 
 const execFileAsync = (0,external_node_util_namespaceObject.promisify)(external_node_child_process_.execFile);
-const CLI_VERSION = "0.1.13";
+const CLI_VERSION = "0.1.15";
+const DEMO_CASES = [
+    {
+        id: "workflow",
+        title: "高权限 workflow 运行不可信 PR 代码",
+        description: "演示 pull_request_target 与 PR head checkout 组合风险。",
+        diffText: `diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
+index 1111111..2222222 100644
+--- a/.github/workflows/pr.yml
++++ b/.github/workflows/pr.yml
+@@ -1,7 +1,17 @@
+ name: PR automation
+ on:
++  pull_request_target:
++    types: [opened, synchronize]
++
+ jobs:
+   test:
+     runs-on: ubuntu-latest
+     steps:
+-      - uses: actions/checkout@v4
++      - uses: actions/checkout@v4
++        with:
++          repository: \${{ github.event.pull_request.head.repo.full_name }}
++          ref: \${{ github.event.pull_request.head.sha }}
++      - run: pnpm install
++      - run: pnpm test
+`
+    },
+    {
+        id: "secret",
+        title: "疑似 secret 被提交",
+        description: "演示 .env、OpenAI key、数据库连接串等敏感内容会被拦截。",
+        diffText: `diff --git a/.env b/.env
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/.env
+@@ -0,0 +1,2 @@
++OPENAI_API_KEY=sk-proj-examplevalueexamplevalue1234567890
++DATABASE_URL=postgres://demo:super-secret-password@example.com:5432/app
+`
+    },
+    {
+        id: "dependency",
+        title: "依赖大版本升级",
+        description: "演示依赖 major upgrade 需要 changelog、迁移说明和验证证据。",
+        diffText: `diff --git a/package.json b/package.json
+index 1111111..2222222 100644
+--- a/package.json
++++ b/package.json
+@@ -1,8 +1,8 @@
+ {
+   "dependencies": {
+-    "react": "^18.2.0",
++    "react": "^19.0.0",
+     "zod": "^3.25.1"
+   },
+   "devDependencies": {
+     "typescript": "^5.9.3"
+   }
+ }
+`
+    },
+    {
+        id: "mcp",
+        title: "MCP 本地命令和凭据面",
+        description: "演示 MCP / agent 配置中的 command、args、env 风险。",
+        diffText: `diff --git a/.cursor/mcp.json b/.cursor/mcp.json
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/.cursor/mcp.json
+@@ -0,0 +1,11 @@
++{
++  "mcpServers": {
++    "local-admin": {
++      "command": "node",
++      "args": ["scripts/admin-server.js"],
++      "env": {
++        "API_TOKEN": "\${LOCAL_API_TOKEN}"
++      }
++    }
++  }
++}
+`,
+        config: { preset: "mcp-security" }
+    },
+    {
+        id: "ui-evidence",
+        title: "UI 改动缺少截图证据",
+        description: "演示 Evidence Contract：组件改动必须提供截图和验证说明。",
+        diffText: `diff --git a/src/components/Button.tsx b/src/components/Button.tsx
+index 1111111..2222222 100644
+--- a/src/components/Button.tsx
++++ b/src/components/Button.tsx
+@@ -1,3 +1,7 @@
+ export function Button() {
+-  return <button>Save</button>;
++  return (
++    <button className="primary">
++      Save
++    </button>
++  );
+ }
+`,
+        config: {
+            evidence: {
+                contracts: [
+                    {
+                        id: "ui-screenshot",
+                        title: "UI changes need screenshots",
+                        paths: ["src/components/**"],
+                        requires: ["screenshot", "verification"],
+                        severity: "medium"
+                    }
+                ]
+            }
+        },
+        pullRequest: {
+            title: "Update button styling",
+            body: "This updates the primary button style and spacing so the layout is easier to scan."
+        }
+    }
+];
 const build_program = new Command();
 build_program
     .name("proof-pr")
@@ -25745,6 +25869,7 @@ build_program
     .description("Check whether ProofPR is installed correctly in the current repository.")
     .option("--config <path>", "Path to .proofpr.yml.", ".proofpr.yml")
     .option("--workflow-path <path>", "Path to the GitHub Actions workflow.", ".github/workflows/proofpr.yml")
+    .option("--pr-template-path <path>", "Path to the pull request template.", ".github/pull_request_template.md")
     .option("--base <ref>", "Base git ref used for local diff checks.", "origin/main")
     .option("--head <ref>", "Head git ref used for local diff checks.", "HEAD")
     .action(async (options) => {
@@ -25754,6 +25879,46 @@ build_program
         process.exitCode = 1;
     }
 });
+build_program
+    .command("template")
+    .description("Create a ProofPR-friendly pull request template.")
+    .option("--output <path>", "Path to write the pull request template.", ".github/pull_request_template.md")
+    .option("--force", "Overwrite the existing template.", false)
+    .action(async (options) => {
+    await writeIfMissing(options.output, renderPullRequestTemplate(), options.force);
+    process.stdout.write(`ProofPR pull request template written to ${options.output}\n\nNext:\n1. Commit the template.\n2. Ask contributors to fill verification, reproduction, screenshot, changelog, and permission rationale sections when relevant.\n3. Run npx proof-pr@latest doctor to check setup.\n`);
+});
+build_program
+    .command("demo")
+    .description("Run a built-in ProofPR demo case without cloning this repository.")
+    .argument("[case]", "Demo case id. Use --list to see available cases.", "workflow")
+    .option("--list", "List built-in demo cases.", false)
+    .option("--format <format>", "Output format: markdown, json, sarif, or html.", parseFormat, "markdown")
+    .option("--output <path>", "Write demo report output to a file instead of stdout.")
+    .option("--locale <locale>", "Report language: en or zh-CN.", "zh-CN")
+    .action(async (caseId, options) => {
+    if (options.list) {
+        process.stdout.write(renderDemoList());
+        return;
+    }
+    const demoCase = DEMO_CASES.find((item) => item.id === caseId);
+    if (!demoCase) {
+        throw new Error(`Unknown demo case "${caseId}". Run "proof-pr demo --list" to see available cases.`);
+    }
+    const result = scanDiff(demoCase.diffText, {
+        config: demoCase.config,
+        pullRequest: demoCase.pullRequest
+    });
+    const locale = parseLocale(options.locale, "zh-CN");
+    const output = renderDemoOutput(demoCase, result, options.format, locale);
+    if (options.output) {
+        await writeOutput(options.output, `${output}\n`);
+        process.stdout.write(`ProofPR demo ${options.format} report written to ${options.output}\n`);
+    }
+    else {
+        process.stdout.write(`${output}\n`);
+    }
+});
 build_program
     .command("scan", { isDefault: true })
     .description("Scan a git diff and print a ProofPR report.")
@@ -25796,13 +25961,26 @@ build_program
     .description("Create a starter .proofpr.yml and GitHub Actions workflow.")
     .option("--config-path <path>", "Path to write the ProofPR configuration file.", ".proofpr.yml")
     .option("--workflow-path <path>", "Path to write the GitHub Actions workflow.", ".github/workflows/proofpr.yml")
+    .option("--no-pr-template", "Skip creating .github/pull_request_template.md.")
+    .option("--pr-template-path <path>", "Path to write the pull request template.", ".github/pull_request_template.md")
     .option("--preset <preset>", `Config preset: ${listConfigPresets().join(", ")}.`, parsePresetOption, "open-source-maintainer")
     .option("--fail-on <level>", "Workflow failure threshold: low, medium, high, or never.", parseFailLevel, "high")
     .option("--force", "Overwrite existing files.", false)
     .action(async (options) => {
     await writeIfMissing(options.configPath, renderConfigTemplate(options.preset), options.force);
     await writeIfMissing(options.workflowPath, renderWorkflowTemplate(options.failOn), options.force);
-    process.stdout.write(`ProofPR initialized.\n\nCreated:\n- ${options.configPath}\n- ${options.workflowPath}\n\nNext:\n1. Commit these files.\n2. Open or update a pull request.\n3. Read the ProofPR comment or Actions summary.\n\nLocal check:\nnpx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN\n\nNeed another task?\nnpx proof-pr@latest guide\n`);
+    const created = [options.configPath, options.workflowPath];
+    const skipped = [];
+    if (options.prTemplate) {
+        const wroteTemplate = await writeIfMissingSoft(options.prTemplatePath, renderPullRequestTemplate(), options.force);
+        if (wroteTemplate) {
+            created.push(options.prTemplatePath);
+        }
+        else {
+            skipped.push(`${options.prTemplatePath} already exists`);
+        }
+    }
+    process.stdout.write(`ProofPR initialized.\n\nCreated:\n${created.map((item) => `- ${item}`).join("\n")}${skipped.length > 0 ? `\n\nSkipped:\n${skipped.map((item) => `- ${item}`).join("\n")}` : ""}\n\nNext:\n1. Commit these files.\n2. Open or update a pull request.\n3. Read the ProofPR comment or Actions summary.\n\nLocal check:\nnpx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN\n\nNeed another task?\nnpx proof-pr@latest guide\n`);
 });
 build_program
     .command("benchmark")
@@ -25849,33 +26027,40 @@ function renderGuide() {
 
 1. 接入 GitHub PR 自动检查
    npx proof-pr@latest init
-   然后提交 .proofpr.yml 和 .github/workflows/proofpr.yml，打开 PR 后看评论和 Actions summary。
+   然后提交 .proofpr.yml、.github/workflows/proofpr.yml 和 .github/pull_request_template.md，打开 PR 后看评论和 Actions summary。
 
 2. 体检当前仓库接入状态
    npx proof-pr@latest doctor
-   检查配置文件、workflow、Action 版本、PR 权限和本地 diff 是否正常。
+   检查配置文件、workflow、PR 模板、Action 版本、PR 权限和本地 diff 是否正常。
 
-3. 本地检查当前分支
+3. 已接入仓库，单独补 PR 模板
+   npx proof-pr@latest template
+   引导贡献者填写验证、复现、截图、changelog 和权限理由。
+
+4. 本地检查当前分支
    npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN
    适合在发 PR 前先看风险、证据评分和 Review 行动清单。
 
-4. 生成可分享 HTML 报告
+5. 生成可分享 HTML 报告
    npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN --format html --output proofpr-report.html
    生成后用浏览器打开 proofpr-report.html。
 
-5. 生成 GitHub Code Scanning 的 SARIF
+6. 生成 GitHub Code Scanning 的 SARIF
    npx proof-pr@latest scan --base origin/main --head HEAD --format sarif --output proofpr.sarif
    适合在 CI 里配合 github/codeql-action/upload-sarif 使用。
 
-6. 试跑内置风险案例
-   npx proof-pr@latest scan --diff-file examples/cases/workflow-untrusted-checkout.diff --locale zh-CN
-   不需要改项目代码，也能快速看到 ProofPR 会抓什么风险。
+7. 不接入仓库，先试跑内置案例
+   npx proof-pr@latest demo workflow --locale zh-CN
+   不需要 clone 仓库或寻找 examples 文件，也能快速看到 ProofPR 会抓什么风险。
+
+8. 查看所有内置案例
+   npx proof-pr@latest demo --list
 
-7. 验证规则样本是否仍然命中
+9. 验证规则样本是否仍然命中
    npx proof-pr@latest benchmark --cases benchmarks/cases
    适合维护 ProofPR 规则或发版前回归。
 
-8. 调整审查强度
+10. 调整审查强度
    打开 .proofpr.yml，把 preset 改成 security-strict、dependency-careful 或 mcp-security。
 
 结果在哪里看：
@@ -25883,6 +26068,37 @@ function renderGuide() {
 - 本地 CLI：终端输出；如果用了 --output，就看写出的 HTML / JSON / SARIF / Markdown 文件。
 `;
 }
+function renderDemoList() {
+    const rows = DEMO_CASES.map((item) => `- ${item.id}: ${item.title}\n  ${item.description}`).join("\n");
+    return `ProofPR 内置案例
+
+用法：
+npx proof-pr@latest demo <case> --locale zh-CN
+
+可用案例：
+${rows}
+`;
+}
+function renderDemoOutput(demoCase, result, format, locale) {
+    if (format === "json") {
+        return JSON.stringify({
+            demo: {
+                id: demoCase.id,
+                title: demoCase.title,
+                description: demoCase.description
+            },
+            result
+        }, null, 2);
+    }
+    if (format === "markdown") {
+        return `# ProofPR demo: ${demoCase.title}
+
+${demoCase.description}
+
+${renderMarkdownReport(result, locale)}`;
+    }
+    return renderOutput(result, format, locale);
+}
 async function runDoctor(options) {
     const checks = [];
     const nextSteps = new Set();
@@ -25924,6 +26140,7 @@ async function runDoctor(options) {
         checks.push({ level: "fail", title: `缺少 ${options.workflowPath}` });
         nextSteps.add("运行 npx proof-pr@latest init 生成 .github/workflows/proofpr.yml。");
     }
+    await inspectPullRequestTemplate(options.prTemplatePath, checks, nextSteps);
     await inspectGitDiff(options, checks, nextSteps);
     if (nextSteps.size === 0) {
         nextSteps.add("当前接入状态正常；可以打开 PR，或运行 npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN 做本地自查。");
@@ -25969,6 +26186,29 @@ function inspectWorkflow(workflow, checks, nextSteps) {
         nextSteps.add("建议在 workflow permissions 中加入 contents: read。");
     }
 }
+async function inspectPullRequestTemplate(path, checks, nextSteps) {
+    if (!(await pathExists(path))) {
+        checks.push({ level: "warn", title: `缺少 ${path}` });
+        nextSteps.add("运行 npx proof-pr@latest template 生成 PR 模板，引导贡献者补充验证、复现、截图和权限理由。");
+        return;
+    }
+    const template = await (0,promises_namespaceObject.readFile)(path, "utf8");
+    checks.push({ level: "pass", title: `${path} 已存在` });
+    if (/验证|verification|test/i.test(template)) {
+        checks.push({ level: "pass", title: "PR 模板会提示验证证据" });
+    }
+    else {
+        checks.push({ level: "warn", title: "PR 模板没有明显的验证证据提示" });
+        nextSteps.add("在 PR 模板中加入“验证方式”栏目，减少 ProofPR 报告里的证据不足。");
+    }
+    if (/复现|reproduction|before|after|截图|screenshot|权限|permission/i.test(template)) {
+        checks.push({ level: "pass", title: "PR 模板覆盖复现、截图或权限理由提示" });
+    }
+    else {
+        checks.push({ level: "warn", title: "PR 模板缺少复现、截图或权限理由提示" });
+        nextSteps.add("在 PR 模板中加入复现、截图、changelog、权限理由等可选栏目。");
+    }
+}
 async function inspectGitDiff(options, checks, nextSteps) {
     try {
         const { stdout } = await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"]);
@@ -26055,6 +26295,14 @@ async function writeIfMissing(path, contents, force) {
     await (0,promises_namespaceObject.mkdir)((0,external_node_path_.dirname)(path), { recursive: true });
     await (0,promises_namespaceObject.writeFile)(path, contents, "utf8");
 }
+async function writeIfMissingSoft(path, contents, force) {
+    if (!force && (await pathExists(path))) {
+        return false;
+    }
+    await (0,promises_namespaceObject.mkdir)((0,external_node_path_.dirname)(path), { recursive: true });
+    await (0,promises_namespaceObject.writeFile)(path, contents, "utf8");
+    return true;
+}
 async function writeOutput(path, contents) {
     await (0,promises_namespaceObject.mkdir)((0,external_node_path_.dirname)(path), { recursive: true });
     await (0,promises_namespaceObject.writeFile)(path, contents, "utf8");
@@ -26102,6 +26350,33 @@ jobs:
           annotations: "true"
 `;
 }
+function renderPullRequestTemplate() {
+    return `## 变更说明
+
+请说明这个 PR 为什么需要、改了什么、影响范围是什么。
+
+## 验证方式
+
+- [ ] 已运行自动化测试：
+- [ ] 已完成手动验证：
+- [ ] 不需要测试，原因：
+
+## 复现 / Before & After
+
+如果是 bug fix，请写复现步骤、预期结果和实际结果。
+如果是 UI 改动，请附 before/after 截图或录屏。
+
+## 依赖 / CI / 权限 / MCP 变更
+
+如果改了依赖、lockfile、GitHub Actions、MCP、环境变量或权限，请说明原因和安全影响。
+
+## 发布风险
+
+- [ ] 无破坏性变更
+- [ ] 需要迁移说明 / changelog
+- [ ] 需要灰度或回滚方案
+`;
+}
 function renderOutput(result, format, locale) {
     if (format === "json") {
         return JSON.stringify(result, null, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proof-pr",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "CLI for ProofPR, a maintainer-focused pull request evidence scanner.",
   "license": "MIT",
   "type": "module",