repo-radar

repo-radar は何をしますか？

ダッシュボードは1つのHTMLファイルで、scripts/dashboard.py によってGitHubからデータを取得します。必要なものはPython 3.10+、PyYAML、GitHub CLI（gh）（サインイン済み）のみです。AIを一切呼び出さないため、無料でGitHub Actions上で毎朝自動再構築できます。

タブ

タブ	表示内容
Plan	リポジトリにPlanファイルがある場合のみ表示。システムの各部分をボックスで表し、各ボックスのオーナー、構築済み・レビュー中・未着手のアイテムを表示。PRがマージまたはクローズされたアイテム、およびどのアイテムも指していないオープンPRをフラグ付けします。
Pull requests	オープンなPRを、必要なアクション別に並べ替え：マージ準備完了、レビュー待ち、作者待ち、チェック失敗、ドラフト。「Start here」では最大5件をピックアップ。
Issues	オープンなIssue：未担当、担当者あり、PRが紐づいているもの。
Graph	オープンな作業の関連性：Planボックス→Issue→PR、サブIssue、「blocked by」、他のPRのブランチ上に構築されたPR。
Done	過去90日間にクローズされたPRとIssueを、それらをリリースしたリリースごとに表示。

セットアップ方法は2つあります。どちらが適切か不明な場合は、ユーザーに確認してください。

方法	対象	追加されるものと場所
単一リポジトリ内（init）	そのリポジトリで作業している人	そのリポジトリ内に日次Actionを追加し、そのリポジトリのページを構築
ウォッチリスト（init --watch）	マネージャーや講師のように複数リポジトリを監視する人	自分のリポジトリの1つに日次Actionを追加し、監視対象リポジトリごとのページと概要ページを構築。監視対象のリポジトリには何も追加されない

SCRIPT は、このスキルのフォルダ内の scripts/dashboard.py、または init を実行したリポジトリ内の .github/dashboard/dashboard.py を指します。

Planファイル（オプション）

Planはシステムに何が必要かをリストアップします。これはGitHubでは把握できない情報、つまり誰もIssueやPRをまだ作成していない部分を表します。完全なフォーマットは scripts/dashboard_plan.py の先頭にあり、templates/plan.yaml がスターターとして利用できます。簡単に説明すると：グループ化されたボックス、各ボックスはアイテムのリスト、各アイテムは built（構築済み）、simulated（シミュレーション済み）、pr（PR番号付き）、または missing（未着手）のいずれかです。ボックスには owner を設定するか、グループのオーナーを継承します。デフォルトの場所は docs/plan.yaml です。別のパスを指定する場合は --plan オプションを使用します。

ルール

1. まずレポートし、求められた場合のみ編集する。 スクリプトは決してPlanを編集しません。ユーザーから自分のPRをPlanに載せるよう依頼があった場合のみ編集します。
2. ユーザー自身のアイテムのみを編集する。 他の人のアイテムと as_of 行はそのままにします。複数の人が同じ行を編集しないようにするためです。
3. ユーザーが毎週のリフレッシュを実行しない限り、アイテムを built とマークしない。 毎週1回、PRがマージされた後、1人がこれを行います。代わりに「マージされました。毎週のリフレッシュの準備ができました」と伝えてください。
4. ステータスをでっち上げない。 アイテムが pr となるのは、その作業を行うオープンなPRがある場合のみです。どのボックスにPRが属するか判断できない場合は、質問してください。
5. HTMLページをメインブランチにコミットしない。 日次Actionはそれを独自の dashboard ブランチに保持します。手動で構築したページは、リポジトリ外の一時フォルダ（以下 <scratch dir>）に配置します。

リポジトリにセットアップする

何かを書き込む前に、一度にまとめて質問してください。

• チームはPlanを使いますか？使う場合、場所はどこですか（デフォルト docs/plan.yaml）、既に存在するものはありますか？上記のフォーマットに合致するファイルであれば、既存のものをそのまま使えます。
• 何時に再構築しますか？ActionはUTCを使用します。デフォルトは毎日11:00 UTCです。

その後、リポジトリのトップフォルダから実行します。

python SCRIPT init                                   # スクリプト + 日次Action
python SCRIPT init --with-plan                       # ... およびスターター用の docs/plan.yaml
python SCRIPT init --plan path/to/plan.yaml          # ... 既存のPlanを使用

init は .github/dashboard/（スクリプト）と .github/workflows/dashboard.yml を作成し、既存のファイルがある場合は上書きしません。その後：

1. ローカルで1度ページを構築（次のセクション）し、表示してユーザーが動作を確認できるようにします。
2. スターターPlanを作成した場合は、ユーザーと一緒にグループ、ボックス、オーナー、および各オーナー名をGitHubログインにマッピングする people リストを記入します。
3. コミットすべき内容（init が作成したファイルとPlan）と、それがデフォルトブランチに到達した後、Actionsタブ（「Dashboard」→「Run workflow」）からすぐに実行できることを伝えます。
4. 毎朝の確認方法を伝えます。 git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html その後、dashboard.html を開きます。公開リポジトリの場合は、代わりに dashboard ブランチでGitHub Pagesを有効にし、Webアドレスを取得することもできます。

Actionがプッシュ時に「Permission denied」で失敗する場合、リポジトリまたは組織がActionsの権限を制限しています。設定 → Actions → 一般 → ワークフローの権限で「読み取りと書き込み」に変更してください。この設定変更はユーザー自身が行います。

ウォッチリストをセットアップする（複数リポジトリ）

何かを書き込む前に、一度にまとめて質問してください。監視するリポジトリ（owner/name形式）、Planが docs/plan.yaml 以外にあるリポジトリがあるか、ウォッチリストを保持する自分のリポジトリ（新しい空のリポジトリでも可）、および再構築時間（UTC）です。

何かを書き込む前に、ページを一度構築してユーザーが確認できるようにします。

python SCRIPT watch --list <scratch dir>/watchlist.yaml --out <scratch dir>/radar

そのフォルダ内の index.html を開きます。読み取りできないリポジトリは、他のリポジトリを止めることなく、その行にエラーを表示します。通常は名前のタイポか、プライベートリポジトリが原因です。

次に、ウォッチリストを保持するリポジトリで以下を実行します。

python SCRIPT init --watch            # スクリプト、watchlist.yaml、および .github/workflows/radar.yml

ユーザーのリポジトリを watchlist.yaml に書き込み、その後ユーザーに伝えます。

1. コミットすべき内容（init --watch が作成したファイル）と、それがデフォルトブランチに到達した後、Actionsタブ（「Radar」→「Run workflow」）からすぐに実行できること。
2. プライベートリポジトリにはトークンが必要です。 Actionは公開リポジトリと自身のリポジトリのみ読み取れます。プライベートリポジトリを監視するには、ユーザーがそれらを読み取れるGitHubトークンを作成し、監視用リポジトリのシークレット RADAR_TOKEN として保存します（設定 → Secrets and variables → Actions）。この作業はユーザー自身が行います。トークンを要求したり、どこかに貼り付けたりしないでください。
3. 毎朝の確認方法を伝えます。 mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar その後、radar/index.html を開きます。

後でリポジトリを追加または削除するには、watchlist.yaml を編集するだけで、他の変更は不要です。

リポジトリ内のスクリプトを更新する

init はスクリプトをリポジトリにコピーするため、リポジトリは更新されるまで、その時点のバージョンを実行し続けます。ユーザーがリポジトリ内のrepo-radarを更新するよう依頼した場合、またはこのスキルのスクリプトがリポジトリのものより新しい場合、リポジトリのトップフォルダから以下を実行します。

python scripts/dashboard.py update        # このスキルのコピーを使用。.github/dashboard/ のものではない

これにより、.github/dashboard/ 内のスクリプトのみが置き換えられ、変更されたファイルが表示されます。Action、ウォッチリスト、Planはユーザーが設定したまま維持されます。その後、.github/dashboard/ をコミットするようユーザーに伝えます。

今すぐ確認する

python SCRIPT build --out <scratch dir>/dashboard.html

リポジトリ内で実行するか（または --repo owner/name を渡します）、リポジトリ外の一時フォルダにページを書き込みます（コミットを防ぐため）。その後、ユーザーにページを表示します。「Start here」カードとPlanタブの黄色いタグから始めて、内容を平易な言葉で説明します。すべてのカウントは具体的に伝えます。「レビューが必要なPRが12件あります」ではなく、「16件のオープンPRのうち12件がレビューを必要としています」のように。

Where am I（1人のユーザー、Planとの照合）

2つの名前が必要です。Planに書かれているオーナー名とGitHubログインです。Planの people リストに gh がサインインしているログインがある場合、スクリプトは自動的に名前を見つけます。それ以外の場合は質問し、--owner "<名前>" を渡します。--login は、ユーザーが他の誰かについて質問している場合にのみ渡します。

ユーザーがプルリクエストブランチにいる場合は、2回実行します。mainはチームが今日見ているものを表示し、ブランチはこのプルリクエストが何を変更するかを表示します。

git fetch origin
python SCRIPT me --ref origin/main
python SCRIPT me

レポートには4つのテーブルがあります。

テーブル	ユーザーに伝える内容
Your boxes	自分がオーナーまたはPRを持つ各ボックスについて：構築済み、シミュレーション済み、PR中、未着手のアイテム数
Items still missing	次の作業。ボックスごとに表示
Items marked pr, checked against GitHub	オープンPRは何もする必要がない。マージ済みPRは毎週のリフレッシュの準備ができている。クローズされマージされていないPRは、アイテムを missing に戻すべき
Your open pull requests with no item on the plan	Planにまだ表示されていない作業

次の順序で説明します。完了およびレビュー中のもの。PlanにないPRと、それぞれがどのボックスに属する可能性が高いか。PRがマージされずにクローズされたアイテム。最初の未着手アイテムを次のタスクとして提示します。

PRをPlanに載せる（依頼があった場合のみ）

mainではなく、ユーザーのプルリクエストブランチで作業します。

1. プルリクエスト番号を見つける：gh pr view --json number,title。
2. そのPRが構築するアイテムを見つける。Plan内のユーザーのボックスを読む。
   • 既にその作業を説明するアイテムがある場合、ステータスを pr に変更し、pr: <番号> を追加する。
   • 該当するアイテムがない場合、適切なボックスに追加する：{status: pr, pr: <番号>, text: "<何を構築するか>"}。text は短く簡潔に保つ。どのボックスか不明な場合はユーザーに確認する。
3. Planがまだ正しく読み込めるか確認する：python SCRIPT build --out <scratch dir>/check.html。エラーがある場合は、メッセージで間違いを特定して停止します。
4. 再度 me を実行する。PRが「Items marked pr」の下に表示され、「no item on the plan」には表示されないはずです。
5. Planファイルをユーザーのプルリクエストにコミットする。

毎週のリフレッシュ（実行する人のみ）

main上でページを構築するか、各オーナーに対して me --ref origin/main を1回実行します。その後、1つのプルリクエストで以下を行います。

• PRがマージされた各アイテムを built にマークする。マージされた作業がスタブ、フェイク、またはスケルトンの場合は simulated にマークする。Planタブではこれらに「merged」タグが付きます。
• マージされずにクローズされたPRの各アイテムを missing に戻す。
• アイテムのないオープンPR（Planタブの最後のセクション）をプルリクエストの説明にリストアップし、各オーナーが配置できるようにする。ボックスを推測してはいけません。
• as_of を、確認に使用したmainのコミットと日付に設定する。

ネットワークアクセスなしでの使用

python SCRIPT fetch --out data.json でGitHubからのデータを保存し、その後 build --data data.json および me --data data.json でオフラインでも動作します。テストではこれを使用します。