codesynapse 1.0.0

package/README.md

@@ -0,0 +1,270 @@
+# CodeSynapse
+
+> Real-time codebase visualization with a neural network-style 3D graph. Watch your code evolve as you or AI agents work on it.
+
+<div align="center">
+
+[![npm version](https://badge.fury.io/js/codesynapse.svg)](https://www.npmjs.com/package/codesynapse)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+## Features
+
+- 🌐 **3D Neural Network Visualization** - Files as neurons, dependencies as synapses
+- ⚡ **Real-time Updates** - Watch changes happen live as you code
+- 🔗 **Dependency Mapping** - Automatically parse and visualize import/require relationships
+- 📊 **Git Diff Integration** - Click any file to see code changes
+- 🎨 **Beautiful Effects** - Glow effects, pulse animations, and particle flows
+- 🚀 **High Performance** - Smooth 60fps visualization even with large codebases
+- 🎯 **AI Agent Friendly** - Perfect for watching AI agents work on your code
+
+## 🎬 Demo
+
+Watch your codebase come alive:
+
+1. Point CodeSynapse at any directory
+2. See all files appear as glowing nodes in 3D space
+3. Dependencies light up as connections between files
+4. When you edit a file, it pulses with cyan light
+5. Click any node to see the git diff in a side panel
+6. Watch the neural network grow as you add more code
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g codesynapse
+```
+
+### Local Installation
+
+```bash
+npm install --save-dev codesynapse
+```
+
+## Usage
+
+### Quick Start
+
+Navigate to your project directory and run:
+
+```bash
+codesynapse
+```
+
+This will:
+1. Start the visualization server on `http://localhost:3004`
+2. Automatically open your browser
+3. Begin watching your project directory
+4. If port 3004 is in use, it will automatically try the next available port
+
+### Command Line Options
+
+```bash
+codesynapse [options]
+
+Options:
+  --port <port>     Specify port (default: 3004)
+  --no-open         Don't automatically open browser
+```
+
+Examples:
+
+```bash
+# Run on a different port
+codesynapse --port 8080
+
+# Don't auto-open browser
+codesynapse --no-open
+```
+
+### Using the Visualization
+
+1. **Start Watching** - Click "Start Watching" to begin monitoring your project
+2. **Explore the Graph** - Drag to rotate, scroll to zoom, click nodes to view code
+3. **Watch Changes** - Edit files and see them light up in real-time:
+   - Green (0-5s) - Just changed, pulsing
+   - Amber (5-30s) - Recently active
+   - Yellow (30-60s) - Cooling down
+   - Blue/Purple/etc. - Stable (color by file type)
+4. **View Code** - Click any node to see syntax-highlighted code and git diffs
+5. **Toggle Theme** - Click the sun/moon icon for light/dark mode
+
+### Controls
+
+- **Mouse drag**: Rotate the camera
+- **Scroll**: Zoom in/out
+- **Click node**: View file details and git diff
+- **Hover node**: See file info tooltip
+
+## Architecture
+
+```
+code-synapse/
+├── server/              # Node.js + Express + Socket.io backend
+│   ├── FileWatcher.ts   # Real-time file monitoring (Chokidar)
+│   ├── DependencyParser.ts  # AST parsing (@babel/parser)
+│   ├── GitIntegration.ts    # Git diff tracking (simple-git)
+│   ├── GraphBuilder.ts      # Graph data structure
+│   └── index.ts            # WebSocket server
+│
+├── client/              # React + Three.js frontend
+│   ├── components/
+│   │   ├── Graph3D.tsx      # 3D visualization (react-force-graph-3d)
+│   │   ├── DiffPanel.tsx    # Git diff viewer
+│   │   ├── Controls.tsx     # UI controls
+│   │   └── Stats.tsx        # Live statistics
+│   └── hooks/
+│       └── useWebSocket.ts  # Socket.io client
+```
+
+### Tech Stack
+
+**Backend:**
+- Express - HTTP server
+- Socket.io - Real-time WebSocket communication
+- Chokidar - File system watching
+- @babel/parser - JavaScript/TypeScript AST parsing
+- simple-git - Git integration
+
+**Frontend:**
+- React 18 - UI framework
+- Three.js - 3D graphics
+- react-force-graph-3d - Force-directed graph layout
+- Socket.io-client - Real-time updates
+
+**Language:**
+- TypeScript throughout for type safety
+
+## Visualization Details
+
+### Node Colors
+
+Files are colored by type:
+- JavaScript (.js, .jsx, .mjs, .cjs) - Yellow
+- TypeScript (.ts, .tsx) - Blue
+- JSON (.json) - Green
+- Styles (.css, .scss, .sass, .less) - Purple
+- Markup (.html) - Red
+- Markdown (.md) - Green
+- Other files - Gray
+
+### Node Size
+
+Nodes scale based on:
+- Number of connections (imports/exports)
+- File size
+- Change frequency
+
+### Visual Effects
+
+- **Pulse animation**: Recently changed files glow cyan and pulse
+- **Particle flow**: Particles travel along dependency connections
+- **Glow aura**: All nodes have a subtle glow effect
+- **Connection highlighting**: Hover to see connected files
+
+## Use Cases
+
+### 1. Understanding Codebases
+Quickly visualize the structure and dependencies of unfamiliar projects.
+
+### 2. Watching AI Agents
+See exactly what files an AI agent is modifying in real-time.
+
+### 3. Refactoring
+Understand the impact of changes by seeing which files are connected.
+
+### 4. Code Reviews
+Visualize the scope of changes in a pull request.
+
+### 5. Teaching
+Help others understand project architecture visually.
+
+## Configuration
+
+Create a `.codesynapse.json` file in your project root:
+
+```json
+{
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/build/**"
+  ],
+  "colors": {
+    "javascript": "#f1e05a",
+    "typescript": "#2b7489",
+    "json": "#00d084"
+  }
+}
+```
+
+## Development
+
+### Project Structure
+
+```bash
+npm run dev           # Start both server and client
+npm run build         # Build for production
+npm start            # Run production build
+```
+
+### Server Development
+
+```bash
+cd server
+npm run dev          # Start with hot reload
+npm run build        # Compile TypeScript
+```
+
+### Client Development
+
+```bash
+cd client
+npm run dev          # Start React dev server
+npm run build        # Build for production
+```
+
+## Troubleshooting
+
+### "Not a git repository" message
+This is normal if the directory you're watching isn't a git repo. Git features will be disabled but file watching still works.
+
+### Large codebases slow
+Try adjusting physics settings or filtering file types in the configuration.
+
+### Connection issues
+Make sure both server (3001) and client (3000) ports are available.
+
+## Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - feel free to use this in your own projects!
+
+## Acknowledgments
+
+Built with:
+- [Chokidar](https://github.com/paulmillr/chokidar) - File watching
+- [react-force-graph](https://github.com/vasturiano/react-force-graph) - 3D visualization
+- [Babel](https://babeljs.io/) - AST parsing
+- [Socket.io](https://socket.io/) - Real-time communication
+
+## Future Ideas
+
+- Support for more languages (Python, Go, Rust, Java)
+- Time-travel mode to replay changes
+- Heatmap visualization for hot spots
+- Multi-project view
+- VR mode for immersive exploration
+- VS Code extension
+- Collaborative mode
+
+---
+
+Made for developers who love beautiful visualizations

package/bin/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+const cwd = process.cwd();
+
+// Get the package root directory
+const packageRoot = path.join(__dirname, '..');
+const serverPath = path.join(packageRoot, 'server', 'dist', 'index.js');
+
+// Check if server dist exists
+if (!fs.existsSync(serverPath)) {
+  console.error('Error: CodeSynapse server not built. Please run: npm install -g codesynapse');
+  process.exit(1);
+}
+
+// Parse command line arguments
+const port = args.includes('--port') ? args[args.indexOf('--port') + 1] : '3004';
+const openBrowser = !args.includes('--no-open');
+
+console.log(`
+╔══════════════════════════════════════════╗
+║                                          ║
+║           CodeSynapse v1.0.0             ║
+║   Real-time Codebase Visualization       ║
+║                                          ║
+╚══════════════════════════════════════════╝
+
+Starting server...
+Project: ${cwd}
+Port: ${port}
+URL: http://localhost:${port}
+`);
+
+// Set environment variables
+const env = {
+  ...process.env,
+  PORT: port,
+  NODE_ENV: 'production'
+};
+
+// Start the server
+const server = spawn('node', [serverPath], {
+  cwd: packageRoot,
+  env,
+  stdio: 'inherit'
+});
+
+// Open browser after a short delay
+if (openBrowser) {
+  setTimeout(() => {
+    const open = require('open');
+    open(`http://localhost:${port}`).catch(() => {
+      console.log('\nOpen your browser and navigate to:', `http://localhost:${port}`);
+    });
+  }, 2000);
+}
+
+// Handle cleanup
+process.on('SIGINT', () => {
+  console.log('\n\nShutting down CodeSynapse...');
+  server.kill();
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  server.kill();
+  process.exit(0);
+});
+
+server.on('exit', (code) => {
+  if (code !== 0 && code !== null) {
+    console.error(`Server exited with code ${code}`);
+    process.exit(code);
+  }
+});

package/client/build/asset-manifest.json

@@ -0,0 +1,14 @@
+{
+  "files": {
+    "main.css": "/static/css/main.23fcdbf2.css",
+    "main.js": "/static/js/main.5c90edac.js",
+    "static/media/ngraph.events.cjs": "/static/media/ngraph.events.d3dfed5ea2f996b98f21.cjs",
+    "index.html": "/index.html",
+    "main.23fcdbf2.css.map": "/static/css/main.23fcdbf2.css.map",
+    "main.5c90edac.js.map": "/static/js/main.5c90edac.js.map"
+  },
+  "entrypoints": [
+    "static/css/main.23fcdbf2.css",
+    "static/js/main.5c90edac.js"
+  ]
+}

package/client/build/index.html

@@ -0,0 +1 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#0a0e1a"/><meta name="description" content="CodeSynapse - Real-time codebase visualization tool"/><title>CodeSynapse - Neural Network Code Visualization</title><script defer="defer" src="/static/js/main.5c90edac.js"></script><link href="/static/css/main.23fcdbf2.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>

package/client/build/static/css/main.23fcdbf2.css

@@ -0,0 +1,2 @@
+*{box-sizing:border-box;padding:0}*,body{margin:0}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;background-color:#0a0e1a;color:#e0e0e0;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;overflow:hidden}code{font-family:Monaco,Consolas,Courier New,monospace}::-webkit-scrollbar{height:8px;width:8px}::-webkit-scrollbar-track{background:rgba(20,24,36,.5)}::-webkit-scrollbar-thumb{background:rgba(100,150,255,.5);border-radius:4px}::-webkit-scrollbar-thumb:hover{background:rgba(100,150,255,.7)}@keyframes slideIn{0%{transform:translateX(100%)}to{transform:translateX(0)}}button:hover:not(:disabled){box-shadow:0 4px 12px rgba(0,255,255,.3);transform:translateY(-2px)}button:active:not(:disabled){transform:translateY(0)}input:focus{border-color:#0ff!important;box-shadow:0 0 0 2px rgba(0,255,255,.2)}::selection{background-color:rgba(0,255,255,.3);color:#fff}
+/*# sourceMappingURL=main.23fcdbf2.css.map*/

package/client/build/static/css/main.23fcdbf2.css.map

@@ -0,0 +1 @@
+{"version":3,"file":"static/css/main.23fcdbf2.css","mappings":"AAAA,EAGE,qBAAsB,CADtB,SAEF,CAEA,OALE,QAeF,CAVA,KAKE,kCAAmC,CACnC,iCAAkC,CAClC,wBAAyB,CACzB,aAAc,CANd,mIAEY,CAKZ,eACF,CAEA,KACE,iDACF,CAGA,oBAEE,UAAW,CADX,SAEF,CAEA,0BACE,4BACF,CAEA,0BACE,+BAAoC,CACpC,iBACF,CAEA,gCACE,+BACF,CAGA,mBACE,GACE,0BACF,CACA,GACE,uBACF,CACF,CAGA,4BAEE,wCAA6C,CAD7C,0BAEF,CAEA,6BACE,uBACF,CAGA,YACE,2BAAgC,CAChC,uCACF,CAGA,YACE,mCAAwC,CACxC,UACF","sources":["index.css"],"sourcesContent":["* {\n  margin: 0;\n  padding: 0;\n  box-sizing: border-box;\n}\n\nbody {\n  margin: 0;\n  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',\n    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',\n    sans-serif;\n  -webkit-font-smoothing: antialiased;\n  -moz-osx-font-smoothing: grayscale;\n  background-color: #0a0e1a;\n  color: #e0e0e0;\n  overflow: hidden;\n}\n\ncode {\n  font-family: Monaco, Consolas, 'Courier New', monospace;\n}\n\n/* Custom scrollbar */\n::-webkit-scrollbar {\n  width: 8px;\n  height: 8px;\n}\n\n::-webkit-scrollbar-track {\n  background: rgba(20, 24, 36, 0.5);\n}\n\n::-webkit-scrollbar-thumb {\n  background: rgba(100, 150, 255, 0.5);\n  border-radius: 4px;\n}\n\n::-webkit-scrollbar-thumb:hover {\n  background: rgba(100, 150, 255, 0.7);\n}\n\n/* Animations */\n@keyframes slideIn {\n  from {\n    transform: translateX(100%);\n  }\n  to {\n    transform: translateX(0);\n  }\n}\n\n/* Button hover effects */\nbutton:hover:not(:disabled) {\n  transform: translateY(-2px);\n  box-shadow: 0 4px 12px rgba(0, 255, 255, 0.3);\n}\n\nbutton:active:not(:disabled) {\n  transform: translateY(0);\n}\n\n/* Input focus effects */\ninput:focus {\n  border-color: #00ffff !important;\n  box-shadow: 0 0 0 2px rgba(0, 255, 255, 0.2);\n}\n\n/* Selection */\n::selection {\n  background-color: rgba(0, 255, 255, 0.3);\n  color: #ffffff;\n}\n"],"names":[],"sourceRoot":""}