@rayburst/cli 0.1.17 → 0.2.0

package/README.md

@@ -1,344 +1,253 @@
-# Rayburst CLI
+# Rayburst
 
-A powerful CLI tool for analyzing and visualizing TypeScript/JavaScript project dependencies and architecture.
+Automatic code analysis for TypeScript/JavaScript projects. Rayburst runs in the background during development and generates dependency graphs that you can visualize in the Rayburst web application.
 
-## Installation
-
-Install globally via npm:
+## Features
 
-```bash
-npm install -g @rayburst/cli
-```
+- **Automatic Analysis**: Runs automatically when you start your dev server - no manual commands needed
+- **Real-time Updates**: Watches for file changes and updates analysis instantly
+- **TypeScript/JavaScript Support**: Full analysis of TS, TSX, JS, and JSX files
+- **React Components**: Detects React components and their dependencies
+- **Function Tracking**: Maps function calls and relationships
+- **Git Integration**: Tracks branches, commits, and changes
+- **Zero Configuration**: Works out of the box with sensible defaults
 
-## Quick Start
+## Installation
 
 ```bash
-# Register your project
-rayburst register /path/to/your/project
-
-# Analyze the project
-rayburst analyze
-
-# Start the dashboard
-rayburst start
+npm install --save-dev @rayburst/cli
 ```
 
-Open your browser to `http://localhost:3105` to view the interactive dashboard.
+## Usage
 
-## Commands
+### Vite Projects
 
-### `rayburst register [path]`
+Add the Rayburst plugin to your `vite.config.ts`:
 
-Register a project for analysis.
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { rayburstPlugin } from '@rayburst/cli/vite'
 
-```bash
-# Register current directory
-rayburst register
-
-# Register specific path
-rayburst register /path/to/project
-
-# Register with custom name
-rayburst register --name "My Project"
+export default defineConfig({
+  plugins: [
+    rayburstPlugin(),  // Add this line
+    react(),
+  ],
+})
 ```
 
-**Options:**
-- `[path]` - Path to project directory (default: current directory)
-- `-n, --name <name>` - Custom project name
-
-### `rayburst list`
-
-List all registered projects.
+That's it! Now when you run `npm run dev`, Rayburst will automatically:
+1. Run initial code analysis
+2. Generate `.rayburst/analysis.json`
+3. Watch for file changes
+4. Update analysis in real-time
 
-```bash
-rayburst list
-```
+### Configuration Options
 
-Shows:
-- Project name
-- Path
-- Last analyzed timestamp
-- Number of branches
+```typescript
+rayburstPlugin({
+  // Disable the plugin (e.g., for testing)
+  enabled: true,
 
-### `rayburst analyze [path]`
+  // Debounce delay for file changes (ms)
+  debounceMs: 1500,
 
-Analyze a registered project and generate dependency graphs.
-
-```bash
-# Analyze current directory
-rayburst analyze
-
-# Analyze specific project by path
-rayburst analyze /path/to/project
-
-# Analyze specific project by ID
-rayburst analyze abc-123
+  // Custom output path
+  outputPath: '.rayburst/analysis.json',
+})
 ```
 
-**Options:**
-- `[path]` - Project path or ID (default: current directory)
-
-**What it analyzes:**
-- Function and class relationships
-- Import/export dependencies
-- Git branches
-- File structure
-- Code architecture
-
-### `rayburst start`
-
-Start the interactive dashboard server.
-
-```bash
-# Start on default port (3105)
-rayburst start
+## Output
 
-# Start on custom port
-rayburst start --port 4000
+The plugin generates a `.rayburst/` directory in your project root:
 
-# Start in production mode
-rayburst start --env production
 ```
-
-**Options:**
-- `-p, --port <port>` - Server port (default: 3105)
-- `-e, --env <environment>` - Environment: development|staging|production (default: production)
-
-### `rayburst unregister <id>`
-
-Unregister a project.
-
-```bash
-# Unregister by project ID
-rayburst unregister abc-123
+my-project/
+├── .rayburst/
+│   └── analysis.json    # Analysis data (nodes, edges, dependencies)
+├── .gitignore           # Auto-updated to ignore .rayburst/
+├── src/
+├── vite.config.ts
+└── package.json
 ```
 
-## Features
+The `.rayburst/` directory is automatically added to your `.gitignore`.
 
-### 📊 Interactive Dependency Graphs
-- Visual representation of code dependencies
-- Function and class relationships
-- Import/export connections
-- Interactive node exploration
+## Analysis Data
 
-### 🔍 Git Integration
-- Multi-branch support
-- Filter by uncommitted changes
-- Branch comparison
-- Track changes over time
+The generated `analysis.json` contains:
 
-### 🎨 Rich Visualization
-- React Flow-based graphs
-- Collapsible node groups
-- Search and filter
-- Auto-layout options
+- **Nodes**: Components, functions, state declarations
+- **Edges**: Dependencies between nodes
+- **Branches**: Git branch information
+- **Files**: Modification timestamps
 
-### 🔄 Real-time Updates
-- File watching (coming soon)
-- Incremental analysis (coming soon)
-- Live graph updates (coming soon)
+This data can be visualized using the [Rayburst web application](https://rayburst.app).
 
-## Usage Workflow
+## Example Output
 
-### 1. Register Your Projects
+```typescript
+// src/App.tsx
+import { Button } from './components/Button'
 
-```bash
-cd /path/to/project1
-rayburst register
-
-cd /path/to/project2
-rayburst register
+export function App() {
+  return <Button onClick={() => alert('Hello')} />
+}
 ```
 
-### 2. Analyze Projects
-
-```bash
-rayburst analyze project1
-rayburst analyze project2
-```
+Rayburst detects:
+- `App` component (node)
+- `Button` component usage (edge: App → Button)
+- JSX relationships
+- File structure
 
-### 3. Explore in Dashboard
+## Console Output
 
 ```bash
-rayburst start
-```
-
-Navigate to `http://localhost:3105` and:
-- Browse registered projects
-- Select branches to view
-- Explore dependency graphs
-- Compare branches
-- Filter by changed files
+$ npm run dev
 
-## Dashboard Features
+[Rayburst] Starting code analysis...
+[Rayburst] Initial analysis complete: 42 nodes, 68 edges
 
-### 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
+# When you edit a file:
+[Rayburst] File changed: src/App.tsx
+[Rayburst] Analysis updated:
+  Added: 1 nodes, 2 edges
+  Modified: 1 nodes
+```
 
-## Architecture
+## How It Works
 
-### Module Federation
+Rayburst uses a Vite plugin that:
 
-The CLI uses Module Federation to load the dashboard UI dynamically:
+1. **Hooks into Vite's lifecycle**: Runs when dev server starts
+2. **Uses ts-morph**: Analyzes TypeScript/JavaScript AST
+3. **Watches files**: Leverages Vite's built-in file watcher
+4. **Incremental updates**: Only re-analyzes changed files
+5. **Generates graphs**: Produces node/edge data structures
 
-- **CLI (Host)**: Port 3105
-- **Dashboard (Remote)**: Loaded from rayburst.app
-- **Shared**: React, React-DOM
+## Requirements
 
-### Data Storage
+- **Vite**: 4.x, 5.x, 6.x, or 7.x
+- **TypeScript**: Project must have `tsconfig.json`
+- **package.json**: Required for project metadata
 
-- **Registry**: `~/.rayburst/projects.json`
-- **Analysis Data**: `~/.rayburst/analysis/<project-id>.json`
+## Browser Compatibility
 
-## Environment Configuration
+The analysis data can be viewed in the Rayburst web app, which requires:
+- Chrome 86+ or Edge 86+ (for File System Access API)
 
-| Environment | Remote URL | Use Case |
-|------------|-----------|----------|
-| development | http://localhost:3000 | Local development |
-| staging | https://dev.rayburst.app | Staging/testing |
-| production | https://www.rayburst.app | Production (default) |
+## Advanced Usage
 
-## Examples
+### Programmatic API
 
-### Analyze Multiple Projects
+You can also use Rayburst programmatically:
 
-```bash
-# Register projects
-rayburst register ~/projects/frontend --name "Frontend"
-rayburst register ~/projects/backend --name "Backend"
-rayburst register ~/projects/shared --name "Shared Lib"
+```typescript
+import { analyzeProject, writeLocalAnalysis } from '@rayburst/cli'
 
-# Analyze all
-rayburst list | xargs -I {} rayburst analyze {}
+// Analyze a project
+const analysis = await analyzeProject('/path/to/project')
 
-# Start dashboard
-rayburst start
+// Write results
+await writeLocalAnalysis('/path/to/project', analysis)
 ```
 
-### Daily Workflow
+### Custom Integration
 
-```bash
-# Morning: Start dashboard
-rayburst start
+```typescript
+import {
+  analyzeProject,
+  ensureRayburstDir,
+  writeLocalAnalysis
+} from '@rayburst/cli'
 
-# After changes: Re-analyze
-rayburst analyze
+async function customAnalysis() {
+  const projectPath = process.cwd()
 
-# View only your changes
-# (Use "Changes Only" toggle in dashboard)
-```
+  // Ensure .rayburst directory exists
+  await ensureRayburstDir(projectPath)
 
-### Custom Port Setup
+  // Run analysis
+  const result = await analyzeProject(projectPath)
 
-```bash
-# If port 3105 is in use
-rayburst start --port 8080
+  // Save results
+  await writeLocalAnalysis(projectPath, result)
+
+  console.log(`Analyzed ${result.planData.nodes.length} nodes`)
+}
 ```
 
 ## Troubleshooting
 
-### Port Already in Use
+### Plugin Not Running
 
-```bash
-# Find process using port
-lsof -i :3105
+Make sure:
+1. Plugin is added to `vite.config.ts`
+2. You're running in dev mode (`npm run dev`, not `npm run build`)
+3. Project has `tsconfig.json`
 
-# Kill process
-kill <PID>
-```
+### No Analysis Generated
 
-### Analysis Fails
+Check:
+1. `.rayburst/` directory exists
+2. Console for error messages
+3. Project has TypeScript/JavaScript files
 
-- Ensure project has a `package.json`
-- Check for TypeScript/JavaScript files
-- Verify git repository (for branch support)
-- Check file permissions
+### Analysis Fails
 
-### Dashboard Not Loading
+Common causes:
+- Invalid `tsconfig.json`
+- TypeScript compilation errors
+- Missing `package.json`
 
-- Verify internet connection (loads remote from rayburst.app)
-- Check firewall settings
-- Try `--env development` for local testing
+Enable verbose logging:
+```typescript
+rayburstPlugin({
+  enabled: process.env.DEBUG === 'true'
+})
+```
 
-### No Projects Listed
+## CI/CD
 
-```bash
-# Check registry location
-rayburst list
+The plugin is automatically disabled in CI environments (when `CI=true`). To force enable:
 
-# Re-register project
-rayburst register /path/to/project
+```typescript
+rayburstPlugin({
+  enabled: true  // Always enabled
+})
 ```
 
-## Development
+## Migration from Old Versions
 
-### Local Setup
+If you were using `rayburst watch` command:
 
+**Before:**
 ```bash
-# Clone repository
-git clone https://github.com/your-org/rayburst-cli.git
-cd rayburst-cli
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
+# Terminal 1
+npm run dev
 
-# Link for local testing
-npm link
-
-# Test commands
-rayburst --help
+# Terminal 2
+rayburst watch
 ```
 
-### Project Structure
-
-```
-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
+**After:**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [rayburstPlugin(), react()],
+})
 ```
 
-## Tech Stack
-
-- **Vite** - Build tool and dev server
-- **React 19** - UI library
-- **Module Federation** - Dynamic remote loading
-- **Express** - Production server
-- **Commander** - CLI framework
-- **Chalk** - Terminal styling
-- **ts-morph** - TypeScript analysis
-- **chokidar** - File watching
+```bash
+# Just one terminal
+npm run dev  # Rayburst runs automatically!
+```
 
 ## Contributing
 
-Contributions are welcome! Please read our contributing guidelines and submit pull requests.
+Contributions welcome! Please read our contributing guidelines.
 
 ## License
 
@@ -349,4 +258,3 @@ MIT
 - [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/dist/analysis/analyze-project.d.ts

@@ -0,0 +1,9 @@
+import { type AnalysisResult } from '@rayburst/types';
+/**
+ * Analyze a TypeScript/React project and generate nodes/edges data
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} projectId - Project ID
+ * @param {function} onLog - Callback for logging
+ * @returns {Promise<AnalysisResult>} Analysis data with nodes and edges
+ */
+export declare function analyzeProject(projectPath: string, projectId?: string, onLog?: (message: string) => void): Promise<AnalysisResult>;