@calibrate-ds/cli 0.1.87 → 0.1.89

package/README.md

@@ -768,6 +768,6 @@ See [PTB.md](./PTB.md) for architecture, type definitions, the generator interfa
 ```bash
 pnpm install
 pnpm build
-pnpm test            # 586 tests across core, generator, and CLI
+pnpm test            # 593 tests across core, generator, and CLI
 node apps/cli/dist/index.js --help
 ```

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

@@ -280,20 +280,25 @@ criteria, and recommended build order.
 
 TOKEN AUTHORITY — what to trust, what to verify:
 - PTB's --ptb-* cssVar names are authoritative for token identity. Always emit them.
-- If tokenConflicts is present in the response, PTB's resolved token hex diverges from
-  the raw Figma fill. These are low-confidence — verify with Figma (get_variable_defs or
-  get_screenshot) and use: var(--ptb-token, <figma-verified-hex>) as the CSS fallback.
-- PTB cannot verify exact visual appearance. Use Figma for colors/spacing when in doubt.
+- If tokenConflicts is present, PTB's resolved token hex diverges from the raw scanned
+  fill. Each conflict includes rawValue — the hex the design actually renders, captured
+  by PTB's own scan. Trust rawValue as the visual ground truth and emit:
+  var(--ptb-token, <rawValue>) as the CSS fallback.
+- For exact visual appearance, read the scan thumbnail at thumbnailPath (and per-variant
+  thumbnails) — it is PTB's captured ground truth for colors, spacing, and arrangement.
 
-DIVISION OF LABOR WITH FIGMA MCP (composite workflow — most accurate):
-  PTB  → token names, dependency graph, variant axes, state/content contracts (read contextFile)
-  Figma → exact hex values, spacing, visual arrangement (get_variable_defs, get_screenshot)
-  Map: Figma hex  →  get_token(hex)  →  --ptb-* cssVar name → emit both together
+EVERYTHING YOU NEED IS IN PTB (no external tools required):
+  token names, dependency graph, variant axes, state/content contracts → read contextFile
+  exact rendered hex → tokenConflicts[].rawValue (from the scan)
+  visual arrangement/spacing → the scan thumbnail at thumbnailPath
+  hex → token name → get_token(hex)
 
 TYPICAL WORKFLOW:
 1. Call start_work("<name>") — read blockedBy and tokenConflicts first
 2. For each blocker: call start_work("<dep>"), implement, call submit_work("<dep>")
-3. Read contextFile for the full implementation brief
+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)
 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;
@@ -411,12 +416,16 @@ TYPICAL WORKFLOW:
                                 layout: context.layout,
                                 size: context.size,
                                 docs: buildDocsPayload(context, codeName, ctx),
-                                promptText: promptPackage.promptText,
+                                // NEW-8: promptText (often 100 KB+) is NOT inlined here — it blew the
+                                // MCP tool-call token limit (94.7% of the payload) and failed the call
+                                // outright on large component-sets. The full brief lives in contextFile
+                                // (unchanged — it still contains promptText and every detail); read it
+                                // from there. Only the compact instructions/summary travel in the payload.
                                 instructions: promptPackage.instructions,
                                 structureSummary: promptPackage.structureSummary,
                                 // Token conflicts: slots where PTB's resolved token hex differs from
-                                // the raw Figma fill. Always low-confidence — verify against Figma
-                                // (get_screenshot / get_variable_defs) before trusting the token name.
+                                // the raw scanned fill. Each carries rawValue (what the design renders,
+                                // from PTB's scan) — trust that and emit var(--ptb-token, <rawValue>).
                                 ...(context.tokenConflicts?.length
                                     ? { tokenConflicts: context.tokenConflicts }
                                     : {}),
@@ -565,13 +574,13 @@ Returns the design context (variants, tokens, slots, contracts, render tree) for
 component PLUS a dependency check: which child components this one uses and whether they are
 already implemented in ptb.lock.
 
-TOKEN AUTHORITY — what to trust, what to verify:
+TOKEN AUTHORITY — what to trust:
 - PTB's --ptb-* cssVar names are authoritative. Always use them in emitted CSS.
-- If tokenConflicts is present, PTB's resolved token hex diverges from the raw Figma fill
-  for those slots. Cross-check with Figma (get_variable_defs / get_screenshot) and emit the
-  correct hex as a literal fallback: var(--ptb-token, <figma-hex>).
-- PTB does NOT know exact pixel positions, image assets, or precise spacing when tokens are
-  unresolved ("unknown"). Use Figma for those facts.
+- If tokenConflicts is present, PTB's resolved token hex diverges from the raw scanned fill
+  for those slots. Each conflict carries rawValue — the hex the design actually renders,
+  from PTB's scan. Emit it as the literal fallback: var(--ptb-token, <rawValue>).
+- For exact visual appearance — colors, spacing, image assets, arrangement — read the scan
+  thumbnail at thumbnailPath (and per-variant thumbnails). That is PTB's captured ground truth.
 
 WORKFLOW — follow this exactly:
 1. Check unbuiltDependencies. If any exist, call implement_component for each one in buildOrder first.
@@ -700,7 +709,9 @@ recursively when you call it for that dependency.`, { name: z.string().describe(
                                 layout: context.layout,
                                 size: context.size,
                                 docs: buildDocsPayload(context, codeName, ctx),
-                                promptText: promptPackage.promptText,
+                                // NEW-8: promptText is NOT inlined (it exceeds the MCP tool-call token
+                                // limit on large components). The full brief — including promptText — is
+                                // in contextFile, which is unchanged; read it from there.
                                 instructions: promptPackage.instructions,
                                 structureSummary: promptPackage.structureSummary,
                                 ...(context.tokenConflicts?.length

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

@@ -51,16 +51,17 @@ WHAT PTB IS AUTHORITATIVE FOR (trust these without Figma):
 - Variant axes, state contract, interaction contract, slot contract
 - Lifecycle: designHash, stampedHash, workStatus (from ptb.lock)
 
-WHAT PTB CANNOT VERIFY (cross-check with Figma when available):
-- Exact visual appearance — PTB has no rendered reference
+VISUAL GROUND TRUTH (all from PTB's own scan — no external tools needed):
+- Exact visual appearance — read the scan thumbnail at thumbnailPath (and per-variant
+  thumbnails). That is the captured reference for colors, spacing, positions, and assets.
 - tokenConflicts (if present): slots where PTB's resolved token hex diverges from the raw
-  Figma fill. Always low-confidence. Use Figma get_variable_defs or get_screenshot to
-  determine which value is correct, then use PTB's cssVar name with Figma's hex as fallback.
+  scanned fill. Each carries rawValue — the hex the design actually renders. Emit PTB's
+  cssVar name with rawValue as the literal fallback: var(--ptb-token, <rawValue>).
 
-DIVISION OF LABOR WITH FIGMA MCP (composite workflow):
-  PTB  → token names, dependency graph, variant axes, state/content contracts
-  Figma → exact hex values, spacing px, badge positions, image assets (get_variable_defs, get_screenshot)
-  Never deep-read the full render tree just to recover colors — that is Figma's job.`, {
+EVERYTHING YOU NEED IS IN PTB:
+  token names, dependency graph, variant axes, state/content contracts → this response
+  exact rendered hex → tokenConflicts[].rawValue      visual arrangement → thumbnailPath
+  hex → token name → get_token(hex)`, {
             name: z.string().describe("Component display name, e.g. 'Button' or 'Notification Item'"),
             detail: z.enum(["summary", "full"]).optional().default("summary").describe("'summary' (default): compact planning brief — variant axes, token bindings, dependencies, layout, state axis names, contextFile path. " +
                 "'full': complete context with render tree and compressed variant patches."),

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

@@ -3,6 +3,19 @@ import * as path from "node:path";
 import { z } from "zod";
 import { resolveToken } from "@calibrate-ds/core";
 const UPGRADE_CHECKLIST = {
+    "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.",
+        "Net effect: fewer round-trips, no dependency on a third-party MCP, and the agent gets a concrete value instead of being sent to another tool. No code behavior changed — only agent-facing guidance in start_work / get_component / get_token descriptions and two type comments.",
+        "Restart your IDE's MCP server to pick up the updated tool descriptions. No re-scan. 593 tests.",
+    ],
+    "0.1.88": [
+        "0.1.87 audit fixes (docs/PTB_0187_REPORT.md). Closes the last functional beta blocker plus the emitter-parity residuals. Six-plus releases, zero regressions.",
+        "FIX (NEW-8, open since .79 — was FAILING HARD): start_work's MCP response inlined promptText (100 KB+, 94.7% of the payload), so start_work on a large component-set EXCEEDED the tool-call token limit and the call failed outright. promptText is no longer inlined in the response. The contextFile on disk is UNCHANGED — it still contains promptText and every detail; read the full brief from there (the tool description says so). This unblocks the primary agent entry point.",
+        "FIX (E-19 parity): multi-mode themes (e.g. Light/Dark) reached the canonical tokens.css but NOT the per-collection css/<name>.css or the TS export <name>.ts. All three emitters now emit every mode — per-collection CSS gets [data-theme] blocks; the TS export carries a valuesByMode field per token.",
+        "FIX (E-9 parity): a malformed hex value (e.g. #GGGGGG) was dropped from CSS but still leaked into the TS export. It's now skipped by every emitter, including <name>.ts. A shared token-value guard + a cross-emitter parity test prevent this fix-one-emitter class from recurring.",
+        "Re-run 'ptb generate-tokens' (or let start_work regenerate) to pick up the emitter fixes. No re-scan needed for these. Restart your IDE's MCP server for the start_work payload change. 593 tests.",
+    ],
     "0.1.87": [
         "LICENSE CHANGE release — no code changes. Calibrate is now licensed under the Functional Source License (FSL-1.1-MIT), a source-available license, instead of Apache-2.0.",
         "What it means: you may still read, use, copy, modify, and redistribute the software freely for any purpose EXCEPT a Competing Use (offering it as a commercial product/service that substitutes for Calibrate). Each version additionally becomes MIT-licensed two years after its release.",

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

@@ -141,8 +141,9 @@ Accepts:
 
 Returns: collection, tokenName, cssVar (--ptb-* variable), resolvedValue, aliasChain (when present).
 
-PTB owns the token identity map — use hex lookup when Figma's get_variable_defs returns a
-raw color and you need the canonical --ptb-* name instead of guessing the convention.`, { query: z.string().describe("Token name, path, Figma variable name (surface/surface-info-light), or hex color (#E5F3FF)") }, async ({ query }) => {
+PTB owns the token identity map — use hex lookup when you have a raw color (e.g. a
+tokenConflicts rawValue from the scan) and need the canonical --ptb-* name instead of
+guessing the convention.`, { query: z.string().describe("Token name, path, Figma variable name (surface/surface-info-light), or hex color (#E5F3FF)") }, async ({ query }) => {
             let ctx;
             try {
                 ctx = await getContext();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calibrate-ds/cli",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "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/figma-client": "^0.1.87",
-    "@calibrate-ds/generator-react": "^0.1.87",
-    "@calibrate-ds/core": "^0.1.87",
-    "@calibrate-ds/shared-types": "^0.1.87"
+    "@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"
   },
   "devDependencies": {
     "@types/node": "^22.13.5",