@tokenzero/cli 0.1.0 → 0.1.3

package/README.md

@@ -0,0 +1,27 @@
+# @tokenzero/cli
+
+Command line for [TokenZero](https://tokenzero.sh): audit LLM token waste in a project, connect it to the TokenZero bring-your-own-key gateway, check usage, and verify signed savings receipts.
+
+```sh
+npx -y @tokenzero/cli audit                    # local static audit; nothing is uploaded
+npx -y @tokenzero/cli audit --json
+npx -y @tokenzero/cli audit --fail-over 30     # CI gate: exit 1 above 30% recoverable
+git diff origin/main | npx -y @tokenzero/cli audit --diff - --format markdown
+```
+
+Audits are **static heuristics**: they read code, not traffic, and report estimates at list prices. Library and SDK repositories are detected and their findings downgraded.
+
+## Connecting to the gateway
+
+These commands talk to the hosted gateway at `https://tokenzero.sh`. To use another deployment, pass `--url` or set `TOKENZERO_URL`.
+
+```sh
+npx -y @tokenzero/cli init        # audit, create a workspace, write base URLs to .env (asks first)
+npx -y @tokenzero/cli usage       # routed spend vs the free tier, savings
+npx -y @tokenzero/cli verify <request_id>   # check a receipt's Ed25519 signature locally
+npx -y @tokenzero/cli rotate-key  # new workspace key; rewrites it in .env
+```
+
+**Authentication.** Send your workspace key as the `X-TokenZero-Key` header; this is the recommended form. Your provider key is sent exactly as you would send it to the provider and passes through untouched. For setups where you cannot add headers, `init` can embed the workspace key in the base URL (`<gateway>/w/<key>/v1`). Treat such URLs as secrets, and run `rotate-key` if one leaks into logs.
+
+Node >= 18. Single file, no dependencies. Apache-2.0.

package/bin/tokenzero.mjs

@@ -203,7 +203,9 @@ function lex(src, path3) {
         j++;
       }
       const end = Math.min(j, src.length);
-      literals.push({ text: src.slice(i + 1, end), line });
+      const rep = (py ? /^\s*\*\s*(\d{1,6})\b/ : /^\.repeat\(\s*(\d{1,6})\s*\)/).exec(src.slice(end + 1, end + 40));
+      const body = src.slice(i + 1, end);
+      literals.push({ text: rep ? body.repeat(Math.max(1, Math.min(Number(rep[1]), Math.floor(2e5 / Math.max(1, body.length))))) : body, line });
       blank(i + 1, end);
       advance(i, end + 1);
       i = end + 1;
@@ -254,6 +256,98 @@ function detectRepoKind(manifests2, files) {
   return { kind: "unknown", reason: "no manifest signal" };
 }
 var DOWN = { high: "medium", medium: "low", low: "info", info: "info" };
+var OPEN = "([{";
+var CLOSE = ")]}";
+function matchClose(m, from, limit = 4e4) {
+  let depth = 0;
+  for (let k = from; k < Math.min(m.length, from + limit); k++) {
+    const c2 = m[k];
+    if (OPEN.includes(c2)) depth++;
+    else if (CLOSE.includes(c2) && --depth === 0) return k;
+  }
+  return Math.min(m.length, from + limit) - 1;
+}
+function makeLocator(masked) {
+  const text = masked.join("\n");
+  const starts = [];
+  let o = 0;
+  for (const l of masked) {
+    starts.push(o);
+    o += l.length + 1;
+  }
+  const lineOf = (off) => {
+    let lo = 0, hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (starts[mid] <= off) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo;
+  };
+  return { text, starts, lineOf };
+}
+var ASSIGN = (name) => new RegExp(`^\\s*(?:export\\s+)?(?:const|let|var|final|static|private|public|readonly|\\s)*\\s*(?:self\\.|this\\.)?${name}\\s*(?::[^=\\n]+)?=(?![=>])`);
+var KEYWORDS = /* @__PURE__ */ new Set(["self", "this", "await", "async", "return", "model", "messages", "role", "content", "system", "user", "true", "false", "True", "False", "None", "null", "undefined", "new", "max_tokens", "temperature", "client", "resp", "response"]);
+function assignmentScope(loc, masked, line) {
+  const eq = masked[line].search(/=(?![=>])/);
+  let end = line;
+  let k = loc.starts[line] + eq + 1;
+  for (; ; ) {
+    const lineEnd = loc.starts[end] + masked[end].length;
+    let opened = -1;
+    for (let q = k; q < lineEnd; q++) if (OPEN.includes(loc.text[q])) {
+      opened = q;
+      break;
+    }
+    if (opened >= 0) {
+      const close = matchClose(loc.text, opened, 2e4);
+      end = loc.lineOf(close);
+      k = close + 1;
+      if (k < loc.starts[end] + masked[end].length) continue;
+    }
+    const tail = masked[end].trimEnd();
+    if (end + 1 < masked.length && (/[+\\,(]$/.test(tail) || /^\s*[+.]/.test(masked[end + 1] ?? "")) && end - line < 60) {
+      end++;
+      k = loc.starts[end];
+      continue;
+    }
+    return { start: line, end };
+  }
+}
+function identifiersIn(masked, sc) {
+  const ids = /* @__PURE__ */ new Set();
+  for (let l = sc.start; l <= sc.end; l++) for (const m of (masked[l] ?? "").matchAll(/\b([A-Za-z_]\w{1,60})\b/g)) if (!KEYWORDS.has(m[1])) ids.add(m[1]);
+  return ids;
+}
+function resolveScopes(loc, masked, from, depth = 2) {
+  const out2 = [], seen = /* @__PURE__ */ new Set();
+  let frontier = [from];
+  for (let d = 0; d < depth && frontier.length; d++) {
+    const next = [];
+    for (const sc of frontier) for (const id of identifiersIn(masked, sc)) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const re = ASSIGN(id);
+      let found = -1;
+      for (let l = sc.start; l >= 0; l--) if (re.test(masked[l])) {
+        found = l;
+        break;
+      }
+      if (found < 0) {
+        for (let l = sc.end + 1; l < masked.length; l++) if (re.test(masked[l])) {
+          found = l;
+          break;
+        }
+      }
+      if (found < 0 || found >= from.start && found <= from.end) continue;
+      const a = assignmentScope(loc, masked, found);
+      out2.push(a);
+      next.push(a);
+    }
+    frontier = next;
+  }
+  return out2;
+}
 function analyzeFiles(files, repo = null, manifests2 = []) {
   const findings = [];
   const callSites = [];
@@ -281,9 +375,16 @@ function analyzeFiles(files, repo = null, manifests2 = []) {
     const hasCacheControl = /cache_control|cacheControl|prompt_cache_key|promptCacheKey|cachedContent|cached_content/.test(src);
     const illustrative = EXAMPLE_PATH.test(f.path);
     let repeatFlagged = false;
-    masked.forEach((code, i) => {
-      const sdk = CALL_RE.find(([re]) => re.test(code))?.[1];
-      if (!sdk) return;
+    const loc = makeLocator(masked);
+    const callLines = [];
+    masked.forEach((code2, i) => {
+      const hit = CALL_RE.find(([re]) => re.test(code2));
+      if (!hit) return;
+      const m = hit[0].exec(code2);
+      const close = matchClose(loc.text, loc.starts[i] + m.index + m[0].length - 1);
+      callLines.push({ line: i, sdk: hit[1], scope: { start: i, end: Math.max(i, loc.lineOf(close)) } });
+    });
+    callLines.forEach(({ line: i, sdk, scope }, n) => {
       const local = [];
       const push = (fd) => {
         let sev = fd.severity;
@@ -291,13 +392,22 @@ function analyzeFiles(files, repo = null, manifests2 = []) {
         if (illustrative) sev = DOWN[sev];
         local.push({ ...fd, severity: sev });
       };
-      const window = lines.slice(i, Math.min(lines.length, i + 30)).join("\n");
-      const model = [...window.matchAll(MODEL_RE)].map((m) => m[1])[0] ?? null;
+      const refs = resolveScopes(loc, masked, scope);
+      const inScopes = (l, scs) => scs.some((sc) => l.line - 1 >= sc.start && l.line - 1 <= sc.end);
+      let near = literals.filter((l) => inScopes(l, [scope, ...refs]));
+      if (!near.some((l) => l.text.trim().length > 20)) {
+        const prevEnd = n > 0 ? callLines[n - 1].scope.end : -1;
+        near = near.concat(literals.filter((l) => l.line - 1 > prevEnd && l.line - 1 >= i - 40 && l.line - 1 < i));
+      }
+      const spanText = lines.slice(scope.start, scope.end + 1).join("\n");
+      const nextStart = n + 1 < callLines.length ? callLines[n + 1].line : lines.length;
+      const fallbackWindow = lines.slice(i, Math.min(nextStart, i + 30)).join("\n");
+      const modelFrom = (t) => [...t.matchAll(MODEL_RE)].map((m) => m[1])[0] ?? null;
+      const model = modelFrom(spanText) ?? modelFrom(refs.map((r) => lines.slice(r.start, r.end + 1).join("\n")).join("\n")) ?? modelFrom(fallbackWindow);
       callSites.push({ file: f.path, line: i + 1, model, sdk });
       if (model) models[model] = (models[model] ?? 0) + 1;
       const key = normalizeModel(model);
       const price = key ? priceFor(key) : null;
-      const near = literals.filter((l) => l.line >= i + 1 - 40 && l.line <= i + 1 + 40);
       const prompts = near.filter((l) => promptLike(l.text));
       const codeCtx = masked.slice(Math.max(0, i - 25), i + 25).join("\n");
       const simpleTask = near.some((l) => SIMPLE_TASK.test(l.text));
@@ -311,23 +421,25 @@ function analyzeFiles(files, repo = null, manifests2 = []) {
           severity: isAnthropic ? bigTok >= 1500 ? "high" : cacheable ? "medium" : "low" : cacheable ? "medium" : "low",
           file: f.path,
           line: prompts[0].line,
-          title: `~${bigTok.toLocaleString()} static prompt tokens re-billed at full price on every call`,
-          detail: isAnthropic ? `This call sends a large fixed prompt but never marks a cache breakpoint, so Anthropic bills all ${bigTok} tokens at the full input rate each time instead of the cache-read rate (${readRate}% cheaper).` : `A fixed prefix of ~${bigTok} tokens is sent on every call. Prefix caching applies only to stable prefixes of at least ${min} tokens on this model; keep the static part first and nothing volatile (timestamps, ids) interpolated into it.`,
+          title: isAnthropic ? `~${bigTok.toLocaleString()} static prompt tokens re-billed at full price on every call` : `~${bigTok.toLocaleString()} static prompt tokens sent on every call; only a stable prefix gets the cache discount`,
+          detail: (isAnthropic ? `This call sends a large fixed prompt but never marks a cache breakpoint, so Anthropic bills all ${bigTok} tokens at the full input rate each time instead of the cache-read rate (${readRate}% cheaper).` : `A fixed block of ~${bigTok} tokens goes out with every call. ${model ? model : "This provider"} discounts cached input ${readRate}%, but only for a byte-identical prefix of at least ${min} tokens that is routed to the same cache; anything volatile (dates, ids, user text) placed before or inside it, or traffic spread across cache shards, means paying full price.`) + (prompts[0].line !== i + 1 ? ` Sent by the call at ${f.path}:${i + 1}.` : ""),
           fix: isAnthropic ? 'Route through TokenZero (breakpoints are injected automatically) or add `cache_control: {type: "ephemeral"}` to the last system block and the last tool.' : "Route through TokenZero to get a stable `prompt_cache_key`, or move dynamic content below the static prefix and set `prompt_cache_key` yourself.",
           // OpenAI/Gemini already cache stable prefixes automatically; the recoverable part
           // is prefix hygiene and cache routing, not the whole cache discount.
           est_savings_pct: !cacheable ? 0 : isAnthropic ? Math.min(85, Math.round(bigTok / (bigTok + 400) * readRate)) : 15
         });
       }
-      if (key && price?.tier === "frontier" && CASCADE_TARGET[key] && simpleTask) {
-        const to = CASCADE_TARGET[key];
+      const cascadeTo = key ? CASCADE_TARGET[key] : void 0;
+      const ratio = cascadeTo ? costOf(cascadeTo, { input: 1500, output: 200 }) / costOf(key, { input: 1500, output: 200 }) : 1;
+      if (key && price && cascadeTo && simpleTask && (price.tier === "frontier" || ratio <= 0.5)) {
+        const to = cascadeTo;
         const a = costOf(key, { input: 1500, output: 200 }), b = costOf(to, { input: 1500, output: 200 });
         push({
-          severity: "high",
+          severity: price.tier === "frontier" || ratio <= 0.2 ? "high" : "medium",
           file: f.path,
           line: i + 1,
           title: `${key} used for a task whose prompt reads like extraction/classification`,
-          detail: `Frontier pricing ($${price.input}/M in, $${price.output}/M out) on a constrained task. ${to} costs ~${Math.round((1 - b / a) * 100)}% less per call at this shape.`,
+          detail: `${price.tier === "frontier" ? "Frontier" : "Full-size"} pricing ($${price.input}/M in, $${price.output}/M out) on a constrained task. ${to} costs ~${Math.round((1 - b / a) * 100)}% less per call at this shape.`,
           fix: `Opt into TokenZero cascade routing (\`X-TokenZero-Cascade: auto\`) so this call is routed to ${to} only when the classifier is confident, with parity reported in the ledger, or switch the model here behind an eval.`,
           est_savings_pct: Math.round((1 - b / a) * 100)
         });
@@ -344,10 +456,10 @@ function analyzeFiles(files, repo = null, manifests2 = []) {
           est_savings_pct: 25
         });
       }
-      if (simpleTask && !repeatFlagged && !/seed\s*[:=]|temperature\s*[:=]\s*0\b/.test(codeCtx)) {
+      if (simpleTask && !repeatFlagged && !/seed["']?\s*[:=]|temperature["']?\s*[:=]\s*0\b|X-TokenZero-Cache/i.test(spanText)) {
         repeatFlagged = true;
         push({
-          severity: "info",
+          severity: "low",
           file: f.path,
           line: i + 1,
           title: "Repeat-prone task with no response-cache opt-in",
@@ -356,7 +468,7 @@ function analyzeFiles(files, repo = null, manifests2 = []) {
           est_savings_pct: 10
         });
       }
-      if (isAnthropic && /\btools\s*[:=]/.test(masked.slice(i, i + 30).join("\n")) && !hasCacheControl) {
+      if (isAnthropic && /\btools\s*[:=]/.test(masked.slice(scope.start, scope.end + 1).join("\n")) && !hasCacheControl) {
         push({
           severity: "low",
           file: f.path,
@@ -428,14 +540,23 @@ function filesFromDiff(diff) {
   }
   return files;
 }
-function prComment(report, publicUrl) {
+var PR_COMMENT_MARKER = "<!-- tokenzero-cost-check -->";
+var PUBLIC_REPO = "https://github.com/tokenzero-ai/tokenzero";
+var inert = (t) => t.replace(/[\\`*_[\]<>|]/g, (c2) => "\\" + c2).replace(/\r?\n/g, " ");
+var pipeSafe = (t) => t.replace(/\|/g, "\\|");
+var code = (t) => "`" + t.replace(/`/g, "'").replace(/\|/g, "\\|").replace(/\r?\n/g, " ").slice(0, 200) + "`";
+var usd2 = (n) => "$" + n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+function prComment(report, opts = {}) {
   const c2 = report.cost_per_10k_runs;
-  const head = c2 ? `**TokenZero FinOps check** \u2014 estimated cost per 10k runs: \`$${c2.before_usd}\` \u2192 \`$${c2.after_usd}\` (${report.estimated_waste_pct}% recoverable) on \`${c2.model}\`` : `**TokenZero FinOps check** \u2014 ${report.findings.length} finding(s), ${report.call_sites.length} LLM call site(s)`;
-  const rows = report.findings.slice(0, 8).map((f) => `| ${f.severity} | \`${f.file}:${f.line}\` | ${f.title} | ${f.est_savings_pct}% |`).join("\n");
+  const head = c2 ? `**TokenZero cost check:** estimated cost per 10k runs ${code(usd2(c2.before_usd))} \u2192 ${code(usd2(c2.after_usd))} (${report.estimated_waste_pct}% recoverable) on ${code(c2.model)}` : `**TokenZero cost check:** ${report.findings.length} finding(s), ${report.call_sites.length} LLM call site(s)`;
+  const rows = report.findings.slice(0, 8).map((f) => `| ${f.severity} | ${code(`${f.file}:${f.line}`)} | ${pipeSafe(f.title)} | ${f.severity === "info" ? "not counted" : f.est_savings_pct + "%"} |`).join("\n");
+  const g = opts.gatewayUrl?.replace(/\/+$/, "");
+  const fix = g ? `One-line fix for everything above: point your SDK at ${code(g + "/v1")} (BYOK; your keys pass straight through).${opts.hostedReport ? ` [Full report](${g}/audit/${report.id})` : ""}` : `How to fix: route calls through the TokenZero gateway, or apply the fixes above by hand. [TokenZero tools](${PUBLIC_REPO})`;
   return [
+    PR_COMMENT_MARKER,
     head,
     "",
-    report.findings.length ? "| severity | where | finding | est. savings |\n|---|---|---|---|\n" + rows : "_No token-waste patterns found in the changed lines._",
+    report.findings.length ? "| severity | where | finding | savings on that call |\n|---|---|---|---|\n" + rows : "_No token-waste patterns found in the changed lines._",
     "",
     report.findings.slice(0, 3).map((f) => `<details><summary>${f.title}</summary>
 
@@ -444,10 +565,10 @@ ${f.detail}
 **Fix:** ${f.fix}
 </details>`).join("\n"),
     "",
-    `One-line fix for everything above: point your SDK at \`${publicUrl}/v1\` (BYOK; your keys pass straight through). [How it works](${publicUrl}) \xB7 [Full report](${publicUrl}/audit/${report.id})`,
-    ...report.notes.map((n) => `> ${n}`),
+    fix,
+    ...report.notes.map((n) => `> ${inert(n)}`),
     "",
-    "<sub>Estimates are static heuristics at list prices, not measurements. Verified numbers come from the signed ledger once traffic flows.</sub>"
+    "<sub>Static heuristics at list prices, not measurements. Each row is the saving on the call it points at; the headline weights rows by confidence and averages over every call site in the change. Verified numbers come from the signed ledger once traffic flows.</sub>"
   ].join("\n");
 }
 
@@ -501,8 +622,8 @@ function canonical(obj) {
 }
 
 // cli/src/main.ts
-var VERSION = "0.1.0";
-var BAKED_URL = typeof __TOKENZERO_BAKED__ === "string" ? __TOKENZERO_BAKED__ : "__TOKENZERO_DEFAULT_URL__";
+var VERSION = "0.1.3";
+var BAKED_URL = true ? "https://tokenzero.sh" : "__TOKENZERO_DEFAULT_URL__";
 function parseArgs(argv) {
   const a = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
@@ -523,7 +644,7 @@ function parseArgs(argv) {
 }
 var VALUE_FLAGS = /* @__PURE__ */ new Set(["url", "name", "key", "format", "diff", "fail-over", "env-file"]);
 var tty = process.stdout.isTTY && !process.env.NO_COLOR;
-var c = (code) => (s) => tty ? `\x1B[${code}m${s}\x1B[0m` : s;
+var c = (code2) => (s) => tty ? `\x1B[${code2}m${s}\x1B[0m` : s;
 var bold = c("1");
 var dim = c("2");
 var green = c("32");
@@ -753,7 +874,7 @@ async function cmdAudit(a) {
   } else report = analyzeFiles(walk(root), null, manifests(root));
   const fmt = a.flags.format ?? (a.flags.json ? "json" : "text");
   if (fmt === "json") out(JSON.stringify(report, null, 2));
-  else if (fmt === "markdown") out(prComment(report, baseUrl(a) ?? "https://tokenzero.sh"));
+  else if (fmt === "markdown") out(prComment(report, { gatewayUrl: baseUrl(a) }));
   else {
     summarize(report, 100);
     for (const f of report.findings.slice(0, 3)) out(`

package/package.json

@@ -1,13 +1,30 @@
 {
   "name": "@tokenzero/cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "TokenZero CLI: connect a project to the TokenZero BYOK gateway, audit LLM token waste locally, check usage and verify signed savings receipts.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "TokenZero Contributors <support@tokenzero.sh>",
   "homepage": "https://tokenzero.sh",
-  "bin": { "tokenzero": "bin/tokenzero.mjs" },
-  "files": ["bin/tokenzero.mjs"],
-  "engines": { "node": ">=18" },
-  "keywords": ["llm", "openai", "anthropic", "gemini", "cost", "finops", "prompt-caching", "mcp"]
+  "bin": {
+    "tokenzero": "bin/tokenzero.mjs"
+  },
+  "files": [
+    "bin/tokenzero.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "llm",
+    "openai",
+    "anthropic",
+    "gemini",
+    "cost",
+    "finops",
+    "prompt-caching",
+    "mcp"
+  ]
 }