クラウド契約とプロジェクト所在を1枚のスプレッドシート台帳に自動集約する

「あの本番サイトはどのアカウントの、どのリポジトリなのか分からない」 「何のクラウドに月いくら払っているのか誰も答えられない」 「PCごとにログインしているアカウントがバラバラで、退職時に何を止めるか分からない」

この3つを、各PCと中央が自動で書き込む1枚のスプレッドシートで解消する手順書。 複数PC・複数クラウドを少人数で回している組織向け。AI に読ませればそのまま実装できる粒度で書いてある。

---

0. 完成形

スプレッドシート1本に3タブ。行の単位が違うものを同じタブに混ぜないのが要。

タブ	1行の単位	書き手
プロジェクト所在地図	1プロジェクト	中央のスクリプト（GitHub / ホスティングの API）
クラウド契約	1契約	人＋AI（プラン・月額・支払い元）
PCログイン	PC × サービス	各PCが定期実行で自己申告

3タブが揃って初めて「この本番URLは、このリポで、この契約で動いていて、このPCが触っている」が1画面で追える。

---

1. 最初に決める3つ（ここを外すと後で作り直しになる）

1-1. 既存シートに相乗りしない

契約タブは支払い情報を持つ。社内でよくある「リンクを知っている全員が編集可」のまま放置された 管理表に相乗りさせてはいけない。新規作成し、ドメイン限定共有にする。 実装後に共有設定を実測で確認すること（「設定したつもり」で公開されている事故が多い）。

1-2. シート本文を収集側にもAIにも読ませない

列の解決と書き込みはサーバ側スクリプト（Google Apps Script 等）に閉じる。 各PCは「送るだけ」、AI は「結果の件数とキーだけ」を見る。読まなければ漏らせない。 検証用に describe 系のエンドポイントを用意し、支払い列の値は応答に含めない。

1-3. 書き込みは許可リスト（denylist にしない）

サーバ側に「機械が書いてよい見出し名」の配列を持ち、それ以外は参照すらしない。 禁止列を列挙する方式は、列が増えたときに破綻する。 許可リスト方式なら、人が新しい列を足しても構造的に安全。

---

2. タブ設計

2-1. プロジェクト所在地図

プロジェクト名 / 用途・説明 / リポジトリ / リポジトリのアカウント / 可視性 / 本番URL /
ホスティングのプロジェクト名 / ホスティングのアカウント / DBプロジェクト / 関連ドキュメント /
開発PC / ローカルパス(basename) / 最終コミット / 状態 / 備考 / 更新日時

• キーは リポジトリ（owner/repo 完全一致）。空の行は プロジェクト名 で突合。
• 機械が書く列と人が書く列を最初に分ける。用途・説明 状態 備考 は人の列＝許可リストに入れない。
• 開発PC は追記マージ（他PCのラベルを消さない）。

2-2. クラウド契約

サービス / アカウント / プラン / 月額 / 通貨 / 支払い元カード(下4桁) / 支払い元(名義) /
契約者・管理者 / 用途 / 関連プロジェクト / 管理画面URL / 請求サイクル / 次回更新日 /
解約可否メモ / 最終確認日 / 自動検出

• キーは (サービス, アカウント)。
• カードと名義は許可リストに入れない＝機械は永久に書けない。
• 各PCのログイン報告を受けたとき、(サービス, アカウント) の行が無ければ サービス名とアカウントと「自動検出」だけの空行を追加する。 → 「使っているのに台帳に無い契約」を機械が可視化する。これが棚卸しの主戦力。

2-3. PCログイン

PC名 / 実ホスト名 / OSユーザー名 / サービス / ログインアカウント / スコープ・組織 /
検出元 / 状態 / CLIバージョン / 最終報告

• ラベル単位の全置換（自分のPCの行を消してから入れ直す）。他PCの行には触らない。
• 状態 は ログイン済み / 未ログイン / CLI無し / 判定不能 の4値以上。 取得できないものを「未ログイン」と断定しない。

---

3. 収集側の実装

3-1. 何を集めるか

サービス	コマンド	取る値
GitHub	gh auth status	Logged in to <host> account <name> を正規表現で
git	git config --global user.email	メール
ホスティング(Vercel等)	<cli> whoami / <cli> teams ls	ユーザー名・チーム
クラウド(GCP等)	<cli> auth list / config get-value project	アカウント・プロジェクト
npm	npm whoami	ユーザー名（ENEEDAUTH は未ログイン）
スクリプト実行環境	認証ファイルの存在と mtime のみ	中身は読まない

3-2. 絶対にやらないこと（テストで固定する）

• 認証ファイルの中身を読む（oauth_token を含む設定ファイル、~/.aws/credentials、.netrc、.env*）
• 環境変数のうち名前に KEY / TOKEN / SECRET / PASSWORD / CREDENTIAL を含むものの値を送る
• 会話内容・ファイル本文・フルパス（basename のみ可）を送る

ソース文字列検査のテストで固定するのが効く:

test("認証ファイルを読んでいない", () => {
  const source = fs.readFileSync(new URL("./cloud-inventory.mjs", import.meta.url), "utf8");
  for (const forbidden of ["hosts.yml", "oauth_token", ".aws/credentials", ".netrc"]) {
    assert(!source.includes(forbidden), forbidden);
  }
  assert(!/process\.env\s*\[/.test(source));
});

3-3. タイムアウトと打ち切り

各コマンド10秒、全体60秒で打ち切る。タイムアウトは 判定不能 であって「未ログイン」ではない。

---

4. 実装中に必ず踏む「成功したのに空」の罠4つ

この4つは全部「例外も出ず、終了コードも0で、ログに何も出ない」型。 最初から知っていないと、動いていない台帳を「動いている」と報告してしまう。

4-1. CLI が表を stderr に書く

一部の CLI（ホスティング系に多い）は一覧そのものを stderr に出す。 stdout だけをパースすると 終了コード0のまま0件になる。

• 対策: stdout と stderr を連結してパーサに渡す。進捗行・見出し行はパーサ側で捨てる。
• 手動確認を 2>&1 付きでやるとこの欠陥を隠す。ストリームを分けて長さを両方見ること。
• パーサのテストには実機の出力全文を fixture として貼る。整形した想定出力では実物に当たらない。

4-2. Windows で .cmd シムを spawnSync から直接起動できない

npm でグローバルインストールした CLI は .cmd のラッパーなので、 spawnSync('<cli>', args) は ENOENT になる。シェル経由で起動する共有ランナーを1つ作り、全ツールがそれを使う。 各ツールが素の spawnSync を書くと、片方だけ直って片方が黙って空を返す。

4-3. サーバ側スクリプトのファイル評価順

Google Apps Script は .gs をファイル名のアルファベット順に評価する。 別ファイルの定数をトップレベルの var で束ねると、参照時点で undefined になり Cannot read properties of undefined で全機能が落ちる。

• 対策: 呼ばれた時点で組み立てる関数にして評価順に依存させない。
• テストは vm に本番と同じ順で流す1本を必ず置く。 テスト側でソースを書き換える細工（source.replace(...)）を入れたら、 それが何を隠しうるかを考える。書き換えないと通らないなら直すべきは実装。

4-4. クライアントのタイムアウト＝未達ではない

サーバ側スクリプトはコールドスタートで数十秒かかる。20秒で切ると サーバは書き込みに成功しているのにクライアントだけ「失敗」と出る。 嘘の失敗ログは、本物の障害を調べるときに真っ先に人を迷わせる。

• 60秒程度に伸ばす。メッセージに「サーバ側は完了している可能性がある」と明記する。
• 再送しない（届いていた場合に二重書き込みになる）。冪等な操作に限って再送を許す。

---

5. 冪等性と自己修復

セットアップ関数は何度実行しても壊れないように作る。作成の途中で落ちた台帳を 再実行だけで正しい形へ寄せられることが重要（人に手で直させない）。

1. スプレッドシートを作ったら真っ先に ID を保存する。 共有設定や移動で失敗しても、次回に2枚目を作らない。
2. 不足しているタブだけをヘッダ付きで補う。既存タブの中身には触らない。
3. ヘッダ行の無い空タブにヘッダを補う。 タブだけ作ってヘッダを書く前に落ちると、列数0になり以降の読み取りが全部失敗する。 タブが揃って見えるのに何も読み書きできない、という分かりにくい壊れ方になる。
4. 自動生成された既定シート（シート1 / Sheet1）は空のときだけ消す。
5. 戻り値に「作ったのか・直したのか・何もしなかったのか」を入れる。隠さない。

---

6. 定期実行への配線を機械で固定する

夜間ジョブの呼び出しに新しいフラグ（--cloud 等）を足したら、 呼び出し側にそれが入っていることをテストで固定する。

test("夜間ジョブが --cloud を渡している", () => {
  const source = fs.readFileSync(path.join(dir, "nightly-poller.mjs"), "utf8");
  const call = source.match(/report\.mjs'[^\n]*/);
  assert.ok(call);
  assert.match(call[0], /--cloud/);
});

引数が1つ落ちても誰も気付かない。実際に「フラグが抜けていて、何ヶ月も1台分しか 集まっていなかった」という事故が起きる。シェルスクリプト版と Node 版の両方を固定すること。

---

7. 突合は推測しない

リポジトリ名とホスティングのプロジェクト名はズレる（foo-unified ↔ foo、bar-cron ↔ bar）。 ここで部分一致や類似度マッチを入れたくなるが、やらない。

• 完全一致だけで突合する。
• 突合できなかったホスティング側のプロジェクトは、独立した行として必ず台帳に出す。 リポと結び付かない本番こそ迷子の本体であり、消してしまうと台帳の意味が無くなる。

実例として、ある組織で初回に走らせたところ リポジトリ16件に対しリポと結び付かない本番が8件出てきた。 これは「台帳に載らなかった8件」ではなく「今まで誰も所在を把握していなかった8件」。

---

8. 導入の順番

1. 新規スプレッドシートを作るセットアップ関数を書く（§5 の冪等性を最初から入れる）
2. サーバ側の受け口（許可リスト・タブ別のプラン関数・describe）と純ロジックのテスト
   • 列順を200回シャッフルして禁止列に1つも書かないことを検証する
   • 人が書いた非空セルが上書きされないことを検証する
   • describe の応答 JSON に支払い情報が現れないことを文字列検索で検証する
3. 収集側（各PC）と中央側（API から所在地図を生成）
4. 定期実行へ配線し、§6 のテストで固定
5. 実機で1回走らせて、シートに実際の行が入ったことを確認してから完了とする （テストが緑でも実機能の証拠にはならない）

---

9. 運用に乗ってからの注意

• プラン・月額・支払い元は自動検出できない。列だけ用意して人が埋める。 空欄のまま放置されても、機械が書く「自動検出」列と突き合わせれば 「使っているのに契約情報が空の行」がそのまま TODO リストになる。
• 同じサービスがアカウント違いで2行になることがある（サービスアカウントと人間アカウント等）。 キーが (サービス, アカウント) なので正しい挙動。統合するかは運用judgment。
• PCが増えたら PCログイン は自動で増える。減らないので、 退職・PC廃棄のときは行を消す運用を決めておく。