kiroo 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yash Pouranik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+<div align="center">
+  <img src="./kiroo_banner.png" alt="Kiroo Banner" width="100%">
+
+  # 🦏 KIROO
+  ### **Version Control for API Interactions**
+  
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+  [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org/)
+  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
+
+  **Record, Replay, Snapshot, and Diff your APIs just like Git handles code.**
+
+  [Installation](#-installation) • [Quick Start](#-quick-start) • [Key Features](#-core-capabilities) • [Why Kiroo?](#-why-kiroo)
+
+</div>
+
+---
+
+## 📖 Introduction
+
+Kiroo treats your API requests and responses as **first-class versionable artifacts**. 
+
+Ever had a production bug that worked fine on your machine? Ever refactored a backend only to find out you broke a critical field 3 days later? Kiroo solves this by letting you **store API interactions in your repository**.
+
+Every interaction is a structured, reproducibility-focused JSON file that lives in your `.kiroo/` directory.
+
+---
+
+## ✨ Core Capabilities
+
+### 🔴 **Auto-Recording**
+Every request made through Kiroo is automatically saved. No more manual exports from Postman.
+```bash
+kiroo post {{baseUrl}}/users -d "name=Yash email=yash@example.com"
+```
+
+### 🔄 **Replay Engine**
+Re-run any past interaction instantly and see if the backend behavior has changed.
+```bash
+kiroo replay <interaction-id>
+```
+
+### 🌍 **Smart Environments & Variables**
+Stop copy-pasting tokens. Chain requests together dynamically.
+```bash
+# Save a token from login
+kiroo post /login --save token=data.accessToken
+
+# Use it in the next request
+kiroo get /profile -H "Authorization: Bearer {{token}}"
+```
+
+### 📸 **Snapshot System & Diff Engine**
+Capture the "Status Quo" of your API and detect **Breaking Changes** during refactors.
+```bash
+# Before refactor
+kiroo snapshot save v1-stable
+
+# After refactor
+kiroo snapshot compare v1-stable current
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+```bash
+# Clone the repo
+git clone https://github.com/yash-pouranik/kiroo.git
+cd kiroo
+
+# Install and link
+npm install
+npm link
+```
+
+### 2. Initialize
+```bash
+kiroo init
+```
+
+### 3. Basic Request
+```bash
+kiroo env set baseUrl http://localhost:3000
+kiroo get {{baseUrl}}/health
+```
+
+---
+
+## 🛠️ Advanced Workflows
+
+### Nested Data Support
+Kiroo's shorthand parser understands nested objects and arrays:
+```bash
+kiroo put /products/1 -d "reviews[0].stars=5 metadata.isFeatured=true"
+```
+
+### Managing Environments
+```bash
+kiroo env use prod
+kiroo env list
+```
+
+---
+
+## 🎯 Comparison
+
+| Feature | Postman / Insomnia | Bruno | **Kiroo** |
+| :--- | :---: | :---: | :---: |
+| **CLI-First** | ❌ | ⚠️ | ✅ |
+| **Git-Native** | ❌ | ✅ | ✅ |
+| **Auto-Recording** | ❌ | ❌ | ✅ |
+| **Built-in Replay** | ❌ | ❌ | ✅ |
+| **Variable Chaining** | ⚠️ | ⚠️ | ✅ |
+
+---
+
+## 📜 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+<div align="center">
+  Built with ❤️ for Developers by <a href="https://github.com/yash-pouranik">Yash Pouranik</a>
+</div>

package/bin/kiroo.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { executeRequest } from '../src/executor.js';
+import { listInteractions, replayInteraction } from '../src/replay.js';
+import { saveSnapshot, compareSnapshots, listSnapshots } from '../src/snapshot.js';
+import { setEnv, setVar, deleteVar, listEnv } from '../src/env.js';
+// import { showGraph } from '../src/graph.js';
+import { initProject } from '../src/init.js';
+// import { showStats } from '../src/stats.js';
+
+const program = new Command();
+
+program
+  .name('kiroo')
+  .description('Git for API interactions. Record, replay, snapshot, and diff your APIs.')
+  .version('0.2.0');
+
+// Init command
+program
+  .command('init')
+  .description('Initialize Kiroo in current directory')
+  .action(async () => {
+    await initProject();
+  });
+  // sk_live_p7BWJjsYlKmauBOjiEeiLRuu4DokkBWsgYne_E6osTo
+
+// HTTP methods as commands
+['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].forEach(method => {
+  program
+    .command(`${method.toLowerCase()} <url>`)
+    .alias(method)
+    .description(`Execute ${method} request and store interaction`)
+    .option('-H, --header <headers...>', 'Headers (key:value)')
+    .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);
+    });
+});
+
+// List interactions
+program
+  .command('list')
+  .description('List all stored interactions')
+  .option('-n, --limit <number>', 'Number of interactions to show', '10')
+  .option('-o, --offset <number>', 'Number of interactions to skip', '0')
+  .action(async (options) => {
+    await listInteractions(options);
+  });
+
+// Replay interaction
+program
+  .command('replay <id>')
+  .description('Replay a stored interaction')
+  .action(async (id) => {
+    await replayInteraction(id);
+  });
+
+// Environment commands
+const env = program.command('env').description('Environment management');
+
+env
+  .command('use <name>')
+  .description('Switch to a specific environment')
+  .action((name) => setEnv(name));
+
+env
+  .command('list')
+  .description('List environments and variables')
+  .action(() => listEnv());
+
+env
+  .command('set <key> <value>')
+  .description('Set a variable in current environment')
+  .action((key, value) => setVar(key, value));
+
+env
+  .command('rm <key>')
+  .description('Remove a variable from current environment')
+  .action((key) => deleteVar(key));
+
+// Snapshot commands
+const snapshot = program.command('snapshot').description('Snapshot management');
+
+snapshot
+  .command('save <tag>')
+  .description('Save current state as snapshot')
+  .action(async (tag) => {
+    await saveSnapshot(tag);
+  });
+
+snapshot
+  .command('list')
+  .description('List all snapshots')
+  .action(async () => {
+    await listSnapshots();
+  });
+
+snapshot
+  .command('compare <tag1> <tag2>')
+  .description('Compare two snapshots')
+  .action(async (tag1, tag2) => {
+    await compareSnapshots(tag1, tag2);
+  });
+
+// Graph command
+/*
+program
+  .command('graph')
+  .description('Show API dependency graph')
+  .action(async () => {
+    await showGraph();
+  });
+*/
+
+// Stats command
+/*
+program
+  .command('stats')
+  .description('Show usage statistics')
+  .action(async () => {
+    await showStats();
+  });
+*/
+
+// Error handling
+program.exitOverride();
+
+try {
+  await program.parseAsync(process.argv);
+} catch (err) {
+  if (err.code === 'commander.help' || err.message === '(outputHelp)') {
+    // Help was requested, exit normally
+    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'));
+    process.exit(1);
+  } else {
+    console.error(chalk.red('\n  ✗ Error:'), err.message, `(${err.code})`, '\n');
+    process.exit(1);
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "kiroo",
+  "version": "0.2.0",
+  "description": "Git for API interactions. Record, replay, snapshot, and diff your APIs.",
+  "type": "module",
+  "bin": {
+    "kiroo": "./bin/kiroo.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "node bin/kiroo.js",
+    "test": "node --test test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yash-pouranik/kiroo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yash-pouranik/kiroo/issues"
+  },
+  "homepage": "https://github.com/yash-pouranik/kiroo#readme",
+  "keywords": [
+    "api",
+    "testing",
+    "cli",
+    "replay",
+    "snapshot",
+    "diff",
+    "git-native",
+    "developer-tools"
+  ],
+  "author": "Yash Pouranik",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.7",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "inquirer": "^9.2.15",
+    "js-yaml": "^4.1.0",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/env.js

@@ -0,0 +1,64 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { loadEnv, saveEnv } from './storage.js';
+
+export function listEnv() {
+  const env = loadEnv();
+  
+  console.log(chalk.cyan(`\n  🌍 Environments:`));
+  Object.keys(env.environments).forEach(name => {
+    const activeMarker = name === env.current ? chalk.green(' (active)') : '';
+    console.log(`  - ${chalk.white(name)}${activeMarker}`);
+  });
+
+  const currentVars = env.environments[env.current];
+  if (Object.keys(currentVars).length > 0) {
+    console.log(chalk.cyan(`\n  📦 Variables in '${env.current}':`));
+    const table = new Table({
+      head: [chalk.cyan('Key'), chalk.cyan('Value')],
+      colWidths: [20, 40]
+    });
+    
+    Object.entries(currentVars).forEach(([k, v]) => {
+      table.push([chalk.white(k), chalk.gray(String(v))]);
+    });
+    console.log(table.toString());
+  } else {
+    console.log(chalk.gray(`\n  No variables set in '${env.current}' environment.`));
+  }
+  console.log('');
+}
+
+export function setEnv(name) {
+  const env = loadEnv();
+  if (name === 'list') {
+    return listEnv();
+  }
+
+  if (!env.environments[name]) {
+    env.environments[name] = {};
+    console.log(chalk.green(`  ✨ Created new environment:`), chalk.white(name));
+  }
+
+  env.current = name;
+  saveEnv(env);
+  console.log(chalk.green(`  🔄 Switched to environment:`), chalk.white(name));
+}
+
+export function setVar(key, value) {
+  const env = loadEnv();
+  env.environments[env.current][key] = value;
+  saveEnv(env);
+  console.log(chalk.green(`  ✅ Set ${key}=${value} in`), chalk.white(env.current));
+}
+
+export function deleteVar(key) {
+  const env = loadEnv();
+  if (env.environments[env.current][key] !== undefined) {
+    delete env.environments[env.current][key];
+    saveEnv(env);
+    console.log(chalk.green(`  🗑️  Deleted variable:`), chalk.white(key));
+  } else {
+    console.log(chalk.yellow(`  ⚠️  Variable '${key}' not found in environment '${env.current}'`));
+  }
+}

package/src/executor.js

@@ -0,0 +1,176 @@
+import axios from 'axios';
+import chalk from 'chalk';
+import ora from 'ora';
+import { saveInteraction, loadEnv, saveEnv } from './storage.js';
+import { formatResponse } from './formatter.js';
+
+function applyEnvReplacements(data, envVars) {
+  if (typeof data === 'string') {
+    return data.replace(/\{\{(.+?)\}\}/g, (match, key) => {
+      return envVars[key] !== undefined ? envVars[key] : match;
+    });
+  }
+  if (typeof data === 'object' && data !== null) {
+    const newData = Array.isArray(data) ? [] : {};
+    for (const key in data) {
+      newData[key] = applyEnvReplacements(data[key], envVars);
+    }
+    return newData;
+  }
+  return data;
+}
+
+function setDeep(obj, path, value) {
+  const keys = path.split(/[.[\]]+/).filter(Boolean);
+  let current = obj;
+  
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const isLast = i === keys.length - 1;
+    
+    if (isLast) {
+      current[key] = value;
+    } else {
+      // Check if next key looks like a number (array index)
+      const nextKey = keys[i + 1];
+      const isNextNumber = !isNaN(nextKey);
+      
+      if (!current[key]) {
+        current[key] = isNextNumber ? [] : {};
+      }
+      current = current[key];
+    }
+  }
+}
+
+function getDeep(obj, path) {
+  const keys = path.split(/[.[\]]+/).filter(Boolean);
+  return keys.reduce((acc, key) => acc && acc[key], obj);
+}
+
+export async function executeRequest(method, url, options = {}) {
+  const env = loadEnv();
+  const currentEnvVars = env.environments[env.current] || {};
+
+  // Apply replacements to URL
+  url = applyEnvReplacements(url, currentEnvVars);
+
+  // Parse headers
+  const headers = {};
+  if (options.header) {
+    options.header.forEach(h => {
+      const [key, ...valueParts] = h.split(':');
+      const headerValue = valueParts.join(':').trim();
+      headers[key.trim()] = applyEnvReplacements(headerValue, currentEnvVars);
+    });
+  }
+
+  // Parse body
+  let body;
+  if (options.data) {
+    let rawData = options.data;
+    // Apply replacements to raw data string before parsing
+    rawData = applyEnvReplacements(rawData, currentEnvVars);
+
+    try {
+      body = JSON.parse(rawData);
+    } catch {
+      body = {};
+      // Improved shorthand parser to handle quoted strings and nested objects
+      const pairs = rawData.match(/(\\.|[^ ])+/g) || [];
+      
+      pairs.forEach(pair => {
+        const [key, ...valueParts] = pair.split('=');
+        let value = valueParts.join('=');
+        
+        if (key && value !== undefined) {
+          let parsedValue;
+          // Check for quoted strings
+          if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            parsedValue = value.slice(1, -1);
+          } else {
+            parsedValue = value;
+            if (value === 'true') parsedValue = true;
+            else if (value === 'false') parsedValue = false;
+            else if (!isNaN(value) && value.trim() !== '') parsedValue = Number(value);
+          }
+          
+          setDeep(body, key, parsedValue);
+        }
+      });
+    }
+  }
+
+  // Ensure URL has protocol
+  if (!url.startsWith('http://') && !url.startsWith('https://')) {
+    url = 'https://' + url;
+  }
+
+  const spinner = ora('Sending request...').start();
+  const startTime = Date.now();
+
+  try {
+    const response = await axios({
+      method: method.toLowerCase(),
+      url,
+      headers,
+      data: body,
+      validateStatus: () => true,
+    });
+
+    const duration = Date.now() - startTime;
+    spinner.succeed(chalk.green(`${response.status} ${response.statusText}`) + chalk.gray(` (${duration}ms)`));
+
+    // Format and display response
+    console.log(formatResponse(response));
+
+    // Handle --save option
+    if (options.save) {
+      const saves = Array.isArray(options.save) ? options.save : [options.save];
+      saves.forEach(s => {
+        const [envKey, responsePath] = s.split('=');
+        if (envKey && responsePath) {
+          const val = getDeep(response, responsePath);
+          if (val !== undefined) {
+            env.environments[env.current][envKey] = val;
+            console.log(chalk.cyan(`  ✨ Saved to env:`), chalk.white(`${envKey}=${val}`));
+          } else {
+            console.log(chalk.yellow(`  ⚠️  Could not find path '${responsePath}' in response`));
+          }
+        }
+      });
+      saveEnv(env);
+    }
+
+    // Save interaction
+    const interactionId = await saveInteraction({
+      method,
+      url,
+      headers,
+      body,
+      response: {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        data: response.data,
+      },
+      duration,
+    });
+
+    console.log(chalk.gray('\n  💾 Interaction saved:'), chalk.white(interactionId));
+
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    spinner.fail(chalk.red('Request failed'));
+    
+    if (error.code === 'ENOTFOUND') {
+      console.error(chalk.red('\n  ✗ Host not found:'), url);
+    } else if (error.code === 'ECONNREFUSED') {
+      console.error(chalk.red('\n  ✗ Connection refused:'), url);
+    } else {
+      console.error(chalk.red('\n  ✗ Error:'), error.message, '\n');
+    }
+    
+    process.exit(1);
+  }
+}

package/src/formatter.js

@@ -0,0 +1,54 @@
+import chalk from 'chalk';
+
+export function formatResponse(response) {
+  const lines = [];
+  
+  // Status
+  const statusColor = response.status >= 200 && response.status < 300 
+    ? 'green' 
+    : response.status >= 400 
+    ? 'red' 
+    : 'yellow';
+  
+  lines.push('');
+  lines.push(chalk[statusColor].bold(`  ${response.status} ${response.statusText}`));
+  lines.push('');
+  
+  // Headers (selected)
+  const importantHeaders = ['content-type', 'content-length', 'set-cookie'];
+  const headers = Object.entries(response.headers)
+    .filter(([key]) => importantHeaders.includes(key.toLowerCase()))
+    .slice(0, 3);
+  
+  if (headers.length > 0) {
+    lines.push(chalk.gray('  Headers:'));
+    headers.forEach(([key, value]) => {
+      const displayValue = typeof value === 'string' && value.length > 50 
+        ? value.substring(0, 50) + '...' 
+        : value;
+      lines.push(chalk.gray(`    ${key}:`), chalk.white(displayValue));
+    });
+    lines.push('');
+  }
+  
+  // Body
+  if (response.data) {
+    lines.push(chalk.gray('  Response:'));
+    
+    if (typeof response.data === 'object') {
+      // Pretty print JSON
+      const json = JSON.stringify(response.data, null, 2);
+      json.split('\n').forEach(line => {
+        lines.push(chalk.cyan(`    ${line}`));
+      });
+    } else {
+      // Plain text
+      const text = String(response.data);
+      const preview = text.length > 500 ? text.substring(0, 500) + '...' : text;
+      lines.push(chalk.white(`    ${preview}`));
+    }
+  }
+  
+  lines.push('');
+  return lines.join('\n');
+}

package/src/init.js

@@ -0,0 +1,48 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { writeFileSync, existsSync } from 'fs';
+import { ensureKirooDir } from './storage.js';
+
+export async function initProject() {
+  console.log('');
+  console.log(chalk.cyan.bold('  🚀 Welcome to Kiroo'));
+  console.log(chalk.gray('  Git for API interactions\n'));
+  
+  if (existsSync('.kiroo')) {
+    console.log(chalk.yellow('  ⚠️  Kiroo is already initialized in this directory.\n'));
+    return;
+  }
+  
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      default: 'my-api-project',
+    },
+    {
+      type: 'input',
+      name: 'baseUrl',
+      message: 'Base URL (optional):',
+      default: '',
+    },
+  ]);
+  
+  ensureKirooDir();
+  
+  const config = {
+    projectName: answers.projectName,
+    baseUrl: answers.baseUrl,
+    createdAt: new Date().toISOString(),
+  };
+  
+  writeFileSync('.kiroo/config.json', JSON.stringify(config, null, 2));
+  
+  console.log('');
+  console.log(chalk.green('  ✅ Kiroo initialized successfully!'));
+  console.log('');
+  console.log(chalk.gray('  Next steps:'));
+  console.log(chalk.white('    kiroo POST https://api.example.com/login email=test@test.com'));
+  console.log(chalk.white('    kiroo list'));
+  console.log(chalk.white('    kiroo snapshot save initial\n'));
+}

package/src/replay.js

@@ -0,0 +1,94 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import axios from 'axios';
+import { getAllInteractions, loadInteraction } from './storage.js';
+import { formatResponse } from './formatter.js';
+
+export async function listInteractions(options) {
+  const interactions = getAllInteractions();
+  const limit = parseInt(options.limit) || 10;
+  const offset = parseInt(options.offset) || 0;
+  
+  if (interactions.length === 0) {
+    console.log(chalk.yellow('\n  No interactions found.'));
+    console.log(chalk.gray('  Run a request first: '), chalk.white('kiroo POST https://api.example.com/endpoint\n'));
+    return;
+  }
+  
+  const table = new Table({
+    head: ['ID', 'Method', 'URL', 'Status', 'Duration'].map(h => chalk.cyan(h)),
+    colWidths: [26, 8, 45, 8, 12],
+  });
+  
+  const page = interactions.slice(offset, offset + limit);
+  
+  page.forEach(int => {
+    const statusColor = int.response.status >= 200 && int.response.status < 300 
+      ? chalk.green 
+      : int.response.status >= 400 
+      ? chalk.red 
+      : chalk.yellow;
+    
+    table.push([
+      chalk.white(int.id),
+      chalk.white(int.request.method),
+      chalk.gray(int.request.url.substring(0, 42) + (int.request.url.length > 42 ? '...' : '')),
+      statusColor(int.response.status),
+      chalk.gray(int.metadata.duration_ms + 'ms'),
+    ]);
+  });
+  
+  console.log('');
+  console.log(table.toString());
+  console.log('');
+  
+  const start = offset + 1;
+  const end = Math.min(offset + limit, interactions.length);
+  
+  console.log(chalk.gray(`  Showing ${start}-${end} of ${interactions.length} interactions`));
+  if (interactions.length > offset + limit) {
+    console.log(chalk.gray(`  Next page: `), chalk.white(`kiroo list --offset ${offset + limit}\n`));
+  } else {
+    console.log('');
+  }
+  console.log(chalk.gray('  Replay: '), chalk.white('kiroo replay <id>\n'));
+}
+
+export async function replayInteraction(id) {
+  try {
+    const interaction = loadInteraction(id);
+    
+    console.log(chalk.cyan(`\n  🔄 Replaying interaction:`), chalk.white(id));
+    console.log(chalk.gray(`  ${interaction.request.method} ${interaction.request.url}\n`));
+    
+    const startTime = Date.now();
+    const response = await axios({
+      method: interaction.request.method.toLowerCase(),
+      url: interaction.request.url,
+      headers: interaction.request.headers,
+      data: interaction.request.body,
+      validateStatus: () => true,
+    });
+    const duration = Date.now() - startTime;
+    
+    console.log(formatResponse(response));
+    
+    // Simple comparison
+    console.log(chalk.cyan('  📊 Comparison with stored response:'));
+    
+    if (response.status === interaction.response.status) {
+      console.log(chalk.green('  ✓ Status matches:'), chalk.white(response.status));
+    } else {
+      console.log(chalk.red('  ✗ Status changed:'), chalk.gray(interaction.response.status), chalk.white('→'), chalk.red(response.status));
+    }
+    
+    const timeDiff = duration - interaction.metadata.duration_ms;
+    const timeColor = timeDiff > 0 ? chalk.yellow : chalk.green;
+    console.log(chalk.gray('  ⏱  Duration:'), chalk.white(`${duration}ms`), timeColor(`(${timeDiff > 0 ? '+' : ''}${timeDiff}ms)`));
+    console.log('');
+    
+  } catch (error) {
+    console.error(chalk.red('\n  ✗ Replay failed:'), error.message, '\n');
+    process.exit(1);
+  }
+}

package/src/snapshot.js

@@ -0,0 +1,127 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { getAllInteractions, saveSnapshotData, getAllSnapshots, loadSnapshotData } from './storage.js';
+
+export async function saveSnapshot(tag) {
+  const interactions = getAllInteractions();
+  
+  if (interactions.length === 0) {
+    console.log(chalk.yellow('\n  No interactions to snapshot.'));
+    console.log(chalk.gray('  Run some requests first.\n'));
+    return;
+  }
+  
+  const snapshotData = {
+    tag,
+    timestamp: new Date().toISOString(),
+    interactions: interactions.map(int => ({
+      id: int.id,
+      method: int.request.method,
+      url: int.request.url,
+      request: int.request,
+      response: {
+        status: int.response.status,
+        body: int.response.data
+      },
+      metadata: int.metadata
+    }))
+  };
+  
+  saveSnapshotData(tag, snapshotData);
+  
+  console.log(chalk.green(`\n  📸 Snapshot saved:`), chalk.white(tag));
+  console.log(chalk.gray(`  Contains ${interactions.length} interactions\n`));
+}
+
+export async function listSnapshots() {
+  const snapshots = getAllSnapshots();
+  
+  if (snapshots.length === 0) {
+    console.log(chalk.yellow('\n  No snapshots found.'));
+    console.log(chalk.gray('  Save one with: '), chalk.white('kiroo snapshot save <tag>\n'));
+    return;
+  }
+  
+  console.log(chalk.cyan('\n  📸 Available Snapshots:'));
+  snapshots.forEach(tag => {
+    console.log(`  - ${chalk.white(tag)}`);
+  });
+  console.log('');
+}
+
+export async function compareSnapshots(tag1, tag2) {
+  try {
+    const s1 = loadSnapshotData(tag1);
+    const s2 = loadSnapshotData(tag2);
+    
+    console.log(chalk.cyan(`\n  🔍 Comparing Snapshots:`), chalk.white(tag1), chalk.gray('vs'), chalk.white(tag2));
+    
+    const results = [];
+    let breakingChanges = 0;
+    
+    // Simplistic comparison: match by URL and Method
+    s2.interactions.forEach(int2 => {
+      const int1 = s1.interactions.find(i => i.url === int2.url && i.method === int2.method);
+      
+      if (!int1) {
+        results.push({
+          type: 'NEW',
+          method: int2.method,
+          url: int2.url,
+          msg: chalk.blue('New interaction added')
+        });
+        return;
+      }
+      
+      const diffs = [];
+      
+      // Compare status
+      if (int1.response.status !== int2.response.status) {
+        diffs.push(`Status: ${chalk.gray(int1.response.status)} → ${chalk.red(int2.response.status)}`);
+        breakingChanges++;
+      }
+      
+      // Deep field comparison (very basic for MVP)
+      if (typeof int1.response.body === 'object' && typeof int2.response.body === 'object' && int1.response.body !== null && int2.response.body !== null) {
+        const keys1 = Object.keys(int1.response.body);
+        const keys2 = Object.keys(int2.response.body);
+        
+        const removed = keys1.filter(k => !keys2.includes(k));
+        if (removed.length > 0) {
+          diffs.push(`Fields removed: ${chalk.red(removed.join(', '))}`);
+          breakingChanges++;
+        }
+      }
+      
+      if (diffs.length > 0) {
+        results.push({
+          type: 'CHANGE',
+          method: int2.method,
+          url: int2.url,
+          msg: diffs.join('\n    ')
+        });
+      }
+    });
+
+    if (results.length === 0) {
+      console.log(chalk.green('\n  ✅ No differences detected. Your API is stable!\n'));
+    } else {
+      console.log('');
+      results.forEach(res => {
+        const symbol = res.type === 'NEW' ? chalk.blue('+') : chalk.yellow('⚠️');
+        console.log(`  ${symbol} ${chalk.white(res.method)} ${chalk.gray(res.url)}`);
+        console.log(`    ${res.msg}`);
+      });
+      
+      if (breakingChanges > 0) {
+        console.log(chalk.red(`\n  🚨 Detected ${breakingChanges} potential breaking changes!\n`));
+      } else {
+        console.log(chalk.blue('\n  ℹ️ Non-breaking changes detected.\n'));
+      }
+    }
+
+  } catch (error) {
+    console.error(chalk.red('\n  ✗ Comparison failed:'), error.message, '\n');
+    process.exit(1);
+  }
+}

package/src/storage.js

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const KIROO_DIR = '.kiroo';
+const INTERACTIONS_DIR = join(KIROO_DIR, 'interactions');
+const SNAPSHOTS_DIR = join(KIROO_DIR, 'snapshots');
+const ENV_FILE = join(KIROO_DIR, 'env.json');
+
+export function ensureKirooDir() {
+  if (!existsSync(KIROO_DIR)) {
+    mkdirSync(KIROO_DIR);
+  }
+  if (!existsSync(INTERACTIONS_DIR)) {
+    mkdirSync(INTERACTIONS_DIR);
+  }
+  if (!existsSync(SNAPSHOTS_DIR)) {
+    mkdirSync(SNAPSHOTS_DIR);
+  }
+  if (!existsSync(ENV_FILE)) {
+    writeFileSync(ENV_FILE, JSON.stringify({ current: 'default', environments: { default: {} } }, null, 2));
+  }
+}
+
+export async function saveInteraction(interaction) {
+  ensureKirooDir();
+  
+  const timestamp = new Date().toISOString();
+  const id = timestamp.replace(/[:.]/g, '-');
+  
+  const interactionData = {
+    id,
+    timestamp,
+    request: {
+      method: interaction.method,
+      url: interaction.url,
+      headers: interaction.headers,
+      body: interaction.body,
+    },
+    response: interaction.response,
+    metadata: {
+      duration_ms: interaction.duration,
+    },
+  };
+
+  const filename = `${id}.json`;
+  const filepath = join(INTERACTIONS_DIR, filename);
+  
+  writeFileSync(filepath, JSON.stringify(interactionData, null, 2));
+  
+  return id;
+}
+
+export function loadInteraction(id) {
+  const filepath = join(INTERACTIONS_DIR, `${id}.json`);
+  
+  if (!existsSync(filepath)) {
+    throw new Error(`Interaction not found: ${id}`);
+  }
+  
+  const data = readFileSync(filepath, 'utf8');
+  return JSON.parse(data);
+}
+
+export function getAllInteractions() {
+  ensureKirooDir();
+  
+  if (!existsSync(INTERACTIONS_DIR)) {
+    return [];
+  }
+  
+  const files = readdirSync(INTERACTIONS_DIR)
+    .filter(f => f.endsWith('.json'))
+    .sort()
+    .reverse(); // Most recent first
+  
+  return files.map(f => {
+    const filepath = join(INTERACTIONS_DIR, f);
+    const data = readFileSync(filepath, 'utf8');
+    return JSON.parse(data);
+  });
+}
+
+export function saveSnapshotData(tag, data) {
+  ensureKirooDir();
+  
+  const filename = `${tag}.json`;
+  const filepath = join(SNAPSHOTS_DIR, filename);
+  
+  writeFileSync(filepath, JSON.stringify(data, null, 2));
+}
+
+export function loadSnapshotData(tag) {
+  const filepath = join(SNAPSHOTS_DIR, `${tag}.json`);
+  
+  if (!existsSync(filepath)) {
+    throw new Error(`Snapshot not found: ${tag}`);
+  }
+  
+  const data = readFileSync(filepath, 'utf8');
+  return JSON.parse(data);
+}
+
+export function getAllSnapshots() {
+  ensureKirooDir();
+  
+  if (!existsSync(SNAPSHOTS_DIR)) {
+    return [];
+  }
+  
+  return readdirSync(SNAPSHOTS_DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace('.json', ''));
+}
+
+export function loadEnv() {
+  ensureKirooDir();
+  const data = readFileSync(ENV_FILE, 'utf8');
+  return JSON.parse(data);
+}
+
+export function saveEnv(data) {
+  ensureKirooDir();
+  writeFileSync(ENV_FILE, JSON.stringify(data, null, 2));
+}