canicode 0.11.4 → 0.12.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "canicode",
+  "owner": {
+    "name": "let-sunny"
+  },
+  "plugins": [
+    {
+      "name": "canicode",
+      "source": ".",
+      "description": "Lint Figma designs for AI code-gen and roundtrip the answers back into the file. CLI + MCP server."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "canicode",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "description": "Lint Figma designs for AI code-gen and roundtrip the answers back into the file. CLI + MCP server.",
   "skills": [
     "./skills/canicode",

package/README.md

@@ -24,7 +24,7 @@
 
 ## How it works
 
-AI can turn Figma designs into code — but the quality depends heavily on **how the design is structured**. CanICode runs a **roundtrip** over your Figma file: analyze the design, surface the gotchas it can't answer on its own, apply fixes back to Figma, re-analyze until the design is clean, then hand off to Figma's `figma-implement-design` skill for code generation. canicode does the design augmentation; code generation lives downstream (see [ADR-013](.claude/docs/ADR.md) for the scope boundary).
+AI can turn Figma designs into code — but the quality depends heavily on **how the design is structured**. CanICode runs a **roundtrip** over your Figma file: analyze the design, surface the gotchas it can't answer on its own, apply fixes back to Figma, re-analyze until the design is clean, then hand off to Figma's `figma-implement-design` skill for code generation. canicode does the design augmentation; code generation lives downstream.
 
 ![Role diagram: gotchas (memo) vs roundtrip (canvas) vs code-gen](docs/images/roles.svg)
 
@@ -46,10 +46,11 @@ Rule scores aren't guesswork. The calibration pipeline converts real Figma desig
 2. **Surface gotchas** — the analyzer emits questions for design information it can't infer (missing states, unclear variants, responsive intent).
 3. **Apply fixes to Figma** — the `/canicode-roundtrip` skill writes answers back via `use_figma`. Each write shows up in the summary with one of three outcome markers:
    - ✅ **scene write succeeded** — the property was written directly to the scene node or instance override.
-   - 📝 **annotated the scene node** — the skill left a structured annotation instead of writing the property. This is the [ADR-012](.claude/docs/ADR.md) default for instance-child layout writes, because propagating a property to the component definition (and therefore every instance of it) is almost never what the user wants. **A summary full of 📝 markers is correct behavior, not failure.**
+   - 📝 **annotated the scene node** — the skill left a structured annotation instead of writing the property. This is the default for instance-child layout writes, because propagating a property to the component definition (and therefore every instance of it) is almost never what the user wants. **A summary full of 📝 markers is correct behavior, not failure.**
    - 🌐 **definition write propagated** — the property was written to the component definition and every instance inherited it. Only happens when the user opted in up front with `allowDefinitionWrite`.
 4. **Re-analyze** — verify gotchas were captured (annotations / acks); repeat step 2 if new gotchas surface.
-5. **Hand off** to `figma-implement-design` — canicode's scope ends here ([ADR-013](.claude/docs/ADR.md)). Figma's official code-generation skill takes the now-clean design and produces code.
+5. **Hand off** to `figma-implement-design` — canicode's scope ends at design augmentation. Figma's official code-generation skill takes the now-clean design and produces code.
+6. **Close out with a Code Connect mapping** — after `figma-implement-design` returns, the roundtrip asks whether the generated code is satisfactory. On `y`, canicode registers a [Code Connect](https://www.figma.com/code-connect-docs/) mapping pointing the Figma component at the just-generated code so future roundtrips on screens containing this component reuse the implementation instead of regenerating markup. **Skipped if Code Connect is not set up in your repo** — the roundtrip warns about this up front, before the gotcha survey, so you can decide whether to install prerequisites first or proceed without mapping.
 
 ---
 
@@ -63,8 +64,10 @@ Rule scores aren't guesswork. The calibration pipeline converts real Figma desig
 
 ```bash
 # 1. Save your Figma token AND install the /canicode-roundtrip skill
-#    (never paste the token into chat — env var or CLI prompt only)
-npx canicode init --token figd_xxxxxxxxxxxxx
+#    Interactive (TTY): npx canicode init        — prompts for the token
+#    Non-interactive:   npx canicode init --token figd_xxxxxxxxxxxxx
+#    (never paste the token into chat — use env var, the prompt, or --token only)
+npx canicode init
 
 # 2. Run the roundtrip on a Figma URL
 /canicode-roundtrip https://www.figma.com/design/ABC123/MyDesign?node-id=1-234
@@ -72,6 +75,8 @@ npx canicode init --token figd_xxxxxxxxxxxxx
 
 > **Prerequisite:** the roundtrip skill calls the Figma MCP server to read and write the design. Install it once with `claude mcp add -s project -t http figma https://mcp.figma.com/mcp` — see the **MCP Server** install section below.
 
+> **Optional — Code Connect (for the closing Step 6 mapping):** install `@figma/code-connect` (`pnpm add -D @figma/code-connect` or npm/yarn equivalent) and create `figma.config.json` at your repo root per [Figma's setup guide](https://www.figma.com/code-connect-docs/). Then run `canicode doctor` to confirm both prerequisites are in place. If you skip this, the roundtrip still generates code but will not register a Code Connect mapping — it tells you up front so you can decide.
+
 **CanICode in Cursor (no Claude Code required):**
 
 1. Add **canicode** and **Figma** MCPs — [Cursor MCP](docs/CUSTOMIZATION.md#cursor-mcp-canicode) for `npx` → `canicode-mcp` (use **`.cursor/mcp.json`** or **`~/.cursor/mcp.json`** in Cursor, not repo-root `.mcp.json`; [why](docs/CUSTOMIZATION.md#which-mcp-file-affects-which-host)); Figma MCP is required for **`use_figma`** if you run **roundtrip** (design writes), not for analyze-only.
@@ -88,7 +93,17 @@ npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234
 claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
-Restart Claude Code or reload MCP (Cursor) so canicode tools (`analyze`, `gotcha-survey`, …) load — same cold-session requirement as the Figma MCP (#433).
+Restart Claude Code or reload MCP (Cursor) so canicode tools (`analyze`, `gotcha-survey`, …) load — same cold-session requirement as the Figma MCP.
+
+**Smoke test (no Figma token needed):**
+
+```bash
+git clone https://github.com/let-sunny/canicode.git
+cd canicode && pnpm install && pnpm build
+canicode analyze ./fixtures/done/desktop-home-page
+```
+
+Loads a bundled fixture (no Figma API call, no token), opens the HTML report in a browser (pass `--no-open` to skip auto-launch). Use any directory under `fixtures/done/` — `desktop-*` are screen-scale, `mobile-*` are mobile viewports.
 
 <details>
 <summary><strong>All channels</strong></summary>
@@ -124,15 +139,18 @@ Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggest
 
 ## Installation — pick one
 
-Each row below is a **complete** install. Don't run more than one — they cover overlapping use cases. (#367)
+Each row below is a **complete** install. Don't run more than one — they cover overlapping use cases.
 
 | If you use… | Install |
 |-------------|---------|
-| **Claude Code** (recommended for the roundtrip workflow) | `npx canicode init --token figd_xxxxxxxxxxxxx` — saves the token AND drops `/canicode`, `/canicode-gotchas`, `/canicode-roundtrip` skills into `./.claude/skills/`. The skills already know how to call canicode via `npx canicode …`, no MCP install needed. |
+| **Claude Code** (recommended for the roundtrip workflow) | `npx canicode init` (interactive prompt for the token in a TTY) or `npx canicode init --token figd_xxxxxxxxxxxxx` (CI / non-TTY) — saves the token AND drops `/canicode`, `/canicode-gotchas`, `/canicode-roundtrip` skills into `./.claude/skills/`. The skills already know how to call canicode via `npx canicode …`, so no **canicode** MCP install is needed; the **Figma** MCP is still required for the `/canicode-roundtrip` apply step — see the prereq below. To rotate the token later without reinstalling skills: `npx canicode config set-token`. |
 | **Cursor / Claude Desktop / other MCP host** | Add canicode to the host’s MCP config — see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md#cursor-mcp-canicode). Example (Cursor project file): `npx` + `canicode-mcp` via `--package=canicode`. |
-| **Just the CLI** (CI, scripts) | Nothing. `npx canicode analyze "<figma-url>"` works directly. Run `canicode init --token …` once if you want the token persisted to `~/.canicode/config.json`. |
+| **OpenClaw / other AgentSkills-compatible host** | Manual skill copy — see [Other agents (manual install)](docs/CUSTOMIZATION.md#other-agents-manual-install). Best-effort docs, not a support commitment. |
+| **Just the CLI** (CI, scripts) | Nothing. `npx canicode analyze "<figma-url>"` works directly. Run `canicode init --token …` once if you want the token persisted to `~/.canicode/config.json`. To rotate the token later, use `canicode config set-token` (no skill reinstall). |
 
-> **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
+> **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token. [Figma's PAT docs](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens)
+> **Scope:** Read-only is sufficient for canicode.
+> **Expiry:** Tokens default to 90 days; check the dropdown when generating.
 
 > **Roundtrip prerequisite:** the `/canicode-roundtrip` skill calls the Figma MCP server to read and write the design. Install it once with `claude mcp add -s project -t http figma https://mcp.figma.com/mcp` and restart Claude Code so the new MCP tools load.
 
@@ -140,7 +158,11 @@ Each row below is a **complete** install. Don't run more than one — they cover
 <summary><strong>Claude Code Skills</strong> — install details</summary>
 
 ```bash
-# Token: env or CLI prompt only — do not paste into agent chat
+# Interactive (TTY) — prompts for the token, never paste it into agent chat
+npx canicode init
+
+# Non-interactive (CI / non-TTY) — token via env or --token only
+FIGMA_TOKEN=figd_xxxxxxxxxxxxx npx canicode init
 npx canicode init --token figd_xxxxxxxxxxxxx
 ```
 
@@ -150,12 +172,22 @@ Drops three skills into `./.claude/skills/`:
 - **canicode-gotchas** — standalone gotcha survey (use `/canicode-gotchas <figma-url>`)
 - **canicode-roundtrip** — full analyze → gotcha → apply roundtrip (use `/canicode-roundtrip <figma-url>`)
 
+> The install copies 7 files total — the three SKILL.md files above plus four canicode-roundtrip helper files (`helpers.js`, `helpers-bootstrap.js`, `helpers-installer.js`, `canicode-roundtrip-helpers.d.ts`) used by the roundtrip Step 4 apply path. The CLI summary's `files installed: 7` reflects this file count.
+
 > **Explicit invocation:** the SKILL.md `description` fields advertise TRIGGER conditions so the model auto-routes Figma-URL prompts to the right skill, but routing is non-deterministic. For deterministic invocation, type `/canicode <figma-url>`, `/canicode-gotchas <figma-url>`, or `/canicode-roundtrip <figma-url>` directly — the slash command bypasses model-based routing.
 
-The skills shell out to `npx canicode …` for analyze / gotcha-survey when the canicode MCP server is not installed — both paths produce the same JSON shape. The Figma MCP server is still required for the apply step (Step 4 in `/canicode-roundtrip`); see the prereq note above.
+The skills shell out to `npx canicode …` for analyze / gotcha-survey, so installing the **canicode** MCP server is optional (both paths produce the same JSON shape). The **Figma** MCP server, however, is required for the apply step (Step 4 in `/canicode-roundtrip`); see the prereq note above.
 
 Flags: `--global` installs into `~/.claude/skills/` instead. `--cursor-skills` also installs Cursor copies under `.cursor/skills/`. `--force` overwrites existing skill files without prompting. Run `canicode docs setup` for the full setup guide.
 
+To manage saved configuration without reinstalling skills:
+
+```bash
+canicode config set-token   # rotate Figma token (interactive on TTY; --token for CI)
+canicode config show        # masked token + config + reports paths
+canicode config path        # absolute path to ~/.canicode/config.json
+```
+
 </details>
 
 <details>
@@ -165,15 +197,15 @@ Flags: `--global` installs into `~/.claude/skills/` instead. `--cursor-skills` a
 claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 ```
 
-Restart Claude Code or reload MCP (Cursor) so canicode MCP tools appear in a fresh session (#433).
+Restart Claude Code or reload MCP (Cursor) so canicode MCP tools appear in a fresh session.
 
 Then ask: *"Analyze this Figma design: https://www.figma.com/design/..."*
 
-canicode's rule engine analyzes the design data — the AI assistant just orchestrates the calls. The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` (set via `canicode init --token …`) or from the host's environment, so passing `-e FIGMA_TOKEN=…` to `claude mcp add` is **not** required and the current parser rejects it anyway (#364).
+canicode's rule engine analyzes the design data — the AI assistant just orchestrates the calls. The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` (set via `canicode init --token …`) or from the host's environment, so passing `-e FIGMA_TOKEN=…` to `claude mcp add` is **not** required and the current parser rejects it anyway.
 
 If you genuinely need a per-server token without using `canicode init`, export it on the calling shell instead: `export FIGMA_TOKEN=figd_xxxxxxxxxxxxx`.
 
-For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md) — especially [Cursor MCP (canicode)](docs/CUSTOMIZATION.md#cursor-mcp-canicode) and the **Manual test checklist (#407)** for verifying `gotcha-survey` end-to-end.
+For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md) — especially [Cursor MCP (canicode)](docs/CUSTOMIZATION.md#cursor-mcp-canicode) and the **Manual test checklist** for verifying `gotcha-survey` end-to-end.
 
 </details>
 
@@ -184,7 +216,9 @@ For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZA
 npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 ```
 
-Setup: `npx canicode init --token figd_xxxxxxxxxxxxx` saves the token and installs the Claude Code skills into `./.claude/skills/`.
+> Pass `--ready-min-grade <S|A+|A|B+|B|C+|C|D|F>` to override the codegen-readiness threshold (default: A).
+
+Setup: `npx canicode init` (interactive prompt; TTY) or `npx canicode init --token figd_xxxxxxxxxxxxx` (CI / non-TTY) saves the token and installs the Claude Code skills into `./.claude/skills/`. Rotate later with `npx canicode config set-token`.
 
 **Figma API Rate Limits** — Rate limits depend on **where the file lives**, not just your plan.