compass-st 1.1.2

package/core/integrations/figma.md

@@ -0,0 +1,277 @@
+# Integration: Figma
+
+**Purpose**: Set up (or verify) Figma integration for Compass. Figma gives Compass read-access to design files so PRDs and stories can reference real design context, component names, and screenshots.
+
+**Caller**: `/compass:setup figma`, `/compass:setup verify-figma`, or the integrations wizard inside `/compass:init` (Phase C).
+
+**Output**:
+- Updates `~/.config/compass/integrations.json` — `integrations.figma`
+- May add a server entry to `~/.claude/mcp.json` or `~/.config/opencode/opencode.jsonc`
+- Never stores the Figma token in Compass files. Token lives only in the host MCP config as an env var.
+
+---
+
+## Step 0 — Language
+
+Read `.compass/.state/config.json` if it exists and load `lang` (default `en`).
+
+**Language enforcement**: all user-facing chat text below uses `lang`. JSON keys stay in English.
+
+## Step 1 — Detect host
+
+Same procedure as Jira workflow Step 1 — detect RUNNING host (check `claude` CLI for Claude Code, check opencode directory for OpenCode). Do NOT assume Claude Code just because `~/.claude/` exists — that directory may exist from Compass adapter install only.
+
+## Step 2 — Parse mode
+
+| Mode | Trigger |
+|---|---|
+| `setup` | `/compass:setup figma` or init wizard |
+| `verify` | `/compass:setup verify-figma` |
+| `reset` | `/compass:setup reset figma` |
+
+## Step 3 — Probe for the Figma MCP tool
+
+The official Figma MCP from claude.ai exposes `mcp__claude_ai_Figma__whoami`. Community alternatives (e.g. `figma-developer-mcp`) expose `mcp__figma__get_me` or similar. Try each known tool name in order:
+
+1. `mcp__claude_ai_Figma__whoami`
+2. `mcp__figma__whoami` / `mcp__figma__get_me`
+
+- If NONE of these tools exist in the tool list → Figma MCP is not loaded. Jump to **Step 5 (install from scratch)**.
+- If a tool exists → call it with no arguments. On success, the integration is live. Jump to **Step 4**.
+- On failure (401, network, bad token) → show error, ask the PO: "Re-configure now? (Yes / Skip)".
+
+## Step 4 — Already configured path
+
+1. Display (in `lang`):
+   ```
+   ✓ Figma is already configured
+     User: <display_name>
+     Email: <email>
+     Host: <HOST>
+   ```
+
+2. Ask the PO (optional, skip-able):
+   ```
+   Default Figma team URL for this repo? (optional, press Enter to skip)
+   ```
+
+3. Update `integrations.figma`:
+   ```json
+   {
+     "status": "configured",
+     "configured_at": "<existing or now>",
+     "verified_at": "<now ISO>",
+     "host": "<HOST>",
+     "user": "<email>",
+     "team": "<team URL or null>",
+     "mcp_package": "<existing or unknown>",
+     "notes": ""
+   }
+   ```
+
+4. Atomically write.
+
+5. Stop.
+
+## Step 5 — Install from scratch (5 sub-steps)
+
+### 5.1 — Explain why (1/5)
+
+```
+Compass wants Figma for:
+  • Reading design file context when writing PRDs (component names, screenshots)
+  • Linking stories to specific frames and nodes
+  • Pulling design tokens and rules into spec files
+
+Read-only. Compass will not modify your Figma files.
+Setup takes about 2 minutes.
+
+Continue? (Yes / Skip)
+```
+
+If Skip → save status `skipped`, return to caller.
+
+### 5.2 — Create Personal Access Token (2/5)
+
+Try to auto-open the settings page:
+
+```bash
+open "https://www.figma.com/settings" 2>/dev/null || xdg-open "https://www.figma.com/settings" 2>/dev/null || start "https://www.figma.com/settings" 2>/dev/null || true
+```
+
+Then show the instructions in a formatted block (same style as the integration summary table — indented, clean, with visual markers):
+
+- en:
+```
+  Figma Personal Access Token
+
+  ① Open figma.com → click your Avatar (top-right)
+  ② Settings → Security
+  ③ "Personal access tokens" → Generate new token
+  ④ Name:        compass-figma
+  ⑤ Expiration:  No expiration (recommended)
+  ⑥ Scopes:      Enable ALL scopes (full access)
+  ⑦ Click "Generate token"
+  ⑧ Copy the token NOW — Figma only shows it once!
+
+  Can't find it? Go to: https://www.figma.com/settings
+  Then scroll to Security → Personal access tokens
+```
+
+- vi:
+```
+  Tạo Figma Personal Access Token
+
+  ① Mở figma.com → click Avatar (góc phải trên)
+  ② Settings → Security
+  ③ "Personal access tokens" → Generate new token
+  ④ Tên:          compass-figma
+  ⑤ Hết hạn:      No expiration (khuyến nghị)
+  ⑥ Scopes:       Bật TẤT CẢ scopes (full access)
+  ⑦ Click "Generate token"
+  ⑧ Copy token NGAY — Figma chỉ hiện 1 lần!
+
+  Không tìm thấy? Vào: https://www.figma.com/settings
+  Rồi cuộn tới Security → Personal access tokens
+```
+
+Wait for PO to confirm they have the token before continuing.
+
+Wait for the PO to confirm they have the token.
+
+### 5.3 — Collect metadata (3/5)
+
+Ask:
+
+1. `Figma account email? (e.g. you@company.com)`
+2. `Personal Access Token? (will NOT be stored in Compass, only in the host MCP config)`
+3. `Default team URL? (optional, e.g. https://www.figma.com/files/team/123456/Acme)`
+
+Validate:
+- Email contains `@`.
+- Token is non-empty and looks like a Figma token (starts with `figd_` or is a long alphanumeric string; don't hard-fail on format, just warn if it's < 20 chars). Token must have been created with full scopes enabled.
+
+### 5.4 — Install the MCP server (4/5)
+
+Two common options:
+
+1. **Official claude.ai Figma MCP** — may already ship with Claude Code. If the tool list contained `mcp__claude_ai_Figma__*` earlier but auth failed, the server is present; only the token is missing. In that case, the PO needs to add the token to the existing entry instead of a new package install.
+2. **Community `figma-developer-mcp`** — npm package, works on any host.
+
+Ask:
+
+```
+Step 4/5 — Install the MCP server
+
+Recommended: figma-developer-mcp (community, works on all hosts)
+Alternative: skip install — I already have the claude.ai Figma MCP
+
+Install figma-developer-mcp via npm? (Yes / Skip install)
+```
+
+If Yes:
+
+```bash
+npm install -g figma-developer-mcp 2>&1
+```
+
+Handle errors the same way as the Jira workflow (npm missing, EACCES, network, 404).
+
+If Skip install, ask for the package name the PO wants Compass to reference (e.g. `claude_ai_Figma`) and use that string as `mcp_package`.
+
+### 5.5 — Edit the host MCP config (5/5)
+
+Locate file (Claude Code: `~/.claude/mcp.json`, OpenCode: `~/.config/opencode/opencode.jsonc`).
+
+1. Back up before editing.
+2. Parse.
+3. Merge entry keyed `figma`:
+
+   ```json
+   "figma": {
+     "command": "npx",
+     "args": ["-y", "figma-developer-mcp"],
+     "env": {
+       "FIGMA_API_KEY": "<token>"
+     }
+   }
+   ```
+
+   If a key `figma` already exists, ask: "Overwrite? / Rename to figma-compass / Cancel".
+
+4. Write back.
+5. `chmod 600 <config file>`.
+6. Show the PO a redacted preview:
+
+   ```json
+   "figma": {
+     "command": "npx",
+     "args": ["-y", "figma-developer-mcp"],
+     "env": { "FIGMA_API_KEY": "<REDACTED>" }
+   }
+   ```
+
+If edit fails, save status `error`, tell the PO to edit manually, give them the raw block.
+
+## Step 6 — Save status + handle restart
+
+Write `integrations.figma`:
+
+```json
+{
+  "status": "configured",
+  "configured_at": "<now ISO>",
+  "verified_at": null,
+  "host": "<HOST>",
+  "user": "<email>",
+  "team": "<team URL or null>",
+  "mcp_package": "figma-developer-mcp",
+  "notes": ""
+}
+```
+
+**Try to verify immediately** — call the Figma MCP tool. If it works → set `verified_at`, show `"✓ Figma connected and verified!"`. Continue flow.
+
+If verify fails (needs restart):
+
+```
+✓ Figma MCP configured.
+
+Note: MCP server will be available after you restart <HOST_NAME>.
+Run /compass:setup verify-figma after restart to confirm.
+```
+
+Use ACTUAL host name ("Claude Code" or "OpenCode"). Do NOT break the init flow — PO finishes init first, restarts later.
+
+## Step 7 — Verify mode
+
+1. Re-probe the Figma tool (Step 3).
+2. On success: update `status` = `configured`, `verified_at` = now ISO, `user` = profile user. Show confirmation.
+3. On failure: show error + troubleshooting:
+
+   | Symptom | Fix |
+   |---|---|
+   | Tool not in tool list | Restart your AI host (close and reopen). |
+   | 403 / invalid token | Token expired or revoked. Re-run `/compass:setup figma`. |
+   | Timeout | Network issue — retry. |
+
+   Mark status `error`.
+
+## Step 8 — Status file shape
+
+Same file as Jira: `~/.config/compass/integrations.json`. Only touch the `figma` sub-object. Preserve everything else. Atomic write (tmp + mv). Update `updated_at`.
+
+Valid `status` values: `configured`, `configured-pending-verify`, `skipped`, `not-configured`, `error`.
+
+## Save session
+
+Same as Jira — only if invoked via `/compass:setup`, write to `.compass/.state/sessions/<timestamp>-setup-figma/transcript.md`. Never log the token.
+
+## Edge cases
+
+- **Figma free account**: API tokens work on free accounts with read-only scopes — no paid plan required.
+- **Token works but file access fails later**: Figma tokens are user-scoped. The PO must have access to the files they want Compass to read. Note this in the final confirmation.
+- **No "default project" concept**: Figma work is file-by-file; Compass does not store a single default. The `team` field is optional and only used to suggest starting points.
+- **Claude Code bundled Figma MCP already present**: the tool `mcp__claude_ai_Figma__whoami` will work without any install. Compass should detect it and skip the install step entirely.
+- **Both MCPs installed at the same time**: that's fine — Compass uses whichever tool responds first. Record the one that succeeded as `mcp_package`.
+- **chmod fails**: warn the PO that the file contains a token but permissions could not be locked.