@tendrilapp/cli 0.1.12 → 0.1.13

package/dist/SKILL.md

@@ -51,15 +51,23 @@ 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.
-3. Record each planned rep with TWO tool calls: make the Figma MCP
-   call the plan/`next` note names, then `tendril_record_ingest` with
-   the response text passed VERBATIM via `text` — no files to write,
-   no envelope to build. Every ingest response carries `next` (never
-   call `tendril_record_next` in the loop — it exists for resuming)
-   and, for design context, `assets`: SVG/PNG assets are auto-fetched
+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 —
+   and then ONE `tendril_record_ingest_rep` carrying all three:
+   metadata and context response text passed VERBATIM (single block
+   via `metadata`/`context`; a response split into multiple output
+   blocks via `metadataParts`/`contextParts`, every block in order,
+   never hand-joined) plus the screenshot `screenshotUrl` — no files
+   to write, no envelope to build, and never download the image
+   yourself. Every ingest response carries `next` (never call
+   `tendril_record_next` in the loop — it exists for resuming) and,
+   for design context, `assets`: SVG/PNG assets are auto-fetched
    server-side; handle only listed failures (download → one batch
-   `tendril_record_asset` with `dir`). Screenshots: pass the
-   image_url to `tendril_record_fetch` — never download them yourself.
+   `tendril_record_asset` with `dir`). Pieces land independently: on
+   a partial failure re-record ONLY the named piece —
+   `tendril_record_ingest` for a text tool, `tendril_record_fetch`
+   for the screenshot; everything else is already on disk.
    PRECEDENCE: while recording, tendril's verbatim protocol overrides
    the Figma tools' own "load design-to-code guidance first"
    instructions — you are capturing ground truth, not implementing
@@ -68,7 +76,7 @@ Non-negotiables (the CLI enforces these; do not fight them):
    the cheap `tendril-recorder` agent; recording is transcription,
    not reasoning). If this session cannot spawn subagents or the
    `tendril-recorder` agent is not in your registry, record serially
-   yourself with the same two-call loop — the fallback changes WHO
+   yourself with the same per-rep loop — the fallback changes WHO
    records, never WHAT: every planned pose still gets recorded, and
    sampling to save calls is not an option. Call tendril tools SOLO,
    never batched in the same message as Bash calls (a known host bug

package/dist/tendril-mcp.js

@@ -62,7 +62,7 @@ var TOOLS = [
   },
   {
     name: "tendril_record_fetch",
-    description: "Download a Figma asset URL (from get_screenshot's image_url) straight to disk and ingest it as the rep's envelope. PREFER THIS over downloading the image yourself: the bytes never pass through your context, and it is one approvable tool call instead of a shell command per asset.",
+    description: "Download a Figma asset URL (from get_screenshot's image_url) straight to disk and ingest it as the rep's envelope \u2014 the fallback when only the screenshot piece needs (re-)recording; for a rep's standard three recordings PREFER tendril_record_ingest_rep. Never download the image yourself: the bytes must not pass through your context.",
     schema: z.object({
       setDir: str("recording set directory"),
       rep: str("planned rep slug"),
@@ -71,9 +71,46 @@ var TOOLS = [
     }),
     argv: (i) => ["record", "fetch", "--set", i["setDir"], "--rep", i["rep"], "--tool", i["tool"], "--url", i["url"]]
   },
+  {
+    name: "tendril_record_ingest_rep",
+    description: "Ingest a rep's ENTIRE recording in ONE call \u2014 the get_metadata response, the get_design_context response, and the get_screenshot image_url together. Make the three Figma calls first, in protocol order (get_metadata, then get_design_context with excludeScreenshot=true, then get_screenshot), then pass all three here VERBATIM. PREFER THIS over three separate ingest/fetch calls: one approvable operation per rep instead of three. Pieces land independently: on a partial failure the error names exactly which piece(s) to re-record \u2014 the rest are already on disk. The response carries `next` and, for design context, `assets` (auto-fetched server-side; only listed failures need record_asset).",
+    schema: z.object({
+      setDir: str("recording set directory"),
+      rep: str("planned rep slug"),
+      metadata: optStr("get_metadata response text VERBATIM (single block)"),
+      metadataParts: z.array(z.string()).optional().describe("get_metadata response as MULTIPLE output blocks: every block, in order, each verbatim \u2014 never hand-join blocks yourself"),
+      context: optStr("get_design_context response text VERBATIM (single block)"),
+      contextParts: z.array(z.string()).optional().describe("get_design_context response as MULTIPLE output blocks, in order, each verbatim"),
+      screenshotUrl: optStr("image_url from the get_screenshot response, verbatim \u2014 the CLI downloads it; the bytes never pass through your context")
+    }),
+    // Texts ride temp files, never argv: Windows caps a command line at
+    // ~32 KB and design-context envelopes routinely exceed it.
+    argv: (i) => {
+      const argvOut = ["record", "ingest-rep", "--set", i["setDir"], "--rep", i["rep"]];
+      const bridge = (label, single, parts) => {
+        if (single !== void 0 && parts !== void 0) throw new Error(`pass at most one of \`${label}\` and \`${label}Parts\``);
+        if (single === void 0 && parts === void 0) return;
+        const tmp = path.join(mkdtempSync(path.join(os.tmpdir(), "tendril-envelope-")), "response.txt");
+        if (single !== void 0) {
+          writeFileSync(tmp, single);
+          argvOut.push(`--${label}-file`, tmp);
+        } else {
+          const blocks = parts;
+          if (blocks.length === 0) throw new Error(`\`${label}Parts\` must be a non-empty array of block texts`);
+          writeFileSync(tmp, JSON.stringify(blocks));
+          argvOut.push(`--${label}-parts-file`, tmp);
+        }
+      };
+      bridge("metadata", i["metadata"], i["metadataParts"]);
+      bridge("context", i["context"], i["contextParts"]);
+      if (i["screenshotUrl"] !== void 0) argvOut.push("--screenshot-url", i["screenshotUrl"]);
+      if (argvOut.length === 6) throw new Error("nothing to ingest \u2014 pass at least one of metadata/metadataParts, context/contextParts, screenshotUrl");
+      return argvOut;
+    }
+  },
   {
     name: "tendril_record_ingest",
-    description: "Ingest a VERBATIM Figma tool-response for a planned rep. PREFER `text` (single block) or `texts` (response split into multiple output blocks \u2014 pass each block verbatim, in order; NEVER hand-join them): no file to write, no wrapper to build; the CLI constructs the envelope from the same bytes. The response includes `next` (the following instruction \u2014 no separate record_next call) and, for get_design_context, `assets`: the emission's SVG/PNG assets are AUTO-FETCHED server-side; only listed failures need manual record_fetch/record_asset handling.",
+    description: "Single-piece ingest of a VERBATIM Figma tool-response \u2014 the fallback path (re-recording one failed piece, set-level get_variable_defs, get_metadata_interior for mains); for a rep's standard three recordings PREFER tendril_record_ingest_rep, which takes them all in one call. Pass `text` (single block) or `texts` (response split into multiple output blocks \u2014 each block verbatim, in order; NEVER hand-join them): the CLI constructs the envelope from the same bytes. The response includes `next` and, for get_design_context, `assets` (auto-fetched; only listed failures need manual handling).",
     schema: z.object({
       setDir: str("recording set directory"),
       rep: str("planned rep slug, or __set__ for the set-level get_variable_defs"),

package/dist/tendril.js

@@ -6276,6 +6276,7 @@ __export(record_exports, {
   runRecordFetch: () => runRecordFetch,
   runRecordFinish: () => runRecordFinish,
   runRecordIngest: () => runRecordIngest,
+  runRecordIngestRep: () => runRecordIngestRep,
   runRecordNext: () => runRecordNext,
   runRecordPlan: () => runRecordPlan,
   runRecordStatus: () => runRecordStatus
@@ -6521,46 +6522,37 @@ async function fetchAssetBytes(startUrl, allowed) {
   if (!res.ok) throw new Error(`HTTP ${res.status}`);
   return Buffer.from(await res.arrayBuffer());
 }
-async function runRecordFetch(opts) {
-  if (!isFigmaAssetUrl(opts.url)) {
-    fail(opts, ExitCode.InputValidation, {
-      error: `refusing to fetch a non-Figma URL: ${opts.url}`,
-      code: "asset-url-rejected",
-      remediation: "Pass the image_url from the get_screenshot response verbatim."
-    });
+async function ingestScreenshotFromUrl(setDir, rep, url) {
+  if (!isFigmaAssetUrl(url)) {
+    return { ok: false, code: "asset-url-rejected", error: `refusing to fetch a non-Figma URL: ${url}`, remediation: "Pass the image_url from the get_screenshot response verbatim." };
   }
   let bytes;
   try {
-    bytes = await fetchAssetBytes(opts.url, isFigmaAssetUrl);
+    bytes = await fetchAssetBytes(url, isFigmaAssetUrl);
   } catch (err) {
-    fail(opts, ExitCode.InputValidation, {
-      error: `asset fetch failed: ${err instanceof Error ? err.message : String(err)}`,
-      code: "asset-fetch-failed",
-      remediation: "Figma asset URLs expire after 7 days \u2014 re-run the Figma tool for a fresh URL."
-    });
+    return { ok: false, code: "asset-fetch-failed", error: `asset fetch failed: ${err instanceof Error ? err.message : String(err)}`, remediation: "Figma asset URLs expire after 7 days \u2014 re-run the Figma tool for a fresh URL." };
   }
   if (!(bytes.length > 8 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71)) {
-    fail(opts, ExitCode.InputValidation, {
-      error: `fetched ${bytes.length} bytes that are not a PNG (expired URL usually returns HTML)`,
-      code: "asset-not-png",
-      remediation: "Re-run get_screenshot for a fresh URL and fetch again."
-    });
+    return { ok: false, code: "asset-not-png", error: `fetched ${bytes.length} bytes that are not a PNG (expired URL usually returns HTML)`, remediation: "Re-run get_screenshot for a fresh URL and fetch again." };
   }
   const payload = { content: [{ type: "image", data: bytes.toString("base64"), mimeType: "image/png" }] };
   try {
-    const { overwrote } = ingestEnvelope(opts.setDir, opts.rep, opts.tool, payload);
-    emitData(opts, { rep: opts.rep, tool: opts.tool, bytes: bytes.length, overwrote, source: "cli-fetch", next: nextPayload(opts.setDir) }, () => {
-      process.stdout.write(`fetched + ingested ${opts.rep}/${opts.tool} (${bytes.length} bytes, no model in the byte path)
-`);
-    });
+    const { overwrote } = ingestEnvelope(setDir, rep, "get_screenshot", payload);
+    return { ok: true, bytes: bytes.length, overwrote };
   } catch (err) {
-    fail(opts, ExitCode.InputValidation, {
-      error: `envelope rejected: ${err instanceof Error ? err.message : String(err)}`,
-      code: "envelope-invalid",
-      remediation: "Check the rep slug is planned in this set."
-    });
+    return { ok: false, code: "envelope-invalid", error: `envelope rejected: ${err instanceof Error ? err.message : String(err)}`, remediation: "Check the rep slug is planned in this set." };
   }
 }
+async function runRecordFetch(opts) {
+  const result = await ingestScreenshotFromUrl(opts.setDir, opts.rep, opts.url);
+  if (!result.ok) {
+    fail(opts, ExitCode.InputValidation, { error: result.error, code: result.code, remediation: result.remediation });
+  }
+  emitData(opts, { rep: opts.rep, tool: opts.tool, bytes: result.bytes, overwrote: result.overwrote, source: "cli-fetch", next: nextPayload(opts.setDir) }, () => {
+    process.stdout.write(`fetched + ingested ${opts.rep}/${opts.tool} (${result.bytes} bytes, no model in the byte path)
+`);
+  });
+}
 async function autoFetchAssets(setDir, rep, envelopeText2) {
   const fetched = [];
   const skipped = [];
@@ -6586,16 +6578,18 @@ async function autoFetchAssets(setDir, rep, envelopeText2) {
   }
   return { fetched, skipped, failed };
 }
+function rawEnvelopeFromFile(file, parts) {
+  if (parts) {
+    const blocks = JSON.parse(readFileSync15(path24.resolve(file), "utf8"));
+    if (!Array.isArray(blocks) || blocks.length === 0 || blocks.some((p) => typeof p !== "string")) throw new Error("parts file must be a non-empty JSON array of strings");
+    return { content: blocks.map((text) => ({ type: "text", text })) };
+  }
+  return { content: [{ type: "text", text: readFileSync15(path24.resolve(file), "utf8") }] };
+}
 async function runRecordIngest(opts) {
   let payload;
   try {
-    if (opts.rawParts === true) {
-      const parts = JSON.parse(readFileSync15(path24.resolve(opts.file), "utf8"));
-      if (!Array.isArray(parts) || parts.length === 0 || parts.some((p) => typeof p !== "string")) throw new Error("--raw-parts file must be a non-empty JSON array of strings");
-      payload = { content: parts.map((text) => ({ type: "text", text })) };
-    } else {
-      payload = opts.raw === true ? { content: [{ type: "text", text: readFileSync15(path24.resolve(opts.file), "utf8") }] } : JSON.parse(readFileSync15(path24.resolve(opts.file), "utf8"));
-    }
+    payload = opts.rawParts === true || opts.raw === true ? rawEnvelopeFromFile(opts.file, opts.rawParts === true) : JSON.parse(readFileSync15(path24.resolve(opts.file), "utf8"));
   } catch (err) {
     fail(opts, ExitCode.InputValidation, {
       error: `cannot read envelope file: ${err instanceof Error ? err.message : String(err)}`,
@@ -6647,6 +6641,72 @@ async function runRecordIngest(opts) {
     });
   }
 }
+async function runRecordIngestRep(opts) {
+  const validate = (label, single, parts) => {
+    if (single !== void 0 && parts !== void 0) {
+      fail(opts, ExitCode.InputValidation, {
+        error: `pass at most one of --${label}-file and --${label}-parts-file`,
+        code: "ingest-rep-args",
+        remediation: `Single-block responses go in --${label}-file; multi-block responses as a JSON string array in --${label}-parts-file.`
+      });
+    }
+  };
+  validate("metadata", opts.metadataFile, opts.metadataPartsFile);
+  validate("context", opts.contextFile, opts.contextPartsFile);
+  const metaFile = opts.metadataPartsFile ?? opts.metadataFile;
+  const ctxFile = opts.contextPartsFile ?? opts.contextFile;
+  if (metaFile === void 0 && ctxFile === void 0 && opts.screenshotUrl === void 0) {
+    fail(opts, ExitCode.InputValidation, {
+      error: "nothing to ingest \u2014 pass at least one piece",
+      code: "ingest-rep-args",
+      remediation: "Provide --metadata-file/--metadata-parts-file, --context-file/--context-parts-file, and/or --screenshot-url."
+    });
+  }
+  const pieces = {};
+  const failed = [];
+  if (metaFile !== void 0) {
+    try {
+      const { overwrote } = ingestEnvelope(opts.setDir, opts.rep, "get_metadata", rawEnvelopeFromFile(metaFile, opts.metadataPartsFile !== void 0));
+      pieces["metadata"] = { overwrote };
+    } catch (err) {
+      failed.push({ piece: "get_metadata", error: err instanceof Error ? err.message : String(err), remediation: "Re-record the get_metadata response verbatim and re-ingest just this piece (tendril_record_ingest)." });
+    }
+  }
+  if (ctxFile !== void 0) {
+    try {
+      const envelope = rawEnvelopeFromFile(ctxFile, opts.contextPartsFile !== void 0);
+      const { overwrote } = ingestEnvelope(opts.setDir, opts.rep, "get_design_context", envelope);
+      const assets = await autoFetchAssets(opts.setDir, opts.rep, envelope.content.map((c) => c.text ?? "").join("\n"));
+      pieces["context"] = { overwrote, assets };
+    } catch (err) {
+      failed.push({ piece: "get_design_context", error: err instanceof Error ? err.message : String(err), remediation: "Re-record the get_design_context response verbatim and re-ingest just this piece (tendril_record_ingest)." });
+    }
+  }
+  if (opts.screenshotUrl !== void 0) {
+    const shot = await ingestScreenshotFromUrl(opts.setDir, opts.rep, opts.screenshotUrl);
+    if (shot.ok) pieces["screenshot"] = { bytes: shot.bytes, overwrote: shot.overwrote };
+    else failed.push({ piece: "get_screenshot", error: shot.error, remediation: `${shot.remediation} Then re-ingest just this piece with tendril_record_fetch (\`record fetch\`).` });
+  }
+  if (failed.length > 0) {
+    const landed = Object.keys(pieces);
+    fail(opts, ExitCode.InputValidation, {
+      error: `ingest-rep ${opts.rep}: ${failed.map((f) => `${f.piece} FAILED (${f.error})`).join("; ")}${landed.length > 0 ? ` \u2014 recorded ok: ${landed.join(", ")}` : ""}`,
+      code: "ingest-rep-partial",
+      remediation: `Only the failed piece(s) need re-recording. ${failed.map((f) => `${f.piece}: ${f.remediation}`).join(" ")}`
+    });
+  }
+  emitData(opts, { rep: opts.rep, ...pieces, next: nextPayload(opts.setDir) }, () => {
+    process.stdout.write(`ingested ${opts.rep}: ${Object.keys(pieces).join(" + ")}
+`);
+    const assets = pieces["context"]?.assets;
+    if (assets !== void 0) {
+      for (const a of assets.fetched) process.stdout.write(`  asset fetched ${a}
+`);
+      for (const f of assets.failed) process.stdout.write(`  ASSET FAILED ${f.name}: ${f.reason} \u2014 download it and run tendril record asset
+`);
+    }
+  });
+}
 function runRecordAsset(opts) {
   if (opts.dir !== void 0) {
     const dir = path24.resolve(opts.dir);
@@ -10402,6 +10462,21 @@ function buildProgram() {
     const { runRecordIngest: runRecordIngest2 } = await Promise.resolve().then(() => (init_record(), record_exports));
     await runRecordIngest2({ ...flags, setDir: local["set"], rep: local["rep"], tool: local["tool"], file: local["file"], raw: local["raw"], rawParts: local["rawParts"] });
   });
+  record.command("ingest-rep").description("Batched per-rep ingest: metadata + design context + screenshot URL in one call; pieces land independently.").requiredOption("--set <dir>", "recording set directory").requiredOption("--rep <slug>", "planned rep slug").option("--metadata-file <file>", "get_metadata response TEXT verbatim").option("--metadata-parts-file <file>", "get_metadata response as a JSON array of block texts (multi-block transport)").option("--context-file <file>", "get_design_context response TEXT verbatim").option("--context-parts-file <file>", "get_design_context response as a JSON array of block texts").option("--screenshot-url <url>", "image_url from the get_screenshot response, verbatim").action(async (_o, cmd) => {
+    const flags = globalFlags(cmd.parent.parent);
+    const local = cmd.opts();
+    const { runRecordIngestRep: runRecordIngestRep2 } = await Promise.resolve().then(() => (init_record(), record_exports));
+    await runRecordIngestRep2({
+      ...flags,
+      setDir: local["set"],
+      rep: local["rep"],
+      metadataFile: local["metadataFile"],
+      metadataPartsFile: local["metadataPartsFile"],
+      contextFile: local["contextFile"],
+      contextPartsFile: local["contextPartsFile"],
+      screenshotUrl: local["screenshotUrl"]
+    });
+  });
   record.command("fetch").description("Download a Figma asset URL straight to disk and ingest it \u2014 no shell, no model in the byte path.").requiredOption("--set <dir>", "recording set directory").requiredOption("--rep <slug>", "planned rep slug").requiredOption("--tool <tool>", "get_screenshot").requiredOption("--url <url>", "image_url from the Figma tool response, verbatim").action(async (_o, cmd) => {
     const flags = globalFlags(cmd.parent.parent);
     const local = cmd.opts();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tendrilapp/cli",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Figma design systems → verified React components. CLI ruler + MCP server.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",