@myop/cli 0.1.4 → 0.1.6

package/README.md

@@ -0,0 +1,335 @@
+# @myop/cli
+
+[![npm version](https://img.shields.io/npm/v/@myop/cli.svg)](https://www.npmjs.com/package/@myop/cli)
+[![License](https://img.shields.io/npm/l/@myop/cli.svg)](https://github.com/myop/cli/blob/main/LICENSE)
+
+> Command-line interface for building, developing, and managing Myop components
+
+Myop CLI is a powerful developer tool for creating and managing remote UI components. Build once, deploy anywhere - components built with Myop can be consumed across different frameworks and platforms.
+
+## Features
+
+- 🚀 **Development Server** - Hot-reload enabled dev server with visual network monitoring
+- 📊 **Visual Dashboard** - Real-time request tracking and architecture visualization
+- 🔄 **Auto-sync** - Automatic component synchronization across multiple dev instances
+- 🌐 **Proxy Fallback** - Seamless fallback to cloud-hosted components
+- 📦 **Component Management** - Easy component registration and discovery
+- 🎨 **Professional UI** - Chrome DevTools-inspired interface with zoom/pan capabilities
+
+## Installation
+
+```bash
+npm install -g @myop/cli
+```
+
+Or use locally in your project:
+
+```bash
+npm install --save-dev @myop/cli
+```
+
+## Quick Start
+
+### Initialize a New Component
+
+```bash
+# Create a new component
+myop add
+
+# Start development server
+myop dev
+```
+
+### Development Workflow
+
+1. **Start the dev server** in your component directory:
+   ```bash
+   myop dev
+   ```
+
+2. **Access the dashboard** at `http://localhost:9292`
+
+3. **View your component** at `http://localhost:9292/view/<componentId>/`
+
+4. **Make changes** - the server watches `.js` and `.css` files and rebuilds automatically
+
+## Commands
+
+### `myop dev`
+
+Start the development server with file watching and hot-reload.
+
+```bash
+myop dev [options]
+```
+
+**Features:**
+- Runs on ports `9292` (main) and `9293` (management)
+- Watches `.js` and `.css` files for changes
+- Automatic builds on file changes
+- Visual dashboard with network architecture diagram
+- Multiple instances can register with the same server
+- Health monitoring with automatic failover
+
+**Options:**
+- `-c, --config <path>` - Path to myop.config.json (default: `./myop.config.json`)
+- `-v, --verbose` - Enable verbose logging
+
+### `myop add`
+
+Add a new flow or component to your project.
+
+```bash
+myop add
+```
+
+Interactive prompt to add new components to your Myop configuration.
+
+### `myop remove`
+
+Remove a flow or component from your project.
+
+```bash
+myop remove
+```
+
+Interactive prompt to remove components from your configuration.
+
+### `myop install`
+
+Install dependencies and set up your Myop project.
+
+```bash
+myop install
+```
+
+### `myop sync`
+
+Synchronize your components with the Myop cloud.
+
+```bash
+myop sync
+```
+
+## Configuration
+
+Create a `myop.config.json` in your project root:
+
+```json
+{
+  "componentId": "your-component-id",
+  "componentName": "My Component"
+}
+```
+
+**Fields:**
+- `componentId` (required) - Unique identifier for your component
+- `componentName` (optional) - Human-readable name displayed in the dashboard
+
+## Development Dashboard
+
+The dev server includes a professional visual dashboard accessible at `http://localhost:9292`:
+
+### Features
+
+- **Network Architecture View**
+  - Visual diagram showing request flow from origins → local server → cloud
+  - Interactive nodes (drag to reposition)
+  - Zoom and pan controls
+  - Curved connection lines for better readability
+
+- **Real-time Monitoring**
+  - Live request tracking via Server-Sent Events (SSE)
+  - Origin detection and grouping
+  - Component request counts
+  - Local vs. proxied request statistics
+
+- **Component Registry**
+  - All registered components with IDs and names
+  - Direct links to component views
+  - File paths for easy navigation
+
+- **Activity Log**
+  - Recent request history
+  - Origin information
+  - Timestamp tracking
+
+## Architecture
+
+### Multi-Instance Support
+
+The dev server supports running multiple component instances simultaneously:
+
+1. **First Instance** - Starts both main and management servers
+2. **Additional Instances** - Register with the existing server
+3. **Auto-Failover** - If the main server dies, another instance takes over
+
+### Request Flow
+
+```
+Origin Request
+    ↓
+Local Dev Server (port 9292)
+    ↓
+Component Registered?
+    ├─ Yes → Serve from local dist/
+    └─ No  → Proxy to cloud.myop.dev
+```
+
+### File Structure
+
+```
+myop-cli/
+├── src/
+│   ├── myop-cli.js              # Main CLI entry point
+│   ├── commands/
+│   │   └── dev/                 # Dev command
+│   │       ├── index.js         # Server logic
+│   │       ├── README.md        # Dev command docs
+│   │       └── management-website/
+│   │           ├── index.js     # HTML generator
+│   │           ├── styles.css   # Dashboard styles
+│   │           └── app.js       # Client-side code
+│   ├── operations/              # CLI operations
+│   └── common/                  # Shared utilities
+└── dist/                        # Built files (npm publish)
+```
+
+## API
+
+### Consume Endpoint
+
+```
+GET /consume?id=<componentId>
+```
+
+Returns the component's HTML loader configuration. Serves from local dist if registered, otherwise proxies to cloud.
+
+**Response:**
+```json
+{
+  "item": {
+    "id": "component-id",
+    "name": "component-id",
+    "consume_variant": [{
+      "id": "variant-id",
+      "name": "dev version",
+      "loader": {
+        "type": "HTMLLoader",
+        "shadowRootMode": "localFrame",
+        "HTML": "<html>...</html>"
+      }
+    }]
+  }
+}
+```
+
+### Management API (port 9293)
+
+#### Register Component
+```
+POST /_register
+Body: { "componentId": "id", "distPath": "/path", "componentName": "name" }
+```
+
+#### Unregister Component
+```
+POST /_unregister
+Body: { "componentId": "id" }
+```
+
+#### List Components
+```
+GET /_list
+Response: { "components": [[id, {path, name}], ...] }
+```
+
+## Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/myop/cli.git
+cd cli
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test locally
+./dist/myop-cli.js dev
+```
+
+### Project Structure
+
+The CLI is built with Vite and uses ES modules. Key technologies:
+
+- **Commander.js** - CLI framework
+- **Inquirer** - Interactive prompts
+- **Ora** - Terminal spinners
+- **Native Node.js APIs** - HTTP server, file watching, child processes
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- Code of Conduct
+- Development workflow
+- Submitting pull requests
+- Coding standards
+
+## Troubleshooting
+
+### Port Already in Use
+
+If ports 9292 or 9293 are already in use:
+
+```bash
+# Find process using the port
+lsof -i :9292
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Component Not Found
+
+Ensure your `myop.config.json` exists and contains a valid `componentId`:
+
+```bash
+cat myop.config.json
+```
+
+### Build Errors
+
+Clear the dist folder and rebuild:
+
+```bash
+rm -rf dist node_modules
+npm install
+npm run build
+```
+
+## License
+
+[LICENSE](LICENSE)
+
+## Links
+
+- [Homepage](https://myop.dev)
+- [Documentation](https://docs.myop.dev)
+- [GitHub Issues](https://github.com/myop/cli/issues)
+- [NPM Package](https://www.npmjs.com/package/@myop/cli)
+
+## Support
+
+- 📧 Email: support@myop.dev
+- 💬 Discord: [Join our community](https://myop.dev/discord)
+- 🐛 Issues: [GitHub Issues](https://github.com/myop/cli/issues)
+
+---
+
+Made with ❤️ by the Myop team