@tendrilapp/cli 0.1.48 → 0.1.50

package/dist/SKILL.md

@@ -254,15 +254,52 @@ Batch runs (several components in one session):
    lists unconfirmed partner pairs, this recording references OTHER
    recorded components (a segmented control built from a recorded
    Control, a dialog holding a recorded Button). Order matters:
-   generate the PARTNER bundle first, then show the pairing to the
-   user — a human decides it by running
+   generate the PARTNER bundle first, then put the pairing decision in
+   front of the human — it is human-only on either channel, and you
+   can never make it. CLICK PATH (lead with this): `tendril_compose`
+   puts the pairing in their browser as an Approve card (sign in first
+   via `tendril_login` if needed — one browser Approve each); relay
+   the approve link VERBATIM, name the account the result says to
+   approve as, never urge, then loop `tendril_compose_wait` (same
+   heartbeat contract as publish waits: pending is a heartbeat, one
+   short liveness line, never "stuck"). The card's Deny is NOT NOW —
+   this request only, never a permanent decline. TERMINAL PATH: the
+   human runs
    `npx -y -p @tendrilapp/cli@latest tendril compose --set <host-set-dir>`
-   in their own terminal (confirm or `--decline <pair-key>`; the
-   pair-key is printed above each pair). Never confirm it yourself.
+   themselves (confirm or `--decline <pair-key>`; decline there IS
+   permanent — asked once). Never confirm on either channel yourself.
    Generating the host with pairs undecided is valid — the brief will
    say so — but the host then re-implements the partner's pixels
    locally instead of composing the verified partner bundle, so
    surface the choice before you spend the rounds.
+   Discovery only sees recording sets in the SCANNED roots: the set's
+   parent directory by default (bounded), or `--library <dir>`. Sets
+   in another project root are invisible to pairing until co-located
+   or pointed at — the tools name their scanned roots so "not
+   scanned" never reads as "no relationship".
+   CONNECTING COMPONENTS THAT ALREADY EXIST (both recorded, both
+   generated): step ONE is putting both recording sets in one scanned
+   root (co-locate, or --library). If the pairing then shows as
+   NAME-ONLY (the host was recorded over MCP, so Figma's instance→
+   component bindings were never captured), run
+   `tendril_record_bindings` on the HOST set — one or two batched
+   REST calls, congruence-verified, no re-recording; needs the Figma
+   connect — if absent, that is ONE more browser Allow via
+   `tendril_figma_connect`, name it up front so it never reads as a
+   detour — and the pairing becomes id-backed and confirmable. Then
+   the click path above (tendril_compose → Approve →
+   tendril_compose_wait). After the approve: the HOST bundle is
+   REGENERATED with the same --library roots (a verified bundle is
+   frozen — composition never retrofits one; the partner bundle is
+   reused verbatim). That regeneration is a normal generation run:
+   ask the model question there as always, and set the expectation in
+   one line that it takes a few scored attempts. If the regenerated
+   host was ALREADY published, the republish completes in one
+   announced call; if it was NEVER published, a SECOND, different
+   browser card appears — the publish approval — say so before it
+   does. On session resume, a pending connect decision may be waiting:
+   if `pending-compose.json` exists under the user config dir, run
+   `tendril_compose_wait` first.
 
 ## Generating (the agent-harness engine — you are the proposer)
 
@@ -388,15 +425,25 @@ on disk — or `null` where a scoring path produced a score with no
 pixels, which is a real outcome and not a bug.
 
 The verdict, the pixels and the diff-colour legend join into one offline
-sheet at `verify-evidence/inspect.html`. That sheet comes from the CLI
-and has no MCP tool of its own, so OFFER to run
-`npx @tendrilapp/cli inspect <bundle-dir>` rather than asking the user
-to type it, and say what it produces before you run it.
+sheet at `verify-evidence/inspect.html`. A GREEN verify writes that
+sheet itself (the report's `eyeCheck.sheetBuilt` says so) — report its
+path, never ask whether to produce it. After a FAILED verify, run
+`npx @tendrilapp/cli inspect <bundle-dir>` yourself before diagnosing:
+the sheet is free, offline and account-less, so no cost or risk exists
+that would justify a prompt in front of it. Note the ORDER — `inspect`
+reads the evidence a `verify` run wrote, so it runs after `verify`,
+never before.
 
 Point the user at that sheet, not at terminal scrollback: a verdict
 nobody can re-read beside the evidence it describes cannot be handed to
-anyone. Note the ORDER — `inspect` writes crops into the evidence
-directory it documents, so run it after `verify`, never before.
+anyone.
+
+Verdict caveats and coverage lines (`INCOMPLETE`, `PIXEL-ONLY`,
+`coverage-denominator-unknown`, `composition-not-checked`) are
+DISCLOSURES, not questions: nothing is blocked and no answer is
+required. State them as plain findings in your final report — never
+convert one into an options dialog. A verified run's happy path has
+ZERO questions.
 
 NEVER re-score a bundle against a DIFFERENT recording set than the one
 it is bound to — scoring rewrites the bundle's verification identity
@@ -408,13 +455,74 @@ denominator — if it prints INCOMPLETE with unrecorded poses, the
 component is not done: record the missing poses (re-running plan tops
 up sets recorded under the old sampled default).
 
+## Publishing — the terminal step of a green run
+
+A verified component's value lands when it is LIVE. This is an
+invariant, not a preference: every run that reaches a green verify ends
+with the user holding the live portal URL — or, if the first-publish
+approval is still pending, unmistakably looking at the approve action.
+No success path terminates with the component reachable only on local
+disk. Do not ask permission to enter this sequence — the human gate is
+the browser approval itself, which only the user can give and which no
+machine token can fake.
+
+The terminal sequence on green: `verify` → the inspect sheet (written
+automatically) → `tendril_publish` → surface what it returns:
+
+- `status: "approval-pending"` (a component's FIRST publish): relay the
+  `approveUrl` VERBATIM and name the `approveAsAccount` it carries —
+  state the account explicitly even when it looks obvious, because the
+  approving browser can be signed in to a different account than this
+  session runs under, and a mismatch strands the user on an empty
+  approve page. Do not urge them to approve: approving includes
+  accepting the design system's publishing terms, and that is their
+  decision to read and make.
+- Then `tendril_publish_wait`, in a loop: each call waits about a
+  minute and returns either the outcome or `approval-pending` again.
+  A pending return is a HEARTBEAT, not a failure — keep calling while
+  `remainingSeconds` says the request is live, relaying a brief
+  liveness line roughly every few minutes (each return carries
+  `waitedTotalSeconds`/`remainingSeconds`; you need not narrate every
+  heartbeat). Never describe an in-flight or pending wait as stuck —
+  a decided approval continues straight into upload and commit inside
+  the same call, which can take minutes with no visible progress —
+  and never abandon the loop while the request is live unless the
+  user redirects you. A denial, a lapse and success each arrive as
+  their own sentence — report the one you got.
+- A re-publish of an already-published component completes in one call,
+  no approval round trip — so it has NO browser gate. Announce in one
+  line what is about to go live BEFORE the call ("publishing the
+  updated Checkbox to your portal"); that line is the human-visible
+  moment for a step no click will confirm.
+- Not signed in? Surface `tendril_login` first — the sequence pauses at
+  sign-in; it never silently skips publishing.
+
+Sub-bar runs do NOT publish — the CLI refuses a declined run, and the
+honest failure report is that run's correct terminal state. The
+invariant is scoped to success.
+
+Make the finish legible: the FIRST line of your final report is "done —
+live at <URL>" (or "done — waiting for your Approve at <link>, as
+<account>"), before scores, caveats and file lists. The user should
+never have to ask where their component is.
+
+A green verify may also print COMPOSE lines: other recorded components
+that embed the one just verified. Relay them after the done-line as
+DISCLOSURES (zero questions — the confirm decision is human-only, in
+the user's terminal, with the exact commands the lines already carry),
+and never confirm or decline a pairing yourself.
+
 ## Code Connect (extra value, after verify passes)
 
 `tendril_codeconnect` emits a Figma Code Connect template (.figma.ts)
 for a certified bundle: every Figma variant value mapped to its
-verified prop fragment, stamped with the trust statement. Offer it
-when the user's team is on a Figma Organization/Enterprise plan (Code
-Connect is unavailable below those). You need the component set's
+verified prop fragment, stamped with the trust statement. This is
+NEVER a dialog on the happy path (the zero-questions rule): mention it
+in ONE line of the final report, AFTER the done-and-live line ("Code
+Connect template available — say the word"), and only act on it when
+the user takes it up. It applies when the user's team is on a Figma
+Organization/Enterprise plan (Code Connect is unavailable below
+those). You need the component set's
 figma.com URL (node-id included). Publishing is the USER'S action with
 their token — `npx @figma/code-connect connect publish` — or, if this
 session has the Figma MCP's code-connect write tools, offer to publish

package/dist/tendril-mcp.js

@@ -131,12 +131,12 @@ var TOOLS = [
   },
   {
     name: "tendril_publish_wait",
-    description: "Phase two of the browser-approved publish: waits (with live progress) for the user's Approve click on the page tendril_publish returned, then uploads the bundle, commits it, and returns the live publication URL. Call it right after relaying the approve link. A denial, a lapse, and success each come back as their own sentence \u2014 report the outcome and the URL to the user.",
+    description: 'Phase two of the browser-approved publish. Waits in a BOUNDED window (~1 minute per call) for the user\'s Approve click on the page tendril_publish returned, then uploads the bundle, commits it, and returns the live publication URL. Call it right after relaying the approve link. While the human has not decided, each call returns `status: "approval-pending"` \u2014 that is a heartbeat, not a failure: tell the user in one short line that you are still waiting (restate the approve link and the account to approve as, ONLY if they seem lost; never urge the decision), then call this again to keep waiting. The request stays live for ~30 minutes. A denial, a lapse, and success each come back as their own sentence \u2014 report the outcome, and on success lead with the live URL. A decided approval continues straight into upload and commit INSIDE the same call \u2014 that phase can take minutes and may render no progress in some hosts; that is normal, not stuck. Some hosts render no progress at all during a call; the bounded window IS the liveness, so never describe an in-flight call as stuck \u2014 and a brief liveness line roughly every few minutes is enough, you need not narrate every heartbeat (each pending return carries waitedTotalSeconds/remainingSeconds to say where the wait stands).',
     schema: z.object({
       bundleDir: str("the same bundle directory tendril_publish was called with"),
       portal: optStr("portal origin override (must match tendril_publish's)")
     }),
-    argv: (i) => ["publish", i["bundleDir"], "--approve-wait", ...typeof i["portal"] === "string" ? ["--to", i["portal"]] : []]
+    argv: (i) => ["publish", i["bundleDir"], "--approve-wait", "--wait-window", "55", ...typeof i["portal"] === "string" ? ["--to", i["portal"]] : []]
   },
   {
     name: "tendril_record_next",
@@ -151,6 +151,40 @@ var TOOLS = [
     schema: z.object({ setDir: str("recording set directory") }),
     argv: (i) => ["record", "rest-fetch", "--set", i["setDir"]]
   },
+  {
+    name: "tendril_record_bindings",
+    description: "Fetch Figma's instance\u2192component bindings for an EXISTING MCP-recorded set \u2014 one or two batched REST calls, no re-recording, pixels/geometry/identity untouched. This is how components that are ALREADY recorded and generated become connectable: the bindings make cross-component pairing id-backed, so `tendril compose` can propose it for the human's confirm. Every binding is congruence-verified against the recorded metadata (a design that changed since recording refuses per pose, named). The CLI makes the requests itself with the user's connected Figma credential (tendril_figma_connect); you make NO Figma call. The result names the next step \u2014 including when no partner set is visible in the scanned root (co-locate the sets or pass compose --library). For sets recorded before file identity was captured, pass the design's file key as `file`.",
+    schema: z.object({ setDir: str("recording set directory"), file: optStr("the design's file key (figma.com/design/<KEY>/\u2026) \u2014 only for sets whose manifest lacks figmaFile; an operator assertion, congruence still gates every binding") }),
+    argv: (i) => ["record", "bindings", "--set", i["setDir"], ...typeof i["file"] === "string" ? ["--file", i["file"]] : []]
+  },
+  {
+    name: "tendril_compose",
+    description: "Put ONE composition pairing in front of the user's BROWSER \u2014 phase one of the browser-approved connect (invariant-5 migration; the terminal `--confirm-compositions` path remains for humans at a TTY). Requires a portal session (tendril_login \u2014 one browser Approve). Returns the approve-page link: RELAY IT verbatim, name the account the result says to approve as, and never urge the decision \u2014 the card carries the engine's honest disclosures and the human reads them. Deny on the card is NOT NOW (this request only, never a permanent decline). You cannot decide this yourself on any channel: the portal accepts the decision only from the user's signed-in browser, and the terminal flag only from an interactive TTY. A host with several open pairings needs `pair` (one card = one decision). Then finish with tendril_compose_wait. Both recording sets must be visible in one scanned workspace \u2014 co-locate them or pass `library`.",
+    schema: z.object({
+      setDir: str("the HOST recording set directory (the component that embeds the partner)"),
+      pair: optStr("the pair-key to request when the host has several open pairings"),
+      library: z.array(z.string()).optional().describe("workspace root(s) holding the partner recording set(s) \u2014 required when they live in another project root"),
+      portal: optStr("portal origin override (defaults to the stored session's portal)")
+    }),
+    argv: (i) => [
+      "compose",
+      "--set",
+      i["setDir"],
+      "--approve-start",
+      ...typeof i["pair"] === "string" ? ["--pair", i["pair"]] : [],
+      ...Array.isArray(i["library"]) ? i["library"].flatMap((d) => ["--library", d]) : [],
+      ...typeof i["portal"] === "string" ? ["--to", i["portal"]] : []
+    ]
+  },
+  {
+    name: "tendril_compose_wait",
+    description: 'Phase two of the browser-approved connect. Waits in a BOUNDED window (~1 minute per call) for the user\'s decision on the card tendril_compose returned; on Approve it records the SAME manifest entry the terminal confirm writes \u2014 after re-deriving the pairing from the CURRENT recordings and refusing if anything changed underneath the click (the click is then not wrong; the project moved \u2014 run the connect again). While undecided, each call returns `status: "approval-pending"` \u2014 a heartbeat, not a failure: one short liveness line to the user, then call again; the request stays live ~30 minutes, and a decided card can take moments to land. NOT NOW, a lapse, and success each arrive as their own sentence \u2014 report the one you got. After success: regenerate the HOST bundle with the same library roots (brief \u2192 generate \u2192 score \u2192 verify), then republish \u2014 announce the republish in one line first. Compose waits follow the same heartbeat contract as publish waits: never urge, never call an in-flight wait stuck.',
+    schema: z.object({
+      setDir: str("the same HOST set directory tendril_compose was called with"),
+      portal: optStr("portal origin override (must match tendril_compose's)")
+    }),
+    argv: (i) => ["compose", "--set", i["setDir"], "--approve-wait", "--wait-window", "55", ...typeof i["portal"] === "string" ? ["--to", i["portal"]] : []]
+  },
   {
     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 \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.",
@@ -298,7 +332,7 @@ var TOOLS = [
   },
   {
     name: "tendril_engine_score",
-    description: "AGENT-HARNESS engine, step 2 (the oracle): scores a candidate bundle directory against recorded truth \u2014 per-config pixels, behaviors, state parity (recording-selected \u2014 a bundle cannot unschedule it) \u2014 and returns feedback plus evidence artifacts. Iterate until allPass or two non-improving rounds. Only THIS tool's output counts as a score; never claim numbers yourself.",
+    description: "AGENT-HARNESS engine, step 2 (the oracle): scores a candidate bundle directory against recorded truth \u2014 per-config pixels, behaviors, state parity (recording-selected \u2014 a bundle cannot unschedule it) \u2014 and returns feedback plus evidence artifacts. Iterate until allPass or two non-improving rounds. Only THIS tool's output counts as a score; never claim numbers yourself. allPass ends the LOOP, not the run: finish with tendril_verify, and a green verify's terminal step is publishing \u2014 the component is done when it is LIVE, not when it scores.",
     schema: z.object({
       taskOrSet: str("reference task name or recording-set directory"),
       candidateDir: str("directory containing the proposed bundle files"),
@@ -341,7 +375,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 below the target bar with an honest report \u2014 sub-bar scores, or at bar cert a config demoted by absent-ink clusters.",
+    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. A GREEN run writes the inspect sheet itself and returns `next`: its terminal step is publishing (tendril_publish \u2192 tendril_publish_wait) \u2014 a verified component reachable only on local disk is an unfinished run; a sub-bar run never publishes.",
     schema: z.object({
       bundleDir: str("bundle directory to verify"),
       bar: optStr("pass (default) or cert"),
@@ -494,7 +528,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 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.",
+    "- 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 \u2014 and on green, publish (tendril_publish, then tendril_publish_wait until decided): the run ends at the live URL or the pending approve action, never at local disk.",
     "- Verdicts come only from Tendril's scores \u2014 never claim or estimate fidelity numbers yourself."
   ].join("\n")
 };
@@ -521,7 +555,11 @@ for (const tool of TOOLS) {
       const onProgress = token === void 0 || extra?.sendNotification === void 0 ? void 0 : (p) => {
         void extra.sendNotification({
           method: "notifications/progress",
-          params: { progressToken: token, progress: p.done, total: p.total, message: `scored ${p.done}/${p.total} configs (${p.label})` }
+          // The label is the CLI's own sentence for THIS phase —
+          // scoring, uploading, waiting for an approval. A
+          // hardcoded "scored N/M configs" here made every
+          // non-scoring tool narrate someone else's work.
+          params: { progressToken: token, progress: p.done, total: p.total, message: `${p.label} (${p.done}/${p.total})` }
         });
       };
       return toolResult(await runCli(tool.argv(input), 9e5, onProgress));