addashboard-cli 0.2.4 → 0.3.0

package/README.md

@@ -1,48 +1,479 @@
-# addashboard-cli
+# webgram CLI
 
-広告ダッシュボード操作用の CLI。詳細な使い方・運用フローは社内マニュアル参照。
+ad-dashboard を Claude Code / Codex CLI / ターミナルから操作するための CLI。
+「install → login → 広告入稿 dry-run → 実入稿」までを 1 本のマニュアルで完走できる構成にしてある。
 
-## インストール
+> 🔐 認証方式: Google SSO (loopback OAuth / 非対話環境は device flow) を主軸、`--password` (ROPC) は deprecated フォールバック
+> 📦 配布: **npm public registry** (`addashboard-cli` unscoped) — `npx -y addashboard-cli@latest` で追加インストール不要
 
-Node.js 18+ が必要。
+---
+
+## 前提
+
+- **Node.js 18+** (`node --version` で確認。無ければ [nodejs.org](https://nodejs.org) から LTS を入れる)
+- **macOS / Linux** (Windows は動作未確認)
+- **ネットワーク到達性**: `registry.npmjs.org` (npm パッケージ DL) と本番エンドポイント (API) の両方に届くこと
+- **ad-dashboard アカウント**: `@webgram.jp` の Google アカウント (推奨)。フォールバックとしてメール + パスワードも可
+
+## クイックスタート (人間向け, 5 分)
+
+### 1. 疎通確認 (npm public registry から取得)
 
 ```bash
-# 都度実行 (推奨)
-npx -y addashboard-cli@latest --help
+npx -y addashboard-cli@latest --version
+# → 0.2.3
+```
 
-# あるいはグローバルインストール
-npm install -g addashboard-cli
-webgram --help
+初回のみ npm パッケージ DL で数秒。以降は npm キャッシュから即時起動。
+
+> 💡 毎回タイプするのが面倒ならグローバルインストール:
+> ```bash
+> npm install -g addashboard-cli
+> webgram --version
+> ```
+> アンインストールは `npm uninstall -g addashboard-cli`。
+
+### 2. ログイン (ターミナルから対話実行)
+
+デフォルトは **Google アカウント (@webgram.jp) でのブラウザログイン** (loopback OAuth)。パスワードは不要。
+
+```bash
+webgram auth login
+# ブラウザで Google ログインを開きます…
+# (ブラウザで @webgram.jp アカウントを選択)
+# ✓ Logged in as you@example.com
+#   Saved to /Users/.../.config/webgram/credentials.json (chmod 0600)
 ```
 
-## ログイン
+ブラウザが自動で開かない環境では、表示された URL を手動で開けば同じフローが完了する。
+
+#### 非対話環境 (Claude Code / CI 等) — device flow
+
+`stdout` が TTY でない**非対話環境では自動で Google device flow に切り替わる** (loopback ブラウザは使えないため)。TTY でも `--device` を付ければ強制できる。
 
 ```bash
-webgram auth login    # ブラウザで認証
-webgram auth whoami   # 状態確認
-webgram auth logout
+webgram auth login          # 非対話環境では自動で device flow
+webgram auth login --device # TTY でも device flow を強制
+
+# ────────────────────────────────────────────
+#   Google でログインしてください (ブラウザ操作が必要です)
+#   1. ブラウザで次の URL を開く:  https://www.google.com/device
+#   2. 次のコードを入力して許可:  ABCD-EFGH
+#   許可が完了すると自動でログインが続行されます…
+# ────────────────────────────────────────────
+# ✓ Logged in as you@example.com
+```
+
+CLI が出力する **URL と user_code** を (別端末やスマホの) ブラウザで開いて @webgram.jp アカウントで許可すると、CLI が自動でトークンを取得して保存する。**client_secret はサーバー側で保持し、CLI には持たせない**。クライアント ID / シークレットの設定は不要 (メンバーは `webgram auth login` を実行するだけ)。
+
+#### パスワード方式 (ROPC・deprecated フォールバック)
+
+device flow もブラウザも使えない場合の**最終フォールバック**:
+
+```bash
+webgram auth login --password                                  # email/password を prompt
+webgram auth login --email you@example.com --password 'secret' # 非推奨: shell history に残る
+```
+
+> ⚠️ パスワード方式は deprecated。対話環境ではブラウザ loopback、非対話環境では device flow が自動で選ばれるため、通常は `--password` 不要。
+
+### 3. ログイン確認
+
+```bash
+webgram auth whoami
+# {"id":"...","email":"you@example.com","name":"...","role":"admin",...}
+```
+
+未ログインなら `✗ not_logged_in` + exit 1。
+
+## YDA 入稿クイックスタート (人間向け, 10 分)
+
+「YDA (Yahoo Display Ads) にキャンペーンを 1 本 PAUSED 状態で入れる」までの最短ルート。他媒体 (Meta / Google / SmartNews / ByteDance) も手順はほぼ同じ (JSON テンプレートを差し替えるだけ)。
+
+### 3-1. アカウント一覧を取得
+
+```bash
+webgram list --platform yda --resource accounts
+# [
+#   { "name": "伸長ぐんぐん習慣", "id": "1002778399" },
+#   { "name": "桑の葉&茶カテキン/株式会社WEBGRAM", "id": "1002792978" },
+#   ...
+# ]
+```
+
+> ⚠️ 一覧に出るのは **ad-dashboard の連携設定 (`ApiConnection.selectedAccounts`) に登録済みのアカウントだけ**。CLI 側でページングして全件取れるコマンドは現状無い。目的のアカウントが出ないときは、ad-dashboard の Web UI (データシンク → YDA) から `selectedAccounts` に追加する。
+
+### 3-2. 入稿ボディ雛形をコピー
+
+同梱の fixtures からコピーして書き換える:
+
+```bash
+# npm install -g addashboard-cli した場合
+cp $(npm root -g)/addashboard-cli/fixtures/yda_poc.json ./my_yda.json
+
+# あるいは GitHub の Web からダウンロード:
+# https://github.com/WEBGRAM-WG/ad-dashboard/tree/main/cli/fixtures
+```
+
+`my_yda.json` を開いて 最低限 以下を書き換える:
+
+- `accountId` — 3-1 で確認した対象アカウント ID
+- `campaigns[0].name` — 任意のユニークな名前 (例: `商品名_20260714_PoC`)
+- `campaigns[0].startDate` — 明日以降 (`YYYY-MM-DD`)
+
+他フィールドの意味は [`cli/fixtures/README.md`](./fixtures/README.md) 参照。
+
+### 3-3. dry-run (実媒体は触らない)
+
+```bash
+webgram submit --platform yda --json-file ./my_yda.json
+# → dry-run が既定。実媒体には一切触らない。zod 検証と would_create のみ返る
+```
+
+`400` が返ったら応答の `error` フィールドを確認。必須項目が抜けているケースがほとんど。
+
+### 3-4. 実入稿
+
+dry-run が警告なしで通過したら、**同じ JSON** に対して:
+
+```bash
+webgram submit --platform yda --json-file ./my_yda.json --no-dry-run --yes
+# ✓ Campaign created: campaignId=32523583
+# ✓ AdGroup created: adGroupId=451748065
+```
+
+`--no-dry-run` と `--yes` の **両方** が必須 (`--yes` なしは exit 2 で停止)。二段階ガードで事故を防いでいる。
+
+### 他媒体の入稿
+
+Meta / Google / SmartNews / ByteDance も手順は同じ。JSON テンプレは `fixtures/` 配下:
+
+| 媒体 | 必須 top-level | fixture |
+|---|---|---|
+| YDA | `accountId` | `yda_poc.json` / `yda_video_poc.json` |
+| Meta | `accountId` (`act_...`) | `meta_poc.json` |
+| Google | `customerId` | `google_poc.json` |
+| SmartNews | `accountId` | `smartnews_poc.json` |
+| ByteDance (TikTok) | `advertiserId` | `tiktok_poc.json` |
+
+各媒体の必須フィールド・制約は [`cli/fixtures/README.md`](./fixtures/README.md) にまとめている。
+
+---
+
+## 初期設定: Skill として配置する (推奨、AI エージェント経由で使う場合)
+
+Claude Code / Codex CLI から「広告運用」「YDA 入稿」等の自然言語で発火させたい場合、**`ad-ops` skill をエージェントの skills ディレクトリに配置する**のが最短。ターミナル直叩きで CLI を使う人はこの章をスキップして OK。
+
+Skill 本体 (`SKILL.md` / `config.json` / `README.md`) は npm パッケージに同梱されているため、`npm root -g` 経由か tarball 展開でコピーする。
+
+### Claude Code に配置
+
+Claude Code のチャットに以下を貼り付けて実行を依頼:
+
+```
+addashboard-cli の ad-ops skill を ~/.claude/skills/ に配置して
+```
+
+Claude が裏で `npm pack addashboard-cli` → 展開 → `cp` を実行する。手動で入れる場合:
+
+```bash
+mkdir -p ~/.claude/skills/ad-ops /tmp/ad-ops-extract
+cd /tmp/ad-ops-extract && npm pack addashboard-cli@latest
+tar xzf addashboard-cli-*.tgz --strip-components=1
+cp -r skills/ad-ops/. ~/.claude/skills/ad-ops/
+```
+
+### Codex CLI に配置
+
+Codex CLI は Claude Code のような skills 自動発火機能を持たないため、以下いずれかで SKILL.md を context に読み込ませる。
+
+**方式 A: プロジェクトルートの `AGENTS.md` に参照を書く (推奨)**
+
+作業ディレクトリの `AGENTS.md` に以下を追記:
+
+```markdown
+## 広告運用 (ad-ops skill)
+
+ad-dashboard の広告操作は `~/.codex/skills/ad-ops/SKILL.md` に従って `webgram` CLI (`npx -y addashboard-cli@latest`) 経由で実行する。設定は `~/.codex/skills/ad-ops/config.json` を参照。
+```
+
+SKILL.md 本体を配置:
+
+```bash
+mkdir -p ~/.codex/skills/ad-ops /tmp/ad-ops-extract
+cd /tmp/ad-ops-extract && npm pack addashboard-cli@latest
+tar xzf addashboard-cli-*.tgz --strip-components=1
+cp -r skills/ad-ops/. ~/.codex/skills/ad-ops/
+```
+
+**方式 B: 都度 `--instructions` で明示読み込み**
+
+```bash
+codex --instructions ~/.codex/skills/ad-ops/SKILL.md "YDA に PAUSED で入稿の dry-run 走らせて"
 ```
 
-## 主なコマンド
+**方式 C: `~/.codex/config.toml` の `instructions` に恒久追加** (Codex CLI のバージョンによる)
+
+### 発火方法
+
+配置後、以下のいずれかのキーワードでエージェントに投げると自動発火 (Codex は AGENTS.md 経由で読み込まれる):
+
+| カテゴリ | 発火キーワード例 |
+|---|---|
+| 参照系 | 「YDA のアカウント見せて」「Meta のキャンペーン一覧」「広告アカウント一覧」 |
+| 入稿系 | 「YDA に入稿して」「PAUSED で dry-run」「Meta に入稿の dry-run」 |
+| 認証系 | 「ad-dashboard のログイン状態は?」「webgram でログアウトして」 |
+| 直接指定 | 「/ad-ops」「ad-ops skill 使って」「広告運用スキルで」 |
+
+skill 側の詳細な発火条件・実行フロー・トラブルシュートは [`skills/ad-ops/README.md`](./skills/ad-ops/README.md) 参照。
+
+---
+
+## AI エージェント向け決定表
+
+Claude Code / Codex CLI などの AI エージェントが「YDA 入稿して」のような曖昧な指示を受けたときに、試行錯誤せず最短経路で完走するための決定表。
+
+### コマンド早見表
+
+| ユーザーがやりたいこと | 実行コマンド |
+|---|---|
+| 疎通確認 | `npx -y addashboard-cli@latest --help` |
+| ログイン状態確認 | `webgram auth whoami` (成功=exit 0 / `not_logged_in`=exit 1) |
+| ログイン (代行禁止 — 後述) | `webgram auth login` (Google SSO / device flow) |
+| ログアウト | `webgram auth logout` |
+| アカウント一覧 | `webgram list --platform <yda\|meta\|google\|smartnews\|bytedance> --resource accounts` |
+| キャンペーン一覧 | `webgram list --platform <媒体> --resource campaigns --account-id <id>` |
+| リソース一覧 (YDA/Meta/Google/ByteDance) | `webgram list --platform <媒体> --resource resources --account-id <id>` |
+| 入稿 dry-run | `webgram submit --platform <媒体> --json-file <path>` |
+| 実入稿 | `webgram submit --platform <媒体> --json-file <path> --no-dry-run --yes` |
+
+### 媒体別 top-level 必須フィールド
+
+エージェントが JSON を組む前に必ず参照する。詳細フィールドは fixtures を参照。
+
+| 媒体 | top-level | 子ノード必須 |
+|---|---|---|
+| yda | `accountId` / `campaigns[]` | `name` / `goal` / `status` / `startDate` / `budget≥1` / `biddingStrategy` / `cpc≥1` / `adGroups[]` |
+| meta | `accountId` (`act_` 付) / `campaigns[]` | `objective` / `status` / `buyingType` / `adSets[]` (`optimizationGoal`,`billingEvent`,`bidStrategy`,`dailyBudget≥1`,`startTime`) |
+| google | `customerId` / `campaigns[]` | `advertisingChannelType` / `status` / `budgetAmountYen≥1` / `adGroups[]` (`cpcBidYen≥1`, `ads[]`) |
+| smartnews | `accountId` / `campaigns[]` | `objective` / `status` / `startDateTime` / `adGroups[]` (`ads[].adHeadline`, `adDescription`, `adLandingPageUrl`, `mediaFileId`) |
+| bytedance | `advertiserId` / `campaigns[]` | `objectiveType` / `adGroups[]` (`optimizationGoal`, `billingEvent`, `budgetMode`, `budget≥20`, `landingPageUrl`, `locationIds`, `scheduleType`, `placementType`, `ads[]`) |
+
+### 制約チェックリスト (共通・媒体別)
+
+エージェントは JSON 生成時に以下を **必ず** 確認する:
+
+- **status は開始時点で `PAUSED` (bytedance は `DISABLE`)** — 動作確認できてから ad-dashboard UI で ACTIVE に切り替える運用
+- **予算 0 円は不可** — YDA/Meta/Google/SmartNews は 1 以上、ByteDance は 20 以上
+- **YDA 動画広告** — `videoPath` 必須、`thumbnailPath` を省略するとサムネ自動生成なし (Yahoo は自動生成しない)
+- **Google Ads** — `RESPONSIVE_SEARCH_AD` は `headlines` 3 本以上・`descriptions` 2 本以上
+- **SmartNews** — `mediaFileId` は事前に SmartNews 側にアップロード済みの画像/動画 ID が必要 (CLI からのアップロード機能なし)
+- **ByteDance** — `budget` は 20 以上、状態は `PAUSED` ではなく `DISABLE`
+- **dry-run 応答の見方** — `{ dry_run: true, would_create: ..., warnings: [] }` が成功。`400` は `error` フィールドを見る。生 JSON が欲しいときは `--verbose`
+
+### ログイン未完時の対応 (最重要)
+
+**AI エージェントは `webgram auth login` を代行実行しない**。Google SSO / device flow のユーザーブラウザ操作は本人が行う (認証 URL とコードは CLI が出力するのでそれをユーザーに提示するだけ)。
+
+`webgram auth whoami` が `not_logged_in` を返したら、エージェントは以下のテキストをユーザーに提示して**停止**する:
+
+> ログインが必要です。ご自身のターミナルで以下を実行してください:
+> ```bash
+> webgram auth login
+> ```
+> ブラウザで Google (@webgram.jp) アカウントを選択してください。完了後「ログインしました」とお伝えください。
+>
+> (非対話環境で自動で device flow になった場合は、CLI が出力する URL と user_code をブラウザで開いて許可)
+
+ユーザーから完了報告を受けたら `webgram auth whoami` で確認してから本題を続行する。
+
+## 接続先の切替 (ローカル開発時のみ)
+
+通常は指定不要 (デフォルトで本番エンドポイントに接続)。ローカル開発時のみ環境変数で切り替える:
 
 ```bash
-webgram list --platform <p> --resource <accounts|campaigns|resources> [--account-id <id>]
-webgram submit --platform <p> --json-file <path>                        # dry-run 既定
-webgram submit --platform <p> --json-file <path> --no-dry-run --yes    # 実入稿
+export WEBGRAM_ENDPOINT=http://localhost:3001
+webgram auth login
 ```
 
-`<p>` = 対応媒体 (`yda` / `meta` / `google` / `smartnews` / `bytedance`)。
+ログイン時の endpoint は credentials.json に保存され、以降の `whoami` / `logout` / `list` / `submit` は同じ endpoint に向く。
+
+## コマンドリファレンス
+
+### `webgram auth login [--device] [--password] [--email <mail>] [--endpoint <url>]`
+
+- 既定は Google SSO (loopback OAuth)。非対話環境では自動で device flow に切り替わる
+- `--device` — TTY でも device flow を強制
+- `--password` — deprecated な ROPC フォールバック。パスワードは prompt or stdin パイプで渡す (argv 直渡しは shell history に残るので避ける)
+
+### `webgram auth whoami`
+
+現在の `access_token` に紐づくユーザー情報を `/api/auth/me` から取得。未ログインで exit 1。
+
+### `webgram auth logout`
+
+サーバー側で `refresh_token` を revoke してから credentials.json を削除。idempotent。
 
-入稿ボディ JSON の雛形と必須フィールドは [`fixtures/README.md`](./fixtures/README.md)。
+### `webgram list --platform <p> --resource <r> [--account-id <id> --campaign-id <id>]`
 
-## Skill として使う
+- `--platform`: `yda` / `meta` / `google` / `smartnews` / `bytedance`
+- `--resource`: `accounts` / `campaigns` / `resources` (媒体により対応差あり)
+
+### `webgram submit --platform <p> --json-file <path> [--no-dry-run --yes] [--verbose]`
+
+- 既定は dry-run。実入稿は `--no-dry-run --yes` の 2 フラグ必須
+- 動画広告付きの YDA/Meta は本実行時のみ multipart upload (timeout 180s)
+- `--verbose` でサーバー応答の raw JSON を表示
+
+### `webgram freee login/templates/issue`
+
+freee 請求書発行用サブコマンド。詳細は `skills/invoice-issue-freee/SKILL.md` 参照。allowlist で利用者制限あり。
+
+### `webgram --help` / `webgram <subcommand> --help`
+
+## 認証フローと保存先
+
+```
+webgram auth login
+  ↓ (Google SSO: loopback OAuth or device flow)
+  ↓ サーバー経由で認可コード → access_token 交換 (client_secret はサーバー側で保持)
+  ↓ 200 { access_token, refresh_token, expires_in: 3600 }
+  ↓
+~/.config/webgram/credentials.json (chmod 0600)
+{
+  "endpoint":     "<本番エンドポイント>",
+  "accessToken":  "eyJ...",     # JWT (1h)
+  "refreshToken": "Xy9...",     # 256bit base64url (90d)
+  "expiresAt":    "2026-06-29T05:00:00.000Z"
+}
+
+API 呼び出し
+  ↓ Authorization: Bearer <access_token>
+  ├─ 200 → 結果
+  └─ 401 → 自動 refresh + retry 1 回 → まだ失敗すればエラー
+```
 
-Claude Code / Codex CLI 用の `ad-ops` skill (広告運用スキル) を同梱。配置手順は [`skills/ad-ops/README.md`](./skills/ad-ops/README.md)。
+| 項目 | 仕様 |
+|---|---|
+| パスワード保存 | しない (Google SSO ではそもそも扱わない) |
+| credentials.json | `chmod 0600` (本人のみ読み書き) |
+| `access_token` | 1 時間 (JWT exp claim) |
+| `refresh_token` | 90 日 |
+| Rate limit | 同一 IP から 15min / 5 回失敗で 429 (`--password` フォールバック時のみ) |
+| 不正再利用検知 | 同じ `refresh_token` を 2 回使うと全 CLI トークン失効 |
+| 通信 | HTTPS (本番) / HTTP (ローカル) |
+
+## トラブルシューティング
+
+### `webgram: command not found`
+
+グローバルインストールしていない場合は `npx -y addashboard-cli@latest <cmd>` で実行するか、以下でグローバル導入:
+
+```bash
+npm install -g addashboard-cli
+which webgram
+```
+
+### `✗ Login failed: invalid_grant`
+
+Google SSO 時は認可コードが期限切れ / 無効。再度 `webgram auth login` を実行。`--password` フォールバック時はメール/パスワードが違うので Web UI で確認。
+
+### `✗ Login failed: network_error`
+
+エンドポイントに繋がっていない。ネットワークを確認、ローカル開発時は backend の起動を確認。
+
+### `✗ not_logged_in`
+
+`webgram auth login` を先に実行。または `ls -la ~/.config/webgram/credentials.json` で残っているか確認。
+
+### Rate limit (HTTP 429)
+
+`--password` フォールバックで 15 分間に 5 回連続でログイン失敗するとブロック。**15 分待ってから** 再試行、または Google SSO に切り替え (rate limit 対象外)。
+
+### アカウント一覧が少ない
+
+`webgram list --platform <媒体> --resource accounts` は `ApiConnection.selectedAccounts` に登録済みのアカウントのみ返す。全件必要なら Web UI (データシンク → 対象媒体) から `selectedAccounts` を追加する。
+
+### dry-run で意味不明なエラー ([object Object] など)
+
+CLI 側 (`src/commands/submission.ts`) で `data.error ?? err.message` に整形済みなので、通常は raw の `[object Object]` は出ない。それでも出るときは `--verbose` を付けて再実行し、サーバー応答の raw JSON を確認。
 
 ## 開発
 
+### ローカルインストール (ソース clone 派)
+
 ```bash
+git clone git@github.com:WEBGRAM-WG/ad-dashboard.git
+cd ad-dashboard/cli
 npm install
 npm run build
-npm test
+npm link                # webgram コマンドがグローバルに登録される
 ```
+
+### テスト実行
+
+```bash
+npm test                # vitest + nock、一時 dir で credentialStore/apiClient/コマンドをユニットテスト
+npm run test:watch
+```
+
+### ローカル backend に対する動作確認
+
+```bash
+# 別ターミナルで backend 起動
+cd ../backend && npm run dev   # :3001
+
+# CLI で叩く
+export WEBGRAM_ENDPOINT=http://localhost:3001
+webgram auth login
+webgram auth whoami
+webgram auth logout
+```
+
+### ディレクトリ構成
+
+```
+cli/
+├── src/
+│   ├── index.ts                # commander エントリ + prompt/promptHidden
+│   ├── commands/
+│   │   ├── auth.ts             # runLogin / runWhoami / runLogout
+│   │   ├── authGoogle.ts       # Google SSO (loopback OAuth)
+│   │   ├── authDevice.ts       # Google device flow
+│   │   ├── ads.ts              # list (accounts/campaigns/resources)
+│   │   ├── submission.ts       # submit (dry-run/実入稿、動画 upload)
+│   │   └── freee.ts            # freee 請求書発行
+│   └── lib/
+│       ├── credentialStore.ts  # ~/.config/webgram/credentials.json (chmod 0600)
+│       └── apiClient.ts        # axios factory (Bearer 付与 + 401 auto-refresh)
+├── fixtures/                   # 入稿ボディ JSON 雛形 (媒体別)
+├── skills/                     # skills/{ad-ops, invoice-issue-freee}
+├── test/unit/                  # vitest + nock
+├── package.json                # "bin": { "webgram": "./dist/index.js" }
+└── tsconfig.json
+```
+
+## 参照
+
+- [`fixtures/README.md`](./fixtures/README.md) — 全 5 媒体の入稿 JSON 雛形と必須フィールド一覧
+- [`skills/ad-ops/SKILL.md`](./skills/ad-ops/SKILL.md) — Claude Code / Codex CLI から自然言語で実行するときのマッピング (広告運用スキル)
+- [`skills/ad-ops/README.md`](./skills/ad-ops/README.md) — Skill 配置手順と発火方法 (Claude Code + Codex CLI 両対応)
+- [`skills/invoice-issue-freee/SKILL.md`](./skills/invoice-issue-freee/SKILL.md) — freee 請求書発行 E2E マニュアル (allowlist 制)
+- [../CLAUDE.md](../CLAUDE.md) — ad-dashboard 全体の知識ベース (媒体別認証・DB スキーマ・デプロイ手順)
+
+## ロードマップ
+
+- [x] `auth login` / `whoami` / `logout` + 401 自動 refresh
+- [x] Google SSO (loopback OAuth / 非対話環境は device flow)
+- [x] `list` (accounts/campaigns/resources) 全 5 媒体
+- [x] `submit` (dry-run + 実入稿) 全 5 媒体
+- [x] `freee login/templates/issue` (allowlist 制)
+- [x] npm public registry 配布 (`addashboard-cli`)
+- [ ] `webgram raw <METHOD> <PATH>` (任意の REST を叩く脱出ハッチ)
+- [ ] `webgram accounts --all` (selectedAccounts に載っていないアカウントもページングで全件取得)
+
+---
+
+## ライセンス
+
+社内限定。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "addashboard-cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "webgram CLI — ad-dashboard (https://macchiato.site) を Claude Code / Codex CLI から操作するための CLI",
   "bin": {
     "webgram": "./dist/index.js"
@@ -9,7 +9,8 @@
     "dist",
     "README.md",
     "skills/ad-ops/**",
-    "skills/invoice-issue-freee/**"
+    "skills/invoice-issue-freee/**",
+    "!skills/ad-ops/入稿計画/**"
   ],
   "keywords": [
     "webgram",
@@ -38,13 +39,17 @@
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "test:e2e": "playwright test",
+    "prepublishOnly": "npm run build",
+    "prepack": "node scripts/materialize-skills.js",
+    "postpack": "node scripts/materialize-skills.js --restore"
   },
   "dependencies": {
     "axios": "^1.7.7",
     "commander": "^12.1.0"
   },
   "devDependencies": {
+    "@playwright/test": "1.61.1",
     "@types/node": "^22.9.0",
     "nock": "14.0.16",
     "tsx": "^4.19.2",

package/skills/ad-ops/SKILL.md

@@ -7,7 +7,7 @@ description: ad-dashboard (https://macchiato.site) の webgram CLI 経由で広
 
 Google Drive から手動 DL 済みの動画を各媒体に半自動入稿するためのスキル。**現状 YDA のみ対応**、Meta / TikTok は将来対応予定。
 
-配置・発火方法は同ディレクトリの [README.md](./README.md) 参照。
+配置・発火方法・ログイン手順は [cli/README.md](../../README.md) の「初期設定: Skill として配置する」章を参照。
 
 ## 動画入稿フロー (メイン用途)
 
@@ -144,3 +144,69 @@ open "https://ads-display.yahoo.co.jp/campaign/detail?accountId=<accountId>&camp
 | 汎用入稿 (JSON) 実入稿     | `npx -y addashboard-cli@latest submit --platform <媒体> --json-file <path> --no-dry-run --yes`                  |
 
 汎用入稿 (JSON ボディ直渡し) は yda / meta / google / smartnews / bytedance の 5 媒体対応。fixtures の雛形は tarball 同梱の `fixtures/*_poc.json`、各媒体の必須フィールドは `fixtures/README.md`。
+
+***
+
+## YDA入稿プランナー（HTML DOCS / JSON入稿・レスポンシブ画像固定型）
+
+動画の API 入稿とは別に、**レスポンシブ(画像)・固定型の一括入稿** を計画・確認するためのシングルHTMLツール。2026-07-16 / 07-21 定例フィードバックを反映。**2026-07-23 に CSV 書き出しを廃止し、保存・入稿受け渡しを JSON に統一**。
+
+- **ファイル**: 本スキル同梱の [`yda-planner.html`](./yda-planner.html)（ローカルで開くだけ・依存なし。実データ同梱: タイトル999 / 画像633 / グループ96）
+- **役割**: 動画=`addashboard-cli submit`（API入稿）、**画像=このプランナーで計画 → 「入稿JSON書き出し」→ 同じ `submit --platform yda` に流す**（Yahoo管理画面CSVインポートは廃止）。
+- **基本思想（定例）**: AIで生成できる部分は **AIに生成させ（JSON読込）**、絶対に人が確定する部分（クリエイティブ選定・確認）を **スプシ的コピペ・一括入力・複製** で楽にする。プランナーで確認・修正して **OK なら 入稿JSON書き出し（=GO）→ `submit` dry-run → 本実行**。
+- **ビュー**: `媒体要件`（YDA/Meta タブの仕様・使い方ページ）/ `プラン`（戦略メモ → 案件設定 → シート/ツリー切替。シートは1広告=1行の表＋広告/広告グループ/キャンペーンのネストタブ、ツリーは開閉・複製・量産）/ `参照データ`（タイトル&説明一覧・登録画像一覧の閲覧+新規登録）/ `履歴`（保存バージョン一覧）。同一 state を投影し切替。
+
+### 保存とバージョン履歴（2026-07-23〜）
+
+- **バージョン保存**: 保存のたびに **常に新バージョン**（v1, v2…）。JSON は `schemaVersion:2` で `meta`（バージョンID・作成/更新日時・作成者・対象媒体・名称・メモ）を持つ。旧 v1 JSON も読込時に自動マイグレーション。**履歴本体はブラウザ内（localStorage）に自動保存**されるため、フォルダ設定なしで一覧・再読込・削除が完結する。
+- **保存フォルダ連携（入稿計画/）**: 履歴ビューの「📁 保存フォルダに接続」で本スキル同梱の `入稿計画/` フォルダを**初回に1回だけ**選ぶと、以後は開くだけで自動接続され、保存のたびにファイルにも書き出される（File System Access API / Chrome系のみ。非対応環境・未接続時はダウンロード動作）。
+- **履歴ビュー**: バージョン・日時・媒体・名称・メモ・作成者の一覧。`読込`（過去バージョン復元）/ `編集`（名称・メモ）/ `削除`。
+- **入稿JSON書き出し**: 設定ダイアログなしの**ワンクリック**。アカウントID・目的(goal)・開始日は案件設定チップ、入札はキャンペーン行（tCPA→`MAXIMIZE_CONVERSIONS`+targetCpa）、ターゲティングは広告グループ行の列（日本語ラベル→API enum 自動変換）から `*_submit-body_*.json` を生成。手入稿バナー・参照未解決の広告は自動除外。accountId 未入力・0件なら書き出し中止（空入稿防止）。
+
+### 量産構造（媒体要件の核）
+
+- 階層 **キャンペーン > 広告グループ > 広告**。`1:1:4`（基本）/ 初期 `1:1:10`（撒いて選ぶ）。
+- **変数=キャンペーン**（検証したい1点だけ変えてキャンペーンを分ける）、**クリエイティブ束=広告グループ内の広告**。
+- 北さんのやり方 = **テンプレ複製 → 中身クリア → 変数だけ差し替え** の量産。プランナーのツリー複製ダイアログ / 「N本まとめて」/ キャンペーン量産で再現。
+- **広告グループ = 1つの `【paramCode】`**。これでキャンペーンID/広告グループID/メディアID/タイトル/説明文/最終URL を解決（VLOOKUP代替）。派生値は純関数で毎回算出。
+
+### 入稿モードと手入稿
+
+- モード: **新規**（12,000円/日・1CP=1AG=1広告を量産）/ **既存ASC**（5万〜10万円/日・まとめ入稿）/ 既存-広告グループ追加 / 既存-広告追加。
+- **バナー(画像のみ)は API 未対応 → 手入稿**。プランナーでは `手入稿` フラグで区別し、入稿JSONから自動除外。
+
+### 発火時の案内
+
+「YDA入稿プランナー」「入稿シート」「タイトル/画像一覧」「まとめ入稿の確認用シート」等を求められたら、このHTMLを案内・オープンする（`open <path>`）。入稿JSONは書き出し後 `webgram submit --platform yda --json-file <submit-body>` で **dry-run → 本実行** にかける。
+
+## ログイン情報の取り扱い
+
+- **通常は device flow を使う**: パスワードは扱わない。CLI が出力する `verification_url` と `user_code` をユーザーに伝え、ブラウザ許可を待つだけ。Google 資格情報は Google 側でのみ入力される
+- device_code / user_code は Google のワンタイム値。不要に貼らない
+- 認証成功後は `~/.config/webgram/credentials.json` (`chmod 0600`) に保存される (再認証不要)
+- **`--password` (ROPC) は deprecated なフォールバック**: どうしても device flow もブラウザも使えない場合のみ。使う場合は AskUserQuestion で1回だけ聞き、`printf '%s\n' '<pw>' | npx -y addashboard-cli@latest auth login --password --email <email>` の形で **stdin パイプ** 経由で渡す (argv は `ps` / シェル履歴に露出するため)。パスワードは応答メッセージに絶対書かない
+
+## トラブルシュート
+
+| 症状 | 対処 |
+|---|---|
+| `command not found: npx` | Node.js が入っていない。`https://nodejs.org` から LTS 版インストールを案内 |
+| `Login failed: invalid_grant` | Web UI (`https://macchiato.site`) でログインできるか確認を案内 |
+| `Login failed: network_error` | `curl -v https://macchiato.site/api/health` で疎通確認 |
+| `not_logged_in` (whoami 時) | `auth login` から再度実行 |
+| Rate limit (429) | 15分間ログイン失敗5回でブロック。15分待ってから再試行 |
+| 入稿失敗 (媒体API側) | エラーメッセージを要約してユーザーに提示、残りの入稿を続けるか AskUserQuestion で確認 |
+
+## 制約 / 今後の拡張
+
+- **将来的な体験改善**: Google Drive 拡張機能から複数動画を選択 → プロンプト自動生成 → 貼り付け実行までワンストップ化
+- CLI バージョンは `npmPackage: "addashboard-cli@latest"` で常に最新。特定バージョンに固定したい場合は `config.json` を `addashboard-cli@0.2.3` の形に変更
+
+### 入稿プランナー関連ロードマップ（2026-07-16 定例 / 2026-07-23 更新）
+
+- ~~CSVを介さない直接入稿~~ → **完了（2026-07-23）**: プランナーの「入稿JSON書き出し」が submit-body.json を生成し、そのまま `submit --platform yda` に流せる。CSV書き出しは廃止。
+- **キャンペーン/広告グループID の自動取得**: 管理画面からの手コピペ（`【paramCode】`↔ID の突合）を、API/MCP で自動取得して置き換える。新規CPは払出し後にID解決。
+- **新規画像のメディア登録自動化**: ドライブ格納画像を YDA メディアに登録し、プランナーの参照データ（画像番号→mediaID）へ反映。
+- **命名規則の統一**: `【】内の数字`のみ共通で、キャンペーン名/広告名は担当者差がある → システム命名に寄せられるようにする。
+- **Meta広告対応**: backend/CLI は実装済み・GUI未対応。検証範囲と要件一覧のドラフトはプランナー媒体要件ビューの「Meta広告」タブを参照。
+- **未確定（要実機確認）**: CTA既定（画像=もっとみる / 動画=詳細を見る）と `buttonText` enum、画像レスポンシブAPI入稿（PR #82）の実疎通、新規時に CP/AG ID 未払出でどう入稿するか、画像サムネURLの入手経路。