@tendrilapp/cli 0.1.3

package/LICENSE

@@ -0,0 +1,23 @@
+Tendril — End User License
+
+Copyright (c) 2026 Jordy Arnoldussen. All rights reserved.
+
+Subject to these terms, you are granted a non-exclusive,
+non-transferable license to install and run this software, in compiled
+form, for the purpose of using the Tendril product.
+
+You may not: reverse engineer, decompile, or disassemble the software
+except where permitted by applicable law; redistribute, sublicense,
+sell, or host the software for third parties; or remove or alter any
+notices in it.
+
+Verification note: the `tendril verify` command is and remains free to
+run — it requires no account and no network connection, and nothing in
+these terms may be read to gate it.
+
+The software is provided "as is", without warranty of any kind. To the
+maximum extent permitted by law, the author is not liable for any
+damages arising from its use.
+
+Third-party dependencies installed alongside this package retain their
+own licenses.

package/README.md

@@ -0,0 +1,12 @@
+# @tendrilapp/cli
+
+Figma design systems → verified React components.
+
+- `tendril` — the CLI: record, generate, verify. `tendril doctor` first.
+- `tendril-mcp` — the MCP server (stdio). Register it with your agent host:
+
+```json
+{ "mcpServers": { "tendril": { "command": "tendril-mcp" } } }
+```
+
+Verification is local, account-less, and network-less — always.

package/dist/tendril-mcp.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+// packages/mcp/src/bin.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// packages/mcp/src/server.ts
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+var REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+var CLI_BIN = path.join(REPO_ROOT, "packages", "cli", "src", "bin.ts");
+var BUNDLED_CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), "tendril.js");
+var CLI_SPAWN = existsSync(BUNDLED_CLI) ? { cmd: process.execPath, prefix: [BUNDLED_CLI] } : { cmd: "npx", prefix: ["tsx", CLI_BIN] };
+var str = (d) => z.string().describe(d);
+var optStr = (d) => z.string().optional().describe(d);
+var TOOLS = [
+  {
+    name: "tendril_record_plan",
+    description: "Plan 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.",
+    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>'),
+      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"]] : []
+    ]
+  },
+  {
+    name: "tendril_record_next",
+    annotations: { readOnlyHint: true },
+    description: "Get the next pending recording instruction (which Figma MCP tool to call for which node, and how to save it). Null instruction means the set is complete.",
+    schema: z.object({ setDir: str("recording set directory") }),
+    argv: (i) => ["record", "next", "--set", i["setDir"]]
+  },
+  {
+    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.",
+    schema: z.object({
+      setDir: str("recording set directory"),
+      rep: str("planned rep slug"),
+      tool: z.enum(["get_screenshot"]).describe("get_screenshot"),
+      url: str("image_url from the Figma response, verbatim")
+    }),
+    argv: (i) => ["record", "fetch", "--set", i["setDir"], "--rep", i["rep"], "--tool", i["tool"], "--url", i["url"]]
+  },
+  {
+    name: "tendril_record_ingest",
+    description: "Ingest a VERBATIM Figma tool-response envelope for a planned rep. Save the raw response to a file first; the CLI validates at the boundary and never rewrites bytes.",
+    schema: z.object({
+      setDir: str("recording set directory"),
+      rep: str("planned rep slug, or __set__ for the set-level get_variable_defs"),
+      // Enumerated, not a free string: this value reaches a file path.
+      // As a bare string it was an arbitrary relative-path overwrite
+      // (--tool "../../outside/victim" replaced a file outside the set,
+      // exit 0). The sink in session.ts now contains the path too — this
+      // is the second layer, and it makes the tool self-documenting.
+      tool: z.enum(["get_design_context", "get_metadata", "get_screenshot", "get_variable_defs", "get_metadata_interior"]),
+      file: str("path to the verbatim envelope JSON")
+    }),
+    argv: (i) => ["record", "ingest", "--set", i["setDir"], "--rep", i["rep"], "--tool", i["tool"], "--file", i["file"]]
+  },
+  {
+    name: "tendril_record_asset",
+    description: "Ingest a downloaded asset file (asset-<id>.<ext>) for a rep. SVGs with active content are rejected; sizes are capped.",
+    schema: z.object({
+      setDir: str("recording set directory"),
+      rep: str("planned rep slug"),
+      name: str("asset-<id>.<ext>"),
+      file: str("downloaded asset file path")
+    }),
+    argv: (i) => ["record", "asset", "--set", i["setDir"], "--rep", i["rep"], "--name", i["name"], "--file", i["file"]]
+  },
+  {
+    name: "tendril_record_status",
+    annotations: { readOnlyHint: true },
+    description: "Recording-set completeness: per-rep recorded/missing tools.",
+    schema: z.object({ setDir: str("recording set directory") }),
+    argv: (i) => ["record", "status", "--set", i["setDir"]]
+  },
+  {
+    name: "tendril_engine_brief",
+    description: "AGENT-HARNESS engine, step 1: emits the task payload file (system brief + every recorded config's emission, box, assets, tokens) and the protocol. YOU (the calling agent) implement the bundle; the CLI is the only judge. Read the payload file completely before proposing.",
+    schema: z.object({
+      taskOrSet: str("a recording-set directory (from tendril_record), or a reference task name \u2014 an unknown name returns the valid list in the error"),
+      // Required by design, not convenience: the model choice must be
+      // settled BEFORE generation starts. A smoke run picked its own
+      // model silently because the ask lived in instruction text, which
+      // evaporates in non-interactive sessions; a required parameter
+      // cannot evaporate. Ask the user when one is present; otherwise
+      // choose, declare, and state the reason in your report.
+      model: str("the model that will WRITE the implementation \u2014 ask the user when interactive; declare your reasoned choice when not"),
+      bar: optStr("pass (default) or cert"),
+      out: optStr("payload file path override")
+    }),
+    argv: (i) => [
+      "engine",
+      "brief",
+      i["taskOrSet"],
+      "--model",
+      i["model"],
+      ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+      ...i["out"] !== void 0 ? ["--out", i["out"]] : []
+    ]
+  },
+  {
+    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, hover parity \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.",
+    schema: z.object({
+      taskOrSet: str("reference task name or recording-set directory"),
+      candidateDir: str("directory containing the proposed bundle files"),
+      bar: optStr("pass (default) or cert"),
+      host: optStr("your host identity (e.g. claude-code, cursor, codex) \u2014 recorded as self-reported provenance"),
+      model: str("the model that proposed the candidate \u2014 REQUIRED; recorded as self-reported provenance, and the CLI refuses to score without it")
+    }),
+    argv: (i) => [
+      "engine",
+      "score",
+      i["taskOrSet"],
+      i["candidateDir"],
+      ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+      ...i["host"] !== void 0 ? ["--host", i["host"]] : [],
+      "--model",
+      i["model"]
+    ]
+  },
+  {
+    name: "tendril_verify",
+    description: "Recompute full verification for a generated bundle (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.",
+    schema: z.object({
+      bundleDir: str("bundle directory to verify"),
+      bar: optStr("pass (default) or cert"),
+      set: optStr("recording-set directory override")
+    }),
+    argv: (i) => [
+      "verify",
+      i["bundleDir"],
+      ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+      ...i["set"] !== void 0 ? ["--set", i["set"]] : []
+    ]
+  },
+  {
+    name: "tendril_generate_curated",
+    description: "CURATED engine (explicit alternative path): generation by an allowlisted API model over the user's OpenRouter-compatible key, with cost consent, hard spend caps, and resume. Use ONLY when the user asks for API-model generation instead of implementing it yourself.",
+    schema: z.object({
+      input: str("reference task name or recording-set directory"),
+      model: optStr("OpenRouter model id (default: allowlist pointer)"),
+      bar: optStr("pass (default) or cert"),
+      cap: optStr("spend cap in USD (default 1.50)"),
+      yes: z.boolean().optional().describe("accept the cost consent (the user must have approved the spend)")
+    }),
+    argv: (i) => [
+      "generate",
+      i["input"],
+      ...i["model"] !== void 0 ? ["--model", i["model"]] : [],
+      ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+      ...i["cap"] !== void 0 ? ["--cap", i["cap"]] : [],
+      ...i["yes"] === true ? ["--yes"] : []
+    ]
+  }
+];
+var PROGRESS_PREFIX = "@tendril-progress ";
+function parseProgressLine(line) {
+  if (!line.startsWith(PROGRESS_PREFIX)) return null;
+  try {
+    return JSON.parse(line.slice(PROGRESS_PREFIX.length));
+  } catch {
+    return null;
+  }
+}
+function stripProgressLines(stderr) {
+  return stderr.split("\n").filter((l) => !l.startsWith(PROGRESS_PREFIX)).join("\n");
+}
+function consumeProgressChunk(pending, chunk, onProgress) {
+  const lines = (pending + chunk).split("\n");
+  const rest = lines.pop() ?? "";
+  for (const line of lines) {
+    const p = parseProgressLine(line);
+    if (p !== null) onProgress(p);
+  }
+  return rest;
+}
+function runCli(argv, timeoutMs = 9e5, onProgress) {
+  return new Promise((resolve) => {
+    const child = execFile(
+      CLI_SPAWN.cmd,
+      [...CLI_SPAWN.prefix, ...argv, "--json"],
+      { cwd: process.cwd(), timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, INIT_CWD: process.cwd() } },
+      (err, stdout, stderrRaw) => {
+        const exitCode = err === null ? 0 : err.code ?? 1;
+        resolve({ ok: exitCode === 0, exitCode: typeof exitCode === "number" ? exitCode : 1, stdout, stderr: stripProgressLines(stderrRaw) });
+      }
+    );
+    if (onProgress === void 0) return;
+    let pending = "";
+    child.stderr?.on("data", (chunk) => {
+      pending = consumeProgressChunk(pending, chunk.toString(), onProgress);
+    });
+  });
+}
+function sourceHash() {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  const h = createHash("sha256");
+  for (const f of readdirSync(dir).filter((n) => n.endsWith(".ts")).sort()) {
+    h.update(f);
+    h.update(readFileSync(path.join(dir, f)));
+  }
+  return h.digest("hex").slice(0, 16);
+}
+var BOOT_HASH = (() => {
+  try {
+    return sourceHash();
+  } catch {
+    return "unknown";
+  }
+})();
+function serverStale() {
+  if (BOOT_HASH === "unknown") return false;
+  try {
+    return sourceHash() !== BOOT_HASH;
+  } catch {
+    return false;
+  }
+}
+function toolResult(result) {
+  const stale = serverStale() ? `
+{"serverStale":true,"remediation":"packages/mcp changed since this server started \u2014 reload the Tendril MCP server before trusting this result or reporting a bug against it"}` : "";
+  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"}` }] };
+  }
+  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"}`;
+  return { content: [{ type: "text", text }], ...result.ok ? {} : { isError: true } };
+}
+
+// packages/mcp/src/bin.ts
+var server = new McpServer({ name: "tendril", version: "0.1.0" });
+for (const tool of TOOLS) {
+  server.registerTool(
+    tool.name,
+    { description: tool.description, inputSchema: tool.schema.shape, ...tool.annotations !== void 0 ? { annotations: tool.annotations } : {} },
+    async (input, extra) => {
+      const token = extra?._meta?.["progressToken"];
+      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})` }
+        });
+      };
+      return toolResult(await runCli(tool.argv(input), 9e5, onProgress));
+    }
+  );
+}
+var transport = new StdioServerTransport();
+await server.connect(transport);