thumbgate 1.27.19 → 1.27.20

package/scripts/action-receipts.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Action Receipts — outcome-paired lessons.
+ *
+ * Pairs each tracked tool call with its concrete result (diff / exit code /
+ * test outcome / state hash) so that a promoted prevention rule can encode
+ * "this action -> this outcome" rather than only a bare thumbs signal.
+ *
+ * Receipts are persisted as JSONL beside the other feedback artifacts
+ * (FEEDBACK_DIR/action-receipts.jsonl) using the same project-scoped
+ * resolution as the rest of the feedback pipeline (feedback-paths).
+ *
+ * This module is self-contained: it only depends on feedback-paths + fs and
+ * makes no edits to shared files. It is consumed from the MCP adapter wiring
+ * step (record_action_receipt / get_action_receipts tools) and threads into
+ * capture_feedback's lesson pipeline + construct_context_pack.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getFeedbackPaths } = require('./feedback-paths');
+
+const RECEIPTS_FILE = 'action-receipts.jsonl';
+
+/**
+ * Resolve the absolute path to the receipts JSONL for the active project.
+ * @param {object} [options] - Passed through to getFeedbackPaths (e.g. for tests).
+ * @returns {string}
+ */
+function getReceiptsPath(options = {}) {
+  const { FEEDBACK_DIR } = getFeedbackPaths(options);
+  return path.join(FEEDBACK_DIR, RECEIPTS_FILE);
+}
+
+function ensureDirFor(filePath) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  } catch {
+    // best-effort; write will surface a real error if the dir truly cannot exist
+  }
+}
+
+function safeString(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  try {
+    return String(value);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Build a short, human-readable summary of a tool input for the paired-lesson
+ * string. Never throws; clamps length so the lesson stays compact.
+ * @param {*} toolInput
+ * @returns {string}
+ */
+function summarizeInput(toolInput) {
+  if (toolInput === null || toolInput === undefined) return '';
+  if (typeof toolInput === 'string') return clampText(toolInput, 120);
+
+  if (typeof toolInput === 'object') {
+    // Prefer the most lesson-relevant keys when present.
+    const preferredKeys = ['file', 'filePath', 'path', 'command', 'cmd', 'query', 'pattern'];
+    for (const key of preferredKeys) {
+      if (toolInput[key]) {
+        return `${key}=${clampText(safeString(toolInput[key]), 100)}`;
+      }
+    }
+    try {
+      return clampText(JSON.stringify(toolInput), 120);
+    } catch {
+      return '';
+    }
+  }
+
+  return clampText(safeString(toolInput), 120);
+}
+
+function clampText(text, max) {
+  const str = safeString(text);
+  if (str.length <= max) return str;
+  return `${str.slice(0, Math.max(0, max - 1))}…`;
+}
+
+/**
+ * Derive a compact outcome descriptor from an outcome object.
+ * @param {object} outcome
+ * @returns {string}
+ */
+function summarizeOutcome(outcome) {
+  if (!outcome || typeof outcome !== 'object') return 'unknown outcome';
+  const parts = [];
+  if (outcome.testOutcome) parts.push(`tests:${clampText(safeString(outcome.testOutcome), 40)}`);
+  if (outcome.exitCode !== undefined && outcome.exitCode !== null) {
+    parts.push(`exit:${outcome.exitCode}`);
+  }
+  if (outcome.diff) {
+    const diffStr = safeString(outcome.diff);
+    parts.push(`diff:${diffStr.length}b`);
+  }
+  if (outcome.stateHash) parts.push(`hash:${clampText(safeString(outcome.stateHash), 12)}`);
+  return parts.length > 0 ? parts.join(' ') : 'no outcome fields';
+}
+
+/**
+ * Normalize a raw record_action_receipt payload into a stored receipt object.
+ * Accepts either a nested { outcome: {...} } shape or flat top-level fields
+ * (diff / exitCode / testOutcome / stateHash) as the MCP tool surfaces them.
+ * @param {object} params
+ * @returns {object}
+ */
+function normalizeReceipt(params = {}) {
+  const outcomeSource = (params.outcome && typeof params.outcome === 'object')
+    ? params.outcome
+    : params;
+
+  const outcome = {
+    diff: outcomeSource.diff !== undefined ? outcomeSource.diff : null,
+    exitCode: (outcomeSource.exitCode !== undefined && outcomeSource.exitCode !== null)
+      ? Number(outcomeSource.exitCode)
+      : null,
+    testOutcome: outcomeSource.testOutcome !== undefined ? outcomeSource.testOutcome : null,
+    stateHash: outcomeSource.stateHash !== undefined ? outcomeSource.stateHash : null,
+  };
+
+  return {
+    actionId: safeString(params.actionId) || null,
+    toolName: params.toolName !== undefined ? safeString(params.toolName) : null,
+    toolInput: params.toolInput !== undefined ? params.toolInput : null,
+    outcome,
+    recordedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Append a receipt to the JSONL ledger.
+ * @param {object} params - { actionId, toolName, toolInput, outcome:{ diff, exitCode, testOutcome, stateHash } }
+ * @param {object} [options] - feedback-paths options (e.g. for tests).
+ * @returns {object} The stored receipt record (with recorded:true).
+ */
+function recordReceipt(params = {}, options = {}) {
+  const receipt = normalizeReceipt(params);
+  const receiptsPath = getReceiptsPath(options);
+  ensureDirFor(receiptsPath);
+  fs.appendFileSync(receiptsPath, `${JSON.stringify(receipt)}\n`, 'utf8');
+  return { recorded: true, ...receipt };
+}
+
+/**
+ * Read all receipts from the ledger (oldest first). Tolerates malformed lines.
+ * @param {object} [options]
+ * @returns {object[]}
+ */
+function readAllReceipts(options = {}) {
+  const receiptsPath = getReceiptsPath(options);
+  let raw;
+  try {
+    raw = fs.readFileSync(receiptsPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const receipts = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      receipts.push(JSON.parse(trimmed));
+    } catch {
+      // skip malformed line
+    }
+  }
+  return receipts;
+}
+
+/**
+ * Return the most recent receipt for a given actionId, or null.
+ * @param {string} actionId
+ * @param {object} [options]
+ * @returns {object|null}
+ */
+function getReceiptForAction(actionId, options = {}) {
+  if (!actionId) return null;
+  const target = safeString(actionId);
+  const receipts = readAllReceipts(options);
+  for (let i = receipts.length - 1; i >= 0; i -= 1) {
+    if (safeString(receipts[i].actionId) === target) return receipts[i];
+  }
+  return null;
+}
+
+/**
+ * Return the last n receipts (most recent last, preserving chronological order).
+ * @param {number} [n=20]
+ * @param {object} [options]
+ * @returns {object[]}
+ */
+function getRecentReceipts(n = 20, options = {}) {
+  const limit = Number.isFinite(Number(n)) && Number(n) > 0 ? Math.floor(Number(n)) : 20;
+  const receipts = readAllReceipts(options);
+  return receipts.slice(-limit);
+}
+
+/**
+ * Build the "action -> outcome" lesson string for a matched receipt.
+ * @param {object} receipt
+ * @returns {string}
+ */
+function buildOutcomePairedLesson(receipt) {
+  if (!receipt) return '';
+  const toolName = safeString(receipt.toolName) || 'action';
+  const inputSummary = summarizeInput(receipt.toolInput);
+  const outcomeSummary = summarizeOutcome(receipt.outcome);
+  return `${toolName}(${inputSummary}) -> ${outcomeSummary}`;
+}
+
+/**
+ * Resolve which actionId a feedback payload refers to. Supports both the
+ * legacy `lastAction` shape (object or string) and a flat `actionId` field.
+ * @param {object} feedbackParams
+ * @returns {string|null}
+ */
+function resolveFeedbackActionId(feedbackParams = {}) {
+  if (feedbackParams.actionId) return safeString(feedbackParams.actionId);
+
+  const lastAction = feedbackParams.lastAction;
+  if (!lastAction) return null;
+  if (typeof lastAction === 'string') return safeString(lastAction);
+  if (typeof lastAction === 'object') {
+    if (lastAction.actionId) return safeString(lastAction.actionId);
+    if (lastAction.id) return safeString(lastAction.id);
+  }
+  return null;
+}
+
+/**
+ * Enrich a capture_feedback payload with the most recent matching receipt's
+ * outcome so the lesson pipeline encodes action->outcome. If no receipt
+ * matches, the original payload is returned unchanged (never throws).
+ * @param {object} feedbackParams
+ * @param {object} [options]
+ * @returns {object}
+ */
+function pairFeedbackWithReceipt(feedbackParams = {}, options = {}) {
+  const actionId = resolveFeedbackActionId(feedbackParams);
+  if (!actionId) return feedbackParams;
+
+  let receipt = null;
+  try {
+    receipt = getReceiptForAction(actionId, options);
+  } catch {
+    return feedbackParams;
+  }
+  if (!receipt) return feedbackParams;
+
+  const outcomePairedLesson = buildOutcomePairedLesson(receipt);
+
+  return {
+    ...feedbackParams,
+    outcome: { ...receipt.outcome },
+    outcomePairedLesson,
+    receiptActionId: actionId,
+  };
+}
+
+/**
+ * Build construct_context_pack-shaped candidate entries from receipts that
+ * match a free-text query. Returns [{ namespace, text, score }].
+ * @param {string} query
+ * @param {number} [limit=5]
+ * @param {object} [options]
+ * @returns {Array<{namespace:string, text:string, score:number}>}
+ */
+function buildReceiptContextEntries(query, limit = 5, options = {}) {
+  const cap = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.floor(Number(limit)) : 5;
+  const receipts = readAllReceipts(options);
+  if (receipts.length === 0) return [];
+
+  const queryTokens = safeString(query)
+    .toLowerCase()
+    .split(/[^a-z0-9]+/i)
+    .filter(Boolean);
+
+  const scored = receipts.map((receipt) => {
+    const lesson = buildOutcomePairedLesson(receipt);
+    const haystack = `${lesson} ${safeString(receipt.toolName)} ${summarizeInput(receipt.toolInput)}`.toLowerCase();
+    let score = 0;
+    for (const token of queryTokens) {
+      if (haystack.includes(token)) score += 1;
+    }
+    const text = `${lesson} [outcome: ${summarizeOutcome(receipt.outcome)}]`;
+    return { namespace: 'action-receipts', text, score };
+  });
+
+  // When the query is empty, surface the most recent receipts (score 0 but
+  // still useful for the pack); otherwise rank by token overlap.
+  const ranked = queryTokens.length === 0
+    ? scored.slice(-cap).reverse()
+    : scored
+      .filter((entry) => entry.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, cap);
+
+  return ranked;
+}
+
+module.exports = {
+  RECEIPTS_FILE,
+  getReceiptsPath,
+  recordReceipt,
+  readAllReceipts,
+  getReceiptForAction,
+  getRecentReceipts,
+  buildOutcomePairedLesson,
+  pairFeedbackWithReceipt,
+  buildReceiptContextEntries,
+  // exposed for testing / reuse
+  summarizeInput,
+  summarizeOutcome,
+  resolveFeedbackActionId,
+};

package/scripts/activation-quickstart.js

@@ -0,0 +1,187 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Activation: guided first prevention rule + a live demonstrated block.
+//
+// ~98.5% of `init` users never promote their first rule, so they never see
+// "ThumbGate just blocked a repeat mistake" — the aha moment that drives
+// activation (and, downstream, conversion). `quickstart` walks a new user
+// through capturing one real example, promoting it to a block rule, and then
+// firing that rule against the exact action so they watch it get blocked.
+//
+// SAFETY: this is additive and lives in its own module. `init` is untouched.
+// The interactive flow ONLY runs in a real TTY. Non-interactive / piped / CI
+// invocations print a one-line hint and exit 0 without prompting or hanging.
+// ---------------------------------------------------------------------------
+
+const path = require('node:path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const PRO_URL = 'https://thumbgate.ai';
+
+// Turn a free-text mistake description into a safe, literal gate pattern. We
+// escape regex metacharacters so arbitrary user input can never produce an
+// invalid or runaway regex inside the gates engine.
+function escapeRegex(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+function pkgVersion() {
+  try {
+    return require(path.join(PKG_ROOT, 'package.json')).version;
+  } catch {
+    // Version is cosmetic in the banner; fall back if package.json is unreadable.
+    return '0.0.0';
+  }
+}
+
+// Core, dependency-injected activation flow so it is testable without a real
+// TTY. Callers provide ask() (returns a Promise<string>), out() (line writer),
+// and isTTY. Returns a structured result describing what was promoted/blocked.
+//
+// Optional injectables (deps) keep the test hermetic and let the CLI pass the
+// real modules:
+//   deps.forcePromote(pattern, action) -> { gateId, totalGates }
+//   deps.runGate(input) -> Promise<rawJsonString>
+//   deps.captureFeedback(params)
+//   deps.trackEvent(name, props)
+async function runActivationFlow({ ask, out, isTTY, deps = {} }) {
+  // Hard safety gate: never prompt or hang in non-interactive contexts.
+  if (!isTTY) {
+    out('thumbgate quickstart is an interactive walkthrough — run it in a terminal.');
+    out('Non-interactive setup: npx thumbgate init   (or: npx thumbgate quick-start)');
+    return { interactive: false, promoted: false, blocked: false };
+  }
+
+  const forcePromote = deps.forcePromote
+    || require(path.join(PKG_ROOT, 'scripts', 'auto-promote-gates')).forcePromote;
+  const runGate = deps.runGate
+    || ((input) => require(path.join(PKG_ROOT, 'scripts', 'gates-engine')).runAsync(input));
+  let captureFeedback = deps.captureFeedback;
+  if (captureFeedback === undefined) {
+    try {
+      ({ captureFeedback } = require(path.join(PKG_ROOT, 'scripts', 'feedback-loop')));
+    } catch {
+      // Feedback capture is a nice-to-have here; the rule + block is the aha.
+      captureFeedback = null;
+    }
+  }
+  const trackEvent = deps.trackEvent || (() => {});
+
+  out('');
+  out(`thumbgate quickstart v${pkgVersion()}`);
+  out('');
+  out("Let's set up your first prevention rule and watch it block a repeat mistake.");
+  out('');
+  out('Think of one thing an AI agent did that you never want it to do again.');
+  out('Examples: "git push --force to main", "rm -rf node_modules", "edit .env directly".');
+  out('');
+
+  let mistake = String(await ask('The mistake to block: ') || '').trim();
+  if (!mistake) {
+    mistake = 'git push --force to main';
+    out(`(using a starter example: ${mistake})`);
+  }
+
+  // 1. Capture it as a real thumbs-down example (best-effort).
+  if (typeof captureFeedback === 'function') {
+    try {
+      captureFeedback({
+        signal: 'down',
+        context: mistake,
+        whatWentWrong: mistake,
+        whatToChange: `Block this action: ${mistake}`,
+        tags: 'quickstart,activation,first-rule',
+        gateAction: 'block',
+      });
+    } catch {
+      // Capture failure should not abort the activation aha.
+    }
+  }
+
+  // 2. Promote it into a hard block rule using the existing primitive.
+  const pattern = escapeRegex(mistake);
+  const promotion = forcePromote(pattern, 'block');
+  out('');
+  out(`  Rule promoted: ${promotion.gateId} [block]`);
+  out(`  Active rules now: ${promotion.totalGates}`);
+
+  // 3. Demonstrate the block. Force strict enforcement for the demo so the
+  //    user's brand-new rule hard-blocks (default posture is warn-by-default).
+  //    We restore the prior value so we never mutate the user's environment.
+  const priorStrict = process.env.THUMBGATE_STRICT_ENFORCEMENT;
+  process.env.THUMBGATE_STRICT_ENFORCEMENT = '1';
+  let verdict;
+  try {
+    const demoInput = { tool_name: 'Bash', tool_input: { command: mistake } };
+    const raw = await runGate(demoInput);
+    verdict = JSON.parse(raw);
+  } finally {
+    if (priorStrict === undefined) delete process.env.THUMBGATE_STRICT_ENFORCEMENT;
+    else process.env.THUMBGATE_STRICT_ENFORCEMENT = priorStrict;
+  }
+
+  const decision = verdict?.decision
+    || verdict?.hookSpecificOutput?.permissionDecision;
+  const blocked = decision === 'block' || decision === 'deny';
+
+  out('');
+  if (blocked) {
+    out('  | ThumbGate just blocked it.');
+    out(`  | Action attempted: ${mistake}`);
+    out('  | Verdict: BLOCKED — the agent cannot repeat this mistake.');
+  } else {
+    // Even in warn posture the action is flagged + logged. Be honest about it.
+    out('  | ThumbGate flagged it.');
+    out(`  | Action attempted: ${mistake}`);
+    out('  | Verdict: flagged and logged. Set THUMBGATE_STRICT_ENFORCEMENT=1 to hard-block.');
+  }
+
+  // 4. Tie the value the user just saw to what Pro keeps working.
+  out('');
+  out('  That rule lives in this project. Pro keeps your rules — and the mistakes');
+  out('  you teach it — synced across every machine and agent runtime you work in,');
+  out(`  so the block you just saw follows your whole team. ${PRO_URL}/pricing`);
+  out('');
+
+  try { trackEvent('cli_quickstart_activated', { command: 'quickstart', blocked }); } catch { /* telemetry best-effort */ }
+
+  return {
+    interactive: true,
+    promoted: true,
+    blocked,
+    gateId: promotion.gateId,
+    pattern,
+    mistake,
+    verdict,
+  };
+}
+
+// CLI entrypoint: wires runActivationFlow to a real readline prompt + stdout.
+function quickstart() {
+  const isTTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
+  const out = (line = '') => console.log(line);
+
+  const trackEvent = (() => {
+    try { return require(path.join(PKG_ROOT, 'scripts', 'cli-telemetry')).trackEvent; } catch { return () => {}; }
+  })();
+
+  if (!isTTY) {
+    // Mirror the non-interactive branch without opening readline (which would
+    // otherwise keep the process alive waiting for input that never comes).
+    return runActivationFlow({ ask: async () => '', out, isTTY: false, deps: { trackEvent } });
+  }
+
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+  return runActivationFlow({ ask, out, isTTY: true, deps: { trackEvent } })
+    .catch((err) => {
+      console.error(`quickstart error: ${err?.message ?? err}`);
+      process.exitCode = 1;
+    })
+    .finally(() => rl.close());
+}
+
+module.exports = { runActivationFlow, quickstart, escapeRegex };