@rayburst/cli 0.1.0 → 0.1.8

package/README.md

@@ -1,258 +1,329 @@
 # Rayburst CLI
 
-A Module Federation host application that loads the Rayburst frontend application dynamically from different environments.
-
-## Overview
-
-The Rayburst CLI is an npm-installable package that serves as a Module Federation host. It dynamically loads the Rayburst application from:
-
-- **Development**: `http://localhost:3000` (local development)
-- **Staging**: `https://dev.rayburst.app` (staging environment)
-- **Production**: `https://www.rayburst.app` (production environment)
-
-The CLI runs on **port 3105** by default.
+A powerful CLI tool for analyzing and visualizing TypeScript/JavaScript project dependencies and architecture.
 
 ## Installation
 
-### Local Development Setup
+Install globally via npm:
 
-1. Install dependencies:
 ```bash
-cd cli
-npm install
+npm install -g @rayburst/cli
 ```
 
-2. Build the CLI:
-```bash
-npm run build
-```
+## Quick Start
 
-3. Link the CLI globally for testing:
 ```bash
-npm link
-```
+# Register your project
+rayburst register /path/to/your/project
 
-### Publishing to npm (Future)
+# Analyze the project
+rayburst analyze
 
-Once ready for production:
-```bash
-npm publish
+# Start the dashboard
+rayburst start
 ```
 
-Then users can install globally:
+Open your browser to `http://localhost:3105` to view the interactive dashboard.
+
+## Commands
+
+### `rayburst register [path]`
+
+Register a project for analysis.
+
 ```bash
-npm install -g rayburst-cli
+# Register current directory
+rayburst register
+
+# Register specific path
+rayburst register /path/to/project
+
+# Register with custom name
+rayburst register --name "My Project"
 ```
 
-## Usage
+**Options:**
+- `[path]` - Path to project directory (default: current directory)
+- `-n, --name <name>` - Custom project name
 
-### Starting the CLI
+### `rayburst list`
+
+List all registered projects.
 
 ```bash
-rayburst start
+rayburst list
 ```
 
-This will start the CLI server on port 3105 in development mode, loading the app from `localhost:3000`.
+Shows:
+- Project name
+- Path
+- Last analyzed timestamp
+- Number of branches
+
+### `rayburst analyze [path]`
 
-### Command Options
+Analyze a registered project and generate dependency graphs.
 
 ```bash
-rayburst start [options]
+# Analyze current directory
+rayburst analyze
 
-Options:
-  -p, --port <port>            Port to run the server on (default: 3105)
-  -e, --env <environment>      Environment: development|staging|production (default: development)
-  -h, --help                   Display help for command
+# Analyze specific project by path
+rayburst analyze /path/to/project
+
+# Analyze specific project by ID
+rayburst analyze abc-123
 ```
 
-### Examples
+**Options:**
+- `[path]` - Project path or ID (default: current directory)
 
-Start on custom port:
-```bash
-rayburst start --port 4000
-```
+**What it analyzes:**
+- Function and class relationships
+- Import/export dependencies
+- Git branches
+- File structure
+- Code architecture
 
-Start in staging mode:
-```bash
-rayburst start --env staging
-```
+### `rayburst start`
+
+Start the interactive dashboard server.
 
-Start in production mode:
 ```bash
-rayburst start --env production --port 8080
+# Start on default port (3105)
+rayburst start
+
+# Start on custom port
+rayburst start --port 4000
+
+# Start in production mode
+rayburst start --env production
 ```
 
-## Development Workflow
+**Options:**
+- `-p, --port <port>` - Server port (default: 3105)
+- `-e, --env <environment>` - Environment: development|staging|production (default: production)
 
-### 1. Build the Main App (Remote)
+### `rayburst unregister <id>`
 
-The main Rayburst app must be built first to generate the `remoteEntry.js`:
+Unregister a project.
 
 ```bash
-# From the root of the rayburst project
-npm run build
+# Unregister by project ID
+rayburst unregister abc-123
 ```
 
-This creates:
-- `dist/assets/remoteEntry.js` - Module federation remote entry
-- All other bundled assets
+## Features
 
-### 2. Start the Main App
+### 📊 Interactive Dependency Graphs
+- Visual representation of code dependencies
+- Function and class relationships
+- Import/export connections
+- Interactive node exploration
 
-Start the main app on port 3000:
+### 🔍 Git Integration
+- Multi-branch support
+- Filter by uncommitted changes
+- Branch comparison
+- Track changes over time
 
-```bash
-npm run start
-```
+### 🎨 Rich Visualization
+- React Flow-based graphs
+- Collapsible node groups
+- Search and filter
+- Auto-layout options
+
+### 🔄 Real-time Updates
+- File watching (coming soon)
+- Incremental analysis (coming soon)
+- Live graph updates (coming soon)
 
-The app will be available at `http://localhost:3000` and expose its remote entry at `http://localhost:3000/assets/remoteEntry.js`.
+## Usage Workflow
 
-### 3. Build the CLI
+### 1. Register Your Projects
 
 ```bash
-cd cli
-npm run build
+cd /path/to/project1
+rayburst register
+
+cd /path/to/project2
+rayburst register
 ```
 
-### 4. Start the CLI
+### 2. Analyze Projects
 
 ```bash
-rayburst start
+rayburst analyze project1
+rayburst analyze project2
 ```
 
-or directly:
+### 3. Explore in Dashboard
 
 ```bash
-cd cli
-npm run dev
+rayburst start
 ```
 
-The CLI will now be running at `http://localhost:3105` and loading the app from `http://localhost:3000`.
+Navigate to `http://localhost:3105` and:
+- Browse registered projects
+- Select branches to view
+- Explore dependency graphs
+- Compare branches
+- Filter by changed files
+
+## Dashboard Features
+
+### Project Management
+- View all registered projects
+- See analysis status
+- Browse branches
+- Open multiple tabs
+
+### Workspace
+- Interactive dependency graphs
+- Node details sidebar
+- Command palette (⌘K)
+- Multi-tab support
+
+### Filtering
+- **All Files**: Show complete dependency graph
+- **Changes Only**: Filter to show only uncommitted changes
+- Custom visibility controls
+- Search functionality
 
 ## Architecture
 
-### Module Federation Setup
+### Module Federation
 
-**Main App (Remote)**
-- Name: `rayburstApp`
-- Port: 3000
-- Exposes: `./App` → `./src/main.tsx`
-- Shared: `react`, `react-dom`
+The CLI uses Module Federation to load the dashboard UI dynamically:
 
-**CLI (Host)**
-- Name: `rayburstCli`
-- Port: 3105
-- Remotes: `rayburstApp` from environment-specific URL
-- Shared: `react`, `react-dom`
+- **CLI (Host)**: Port 3105
+- **Dashboard (Remote)**: Loaded from rayburst.app
+- **Shared**: React, React-DOM
 
-### File Structure
+### Data Storage
 
-```
-cli/
-├── bin/
-│   └── rayburst.js          # CLI entry point
-├── src/
-│   └── main.tsx             # React shell that loads remote
-├── dist/                    # Built files (generated)
-├── index.html               # HTML shell with loading state
-├── server.js                # Express server
-├── vite.config.ts           # Vite + Module Federation config
-├── package.json
-└── README.md
-```
+- **Registry**: `~/.rayburst/projects.json`
+- **Analysis Data**: `~/.rayburst/analysis/<project-id>.json`
 
 ## Environment Configuration
 
-The CLI automatically determines which remote URL to use based on the environment:
-
 | Environment | Remote URL | Use Case |
 |------------|-----------|----------|
 | development | http://localhost:3000 | Local development |
 | staging | https://dev.rayburst.app | Staging/testing |
-| production | https://www.rayburst.app | Production |
+| production | https://www.rayburst.app | Production (default) |
 
-## Troubleshooting
-
-### Port 3000 Already in Use
+## Examples
 
-If port 3000 is already in use, find and kill the process:
+### Analyze Multiple Projects
 
 ```bash
-lsof -i :3000
-kill <PID>
+# Register projects
+rayburst register ~/projects/frontend --name "Frontend"
+rayburst register ~/projects/backend --name "Backend"
+rayburst register ~/projects/shared --name "Shared Lib"
+
+# Analyze all
+rayburst list | xargs -I {} rayburst analyze {}
+
+# Start dashboard
+rayburst start
 ```
 
-### Port 3105 Already in Use
+### Daily Workflow
+
+```bash
+# Morning: Start dashboard
+rayburst start
+
+# After changes: Re-analyze
+rayburst analyze
+
+# View only your changes
+# (Use "Changes Only" toggle in dashboard)
+```
 
-Similarly for port 3105:
+### Custom Port Setup
 
 ```bash
-lsof -i :3105
-kill <PID>
+# If port 3105 is in use
+rayburst start --port 8080
 ```
 
-### Remote Entry Not Found
+## Troubleshooting
 
-Make sure the main app is **built** and running the **preview server** (not dev server):
+### Port Already in Use
 
 ```bash
-# 1. Build the app first
-npm run build
-
-# 2. Start the preview server (serves built files)
-npm run start
+# Find process using port
+lsof -i :3105
 
-# 3. Verify remoteEntry.js is accessible
-curl -I http://localhost:3000/assets/remoteEntry.js
+# Kill process
+kill <PID>
 ```
 
-Should return `200 OK` with `Content-Type: text/javascript`.
+### Analysis Fails
 
-**Important**: The dev server (`npm run dev`) does NOT generate the `remoteEntry.js` file. You must:
-1. Build the app with `npm run build`
-2. Serve built files with `npm run start` (vite preview)
+- Ensure project has a `package.json`
+- Check for TypeScript/JavaScript files
+- Verify git repository (for branch support)
+- Check file permissions
 
-If you see `Content-Type: text/html` instead of `text/javascript`, you're running the dev server instead of the preview server.
+### Dashboard Not Loading
 
-### Module Federation Loading Errors
+- Verify internet connection (loads remote from rayburst.app)
+- Check firewall settings
+- Try `--env development` for local testing
 
-1. Ensure both apps share the same major versions of React and React DOM
-2. Check browser console for detailed error messages
-3. Verify the remote URL is accessible from the host
-4. Check CORS headers if loading from different domains
+### No Projects Listed
 
-## Testing Different Environments
-
-### Local Testing
 ```bash
-# Terminal 1: Start main app
-npm run start
+# Check registry location
+rayburst list
 
-# Terminal 2: Start CLI
-rayburst start
+# Re-register project
+rayburst register /path/to/project
 ```
 
-Visit: `http://localhost:3105`
+## Development
+
+### Local Setup
 
-### Staging Testing
 ```bash
-rayburst start --env staging
-```
+# Clone repository
+git clone https://github.com/your-org/rayburst-cli.git
+cd rayburst-cli
 
-Visit: `http://localhost:3105` (loads from dev.rayburst.app)
+# Install dependencies
+npm install
 
-### Production Testing
-```bash
-rayburst start --env production
-```
+# Build
+npm run build
+
+# Link for local testing
+npm link
 
-Visit: `http://localhost:3105` (loads from www.rayburst.app)
+# Test commands
+rayburst --help
+```
 
-## Scripts
+### Project Structure
 
-- `npm run dev` - Start CLI in development mode
-- `npm run build` - Build the CLI for production
-- `npm run start` - Start the CLI server (requires build first)
+```
+rayburst-cli/
+├── bin/
+│   └── rayburst.js          # CLI entry point
+├── src/
+│   ├── registry.js          # Project registry
+│   ├── git-utils.js         # Git operations
+│   ├── file-watcher.js      # File watching
+│   └── main.tsx             # Dashboard loader
+├── scripts/
+│   └── analyze-project.js   # Analysis engine
+├── server.js                # Express server
+├── vite.config.ts           # Build config
+└── package.json
+```
 
 ## Tech Stack
 
@@ -262,12 +333,20 @@ Visit: `http://localhost:3105` (loads from www.rayburst.app)
 - **Express** - Production server
 - **Commander** - CLI framework
 - **Chalk** - Terminal styling
+- **ts-morph** - TypeScript analysis
+- **chokidar** - File watching
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests.
+
+## License
+
+MIT
 
-## Future Enhancements
+## Links
 
-- [ ] Auto-detect if remote is available and fallback
-- [ ] Support for custom remote URLs via config file
-- [ ] Health check endpoint
-- [ ] Hot reload support for development
-- [ ] Docker support
-- [ ] CI/CD integration examples
+- [Documentation](https://rayburst.app/docs)
+- [GitHub Repository](https://github.com/your-org/rayburst)
+- [Issue Tracker](https://github.com/your-org/rayburst/issues)
+- [Changelog](https://github.com/your-org/rayburst/releases)

package/bin/rayburst.js

@@ -4,7 +4,16 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
+import {
+  registerProject,
+  unregisterProject,
+  listProjects,
+  getRegistryPaths,
+  writeAnalysisData,
+  updateProjectAnalysis,
+} from '../src/registry.js';
+import { analyzeProject } from '../scripts/analyze-project.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -58,4 +67,150 @@ program
     });
   });
 
+program
+  .command('register')
+  .description('Register the current directory as a Rayburst project')
+  .argument('[path]', 'Path to register (defaults to current directory)', '.')
+  .option('--no-analyze', 'Skip automatic code analysis')
+  .action((projectPath, options) => {
+    try {
+      console.log(chalk.blue('📦 Registering project...'));
+      const project = registerProject(projectPath);
+      console.log(chalk.green('✓ Project registered successfully!'));
+      console.log(chalk.gray(`   Name: ${project.name}`));
+      console.log(chalk.gray(`   Path: ${project.path}`));
+      console.log(chalk.gray(`   ID: ${project.id}`));
+      console.log();
+
+      // Run analysis by default
+      if (options.analyze !== false) {
+        console.log(chalk.blue('🔍 Analyzing project...'));
+        try {
+          const analysisData = analyzeProject(project.path);
+          writeAnalysisData(project.id, analysisData);
+          updateProjectAnalysis(project.id);
+          console.log(chalk.green('✓ Analysis complete!'));
+          console.log(chalk.gray(`   Nodes: ${analysisData.planData[Object.keys(analysisData.planData)[0]]?.nodes?.length || 0}`));
+          console.log(chalk.gray(`   Edges: ${analysisData.planData[Object.keys(analysisData.planData)[0]]?.edges?.length || 0}`));
+        } catch (error) {
+          console.warn(chalk.yellow('⚠ Analysis failed:'), error.message);
+          console.warn(chalk.dim('   Project registered but without analysis data'));
+        }
+      }
+
+      console.log();
+      console.log(chalk.dim('💡 Run'), chalk.cyan('rayburst list'), chalk.dim('to see all registered projects'));
+      console.log(chalk.dim('💡 Run'), chalk.cyan('rayburst start'), chalk.dim('to open the Rayburst dashboard'));
+    } catch (error) {
+      console.error(chalk.red('✗ Registration failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('unregister')
+  .description('Unregister a Rayburst project')
+  .argument('[path]', 'Path or project ID to unregister (defaults to current directory)', '.')
+  .action((projectPath) => {
+    try {
+      console.log(chalk.blue('📦 Unregistering project...'));
+      const project = unregisterProject(projectPath);
+      console.log(chalk.green('✓ Project unregistered successfully!'));
+      console.log(chalk.gray(`   Name: ${project.name}`));
+      console.log(chalk.gray(`   Path: ${project.path}`));
+    } catch (error) {
+      console.error(chalk.red('✗ Unregistration failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List all registered Rayburst projects')
+  .action(() => {
+    try {
+      const projects = listProjects();
+
+      if (projects.length === 0) {
+        console.log(chalk.yellow('No projects registered yet.'));
+        console.log();
+        console.log(chalk.dim('💡 Run'), chalk.cyan('rayburst register'), chalk.dim('in a project directory to register it'));
+        return;
+      }
+
+      console.log(chalk.blue(`📦 Registered Projects (${projects.length}):\n`));
+
+      projects.forEach((project, index) => {
+        console.log(chalk.bold(`${index + 1}. ${project.name}`));
+        console.log(chalk.gray(`   Path: ${project.path}`));
+        console.log(chalk.gray(`   ID: ${project.id}`));
+        console.log(chalk.gray(`   Version: ${project.packageJson?.version || 'N/A'}`));
+        console.log(chalk.gray(`   Registered: ${new Date(project.registeredAt).toLocaleString()}`));
+        if (project.lastAnalyzed) {
+          console.log(chalk.gray(`   Last Analyzed: ${new Date(project.lastAnalyzed).toLocaleString()}`));
+        }
+        console.log();
+      });
+
+      const paths = getRegistryPaths();
+      console.log(chalk.dim(`Registry location: ${paths.projectsFile}`));
+    } catch (error) {
+      console.error(chalk.red('✗ Failed to list projects:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('analyze')
+  .description('Analyze a registered Rayburst project')
+  .argument('[path]', 'Path or project ID to analyze (defaults to current directory)', '.')
+  .action((projectPath) => {
+    try {
+      // Find the project by path or ID
+      const projects = listProjects();
+      const absolutePath = resolve(projectPath);
+
+      let project = projects.find(p => p.path === absolutePath);
+      if (!project) {
+        // Try to find by ID
+        project = projects.find(p => p.id === projectPath);
+      }
+
+      if (!project) {
+        console.error(chalk.red('✗ Project not found. Make sure it\'s registered first.'));
+        console.log();
+        console.log(chalk.dim('💡 Run'), chalk.cyan('rayburst list'), chalk.dim('to see registered projects'));
+        console.log(chalk.dim('💡 Run'), chalk.cyan('rayburst register'), chalk.dim('to register a new project'));
+        process.exit(1);
+      }
+
+      console.log(chalk.blue('🔍 Analyzing project...'));
+      console.log(chalk.gray(`   Name: ${project.name}`));
+      console.log(chalk.gray(`   Path: ${project.path}`));
+      console.log();
+
+      const analysisData = analyzeProject(project.path);
+      writeAnalysisData(project.id, analysisData);
+      updateProjectAnalysis(project.id);
+
+      console.log(chalk.green('✓ Analysis complete!'));
+
+      // Show stats for each branch
+      const branchIds = Object.keys(analysisData.planData);
+      console.log(chalk.gray(`   Branches analyzed: ${branchIds.length}`));
+
+      branchIds.forEach(branchId => {
+        const planData = analysisData.planData[branchId];
+        const branch = analysisData.branches.find(b => b.id === branchId);
+        console.log(chalk.gray(`   - ${branch?.name || branchId}: ${planData.nodes.length} nodes, ${planData.edges.length} edges`));
+      });
+
+      console.log();
+      console.log(chalk.dim('💡 Run'), chalk.cyan('rayburst start'), chalk.dim('to view the analysis in the dashboard'));
+    } catch (error) {
+      console.error(chalk.red('✗ Analysis failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
 program.parse();