repoready

repoready

一个仓库在技术上可以非常出色，却仍可能在最初的十分钟内失去第一位贡献者：没有 README 为他们指引方向，没有安装步骤可供遵循，也没有测试命令来证明环境配置成功。repoready 根据你提供的信息评估这段初次体验——不会运行任何内容。

你只需提供仓库的文件列表（如果有 README 内容，也一并提供），还可以选择提供 package.json 脚本。它会按固定顺序返回八项检查，每项都包含通过或失败状态，以及准确的详情字符串：

• readme — README 是否存在
• install_docs — README 是否说明了安装方法
• test_script — 是否定义了 test 脚本
• test_command_docs — README 是否说明了测试命令
• license — 是否存在许可证文件
• contributing — 是否存在贡献指南
• ci — .github/workflows/ 下是否存在 CI 工作流
• lockfile — 是否存在已知的锁文件

前四项是必要检查。结果还会统计通过项数（共 8 项），按检查顺序列出未通过的必要检查，并且仅当所有必要检查都通过时才将 ready 设为 true。因此，仓库即使在辅助检查（许可证、贡献指南、CI、锁文件）中得分很高，也仍可能被如实标记为尚未就绪，因为新手无法安装它或运行测试。

按输入顺序，第一个 basename 小写后为 readme.md 或以 readme. 开头的文件会被视为 README。如果未提供其内容，两项文档检查会明确说明这一点（README content not supplied），而不会根据文件名猜测。basename 匹配不区分大小写；CI 检查要求路径前缀必须精确为 .github/workflows/；锁文件检查识别 package-lock.json、yarn.lock、pnpm-lock.yaml、Cargo.lock、poetry.lock、Pipfile.lock 和 go.sum。

无效输入——文件列表缺失或为空、文件路径缺失、为空或重复、content 不是字符串，或 package_scripts 的值不是字符串——会产生指明问题路径的验证错误，且不会生成部分评估结果。计算过程纯粹在本地完成：不访问网络、不需要配置，也不会执行任何内容。

CLI

npx @reneturcios/repoready assess --input args.json
npx @reneturcios/repoready --version

args.json 包含完整的参数对象：

{
  "files": [
    { "path": "README.md", "content": "# Demo\n\n## Install\n\nnpm install\n\nRun npm test to verify.\n" },
    { "path": "LICENSE" },
    { "path": "CONTRIBUTING.md" },
    { "path": ".github/workflows/ci.yml" },
    { "path": "package-lock.json" }
  ],
  "package_scripts": { "test": "node --test", "build": "tsc" }
}

评估结果会以 JSON 格式输出：

{
  "checks": [
    { "id": "readme", "status": "pass", "detail": "README found at README.md" },
    { "id": "install_docs", "status": "pass", "detail": "README documents installation" },
    { "id": "test_script", "status": "pass", "detail": "a test script is defined" },
    { "id": "test_command_docs", "status": "pass", "detail": "README documents a test command" },
    { "id": "license", "status": "pass", "detail": "license file found at LICENSE" },
    { "id": "contributing", "status": "pass", "detail": "contributing guide found at CONTRIBUTING.md" },
    { "id": "ci", "status": "pass", "detail": "CI workflows found" },
    { "id": "lockfile", "status": "pass", "detail": "lockfile found at package-lock.json" }
  ],
  "passed": 8,
  "total": 8,
  "essential_failures": [],
  "ready": true
}

退出码：成功时为 0；运行时出错时为 1（包括输入文件无法读取或无效，以及输入无效）；用法错误时为 2。

MCP 服务

npx -y @reneturcios/repoready mcp

MCP 客户端配置：

{
  "mcpServers": {
    "repoready": {
      "command": "npx",
      "args": ["-y", "@reneturcios/repoready", "mcp"]
    }
  }
}

工具

• assess_readiness — 根据仓库文件和 package 脚本评估首次贡献准备情况。

  • files（数组，必填，至少一个）— 文件对象组成的数组，格式为 {path, content?}；path 在集合中必须唯一，content 用于 README 检查
  • package_scripts（对象，可选）— package.json 脚本，采用字符串到字符串的映射

  返回 {checks, passed, total, essential_failures, ready}。

Docker

docker run -i ghcr.io/cloudcorprecords/repoready
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/repoready assess --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios