@rayburst/cli 0.1.0

package/README.md

@@ -0,0 +1,273 @@
+# 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.
+
+## Installation
+
+### Local Development Setup
+
+1. Install dependencies:
+```bash
+cd cli
+npm install
+```
+
+2. Build the CLI:
+```bash
+npm run build
+```
+
+3. Link the CLI globally for testing:
+```bash
+npm link
+```
+
+### Publishing to npm (Future)
+
+Once ready for production:
+```bash
+npm publish
+```
+
+Then users can install globally:
+```bash
+npm install -g rayburst-cli
+```
+
+## Usage
+
+### Starting the CLI
+
+```bash
+rayburst start
+```
+
+This will start the CLI server on port 3105 in development mode, loading the app from `localhost:3000`.
+
+### Command Options
+
+```bash
+rayburst start [options]
+
+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
+```
+
+### Examples
+
+Start on custom port:
+```bash
+rayburst start --port 4000
+```
+
+Start in staging mode:
+```bash
+rayburst start --env staging
+```
+
+Start in production mode:
+```bash
+rayburst start --env production --port 8080
+```
+
+## Development Workflow
+
+### 1. Build the Main App (Remote)
+
+The main Rayburst app must be built first to generate the `remoteEntry.js`:
+
+```bash
+# From the root of the rayburst project
+npm run build
+```
+
+This creates:
+- `dist/assets/remoteEntry.js` - Module federation remote entry
+- All other bundled assets
+
+### 2. Start the Main App
+
+Start the main app on port 3000:
+
+```bash
+npm run start
+```
+
+The app will be available at `http://localhost:3000` and expose its remote entry at `http://localhost:3000/assets/remoteEntry.js`.
+
+### 3. Build the CLI
+
+```bash
+cd cli
+npm run build
+```
+
+### 4. Start the CLI
+
+```bash
+rayburst start
+```
+
+or directly:
+
+```bash
+cd cli
+npm run dev
+```
+
+The CLI will now be running at `http://localhost:3105` and loading the app from `http://localhost:3000`.
+
+## Architecture
+
+### Module Federation Setup
+
+**Main App (Remote)**
+- Name: `rayburstApp`
+- Port: 3000
+- Exposes: `./App` → `./src/main.tsx`
+- Shared: `react`, `react-dom`
+
+**CLI (Host)**
+- Name: `rayburstCli`
+- Port: 3105
+- Remotes: `rayburstApp` from environment-specific URL
+- Shared: `react`, `react-dom`
+
+### File Structure
+
+```
+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
+```
+
+## 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 |
+
+## Troubleshooting
+
+### Port 3000 Already in Use
+
+If port 3000 is already in use, find and kill the process:
+
+```bash
+lsof -i :3000
+kill <PID>
+```
+
+### Port 3105 Already in Use
+
+Similarly for port 3105:
+
+```bash
+lsof -i :3105
+kill <PID>
+```
+
+### Remote Entry Not Found
+
+Make sure the main app is **built** and running the **preview server** (not dev server):
+
+```bash
+# 1. Build the app first
+npm run build
+
+# 2. Start the preview server (serves built files)
+npm run start
+
+# 3. Verify remoteEntry.js is accessible
+curl -I http://localhost:3000/assets/remoteEntry.js
+```
+
+Should return `200 OK` with `Content-Type: text/javascript`.
+
+**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)
+
+If you see `Content-Type: text/html` instead of `text/javascript`, you're running the dev server instead of the preview server.
+
+### Module Federation Loading Errors
+
+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
+
+## Testing Different Environments
+
+### Local Testing
+```bash
+# Terminal 1: Start main app
+npm run start
+
+# Terminal 2: Start CLI
+rayburst start
+```
+
+Visit: `http://localhost:3105`
+
+### Staging Testing
+```bash
+rayburst start --env staging
+```
+
+Visit: `http://localhost:3105` (loads from dev.rayburst.app)
+
+### Production Testing
+```bash
+rayburst start --env production
+```
+
+Visit: `http://localhost:3105` (loads from www.rayburst.app)
+
+## Scripts
+
+- `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)
+
+## 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
+
+## Future Enhancements
+
+- [ ] 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

package/bin/rayburst.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const program = new Command();
+
+program
+  .name('rayburst')
+  .description('Rayburst CLI - Module Federation Host')
+  .version('0.1.0');
+
+program
+  .command('start')
+  .description('Start the Rayburst application')
+  .option('-p, --port <port>', 'Port to run the server on', '3105')
+  .option('-e, --env <environment>', 'Environment (development|staging|production)', 'development')
+  .action((options) => {
+    console.log(chalk.blue('🚀 Starting Rayburst CLI...'));
+    console.log(chalk.gray(`   Port: ${options.port}`));
+    console.log(chalk.gray(`   Environment: ${options.env}`));
+
+    const serverPath = join(__dirname, '..', 'server.js');
+
+    const env = {
+      ...process.env,
+      PORT: options.port,
+      NODE_ENV: options.env,
+    };
+
+    const server = spawn('node', [serverPath], {
+      env,
+      stdio: 'inherit',
+    });
+
+    server.on('error', (err) => {
+      console.error(chalk.red('Failed to start server:'), err);
+      process.exit(1);
+    });
+
+    server.on('exit', (code) => {
+      if (code !== 0) {
+        console.error(chalk.red(`Server exited with code ${code}`));
+        process.exit(code);
+      }
+    });
+
+    process.on('SIGINT', () => {
+      console.log(chalk.yellow('\n👋 Shutting down Rayburst CLI...'));
+      server.kill('SIGINT');
+      process.exit(0);
+    });
+  });
+
+program.parse();

package/dist/assets/_commonjsHelpers-B85MJLTf.js

@@ -0,0 +1,5 @@
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+export { getDefaultExportFromCjs as g };

package/dist/assets/hostInit-CYZeRSfr.js

@@ -0,0 +1,9 @@
+import { _ as __vitePreload } from './preload-helper-Dea3Szod.js';
+
+const remoteEntryPromise = __vitePreload(() => import('./remoteEntry-BkHjZ4dx.js'),true              ?[]:void 0);
+    // __tla only serves as a hack for vite-plugin-top-level-await.
+    Promise.resolve(remoteEntryPromise)
+      .then(remoteEntry => {
+        return Promise.resolve(remoteEntry.__tla)
+          .then(remoteEntry.init).catch(remoteEntry.init)
+      });