@tendrilapp/cli 0.1.30 → 0.1.31

package/dist/SKILL.md

@@ -131,7 +131,12 @@ Batch runs (several components in one session):
 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
+   to a file, and never hand-join blocks), AND `figmaFile` set to the
+   file key from the URL you were handed (figma.com/design/<KEY>/… —
+   pass exactly KEY): it is recorded as the set's file identity for
+   cross-bundle composition, captured at plan time only and never
+   backfillable — a set planned without it can never join across
+   bundles → 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

package/dist/tendril-mcp.js

@@ -37,7 +37,8 @@ var TOOLS = [
       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)")
+      componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)"),
+      figmaFile: optStr("the Figma file key from the design URL you were handed \u2014 figma.com/design/<KEY>/\u2026, pass exactly <KEY>. ALWAYS pass it on a fresh plan: it is the set's recorded file identity for cross-bundle composition (ADR-013), captured at plan time only and never backfillable later")
     }),
     // Texts ride temp files, never argv: Windows caps a command line at
     // ~32 KB and metadata envelopes can exceed it.
@@ -60,7 +61,11 @@ var TOOLS = [
         }
       }
       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"]] : []);
+      argvOut.push(
+        ...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [],
+        ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : [],
+        ...typeof i["figmaFile"] === "string" ? ["--figma-file", i["figmaFile"]] : []
+      );
       return argvOut;
     }
   },

package/dist/tendril.js

@@ -1069,6 +1069,9 @@ function planSet(setDir, component, symbols, opts = {}) {
   const manifest = {
     version: 1,
     component,
+    ...opts.figmaFile !== void 0 ? { figmaFile: opts.figmaFile } : {},
+    ...opts.componentSetNode !== void 0 ? { componentSetNode: opts.componentSetNode } : {},
+    ...opts.figmaComponentName !== void 0 ? { figmaComponentName: opts.figmaComponentName } : {},
     ...opts.sourceFrames !== void 0 ? { sourceFrames: opts.sourceFrames } : {},
     ...opts.variantScope !== void 0 ? { variantScope: opts.variantScope } : {},
     ...opts.defaults !== void 0 && Object.keys(opts.defaults).length > 0 ? { defaults: opts.defaults } : {},
@@ -1215,8 +1218,27 @@ var init_session = __esm({
     SessionManifestSchema = z4.object({
       version: z4.literal(1),
       component: z4.string().min(1),
+      /** ADR-013 slice 1 (v4, capture-only): cross-set identity, captured
+       * at RECORD TIME on fresh plans only — NEVER backfilled (the
+       * recording-set hash covers this file's bytes, so adding fields to
+       * a set that already produced bundles voids their provenance).
+       * `figmaFile` is the Figma file key from the URL the agent host was
+       * handed — an AGENT ASSERTION, disclosed, never enforcement-bearing
+       * alone (ADR-013 §1). `componentSetNode`/`figmaComponentName` are
+       * the enclosing set's id and Figma-side name as the planner's own
+       * metadata parse saw them — the identity that stops a re-recording
+       * of the same component from reading as a different one (`component`
+       * below is the plan-time DISPLAY name; the measured case recorded
+       * one control as "Lucent Control (Dark)" and "control"). All
+       * optional: legacy sets simply cannot join, disclosed. */
+      figmaFile: z4.string().regex(/^[A-Za-z0-9]{8,64}$/).optional(),
+      componentSetNode: z4.string().optional(),
+      figmaComponentName: z4.string().optional(),
       sourceFrames: z4.record(z4.string(), z4.string()).optional(),
-      reps: z4.array(z4.object({ slug: z4.string(), nodeId: z4.string(), sourceFrame: z4.string().optional() })).min(1),
+      /** Per-rep `componentKey` is SEEDED (ADR-013 v4: the one-call MCP
+       * probe decides whether anything can ever fill it) so interim sets
+       * are not born cross-file-dead if keys turn out to be available. */
+      reps: z4.array(z4.object({ slug: z4.string(), nodeId: z4.string(), sourceFrame: z4.string().optional(), componentKey: z4.string().optional() })).min(1),
       notRecorded: z4.string().optional(),
       /** Explicit axis-default overrides from `record plan --default`.
        * Recorded-truth-side on purpose: the default decides which pose an
@@ -7873,10 +7895,10 @@ function symbolsFromMetadataEnvelope(file, sourceFrame) {
         nodeId: node.id,
         name: node.name,
         ...sourceFrame !== void 0 ? { sourceFrame } : {},
-        ...ancestor !== void 0 ? { setName: ancestor } : {}
+        ...ancestor !== void 0 ? { setName: ancestor.name, setNodeId: ancestor.id } : {}
       });
     }
-    const next = node.type !== "COMPONENT" && node.name !== "" ? node.name : ancestor;
+    const next = node.type !== "COMPONENT" && node.name !== "" ? { name: node.name, id: node.id } : ancestor;
     for (const child of node.children) walk2(child, next);
   };
   const forest = parseMetadataForest(text);
@@ -8014,10 +8036,25 @@ function runRecordPlan(opts) {
   if (metadataTruncated) {
     warn(opts, "get_metadata response appears TRUNCATED (unclosed structure) \u2014 the variant list below may be incomplete. Cross-check variantsFound against the variant count Figma shows for this component set; re-fetch the metadata if lower.");
   }
+  if (opts.figmaFile !== void 0 && !/^[A-Za-z0-9]{8,64}$/.test(opts.figmaFile)) {
+    fail(opts, ExitCode.InputValidation, {
+      error: `--figma-file must be the bare file key from the Figma URL (letters and digits only) \u2014 got ${JSON.stringify(opts.figmaFile)}`,
+      code: "bad-figma-file",
+      remediation: "From https://www.figma.com/design/<KEY>/<name>?node-id=\u2026, pass exactly <KEY>."
+    });
+  }
+  const setIdentity = (() => {
+    if (variantScope !== "component-set") return {};
+    const ids = [...new Set(symbols.map((s) => s.setNodeId).filter((x) => x !== void 0))];
+    const names = [...new Set(symbols.map((s) => s.setName).filter((x) => x !== void 0))];
+    return ids.length === 1 && names.length === 1 ? { componentSetNode: ids[0], figmaComponentName: names[0] } : {};
+  })();
   const { manifest, plan, resumed, toppedUp } = planSet(opts.setDir, opts.component, symbols, {
     ...Object.keys(defaults).length > 0 ? { defaults } : {},
     ...opts.sample === true ? { sample: true } : {},
-    variantScope
+    variantScope,
+    ...opts.figmaFile !== void 0 ? { figmaFile: opts.figmaFile } : {},
+    ...setIdentity
   });
   const defaultReports = reportAxisDefaults(symbols, Object.keys(defaults).length > 0 ? defaults : void 0);
   const toConfirm = resumed ? [] : defaultReports.filter((r) => (r.rule === "non-interaction" || r.rule === "frequency") && r.domain.length > 1);
@@ -12230,7 +12267,8 @@ var init_server = __esm({
           metadata: optStr("ONLY when get_metadata genuinely returned one single block: its text verbatim (otherwise use metadataParts)"),
           metadataFiles: z12.array(z12.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: z12.array(z12.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)")
+          componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)"),
+          figmaFile: optStr("the Figma file key from the design URL you were handed \u2014 figma.com/design/<KEY>/\u2026, pass exactly <KEY>. ALWAYS pass it on a fresh plan: it is the set's recorded file identity for cross-bundle composition (ADR-013), captured at plan time only and never backfillable later")
         }),
         // Texts ride temp files, never argv: Windows caps a command line at
         // ~32 KB and metadata envelopes can exceed it.
@@ -12253,7 +12291,11 @@ var init_server = __esm({
             }
           }
           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"]] : []);
+          argvOut.push(
+            ...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [],
+            ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : [],
+            ...typeof i["figmaFile"] === "string" ? ["--figma-file", i["figmaFile"]] : []
+          );
           return argvOut;
         }
       },
@@ -14073,7 +14115,7 @@ function buildProgram() {
     await runActivate2({ ...flags, serviceUrl: local["serviceUrl"] });
   });
   const record = program.command("record").description("Agent-driven recording protocol: plan the queue, get instructions, ingest verbatim envelopes, resume from disk.");
-  record.command("plan").requiredOption("--set <dir>", "recording set directory").requiredOption("--component <name>", "component/system name").option("--metadata <file...>", "verbatim get_metadata envelope(s), optionally <file>@<frameId>").option("--metadata-raw-file <file>", "the get_metadata response TEXT exactly as received (single block); the CLI builds the envelope itself").option("--metadata-raw-parts-file <file>", "a JSON array of the get_metadata response blocks, each verbatim, in order (multi-block responses)").option("--default <axis=value...>", "explicit axis default, e.g. --default State=Rest (repeatable; persisted to the manifest; may re-plan an unrecorded set)").option("--component-set <name>", "when the metadata holds several component sets, record only this one (name = the set label in the plan error)").option("--sample", "cost sampling: anchor + one-factor + conflict crosses only (the FULL variant matrix is the default; sampling is blind to multi-axis interactions)").action(async (_o, cmd) => {
+  record.command("plan").requiredOption("--set <dir>", "recording set directory").requiredOption("--component <name>", "component/system name").option("--metadata <file...>", "verbatim get_metadata envelope(s), optionally <file>@<frameId>").option("--metadata-raw-file <file>", "the get_metadata response TEXT exactly as received (single block); the CLI builds the envelope itself").option("--metadata-raw-parts-file <file>", "a JSON array of the get_metadata response blocks, each verbatim, in order (multi-block responses)").option("--default <axis=value...>", "explicit axis default, e.g. --default State=Rest (repeatable; persisted to the manifest; may re-plan an unrecorded set)").option("--component-set <name>", "when the metadata holds several component sets, record only this one (name = the set label in the plan error)").option("--sample", "cost sampling: anchor + one-factor + conflict crosses only (the FULL variant matrix is the default; sampling is blind to multi-axis interactions)").option("--figma-file <key>", "the Figma file key from the design URL (figma.com/design/<KEY>/\u2026) \u2014 recorded as the set's file identity for cross-bundle composition (ADR-013; fresh plans only, never backfilled)").action(async (_o, cmd) => {
     const flags = globalFlags(cmd.parent.parent);
     const local = cmd.opts();
     const { runRecordPlan: runRecordPlan2 } = await Promise.resolve().then(() => (init_record(), record_exports));
@@ -14082,6 +14124,7 @@ function buildProgram() {
       setDir: local["set"],
       component: local["component"],
       sample: local["sample"],
+      ...local["figmaFile"] !== void 0 ? { figmaFile: local["figmaFile"] } : {},
       ...local["metadata"] !== void 0 ? { metadataFiles: local["metadata"] } : {},
       ...local["metadataRawFile"] !== void 0 ? { metadataRawFile: local["metadataRawFile"] } : {},
       ...local["metadataRawPartsFile"] !== void 0 ? { metadataRawPartsFile: local["metadataRawPartsFile"] } : {},

package/package.json

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