# クラウド契約とプロジェクト所在を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 account ` を正規表現で | | git | `git config --global user.email` | メール | | ホスティング(Vercel等) | ` whoami` / ` teams ls` | ユーザー名・チーム | | クラウド(GCP等) | ` 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` のみ可）を送る **ソース文字列検査のテスト**で固定するのが効く: ```js 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('', 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` 等）を足したら、 **呼び出し側にそれが入っていることをテストで固定する。** ```js 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廃棄のときは行を消す運用を決めておく。 ---