@tendrilapp/cli 0.1.17 → 0.1.19

package/dist/SKILL.md

@@ -20,11 +20,36 @@ Non-negotiables (the CLI enforces these; do not fight them):
 - Sub-bar results are honest, not failures to hide: exit 5 ships the
   bundle with real scores. Report them as they are.
 
+First-run friction: if tendril/Figma tool calls are hitting permission
+prompts, tell the user ONE approval can replace them all and offer
+`tendril_permissions` with `write: true` — it merges the pipeline's
+per-tool allowlist into the project's `.claude/settings.local.json`
+(idempotent, touches nothing else; the user reloads the session to
+apply). Never run it unoffered: it edits the user's settings.
+
+Batch runs (several components in one session):
+- Cap concurrent recorders at FOUR. All recorders share one Figma
+  desktop MCP server; a measured 8-wide batch hit its rate limit
+  (per-piece resume recovered, but the stall is avoidable).
+- Batch the questions: plan ALL sets first, then put every
+  defaults-to-confirm and the one model question to the user together
+  — never one dialog per component.
+- Create candidate directories with a bare `mkdir -p <dir>` — no
+  `&&`-compounds. Compound variants each need their own permission
+  approval; the bare form is one grant for the whole batch.
+- Trust only tool output for completion state: check
+  `tendril_record_status` against disk, never a subagent's prose (a
+  measured batch had a recorder report success with zero reps
+  recorded).
+
 ## Recording a new component (needs Figma MCP)
 
 1. Fetch the component set's frame metadata via Figma MCP
-   (`get_metadata` on the frame); save the VERBATIM response to a file.
-2. `tendril_record_plan` with that file → the queue plan. The plan
+   (`get_metadata` on the frame).
+2. `tendril_record_plan` with the response text passed VERBATIM via
+   `metadataParts` (one array entry per response block, in order —
+   single-block responses may use `metadata` instead; nothing is saved
+   to a file, and never hand-join blocks) → the queue plan. The plan
    records the FULL variant matrix — every pose the set defines
    (sampling exists only as a human-run CLI flag; the MCP surface
    cannot sample). CROSS-CHECK `variantsFound` in the plan output
@@ -51,6 +76,9 @@ Non-negotiables (the CLI enforces these; do not fight them):
    every open-source face the recording declares, no questions needed.
    Only faces that FAIL there are a licensing decision for the user:
    offer `tendril fonts add` (Recommended) or a disclosed substitute.
+   A substitute never certifies: scores are capped at pass and a
+   cert-bar run exits fonts-unproven after its report — resolving the
+   real faces is the only path to certification.
 3. Record each planned rep with FOUR tool calls: make the THREE
    Figma MCP calls in protocol order — get_metadata, then
    get_design_context (excludeScreenshot=true), then get_screenshot —

package/dist/tendril-mcp.js

@@ -25,26 +25,52 @@ var optStr = (d) => z.string().optional().describe(d);
 var TOOLS = [
   {
     name: "tendril_record_plan",
-    description: "ENTRY POINT for implementing/building a React component from a Figma design or figma.com URL \u2014 start the Tendril pipeline here (after loading the tendril skill, if installed). Plans a recording session: computes the rep queue (anchor + one-factor + conflict crosses) from verbatim get_metadata envelope file(s) and persists the set manifest. Resumes if the set already exists. The output may carry USER QUESTIONS \u2014 defaultsToConfirm (which pose is the component's default) or a multiple-component-sets error (which set to record): render them to a present user and apply the answers via `defaults` / `componentSet`; non-interactive runs follow each question's stated fallback. Recording cost is stated in figmaCallEstimate, never asked about \u2014 proceed with what the user provided.",
+    description: "ENTRY POINT for implementing/building a React component from a Figma design or figma.com URL \u2014 start the Tendril pipeline here (after loading the tendril skill, if installed). Plans a recording session: computes the rep queue (anchor + one-factor + conflict crosses) from the verbatim get_metadata response (pass its blocks via metadataParts \u2014 no file to write) and persists the set manifest. Resumes if the set already exists. The output may carry USER QUESTIONS \u2014 defaultsToConfirm (which pose is the component's default) or a multiple-component-sets error (which set to record): render them to a present user and apply the answers via `defaults` / `componentSet`; non-interactive runs follow each question's stated fallback. Recording cost is stated in figmaCallEstimate, never asked about \u2014 proceed with what the user provided.",
     schema: z.object({
       setDir: str("recording set directory to create/resume"),
       component: str("component/system name"),
-      metadataFiles: z.array(z.string()).describe('verbatim get_metadata envelope file paths \u2014 the tool response saved AS-IS, JSON shape {"content":[{"type":"text","text":"<frame \u2026>"}]}; raw copied text is rejected. Optionally <file>@<frameId>'),
+      // Parts array FIRST, same reason as ingest_rep: real responses
+      // are usually multi-block, and the file param made plan the ONE
+      // remaining hand-built-envelope entry point (run 10: the agent
+      // wrote the file twice — once as text, once as JSON envelope).
+      metadataParts: z.array(z.string()).optional().describe("the frame-level get_metadata response blocks, every block in order, each verbatim \u2014 never hand-join or save them yourself; this is the NORMAL param"),
+      metadata: optStr("ONLY when get_metadata genuinely returned one single block: its text verbatim (otherwise use metadataParts)"),
+      metadataFiles: z.array(z.string()).optional().describe('saved verbatim get_metadata envelope file paths \u2014 JSON shape {"content":[{"type":"text","text":"<frame \u2026>"}]}; optionally <file>@<frameId>. Prefer metadataParts: no file to write'),
       defaults: z.array(z.string()).optional().describe(`axis defaults as "Axis=Value" (from the user's defaultsToConfirm answers; may re-plan a set with nothing recorded yet)`),
       componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)")
     }),
-    argv: (i) => [
-      "record",
-      "plan",
-      "--set",
-      i["setDir"],
-      "--component",
-      i["component"],
-      "--metadata",
-      ...i["metadataFiles"],
-      ...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [],
-      ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : []
-    ]
+    // Texts ride temp files, never argv: Windows caps a command line at
+    // ~32 KB and metadata envelopes can exceed it.
+    argv: (i) => {
+      const argvOut = ["record", "plan", "--set", i["setDir"], "--component", i["component"]];
+      if (i["metadata"] !== void 0 && i["metadataParts"] !== void 0) throw new Error("pass at most one of `metadata` and `metadataParts`");
+      const files = i["metadataFiles"];
+      if (files !== void 0 && files.length > 0) argvOut.push("--metadata", ...files);
+      const single = i["metadata"];
+      const parts = i["metadataParts"];
+      if (single !== void 0 || parts !== void 0) {
+        const tmp = path.join(mkdtempSync(path.join(os.tmpdir(), "tendril-envelope-")), "response.txt");
+        if (single !== void 0) {
+          writeFileSync(tmp, single);
+          argvOut.push("--metadata-raw-file", tmp);
+        } else {
+          if (parts.length === 0) throw new Error("`metadataParts` must be a non-empty array of block texts");
+          writeFileSync(tmp, JSON.stringify(parts));
+          argvOut.push("--metadata-raw-parts-file", tmp);
+        }
+      }
+      if (argvOut.length === 6) throw new Error("nothing to plan from \u2014 pass metadataParts (normal), metadata (single-block), or metadataFiles");
+      argvOut.push(...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [], ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : []);
+      return argvOut;
+    }
+  },
+  {
+    name: "tendril_permissions",
+    description: "Install the Claude Code permission allowlist for the Tendril pipeline (write: true \u2014 merges per-tool entries into the project's .claude/settings.local.json, idempotent, never touches other settings), or list the entries without writing. USE THIS when tendril/Figma tool calls keep hitting permission prompts: offer it to the user once \u2014 ONE approval here replaces a prompt per pipeline call (run 8 measured 16+ prompts for a single component's recording). The user must reload the session for new settings to apply.",
+    schema: z.object({
+      write: z.boolean().optional().describe("true = install into .claude/settings.local.json (the point of this tool); false/absent = just return the entries")
+    }),
+    argv: (i) => ["permissions", "--claude", ...i["write"] === true ? ["--write"] : []]
   },
   {
     name: "tendril_doctor",
@@ -81,7 +107,7 @@ var TOOLS = [
       // multi-block (run 6: 49/49 reps — metadata 2 blocks, design
       // context 5-6), so the arrays are the norm and the single-string
       // params the rare case, not the reverse.
-      metadataParts: z.array(z.string()).optional().describe("get_metadata response blocks, every block in order, each verbatim \u2014 never hand-join blocks yourself. Real responses are almost always multi-block; this is the NORMAL param."),
+      metadataParts: z.array(z.string()).optional().describe("get_metadata response blocks, every block in order, each verbatim \u2014 never hand-join blocks yourself. Multi-block responses are common (run 6: 49/49 reps); a single block wrapped in a one-element array is equally fine."),
       contextParts: z.array(z.string()).optional().describe("get_design_context response blocks, every block in order, each verbatim \u2014 the NORMAL param (real responses arrive as 5-6 blocks)"),
       screenshotUrl: optStr("image_url from the get_screenshot response, verbatim \u2014 the CLI downloads it; the bytes never pass through your context"),
       metadata: optStr("ONLY when get_metadata genuinely returned one single block: its text verbatim (otherwise use metadataParts)"),
@@ -241,7 +267,7 @@ var TOOLS = [
   },
   {
     name: "tendril_verify",
-    description: "Verify/check that a component matches its Figma design \u2014 use when the user asks whether an implementation is faithful to the design, or to re-certify an existing Tendril bundle. Recomputes full verification (per-config status, behaviors, composition, evidence artifacts). Free, account-less, network-less \u2014 the trust anchor. Exit 5 means sub-bar with an honest report.",
+    description: "Verify/check that a component matches its Figma design \u2014 use when the user asks whether an implementation is faithful to the design, or to re-certify an existing Tendril bundle. Recomputes full verification (per-config status, behaviors, composition, evidence artifacts). Free, account-less, network-less \u2014 the trust anchor. Exit 5 means below the target bar with an honest report \u2014 sub-bar scores, or at bar cert a config demoted by absent-ink clusters.",
     schema: z.object({
       bundleDir: str("bundle directory to verify"),
       bar: optStr("pass (default) or cert"),
@@ -343,7 +369,7 @@ function toolResult(result) {
   const body = (result.stdout.trim() !== "" ? result.stdout : result.stderr) + stale;
   if (result.exitCode === 5) {
     return { content: [{ type: "text", text: `${body}
-{"exitCode":5,"note":"sub-bar HONEST result \u2014 the report and bundle are valid; this is not a tool failure"}` }] };
+{"exitCode":5,"note":"HONEST below-target result \u2014 the report and bundle are valid; this is not a tool failure. Either sub-bar scores, or (at --bar cert) a config demoted by absent-ink clusters despite at-bar numbers \u2014 the report names which."}` }] };
   }
   const text = result.ok ? body : `${body}
 {"exitCode":${result.exitCode},"note":"CLI exit-code contract: 3 input, 4 confirmation required, 6 fonts unproven, 7 recording incomplete"}`;
@@ -379,7 +405,7 @@ var IMPLEMENT_PROMPT = {
   build: (figmaUrl) => [
     `Implement the Figma component at ${figmaUrl} as a pixel-verified React component using the Tendril pipeline.`,
     "- If the tendril skill (or plugin) is installed, load it and follow it.",
-    "- Otherwise: start at tendril_record_plan; while recording, make exactly the Figma call each tendril_record_next step names (get_metadata comes before any get_design_context) and save responses verbatim; then tendril_engine_brief, implement the candidate, and tendril_engine_score until the bar passes; finish with tendril_verify.",
+    "- Otherwise: start at tendril_record_plan; while recording, make exactly the Figma call each tendril_record_next step names (get_metadata comes before any get_design_context) and pass every response VERBATIM to the ingest tools (no files to save \u2014 the parts params take the response blocks directly); then tendril_engine_brief, implement the candidate, and tendril_engine_score until the bar passes; finish with tendril_verify.",
     "- Verdicts come only from Tendril's scores \u2014 never claim or estimate fidelity numbers yourself."
   ].join("\n")
 };