@kendroger/io-snapshot 1.1.0

package/.snapdiffrc.json

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

package/README.md

@@ -0,0 +1,124 @@
+# 📸 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/@kendroger/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 primary backups 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-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-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,251 @@
+#!/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();
+    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 = opts.timeout || config.timeout || 30;
+
+        log.divider('IMPORTANT');
+        log.info('Run this command FIRST,');
+        log.info('         THEN start your app!');
+        log.divider();
+
+        log.workflow([
+            'io-snapshot record  → Inject recorder + start background daemon',
+            'npm run dev         → Start your app (daemon MUST be running)',
+            'Interact with app   → Use your app to capture real-world data',
+            'io-snapshot stop    → Stop recording and restore your original code',
+            'Modify your code    → Perform your refactoring or changes',
+            'io-snapshot test    → Verify new code against captured snapshots'
+        ]);
+
+        const snapshotPath = path.resolve(process.cwd(), SNAPSHOT_FILE);
+        fs.writeFileSync(snapshotPath, '');
+        log.info('Cleared previous snapshot file for a fresh session.');
+
+        log.info('Checking for existing 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 {
+                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 active.');
+            log.info(`Snapshots will be saved to: ${snapshotPath}`);
+            log.divider();
+            log.success('NOW START YOUR APP (e.g., npm run dev)');
+            log.info('Interact with your app to capture snapshots.');
+            log.info('Run "io-snapshot stop" when done to 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')
+    .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}.`);
+        }
+
+        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 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: ${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) || !Number.isInteger(portNum) || portNum < 1 || portNum > 65535) {
+        throw new Error(`Invalid port: ${port}. Must be an integer between 1 and 65535.`);
+    }
+    return portNum;
+}
+
+export function validateTimeout(timeout) {
+    const timeoutNum = parseInt(timeout, 10);
+    if (isNaN(timeoutNum) || !Number.isInteger(timeoutNum) || timeoutNum < 1) {
+        throw new Error(`Invalid timeout: ${timeout}. Must be a positive integer.`);
+    }
+    return timeoutNum;
+}
+
+export function validateFilePattern(pattern) {
+    if (!pattern || typeof pattern !== 'string' || pattern.trim() === '') {
+        throw new Error('File pattern must be a non-empty string.');
+    }
+    return pattern.trim();
+}

package/lib/constants.js

@@ -0,0 +1,10 @@
+export const DEFAULT_PORT = 9444;
+export const DEFAULT_TIMEOUT = 30;
+export const SNAPSHOT_FILE = '.snaps.jsonl';
+export const CONFIG_FILE = '.iosnapshotrc.json';
+export const BACKUP_EXT = '.snap.bak';
+
+// Path-related constants
+export const TEMP_SESSION_DIR_PREFIX = 'io-snapshot-session-';
+export const PID_FILE_NAME = 'io-snapshot.pid';
+export const LOCAL_BACKUP_DIR = '.io-snapshot-backups';

package/lib/daemon.js

@@ -0,0 +1,167 @@
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+import { DEFAULT_PORT, DEFAULT_TIMEOUT, SNAPSHOT_FILE } from './constants.js';
+import { loadConfig } from './config.js';
+import { log } from './logger.js';
+import { getPidFilePath, ensureTempSessionDir } from './paths.js';
+
+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) {
+    ensureTempSessionDir();
+    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();
+            log.success('Recording started.');
+            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, () => {
+        log.info(`Daemon running on http://localhost:${port}`);
+        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.SNAP_DAEMON_CORS || config.cors?.origin || '*';
+    startDaemon(actualPort, actualTimeout, { origin: corsEnv });
+}
+
+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,17 @@
+const PREFIX = '[io-snapshot]';
+
+export const log = {
+    info: (msg) => console.log(`${PREFIX} ${msg}`),
+    success: (msg) => console.log(`\x1b[32m${PREFIX} SUCCESS: ${msg}\x1b[0m`),
+    warn: (msg) => console.warn(`\x1b[33m${PREFIX} WARNING: ${msg}\x1b[0m`),
+    error: (msg) => console.error(`\x1b[31m${PREFIX} ERROR: ${msg}\x1b[0m`),
+    step: (num, msg) => console.log(`\x1b[34m${PREFIX} [Step ${num}] ${msg}\x1b[0m`),
+    divider: (label = '') => {
+        const line = '━'.repeat(20);
+        console.log(`\x1b[90m${line}${label ? ` ${label} ` : ''}${line}\x1b[0m`);
+    },
+    workflow: (steps) => {
+        console.log(`\x1b[36m${PREFIX} Workflow:\x1b[0m`);
+        steps.forEach((step, i) => console.log(`  ${i + 1}. ${step}`));
+    }
+};

package/lib/paths.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import {
+    TEMP_SESSION_DIR_PREFIX,
+    PID_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 ensureTempSessionDir() {
+    const dirPath = getTempSessionDirPath();
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+
+export function getPidFilePath() {
+    return path.join(getTempSessionDirPath(), PID_FILE_NAME);
+}
+
+// Gets the path for the primary backup in the OS temp directory
+export function getPrimaryBackupPath(filePath) {
+    const absoluteFilePath = path.resolve(process.cwd(), filePath);
+    const relativePath = path.relative(process.cwd(), absoluteFilePath);
+    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 absoluteFilePath = path.resolve(process.cwd(), filePath);
+    const relativePath = path.relative(process.cwd(), absoluteFilePath);
+    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-inline.js

@@ -0,0 +1,42 @@
+export function getInlineRecorderCode() {
+    const port = process.env.IOSNAP_DAEMON_PORT || 9444;
+
+    return `
+(function() {
+    var port = ${port};
+    var _snap_SuperJSON = null;
+    function _snap_getSuperJSON() {
+        if (_snap_SuperJSON) return _snap_SuperJSON;
+        try {
+        _snap_SuperJSON = { stringify: JSON.stringify, parse: JSON.parse };
+        return _snap_SuperJSON;
+        } catch (e) {
+        return { stringify: JSON.stringify, parse: JSON.parse };
+        }
+    }
+    function _snap_record(fn, fnName) {
+        return new Proxy(fn, {
+        async apply(target, thisArg, args) {
+            var result = Reflect.apply(target, thisArg, args);
+            var snapshot = {
+            fnName: fnName,
+            args: args,
+            result: result,
+            at: new Date().toISOString()
+            };
+            var SJ = _snap_getSuperJSON();
+            fetch('http://localhost:' + port + '/telemetry', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: SJ.stringify(snapshot)
+            }).catch(function(err) { 
+                    console.warn('[io-snapshot] Telemetry failed:', err.message); 
+                });
+            return result;
+        }
+        });
+    }
+    window._snap_record = _snap_record;
+})();
+`.trim();
+}

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((error) => {
+                console.warn(`[io-snapshot] Failed to send telemetry: ${error.message}`);
+            });
+
+            return result;
+        }
+    });
+}

package/lib/transformer.js

@@ -0,0 +1,348 @@
+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 'tinyglobby';
+import { BACKUP_EXT, SNAPSHOT_FILE, LOCAL_BACKUP_DIR } from './constants.js';
+import { getTempSessionDirPath, getPrimaryBackupPath, getLocalBackupPath } from './paths.js';
+import { getInlineRecorderCode } from './recorder-inline.js';
+import { log } from './logger.js';
+
+const { parse } = babelParser;
+const traverse = babelTraverse.default?.default || babelTraverse.default;
+const t = babelTypes;
+const generate = babelGenerator.default?.default || babelGenerator.default || babelGenerator;
+
+function getProject() {
+    return new Project({
+        useInMemoryFileSystem: false,
+    });
+}
+
+function injectTSFile(filePath) {
+    const project = getProject();
+    const sourceFile = project.addSourceFileAtPath(filePath);
+    let modified = false;
+
+    log.info(`Injecting recorder into ${filePath}`);
+
+    const hasRecorder = sourceFile.getText().includes('window._snap_record') || sourceFile.getText().includes('globalThis._snap_record');
+
+    if (!hasRecorder) {
+        const inlineCode = getInlineRecorderCode();
+        sourceFile.insertText(0, inlineCode);
+        modified = true;
+    }
+
+    const exports = sourceFile.getExportedDeclarations();
+
+    if (exports.size === 0 && !modified) {
+        return false;
+    }
+
+    let functionsWrapped = false;
+    exports.forEach((declarations, name) => {
+        declarations.forEach(decl => {
+            const kind = decl.getKindName();
+
+            if (kind === 'FunctionDeclaration') {
+                const originalName = decl.getName();
+                decl.rename(`_snap_${originalName}`);
+                decl.setIsExported(false);
+
+                sourceFile.addVariableStatement({
+                    isExported: true,
+                    declarationKind: 'const',
+                    declarations: [{
+                        name: originalName,
+                        initializer: `_snap_record(_snap_${originalName}, '${originalName}')`
+                    }]
+                });
+                functionsWrapped = true;
+            }
+
+            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}`;
+                            init.replaceWithText(`_snap_record(${originalName}, '${name}')`);
+                            varDecl2.setName(originalName);
+                            functionsWrapped = true;
+                        }
+                    });
+                }
+            }
+        });
+    });
+
+    if (functionsWrapped) {
+        modified = true;
+    }
+
+    if (modified) {
+        sourceFile.saveSync();
+    }
+    
+    return modified;
+}
+
+function injectJSFile(filePath) {
+    const code = fs.readFileSync(filePath, 'utf8');
+
+    log.info(`Injecting recorder into ${filePath}`);
+
+    let ast;
+    try {
+        ast = parse(code, {
+            sourceType: 'module',
+            plugins: ['jsx']
+        });
+    } catch (error) {
+        log.error(`Parser error in ${filePath}: ${error.message}`);
+        return false;
+    }
+
+    let modified = false;
+
+    const hasRecorder = ast.program.body.some(
+        node => (
+            t.isExpressionStatement(node) &&
+            node.expression.type === 'CallExpression' &&
+            node.expression.callee?.type === 'FunctionExpression' &&
+            node.expression.callee.body?.body?.some?.(stmt =>
+                stmt.type === 'ExpressionStatement' &&
+                stmt.expression.type === 'AssignmentExpression' &&
+                stmt.expression.left.property?.name === '_snap_record'
+            )
+        )
+    );
+
+    if (!hasRecorder) {
+        const inlineCode = getInlineRecorderCode();
+        const recorderAst = parse(inlineCode, { sourceType: 'script' });
+        ast.program.body.unshift(...recorderAst.program.body);
+        modified = true;
+    }
+
+    const newNodes = [];
+    let functionsWrapped = false;
+
+    traverse(ast, {
+        FunctionDeclaration(path) {
+            if (path.node.id && path.node.id.name && !path.node.id.name.startsWith('_snap_')) {
+                const { name } = path.node.id;
+                const newName = `_snap_${name}`;
+                
+                const newFunction = t.functionDeclaration(
+                    t.identifier(newName),
+                    path.node.params,
+                    path.node.body,
+                    path.node.generator,
+                    path.node.async
+                );
+
+                const wrapper = t.variableDeclaration('const', [
+                    t.variableDeclarator(
+                        t.identifier(name),
+                        t.callExpression(t.identifier('_snap_record'), [
+                            t.identifier(newName),
+                            t.stringLiteral(name)
+                        ])
+                    )
+                ]);
+
+                if (path.parent.type === 'ExportNamedDeclaration' || path.parent.type === 'ExportDefaultDeclaration') {
+                    const exportParent = path.findParent(p => p.isExportDeclaration());
+                    if (exportParent) {
+                        exportParent.replaceWith(newFunction);
+                        path.skip();
+                        newNodes.push(t.exportNamedDeclaration(wrapper));
+                        functionsWrapped = true;
+                    }
+                } else {
+                    path.replaceWith(newFunction);
+                    path.skip();
+                    newNodes.push(wrapper);
+                    functionsWrapped = true;
+                }
+            }
+        },
+        VariableDeclaration(path) {
+            path.get('declarations').forEach(declaratorPath => {
+                const declarator = declaratorPath.node;
+                if (t.isIdentifier(declarator.id) && 
+                    !declarator.id.name.startsWith('_snap_') &&
+                    (t.isArrowFunctionExpression(declarator.init) || t.isFunctionExpression(declarator.init))) {
+                    
+                    const { name } = declarator.id;
+                    const newName = `_snap_${name}`;
+                    
+                    const originalFunction = declarator.init;
+                    
+                    const newDeclarator = t.variableDeclarator(t.identifier(newName), originalFunction);
+                    
+                    const wrapper = t.variableDeclaration('const', [
+                        t.variableDeclarator(
+                            t.identifier(name),
+                            t.callExpression(t.identifier('_snap_record'), [
+                                t.identifier(newName),
+                                t.stringLiteral(name)
+                            ])
+                        )
+                    ]);
+
+                    if (path.parent.type === 'ExportNamedDeclaration') {
+                        const exportParent = path.findParent(p => p.isExportDeclaration());
+                        if (exportParent) {
+                            exportParent.replaceWith(t.variableDeclaration(path.node.kind, [newDeclarator]));
+                            path.skip();
+                            newNodes.push(t.exportNamedDeclaration(wrapper));
+                            functionsWrapped = true;
+                        }
+                    } else {
+                        path.replaceWith(t.variableDeclaration(path.node.kind, [newDeclarator]));
+                        path.skip();
+                        newNodes.push(wrapper);
+                        functionsWrapped = true;
+                    }
+                }
+            });
+        }
+    });
+
+    if (functionsWrapped) {
+        modified = true;
+    }
+
+    if (!modified) {
+        return false;
+    }
+
+    ast.program.body.push(...newNodes);
+
+    const output = generate(ast, {}, code);
+    fs.writeFileSync(filePath, output.code);
+    return true;
+}
+
+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 for ${filePath}. Restoring from local fallback.`);
+        fs.copyFileSync(localBackupPath, filePath);
+    } else {
+        log.error(`No backup found for ${filePath}.`);
+        return false;
+    }
+    return true;
+}
+
+export async function injectRecorder(targetPattern, force = false) {
+    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 sourceFiles = files.filter(f => !f.endsWith(BACKUP_EXT));
+
+    log.info(`Processing ${sourceFiles.length} files...`);
+
+    for (const file of sourceFiles) {
+        const primaryBackupPath = getPrimaryBackupPath(file);
+
+        if (fs.existsSync(primaryBackupPath) && !force) {
+            log.warn(`Skipping ${file} - already injected. Use --force to re-inject.`);
+            continue;
+        }
+
+        if (fs.existsSync(primaryBackupPath) && force) {
+            fs.copyFileSync(primaryBackupPath, file);
+        }
+
+        const localBackupPath = getLocalBackupPath(file);
+        fs.copyFileSync(file, primaryBackupPath);
+        fs.copyFileSync(file, localBackupPath);
+
+        try {
+            let injected = false;
+            if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+                injectTSFile(file);
+                injected = true; // Assume true for TS files for now
+            } else {
+                injected = injectJSFile(file);
+            }
+
+            if (injected) {
+                log.success(`Injected into ${file}`);
+            } else {
+                log.info(`No functions to inject in ${file}, skipping.`);
+                // Restore the original file since no changes were made
+                restoreFile(file);
+            }
+        } catch (error) {
+            log.error(`Failed to inject ${file}: ${error.message}`);
+            restoreFile(file);
+        }
+    }
+}
+
+export async function restore(targetPattern, keepSnapshots = false) {
+    let filesToRestore = [];
+
+    if (targetPattern) {
+        const files = await glob(targetPattern);
+        filesToRestore = files.filter(f => !f.endsWith(BACKUP_EXT));
+    } else {
+        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.slice(0, -BACKUP_EXT.length);
+            });
+        }
+    }
+
+    for (const file of filesToRestore) {
+        if (restoreFile(file)) {
+            log.success(`Restored ${file}`);
+        }
+    }
+
+    const snapshotPath = path.resolve(process.cwd(), SNAPSHOT_FILE);
+    if (!keepSnapshots && fs.existsSync(snapshotPath)) {
+        fs.unlinkSync(snapshotPath);
+        log.success(`Removed ${SNAPSHOT_FILE}`);
+    }
+
+    const tempSessionDirPath = getTempSessionDirPath();
+    if (fs.existsSync(tempSessionDirPath)) {
+        fs.rmSync(tempSessionDirPath, { recursive: true, force: true });
+    }
+
+    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,165 @@
+import SuperJSON from 'superjson';
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import diff from 'microdiff';
+import { glob } from 'tinyglobby';
+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.length > 0) {
+            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,59 @@
+{
+  "name": "@kendroger/io-snapshot",
+  "version": "1.1.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": {
+    "@babel/generator": "^7.23.0",
+    "@babel/parser": "^7.23.0",
+    "@babel/traverse": "^7.23.0",
+    "@babel/types": "^7.23.0",
+    "commander": "^12.0.0",
+    "microdiff": "^1.5.0",
+    "superjson": "^2.2.1",
+    "tinyglobby": "^0.2.0",
+    "ts-morph": "^21.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}