state-surgeon 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,296 @@
+# 🔬 State Surgeon
+
+**Time-travel debugging platform for JavaScript applications**
+
+State Surgeon records every state mutation across your React, Redux, and Zustand applications, providing interactive forensic tools to investigate bugs.
+
+> "Deterministic state timeline reconstruction with surgical debugging capabilities"
+
+[![npm version](https://badge.fury.io/js/state-surgeon.svg)](https://www.npmjs.com/package/state-surgeon)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Features
+
+- 🎯 **Automatic State Capture** - Instruments React hooks, Redux stores, and Zustand without code changes
+- 🕰️ **Time Travel** - Scrub through your state history with a visual timeline
+- 🔍 **State Diff Viewer** - Side-by-side comparison of before/after states
+- 📊 **Mutation Inspector** - Detailed view of each state change with call stacks
+- 🔗 **Causal Chain Analysis** - Find the root cause of state corruption
+- 🧪 **Test Case Generation** - Generate test cases from bug timelines (coming soon)
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install state-surgeon
+```
+
+### 2. Start the Recorder Server
+
+```javascript
+import { createRecorderServer } from 'state-surgeon/recorder';
+
+const server = createRecorderServer({
+  port: 8080,
+  wsPort: 8081,
+  debug: true,
+});
+
+await server.start();
+console.log('State Surgeon Recorder running on http://localhost:8080');
+```
+
+### 3. Instrument Your App
+
+```javascript
+import React from 'react';
+import { StateSurgeonClient, instrumentReact } from 'state-surgeon/instrument';
+
+// Create client (connects to recorder)
+const client = new StateSurgeonClient({
+  serverUrl: 'ws://localhost:8081',
+  appId: 'my-app',
+  debug: true,
+});
+
+// Instrument React hooks
+instrumentReact(React);
+
+// Now all useState and useReducer calls are automatically tracked!
+```
+
+### 4. View the Dashboard
+
+Open `http://localhost:8080/_surgeon` to see your state mutations in real-time.
+
+## Usage
+
+### React Instrumentation
+
+```javascript
+import React from 'react';
+import { instrumentReact } from 'state-surgeon/instrument';
+
+// Instrument React (call once at app startup)
+const cleanup = instrumentReact(React);
+
+// Your components work normally
+function Counter() {
+  const [count, setCount] = React.useState(0); // ✅ Automatically tracked!
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+
+// To stop instrumentation
+cleanup();
+```
+
+### Redux Instrumentation
+
+```javascript
+import { createStore, applyMiddleware } from 'redux';
+import { createReduxMiddleware } from 'state-surgeon/instrument';
+
+const stateSurgeonMiddleware = createReduxMiddleware({
+  storeName: 'main',
+  ignoreActions: ['@@INIT'], // Optional: ignore certain actions
+});
+
+const store = createStore(
+  rootReducer,
+  applyMiddleware(stateSurgeonMiddleware)
+);
+```
+
+### Zustand Instrumentation
+
+```javascript
+import { create } from 'zustand';
+import { instrumentZustand } from 'state-surgeon/instrument';
+
+const useStore = create(
+  instrumentZustand(
+    (set) => ({
+      count: 0,
+      increment: () => set((state) => ({ count: state.count + 1 })),
+    }),
+    { storeName: 'counter' }
+  )
+);
+```
+
+### API Call Tracking
+
+```javascript
+import { instrumentFetch, instrumentXHR } from 'state-surgeon/instrument';
+
+// Track all fetch calls
+const cleanupFetch = instrumentFetch({
+  captureResponseBody: true,
+  ignoreUrls: ['/health', '/metrics'],
+});
+
+// Track XMLHttpRequest
+const cleanupXHR = instrumentXHR();
+```
+
+## API Reference
+
+### Instrument Module
+
+#### `StateSurgeonClient`
+
+Main client for connecting to the recorder server.
+
+```typescript
+const client = new StateSurgeonClient({
+  serverUrl?: string;    // WebSocket URL (default: 'ws://localhost:8081')
+  appId?: string;        // Application identifier
+  sessionId?: string;    // Session ID (auto-generated if not provided)
+  autoConnect?: boolean; // Connect on creation (default: true)
+  batchSize?: number;    // Mutations to batch before sending (default: 50)
+  flushInterval?: number;// Flush interval in ms (default: 100)
+  debug?: boolean;       // Enable console logging
+});
+```
+
+#### `instrumentReact(React, options?)`
+
+Patches React's `useState` and `useReducer` to capture mutations.
+
+```typescript
+const cleanup = instrumentReact(React, {
+  client?: StateSurgeonClient; // Custom client instance
+  captureComponentName?: boolean; // Detect component from stack trace
+});
+```
+
+#### `createReduxMiddleware(options?)`
+
+Creates Redux middleware for capturing dispatched actions.
+
+```typescript
+const middleware = createReduxMiddleware({
+  client?: StateSurgeonClient;
+  storeName?: string;
+  ignoreActions?: string[]; // Action types to skip
+});
+```
+
+### Recorder Module
+
+#### `createRecorderServer(options?)`
+
+Creates the mutation recording server.
+
+```typescript
+const server = createRecorderServer({
+  port?: number;         // HTTP port (default: 8080)
+  wsPort?: number;       // WebSocket port (default: 8081)
+  cors?: boolean;        // Enable CORS (default: true)
+  debug?: boolean;       // Enable logging
+});
+
+await server.start();
+```
+
+### Dashboard Module
+
+#### `StateSurgeonDashboard`
+
+React component for the forensic debugging UI.
+
+```tsx
+import { StateSurgeonDashboard } from 'state-surgeon/dashboard';
+
+function App() {
+  return <StateSurgeonDashboard serverUrl="http://localhost:8080" />;
+}
+```
+
+## Advanced Usage
+
+### Finding State Corruption
+
+```javascript
+import { TimelineReconstructor } from 'state-surgeon/recorder';
+
+const reconstructor = new TimelineReconstructor(store);
+
+// Find exactly when a value became invalid
+const corruptedMutation = await reconstructor.findStateCorruption(
+  sessionId,
+  (state) => !isNaN(state.cart?.total) // Validation function
+);
+
+console.log('State became corrupted at:', corruptedMutation);
+```
+
+### Comparing Sessions
+
+```javascript
+const { divergencePoint, session1Only, session2Only } =
+  await reconstructor.compareSessions(workingSessionId, brokenSessionId);
+
+console.log('Sessions diverged at mutation index:', divergencePoint);
+```
+
+### Finding Mutations for a Path
+
+```javascript
+const mutations = await reconstructor.findMutationsForPath(
+  sessionId,
+  'cart.total' // State path
+);
+
+console.log('These mutations affected cart.total:', mutations);
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Your Application                          │
+├─────────────────────────────────────────────────────────────┤
+│  instrumentReact()  │  createReduxMiddleware()  │  etc.     │
+│           ↓                    ↓                             │
+│                  StateSurgeonClient                          │
+│                         ↓                                    │
+│              WebSocket Transport                             │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│                   Recorder Server                            │
+├─────────────────────────────────────────────────────────────┤
+│  WebSocket Handler  │  MutationStore  │  API Routes         │
+│                     │                 │                      │
+│                     ↓                 ↓                      │
+│              TimelineReconstructor                           │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│                     Dashboard UI                             │
+├─────────────────────────────────────────────────────────────┤
+│  TimelineScrubber  │  StateDiffViewer  │  MutationInspector │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run demo
+npm run demo
+```
+
+## License
+
+MIT © 2024