ai-project-maintainer 0.3.0

package/ai-project-maintainer/scripts/report-summary.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { toMarkdown } from "./lib/report.mjs";
+
+export function summarizeReport(reportPath) {
+  const full = path.resolve(reportPath);
+  const text = fs.readFileSync(full, "utf8").replace(/^\uFEFF/, "");
+  const report = JSON.parse(text);
+  return toMarkdown(report);
+}
+
+function main() {
+  const reportPath = process.argv.slice(2).find((arg) => !arg.startsWith("--"));
+  if (!reportPath) {
+    console.error("Usage: node report-summary.mjs <reports/security-report.json>");
+    process.exit(2);
+  }
+  console.log(summarizeReport(reportPath));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/ai-project-maintainer/scripts/run-local-gate.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { buildAuditPlan } from "./audit-plan.mjs";
+import { detectProject } from "./lib/project-detect.mjs";
+import { getToolVersions } from "./lib/command-runner.mjs";
+import { runRegisteredChecks } from "./lib/check-registry.mjs";
+import { loadIntake } from "./lib/intake.mjs";
+import { applyPolicy, loadPolicyBundle } from "./lib/policy.mjs";
+import { buildJsonReport, toMarkdown, writeReportFiles } from "./lib/report.mjs";
+
+const versionedTools = [
+  "git",
+  "npm",
+  "pnpm",
+  "yarn",
+  "bun",
+  "gitleaks",
+  "trivy",
+  "semgrep",
+  "osv-scanner",
+  "actionlint",
+  "zizmor",
+  "syft",
+  "grype",
+  "checkov",
+  "squawk",
+  "scorecard",
+  "pre-commit",
+  "mega-linter-runner",
+];
+
+function resolveOutputPath(root, outputPath) {
+  if (!outputPath) return path.join(root, "reports", "security-report.json");
+  return path.isAbsolute(outputPath) ? outputPath : path.resolve(root, outputPath);
+}
+
+function productionAuditChecks(audit, intake) {
+  if (!audit) return [];
+  const productionPolicy = intake.riskPolicy?.production || {};
+  const blockOnCoverageGaps = Boolean(productionPolicy.block_on_coverage_gaps);
+  const blockOnUserDecisions = Boolean(productionPolicy.block_on_user_decisions);
+  return audit.plan
+    .filter((item) => item.status === "GAP" || item.status === "USER_DECISION")
+    .map((item) => ({
+      checkId: `production-${item.id}`,
+      name: `production audit: ${item.title}`,
+      group: "production-audit",
+      status: item.status,
+      blocking: item.status === "GAP" ? blockOnCoverageGaps : blockOnUserDecisions,
+      coverageGap: item.status === "GAP",
+      summary: item.summary,
+      recommendation: item.recommendation,
+    }));
+}
+
+export function runLocalGate(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const outputPath = resolveOutputPath(root, options.outputPath);
+  const writeReports = Boolean(options.writeReports);
+  const sbomOutputPath = writeReports ? path.join(path.dirname(outputPath), "sbom.cdx.json") : null;
+  if (writeReports) fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const project = detectProject(root);
+  const policyBundle = loadPolicyBundle(root);
+  const intake = options.production ? loadIntake(root, project) : null;
+  const audit = options.production ? buildAuditPlan(project, intake) : null;
+  const checks = runRegisteredChecks(project, {
+    strict: Boolean(options.strict),
+    release: Boolean(options.release),
+    noTests: Boolean(options.noTests),
+    runnerOptions: options.runnerOptions || {},
+    sbomOutputPath,
+    policy: policyBundle.policy,
+  }).concat(productionAuditChecks(audit, intake));
+  const policyResult = applyPolicy(checks, policyBundle);
+  const toolVersions = getToolVersions(versionedTools, options.runnerOptions || {});
+  const report = buildJsonReport({
+    root,
+    mode: {
+      strict: Boolean(options.strict),
+      release: Boolean(options.release),
+      noTests: Boolean(options.noTests),
+      production: Boolean(options.production),
+      policy: policyBundle.policy.mode,
+    },
+    probe: project,
+    checks: policyResult.checks,
+    toolVersions,
+    invalidExceptions: policyResult.invalidExceptions,
+    audit,
+  });
+
+  if (writeReports) writeReportFiles(report, outputPath);
+  return report;
+}
+
+function parseArgs(args) {
+  const positional = [];
+  const parsed = {
+    strict: false,
+    release: false,
+    jsonOnly: false,
+    noTests: false,
+    production: false,
+    outputPath: null,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--strict") parsed.strict = true;
+    else if (arg === "--release") parsed.release = true;
+    else if (arg === "--json") parsed.jsonOnly = true;
+    else if (arg === "--no-tests") parsed.noTests = true;
+    else if (arg === "--production") parsed.production = true;
+    else if (arg === "--output") parsed.outputPath = args[++i];
+    else if (arg.startsWith("--output=")) parsed.outputPath = arg.slice("--output=".length);
+    else if (!arg.startsWith("--")) positional.push(arg);
+  }
+
+  parsed.projectRoot = positional[0] || process.cwd();
+  return parsed;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const report = runLocalGate(args.projectRoot, {
+    strict: args.strict,
+    release: args.release,
+    noTests: args.noTests,
+    production: args.production,
+    outputPath: args.outputPath,
+    writeReports: true,
+  });
+
+  if (args.jsonOnly) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(toMarkdown(report));
+  }
+
+  process.exit(report.passed ? 0 : 1);
+}
+
+if (import.meta.url === pathToFileURL(fileURLToPath(import.meta.url)).href && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/docs/CI-GITHUB-ACTIONS.zh-CN.md

@@ -0,0 +1,83 @@
+# GitHub Actions 接入说明
+
+## 生成 CI
+
+如果已经发布到 npm，可以用：
+
+```powershell
+npx ai-project-maintainer init "E:\我的项目" --profile oss --ci github
+```
+
+如果还没有 npm 账号或还没有发布 npm 包，也可以从源码运行初始化脚本：
+
+```powershell
+git clone https://github.com/xixifusi1213-gif/ai-project-maintainer.git
+cd .\ai-project-maintainer
+npm install
+node .\ai-project-maintainer\scripts\init-project.mjs "E:\我的项目" --profile oss --ci github
+```
+
+会生成：
+
+```text
+.github/workflows/security-gate.yml
+.github/dependabot.yml
+```
+
+## CI 如何调用工具包
+
+生成出来的 GitHub Actions 模板不依赖 npm 包发布，也不需要 npm 账号。
+
+默认 workflow 会：
+
+- checkout 你的项目代码。
+- 安装 Node。
+- 根据 lockfile 安装你的项目依赖。
+- 安装常用安全扫描器。
+- 临时 clone `https://github.com/xixifusi1213-gif/ai-project-maintainer.git` 到 runner。
+- 在 runner 里安装工具包依赖。
+- 如果项目存在 `.ai-maintainer/project-profile.yml`，自动追加 `--production`。
+- 运行 `node "$RUNNER_TEMP/ai-project-maintainer/ai-project-maintainer/scripts/run-local-gate.mjs" "$GITHUB_WORKSPACE" --strict --release $EXTRA_FLAGS --output reports/security-report.json`。
+- 把 Markdown 报告写入 GitHub Step Summary。
+- 尝试上传 SARIF 到 GitHub Code Scanning。
+- 上传 `reports/` 作为 artifact。
+
+这意味着：只要你的工具包 GitHub 仓库是公开可 clone 的，同学的项目就能直接使用这套 CI 门禁，不需要你先发布 npm 包。
+
+## 阻断标准
+
+默认阻断：
+
+- 测试、构建、打包失败。
+- secret 扫描命中。
+- 生产依赖高危或严重漏洞。
+- Semgrep 阻断发现。
+- Trivy 数据库在严格模式下不可用。
+- Electron 危险配置。
+- GitHub Actions 高风险配置。
+- 过期或缺字段的例外。
+
+默认不阻断：
+
+- 缺少生产监控、日志、备份、回滚、发布审批等证据，报告中标记为 `GAP`。
+- `USER_DECISION` 项，例如核心业务流程尚未由项目负责人确认。
+
+如果希望生产证据缺口也阻断 CI，在 `.ai-maintainer/risk-policy.yml` 设置：
+
+```yaml
+production:
+  block_on_coverage_gaps: true
+```
+
+## 报告
+
+CI 上传的 `security-reports` artifact 通常包含：
+
+```text
+security-report.json
+security-report.md
+security-report.sarif
+sbom.cdx.json
+```
+
+`security-report.md` 会包含 `Production Audit`、`Coverage Gaps` 和 `User Decisions`。

package/docs/DEMO.md

@@ -0,0 +1,81 @@
+# Demo: From AI-Coded Repo to Production Audit Report
+
+This demo shows the core workflow without requiring any paid account or external API.
+
+## 1. Initialize The Project
+
+```powershell
+npx ai-project-maintainer init "E:\my-project" --profile oss --ci github
+```
+
+This creates the local policy, exceptions file, GitHub Actions workflow, Dependabot config, and report directory.
+
+## 2. Create Production Audit Intake
+
+```powershell
+npx ai-project-maintainer init-audit "E:\my-project"
+```
+
+This creates:
+
+```text
+.ai-maintainer/project-profile.yml
+.ai-maintainer/evidence-sources.yml
+.ai-maintainer/business-flows.yml
+.ai-maintainer/risk-policy.yml
+.ai-maintainer/threat-model.md
+.ai-maintainer/release-checklist.yml
+.ai-maintainer/incident-runbook.md
+.ai-maintainer/db-migration-policy.yml
+.ai-maintainer/observability-checklist.yml
+```
+
+These files record project facts and evidence locations. They should not contain tokens, DSNs, passwords, or production secrets.
+
+## 3. Generate An Audit Plan
+
+```powershell
+npx ai-project-maintainer audit-plan "E:\my-project" --output reports/audit-plan.json
+```
+
+Example output:
+
+```text
+PASS          Production audit intake is present.
+USER_DECISION Critical business flows must be declared.
+GAP           No GitHub Actions workflow evidence detected.
+GAP           No production release approval evidence declared.
+GAP           Error monitoring evidence is missing.
+N/A           No database surface detected or declared.
+```
+
+The point is not to pretend the project is safe. The point is to make missing production evidence visible.
+
+## 4. Run The Production Gate
+
+```powershell
+npx ai-project-maintainer gate "E:\my-project" --production --strict --release --output reports/security-report.json
+```
+
+The report combines deterministic scanner output with production-readiness evidence:
+
+```text
+PASS gitleaks secret scan
+PASS trivy filesystem scan
+PASS semgrep static scan
+GAP  Error monitoring evidence is missing.
+GAP  Production logs evidence is missing.
+USER_DECISION Critical business flows must be declared.
+```
+
+See [sample report](demo-output/security-report.md).
+
+## 5. Let Codex Fix Blockers
+
+Ask Codex:
+
+```text
+$ai-project-maintainer run the production gate for this project, fix blockers, and rerun until it passes.
+```
+
+Codex can handle deterministic blockers. The maintainer still owns business decisions such as critical flows, accepted risks, and production evidence.

package/docs/DEMO.zh-CN.md

@@ -0,0 +1,81 @@
+# 演示：从 AI coding 项目到生产审查报告
+
+这个 demo 不需要付费账号，也不需要外部 API。
+
+## 1. 初始化项目门禁
+
+```powershell
+npx ai-project-maintainer init "E:\我的项目" --profile oss --ci github
+```
+
+这会生成本地策略、例外文件、GitHub Actions、Dependabot 配置和报告目录。
+
+## 2. 生成生产审查画像
+
+```powershell
+npx ai-project-maintainer init-audit "E:\我的项目"
+```
+
+这会生成：
+
+```text
+.ai-maintainer/project-profile.yml
+.ai-maintainer/evidence-sources.yml
+.ai-maintainer/business-flows.yml
+.ai-maintainer/risk-policy.yml
+.ai-maintainer/threat-model.md
+.ai-maintainer/release-checklist.yml
+.ai-maintainer/incident-runbook.md
+.ai-maintainer/db-migration-policy.yml
+.ai-maintainer/observability-checklist.yml
+```
+
+这些文件只记录项目事实和证据来源，不应该写 token、DSN、密码或生产 secret。
+
+## 3. 生成审计计划
+
+```powershell
+npx ai-project-maintainer audit-plan "E:\我的项目" --output reports/audit-plan.json
+```
+
+示例输出：
+
+```text
+PASS          生产审查画像已存在。
+USER_DECISION 需要项目负责人声明核心业务流程。
+GAP           没有 GitHub Actions 证据。
+GAP           没有生产发布审批证据。
+GAP           缺少错误监控证据。
+N/A           没有检测到数据库。
+```
+
+重点不是假装项目安全，而是把“缺少哪些生产证据”明确写出来。
+
+## 4. 运行生产级门禁
+
+```powershell
+npx ai-project-maintainer gate "E:\我的项目" --production --strict --release --output reports/security-report.json
+```
+
+报告会把确定性扫描结果和生产准备度证据合在一起：
+
+```text
+PASS gitleaks secret scan
+PASS trivy filesystem scan
+PASS semgrep static scan
+GAP  缺少错误监控证据。
+GAP  缺少生产日志证据。
+USER_DECISION 需要声明核心业务流程。
+```
+
+查看 [示例报告](demo-output/security-report.md)。
+
+## 5. 让 Codex 修阻断项
+
+对 Codex 说：
+
+```text
+$ai-project-maintainer 对这个项目运行生产级门禁，修复阻断项，然后重新运行直到通过。
+```
+
+Codex 可以处理确定性的阻断项。项目负责人仍然负责核心业务流程、风险接受和生产证据判断。

package/docs/GITHUB-LAUNCH-CHECKLIST.md

@@ -0,0 +1,77 @@
+# GitHub Launch Checklist
+
+These steps require GitHub UI access if `gh` is not authenticated locally.
+
+## Repository About
+
+Open the repository page and click the gear icon in the About panel.
+
+Description:
+
+```text
+Production-readiness audit and CI gate for AI-coded projects.
+```
+
+Topics:
+
+```text
+ai-coding
+devsecops
+security
+production-readiness
+codex
+github-actions
+semgrep
+trivy
+gitleaks
+ai-agents
+```
+
+## Social Preview
+
+Upload a social preview image in repository settings.
+
+Recommended source:
+
+```text
+assets/social-preview.png
+```
+
+Editable source:
+
+```text
+assets/social-preview.svg
+```
+
+If GitHub asks for PNG/JPG, export the SVG to PNG at `1280x640`.
+
+## Release
+
+Create release:
+
+```text
+Tag: v0.3.0
+Title: v0.3.0: Production audit intake and gate for AI-coded projects
+```
+
+Release notes:
+
+```text
+## Highlights
+
+- Added `init-audit` to generate project profile and production evidence templates.
+- Added `audit-plan` to produce project-specific production-readiness plans.
+- Added `gate --production` to combine scanner evidence with production audit evidence.
+- GitHub Actions can automatically enable production mode when `.ai-maintainer/project-profile.yml` exists.
+- Reports now include `GAP`, `N/A`, and `USER_DECISION` production audit states.
+
+## Verification
+
+- npm test
+- npm run check
+- npm pack --dry-run
+```
+
+## First Launch Posts
+
+Use `docs/PROMOTION.md` for English and Chinese launch copy.

package/docs/INSTALL.zh-CN.md

@@ -0,0 +1,112 @@
+# AI Project Maintainer 使用说明
+
+## 这是什么
+
+`ai-project-maintainer` 是一个面向 AI coding 和开源项目维护者的半自动维护门禁。
+
+它不会保证项目绝对安全，也不会替你完全自动维护生产项目。它负责把常见、专业、可重复的检查组织起来：测试、secret、依赖漏洞、静态安全扫描、CI 配置、SBOM、Electron 风险、数据库迁移风险、生产证据缺口和报告证据包。
+
+## 推荐用法：npx
+
+发布到 npm 后，可以这样使用：
+
+```powershell
+npx ai-project-maintainer doctor
+npx ai-project-maintainer init "E:\我的项目" --profile oss --ci github
+npx ai-project-maintainer init-audit "E:\我的项目"
+npx ai-project-maintainer audit-plan "E:\我的项目" --output reports/audit-plan.json
+npx ai-project-maintainer gate "E:\我的项目" --production --strict --release --output reports/security-report.json
+npx ai-project-maintainer summary "E:\我的项目\reports\security-report.json"
+```
+
+## 从源码运行
+
+如果还没有 npm 版本，也可以从 GitHub 克隆后直接运行源码脚本：
+
+```powershell
+git clone https://github.com/xixifusi1213-gif/ai-project-maintainer.git
+cd .\ai-project-maintainer
+npm install
+node .\ai-project-maintainer\scripts\doctor.mjs
+node .\ai-project-maintainer\scripts\init-project.mjs "E:\我的项目" --profile oss --ci github
+node .\ai-project-maintainer\scripts\init-audit.mjs "E:\我的项目"
+node .\ai-project-maintainer\scripts\audit-plan.mjs "E:\我的项目" --output reports/audit-plan.json
+node .\ai-project-maintainer\scripts\run-local-gate.mjs "E:\我的项目" --production --strict --release --output reports/security-report.json
+```
+
+## 安装为 Codex Skill
+
+```powershell
+git clone https://github.com/xixifusi1213-gif/ai-project-maintainer.git
+cd .\ai-project-maintainer
+Copy-Item -Recurse .\ai-project-maintainer "$env:USERPROFILE\.codex\skills\ai-project-maintainer"
+```
+
+复制完成后重启 Codex，然后在项目线程中输入：
+
+```text
+$ai-project-maintainer 先为这个项目生成生产审查画像，再生成审计计划，最后运行生产级门禁并修复阻断项。
+```
+
+## 初始化项目
+
+```powershell
+npx ai-project-maintainer init "E:\我的项目" --profile oss --ci github --pre-commit
+```
+
+会生成：
+
+```text
+.ai-maintainer/policy.yml
+.ai-maintainer/exceptions.yml
+.github/workflows/security-gate.yml
+.github/dependabot.yml
+.pre-commit-config.yaml
+reports/.gitkeep
+```
+
+生成的 GitHub Actions workflow 不要求工具包已经发布到 npm。CI 会临时 clone `https://github.com/xixifusi1213-gif/ai-project-maintainer.git`，然后用 `node` 运行仓库里的门禁脚本。
+
+## 生产级审查
+
+正式审查前先运行：
+
+```powershell
+npx ai-project-maintainer init-audit "E:\我的项目"
+```
+
+这会生成项目画像、证据来源、核心业务流程、风险策略、威胁模型、发布清单、事故手册、数据库迁移策略和观测性清单。
+
+用户需要填写业务判断和证据来源，例如：
+
+- 这个项目是否有登录、权限、支付、财务、隐私数据。
+- 核心业务流程是什么，哪些结果不能错。
+- 是否有数据库、迁移、备份、回滚。
+- 是否有 CI、发布审批、监控、日志、指标、告警。
+
+再运行：
+
+```powershell
+npx ai-project-maintainer audit-plan "E:\我的项目" --output reports/audit-plan.json
+npx ai-project-maintainer gate "E:\我的项目" --production --strict --release --output reports/security-report.json
+```
+
+默认情况下，缺少生产证据会标记为 `GAP`，不会直接失败。已经检查失败的高风险项仍然会失败，例如测试失败、secret 泄露、危险 Electron 配置、过期例外。
+
+如果希望缺少生产证据也阻断发布，在 `.ai-maintainer/risk-policy.yml` 设置：
+
+```yaml
+production:
+  block_on_coverage_gaps: true
+```
+
+## 门禁状态
+
+- `PASS`：已检查并通过。
+- `FAIL`：已检查并失败。
+- `WARN`：有风险但默认不阻断。
+- `GAP`：缺少证据，无法判断。
+- `N/A`：该项目不适用。
+- `USER_DECISION`：需要项目负责人判断。
+
+真正决定是否失败的是阻断项；维护分和生产证据缺口用于帮助你判断项目健康度。