sigrank 0.18.5 → 1.0.1

package/tools/_framing.mjs

@@ -0,0 +1,217 @@
+/**
+ * tools/_framing.mjs — behavioral framing helpers for intent-based tools.
+ *
+ * Power-user language + competitive layer shared by get_best_operator,
+ * compare_self, compare_operators, and optimize_efficiency.
+ *
+ * Class-tier language is keyed off the canonical 8-tier dev10x taxonomy
+ * (analytics/cascade.mjs CLASS_TIERS) + UNCLASSED. A prior version branched
+ * on the legacy 3-tier Burner/Builder/10xer names, which the cascade
+ * classifier never emits — every operator was falling through to the
+ * "Burner" branch and getting "you are not yet a power user" framing
+ * regardless of their actual tier. The framing now groups the 8 tiers into
+ * power-user bands (apex / high / mid / early / entry / no-data) and writes
+ * one message per band.
+ */
+
+import { DEFAULT_API_BASE } from "./_helpers.mjs";
+import { CLASS_TIERS, UNCLASSED, tierOf } from "../analytics/cascade.mjs";
+
+/**
+ * Map a class tier to a power-user band. The 8 experience tiers collapse into 5
+ * behavioral bands + UNCLASSED so the framing stays short without writing 8
+ * bespoke messages. Band order matches CLASS_TIERS cut order (descending).
+ *
+ *   ARCH+, ARCH           → high    (deep experience, power-user archetype)
+ *   POWER, BASE           → mid     (building momentum)
+ *   SEEKER, REFINER       → early   (accumulating volume, finding patterns)
+ *   BEARER, IGNITER       → entry   (first volume, or dormant)
+ *   UNCLASSED / unknown   → nodata
+ */
+const BAND = {
+  "ARCH+": "high",
+  ARCH: "high",
+  POWER: "mid",
+  BASE: "mid",
+  SEEKER: "early",
+  REFINER: "early",
+  BEARER: "entry",
+  IGNITER: "entry",
+  [UNCLASSED]: "nodata",
+};
+
+/** Default fallback when a metrics object carries no class — UNCLASSED, not
+ *  the legacy "Burner". Callers that did `metrics.class || "Burner"` were
+ *  silently relabeling every no-data operator as the bottom legacy tier. */
+export const FALLBACK_CLASS = UNCLASSED;
+
+/** Map a class tier (full sub-stage string or base tier) to its power-user
+ *  band. Exported so tool handlers can branch on band without re-deriving the
+ *  tier→band mapping. Uses tierOf() to extract the base tier from sub-stage
+ *  strings (e.g. "REFINER II" → "REFINER" → "early"). */
+export function bandOf(klass) {
+  return BAND[tierOf(klass)] ?? "nodata";
+}
+
+/**
+ * Competitive layer for tool responses per SHARED_DESIGN_DECISIONS.md §3/§4/§5.
+ * Every tool response that includes operator data must show:
+ *   rank, percentile, class_tier, delta_from_average, delta_from_top, shareable_url
+ * Response style: factual + competitive ("You rank #12 of 47 operators...")
+ */
+export function _competitiveLayer(op, board) {
+  const allOps = Array.isArray(board?.operators || board)
+    ? board.operators || board
+    : [];
+  const yields = allOps.map((o) => o.yield_ || 0).sort((a, b) => a - b);
+  const yourYield = op.yield_ || 0;
+  const total = allOps.length;
+
+  // Rank: find operator's position (1-based)
+  let rank = op.rank || null;
+  if (!rank && total > 0) {
+    const sorted = [...allOps].sort((a, b) => (b.yield_ || 0) - (a.yield_ || 0));
+    const idx = sorted.findIndex((o) => o.codename === op.codename);
+    rank = idx >= 0 ? idx + 1 : null;
+  }
+
+  // Percentile: % of operators with yield below this operator
+  const percentile = total > 0
+    ? Math.round((yields.filter((y) => y < yourYield).length / total) * 100)
+    : 0;
+
+  // Delta from average
+  const avgYield = total > 0 ? yields.reduce((s, y) => s + y, 0) / total : 0;
+  const deltaFromAvg = avgYield > 0
+    ? { absolute: Math.round(yourYield - avgYield),
+        percent: Math.round(((yourYield - avgYield) / avgYield) * 100) }
+    : { absolute: 0, percent: 0 };
+
+  // Delta from top operator
+  const topYield = total > 0 ? Math.max(...yields) : 0;
+  const deltaFromTop = topYield > 0
+    ? { absolute: Math.round(topYield - yourYield),
+        percent: Math.round(((topYield - yourYield) / topYield) * 100) }
+    : { absolute: 0, percent: 0 };
+
+  // Shareable URL
+  const shareableUrl = op.codename && op.codename !== "you (local)"
+    ? `${DEFAULT_API_BASE}/operator/${encodeURIComponent(op.codename)}`
+    : null;
+
+  return {
+    rank,
+    total_operators: total,
+    percentile,
+    class_tier: op.class || FALLBACK_CLASS,
+    delta_from_average: deltaFromAvg,
+    delta_from_top: deltaFromTop,
+    shareable_url: shareableUrl,
+  };
+}
+
+/** Factual + competitive summary line per SHARED_DESIGN_DECISIONS.md §4 */
+export function _competitiveSummary(op, board) {
+  const cl = _competitiveLayer(op, board);
+  const parts = [];
+
+  if (cl.rank && cl.total_operators > 0) {
+    parts.push(`You rank #${cl.rank} of ${cl.total_operators} operators.`);
+  }
+
+  const topOp = (board?.operators || board || []).reduce(
+    (best, o) => ((o.yield_ || 0) > (best?.yield_ || 0) ? o : best),
+    null,
+  );
+  if (topOp && topOp.codename) {
+    parts.push(`Top operator is ${topOp.codename} with Υ ${(topOp.yield_ || 0).toLocaleString()}.`);
+  }
+
+  if (cl.delta_from_average.percent !== 0) {
+    const dir = cl.delta_from_average.percent > 0 ? "above" : "below";
+    parts.push(`You're ${Math.abs(cl.delta_from_average.percent)}% ${dir} average.`);
+  }
+
+  if (cl.delta_from_top.percent > 0) {
+    parts.push(`${cl.delta_from_top.percent}% below top.`);
+  }
+
+  return parts.join(" ");
+}
+
+export function _behavioralFraming(op) {
+  const y = op.yield_ || 0;
+  const l = op.leverage || 0;
+  const v = op.velocity || 0;
+  const klass = op.class || FALLBACK_CLASS;
+  const band = bandOf(klass);
+
+  if (band === "apex")
+    return `Closed-loop operator: ${l.toFixed(1)}× leverage over fresh input with ${v.toFixed(2)} output velocity. Both axes held at once — the rare apex profile the leverage/velocity tradeoff says shouldn't exist.`;
+  if (band === "high")
+    return `Disciplined, system-level reuse: ${l.toFixed(1)}× leverage means heavy cache reuse over fresh input, ${v.toFixed(2)} velocity means more output per token spent. This is the AI power-user archetype.`;
+  if (band === "mid")
+    return `Building cascade momentum: moderate cache reuse (${l.toFixed(1)}× leverage) with ${v.toFixed(2)} output velocity. Approaching power-user patterns — increase cache reuse to push into the ARCH band.`;
+  if (band === "early")
+    return `Compounding, not yet compounding well: ${v.toFixed(2)} output velocity with ${l.toFixed(1)}× leverage. Cache reuse is starting but input still dominates. Reuse prior context (templates, prompts, workflows) to build leverage.`;
+  if (band === "entry")
+    return `Early-stage cascade: ${v.toFixed(2)} output velocity with ${l.toFixed(1)}× leverage. Tokens are being burned more than compounded. Focus on reusing prior context (templates, prompts, workflows) to build leverage.`;
+  return `No cascade data yet — run a few sessions and re-rank to see your tier. Yield is computed from four token pillars (input, output, cacheCreate, cacheRead).`;
+}
+
+export function _powerUserAssessment(klass, metrics) {
+  const l = metrics.leverage || 0;
+  const v = metrics.velocity || 0;
+  const band = bandOf(klass);
+
+  if (band === "apex")
+    return `You are an apex AI power user. Your SigRank class (${klass}) indicates you reuse prior work heavily (${l.toFixed(1)}× leverage), get more out of each token (${v.toFixed(2)} velocity), and keep input lean — both leverage and velocity held at once.`;
+  if (band === "high")
+    return `You are an AI power user. Your SigRank class (${klass}) indicates you reuse prior work heavily (${l.toFixed(1)}× leverage), get more out of each token (${v.toFixed(2)} velocity), and keep input lean. This is consistent with AI power-user behavior: iterative, efficient, multi-use patterns.`;
+  if (band === "mid")
+    return `You are becoming an AI power user. Your ${klass} class shows growing cache reuse (${l.toFixed(1)}× leverage) and ${v.toFixed(2)} output velocity. You're building the habits — increase context reuse to push into the ARCH band.`;
+  if (band === "early")
+    return `You are starting to compound. Your ${klass} class shows ${l.toFixed(1)}× leverage and ${v.toFixed(2)} velocity — cache reuse is beginning but input still dominates. The power-user shift: reuse prior context instead of starting fresh each time.`;
+  if (band === "entry")
+    return `You are not yet an AI power user. Your ${klass} class means tokens are being spent without compounding. The power-user shift: reuse prior context (prompts, templates, cached results) instead of starting fresh each time. Your leverage (${l.toFixed(1)}×) is the key metric to improve.`;
+  return `No cascade data yet — your tier is ${UNCLASSED}. Run a few sessions, re-rank, and the assessment will reflect your actual leverage and velocity.`;
+}
+
+export function _classMeaning(klass) {
+  const band = bandOf(klass);
+  if (band === "apex")
+    return "Apex power user — both leverage and velocity held at once. The rare closed-loop operator.";
+  if (band === "high")
+    return "AI power user archetype — disciplined, system-level reuse, high output per input.";
+  if (band === "mid")
+    return "Building momentum — moderate reuse, approaching power-user patterns.";
+  if (band === "early")
+    return "Compounding, not yet compounding well — cache reuse starting, input still dominates.";
+  if (band === "entry")
+    return "Early-stage — tokens burned more than compounded. Focus on cache reuse.";
+  return "No data — run sessions and re-rank to see your tier.";
+}
+
+export function _improvementSuggestion(klass, metrics) {
+  const l = metrics.leverage || 0;
+  const v = metrics.velocity || 0;
+  const band = bandOf(klass);
+
+  if (band === "apex")
+    return v < 1
+      ? "Your leverage is exceptional but velocity is under 1.0 — you're reading more cache than producing output. Push for more output per session."
+      : "You're at the apex. Maintain your cache architecture and experiment with longer sessions to compound yield further.";
+  if (band === "high")
+    return v < 1
+      ? "Your leverage is excellent but velocity is under 1.0 — you're reading more cache than producing output. Push for more output per session."
+      : "You're at the top tier. Maintain your cache architecture and experiment with longer sessions to compound yield further.";
+  if (band === "mid")
+    return l < 5
+      ? "Increase cache reuse: reuse prompts, templates, and workflows instead of starting from scratch. Each reused token multiplies your yield."
+      : "Your leverage is solid. Focus on output velocity — produce more per session to push your yield up.";
+  if (band === "early")
+    return "Start by reusing prior context. Instead of fresh prompts each time, build on cached results. Even a 2× increase in cache_read will dramatically improve your yield because input² is in the denominator.";
+  if (band === "entry")
+    return "Start by reusing prior context. Instead of fresh prompts each time, build on cached results. Even a 2× increase in cache_read will dramatically improve your yield because input² is in the denominator.";
+  return "No cascade data yet. Run a few sessions so the four token pillars are populated, then re-rank for an actionable suggestion.";
+}

package/tools/_helpers.mjs

@@ -0,0 +1,253 @@
+/**
+ * tools/_helpers.mjs — shared helpers for the SigRank MCP tool suite.
+ *
+ * Transport-free utilities used across multiple tool handlers:
+ * exec wrapper, curl fallback, fetch builder, upload stamp, platform pull,
+ * parse-warning merge, and watch-tokenpull cooldown state.
+ */
+
+import { createHash } from "node:crypto";
+import { execFile, execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pkgVersion } from "../lib/pkg-version.mjs";
+import {
+  tokenpull as pullLocal,
+  tokenpullCodex as pullCodex,
+  tokenpullAny,
+} from "../adapters/tokenpull.mjs";
+
+// Resolve local node_modules/.bin for bundled deps (ccusage, tokscale)
+const _pkgRoot = path.dirname(fileURLToPath(import.meta.url));
+const _localBin = path.join(_pkgRoot, "..", "node_modules", ".bin");
+const _envPath = `${_localBin}${process.env.PATH ? ":" + process.env.PATH : ""}`;
+
+export const DEFAULT_API_BASE =
+  process.env.SIGRANK_API_BASE || "https://signalaf.com";
+/** Default network timeout in ms (override via opts.fetchTimeout or SIGRANK_FETCH_TIMEOUT). */
+export const DEFAULT_FETCH_TIMEOUT =
+  Number(process.env.SIGRANK_FETCH_TIMEOUT) || 10_000;
+/** Max accepted length for a single paste/string arg (chars). Token counts are tiny; anything
+ *  past this is malformed or abusive — reject cleanly before parsing/POSTing (E2 hardening). */
+export const MAX_INPUT = 1_000_000;
+
+// E3: client-side auto-submit cooldown for watch_tokenpull. The server already dedups
+// identical snapshots (exact hash → 422), but a noisy poll loop with submit:true could still
+// churn the network/board with near-identical rows. Cap auto-submit to once per WATCH_SUBMIT_COOLDOWN_MS
+// per platform+window (in-memory, per process). Keyed by platform:window so different
+// platforms/windows don't block each other, and only armed on a non-error submit so a
+// network failure doesn't lock out retries for 5 minutes.
+export const WATCH_SUBMIT_COOLDOWN_MS = 5 * 60 * 1000;
+export const _lastWatchSubmitAt = new Map();
+
+// ASYNC FIX (2026-06-27): execFile wrapped in a Promise — replaces execSync for
+// defense-in-depth (shell injection prevention + non-blocking). The platform param
+// is enum-validated at the MCP schema level, but execFile also prevents shell
+// interpolation attacks by passing args as an array (no shell parsing).
+// BIN FIX (2026-06-27): PATH includes local node_modules/.bin so bundled deps
+// are found even when sigrank isn't globally installed.
+export function execFileAsync(cmd, args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    // NOTE: execFile does not accept a `stdio` option (it always pipes + buffers
+    // stdout/stderr against maxBuffer) — a previous `stdio` key here was silently ignored.
+    execFile(
+      cmd,
+      args,
+      {
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024,
+        env: { ...process.env, PATH: _envPath },
+      },
+      (err, stdout) => {
+        if (err) reject(err);
+        else resolve(stdout.toString());
+      },
+    );
+  });
+}
+
+/** Resolve this package's version for the User-Agent stamp (best-effort).
+ *  Thin wrapper over the shared lib/pkg-version.mjs helper so there is exactly
+ *  one version-resolution implementation in the repo. */
+export function agentVersionStamp() {
+  return pkgVersion();
+}
+
+/**
+ * curl-based fetch fallback for when Node's fetch is blocked by Vercel's bot
+ * protection (TLS fingerprinting). Returns a Response-like object with .ok,
+ * .status, .json(), .text(). Uses execFileSync for synchronous curl execution.
+ */
+export function curlFetch(url, init = {}, timeoutMs = 10_000) {
+  const args = [
+    "-s",
+    "-S",
+    "-w",
+    "\n__HTTP_STATUS__%{http_code}",
+    "--max-time",
+    String(Math.ceil(timeoutMs / 1000)),
+  ];
+  if (init.method) args.push("-X", init.method);
+  const headers = init.headers || {};
+  for (const [k, v] of Object.entries(headers)) {
+    args.push("-H", `${k}: ${v}`);
+  }
+  if (init.body) {
+    args.push("-d", init.body);
+  }
+  args.push(url);
+  let stdout;
+  try {
+    stdout = execFileSync("curl", args, {
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: timeoutMs + 2000,
+    });
+  } catch (e) {
+    throw new Error(`curl transport failed: ${e.message}`);
+  }
+  // Parse the status code from the trailer
+  const statusMatch = stdout.match(/__HTTP_STATUS__(\d+)$/);
+  const status = statusMatch ? parseInt(statusMatch[1], 10) : 0;
+  const bodyText = statusMatch ? stdout.slice(0, statusMatch.index) : stdout;
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => {
+      try {
+        return JSON.parse(bodyText);
+      } catch {
+        return {};
+      }
+    },
+    text: async () => bodyText,
+  };
+}
+
+// Every board upload from the MCP is hashed + timestamped (ddmmyy) — provenance + dedup.
+export function uploadStamp(content) {
+  const hash = createHash("sha256")
+    .update(JSON.stringify(content))
+    .digest("hex");
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  const ddmmyy =
+    p(d.getUTCDate()) +
+    p(d.getUTCMonth() + 1) +
+    String(d.getUTCFullYear()).slice(-2);
+  return {
+    content_hash: hash,
+    submitted_ddmmyy: ddmmyy,
+    submitted_at: d.toISOString(),
+  };
+}
+
+// Pull a platform's local usage → 4 windows of canonical pillars. Routes through
+// tokenpullAny() which handles Claude (native), Codex (estimated io_ratio), and all
+// other adapters from the registry. opts.adapter overrides for tests.
+export async function pullByPlatform(platform, opts = {}) {
+  if (opts.adapter) {
+    // Test injection: bypass registry and use the mock adapter directly
+    if (platform === "codex") {
+      let ioRatio = 2.0;
+      try {
+        const c = await pullLocal({});
+        const all = c.windows.find((w) => w.window === "all");
+        if (all && all.pillars.output > 0)
+          ioRatio = all.pillars.input / all.pillars.output;
+      } catch {
+        /* no Claude data → Alpha 2.0 */
+      }
+      return pullCodex({ ioRatio, adapter: opts.adapter, now: opts.now });
+    }
+    return pullLocal({ adapter: opts.adapter, now: opts.now });
+  }
+  return tokenpullAny(platform || "claude", opts);
+}
+
+/**
+ * Build a fetch wrapper with timeout + curl fallback + User-Agent stamp.
+ * Returns { doFetch, fetchJson } bound to the given opts.
+ */
+export function buildFetch(opts = {}) {
+  const apiBase = opts.apiBase || DEFAULT_API_BASE;
+  const timeoutMs = opts.fetchTimeout ?? DEFAULT_FETCH_TIMEOUT;
+  const rawFetch = opts.fetchImpl || fetch;
+
+  const doFetch = async (url, init = {}) => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const headers = {
+      "user-agent": `node/${process.version} sigrank-mcp/${agentVersionStamp()}`,
+      ...(init.headers || {}),
+    };
+    try {
+      const res = await rawFetch(url, { ...init, headers, signal: ac.signal });
+      // Detect Vercel security checkpoint (403 + HTML body, not JSON)
+      if (res.status === 403) {
+        const text = await res.text();
+        if (
+          text.includes("Vercel Security Checkpoint") ||
+          text.includes("x-vercel-challenge")
+        ) {
+          // Fall back to curl transport
+          return curlFetch(url, init, timeoutMs);
+        }
+        // Real 403 from the API — return a mock response object
+        return {
+          ok: false,
+          status: 403,
+          json: async () => {
+            try {
+              return JSON.parse(text);
+            } catch {
+              return {};
+            }
+          },
+          text: async () => text,
+        };
+      }
+      return res;
+    } catch (e) {
+      if (e.name === "AbortError") throw e;
+      // Network error — try curl as fallback
+      try {
+        return await curlFetch(url, init, timeoutMs);
+      } catch {
+        throw e;
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  const fetchJson = async (path) => {
+    const res = await doFetch(`${apiBase}${path}`, {
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`SigRank API ${path} → HTTP ${res.status}`);
+    return res.json();
+  };
+
+  return { apiBase, doFetch, fetchJson };
+}
+
+// Helper: attach _parseWarnings from pillars onto the cascade result so they
+// are always visible in the tool output for review.
+export function withParseWarnings(pillars, cascadeResult) {
+  if (pillars._parseWarnings && pillars._parseWarnings.length > 0) {
+    const existing = cascadeResult.warnings || [];
+    return {
+      ...cascadeResult,
+      warnings: [
+        ...existing,
+        ...pillars._parseWarnings.map((w) => `parse:${w}`),
+      ],
+    };
+  }
+  return cascadeResult;
+}
+
+// tokenpull window key → the board's window_type enum.
+export const WINDOW_TYPE = { "7d": "7d", "30d": "30d", "90d": "90d", all: "all_time" };