thumbgate 1.0.0 → 1.2.0

package/scripts/docker-sandbox-planner.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+
+const { classifyCommand } = require('./operational-integrity');
+
+const HIGH_RISK_ACTION_TYPES = new Set([
+  'shell.exec',
+  'file.delete',
+  'upload',
+  'message.send',
+]);
+
+function normalizeText(value) {
+  if (value === undefined || value === null) return '';
+  return String(value).trim();
+}
+
+function normalizeStringArray(values = []) {
+  if (!Array.isArray(values)) return [];
+  return Array.from(new Set(
+    values
+      .map((value) => normalizeText(value))
+      .filter(Boolean),
+  ));
+}
+
+function normalizeRiskBand(value) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (['very_high', 'high', 'medium', 'low'].includes(normalized)) {
+    return normalized;
+  }
+  if (normalized === 'critical') return 'very_high';
+  return 'low';
+}
+
+function quoteShellArg(value) {
+  return `'${String(value).replaceAll('\'', String.raw`'\''`)}'`;
+}
+
+function buildNetworkPolicy(input = {}) {
+  const allowedHosts = normalizeStringArray(input.allowedHosts || input.egressAllowlist);
+  if (input.requiresNetwork !== true) {
+    return {
+      mode: 'deny_all',
+      allowedHosts: [],
+    };
+  }
+  return {
+    mode: allowedHosts.length > 0 ? 'allow_list' : 'egress_enabled',
+    allowedHosts,
+  };
+}
+
+function buildLaunchers(workspacePath) {
+  const suffix = workspacePath ? ` shell ${quoteShellArg(workspacePath)}` : ' shell';
+  return {
+    standalone: `sbx run${suffix}`,
+    dockerDesktop: `docker sandbox run${suffix}`,
+    followUp: workspacePath
+      ? [
+        'sbx list',
+        'docker sandbox ls',
+      ]
+      : [],
+  };
+}
+
+function buildSummary(shouldSandbox, recommendation) {
+  if (!shouldSandbox) {
+    return 'Current action can stay on the normal local execution path.';
+  }
+  if (recommendation === 'required') {
+    return 'Route this action into Docker Sandboxes before retrying so the run happens inside a disposable microVM instead of on the host.';
+  }
+  return 'Prefer Docker Sandboxes for this action to reduce host blast radius while keeping local autonomy.';
+}
+
+function buildWhy({
+  recommendation,
+  command,
+  riskBand,
+  actionType,
+  affectedFiles,
+}) {
+  const lines = [];
+  if (recommendation === 'required') {
+    lines.push('The predicted action is destructive or release-sensitive enough to justify host isolation.');
+  } else if (recommendation === 'recommended') {
+    lines.push('The predicted action is high-risk enough that isolated execution meaningfully reduces host blast radius.');
+  } else {
+    lines.push('The current action does not need a dedicated Docker sandbox boundary.');
+  }
+
+  if (command && /\brm\s+-rf\b/i.test(command)) {
+    lines.push('Recursive delete commands are safer when the filesystem boundary lives inside a disposable microVM.');
+  }
+  if (command && /\bgit\s+push\b.*(?:--force|-f)\b/i.test(command)) {
+    lines.push('Force-push flows should run in an isolated lane so host credentials and unrelated state stay out of scope.');
+  }
+  if (command && /\b(?:gh\s+pr\s+(?:create|merge)|npm\s+publish|yarn\s+publish|pnpm\s+publish)\b/i.test(command)) {
+    lines.push('PR, merge, and publish flows are governance-sensitive and benefit from a disposable execution boundary.');
+  }
+  if (HIGH_RISK_ACTION_TYPES.has(actionType)) {
+    lines.push(`Action type ${actionType} is in the high-risk set for local execution.`);
+  }
+  if (riskBand === 'very_high' || riskBand === 'high') {
+    lines.push(`Risk band ${riskBand} predicts elevated blast radius on the local host.`);
+  }
+  if (affectedFiles.length >= 4) {
+    lines.push(`The change touches ${affectedFiles.length} files, so host isolation improves recovery if the run goes sideways.`);
+  }
+  return lines;
+}
+
+function buildDockerSandboxPlan(input = {}) {
+  const toolName = normalizeText(input.toolName);
+  const actionType = normalizeText(input.actionType)
+    || (toolName === 'Bash' ? 'shell.exec' : '');
+  const command = normalizeText(input.command);
+  const repoPath = normalizeText(input.repoPath);
+  const workspacePath = repoPath ? path.resolve(repoPath) : null;
+  const affectedFiles = normalizeStringArray(input.affectedFiles || input.changedFiles || input.files);
+  const riskBand = normalizeRiskBand(input.riskBand || input.band);
+  const riskScore = Number.isFinite(Number(input.riskScore))
+    ? Number(Number(input.riskScore).toFixed(4))
+    : null;
+  const commandInfo = classifyCommand(command);
+  const destructiveCommand = /\brm\s+-rf\b/i.test(command)
+    || /\bgit\s+push\b.*(?:--force|-f)\b/i.test(command)
+    || /\bgh\s+pr\s+merge\b.*--admin\b/i.test(command);
+  const governedCommand = Boolean(
+    commandInfo.isPrCreate
+      || commandInfo.isPrMerge
+      || commandInfo.isPublish
+      || commandInfo.isReleaseCreate
+      || commandInfo.isTagCreate
+  );
+  const highRiskAction = HIGH_RISK_ACTION_TYPES.has(actionType)
+    || destructiveCommand
+    || governedCommand
+    || riskBand === 'high'
+    || riskBand === 'very_high';
+
+  let recommendation = 'not_needed';
+  if (destructiveCommand || commandInfo.isPublish || commandInfo.isReleaseCreate || actionType === 'upload' || actionType === 'message.send') {
+    recommendation = 'required';
+  } else if (highRiskAction || affectedFiles.length >= 4) {
+    recommendation = 'recommended';
+  }
+
+  const shouldSandbox = recommendation !== 'not_needed';
+  const networkPolicy = buildNetworkPolicy({
+    requiresNetwork: input.requiresNetwork === true || governedCommand || commandInfo.isPublish || actionType === 'upload' || actionType === 'message.send',
+    allowedHosts: input.allowedHosts,
+    egressAllowlist: input.egressAllowlist,
+  });
+  const launchers = buildLaunchers(workspacePath);
+  const summary = buildSummary(shouldSandbox, recommendation);
+
+  return {
+    plannerVersion: 'docker-sandbox-plan-v1',
+    shouldSandbox,
+    recommendation,
+    summary,
+    sandboxKind: shouldSandbox ? 'docker_microvm' : 'host',
+    workspacePath,
+    actionType: actionType || null,
+    riskBand,
+    riskScore,
+    command: command || null,
+    affectedFiles,
+    networkPolicy,
+    launchers,
+    claims: shouldSandbox ? {
+      isolationBoundary: 'microvm',
+      hostAccess: 'bounded_outside_host',
+      dockerDaemon: 'private_inside_sandbox',
+      workspaceStrategy: workspacePath ? 'directory_sync' : 'ephemeral',
+    } : null,
+    why: buildWhy({
+      recommendation,
+      command,
+      riskBand,
+      actionType,
+      affectedFiles,
+    }),
+  };
+}
+
+module.exports = {
+  HIGH_RISK_ACTION_TYPES,
+  buildDockerSandboxPlan,
+  buildLaunchers,
+  buildNetworkPolicy,
+  buildSummary,
+  normalizeRiskBand,
+};
+
+if (require.main === module) {
+  const plan = buildDockerSandboxPlan({
+    toolName: process.argv[2] || 'Bash',
+    command: process.argv.slice(3).join(' '),
+    repoPath: process.cwd(),
+  });
+  console.log(JSON.stringify(plan, null, 2));
+}

package/scripts/export-hf-dataset.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * HuggingFace Dataset Exporter
+ *
+ * Exports ThumbGate agent traces as a HuggingFace-compatible dataset in two formats:
+ *
+ * 1. Agent Traces (traces split) — raw feedback entries with tool calls, signals,
+ *    context, and outcomes. Matches the "share your agent traces" initiative.
+ *
+ * 2. DPO Preferences (preferences split) — chosen/rejected preference pairs
+ *    derived from error→learning memory promotion. Ready for DPO/RLHF training.
+ *
+ * Output: Parquet-compatible JSONL files + dataset_info.json (HF Dataset Card metadata).
+ *
+ * HuggingFace Datasets format:
+ *   dataset_dir/
+ *     dataset_info.json        — metadata, features schema, splits
+ *     traces.jsonl             — agent trace rows
+ *     preferences.jsonl        — DPO preference pair rows
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveFeedbackDir } = require('./feedback-paths');
+const { exportDpoFromMemories } = require('./export-dpo-pairs');
+const { getProvenance } = require('./contextfs');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readJSONL(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  const raw = fs.readFileSync(filePath, 'utf-8').trim();
+  if (!raw) return [];
+  return raw
+    .split('\n')
+    .map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function writeJSONL(filePath, rows) {
+  const content = rows.map((row) => JSON.stringify(row)).join('\n');
+  fs.writeFileSync(filePath, content ? `${content}\n` : '');
+}
+
+// ---------------------------------------------------------------------------
+// PII / path redaction
+// ---------------------------------------------------------------------------
+
+function redactPaths(text) {
+  if (!text || typeof text !== 'string') return text || '';
+  return text
+    .replace(/\/Users\/[^\s/]+/g, '/Users/redacted')
+    .replace(/\/home\/[^\s/]+/g, '/home/redacted')
+    .replace(/C:\\Users\\[^\s\\]+/g, 'C:\\Users\\redacted');
+}
+
+function redactEntry(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === 'string') {
+      out[key] = redactPaths(value);
+    } else if (Array.isArray(value)) {
+      out[key] = value.map((v) => (typeof v === 'string' ? redactPaths(v) : v));
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Trace row builder — converts feedback-log entries to HF trace rows
+// ---------------------------------------------------------------------------
+
+function buildTraceRow(entry, index) {
+  return {
+    trace_id: entry.id || `trace_${index}`,
+    timestamp: entry.timestamp || null,
+    signal: entry.signal || entry.feedback || 'unknown',
+    tool_name: entry.toolName || entry.actionType || 'unknown',
+    context: redactPaths(entry.context || ''),
+    what_worked: redactPaths(entry.whatWorked || ''),
+    what_went_wrong: redactPaths(entry.whatWentWrong || ''),
+    what_to_change: redactPaths(entry.whatToChange || ''),
+    tags: Array.isArray(entry.tags) ? entry.tags : [],
+    failure_type: entry.failureType || null,
+    source: 'thumbgate',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Preference row builder — converts DPO pairs to HF preference rows
+// ---------------------------------------------------------------------------
+
+function buildPreferenceRow(pair, index) {
+  return {
+    pair_id: `pref_${index}`,
+    prompt: redactPaths(pair.prompt || ''),
+    chosen: redactPaths(pair.chosen || ''),
+    rejected: redactPaths(pair.rejected || ''),
+    match_score: pair.metadata ? pair.metadata.matchScore : null,
+    matched_keys: pair.metadata ? pair.metadata.matchedKeys || [] : [],
+    rubric_delta: pair.metadata && pair.metadata.rubric
+      ? pair.metadata.rubric.weightedDelta
+      : null,
+    source: 'thumbgate',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dataset info (HuggingFace Dataset Card metadata)
+// ---------------------------------------------------------------------------
+
+function buildDatasetInfo({ traceCount, preferenceCount, exportedAt }) {
+  return {
+    dataset_info: {
+      description: 'Agent traces and DPO preference pairs from ThumbGate — pre-action gates for AI coding agents. Contains real-world tool call feedback, failure patterns, and learned corrections.',
+      citation: '',
+      homepage: 'https://github.com/IgorGanapolsky/ThumbGate',
+      license: 'MIT',
+      features: {
+        traces: {
+          trace_id: { dtype: 'string' },
+          timestamp: { dtype: 'string' },
+          signal: { dtype: 'string' },
+          tool_name: { dtype: 'string' },
+          context: { dtype: 'string' },
+          what_worked: { dtype: 'string' },
+          what_went_wrong: { dtype: 'string' },
+          what_to_change: { dtype: 'string' },
+          tags: { dtype: 'list', inner: { dtype: 'string' } },
+          failure_type: { dtype: 'string' },
+          source: { dtype: 'string' },
+        },
+        preferences: {
+          pair_id: { dtype: 'string' },
+          prompt: { dtype: 'string' },
+          chosen: { dtype: 'string' },
+          rejected: { dtype: 'string' },
+          match_score: { dtype: 'float32' },
+          matched_keys: { dtype: 'list', inner: { dtype: 'string' } },
+          rubric_delta: { dtype: 'float32' },
+          source: { dtype: 'string' },
+        },
+      },
+      splits: {
+        traces: { num_examples: traceCount },
+        preferences: { num_examples: preferenceCount },
+      },
+    },
+    exported_at: exportedAt,
+    exporter: 'thumbgate/export-hf-dataset',
+    version: '1.0.0',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main export function
+// ---------------------------------------------------------------------------
+
+/**
+ * Export ThumbGate data as a HuggingFace-compatible dataset.
+ *
+ * @param {Object} options
+ * @param {string} [options.outputDir] - Directory to write dataset files
+ * @param {string} [options.feedbackDir] - Override feedback data directory
+ * @param {boolean} [options.includeProvenance] - Include provenance events in traces
+ * @returns {Object} Export summary
+ */
+function exportHfDataset(options = {}) {
+  const feedbackDir = options.feedbackDir || resolveFeedbackDir();
+  const outputDir = options.outputDir || path.join(feedbackDir, 'hf-dataset');
+  const includeProvenance = options.includeProvenance !== false;
+
+  ensureDir(outputDir);
+
+  // --- Traces split ---
+  const feedbackLogPath = path.join(feedbackDir, 'feedback-log.jsonl');
+  const feedbackEntries = readJSONL(feedbackLogPath);
+  const traceRows = feedbackEntries.map((entry, i) => buildTraceRow(redactEntry(entry), i));
+
+  // Optionally append provenance events as traces
+  if (includeProvenance) {
+    try {
+      const provenanceEvents = getProvenance(200);
+      for (const evt of provenanceEvents) {
+        traceRows.push({
+          trace_id: evt.id || `prov_${traceRows.length}`,
+          timestamp: evt.timestamp || null,
+          signal: 'provenance',
+          tool_name: evt.type || 'context_assembly',
+          context: redactPaths(JSON.stringify(evt).slice(0, 500)),
+          what_worked: '',
+          what_went_wrong: '',
+          what_to_change: '',
+          tags: ['provenance'],
+          failure_type: null,
+          source: 'thumbgate',
+        });
+      }
+    } catch {
+      // Provenance read failure should not break export
+    }
+  }
+
+  writeJSONL(path.join(outputDir, 'traces.jsonl'), traceRows);
+
+  // --- Preferences split ---
+  const memoryLogPath = path.join(feedbackDir, 'memory-log.jsonl');
+  const memories = readJSONL(memoryLogPath);
+  let preferenceRows = [];
+
+  if (memories.length > 0) {
+    try {
+      const dpoResult = exportDpoFromMemories(memories);
+      preferenceRows = dpoResult.pairs.map((pair, i) => buildPreferenceRow(pair, i));
+    } catch {
+      // DPO export failure should not break the traces export
+    }
+  }
+
+  writeJSONL(path.join(outputDir, 'preferences.jsonl'), preferenceRows);
+
+  // --- Dataset info ---
+  const exportedAt = new Date().toISOString();
+  const info = buildDatasetInfo({
+    traceCount: traceRows.length,
+    preferenceCount: preferenceRows.length,
+    exportedAt,
+  });
+  fs.writeFileSync(
+    path.join(outputDir, 'dataset_info.json'),
+    JSON.stringify(info, null, 2) + '\n',
+  );
+
+  return {
+    outputDir,
+    traceCount: traceRows.length,
+    preferenceCount: preferenceRows.length,
+    files: ['traces.jsonl', 'preferences.jsonl', 'dataset_info.json'],
+    exportedAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = {};
+  process.argv.slice(2).forEach((arg) => {
+    if (!arg.startsWith('--')) return;
+    const [key, ...rest] = arg.slice(2).split('=');
+    args[key] = rest.length ? rest.join('=') : true;
+  });
+
+  const result = exportHfDataset({
+    outputDir: args.output || undefined,
+    includeProvenance: args.provenance !== 'false',
+  });
+
+  console.log(`Exported HuggingFace dataset to ${result.outputDir}`);
+  console.log(`  Traces: ${result.traceCount}`);
+  console.log(`  Preferences: ${result.preferenceCount}`);
+  console.log(`  Files: ${result.files.join(', ')}`);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  exportHfDataset,
+  buildTraceRow,
+  buildPreferenceRow,
+  buildDatasetInfo,
+  redactPaths,
+  redactEntry,
+  readJSONL,
+};

package/scripts/github-about.js

@@ -12,6 +12,8 @@ const ROOT = path.join(__dirname, '..');
 const CONFIG_RELATIVE_PATH = path.join('config', 'github-about.json');
 const LEGACY_REPOSITORY_URL = 'https://github.com/IgorGanapolsky/thumbgate';
 const GITHUB_API_BASE_URL = 'https://api.github.com';
+const DEFAULT_VERIFY_ATTEMPTS = 5;
+const DEFAULT_VERIFY_DELAY_MS = 2000;
 
 function readText(root, relativePath) {
   return fs.readFileSync(path.join(root, relativePath), 'utf8');
@@ -296,6 +298,57 @@ async function fetchLiveGitHubAbout(options = {}) {
   };
 }
 
+function normalizePositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function sleep(delayMs) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+}
+
+async function verifyLiveGitHubAbout(options = {}) {
+  const root = options.root || ROOT;
+  const expected = options.expected || loadGitHubAboutConfig(root);
+  const repo = normalizeText(options.repo) || expected.repo;
+  const label = options.label || `Live GitHub About (${repo})`;
+  const attempts = normalizePositiveInteger(options.attempts, DEFAULT_VERIFY_ATTEMPTS);
+  const delayMs = normalizePositiveInteger(options.delayMs, DEFAULT_VERIFY_DELAY_MS);
+  const fetcher = typeof options.fetcher === 'function' ? options.fetcher : fetchLiveGitHubAbout;
+  const sleeper = typeof options.sleep === 'function' ? options.sleep : sleep;
+  let actual = null;
+  let errors = [];
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    actual = await fetcher({
+      root,
+      repo,
+      token: options.token,
+    });
+    errors = compareGitHubAbout(expected, actual, label);
+    if (errors.length === 0) {
+      return {
+        ok: true,
+        actual,
+        attemptsUsed: attempt,
+        errors: [],
+      };
+    }
+    if (attempt < attempts) {
+      await sleeper(delayMs * attempt);
+    }
+  }
+
+  return {
+    ok: false,
+    actual,
+    attemptsUsed: attempts,
+    errors,
+  };
+}
+
 async function updateLiveGitHubAbout(options = {}) {
   const about = loadGitHubAboutConfig(options.root || ROOT);
   const repo = normalizeText(options.repo) || about.repo;
@@ -334,6 +387,8 @@ async function updateLiveGitHubAbout(options = {}) {
 }
 
 module.exports = {
+  DEFAULT_VERIFY_ATTEMPTS,
+  DEFAULT_VERIFY_DELAY_MS,
   LEGACY_REPOSITORY_URL,
   buildCanonicalRepoUrls,
   collectLocalGitHubAboutErrors,
@@ -347,4 +402,5 @@ module.exports = {
   normalizeTopics,
   normalizeUrl,
   updateLiveGitHubAbout,
+  verifyLiveGitHubAbout,
 };

package/scripts/operational-integrity.js

@@ -457,12 +457,17 @@ function parseCliArgs(argv = process.argv.slice(2)) {
   return options;
 }
 
+function resolveCiBranchName(env = process.env) {
+  const branchName = String(env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME || '').trim();
+  return branchName || undefined;
+}
+
 function runCli(env = process.env, argv = process.argv.slice(2)) {
   const args = parseCliArgs(argv);
   const result = evaluateOperationalIntegrity({
     repoPath: args.repoPath,
     baseBranch: args.baseBranch || env.DEFAULT_BRANCH || DEFAULT_BASE_BRANCH,
-    currentBranch: env.GITHUB_REF_NAME || undefined,
+    currentBranch: resolveCiBranchName(env),
     requirePrForReleaseSensitive: args.requirePrForReleaseSensitive,
     requireVersionNotBehindBase: args.requireVersionNotBehindBase,
     fetchBase: args.fetchBase,
@@ -517,6 +522,7 @@ module.exports = {
   parseSemver,
   readPackageVersion,
   resolveBaseRef,
+  resolveCiBranchName,
   resolveRepoRoot,
   runCli,
   sanitizeGlobList,

package/scripts/published-cli.js

@@ -13,6 +13,10 @@ function runtimePrefixDir(prefixDir) {
   return prefixDir || path.join(os.homedir(), '.thumbgate', 'runtime');
 }
 
+function installedRuntimeBin(prefixDir) {
+  return path.join(runtimePrefixDir(prefixDir), 'node_modules', '.bin', 'thumbgate');
+}
+
 function publishedCliArgs(pkgVersion, commandArgs = [], options = {}) {
   return [
     'exec',
@@ -29,7 +33,11 @@ function publishedCliArgs(pkgVersion, commandArgs = [], options = {}) {
 
 function publishedCliShellCommand(pkgVersion, commandArgs = [], options = {}) {
   const prefixDir = runtimePrefixDir(options.prefixDir);
-  return `mkdir -p ${shellQuote(prefixDir)} && exec npm ${publishedCliArgs(pkgVersion, commandArgs, { prefixDir }).map(shellQuote).join(' ')}`;
+  const runtimeBin = installedRuntimeBin(prefixDir);
+  const escapedArgs = commandArgs.map(shellQuote).join(' ');
+  const fastPath = `[ -x ${shellQuote(runtimeBin)} ] && exec ${shellQuote(runtimeBin)}${escapedArgs ? ` ${escapedArgs}` : ''}`;
+  const installPath = `mkdir -p ${shellQuote(prefixDir)} && exec npm ${publishedCliArgs(pkgVersion, commandArgs, { prefixDir }).map(shellQuote).join(' ')}`;
+  return `${fastPath} || ${installPath}`;
 }
 
 function runPublishedCli(pkgVersion, commandArgs = [], options = {}) {
@@ -55,6 +63,7 @@ function runPublishedCliHelp(pkgVersion, options = {}) {
 module.exports = {
   publishedCliArgs,
   publishedCliShellCommand,
+  installedRuntimeBin,
   runtimePrefixDir,
   runPublishedCli,
   runPublishedCliHelp,