@calibrate-ds/cli 0.1.89 → 0.1.90

package/README.md

@@ -150,7 +150,7 @@ ptb stamp component Button # mark Button as implemented against the current desi
 
 ## MCP Server — AI IDE Integration
 
-PTB exposes 22 tools over a stdio MCP server. Your AI IDE can query component design context, run scans, generate code, and manage stamps — all from chat. Everything you can do in the terminal, you can do from chat.
+PTB exposes 23 tools over a stdio MCP server. Your AI IDE can query component design context, run scans, generate code, and manage stamps — all from chat. Everything you can do in the terminal, you can do from chat.
 
 ### Available tools
 
@@ -768,6 +768,6 @@ See [PTB.md](./PTB.md) for architecture, type definitions, the generator interfa
 ```bash
 pnpm install
 pnpm build
-pnpm test            # 593 tests across core, generator, and CLI
+pnpm test            # 609 tests across core, generator, and CLI
 node apps/cli/dist/index.js --help
 ```

package/dist/commands/init.js

@@ -562,7 +562,7 @@ export function createInitCommand() {
         console.log(`       \x1b[36mptb export context\x1b[0m       \x1b[2m— write .ptb/context/ files for AI IDEs (commit these)\x1b[0m`);
         console.log(`       \x1b[2mNext.js App Router? Add \x1b[0m\x1b[33m"useClient": true\x1b[0m\x1b[2m to the \x1b[0m\x1b[33mgeneration\x1b[0m\x1b[2m section of ptb.config.json\x1b[0m`);
         console.log(`       \x1b[2mso every generated component emits \x1b[0m\x1b[36m"use client"\x1b[0m\x1b[2m as its first line.\x1b[0m\n`);
-        console.log(`  ${step++}. Connect your AI IDE via MCP — PTB exposes 22 tools (scan, generate, inspect, stamp, and more):\n`);
+        console.log(`  ${step++}. Connect your AI IDE via MCP — PTB exposes 23 tools (scan, generate, inspect, stamp, and more):\n`);
         console.log(`       \x1b[1mClaude Code:\x1b[0m  already configured via \x1b[36m.mcp.json\x1b[0m — just restart Claude Code.\n`);
         console.log(`       \x1b[1mOther IDEs\x1b[0m (Cursor, Windsurf, Antigravity, VS Code):`);
         console.log(`       Once Claude Code is connected, ask in chat:  \x1b[36m"set up MCP for cursor"\x1b[0m`);

package/dist/mcp/tools/action-tools.js

@@ -299,6 +299,10 @@ TYPICAL WORKFLOW:
 3. Read contextFile for the full implementation brief (it contains promptText, the
    render tree, and variantDiffs — these are intentionally NOT inlined in this
    response because they exceed the tool-call size limit on large components)
+3b. For a multi-variant component set, call get_variant_tokens("<name>") for the
+   compact per-variant build matrix — every variant's resolved --ptb-* bindings,
+   colors, radius, padding, and gap in one small response. Prefer this over
+   excavating variantDiffs from the contextFile.
 4. Implement the requested component
 5. Call submit_work("<name>") when done`, { name: z.string().describe("Component to start working on, e.g. 'SearchBar'") }, async ({ name }) => {
             let ctx;
@@ -401,11 +405,17 @@ TYPICAL WORKFLOW:
                                     options: ax.options ?? [],
                                     defaultValue: ax.defaultValue,
                                 })),
+                                // B-5: emit real binding data, not just slot names. The old map
+                                // read b.token/b.cssVar/b.collection — fields that don't exist on
+                                // a TokenBinding — so every entry serialized to just {slot}. The
+                                // actual value (rawValue) and token identity live on resolvedToken.
                                 tokenBindings: (context.tokenBindings ?? []).map((b) => ({
                                     slot: b.slot,
-                                    token: b.token,
-                                    cssVar: b.cssVar,
-                                    collection: b.collection,
+                                    rawValue: b.rawValue ?? null,
+                                    token: b.resolvedToken?.name ?? b.boundToken?.name ?? null,
+                                    cssVar: b.resolvedToken?.cssVariable ?? null,
+                                    collection: b.resolvedToken?.collection?.name ?? null,
+                                    bound: !!b.boundToken,
                                 })),
                                 dependencies: context.dependencies.map((d) => ({
                                     name: d.name,
@@ -694,11 +704,17 @@ recursively when you call it for that dependency.`, { name: z.string().describe(
                                     options: ax.options ?? [],
                                     defaultValue: ax.defaultValue,
                                 })),
+                                // B-5: emit real binding data, not just slot names. The old map
+                                // read b.token/b.cssVar/b.collection — fields that don't exist on
+                                // a TokenBinding — so every entry serialized to just {slot}. The
+                                // actual value (rawValue) and token identity live on resolvedToken.
                                 tokenBindings: (context.tokenBindings ?? []).map((b) => ({
                                     slot: b.slot,
-                                    token: b.token,
-                                    cssVar: b.cssVar,
-                                    collection: b.collection,
+                                    rawValue: b.rawValue ?? null,
+                                    token: b.resolvedToken?.name ?? b.boundToken?.name ?? null,
+                                    cssVar: b.resolvedToken?.cssVariable ?? null,
+                                    collection: b.resolvedToken?.collection?.name ?? null,
+                                    bound: !!b.boundToken,
                                 })),
                                 dependencies: context.dependencies.map((d) => ({
                                     name: d.name,

package/dist/mcp/tools/component-tools.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { z } from "zod";
-import { getComponentContext } from "@calibrate-ds/core";
+import { getComponentContext, buildVariantTokenMap } from "@calibrate-ds/core";
 function toSlug(name) {
     return name.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -201,6 +201,33 @@ EVERYTHING YOU NEED IS IN PTB:
             catch { /* non-fatal */ }
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         });
+        server.tool("get_variant_tokens", `Get the compact per-variant token/style build matrix for a component set.
+
+For EVERY variant (all combinations of the variant axes), returns the resolved
+design-system bindings and spacing needed to implement it:
+  - background / text-color / border-color → { cssVar (--ptb-*), value (hex), token }
+  - border-radius, padding, gap             → resolved values (px)
+  - per-node text content, stroke weight + align (inside/outside)
+
+This is the data an agent needs to build all variants WITHOUT reading the large
+context render tree or reconstructing it from variantDiffs. Emit each slot as
+var(<cssVar>, <value>) when cssVar is present; use value directly when it is not.
+Returns variantCount:0 with a note for single (non-set) components.`, { name: z.string().describe("Component set name, e.g. 'ChipsWeb'") }, async ({ name }) => {
+            let ctx;
+            try {
+                ctx = await getContext();
+            }
+            catch (e) {
+                return { content: [{ type: "text", text: e.message }] };
+            }
+            const comp = findComponent(ctx.snapshot, name);
+            if (!comp) {
+                const available = ctx.snapshot.components.map((c) => c.name).slice(0, 15).join(", ");
+                return { content: [{ type: "text", text: `Component '${name}' not found.\nAvailable (first 15): ${available}` }] };
+            }
+            const map = buildVariantTokenMap(comp);
+            return { content: [{ type: "text", text: JSON.stringify(map, null, 2) }] };
+        });
     },
 };
 //# sourceMappingURL=component-tools.js.map

package/dist/mcp/tools/info-tools.js

@@ -3,6 +3,17 @@ import * as path from "node:path";
 import { z } from "zod";
 import { resolveToken } from "@calibrate-ds/core";
 const UPGRADE_CHECKLIST = {
+    "0.1.90": [
+        "BAKE-OFF audit fixes (docs/PTB_VS_FIGMA_BAKEOFF.md). A cold PTB-only vs Figma-only head-to-head exposed that PTB's verifier declined to enforce the one thing PTB uniquely provides: design-system token binding.",
+        "FIX (B-1, the moat gate): verify computed cssVarScore (fraction of the design's bound --ptb-* vars present in the CSS) then NEVER read it — a token-blind component that renders correctly but binds ZERO design tokens PASSED. cssVarScore is now a HARD GATE: cssVarScore === 0 → fail, and tokenScore cannot rescue it. cssVarScore is now surfaced in the run_verify / get_verify_report responses.",
+        "FIX (B-1, naming): tokenScore was misnamed — it measures rendered TEXT content, not token binding. The response now also returns textContentScore (the accurate name); tokenScore is kept as a deprecated alias so nothing breaks.",
+        "FIX (B-2, scaffold CSS): a token-bound border emitted 'border: var(--x, #hex)' — a bare color with no width/style, which is INVALID and dropped, leaving outlined components with no border. Now emits 'border: 1px solid var(...)'. Also: slots that map to the same CSS property (text/fill/iconColor → color) no longer emit a duplicate declaration. Regenerate components (generate-components --force) to pick these up.",
+        "FIX (B-5): start_work's tokenBindings returned just {slot} with no values (it read fields that don't exist on the type). It now returns rawValue, token name, cssVar, collection, and bound flag.",
+        "NEW TOOL (B-3, the cost win): get_variant_tokens(name) returns a compact PRE-RESOLVED per-variant token matrix — for every variant, the --ptb-* binding + value for background/text/border, plus radius/padding/gap/text and stroke weight+align. No more scripting through variantDiffs: ChipsWeb's full 42-variant matrix is ~6k tokens (vs ~86k to read context naively). start_work now points agents to it for multi-variant sets. Restart your MCP server to see the new tool.",
+        "FIX (B-4): Storybook loaded no fonts, so text rendered in a fallback and CAPPED every text component's pixel score (~0.82) regardless of correctness. setup now writes .storybook/preview-head.html loading the design's fonts (from typography.css) via Google Fonts. Re-run Storybook setup / ptb init to get it.",
+        "FIX (B-8): per-variant verify now names how many variants had no reference thumbnail and were skipped (was silently undercounting). FIX (B-9): the primary diff image is retained + its path kept in the verify report, so a low score is inspectable (was deleting all pngs).",
+        "B-7 strokeAlign is now available to the agent via get_variant_tokens (weight+align). Deferred (verified, not changed): B-2 double-padding, B-6 radius alias tier (risky core change), B-10 unbound raw hexes (design-side, not a PTB bug). Restart MCP; regenerate components for the CSS fixes. 609 tests.",
+    ],
     "0.1.89": [
         "INDEPENDENCE release — PTB no longer recommends or depends on any external tool. Previously several MCP tool descriptions told the agent to 'cross-check with Figma MCP' (get_variable_defs / get_screenshot) for exact hex and visual truth.",
         "That guidance was redundant: PTB already has that data from its own scan. tokenConflicts now direct the agent to rawValue — the hex the design actually renders, captured by the scan — with var(--ptb-token, <rawValue>) as the fallback; and the scan thumbnail at thumbnailPath is the visual ground truth for colors/spacing/arrangement.",

package/dist/mcp/tools/verify-tool.js

@@ -86,6 +86,16 @@ Returns: pixel match score, AI assessment ("matches" / "minor-differences" / "si
                                 passFail,
                                 verdictScore,
                                 verdictMetric,
+                                // B-1: cssVarScore is the design-system BINDING signal — fraction
+                                // of the design's bound --ptb-* vars present in the CSS. 0 = the
+                                // component renders correctly but is disconnected from the design
+                                // system (hard fail via the verdict gate). Surfaced so agents/users
+                                // can see it, not just its warning string.
+                                cssVarScore: result.cssVarScore ?? null,
+                                // textContentScore is the accurate name for what tokenScore measures
+                                // (rendered TEXT content, NOT token binding). tokenScore is a
+                                // deprecated alias kept for existing consumers.
+                                textContentScore: result.textContentScore ?? result.tokenScore ?? null,
                                 tokenScore: result.tokenScore ?? null,
                                 structureScore: result.structureScore ?? null,
                                 pixelMatchScore: score,
@@ -122,6 +132,8 @@ Returns: pixel match score, AI assessment ("matches" / "minor-differences" / "si
                 const summary = {
                     component: report.componentName,
                     checkedAt: report.checkedAt,
+                    cssVarScore: report.cssVarScore ?? null,
+                    textContentScore: report.textContentScore ?? report.tokenScore ?? null,
                     pixelMatchScore: report.pixelMatch?.score ?? null,
                     assessment: report.aiFeedback?.overallAssessment ?? null,
                     summary: report.aiFeedback?.summary ?? null,

package/dist/verify/run-verify.js

@@ -493,6 +493,17 @@ export async function runVerify(component, config, snapshot, options = {}) {
     // warning gate can check whether per-variant thumbnails are available before
     // deciding whether to fire a "no design reference" warning.
     const variantThumbs = component.variantThumbnails ?? [];
+    // B-8: the true number of variants in the set (every variant child), which can
+    // exceed the number of reference thumbnails when some variants failed to export.
+    // Previously the "capped at N of M" message used only the thumbnail count, so
+    // missing variants were silently unaccounted for. Surface the real gap.
+    const declaredVariantCount = component.variantNodeRefs?.length ??
+        component.variantSnapshots?.length ??
+        variantThumbs.length;
+    if (declaredVariantCount > variantThumbs.length) {
+        warnings.push(`${declaredVariantCount - variantThumbs.length} of ${declaredVariantCount} variants have no reference ` +
+            `thumbnail and were not pixel-verified (re-run 'ptb scan' to regenerate variant references).`);
+    }
     // GAP-022: prefer the single-variant reference for pixel-diff (a single-variant
     // story can't match the full variant grid). Fall back to the grid thumbnail.
     const thumbnailPath = component.variantThumbnailPath ?? component.thumbnailPath ?? null;
@@ -621,6 +632,9 @@ export async function runVerify(component, config, snapshot, options = {}) {
                         report.designTokenCount = designTokens.length;
                         report.foundTokenCount = found.length;
                         report.tokenScore = parseFloat((found.length / designTokens.length).toFixed(4));
+                        // B-1: same value under the accurate name (tokenScore measures
+                        // rendered TEXT content, not token binding). tokenScore kept as alias.
+                        report.textContentScore = report.tokenScore;
                     }
                 }
             }
@@ -756,14 +770,23 @@ export async function runVerify(component, config, snapshot, options = {}) {
         }
     }
     // ── Step 5: Cleanup PNG artifacts ───────────────────────────────────────
-    // All scores and feedback are in report.json; the PNGs are no longer needed.
-    // At scale (100+ components × 20 variants) keeping them wastes significant disk.
+    // B-9: retain the single primary diff image so a low score is inspectable —
+    // previously ALL pngs were deleted and screenshots.diff nulled, so an agent
+    // seeing a low pixelMatch had no way to see WHERE it diverged (it had to find
+    // report.json on disk and re-run Playwright by hand). The figma/impl and
+    // per-variant pngs are still removed; one diff per component is negligible disk.
     // Thumbnails live in .ptb/thumbnails/ — outside verifyDir — and are not touched.
-    report.screenshots = { figma: null, figmaSource: report.screenshots.figmaSource, impl: null, diff: null };
+    const keepDiff = report.screenshots.diff ? path.basename(report.screenshots.diff) : null;
+    report.screenshots = {
+        figma: null,
+        figmaSource: report.screenshots.figmaSource,
+        impl: null,
+        diff: report.screenshots.diff ?? null,
+    };
     // Persist report
     const reportPath = path.join(verifyDir, "report.json");
     await fs.writeFile(reportPath, JSON.stringify(report, null, 2), "utf-8");
-    const pngs = (await fs.readdir(verifyDir)).filter(e => e.endsWith(".png"));
+    const pngs = (await fs.readdir(verifyDir)).filter(e => e.endsWith(".png") && e !== keepDiff);
     await Promise.all(pngs.map(e => fs.unlink(path.join(verifyDir, e)).catch(() => undefined)));
     return { ...report, warnings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calibrate-ds/cli",
-  "version": "0.1.89",
+  "version": "0.1.90",
   "license": "FSL-1.1-MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -44,10 +44,10 @@
     "commander": "^14.0.3",
     "openai": "^6.34.0",
     "zod": "^4.3.6",
-    "@calibrate-ds/core": "^0.1.89",
-    "@calibrate-ds/figma-client": "^0.1.89",
-    "@calibrate-ds/generator-react": "^0.1.89",
-    "@calibrate-ds/shared-types": "^0.1.89"
+    "@calibrate-ds/core": "^0.1.90",
+    "@calibrate-ds/figma-client": "^0.1.90",
+    "@calibrate-ds/generator-react": "^0.1.90",
+    "@calibrate-ds/shared-types": "^0.1.90"
   },
   "devDependencies": {
     "@types/node": "^22.13.5",