teleportation-cli 1.3.0 → 1.4.1

package/lib/install/installer.js

@@ -10,6 +10,7 @@
  */
 
 import { copyFile, mkdir, chmod, readFile, writeFile, stat, readdir } from 'fs/promises';
+import { existsSync } from 'fs';
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
@@ -79,6 +80,28 @@ export function checkClaudeCode() {
   };
 }
 
+/**
+ * Check if Cursor IDE is installed by detecting ~/.cursor directory or cursor binary
+ */
+export function checkCursorIde() {
+  const cursorDir = join(HOME_DIR, '.cursor');
+  if (existsSync(cursorDir)) {
+    return { valid: true, path: cursorDir };
+  }
+  try {
+    const cursorPath = execSync('which cursor', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (cursorPath) {
+      return { valid: true, path: cursorPath };
+    }
+  } catch (e) {
+    // Cursor binary not found
+  }
+  return {
+    valid: false,
+    error: 'Cursor IDE not found. Install Cursor or ensure ~/.cursor directory exists.'
+  };
+}
+
 /**
  * Check if Gemini CLI is installed
  */
@@ -307,6 +330,88 @@ export async function installGeminiHooks(sourceGeminiHooksDir) {
   };
 }
 
+/**
+ * Install Teleportation hooks for Cursor IDE.
+ * Writes/merges ~/.cursor/hooks.json to point at the installed hook scripts.
+ * Cursor reads this file natively — no "Third-party skills" toggle required.
+ *
+ * @param {string} sourceHooksDir - Absolute path to the installed .claude/hooks/ directory
+ */
+export async function installCursorHooks(sourceHooksDir) {
+  const cursorDir = join(HOME_DIR, '.cursor');
+  const hooksJsonPath = join(cursorDir, 'hooks.json');
+  await mkdir(cursorDir, { recursive: true });
+
+  // Build the native Cursor hooks.json format
+  const hooksConfig = {
+    preToolUse: [{ command: `bun ${join(sourceHooksDir, 'pre_tool_use.mjs')}` }],
+    postToolUse: [{ command: `bun ${join(sourceHooksDir, 'post_tool_use.mjs')}` }],
+    sessionStart: [{ command: `bun ${join(sourceHooksDir, 'session_start.mjs')}` }],
+    sessionEnd: [{ command: `bun ${join(sourceHooksDir, 'session_end.mjs')}` }],
+    stop: [{ command: `bun ${join(sourceHooksDir, 'stop.mjs')}` }],
+    beforeSubmitPrompt: [{ command: `bun ${join(sourceHooksDir, 'user_prompt_submit.mjs')}` }],
+  };
+
+  // Merge with any existing hooks.json to preserve other tools' hooks
+  let existing = { version: 1, hooks: {} };
+  try {
+    const content = await readFile(hooksJsonPath, 'utf8');
+    existing = JSON.parse(content);
+    existing.hooks = existing.hooks || {};
+  } catch (e) {
+    // No existing file — start fresh
+  }
+
+  // Overwrite only Teleportation-managed hooks; leave others untouched
+  const merged = {
+    ...existing,
+    version: 1,
+    hooks: { ...existing.hooks, ...hooksConfig },
+  };
+
+  await writeFile(hooksJsonPath, JSON.stringify(merged, null, 2));
+  return { hooksJsonPath, hooksInstalled: Object.keys(hooksConfig) };
+}
+
+/**
+ * Remove Teleportation hooks from ~/.cursor/hooks.json without deleting the file.
+ * Preserves hooks belonging to other tools.
+ */
+export async function uninstallCursorHooks() {
+  const hooksJsonPath = join(HOME_DIR, '.cursor', 'hooks.json');
+  const teleportationKeys = ['preToolUse', 'postToolUse', 'sessionStart', 'sessionEnd', 'stop', 'beforeSubmitPrompt'];
+  const teleportationHookFiles = [
+    'pre_tool_use.mjs',
+    'post_tool_use.mjs',
+    'session_start.mjs',
+    'session_end.mjs',
+    'stop.mjs',
+    'user_prompt_submit.mjs',
+  ];
+
+  try {
+    const content = await readFile(hooksJsonPath, 'utf8');
+    const parsed = JSON.parse(content);
+    if (parsed.hooks) {
+      for (const key of teleportationKeys) {
+        if (!Array.isArray(parsed.hooks[key])) continue;
+        parsed.hooks[key] = parsed.hooks[key].filter((entry) => {
+          const command = entry?.command || '';
+          return !teleportationHookFiles.some((file) => command.includes(file));
+        });
+        if (parsed.hooks[key].length === 0) {
+          delete parsed.hooks[key];
+        }
+      }
+    }
+    await writeFile(hooksJsonPath, JSON.stringify(parsed, null, 2));
+    return { success: true, hooksJsonPath };
+  } catch (e) {
+    if (e.code === 'ENOENT') return { success: true, hooksJsonPath }; // Nothing to remove
+    throw e;
+  }
+}
+
 /**
  * Copy daemon files to ~/.teleportation/daemon/
  */
@@ -662,6 +767,7 @@ export async function verifyInstallation() {
  * @param {Object} [options] - Installation options
  * @param {boolean} [options.includeClaude] - Force include Claude hooks (overrides detection)
  * @param {boolean} [options.includeGemini] - Force include Gemini hooks (overrides detection)
+ * @param {boolean} [options.includeCursor] - Force include Cursor hooks (overrides detection)
  */
 export async function install(sourceHooksDir, options = {}) {
   // Pre-flight checks
@@ -673,6 +779,7 @@ export async function install(sourceHooksDir, options = {}) {
   // Check available CLIs
   const claudeCheck = checkClaudeCode();
   const geminiCheck = checkGeminiCli();
+  const cursorCheck = checkCursorIde();
   
   // Resolve what to install based on options and detection
   const shouldInstallClaude = options.includeClaude !== undefined 
@@ -683,11 +790,15 @@ export async function install(sourceHooksDir, options = {}) {
     ? options.includeGemini 
     : geminiCheck.valid;
 
-  if (!shouldInstallClaude && !shouldInstallGemini) {
-    if (options.includeClaude === false && options.includeGemini === false) {
+  const shouldInstallCursor = options.includeCursor !== undefined
+    ? options.includeCursor
+    : cursorCheck.valid;
+
+  if (!shouldInstallClaude && !shouldInstallGemini && !shouldInstallCursor) {
+    if (options.includeClaude === false && options.includeGemini === false && options.includeCursor === false) {
       throw new Error('No targets selected for installation.');
     }
-    throw new Error('Neither Claude Code nor Gemini CLI found. Please install one of them first, or specify a target.');
+    throw new Error('Neither Claude Code, Gemini CLI, nor Cursor IDE found. Please install one of them first, or specify a target.');
   }
 
   // Create directories
@@ -695,6 +806,7 @@ export async function install(sourceHooksDir, options = {}) {
 
   let hooksInstalled = 0;
   let geminiHooksInstalled = 0;
+  let cursorHooksInstalled = 0;
 
   // 1. Install Claude hooks
   if (shouldInstallClaude) {
@@ -719,6 +831,16 @@ export async function install(sourceHooksDir, options = {}) {
     }
   }
 
+  // 3. Install Cursor hooks
+  if (shouldInstallCursor) {
+    try {
+      const cursorResult = await installCursorHooks(resolve(getProjectHooksDir()));
+      cursorHooksInstalled = cursorResult.hooksInstalled.length;
+    } catch (e) {
+      console.warn(`Warning: Cursor hooks failed to install: ${e.message}`);
+    }
+  }
+
   // Install daemon (still goes to ~/.teleportation/daemon/)
   const daemonResult = await installDaemon();
   if (daemonResult.failed.length > 0) {
@@ -753,6 +875,7 @@ export async function install(sourceHooksDir, options = {}) {
     success: true,
     hooksInstalled,
     geminiHooksInstalled,
+    cursorHooksInstalled,
     daemonInstalled: daemonResult.installed.length,
     libFilesInstalled: libResult.installed.length,
     settingsFile: getProjectSettings(),

package/lib/install/uhr-installer.js

@@ -13,35 +13,41 @@
  */
 
 import { execSync } from 'child_process';
-import { join } from 'path';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { tmpdir } from 'os';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Absolute path to the local uhr binary shipped with teleportation
+const LOCAL_UHR_BIN = resolve(__dirname, '..', '..', 'node_modules', '.bin', 'uhr');
+
 /**
- * Check if the UHR CLI is available on this system.
- *
- * Checks two locations:
- *   1. `uhr` on the system PATH (via `which uhr`)
- *   2. `node_modules/.bin/uhr` (local project install)
- *
- * @returns {Promise<boolean>} true if UHR CLI is reachable
+ * Resolve the uhr binary path, preferring PATH then the local node_modules install.
+ * Returns the binary path string, or null if not found.
+ * @returns {Promise<string|null>}
  */
-export async function isUhrAvailable() {
+export async function resolveUhrBin() {
   // Check PATH first
   try {
-    execSync('which uhr', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-    return true;
+    const found = execSync('which uhr', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (found) return found;
   } catch (_) {
     // Not in PATH
   }
 
-  // Check local node_modules
+  // Check absolute path to local node_modules/.bin/uhr
   try {
-    const localBin = join('node_modules', '.bin', 'uhr');
-    const file = Bun.file(localBin);
-    return await file.exists();
+    const file = Bun.file(LOCAL_UHR_BIN);
+    if (await file.exists()) return LOCAL_UHR_BIN;
   } catch (_) {
-    return false;
+    // continue
   }
+
+  return null;
+}
+
+export async function isUhrAvailable() {
+  return (await resolveUhrBin()) !== null;
 }
 
 /**
@@ -89,9 +95,14 @@ export async function installViaUhr(manifestPath, hooksDir, options = {}) {
   }
 
   // 5. Run uhr install
+  const uhrBin = await resolveUhrBin();
+  if (!uhrBin) {
+    return { success: false, reason: 'UHR CLI not found (checked PATH and node_modules/.bin/uhr)' };
+  }
+
   const warnings = [];
   try {
-    const output = execSync(`uhr install ${tempManifestPath}`, {
+    const output = execSync(`"${uhrBin}" install "${tempManifestPath}"`, {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 30000,
@@ -123,8 +134,11 @@ export async function installViaUhr(manifestPath, hooksDir, options = {}) {
  * @returns {Promise<{success: boolean}>}
  */
 export async function uninstallViaUhr(serviceName) {
+  const uhrBin = await resolveUhrBin();
+  if (!uhrBin) return { success: false };
+
   try {
-    execSync(`uhr uninstall ${serviceName}`, {
+    execSync(`"${uhrBin}" uninstall "${serviceName}"`, {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 30000,

package/lib/intelligence/benchmark.js

@@ -0,0 +1,240 @@
+/**
+ * Transcript intelligence benchmark aggregation.
+ *
+ * Computes comparative performance slices by task class + provider + model.
+ */
+
+function toNumberOrNull(value) {
+  if (value == null) return null;
+  const num = Number(value);
+  return Number.isFinite(num) ? num : null;
+}
+
+function toBoolOrNull(value) {
+  if (typeof value === 'boolean') return value;
+  return null;
+}
+
+function initSession(event) {
+  return {
+    session_id: event.session_id || 'unknown-session',
+    task_category: event.task_category || 'unknown',
+    provider: event.provider || 'unknown',
+    model: event.model || 'unknown',
+    success_seen: false,
+    failure_seen: false,
+    cost_usd: 0,
+    duration_ms: 0,
+    tokens_used: 0,
+    approval_prompts: 0,
+    approval_escalations: 0,
+    tool_events: 0,
+  };
+}
+
+function updateSessionSummary(summary, event) {
+  if (event.event_type === 'approval_request') {
+    summary.approval_prompts += 1;
+  }
+  if (event.event_type === 'approval_decision' && event.approval?.decision === 'escalate') {
+    summary.approval_escalations += 1;
+  }
+  if (event.event_type === 'tool_call') {
+    summary.tool_events += 1;
+  }
+
+  const success = toBoolOrNull(event.execution?.success);
+  if (success === true) summary.success_seen = true;
+  if (success === false) summary.failure_seen = true;
+
+  const cost = toNumberOrNull(event.execution?.cost_usd);
+  if (cost != null) summary.cost_usd += cost;
+
+  const duration = toNumberOrNull(event.execution?.duration_ms);
+  if (duration != null) summary.duration_ms += duration;
+
+  const tokens = toNumberOrNull(event.execution?.tokens_used);
+  if (tokens != null) summary.tokens_used += tokens;
+}
+
+function finalizeSession(summary) {
+  let completion_state = 'partial';
+  if (summary.success_seen && !summary.failure_seen) completion_state = 'success';
+  if (summary.failure_seen && !summary.success_seen) completion_state = 'failed';
+
+  return {
+    ...summary,
+    completion_state,
+  };
+}
+
+function average(values) {
+  if (values.length === 0) return null;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function computeQualityProxy(stats) {
+  // Bounded [0..1]: favor success and penalize failures/escalations.
+  const escalationPenalty = Math.min(0.25, stats.escalation_rate * 0.5);
+  const failurePenalty = stats.failure_rate * 0.35;
+  const quality = stats.success_rate - escalationPenalty - failurePenalty;
+  return Math.max(0, Number(quality.toFixed(4)));
+}
+
+function normalizeHigherIsWorse(value, min, max) {
+  if (value == null || min == null || max == null) return 0;
+  const span = max - min;
+  if (span <= 0) return 0;
+  return Math.min(1, Math.max(0, (value - min) / span));
+}
+
+function proportionConfidenceInterval(rate, sampleSize) {
+  if (!Number.isFinite(rate) || !Number.isFinite(sampleSize) || sampleSize <= 0) {
+    return { low: 0, high: 0, margin: 0 };
+  }
+
+  const margin = 1.96 * Math.sqrt((rate * (1 - rate)) / sampleSize);
+  return {
+    low: Number(Math.max(0, rate - margin).toFixed(4)),
+    high: Number(Math.min(1, rate + margin).toFixed(4)),
+    margin: Number(margin.toFixed(4)),
+  };
+}
+
+export function buildSessionBenchmarks(events) {
+  if (!Array.isArray(events) || events.length === 0) return [];
+
+  const sessions = new Map();
+
+  for (const event of events) {
+    const key = event.session_id || 'unknown-session';
+    const summary = sessions.get(key) || initSession(event);
+    updateSessionSummary(summary, event);
+    sessions.set(key, summary);
+  }
+
+  return Array.from(sessions.values()).map(finalizeSession);
+}
+
+export function aggregateBenchmarksByTaskClass(events, options = {}) {
+  const minSessions = Number.isInteger(options.minSessions) ? Math.max(1, options.minSessions) : 1;
+  const sessionRows = buildSessionBenchmarks(events);
+  if (sessionRows.length === 0) return [];
+
+  const slices = new Map();
+
+  for (const row of sessionRows) {
+    const key = `${row.task_category}::${row.provider}::${row.model}`;
+    const existing = slices.get(key) || {
+      task_category: row.task_category,
+      provider: row.provider,
+      model: row.model,
+      sessions: [],
+    };
+    existing.sessions.push(row);
+    slices.set(key, existing);
+  }
+
+  return Array.from(slices.values())
+    .filter((slice) => slice.sessions.length >= minSessions)
+    .map((slice) => {
+      const total = slice.sessions.length;
+      const successCount = slice.sessions.filter((row) => row.completion_state === 'success').length;
+      const failureCount = slice.sessions.filter((row) => row.completion_state === 'failed').length;
+
+      const escalationPrompts = slice.sessions.reduce((sum, row) => sum + row.approval_prompts, 0);
+      const escalations = slice.sessions.reduce((sum, row) => sum + row.approval_escalations, 0);
+
+      const stats = {
+        success_rate: Number((successCount / total).toFixed(4)),
+        failure_rate: Number((failureCount / total).toFixed(4)),
+        escalation_rate: escalationPrompts === 0
+          ? 0
+          : Number((escalations / escalationPrompts).toFixed(4)),
+      };
+
+      return {
+        task_category: slice.task_category,
+        provider: slice.provider,
+        model: slice.model,
+        sample_size: total,
+        ...stats,
+        avg_cost_usd: average(slice.sessions.map((row) => row.cost_usd)),
+        avg_duration_ms: average(slice.sessions.map((row) => row.duration_ms)),
+        avg_tokens_used: average(slice.sessions.map((row) => row.tokens_used)),
+        completion_reliability: Number((1 - stats.failure_rate).toFixed(4)),
+        quality_proxy: computeQualityProxy(stats),
+      };
+    })
+    .sort((a, b) => {
+      if (b.quality_proxy !== a.quality_proxy) return b.quality_proxy - a.quality_proxy;
+      if (b.success_rate !== a.success_rate) return b.success_rate - a.success_rate;
+      return a.avg_cost_usd - b.avg_cost_usd;
+    });
+}
+
+export function scoreHarnessModelBenchmark(events, options = {}) {
+  const provider = options.harness || options.provider;
+  const model = options.model;
+  const taskCategory = options.taskCategory || options.task_category;
+  const minSessions = Number.isInteger(options.minSessions) ? Math.max(1, options.minSessions) : 30;
+
+  const allSlices = aggregateBenchmarksByTaskClass(events, { minSessions: 1 });
+  if (allSlices.length === 0) {
+    return { eligible: false, reason: 'no_benchmark_data' };
+  }
+
+  const comparable = taskCategory
+    ? allSlices.filter((slice) => slice.task_category === taskCategory)
+    : allSlices;
+
+  const target = comparable.find((slice) =>
+    slice.provider === provider && slice.model === model && (!taskCategory || slice.task_category === taskCategory),
+  );
+
+  if (!target) {
+    return { eligible: false, reason: 'no_matching_slice' };
+  }
+
+  if (target.sample_size < minSessions) {
+    return {
+      eligible: false,
+      reason: 'insufficient_evidence',
+      sample_size: target.sample_size,
+      required_sample_size: minSessions,
+    };
+  }
+
+  const costs = comparable.map((slice) => slice.avg_cost_usd).filter((value) => Number.isFinite(value));
+  const latencies = comparable.map((slice) => slice.avg_duration_ms).filter((value) => Number.isFinite(value));
+
+  const costMin = costs.length > 0 ? Math.min(...costs) : null;
+  const costMax = costs.length > 0 ? Math.max(...costs) : null;
+  const latencyMin = latencies.length > 0 ? Math.min(...latencies) : null;
+  const latencyMax = latencies.length > 0 ? Math.max(...latencies) : null;
+
+  const normalizedCostPenalty = normalizeHigherIsWorse(target.avg_cost_usd, costMin, costMax);
+  const normalizedLatencyPenalty = normalizeHigherIsWorse(target.avg_duration_ms, latencyMin, latencyMax);
+
+  const score = Number((
+    (0.35 * target.success_rate) +
+    (0.2 * target.quality_proxy) +
+    (0.15 * (1 - normalizedCostPenalty)) +
+    (0.1 * (1 - normalizedLatencyPenalty)) +
+    (0.1 * target.completion_reliability) +
+    (0.1 * (1 - target.escalation_rate))
+  ).toFixed(4));
+
+  return {
+    eligible: true,
+    task_category: target.task_category,
+    provider: target.provider,
+    model: target.model,
+    sample_size: target.sample_size,
+    score,
+    metrics: target,
+    confidence_interval: proportionConfidenceInterval(target.success_rate, target.sample_size),
+  };
+}
+
+export { computeQualityProxy, proportionConfidenceInterval };

package/lib/intelligence/index.js

@@ -0,0 +1,29 @@
+export {
+  normalizeTranscriptEvent,
+  normalizeTranscriptEvents,
+  isValidNormalizedEvent,
+  normalizeTranscriptEntry,
+  validateNormalizedTranscriptEntry,
+  TASK_CATEGORIES,
+  EVENT_TYPES,
+  APPROVAL_DECISIONS,
+  APPROVAL_SOURCES,
+  ENTRY_SCHEMA_VERSION,
+} from './schema.js';
+
+export {
+  mineRequestPatterns,
+  extractRequestText,
+  tokenize,
+  classifyIntent,
+} from './transcript-mine.js';
+
+export {
+  buildSessionBenchmarks,
+  aggregateBenchmarksByTaskClass,
+  scoreHarnessModelBenchmark,
+  computeQualityProxy,
+  proportionConfidenceInterval,
+} from './benchmark.js';
+
+export { rebuildPolicyArtifacts } from './rebuild-policies.js';