@hegemonart/get-design-done 1.30.6 → 1.31.0

package/scripts/lib/health-mirror/index.cjs

@@ -8,12 +8,13 @@
 // Surface:
 //   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
 //
-// The 5 checks (in stable order) are:
+// The 6 checks (in stable order) are:
 //   1. claude_md            — CLAUDE.md presence
 //   2. planning_dir         — .planning/ presence
 //   3. design_dir           — .design/ presence
 //   4. package_json         — package.json present AND parseable
 //   5. issue_reporter       — kill-switch state (Plan 30-06 / D-08)
+//   6. figma_extract        — extract readiness + Free-tier signal (Plan 31-09)
 //
 // Check 5 was added in Plan 30-06 — surfaces the report-issue kill-switch
 // (env or config disable) so users can verify why the command is
@@ -22,6 +23,17 @@
 //   - "issue reporter: disabled by env (GDD_DISABLE_ISSUE_REPORTER=1)"
 //   - "issue reporter: disabled by config (.design/config.json: issue_reporter=false)"
 // When both env and config trigger, env wins (matches D-08 display contract).
+//
+// Check 6 was added in Plan 31-09 — surfaces figma-extract readiness so a user
+// running /gdd:health immediately knows whether figma-extract is usable. The
+// detail line is one of three exact strings:
+//   - "figma extract: ready (token set)"
+//   - "figma extract: token missing"
+//   - "figma extract: plugin sync needed for variables (Free tier detected)"
+// D-10: only FIGMA_TOKEN *presence* is used — the token VALUE is never read,
+// logged, or placed in the detail. The Free-tier state is derived from a LOCAL
+// signal only (a prior pull's _meta.json recording a 403/skip on the Variables
+// endpoint) — never a live network call (health-mirror is pure read-only).
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -135,7 +147,82 @@ async function getHealthChecks(rootDir) {
     });
   }
 
+  // 6. figma_extract — extract readiness + Free-tier plugin-sync signal (Plan 31-09)
+  // Reports exactly one of three states. PURE read-only: presence-only token
+  // check (D-10 — value never read/logged/printed) + a LOCAL Free-tier marker
+  // (a prior pull's _meta.json recording a 403/skip on the Variables endpoint —
+  // see scripts/lib/figma-extract/pull.cjs). NEVER throws, NEVER networks.
+  {
+    // D-10: presence only. The token VALUE is never bound to a variable that
+    // could be interpolated into detail/logs — only the boolean is kept.
+    const tokenSet = !!(process.env.FIGMA_TOKEN || process.env.FIGMA_PERSONAL_ACCESS_TOKEN);
+
+    let detail;
+    let status;
+    if (!tokenSet) {
+      detail = 'figma extract: token missing';
+      status = 'warn';
+    } else if (figmaVariablesBlockedLocally(rootDir)) {
+      // Token present but a prior pull recorded a 403/skip on the Variables REST
+      // path → Free/non-Enterprise tier. Actionable (plugin sync), not a hard fail.
+      detail = 'figma extract: plugin sync needed for variables (Free tier detected)';
+      status = 'warn';
+    } else {
+      detail = 'figma extract: ready (token set)';
+      status = 'ok';
+    }
+    checks.push({ name: 'figma_extract', status, detail });
+  }
+
   return { checks };
 }
 
+/**
+ * Free-tier signal (LOCAL only — never a network call). The raw-pull stage
+ * (scripts/lib/figma-extract/pull.cjs) writes a _meta.json per file key under
+ * the gitignored cache dir; on a Variables 403 it records a totals[] entry
+ * `{ name: 'variables', skipped: true, reason: 'HTTP 403' }`. We scan the
+ * default cache root for any such marker. Defensive: malformed/absent markers
+ * default to NOT-free (→ 'ready') so the health probe never false-alarms and
+ * NEVER throws. NEVER reads the token; NEVER makes a request.
+ *
+ * @param {string} rootDir project root passed to getHealthChecks
+ * @returns {boolean} true iff a prior pull recorded a Variables 403/skip
+ */
+function figmaVariablesBlockedLocally(rootDir) {
+  try {
+    const rawRoot = path.join(rootDir, '.figma-extract-cache', 'raw');
+    let entries;
+    try {
+      entries = fs.readdirSync(rawRoot, { withFileTypes: true });
+    } catch {
+      return false; // no cache yet → default to ready
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const metaPath = path.join(rawRoot, ent.name, '_meta.json');
+      let meta;
+      try {
+        meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      } catch {
+        continue; // missing/garbage marker → ignore this dir, keep scanning
+      }
+      const totals = meta && Array.isArray(meta.totals) ? meta.totals : [];
+      const blocked = totals.some(
+        (t) =>
+          t &&
+          t.name === 'variables' &&
+          t.skipped === true &&
+          typeof t.reason === 'string' &&
+          /403/.test(t.reason)
+      );
+      if (blocked) return true;
+    }
+    return false;
+  } catch {
+    // Absolute safety net — the health probe must never crash on this check.
+    return false;
+  }
+}
+
 module.exports = { getHealthChecks };

package/skills/figma-extract/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gdd-figma-extract
+description: Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context.
+---
+
+# gdd-figma-extract
+
+Pull a whole Figma design system into a compact, queryable local digest — **without** the raw JSON ever entering Claude context. The heavy lifting runs in tested `.cjs` tools; the model reads only the digest outputs.
+
+## Usage
+
+```
+/gdd:figma-extract <file-key-or-url>                  # full design-system digest
+/gdd:figma-extract <file-key-or-url> --component Button  # ~500-token single-component slice
+```
+
+`<file-key-or-url>` is a Figma file URL (`https://www.figma.com/file/<key>/…` or `/design/<key>/…`) or a bare file key.
+
+## Behavior
+
+1. **Preflight (D-10).** Confirm `FIGMA_TOKEN` is set in the environment:
+   ```
+   node -e "process.exit(process.env.FIGMA_TOKEN||process.env.FIGMA_PERSONAL_ACCESS_TOKEN?0:1)"
+   ```
+   If unset, tell the user to `export FIGMA_TOKEN=figd_…` (from https://www.figma.com/developers/api#access-tokens). The token comes from the environment **only** — never ask the user to paste it into a file or the chat, and never echo it back.
+
+2. **Stage 1 — pull.** Pull the file's REST endpoints into the gitignored raw cache (D-09):
+   ```
+   node scripts/lib/figma-extract/pull.cjs "<file-key-or-url>"
+   ```
+   This caches to `.figma-extract-cache/raw/<file-key>/` and skips re-pulling when Figma's `version` is unchanged (D-11). Add `--force` to bypass the cache, `--out <dir>` to relocate the cache. The tool prints a JSON summary (endpoints, bytes, cached) on stdout — the raw bodies stay on disk.
+
+3. **Stage 2 — plugin sync (OPTIONAL, Path C).** Only when the design tokens live in Figma Variables that the REST API cannot return (non-Enterprise plans → the pull summary shows `variables` skipped) and the user wants token coverage:
+   ```
+   node scripts/lib/figma-extract/receiver.cjs --out .figma-extract-cache/raw/<file-key>
+   ```
+   This binds `127.0.0.1:5179` (D-06). Tell the user to run the dev-installed **"GDD Sync"** plugin in Figma and click **"Export to GDD"** — see `figma-plugin/README.md` for the one-time dev-install. The receiver writes `variables.json` into the cache and exits on receipt or timeout. Skip this stage entirely for design systems whose tokens already come through the REST pull.
+
+4. **Stage 3 — digest.** Transform the cache into the compact digest:
+   ```
+   node scripts/lib/figma-extract/digest.cjs --raw .figma-extract-cache/raw/<file-key> --out .figma-extract-cache/digest
+   ```
+   This writes `DESIGN.md`, `tokens.json`, and `components.json`. Add `--prefer-styles` to invert the token priority to styles-first (D-04). Add `--component <name>` (D-08) to emit a single-component slice instead of the full digest.
+
+5. **Read the digest.** Open **only** `.figma-extract-cache/digest/DESIGN.md` (plus `tokens.json` / `components.json` when you need structured data). For a single component, pass `--component <name>` in Stage 3 and read the ~500-token slice instead of the full ~16K-token spec.
+
+## Required Reading
+
+- `.figma-extract-cache/digest/DESIGN.md` — the compact human/LLM-readable spec
+- `.figma-extract-cache/digest/tokens.json` — resolved design tokens (when structured token data is needed)
+- `.figma-extract-cache/digest/components.json` — components with variants/props/defaults (when structured component data is needed)
+
+## Notes
+
+- Two-stage pipeline (D-01): re-run Stage 3 against an existing cache without re-pulling. The digest does zero network calls.
+- The spike proved **0 Claude tokens** during extraction (898× compression, 223 MB → 254 KB). That property holds only because this skill never surfaces the raw cache.
+- Figma MCP remains the right tool for spot questions on a single live component; this skill is the cheaper path for whole-design-system workflows.
+
+## Do Not
+
+- **Do NOT read or `cat` the `raw/*.json` cache** (e.g. `.figma-extract-cache/raw/<file-key>/file.json`). It is tool-internal and often 100+ MB; loading it into context defeats the off-context guarantee (D-12). Read only the digest outputs above.
+- **Do not persist, log, echo, or print `FIGMA_TOKEN`** (D-10). It belongs in the environment only — never write it to a file, a commit, or chat output.
+
+## FIGMA-EXTRACT COMPLETE

package/skills/health/SKILL.md

@@ -53,6 +53,16 @@ Health: 5 / 6 checks passing.
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Figma-extract readiness (figma_extract)
+
+After the health table, the `gdd_health` MCP surface (`scripts/lib/health-mirror/index.cjs`) reports a `figma_extract` check so a user knows whether figma-extract is usable. The detail is one of three exact strings:
+
+- `figma extract: ready (token set)` — `FIGMA_TOKEN` (or `FIGMA_PERSONAL_ACCESS_TOKEN`) is present (status `ok`).
+- `figma extract: token missing` — no token env is set (status `warn`).
+- `figma extract: plugin sync needed for variables (Free tier detected)` — token present but a prior pull recorded a 403/skip on the Variables REST path, so run the plugin-sync step (status `warn`).
+
+Token PRESENCE only is detected (D-10) — the token value is never read, logged, or shown. The Free-tier signal is read from the local raw-pull cache only; no network call is made.
+
 ## Check MCP registration (gdd-mcp)
 
 After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./health-mcp-detection.md`.