kiroo 0.9.0 → 0.9.5

package/README.md

@@ -141,7 +141,7 @@ Initialize Kiroo in your current project.
   kiroo init
   ```
 
-### `kiroo get/post/put/delete <url>`
+### `kiroo get/post/put/delete/patch <url>`
 Execute and record an API interaction.
 - **Description**: Performs an HTTP request, displays the response, and saves it to history.
 - **Prerequisites**: Access to the URL (or a `baseUrl` set in the environment).
@@ -154,6 +154,7 @@ Execute and record an API interaction.
 - **Example**:
   ```bash
   kiroo post /api/auth/login -d "email=user@test.com password=123" --save token=data.token
+  kiroo patch /api/profile -d "name=UpdatedName"
   ```
 
 ### `kiroo list`
@@ -271,9 +272,15 @@ Snapshot management.
   - `list`: List all saved snapshots.
   - `compare <tag1> <tag2>`: Detect structural changes between two states.
   - `compare <tag1> <tag2> --analyze`: Structural compare + semantic severity in one run.
+  - `run <tag>`: Execute all interactions in a snapshot sequentially (supports auth token chaining).
+- **Options for `run`**:
+  - `-v, --verbose`: Show response preview for each request.
+  - `--fail-fast`: Stop immediately on first failed interaction.
+  - `--timeout <ms>`: Request timeout in milliseconds (Default: 30000).
 - **Example**:
   ```bash
   kiroo snapshot compare v1.stable current
+  kiroo snapshot run v1.stable --fail-fast
   ```
 
 ### `kiroo analyze <tag1> <tag2>`
@@ -349,6 +356,17 @@ Wipe history.
   kiroo clear --force
   ```
 
+### `kiroo help [command]`
+Get command-level help directly in CLI.
+- **Description**: Shows global help or detailed help for a specific command.
+- **Arguments**:
+  - `command`: (Optional) Command name to inspect.
+- **Example**:
+  ```bash
+  kiroo help
+  kiroo help bench
+  ```
+
 ---
 
 ## 🤝 Contributing

package/bin/kiroo.js

@@ -17,19 +17,24 @@ import { editInteraction } from '../src/edit.js';
 import { exportInteractions } from '../src/export.js';
 import { runProxy } from '../src/proxy.js';
 import { analyzeSnapshots } from '../src/analyze.js';
+import { runSnapshot } from '../src/run.js';
 
 const program = new Command();
 
 program
   .name('kiroo')
   .description('Git for API interactions. Record, replay, snapshot, and diff your APIs.')
-  .version('0.8.0')
+  .version('0.9.5')
+  .showSuggestionAfterError()
   .option('--lang <language>', 'Translate output to specified language (e.g., hi, es, fr)');
 
 // Init command
 program
   .command('init')
   .description('Initialize Kiroo in current directory')
+  .addHelpText('after', `
+Examples:
+  $ kiroo init`)
   .action(async () => {
     await initProject();
   });
@@ -39,17 +44,25 @@ program
 program
   .command('check <url>')
   .description('Execute a request and validate the response against rules')
+  .addHelpText('after', `
+Examples:
+  $ kiroo check /api/users --status 200 --has id,email
+  $ kiroo check http://api.example.com/login --match status=active`)
   .option('-m, --method <method>', 'HTTP method (GET, POST, etc.)', 'GET')
+  // ... (keep options as is)
   .option('-H, --header <header...>', 'Add custom headers')
   .option('-d, --data <data>', 'Request body (JSON or shorthand)')
   .option('--status <code...>', 'Expected HTTP status code')
   .option('--has <fields...>', 'Comma-separated list of expected fields in JSON response')
   .option('--match <matches...>', 'Expected field values (e.g., status=active)')
   .action(async (url, options) => {
+    // ...
     // Execute request
+    const opts = program.opts();
     const response = await executeRequest(options.method || 'GET', url, {
       header: options.header,
       data: options.data,
+      lang: opts.lang
     });
 
     if (!response) {
@@ -78,13 +91,12 @@ program
 
     // Validate
     const validation = validateResponse(response, rules);
-    showCheckResult(validation);
+    await showCheckResult(validation, opts.lang);
 
     if (!validation.passed) {
       process.exit(1);
     }
   });
-  // sk_live_p7BWJjsYlKmauBOjiEeiLRuu4DokkBWsgYne_E6osTo
 
 // HTTP methods as commands
 ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].forEach(method => {
@@ -96,7 +108,8 @@ program
     .option('-d, --data <data>', 'Request body (JSON string or key=value pairs)')
     .option('-s, --save <pairs...>', 'Extract values from response to env (key=path.to.data)')
     .action(async (url, options) => {
-      await executeRequest(method, url, options);
+      const opts = program.opts();
+      await executeRequest(method, url, { ...options, lang: opts.lang });
     });
 });
 
@@ -155,7 +168,8 @@ program
   .option('-v, --verbose', 'Show detailed output for every request')
   .option('-d, --data <data>', 'Request body')
   .action(async (url, options) => {
-    await runBenchmark(url, options);
+    const opts = program.opts();
+    await runBenchmark(url, { ...options, lang: opts.lang });
   });
 
 // Clear command
@@ -266,6 +280,20 @@ snapshot
     }
   });
 
+snapshot
+  .command('run <tag>')
+  .description('Execute all interactions from a snapshot sequentially (auto-chains auth tokens)')
+  .option('-v, --verbose', 'Show response body preview for each request')
+  .option('--fail-fast', 'Exit immediately on first failure')
+  .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
+  .action(async (tag, options) => {
+    await runSnapshot(tag, {
+      verbose: !!options.verbose,
+      failFast: !!options.failFast,
+      timeout: parseInt(options.timeout, 10) || 30000,
+    });
+  });
+
 program
   .command('analyze <tag1> <tag2>')
   .description('Semantic blast-radius analysis between two snapshots')
@@ -336,9 +364,33 @@ program
 // Stats command
 program
   .command('stats')
-  .description('Show usage statistics')
+  .alias('stat')
+  .description('Show usage statistics and bottlenecks')
+  .addHelpText('after', `
+Examples:
+  $ kiroo stats
+  $ kiroo stats --lang hi`)
   .action(async () => {
-    await showStats();
+    const opts = program.opts();
+    await showStats({ lang: opts.lang });
+  });
+
+// Help command
+program
+  .command('help [command]')
+  .description('Display help for a command')
+  .action((cmd) => {
+    if (cmd) {
+      const subCommand = program.commands.find(c => c.name() === cmd || c.aliases().includes(cmd));
+      if (subCommand) {
+        subCommand.help();
+      } else {
+        console.error(chalk.red(`\n  ✗ Unknown command: ${cmd}`));
+        program.help();
+      }
+    } else {
+      program.help();
+    }
   });
 
 // Error handling
@@ -347,15 +399,14 @@ program.exitOverride();
 try {
   await program.parseAsync(process.argv);
 } catch (err) {
-  if (err.code === 'commander.help' || err.message === '(outputHelp)') {
-    // Help was requested, exit normally
+  if (err.code === 'commander.help' || err.code === 'commander.version' || err.message === '(outputHelp)') {
     process.exit(0);
-  } else if (err.code === 'commander.unknownCommand') {
-    console.error(chalk.red(`\n  ✗ Unknown command: ${err.message}\n`));
-    console.log(chalk.gray('  Run'), chalk.white('kiroo --help'), chalk.gray('for usage information.\n'));
+  } else if (err.code === 'commander.unknownCommand' || err.code === 'commander.missingArgument') {
+    // Commander already printed the error and suggestion, just exit
     process.exit(1);
   } else {
-    console.error(chalk.red('\n  ✗ Error:'), err.message, `(${err.code})`, '\n');
+    // For other unexpected errors, we print our own formatted message
+    console.error(chalk.red('\n  ✗ Error:'), err.message, '\n');
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiroo",
-  "version": "0.9.0",
+  "version": "0.9.5",
   "description": "Git for API interactions. Record, replay, snapshot, and diff your APIs.",
   "type": "module",
   "bin": {

package/src/analyze.js

@@ -500,18 +500,25 @@ export async function analyzeSnapshots(tag1, tag2, options = {}) {
     if (options.json) {
       console.log(stableJSONStringify(report));
     } else {
-      console.log(chalk.cyan('\n  🧠 Blast Radius Analysis'));
+      let header = '🧠 Blast Radius Analysis';
+      if (options.lang) header = await translateText(header, options.lang);
+      console.log(chalk.cyan(`\n  ${header}`));
       console.log(chalk.gray(`  Source: ${tag1}`));
       console.log(chalk.gray(`  Target: ${tag2}\n`));
 
       const shownEndpoints = report.endpoints.slice(0, 6);
       for (const endpoint of shownEndpoints) {
+        let severityLabel = endpoint.highestSeverity.toUpperCase();
+        if (options.lang) severityLabel = await translateText(severityLabel, options.lang);
         const severityColor = colorForSeverity(endpoint.highestSeverity);
-        console.log(`  ${severityColor(endpoint.highestSeverity.toUpperCase())} ${chalk.white(endpoint.method)} ${chalk.gray(endpoint.path)}`);
-        endpoint.issues.slice(0, 4).forEach((issue) => {
+        console.log(`  ${severityColor(severityLabel)} ${chalk.white(endpoint.method)} ${chalk.gray(endpoint.path)}`);
+        
+        for (const issue of endpoint.issues.slice(0, 4)) {
           const issueColor = colorForSeverity(issue.severity);
-          console.log(`    - ${issueColor(issue.severity)} ${issue.message}`);
-        });
+          let issueMsg = issue.message;
+          if (options.lang) issueMsg = await translateText(issueMsg, options.lang);
+          console.log(`    - ${issueColor(issue.severity)} ${issueMsg}`);
+        }
         if (endpoint.issues.length > 4) {
           console.log(chalk.gray(`    - ... +${endpoint.issues.length - 4} more issues`));
         }
@@ -531,10 +538,21 @@ export async function analyzeSnapshots(tag1, tag2, options = {}) {
         modelPriority,
         maxTokens
       });
-      console.log(chalk.magenta(`\n  🤖 AI Summary (${ai.model})`));
-      toConciseBullets(ai.summary, report).forEach((bullet) => {
-        console.log(`  ${bullet}`);
-      });
+      let aiSectionTitle = `🤖 AI Summary (${ai.model})`;
+      if (options.lang) aiSectionTitle = await translateText(aiSectionTitle, options.lang);
+      console.log(chalk.magenta(`\n  ${aiSectionTitle}`));
+      
+      const bullets = toConciseBullets(ai.summary, report);
+      for (const bullet of bullets) {
+        let finalBullet = bullet;
+        if (options.lang) {
+          // Translate the text part of the bullet
+          const bulletText = bullet.replace(/^- /, '');
+          const translatedBullet = await translateText(bulletText, options.lang);
+          finalBullet = `- ${translatedBullet}`;
+        }
+        console.log(`  ${finalBullet}`);
+      }
     }
 
     if (failOnSeverity && shouldFail(report, failOnSeverity)) {

package/src/bench.js

@@ -4,6 +4,7 @@ import axios from 'axios';
 import ora from 'ora';
 import { loadEnv } from './storage.js';
 import { applyEnvReplacements } from './executor.js';
+import { translateText } from './lingo.js';
 
 export async function runBenchmark(url, options) {
   const envData = loadEnv();
@@ -177,7 +178,7 @@ export async function runBenchmark(url, options) {
       }
     };
 
-    const finalizeBenchmark = () => {
+    const finalizeBenchmark = async () => {
       const totalTime = Date.now() - startTime;
       if (!isVerbose) spinner.stop();
       
@@ -191,7 +192,9 @@ export async function runBenchmark(url, options) {
         avg = Math.round(results.times.reduce((a, b) => a + b, 0) / results.times.length);
       }
 
-      console.log('\n  ' + chalk.blue.bold('🚀 Benchmark Results'));
+      let resultTitle = '🚀 Benchmark Results';
+      if (options.lang) resultTitle = await translateText(resultTitle, options.lang);
+      console.log('\n  ' + chalk.blue.bold(resultTitle));
       console.log('  ' + chalk.gray(`${method} ${targetUrl}\n`));
 
       const statsTable = new Table({
@@ -212,9 +215,13 @@ export async function runBenchmark(url, options) {
       console.log(statsTable.toString());
       
       if (results.failures > 0) {
-        console.log(chalk.red(`\n  ⚠️  ${results.failures} requests failed (HTTP 4xx/5xx or Network Error).\n`));
+        let errorMsg = `⚠️  ${results.failures} requests failed (HTTP 4xx/5xx or Network Error).`;
+        if (options.lang) errorMsg = await translateText(errorMsg, options.lang);
+        console.log(chalk.red(`\n  ${errorMsg}\n`));
       } else {
-        console.log(chalk.green(`\n  ✅ All requests completed successfully.\n`));
+        let successMsg = '✅ All requests completed successfully.';
+        if (options.lang) successMsg = await translateText(successMsg, options.lang);
+        console.log(chalk.green(`\n  ${successMsg}\n`));
       }
       
       resolve();

package/src/checker.js

@@ -76,24 +76,41 @@ function getDeep(obj, path) {
   return keys.reduce((acc, key) => acc && acc[key], obj);
 }
 
-export function showCheckResult(validation) {
-  console.log(chalk.cyan('\n  🧪 Test Results:'));
+import { translateText } from './lingo.js';
+
+export async function showCheckResult(validation, lang) {
+  let title = '🧪 Test Results:';
+  if (lang) title = await translateText(title, lang);
+  console.log(chalk.cyan(`\n  ${title}`));
   
-  validation.results.forEach(res => {
+  for (const res of validation.results) {
     const icon = res.passed ? chalk.green('✓') : chalk.red('✗');
     const color = res.passed ? chalk.white : chalk.red;
     
-    console.log(`  ${icon} ${res.label}`);
+    let label = res.label;
+    if (lang) label = await translateText(label, lang);
+    console.log(`  ${icon} ${label}`);
+    
     if (!res.passed) {
-      console.log(chalk.gray(`     Expected: ${res.expected}`));
-      console.log(chalk.gray(`     Actual:   ${res.actual}`));
+      let expectedLabel = 'Expected:';
+      let actualLabel = 'Actual:';
+      if (lang) {
+        expectedLabel = await translateText(expectedLabel, lang);
+        actualLabel = await translateText(actualLabel, lang);
+      }
+      console.log(chalk.gray(`     ${expectedLabel} ${res.expected}`));
+      console.log(chalk.gray(`     ${actualLabel}   ${res.actual}`));
     }
-  });
+  }
 
   if (validation.passed) {
-    console.log(chalk.green.bold('\n  ✨ ALL TESTS PASSED! \n'));
+    let msg = '✨ ALL TESTS PASSED!';
+    if (lang) msg = await translateText(msg, lang);
+    console.log(chalk.green.bold(`\n  ${msg} \n`));
   } else {
-    console.log(chalk.red.bold('\n  ❌ SOME TESTS FAILED \n'));
+    let msg = '❌ SOME TESTS FAILED';
+    if (lang) msg = await translateText(msg, lang);
+    console.log(chalk.red.bold(`\n  ${msg} \n`));
     process.exit(1);
   }
 }

package/src/executor.js

@@ -177,7 +177,7 @@ export async function executeRequest(method, url, options = {}) {
     spinner.succeed(chalk.green(`${response.status} ${response.statusText}`) + chalk.gray(` (${duration}ms)`));
 
     // Format and display response
-    console.log(formatResponse(response));
+    console.log(await formatResponse(response, options.lang));
 
     // Handle --save option
     if (options.save) {

package/src/export.js

@@ -96,10 +96,12 @@ function getPathAndOrigin(rawUrl) {
 }
 
 function inferSchema(value) {
-  if (value === null) return { nullable: true };
+  if (value === null) return { type: 'object', nullable: true };
   if (Array.isArray(value)) {
     if (value.length === 0) return { type: 'array', items: {} };
-    const mergedItem = value.map((item) => inferSchema(item)).reduce(mergeSchemas, {});
+    // Only infer from first 5 items to avoid noise from duplicates
+    const sample = value.slice(0, 5);
+    const mergedItem = sample.map((item) => inferSchema(item)).reduce(mergeSchemas, {});
     return { type: 'array', items: mergedItem };
   }
   if (value && typeof value === 'object') {
@@ -253,6 +255,37 @@ function hasHeader(headers, name) {
   return Object.keys(headers || {}).some((k) => k.toLowerCase() === name.toLowerCase());
 }
 
+const SENSITIVE_PATTERNS = [
+  { regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, replace: '<REDACTED_EMAIL>' },
+  { regex: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, replace: '<REDACTED_JWT>' },
+  { regex: /\b(sk_live_|pk_live_|sk_test_|pk_test_)[A-Za-z0-9_-]{10,}/g, replace: '<REDACTED_KEY>' },
+  { regex: /\b(gsk_|ghp_|gho_|glpat-)[A-Za-z0-9_-]{10,}/g, replace: '<REDACTED_KEY>' },
+];
+
+function redactValue(val) {
+  if (typeof val !== 'string') return val;
+  let result = val;
+  for (const { regex, replace } of SENSITIVE_PATTERNS) {
+    result = result.replace(regex, replace);
+  }
+  return result;
+}
+
+function truncateAndRedact(value, maxArrayItems = 3) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return redactValue(value);
+  if (typeof value !== 'object') return value;
+  if (Array.isArray(value)) {
+    const sliced = value.slice(0, maxArrayItems);
+    return sliced.map((item) => truncateAndRedact(item, maxArrayItems));
+  }
+  const result = {};
+  for (const [k, v] of Object.entries(value)) {
+    result[k] = truncateAndRedact(v, maxArrayItems);
+  }
+  return result;
+}
+
 function buildOpenApiSpec(interactions, options = {}) {
   const title = options.title || 'Kiroo Traffic API';
   const version = options.apiVersion || '1.0.0';
@@ -368,7 +401,7 @@ function buildOpenApiSpec(interactions, options = {}) {
         content: {
           [mimeType]: {
             schema: mergedBodySchema,
-            example: op.requestBodies[0]
+            example: truncateAndRedact(op.requestBodies[0])
           }
         }
       };
@@ -377,17 +410,41 @@ function buildOpenApiSpec(interactions, options = {}) {
     const sortedStatuses = Array.from(op.responses.keys()).sort((a, b) => a.localeCompare(b));
     sortedStatuses.forEach((status) => {
       const res = op.responses.get(status);
+      const statusNum = parseInt(status, 10);
+
+      // Meaningful description based on status code
+      const description = statusNum === 200 ? 'Successful response'
+        : statusNum === 201 ? 'Resource created'
+        : statusNum === 204 ? 'No content'
+        : statusNum === 304 ? 'Not modified'
+        : statusNum === 400 ? 'Bad request'
+        : statusNum === 401 ? 'Unauthorized'
+        : statusNum === 403 ? 'Forbidden'
+        : statusNum === 404 ? 'Not found'
+        : statusNum === 409 ? 'Conflict'
+        : statusNum === 500 ? 'Internal server error'
+        : `Response ${status}`;
+
+      // 204 and 304 typically have no body
+      if (statusNum === 204 || statusNum === 304) {
+        operation.responses[status] = { description };
+        return;
+      }
+
       const mimeType = Array.from(res.mimeTypes)[0] || 'application/json';
       const schema = res.bodies.length > 0
         ? res.bodies.map((b) => inferSchema(b)).reduce(mergeSchemas, {})
         : {};
 
+      // Recursively truncate arrays and redact sensitive data in examples
+      let example = res.example !== undefined ? truncateAndRedact(res.example) : undefined;
+
       operation.responses[status] = {
-        description: 'Observed response',
+        description,
         content: {
           [mimeType]: {
             schema,
-            ...(res.example !== undefined ? { example: res.example } : {})
+            ...(example !== undefined ? { example } : {})
           }
         }
       };

package/src/formatter.js

@@ -1,6 +1,8 @@
 import chalk from 'chalk';
 
-export function formatResponse(response) {
+import { translateText, translateResponseData } from './lingo.js';
+
+export async function formatResponse(response, lang) {
   const lines = [];
   
   // Status
@@ -21,7 +23,10 @@ export function formatResponse(response) {
     .slice(0, 3);
   
   if (headers.length > 0) {
-    lines.push(chalk.gray('  Headers:'));
+    let headersLabel = '  Headers:';
+    if (lang) headersLabel = await translateText(headersLabel, lang);
+    lines.push(chalk.gray(headersLabel));
+    
     headers.forEach(([key, value]) => {
       const displayValue = typeof value === 'string' && value.length > 50 
         ? value.substring(0, 50) + '...' 
@@ -33,17 +38,24 @@ export function formatResponse(response) {
   
   // Body
   if (response.data) {
-    lines.push(chalk.gray('  Response:'));
+    let responseLabel = '  Response:';
+    if (lang) responseLabel = await translateText(responseLabel, lang);
+    lines.push(chalk.gray(responseLabel));
+    
+    let displayData = response.data;
+    if (lang) {
+      displayData = await translateResponseData(response.data, lang);
+    }
     
-    if (typeof response.data === 'object') {
+    if (typeof displayData === 'object') {
       // Pretty print JSON
-      const json = JSON.stringify(response.data, null, 2);
+      const json = JSON.stringify(displayData, null, 2);
       json.split('\n').forEach(line => {
         lines.push(chalk.cyan(`    ${line}`));
       });
     } else {
       // Plain text
-      const text = String(response.data);
+      const text = String(displayData);
       const preview = text.length > 500 ? text.substring(0, 500) + '...' : text;
       lines.push(chalk.white(`    ${preview}`));
     }

package/src/lingo.js

@@ -15,6 +15,7 @@ function getLingoEngine() {
 }
 
 export async function translateText(text, targetLang) {
+  if (!text || typeof text !== 'string' || text.trim() === '') return text;
   const engine = getLingoEngine();
   if (!engine) return text;
 
@@ -26,7 +27,29 @@ export async function translateText(text, targetLang) {
     });
     return result;
   } catch (error) {
-    console.log(chalk.red(`\n  ⚠️  Translation failed: ${error.message}`));
+    // console.log(chalk.red(`\n  ⚠️  Translation failed: ${error.message}`));
     return text; 
   }
 }
+
+/**
+ * Recursively translates strings within an object or array
+ */
+export async function translateResponseData(data, targetLang) {
+  if (!data) return data;
+  if (typeof data === 'string') {
+    return await translateText(data, targetLang);
+  }
+  if (Array.isArray(data)) {
+    return await Promise.all(data.map(item => translateResponseData(item, targetLang)));
+  }
+  if (typeof data === 'object') {
+    const translated = {};
+    for (const [key, value] of Object.entries(data)) {
+      // Don't translate keys, just values
+      translated[key] = await translateResponseData(value, targetLang);
+    }
+    return translated;
+  }
+  return data;
+}

package/src/proxy.js

@@ -91,8 +91,28 @@ export async function runProxy(targetHost, options = {}) {
     });
   });
 
+  // Add CORS headers to proxied responses
+  proxy.on('proxyRes', function (proxyRes, req, res) {
+    proxyRes.headers['access-control-allow-origin'] = req.headers.origin || '*';
+    proxyRes.headers['access-control-allow-credentials'] = 'true';
+  });
+
   const server = http.createServer((req, res) => {
     req.kirooStartTime = Date.now();
+
+    // Handle CORS preflight
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': req.headers.origin || '*',
+        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+        'Access-Control-Allow-Headers': req.headers['access-control-request-headers'] || '*',
+        'Access-Control-Allow-Credentials': 'true',
+        'Access-Control-Max-Age': '86400',
+      });
+      res.end();
+      return;
+    }
+
     let bodyChunks = [];
 
     req.on('data', (chunk) => {

package/src/run.js

@@ -0,0 +1,246 @@
+import axios from 'axios';
+import chalk from 'chalk';
+import ora from 'ora';
+import { loadSnapshotData, loadEnv } from './storage.js';
+
+const REDACTED_RE = /<REDACTED[^>]*>/i;
+
+function isRedacted(val) {
+  return typeof val === 'string' && REDACTED_RE.test(val.trim());
+}
+
+/**
+ * Sort interactions chronologically (oldest first) so login
+ * runs before authenticated requests.
+ */
+function sortChronologically(interactions) {
+  return [...interactions].sort((a, b) => {
+    // IDs are timestamps like "2026-03-15T08-10-57-031Z"
+    const idA = a.id || '';
+    const idB = b.id || '';
+    return idA.localeCompare(idB);
+  });
+}
+
+/**
+ * Deduplicate redundant interactions (e.g. 10 identical GET /api/projects 304s).
+ * Keeps unique method+path combinations, but allows duplicates for different
+ * status codes or non-cacheable methods (POST/PUT/DELETE).
+ */
+function deduplicateInteractions(interactions) {
+  const seen = new Map();
+  return interactions.filter((int) => {
+    const method = String(int.method || int.request?.method || 'GET').toUpperCase();
+    // Always keep non-GET (side-effectful) methods
+    if (method !== 'GET') return true;
+
+    const url = int.url || int.request?.url || '/';
+    const status = int.response?.status || 0;
+    const key = `${method}|${url}|${status}`;
+    if (seen.has(key)) return false;
+    seen.set(key, true);
+    return true;
+  });
+}
+
+/**
+ * Run all interactions from a snapshot sequentially.
+ * - Sorted oldest-first so login precedes authenticated requests
+ * - Deduplicates redundant 304 GET requests
+ * - Auto-chains tokens from auth responses
+ * - Resolves <REDACTED> headers/body from env vars
+ */
+export async function runSnapshot(tag, options = {}) {
+  let snapshot;
+  try {
+    snapshot = loadSnapshotData(tag);
+  } catch (err) {
+    console.error(chalk.red(`\n  ✗ Snapshot not found: ${tag}`));
+    console.log(chalk.gray(`  Run 'kiroo snapshot list' to see available snapshots.\n`));
+    process.exit(1);
+  }
+
+  const raw = snapshot.interactions || [];
+  if (raw.length === 0) {
+    console.log(chalk.yellow(`\n  ⚠️ Snapshot "${tag}" has no interactions.\n`));
+    return;
+  }
+
+  const env = loadEnv();
+  const envVars = env.environments[env.current] || {};
+  const baseUrl = envVars.baseUrl || '';
+
+  // Sort chronologically, then deduplicate
+  const sorted = sortChronologically(raw);
+  const interactions = deduplicateInteractions(sorted);
+
+  // Captured variables during run (auto-chained)
+  const captured = {};
+
+  console.log(chalk.cyan(`\n  ▶ Running snapshot: ${chalk.white(tag)}`));
+  console.log(chalk.gray(`  ${interactions.length} interactions (${raw.length - interactions.length} duplicates skipped)\n`));
+
+  let passed = 0;
+  let failed = 0;
+
+  for (let i = 0; i < interactions.length; i++) {
+    const int = interactions[i];
+    const method = String(int.method || int.request?.method || 'GET').toUpperCase();
+    let url = int.url || int.request?.url || '/';
+    const headers = { ...(int.request?.headers || {}) };
+    let body = int.request?.body ? JSON.parse(JSON.stringify(int.request.body)) : undefined;
+
+    // Remove internal/hop-by-hop headers
+    for (const h of ['host', 'content-length', 'connection', 'accept-encoding', 'if-none-match',
+      'sec-ch-ua', 'sec-ch-ua-mobile', 'sec-ch-ua-platform', 'sec-fetch-dest', 'sec-fetch-mode',
+      'sec-fetch-site', 'dnt', 'origin', 'referer', 'user-agent']) {
+      delete headers[h];
+    }
+
+    // Resolve URL — if relative, prepend baseUrl
+    if (url.startsWith('/') && baseUrl) {
+      const normalized = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+      url = normalized + url;
+    }
+
+    // Fix redacted auth headers
+    for (const [key, val] of Object.entries(headers)) {
+      if (isRedacted(String(val))) {
+        const k = key.toLowerCase();
+        if (k === 'authorization') {
+          const token = captured.token || envVars.token;
+          if (token) headers[key] = token.startsWith('Bearer') ? token : `Bearer ${token}`;
+          else delete headers[key];
+        } else if (k === 'x-api-key' || k === 'api-key') {
+          const apiKey = captured.apiKey || envVars.sk || envVars.apiKey || envVars['x-api-key'];
+          if (apiKey) headers[key] = apiKey;
+          else delete headers[key];
+        } else {
+          delete headers[key];
+        }
+      }
+    }
+
+    // Fix redacted body fields (e.g. password)
+    if (body && typeof body === 'object') {
+      for (const [key, val] of Object.entries(body)) {
+        if (isRedacted(String(val))) {
+          // Try to find from env vars (password, secret, etc.)
+          const envVal = envVars[key] || envVars[key.toLowerCase()];
+          if (envVal) {
+            body[key] = envVal;
+          }
+          // If no env val found, leave <REDACTED> — will fail but at least user knows
+        }
+      }
+    }
+
+    // Replace {{var}} placeholders
+    const allVars = { ...envVars, ...captured };
+    url = replaceVars(url, allVars);
+    if (typeof body === 'string') body = replaceVars(body, allVars);
+    if (body && typeof body === 'object') body = replaceVarsDeep(body, allVars);
+    for (const [key, val] of Object.entries(headers)) {
+      if (typeof val === 'string') headers[key] = replaceVars(val, allVars);
+    }
+
+    // Execute
+    const shortUrl = url.replace(/^https?:\/\/[^/]+/, '');
+    const label = `[${i + 1}/${interactions.length}] ${method} ${shortUrl}`;
+    const spinner = ora({ text: chalk.gray(label), spinner: 'dots' }).start();
+    const start = Date.now();
+
+    try {
+      const res = await axios({
+        method: method.toLowerCase(),
+        url,
+        headers,
+        data: body,
+        timeout: options.timeout || 30000,
+        validateStatus: () => true,
+      });
+
+      const duration = Date.now() - start;
+      const status = res.status;
+      const statusColor = status >= 400 ? chalk.red : chalk.green;
+
+      spinner.stopAndPersist({
+        symbol: status >= 400 ? chalk.red('✗') : chalk.green('✓'),
+        text: `${statusColor(`${status}`)} ${chalk.gray(`${method} ${shortUrl}`)} ${chalk.dim(`${duration}ms`)}`,
+      });
+
+      // Auto-capture tokens from auth-like responses
+      if (res.data && typeof res.data === 'object') {
+        const data = res.data;
+        for (const field of ['token', 'accessToken', 'access_token', 'jwt', 'authToken', 'auth_token']) {
+          if (data[field] && typeof data[field] === 'string') {
+            captured.token = data[field];
+            if (options.verbose) console.log(chalk.dim(`    🔑 Captured ${field}`));
+          }
+          if (data.data && typeof data.data === 'object' && data.data[field]) {
+            captured.token = data.data[field];
+            if (options.verbose) console.log(chalk.dim(`    🔑 Captured data.${field}`));
+          }
+        }
+        for (const field of ['apiKey', 'api_key', 'key', 'publishableKey']) {
+          if (data[field] && typeof data[field] === 'string') {
+            captured.apiKey = data[field];
+          }
+        }
+      }
+
+      if (options.verbose && res.data) {
+        const bodyStr = typeof res.data === 'object' ? JSON.stringify(res.data, null, 2) : String(res.data);
+        const lines = bodyStr.split('\n');
+        const preview = lines.length > 6 ? lines.slice(0, 6).join('\n') + '\n    ...' : lines.join('\n');
+        console.log(chalk.gray(`    ↳ ${preview.split('\n').join('\n    ')}`));
+      }
+
+      if (status < 400) passed++;
+      else failed++;
+
+    } catch (err) {
+      const duration = Date.now() - start;
+      spinner.stopAndPersist({
+        symbol: chalk.red('✗'),
+        text: `${chalk.red('ERR')} ${chalk.gray(`${method} ${shortUrl}`)} ${chalk.dim(`${duration}ms`)} ${chalk.red(err.code || err.message)}`,
+      });
+      failed++;
+    }
+  }
+
+  // Summary
+  console.log(chalk.cyan(`\n  ── Run Complete ──`));
+  console.log(chalk.white(`  Snapshot: ${tag}`));
+  console.log(chalk.green(`  Passed:  ${passed}`));
+  if (failed > 0) console.log(chalk.red(`  Failed:  ${failed}`));
+  console.log(chalk.gray(`  Total:   ${interactions.length}\n`));
+
+  if (captured.token) {
+    console.log(chalk.dim(`  🔑 Auto-captured token from auth response`));
+    console.log('');
+  }
+
+  if (failed > 0 && options.failFast) {
+    process.exit(1);
+  }
+}
+
+function replaceVars(str, vars) {
+  return str.replace(/\{\{(.+?)\}\}/g, (match, key) => {
+    return vars[key] !== undefined ? vars[key] : match;
+  });
+}
+
+function replaceVarsDeep(obj, vars) {
+  if (typeof obj === 'string') return replaceVars(obj, vars);
+  if (Array.isArray(obj)) return obj.map(item => replaceVarsDeep(item, vars));
+  if (obj && typeof obj === 'object') {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+      result[k] = replaceVarsDeep(v, vars);
+    }
+    return result;
+  }
+  return obj;
+}

package/src/stats.js

@@ -1,8 +1,10 @@
 import chalk from 'chalk';
 import Table from 'cli-table3';
 import { getAllInteractions } from './storage.js';
+import { translateText } from './lingo.js';
 
-export function showStats() {
+export async function showStats(options = {}) {
+  const lang = options.lang;
   const interactions = getAllInteractions();
 
   if (interactions.length === 0) {
@@ -11,7 +13,9 @@ export function showStats() {
     return;
   }
 
-  console.log(chalk.cyan.bold('\n  📊 Kiroo Analytics Dashboard\n'));
+  let title = '📊 Kiroo Analytics Dashboard';
+  if (lang) title = await translateText(title, lang);
+  console.log(chalk.cyan.bold(`\n  ${title}\n`));
 
   // 1. General Metrics
   const total = interactions.length;
@@ -26,7 +30,9 @@ export function showStats() {
     { [chalk.white('Avg. Duration')]: chalk.white(avgDuration + 'ms') }
   );
 
-  console.log(chalk.white.bold('  ● General Performance'));
+  let generalHeader = '● General Performance';
+  if (lang) generalHeader = await translateText(generalHeader, lang);
+  console.log(chalk.white.bold(`  ${generalHeader}`));
   console.log(generalTable.toString());
 
   // 2. Method Distribution
@@ -45,7 +51,9 @@ export function showStats() {
     methodTable.push([chalk.white(method), chalk.white(count), chalk.gray(percentage)]);
   });
 
-  console.log(chalk.white.bold('\n  ● Request Distribution'));
+  let distHeader = '● Request Distribution';
+  if (lang) distHeader = await translateText(distHeader, lang);
+  console.log(chalk.white.bold(`\n  ${distHeader}`));
   console.log(methodTable.toString());
 
   // 3. Slowest Endpoints
@@ -67,7 +75,9 @@ export function showStats() {
     ]);
   });
 
-  console.log(chalk.white.bold('\n  ● Top 5 Slowest Endpoints (Bottlenecks)'));
+  let slowHeader = '● Top 5 Slowest Endpoints (Bottlenecks)';
+  if (lang) slowHeader = await translateText(slowHeader, lang);
+  console.log(chalk.white.bold(`\n  ${slowHeader}`));
   console.log(slowTable.toString());
   console.log('');
 }