@kendroger/io-snapshot 1.0.0

package/.snapdiffrc.json

@@ -0,0 +1,5 @@
+{
+  "port": 9444,
+  "timeout": 15,
+  "exclude": ["node_modules", "dist", "*.snap.bak"]
+}

package/README.md

@@ -0,0 +1,118 @@
+# 📸 io-snapshot
+
+`io-snapshot` is a powerful behavior-preservation tool designed for zero-regression refactoring. It captures the exact inputs and outputs of your functions during real-world execution and allows you to "replay" them later to ensure that your structural changes haven't introduced behavioral drift.
+
+[![npm version](https://img.shields.io/npm/v/io-snapshot.svg)](https://www.npmjs.com/package/io-snapshot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Why io-snapshot?
+
+Unit tests verify what you *expect* to happen. `io-snapshot` verifies what *actually happens* in your application. It acts as a safety net for:
+
+- **Major Refactors:** Switching from Promises to `async/await` or restructuring complex logic.
+- **Dependency Swaps:** Replacing one library with another while maintaining the same interface.
+- **Performance Tuning:** Ensuring that optimizations don't break edge cases or return values.
+- **Legacy Code:** Safely refactoring codebases that lack traditional test coverage.
+
+## 📦 Installation
+
+Install globally or as a dev dependency:
+
+```bash
+# Global installation
+npm install -g io-snapshot
+
+# Local installation
+npm install --save-dev io-snapshot
+```
+
+## 🛠 Workflow
+
+`io-snapshot` follows a simple 4-step workflow:
+
+### 1. Record
+Inject the recorder into your target files and start capturing snapshots while you use your application.
+
+```bash
+io-snapshot record ./src/services/*.ts
+```
+*Wait for the "Recording started" message, then start and interact with your app.*
+
+### 2. Stop & Restore
+Once you've captured enough data, stop the recording. This restores your original source code but preserves the snapshots in `.snaps.jsonl`.
+
+```bash
+io-snapshot stop
+```
+
+### 3. Refactor
+Modify your code, optimize your functions, or swap dependencies. As long as the function name and exported interface remain the same, you're good to go.
+
+### 4. Verify
+Run the test command to replay the captured inputs against your new code and compare the outputs.
+
+```bash
+io-snapshot test ./src/services/*.ts
+```
+
+## ⌨️ Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `record [target]` | Injects recorder, starts daemon, and begins capturing snapshots. |
+| `stop` | Stops the daemon and restores original source code. |
+| `test [target]` | Replays snapshots against current code and reports any drift. |
+| `clean [target]` | Restores original files and deletes the snapshot data. |
+| `inject [target]` | Explicitly injects the recorder without starting the daemon. |
+
+## ⚙️ Configuration
+
+You can configure `io-snapshot` via a `.iosnapshotrc.json` file in your project root.
+
+**File Locations:**
+- **`.snaps.jsonl`**: Stores your recorded snapshots directly in your project's root directory.
+- **Temporary Session Files**: Files like the daemon's PID (`.io-snapshot.pid`) and the injected recorder code (`.io-snapshot/recorder.js`) are stored in a unique, project-specific directory within your **operating system's temporary folder**. This ensures a clean project root and prevents conflicts.
+- **Backup Files**:
+  - **Primary Backups**: Created in the OS temporary folder alongside other temporary session files.
+  - **Fallback Backups**: Created in a `.io-snapshot-local-backups/` directory in your project's root for persistence against OS temp folder cleanup.
+
+```json
+{
+  "port": 9444,
+  "timeout": 30,
+  "exclude": ["node_modules/**", "test/**"]
+}
+```
+
+## 🤔 Troubleshooting
+
+Here are some common issues and how to solve them in simple terms.
+
+| Problem | Solution |
+| :--- | :--- |
+| **`"io-snapshot: command not found"`** | This usually means the tool wasn't installed correctly. Try running `npm install -g io-snapshot` again. If you installed it locally (`--save-dev`), you'll need to run it through an npm script. |
+| **`"io-snapshot is already running!"`** | You have a previous session that wasn't stopped. Run `io-snapshot stop` to end it, and then you can start a new recording. |
+| **No snapshots are being recorded.** | 1. Make sure you are running your application *after* `io-snapshot record` says "Recording started." <br> 2. Check that the functions you want to record are **exported** from their files. <br> 3. Make sure you are interacting with the parts of your app that use those functions. |
+| **`"EADDRINUSE: address already in use"`** | The port `io-snapshot` wants to use (default: 9444) is occupied. You can either stop the other program or tell `io-snapshot` to use a different port with the `-p` flag: `io-snapshot record -p 9445` |
+| **Tests are passing, but I know the logic is different.**| `io-snapshot` checks if the final *output* is the same for a given *input*. If your refactor produces the same result (e.g., changing a `for` loop to a `.map()`), `io-snapshot` will correctly report no change in behavior. It only cares about the "what," not the "how." |
+
+## 🔍 How it Works
+
+1. **Instrumentation:** It uses `ts-morph` and `Babel` to wrap your exported functions with a Proxy.
+2. **Backup:** Before injecting, `io-snapshot` creates two backups of your original files:
+   - A **primary backup** in a temporary directory managed by your operating system.
+   - A **fallback backup** in a `.io-snapshot-local-backups/` directory within your project's root.
+   This ensures that even if OS temporary files are cleared, your original code can still be restored.
+3. **Capture:** When the wrapped functions are called, the inputs and outputs are sent to a local background daemon.
+4. **Storage:** Snapshots are serialized using `SuperJSON` (to preserve complex types like Dates and RegEx) and stored in a newline-delimited JSON file (`.snaps.jsonl`) in your project root.
+5. **Verification:** The test runner imports your modified functions and feeds them the exact arguments from the snapshots, then performs a deep-diff on the results. When restoring, it first attempts to use the primary backup, falling back to the local backup if necessary.
+
+## ⚠️ Requirements & Limitations
+
+- Functions must be **exported** to be captured.
+- Data must be **serializable** (SuperJSON handles many complex types, but extremely complex circular references or native handles might be tricky).
+- Currently supports **ES Modules (ESM)** projects.
+
+## 📄 License
+
+MIT © [kendroger](https://github.com/kendroger)

package/bin/cli.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import http from 'http';
+import { SNAPSHOT_FILE } from '../lib/constants.js';
+import { loadConfig, validatePort, validateTimeout, validateFilePattern } from '../lib/config.js';
+import { log } from '../lib/logger.js';
+import { getPidFilePath, ensureTempSessionDir } from '../lib/paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function savePid(pid) {
+    const pidPath = getPidFilePath();
+    ensureTempSessionDir(); // Ensure the temp directory exists before saving PID
+    fs.writeFileSync(pidPath, String(pid));
+}
+
+function getSavedPid() {
+    const pidPath = getPidFilePath();
+    if (fs.existsSync(pidPath)) {
+        return parseInt(fs.readFileSync(pidPath, 'utf8'), 10);
+    }
+    return null;
+}
+
+function removePid() {
+    const pidPath = getPidFilePath();
+    if (fs.existsSync(pidPath)) {
+        fs.unlinkSync(pidPath);
+    }
+}
+
+async function daemonRequest(endpoint, port, method = 'POST') {
+    return new Promise((resolve, reject) => {
+        const req = http.request(`http://localhost:${port}${endpoint}`, { method }, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                } catch {
+                    resolve(data);
+                }
+            });
+        });
+        req.on('error', reject);
+        req.end();
+    });
+}
+
+program
+    .name('io-snapshot')
+    .description('Capture and compare function behavior snapshots for zero-regression refactoring');
+
+program
+    .command('inject [target]')
+    .description('Inject recorder into target files (for explicit use)')
+    .option('-f, --force', 'Force re-inject even if already injected')
+    .action(async (target, opts) => {
+        try {
+            if (target) validateFilePattern(target);
+        } catch (error) {
+            log.error(error.message);
+            process.exit(1);
+        }
+
+        const { injectRecorder } = await import('../lib/transformer.js');
+        await injectRecorder(target, opts.force);
+    });
+
+program
+    .command('record [target]')
+    .description('Inject, start daemon, and begin recording snapshots')
+    .option('-p, --port <port>', 'Port to run the daemon on')
+    .option('-t, --timeout <minutes>', 'Auto-shutdown after N minutes of inactivity')
+    .option('-f, --force', 'Force re-inject even if already injected')
+    .action(async (target, opts) => {
+        try {
+            if (opts.port) validatePort(opts.port);
+            if (opts.timeout) validateTimeout(opts.timeout);
+            if (target) validateFilePattern(target);
+        } catch (error) {
+            log.error(error.message);
+            process.exit(1);
+        }
+
+        const config = loadConfig();
+        const port = opts.port || config.port || 9444;
+        const timeout = config.timeout || 30; // Use config.timeout directly, as opts.timeout is used above
+
+        log.divider('IMPORTANT');
+        log.info('Run this command FIRST,');
+        log.info('         THEN start your app!');
+        log.divider();
+
+        log.workflow([
+            'io-snapshot record  → Inject code + start daemon + begin recording',
+            'npm run dev       → Start your app (AFTER recording has started)',
+            'Interact with app → Use your app to capture snapshots',
+            'io-snapshot stop    → Stop recording, restore original code',
+            'Modify your code  → Refactor/change your functions',
+            'io-snapshot test    → Verify changes against recorded snapshots'
+        ]);
+
+        const snapshotPath = path.resolve(process.cwd(), SNAPSHOT_FILE);
+        if (fs.existsSync(snapshotPath)) {
+            fs.unlinkSync(snapshotPath);
+            log.info('Cleared previous snapshot file.');
+        }
+
+        log.info('Checking for existing io-snapshot session...');
+        const savedPid = getSavedPid();
+        if (savedPid) {
+            try {
+                process.kill(savedPid, 0);
+                log.divider();
+                log.warn('io-snapshot is already running!');
+                log.warn(`A daemon is active (PID: ${savedPid})`);
+                log.warn('Please run "io-snapshot stop" first before starting a new session.');
+                log.divider();
+                process.exit(1);
+            } catch {
+                // Process not running, clean up stale PID
+                removePid();
+            }
+        }
+
+        log.step(1, 'Injecting recorder into files...');
+        const { injectRecorder } = await import('../lib/transformer.js');
+        await injectRecorder(target, opts.force);
+
+        log.step(2, 'Starting daemon...');
+        const env = {
+            ...process.env,
+            IOSNAP_DAEMON_PORT: String(port),
+            IOSNAP_DAEMON_CORS: '*'
+        };
+
+        const child = spawn(process.execPath, [path.join(__dirname, '../lib/daemon.js')], {
+            cwd: process.cwd(),
+            stdio: 'ignore',
+            env,
+            detached: true
+        });
+
+        child.unref();
+        savePid(child.pid);
+        log.success(`Daemon started on port ${port} (PID: ${child.pid})`);
+
+        await new Promise(resolve => setTimeout(resolve, 1000));
+
+        log.step(3, 'Starting recording...');
+        
+        try {
+            await daemonRequest('/record', port);
+            log.success('Recording started.');
+            log.info(`Snapshots will be saved to: ${snapshotPath}`);
+            log.divider();
+            log.success('NOW START YOUR APP (npm run dev)');
+            log.info('Interact with your app to capture snapshots.');
+            log.info('Run "io-snapshot stop" when done to stop recording and restore original code.');
+            log.divider();
+        } catch (error) {
+            log.error(`Failed to start recording: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('stop')
+    .description('Stop recording, stop daemon, and restore original code (snapshots preserved)')
+    .option('-p, --port <port>', 'Port where the daemon is running')
+    .action(async (opts) => {
+        try {
+            if (opts.port) validatePort(opts.port);
+        } catch (error) {
+            log.error(error.message);
+            process.exit(1);
+        }
+
+        const config = loadConfig();
+        const port = opts.port || config.port || 9444;
+
+        log.step(1, 'Stopping recording...');
+        try {
+            await daemonRequest('/stop', port);
+            log.success('Recording stopped.');
+        } catch (error) {
+            log.warn(`Daemon not responding: ${error.message}. May already be stopped.`);
+        }
+
+        log.step(2, 'Stopping daemon...');
+        const savedPid = getSavedPid();
+        if (savedPid) {
+            try {
+                process.kill(savedPid, 'SIGTERM');
+                log.success(`Daemon (PID: ${savedPid}) stopped.`);
+                removePid();
+            } catch (error) {
+                log.warn('Daemon not running, cleaning up stale PID file.');
+                removePid();
+            }
+        }
+
+        log.step(3, 'Restoring original code...');
+        const { restore } = await import('../lib/transformer.js');
+        await restore(null, true);
+
+        const snapshotPath = path.resolve(process.cwd(), SNAPSHOT_FILE);
+        if (fs.existsSync(snapshotPath)) {
+            const stats = fs.statSync(snapshotPath);
+            log.success(`Snapshots preserved at: ${snapshotPath} (${stats.size} bytes)`);
+        }
+
+        log.divider();
+        log.success('Original code restored. Snapshots preserved for testing.');
+        log.info('Run "io-snapshot test" to verify your code changes.');
+        log.divider();
+    });
+
+program
+    .command('test [target]')
+    .description('Replay snapshots against current code to verify behavior')
+    .action(async (target) => {
+        try {
+            if (target) validateFilePattern(target);
+        } catch (error) {
+            log.error(error.message);
+            process.exit(1);
+        }
+
+        const { verifyDir } = await import('../lib/verifier.js');
+        await verifyDir(target);
+    });
+
+program
+    .command('clean [target]')
+    .description('Restore original files and delete snapshots')
+    .action(async (target) => {
+        try {
+            if (target) validateFilePattern(target);
+        } catch (error) {
+            log.error(error.message);
+            process.exit(1);
+        }
+
+        const { restore } = await import('../lib/transformer.js');
+        await restore(target);
+    });
+
+program.parse();

package/lib/config.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import path from 'path';
+import { CONFIG_FILE } from './constants.js';
+
+export function loadConfig() {
+    const configPath = path.resolve(process.cwd(), CONFIG_FILE);
+
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        return JSON.parse(content);
+    } catch (error) {
+        console.warn(`[io-snapshot] Warning: Failed to parse config file: ${error.message}`);
+        return {};
+    }
+}
+
+export function validatePort(port) {
+    const portNum = parseInt(port, 10);
+    if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+        throw new Error(`Invalid port: ${port}. Must be between 1 and 65535.`);
+    }
+    return portNum;
+}
+
+export function validateTimeout(timeout) {
+    const timeoutNum = parseInt(timeout, 10);
+    if (isNaN(timeoutNum) || timeoutNum < 1) {
+        throw new Error(`Invalid timeout: ${timeout}. Must be a positive number.`);
+    }
+    return timeoutNum;
+}
+
+export function validateFilePattern(pattern) {
+    if (!pattern || typeof pattern !== 'string') {
+        throw new Error('File pattern must be a non-empty string.');
+    }
+    return pattern;
+}

package/lib/constants.js

@@ -0,0 +1,10 @@
+export const DEFAULT_PORT = 9444;
+export const DEFAULT_TIMEOUT = 30;
+export const SNAPSHOT_FILE = '.snaps.jsonl'; // In project root
+export const TEMP_SESSION_DIR_PREFIX = 'io-snapshot-session-';
+export const TEMP_SUBDIR_NAME = '.io-snapshot'; // Subdirectory within the session temp dir
+export const PID_FILE_NAME = '.io-snapshot.pid'; // In the session temp dir
+export const RECORDER_FILE_NAME = 'recorder.js'; // In the session temp dir
+export const LOCAL_BACKUP_DIR = '.io-snapshot-local-backups';
+export const CONFIG_FILE = '.iosnapshotrc.json';
+export const BACKUP_EXT = '.snap.bak';

package/lib/daemon.js

@@ -0,0 +1,193 @@
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { DEFAULT_PORT, DEFAULT_TIMEOUT, SNAPSHOT_FILE } from './constants.js';
+import { loadConfig } from './config.js';
+import { log } from './logger.js';
+import { getPidFilePath } from './paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+let isRecording = false;
+let lastTelemetryTime = Date.now();
+let server = null;
+let timeoutInterval = null;
+let corsOrigin = '*';
+
+function setCorsHeaders(res) {
+    if (corsOrigin === '*') {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+    } else if (corsOrigin) {
+        res.setHeader('Access-Control-Allow-Origin', corsOrigin);
+    }
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+}
+
+function sendResponse(res, statusCode, data) {
+    setCorsHeaders(res);
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+}
+
+function savePid(pid) {
+    fs.writeFileSync(getPidFilePath(), String(pid));
+}
+
+function removePid() {
+    const pidPath = getPidFilePath();
+    if (fs.existsSync(pidPath)) {
+        fs.unlinkSync(pidPath);
+    }
+}
+
+function resetTimeout() {
+    lastTelemetryTime = Date.now();
+}
+
+function startTimeoutWatcher(timeoutMinutes) {
+    if (timeoutInterval) clearInterval(timeoutInterval);
+
+    timeoutInterval = setInterval(() => {
+        const elapsed = (Date.now() - lastTelemetryTime) / 1000 / 60;
+        if (elapsed >= timeoutMinutes && server) {
+            log.error(`Daemon auto-shutting down after ${timeoutMinutes} minutes of inactivity.`);
+            stopServer();
+        }
+    }, 30000);
+}
+
+function stopServer() {
+    if (server) {
+        server.close();
+        server = null;
+    }
+    if (timeoutInterval) {
+        clearInterval(timeoutInterval);
+        timeoutInterval = null;
+    }
+    removePid();
+    process.exit(0);
+}
+
+async function handleTelemetry(req, res) {
+    let body = '';
+    for await (const chunk of req) {
+        body += chunk;
+    }
+
+    if (!isRecording) {
+        sendResponse(res, 200, { status: 'ignored', reason: 'not_recording' });
+        return;
+    }
+
+    resetTimeout();
+
+    try {
+        fs.appendFileSync(path.resolve(process.cwd(), SNAPSHOT_FILE), body + '\n');
+        sendResponse(res, 200, { status: 'captured' });
+    } catch (error) {
+        sendResponse(res, 500, { error: error.message });
+    }
+}
+
+function startDaemon(port, timeoutMinutes, corsOptions) {
+    if (corsOptions?.origin) {
+        corsOrigin = corsOptions.origin;
+    }
+
+    server = http.createServer(async (req, res) => {
+        const url = new URL(req.url, `http://localhost:${port}`);
+
+        if (req.method === 'OPTIONS') {
+            setCorsHeaders(res);
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+
+        if (req.method === 'GET' && url.pathname === '/status') {
+            sendResponse(res, 200, {
+                isRecording,
+                timeout: timeoutMinutes,
+                uptime: process.uptime(),
+                corsOrigin
+            });
+            return;
+        }
+
+        if (req.method === 'POST' && url.pathname === '/record') {
+            isRecording = true;
+            resetTimeout();
+            const snapshotPath = path.resolve(process.cwd(), SNAPSHOT_FILE);
+            log.success('Recording started.');
+            log.info(`Saving snapshots to: ${snapshotPath}`);
+            sendResponse(res, 200, { isRecording: true });
+            return;
+        }
+
+        if (req.method === 'POST' && url.pathname === '/stop') {
+            isRecording = false;
+            log.success('Recording stopped.');
+            sendResponse(res, 200, { isRecording: false });
+            return;
+        }
+
+        if (req.method === 'POST' && url.pathname === '/telemetry') {
+            await handleTelemetry(req, res);
+            return;
+        }
+
+        sendResponse(res, 404, { error: 'Not found' });
+    });
+
+    server.on('error', (error) => {
+        if (error.code === 'EADDRINUSE') {
+            log.error(`Port ${port} is already in use.`);
+            process.exit(1);
+        }
+        throw error;
+    });
+
+    server.listen(port, () => {
+        const snapshotPath = path.resolve(process.cwd(), SNAPSHOT_FILE);
+        log.info(`Daemon running on http://localhost:${port}`);
+        log.info(`Snapshots will be saved to: ${snapshotPath}`);
+        log.info(`Auto-shutdown after ${timeoutMinutes} minutes of inactivity.`);
+        savePid(process.pid);
+        startTimeoutWatcher(timeoutMinutes);
+    });
+}
+
+export function runDaemon(port, timeout, corsOptions) {
+    const config = loadConfig();
+    const actualPort = port || config.port || DEFAULT_PORT;
+    const actualTimeout = timeout || config.timeout || DEFAULT_TIMEOUT;
+    const corsEnv = process.env.IOSNAP_DAEMON_CORS || config.cors?.origin || '*';
+    startDaemon(actualPort, actualTimeout, { origin: corsEnv });
+}
+
+export function stopDaemon() {
+    const config = loadConfig();
+    const port = config.port || DEFAULT_PORT;
+
+    http.get(`http://localhost:${port}/status`, (res) => {
+        res.resume();
+        if (res.statusCode === 200) {
+            const req = http.request(`http://localhost:${port}/stop`, { method: 'POST' }, () => {
+                log.success('Daemon stopped.');
+                process.exit(0);
+            });
+            req.end();
+        }
+    }).on('error', () => {
+        log.error('Daemon is not running.');
+        process.exit(1);
+    });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const config = loadConfig();
+    runDaemon(config.port || DEFAULT_PORT, config.timeout || DEFAULT_TIMEOUT);
+}

package/lib/logger.js

@@ -0,0 +1,42 @@
+const PREFIX = '[io-snapshot]';
+
+export const log = {
+    info(...args) {
+        console.log(PREFIX, ...args);
+    },
+
+    warn(...args) {
+        console.warn(PREFIX, 'Warning:', ...args);
+    },
+
+    error(...args) {
+        console.error(PREFIX, 'Error:', ...args);
+    },
+
+    success(...args) {
+        console.log(PREFIX, '✓', ...args);
+    },
+
+    step(stepNumber, ...args) {
+        console.log(PREFIX, `Step ${stepNumber}:`, ...args);
+    },
+
+    divider(text = '') {
+        if (text) {
+            console.log(`========================================`);
+            console.log(PREFIX, text);
+            console.log(`========================================`);
+        } else {
+            console.log(`========================================`);
+        }
+    },
+
+    workflow(steps) {
+        console.log('');
+        console.log('Workflow:');
+        steps.forEach((step, index) => {
+            console.log(`  ${index + 1}. ${step}`);
+        });
+        console.log('');
+    }
+};

package/lib/paths.js

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import {
+    TEMP_SESSION_DIR_PREFIX,
+    TEMP_SUBDIR_NAME,
+    PID_FILE_NAME,
+    RECORDER_FILE_NAME,
+    LOCAL_BACKUP_DIR,
+    BACKUP_EXT
+} from './constants.js';
+
+let _tempSessionDirPath = null;
+
+function getProjectHash() {
+    return crypto.createHash('md5').update(process.cwd()).digest('hex');
+}
+
+export function getTempSessionDirPath() {
+    if (_tempSessionDirPath) {
+        return _tempSessionDirPath;
+    }
+    _tempSessionDirPath = path.join(os.tmpdir(), TEMP_SESSION_DIR_PREFIX + getProjectHash());
+    return _tempSessionDirPath;
+}
+
+export function getRecorderPath() {
+    return path.join(getTempSessionDirPath(), TEMP_SUBDIR_NAME, RECORDER_FILE_NAME);
+}
+
+export function getPidFilePath() {
+    return path.join(getTempSessionDirPath(), PID_FILE_NAME);
+}
+
+export function getRecorderDir() {
+    return path.join(getTempSessionDirPath(), TEMP_SUBDIR_NAME);
+}
+
+export function ensureTempSessionDir() {
+    const dirPath = getTempSessionDirPath();
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+    const recorderDirPath = getRecorderDir();
+    if (!fs.existsSync(recorderDirPath)) {
+        fs.mkdirSync(recorderDirPath, { recursive: true });
+    }
+}
+
+// Gets the path for the primary backup in the OS temp directory
+export function getPrimaryBackupPath(filePath) {
+    const relativePath = path.relative(process.cwd(), filePath);
+    const backupPath = path.join(getTempSessionDirPath(), 'backup', relativePath) + BACKUP_EXT;
+    // Ensure the subdirectory structure exists
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    return backupPath;
+}
+
+// Gets the path for the fallback backup in the project's root directory
+export function getLocalBackupPath(filePath) {
+    const relativePath = path.relative(process.cwd(), filePath);
+    const backupPath = path.join(process.cwd(), LOCAL_BACKUP_DIR, relativePath) + BACKUP_EXT;
+    // Ensure the subdirectory structure exists
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    return backupPath;
+}

package/lib/recorder.js

@@ -0,0 +1,38 @@
+import SuperJSON from 'superjson';
+
+function getPort() {
+    if (typeof process !== 'undefined' && process.env.IOSNAP_DAEMON_PORT) {
+        return parseInt(process.env.IOSNAP_DAEMON_PORT, 10);
+    }
+    if (typeof window !== 'undefined') {
+        return window.IOSNAP_DAEMON_PORT || 9444;
+    }
+    return 9444;
+}
+
+export function record(fn, fnName) {
+    return new Proxy(fn, {
+        async apply(target, thisArg, args) {
+            const result = await Reflect.apply(target, thisArg, args);
+
+            const snapshot = {
+                fnName,
+                args,
+                result,
+                at: new Date().toISOString()
+            };
+
+            const port = getPort();
+
+            fetch(`http://localhost:${port}/telemetry`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: SuperJSON.stringify(snapshot)
+            }).catch(() => {
+                console.warn('[io-snapshot] Daemon not running. Run io-snapshot daemon first.');
+            });
+
+            return result;
+        }
+    });
+}

package/lib/transformer.js

@@ -0,0 +1,363 @@
+import { Project } from 'ts-morph';
+import * as babelParser from '@babel/parser';
+import * as babelTraverse from '@babel/traverse';
+import * as babelTypes from '@babel/types';
+import * as babelGenerator from '@babel/generator';
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import { BACKUP_EXT, SNAPSHOT_FILE, RECORDER_FILE_NAME, TEMP_SUBDIR_NAME, LOCAL_BACKUP_DIR } from './constants.js';
+import { getRecorderPath, getRecorderDir, getTempSessionDirPath, getPrimaryBackupPath, getLocalBackupPath } from './paths.js';
+import { log } from './logger.js';
+
+const parse = babelParser.parse;
+const traverse = babelTraverse.default?.default || babelTraverse.default;
+const t = babelTypes;
+const generate = babelGenerator.default?.default || babelGenerator.default || babelGenerator;
+
+const RECORDER_CODE = `export function _snap_record(fn, fnName) {
+    return new Proxy(fn, {
+        async apply(target, thisArg, args) {
+            const result = Reflect.apply(target, thisArg, args);
+            const port = typeof process !== 'undefined' && process.env.IOSNAP_DAEMON_PORT 
+                ? parseInt(process.env.IOSNAP_DAEMON_PORT, 10)
+                : typeof window !== 'undefined' ? (window.IOSNAP_DAEMON_PORT || 9444) : 9444;
+            
+            const snapshot = {
+                fnName,
+                args: args,
+                result: result,
+                at: new Date().toISOString()
+            };
+            
+            fetch('http://localhost:' + port + '/telemetry', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(snapshot)
+            }).catch(() => {});
+            
+            return result;
+        }
+    });
+}
+`;
+
+function ensureRecorderFile() {
+    const recorderPath = getRecorderPath();
+    const dirPath = getRecorderDir();
+
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+
+    if (!fs.existsSync(recorderPath)) {
+        fs.writeFileSync(recorderPath, RECORDER_CODE);
+        log.success(`Created ${path.join(TEMP_SUBDIR_NAME, RECORDER_FILE_NAME)} in temp directory.`);
+    }
+}
+
+function getProject() {
+    return new Project({
+        useInMemoryFileSystem: false,
+    });
+}
+
+function injectTSFile(filePath) {
+    const project = getProject();
+    const sourceFile = project.addSourceFileAtPath(filePath);
+
+    log.info('Injecting recorder import');
+
+    // Calculate relative path from the source file to the recorder file in the temp directory
+    const relativeRecorderPath = path.relative(path.dirname(filePath), getRecorderPath().replace(/\.js$/, ''));
+
+    const imports = sourceFile.getImportDeclarations();
+    const hasRecorderImport = imports.some(
+        imp => imp.getModuleSpecifierValue?.().includes(relativeRecorderPath)
+    );
+
+    if (!hasRecorderImport) {
+        sourceFile.addImportDeclaration({
+            moduleSpecifier: `./${relativeRecorderPath}`, // Use relative path for import
+            namedImports: ['_snap_record']
+        });
+    }
+
+    const exports = sourceFile.getExportedDeclarations();
+    log.info(`Found ${exports.size} exported declarations`);
+
+    exports.forEach((declarations, name) => {
+        log.info(`Processing export: ${name}`);
+        declarations.forEach(decl => {
+            const kind = decl.getKindName();
+            log.info(`  Kind: ${kind}`);
+
+            if (kind === 'FunctionDeclaration') {
+                const originalName = decl.getName();
+                log.info(`  Renaming function: ${originalName} -> _snap_${originalName}`);
+                decl.rename(`_snap_${originalName}`);
+                decl.setIsExported(false);
+
+                sourceFile.addVariableStatement({
+                    isExported: true,
+                    declarationKind: 'const',
+                    declarations: [{
+                        name: originalName,
+                        initializer: `_snap_record(_snap_${originalName}, '${originalName}')`
+                    }]
+                });
+                log.info(`  Added wrapper for: ${originalName}`);
+            }
+
+            if (kind === 'ArrowFunction' || kind === 'FunctionExpression') {
+                const variableStmt = decl.getFirstAncestor(a => a.getKindName() === 'VariableStatement');
+                if (variableStmt) {
+                    const declarations = variableStmt.getDeclarations();
+
+                    declarations.forEach(varDecl2 => {
+                        const name = varDecl2.getName();
+                        const init = varDecl2.getInitializer();
+                        if (init && (init.getKindName() === 'ArrowFunction' || init.getKindName() === 'FunctionExpression')) {
+                            const originalName = `_snap_${name}`;
+                            log.info(`  Wrapping arrow/function: ${name}`);
+                            init.replaceWithText(`_snap_record(${originalName}, '${name}')`);
+                            varDecl2.setName(originalName);
+                        }
+                    });
+                }
+            }
+        });
+    });
+
+    sourceFile.saveSync();
+    log.info(`Saved changes to ${filePath}`);
+}
+
+function injectJSFile(filePath) {
+    const code = fs.readFileSync(filePath, 'utf8');
+
+    log.info('Injecting recorder import');
+
+    let ast;
+    try {
+        ast = parse(code, {
+            sourceType: 'module',
+            plugins: ['jsx']
+        });
+    } catch (error) {
+        log.error(`Parser error: ${error.message}`);
+        return;
+    }
+
+    // Calculate relative path from the source file to the recorder file in the temp directory
+    const relativeRecorderPath = path.relative(path.dirname(filePath), getRecorderPath().replace(/\.js$/, ''));
+
+    // Check if already has recorder import
+    const hasRecorderImport = ast.program.body.some(
+        node => t.isImportDeclaration(node) &&
+            node.source.value.includes(relativeRecorderPath)
+    );
+
+    // Add import if not present
+    if (!hasRecorderImport) {
+        const importDecl = t.importDeclaration(
+            [t.importSpecifier(t.identifier('_snap_record'), t.identifier('_snap_record'))],
+            t.stringLiteral(`./${relativeRecorderPath}`) // Use relative path for import
+        );
+        ast.program.body.unshift(importDecl);
+    }
+
+    const wrapperStatements = [];
+    const exportsToRemove = [];
+
+    traverse(ast, {
+        ExportNamedDeclaration(path) {
+            const decl = path.node.declaration;
+
+            if (t.isFunctionDeclaration(decl)) {
+                const name = decl.id.name;
+                const newName = `_snap_${name}`;
+                log.info(`Wrapping function: ${name} -> ${newName}`);
+                decl.id.name = newName;
+
+                wrapperStatements.push(t.exportNamedDeclaration(t.variableDeclaration('const', [
+                    t.variableDeclarator(
+                        t.identifier(name),
+                        t.callExpression(t.identifier('_snap_record'), [
+                            t.identifier(newName),
+                            t.stringLiteral(name)
+                        ])
+                    )
+                ])));
+
+                exportsToRemove.push(path);
+            }
+
+            if (t.isVariableDeclaration(decl)) {
+                decl.declarations.forEach(varDecl => {
+                    if (t.isIdentifier(varDecl.id) &&
+                        (t.isArrowFunctionExpression(varDecl.init) ||
+                            t.isFunctionExpression(varDecl.init))) {
+                        const name = varDecl.id.name;
+                        const newName = `_snap_${name}`;
+                        log.info(`Wrapping variable: ${name} -> ${newName}`);
+                        varDecl.id.name = newName;
+
+                        wrapperStatements.push(t.exportNamedDeclaration(t.variableDeclaration('const', [
+                            t.variableDeclarator(
+                                t.identifier(name),
+                                t.callExpression(t.identifier('_snap_record'), [
+                                    t.identifier(newName),
+                                    t.stringLiteral(name)
+                                ])
+                            )
+                        ])));
+
+                        exportsToRemove.push(path);
+                    }
+                });
+            }
+        }
+    });
+
+    if (wrapperStatements.length === 0) {
+        log.warn('No exported functions found to wrap');
+        return;
+    }
+
+    for (const expPath of exportsToRemove) {
+        const decl = expPath.node.declaration;
+        expPath.replaceWith(decl);
+    }
+
+    for (const stmt of wrapperStatements) {
+        ast.program.body.push(stmt);
+    }
+
+    const output = generate(ast, {}, code);
+    fs.writeFileSync(filePath, output.code);
+    log.info(`Saved changes to ${filePath}`);
+}
+
+function restoreFile(filePath) {
+    const primaryBackupPath = getPrimaryBackupPath(filePath);
+    const localBackupPath = getLocalBackupPath(filePath);
+
+    if (fs.existsSync(primaryBackupPath)) {
+        fs.copyFileSync(primaryBackupPath, filePath);
+    } else if (fs.existsSync(localBackupPath)) {
+        log.warn(`Primary backup not found. Restoring from local fallback: ${localBackupPath}`);
+        fs.copyFileSync(localBackupPath, filePath);
+    } else {
+        log.error(`No backup found for ${filePath}. File cannot be restored.`);
+        return false; // Indicate failure
+    }
+    return true; // Indicate success
+}
+
+export async function injectRecorder(targetPattern, force = false) {
+    ensureRecorderFile();
+
+    const defaultPattern = '**/*.{ts,tsx,js,jsx}';
+    const pattern = targetPattern || defaultPattern;
+
+    const files = await glob(pattern, {
+        ignore: ['node_modules/**', '**/node_modules/**', `${LOCAL_BACKUP_DIR}/**`]
+    });
+
+    if (files.length === 0) {
+        log.warn(`No files found matching: ${pattern}`);
+        return;
+    }
+
+    const tsFiles = files.filter(f => (f.endsWith('.ts') || f.endsWith('.tsx')) && !f.includes(BACKUP_EXT));
+    const jsFiles = files.filter(f => (f.endsWith('.js') || f.endsWith('.jsx')) && !f.includes(BACKUP_EXT));
+
+    log.info(`Found ${tsFiles.length} TypeScript and ${jsFiles.length} JavaScript files to inject.`);
+
+    for (const file of [...tsFiles, ...jsFiles]) {
+        const primaryBackupPath = getPrimaryBackupPath(file);
+
+        if (fs.existsSync(primaryBackupPath) && !force) {
+            log.warn(`Skipping ${file} - already injected (backup exists). Use --force to re-inject.`);
+            continue;
+        }
+
+        if (fs.existsSync(primaryBackupPath) && force) {
+            log.info(`Re-injecting ${file}`);
+            // Restore from primary to ensure we are injecting a clean file
+            fs.copyFileSync(primaryBackupPath, file);
+        } else {
+            log.info(`Injecting ${file}`);
+        }
+
+        // Create both backups
+        const localBackupPath = getLocalBackupPath(file);
+        fs.copyFileSync(file, primaryBackupPath);
+        fs.copyFileSync(file, localBackupPath);
+
+        try {
+            if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+                injectTSFile(file);
+            } else {
+                injectJSFile(file);
+            }
+            log.success(`Injected recorder into ${file}`);
+        } catch (error) {
+            log.error(`Failed to inject ${file}: ${error.message}`);
+            // If injection fails, try to restore from one of the backups
+            restoreFile(file);
+        }
+    }
+}
+
+export async function restore(targetPattern, keepSnapshots = false) {
+    let filesToRestore = [];
+
+    if (targetPattern) {
+        const files = await glob(targetPattern);
+        filesToRestore = files.filter(f => !f.includes(BACKUP_EXT));
+    } else {
+        // Search for all backup files in the local backup dir to determine what to restore
+        const backupDir = path.join(process.cwd(), LOCAL_BACKUP_DIR);
+        if (fs.existsSync(backupDir)) {
+            const bakFiles = await glob(`${backupDir}/**/*${BACKUP_EXT}`);
+            filesToRestore = bakFiles.map(f => {
+                const relativePath = path.relative(backupDir, f);
+                return relativePath.replace(BACKUP_EXT, '');
+            });
+        }
+    }
+
+    if (filesToRestore.length === 0) {
+        log.warn('No files to restore.');
+    }
+
+    for (const file of filesToRestore) {
+        if (restoreFile(file)) {
+            log.success(`Restored ${file}`);
+        }
+    }
+
+    // --- Final Cleanup ---
+
+    const snapshotPath = path.resolve(process.cwd(), SNAPSHOT_FILE);
+    if (!keepSnapshots && fs.existsSync(snapshotPath)) {
+        fs.unlinkSync(snapshotPath);
+        log.success(`Removed ${SNAPSHOT_FILE}`);
+    }
+
+    // Remove the entire temp session directory, which includes primary backups and PID file
+    const tempSessionDirPath = getTempSessionDirPath();
+    if (fs.existsSync(tempSessionDirPath)) {
+        fs.rmSync(tempSessionDirPath, { recursive: true, force: true });
+        log.success(`Removed temp session directory: ${tempSessionDirPath}`);
+    }
+
+    // Remove the local backup directory from the project root
+    const localBackupDirPath = path.join(process.cwd(), LOCAL_BACKUP_DIR);
+    if (fs.existsSync(localBackupDirPath)) {
+        fs.rmSync(localBackupDirPath, { recursive: true, force: true });
+        log.success(`Removed local backup directory: ${LOCAL_BACKUP_DIR}`);
+    }
+}

package/lib/verifier.js

@@ -0,0 +1,166 @@
+import SuperJSON from 'superjson';
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import pkg from 'deep-diff';
+const { diff } = pkg;
+import { glob } from 'glob';
+import { SNAPSHOT_FILE } from './constants.js';
+import { loadConfig } from './config.js';
+import { log } from './logger.js';
+
+export async function verify(newFn, fnName) {
+    const config = loadConfig();
+    const port = config.port || 9444;
+
+    if (!fs.existsSync(path.resolve(process.cwd(), SNAPSHOT_FILE))) {
+        log.error(`No snapshots found! Run 'io-snapshot record' first.`);
+        return { passed: false, error: 'no_snapshots' };
+    }
+
+    const fileContent = fs.readFileSync(path.resolve(process.cwd(), SNAPSHOT_FILE), 'utf8');
+    const snapshots = fileContent.split('\n')
+        .filter(line => line.trim())
+        .map(line => {
+            try {
+                const parsed = SuperJSON.parse(line);
+                if (parsed?.fnName) return parsed;
+            } catch (error) {
+                log.warn(`Failed to parse snapshot line: ${error.message}`);
+            }
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed?.fnName) return parsed;
+            } catch (error) {
+                log.warn(`Failed to parse snapshot line as JSON: ${error.message}`);
+            }
+            return null;
+        })
+        .filter(s => s?.fnName === fnName);
+
+    if (snapshots.length === 0) {
+        log.info(`No snapshots found for function '${fnName}'.`);
+        return { passed: true, skipped: true };
+    }
+
+    let allPassed = true;
+    let failedCount = 0;
+
+    for (const snap of snapshots) {
+        const newResult = await newFn(...snap.args);
+        const changes = diff(snap.result, newResult);
+
+        if (changes) {
+            log.error(`Drift detected in ${fnName}!`);
+            console.dir(changes, { depth: null });
+            allPassed = false;
+            failedCount++;
+        } else {
+            log.success(`${fnName} passed semantic check.`);
+        }
+    }
+
+    if (allPassed && snapshots.length > 0) {
+        log.success(`All ${snapshots.length} snapshots passed for ${fnName}.`);
+    }
+
+    return { passed: allPassed, failed: failedCount, total: snapshots.length };
+}
+
+export async function verifyDir(targetPattern) {
+    if (!fs.existsSync(path.resolve(process.cwd(), SNAPSHOT_FILE))) {
+        log.error(`No snapshots found! Run 'io-snapshot record' first.`);
+        process.exit(1);
+    }
+
+    const fileContent = fs.readFileSync(path.resolve(process.cwd(), SNAPSHOT_FILE), 'utf8');
+    const allSnapshots = fileContent.split('\n')
+        .filter(line => line.trim())
+        .map(line => {
+            try {
+                const parsed = SuperJSON.parse(line);
+                if (parsed?.fnName) return parsed;
+            } catch (error) {
+                log.warn(`Failed to parse snapshot line: ${error.message}`);
+            }
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed?.fnName) return parsed;
+            } catch (error) {
+                log.warn(`Failed to parse snapshot line as JSON: ${error.message}`);
+            }
+            return null;
+        })
+        .filter(s => s?.fnName);
+
+    const fnNames = [...new Set(allSnapshots.map(s => s.fnName))];
+
+    if (fnNames.length === 0) {
+        log.warn('No snapshots to verify.');
+        return;
+    }
+
+    let allFiles = [];
+
+    if (targetPattern) {
+        const files = await glob(targetPattern);
+        const tsFiles = files.filter(f => (f.endsWith('.ts') || f.endsWith('.tsx')) && !f.includes('.snap.bak'));
+        const jsFiles = files.filter(f => (f.endsWith('.js') || f.endsWith('.jsx')) && !f.includes('.snap.bak'));
+        allFiles = [...tsFiles, ...jsFiles];
+    } else {
+        const allSourceFiles = await glob('**/*.{ts,tsx,js,jsx}', {
+            ignore: ['node_modules/**', '**/node_modules/**']
+        });
+        allFiles = allSourceFiles.filter(f => !f.includes('.snap.bak'));
+    }
+
+    if (allFiles.length === 0) {
+        log.warn('No source files found.');
+        return;
+    }
+
+    log.info(`Verifying ${fnNames.length} functions against ${allSnapshots.length} snapshots...`);
+
+    let totalPassed = true;
+
+    for (const fnName of fnNames) {
+        let found = false;
+
+        for (const file of allFiles) {
+            try {
+                const absolutePath = path.resolve(process.cwd(), file);
+                const fileUrl = pathToFileURL(absolutePath).href;
+                const mod = await import(fileUrl);
+                const fn = mod[fnName];
+
+                if (!fn) {
+                    continue;
+                }
+
+                found = true;
+                log.info(`Checking function '${fnName}' in ${file}`);
+                const result = await verify(fn, fnName);
+                if (result && !result.passed) {
+                    totalPassed = false;
+                }
+                break;
+            } catch (error) {
+                log.warn(`Could not load function from ${file}: ${error.message}`);
+            }
+        }
+
+        if (!found) {
+            log.warn(`Function '${fnName}' not found in any source file.`);
+        }
+    }
+
+    if (totalPassed) {
+        log.divider('SUCCESS');
+        log.success('All verifications passed!');
+        process.exit(0);
+    } else {
+        log.divider('FAILURE');
+        log.error('Some verifications failed.');
+        process.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@kendroger/io-snapshot",
+  "version": "1.0.0",
+  "description": "Capture and compare function behavior snapshots for zero-regression refactoring.",
+  "keywords": [
+    "refactor",
+    "testing",
+    "semantic",
+    "automation",
+    "ai",
+    "diff",
+    "test"
+  ],
+  "homepage": "https://github.com/kenDRoger/io-snapshot#readme",
+  "bugs": {
+    "url": "https://github.com/kenDRoger/io-snapshot/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kenDRoger/io-snapshot.git"
+  },
+  "license": "MIT",
+  "author": "kendroger",
+  "type": "module",
+  "exports": {
+    ".": "./lib/recorder.js",
+    "./recorder": "./lib/recorder.js",
+    "./verifier": "./lib/verifier.js",
+    "./transformer": "./lib/transformer.js",
+    "./daemon": "./lib/daemon.js",
+    "./constants": "./lib/constants.js",
+    "./config": "./lib/config.js",
+    "./logger": "./lib/logger.js"
+  },
+  "main": "./lib/recorder.js",
+  "bin": {
+    "io-snapshot": "bin/cli.js"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "scripts": {
+    "test": "vitest"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "deep-diff": "^1.0.2",
+    "glob": "^10.3.10",
+    "superjson": "^2.2.1"
+  },
+  "devDependencies": {
+    "@babel/generator": "^7.23.0",
+    "@babel/parser": "^7.23.0",
+    "@babel/traverse": "^7.23.0",
+    "@babel/types": "^7.23.0",
+    "ts-morph": "^21.0.0"
+  }
+}