✨ feat: add repo preflight onboarding command

[ShigureNyako]

Summary

Fixes #15.

This PR adds gh-llm repo preflight --repo OWNER/REPO to consolidate repo-level contribution setup checks before starting work.

Motivation

Before contributing to an unfamiliar repo, users still need to manually check the default branch, whether a fork is required, onboarding docs, PR template, CODEOWNERS, and default-branch protection expectations.

Solution

• add a new repo preflight command group and renderer
• query repo metadata via gh repo view, use recursive tree scan plus common-path contents fallback for onboarding files, and read default-branch protection via REST with paginated GraphQL enrichment for rule details
• detect and render CONTRIBUTING*, AGENTS.md, PR templates, and CODEOWNERS
• generate heuristic next commands from the detected push access, onboarding files, and default-branch protection signals
• surface the command in skills/github-conversation/SKILL.md and cover it with CLI tests

Validation

• uv run pytest -q
• uv run ruff check
• uv run pyright
• uv run gh-llm repo preflight --repo PaddlePaddle/Paddle
• uv run gh-llm repo preflight --repo AutoMQ/automq

Notes

• The "next commands" section is intentionally heuristic: it is derived from the detected permissions, onboarding files, and default-branch protection signals above, so the suggestions reflect the current repo setup instead of a fixed canned list.
• AGENTS.md is included in the onboarding scan alongside CONTRIBUTING*, PR templates, and CODEOWNERS.

@SigureMo Please review this PR when you have time. Thanks!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 995c6b8b3d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds a new gh-llm repo preflight (alias: repo onboarding) command to summarize repository contribution/onboarding signals (metadata, onboarding files, branch protection) and print inferred next-step commands.

Changes:

• Introduce repo preflight data models and GitHub API resolution (repo view, tree scan, branch protection GraphQL).
• Add repo preflight/onboarding CLI command and renderer.
• Document the new command in README.md and add CLI test coverage.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_cli.py	Extends GhResponder stubs and adds a CLI test for repo preflight output.
src/gh_llm/models.py	Adds RepoPreflight-related dataclasses for repo onboarding signals.
src/gh_llm/github_api.py	Implements repo preflight resolution, document detection, and branch protection rule selection.
src/gh_llm/commands/repo.py	Adds the new repo preflight/onboarding command and output rendering.
src/gh_llm/cli.py	Registers the new repo command group with the top-level CLI parser.
README.md	Documents usage and expected output of the new command.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ShigureNyako]

结论：REQUEST_CHANGES。

说明：受当前 GitHub 账号限制影响，我无法对自己的 PR 提交 REQUEST_CHANGES 状态，所以这里用 COMMENT 形式提交正式 review；但从评审结论上看，这个 PR 还需要先改再合。

我本地复跑了 uv run ruff check、uv run pyright、uv run pytest -q，并实际运行了 uv run gh-llm repo preflight --repo PaddlePaddle/Paddle 与 uv run gh-llm repo preflight --repo AutoMQ/automq。有两个阻塞问题：

1. src/gh_llm/github_api.py:879-933 里的 branch protection 解析对真实只读贡献场景会给出错误结果。当前实现完全依赖 branchProtectionRules GraphQL 查询，但我本地实测：
   • uv run gh-llm repo preflight --repo PaddlePaddle/Paddle 输出 No branch protection rule matched develop.
   • uv run gh-llm repo preflight --repo AutoMQ/automq 输出 No branch protection rule matched main.
     但对应的 REST 分支接口 gh api repos/PaddlePaddle/Paddle/branches/develop / gh api repos/AutoMQ/automq/branches/main 都返回 protected: true，并带有 required status checks。也就是说，这个 PR 在最核心的 onboarding 信号上会出现系统性 false negative，后面的“next commands”推导也会一起失真。
2. src/gh_llm/github_api.py:2887-2888 声称匹配 CONTRIBUTING*，实际只接受 CONTRIBUTING 或 CONTRIBUTING.<ext>。我本地实测 uv run gh-llm repo preflight --repo AutoMQ/automq 时，输出里 CONTRIBUTING 是 (not found)；但 gh api repos/AutoMQ/automq/contents/CONTRIBUTING_GUIDE.md 可以正常返回。这个行为和 PR 描述 / README 中承诺的 CONTRIBUTING* 不一致，也会漏掉真实仓库里常见的贡献指引文件。

测试覆盖也还不够：当前新增测试只覆盖了一个完全理想化的 happy path（CONTRIBUTING.md + GraphQL 直接返回 branchProtectionRules 节点），没有覆盖上面这两类真实失败场景。另，当前 CI 里的 fmt 检查也还是红的。

[ShigureNyako]

已跟进本轮 review，并逐条回复 / resolve 了相关 thread。

本轮新增修复点：

• 默认分支保护改成以 REST branches/<default_branch> 为准，再用分页 GraphQL 补充分支规则细节，避免把受保护分支误判成未保护
• recursive tree 在 truncated 时回退到常见 onboarding 路径的 contents listing，并在输出里显式提示 fallback
• CONTRIBUTING* 匹配放宽到常见前缀形式，补上 CONTRIBUTING_GUIDE.md 回归测试
• CLI surface 只保留 repo preflight，去掉 onboarding alias
• README 中先移除该入口，改为优先放到 skills/github-conversation/SKILL.md

验证：

• uv run pytest -q
• uv run ruff check
• uv run pyright
• uv run gh-llm repo preflight --repo PaddlePaddle/Paddle
• uv run gh-llm repo preflight --repo AutoMQ/automq

[ShigureNyako]

结论：REQUEST_CHANGES。

说明：受当前 GitHub 账号限制影响，我无法对自己的 PR 提交 REQUEST_CHANGES 状态，所以这里继续用 COMMENT 形式提交正式 review；但从评审结论上看，这个 PR 还需要先改再合。

我独立复跑了：

• uv run pytest -q
• uv run ruff check
• uv run pyright
• uv run gh-llm repo preflight --repo PaddlePaddle/Paddle
• uv run gh-llm repo preflight --repo AutoMQ/automq
• uv run gh-llm repo preflight --repo ShigureNyako/gh-llm

前两个真实上游仓库场景这轮已经基本修正到位：branch protection 的 REST 回退、CONTRIBUTING* 匹配、CLI surface 收敛，以及对应测试都对上了。

但 fork 场景还有一个阻塞问题：当前 src/gh_llm/github_api.py 里把 parent_repo 读成了 parent.nameWithOwner，而 gh repo view --json parent 实际返回的是 parent.owner.login + parent.name。我本地实测 uv run gh-llm repo preflight --repo ShigureNyako/gh-llm 时，输出里只有 is_fork: true，没有 parent_repo / Parent repo，后续 next commands 还会生成 gh pr create --repo ShigureNyako/gh-llm --base main。这会把 fork 贡献链路导向错误目标仓库。

建议先把 fork 的 upstream 识别 / 输出 / 测试链路补齐，再合这个 PR。

[ShigureNyako]

结论：REQUEST_CHANGES。

说明：受当前 GitHub 账号限制影响，我无法对自己的 PR 提交 REQUEST_CHANGES 状态，所以这里继续用 COMMENT 形式提交正式 review；但从独立复核结论看，这个 PR 这轮还不能直接合。

我这次重点复核了三件事：

• fork / upstream / parent repo 识别是否真的修好
• next commands 的 PR 目标仓库是否已改对
• merge conflict 处理后是否引入其他行为回退

先说正向结果：fork 识别这块现在基本修正到位了。

• uv run gh-llm repo preflight --repo ShigureNyako/gh-llm 现在已经能输出 parent_repo: ShigureLab/gh-llm
• 输出里也有 Parent repo: ShigureLab/gh-llm`` 的 summary 提示
• next commands 已改成 gh pr create --repo ShigureLab/gh-llm --base main，不再错误指向 fork 自己
• 我复跑 uv run pytest -q、uv run ruff check、uv run pyright 也都通过；PaddlePaddle/Paddle 和 AutoMQ/automq 两个真实只读场景没有看到之前那类行为回退

但阻塞点也很明确：当前 PR 仍然和 main 冲突，不能确认“merge conflict 已解决”。

我本地独立复核到的证据：

• gh llm pr checks --pr 32 --repo ShigureLab/gh-llm --all：CI 的确是绿的
• 但 gh pr view 32 --repo ShigureLab/gh-llm --json mergeable,mergeStateStatus 当前返回仍是 mergeable: CONFLICTING、mergeStateStatus: DIRTY
• gh llm pr conflict-files --pr 32 --repo ShigureLab/gh-llm 明确指向 src/gh_llm/cli.py
• 我本地用 git merge-tree $(git merge-base HEAD upstream/main) HEAD upstream/main 复核后，也能看到这里和 main 上新增的 doctor 注册 / GhCommandError 处理发生了真实冲突

所以，这轮我没有再看到 fork preflight 逻辑本身的明显功能性回退，但 PR 当前仍不是可合状态。建议先把 src/gh_llm/cli.py 的冲突重新合掉，并确认 repo 与 doctor 两组 CLI 注册都保留，再回来看是否通过。

[ShigureNyako]

结论：APPROVE。

说明：受当前 GitHub 账号限制影响，我无法对自己的 PR 提交 APPROVE 状态，所以这里用 COMMENT 形式提交正式 review；但从本轮独立复核结论看，这个 PR 现在可以合。

我基于最新提交 308b67369152fac4112f960dacc7a34c69c6bce5 重点复核了三件事：

• src/gh_llm/cli.py 的 merge conflict 是否真的彻底解决
• 合并后是否同时保留 repo 注册、doctor 注册与 GhCommandError 处理
• fork / upstream / next commands 行为是否仍正确

复核结果：

1. cli.py 冲突已实际解决。当前文件里同时保留了：
   • from gh_llm.commands.repo import register_repo_parser
   • from gh_llm.commands.doctor import register_doctor_parser
   • from gh_llm.diagnostics import GhCommandError, format_command_error
     并且 _build_parser() 同时注册了 repo 与 doctor，run() 里也保留了 GhCommandError 的专门错误输出分支。
2. mergeability 已恢复正常。我本地执行 git merge-tree $(git merge-base HEAD upstream/main) HEAD upstream/main 未再看到冲突输出；gh pr view 32 --repo ShigureLab/gh-llm --json mergeable,mergeStateStatus 当前也是 MERGEABLE / CLEAN。
3. fork / upstream 行为仍然正确。uv run gh-llm repo preflight --repo ShigureNyako/gh-llm 现在会输出 parent_repo: ShigureLab/gh-llm，并生成 gh pr create --repo ShigureLab/gh-llm --base main；PaddlePaddle/Paddle 与 AutoMQ/automq 两个真实只读场景复测也没有看到之前修复项回退。

我本地复跑了：

• uv run pytest -q
• uv run ruff check
• uv run pyright
• uv run gh-llm --help
• uv run gh-llm doctor
• uv run gh-llm repo preflight --repo ShigureNyako/gh-llm
• uv run gh-llm repo preflight --repo PaddlePaddle/Paddle
• uv run gh-llm repo preflight --repo AutoMQ/automq

这轮没有再发现阻塞问题，可以合。