@myop/cli 0.1.40 → 0.1.42

package/dist/skills/myop-component/references/component-api.md

@@ -0,0 +1,457 @@
+# Component Public API
+
+Myop components communicate with host applications through exactly 2 global functions defined on `window`. Both must be defined synchronously during top-level script execution.
+
+## Contents
+- [myop_init_interface](#myop_init_interface)
+- [myop_cta_handler](#myop_cta_handler)
+- [Preview Script](#preview-script)
+- [Complete Example](#complete-example)
+- [Host-Side Integration](#host-side-integration)
+
+## myop_init_interface
+
+**Direction:** Host Application -> Component
+
+**Purpose:** Initialize or update the component with data. Also used to read current state.
+
+### Dual Signature
+
+```javascript
+// Setter: Host sends data to component
+window.myop_init_interface(data);   // returns void
+
+// Getter: Host reads current component state
+const state = window.myop_init_interface();  // returns MyopInitData
+```
+
+### Implementation Pattern
+
+```javascript
+(function() {
+    var currentState = {};
+
+    window.myop_init_interface = function(data) {
+        // Getter mode: return current state when called without arguments
+        if (!data) return currentState;
+
+        // Setter mode: store state and render synchronously
+        currentState = data;
+        render(data);
+    };
+
+    function render(data) {
+        var root = document.getElementById('app-root');
+        // Build HTML string and set innerHTML in one operation
+        root.innerHTML = '<h1>' + data.title + '</h1>';
+    }
+})();
+```
+
+### Rules
+
+1. **MUST be defined at top-level** - The host calls this function immediately after loading the component. If it's not yet defined, the component will not receive data.
+
+2. **MUST render synchronously** - When called with data, the component must update the DOM before the function returns. No `setTimeout`, no `requestAnimationFrame`, no `await`.
+
+3. **MUST handle getter mode** - When called without arguments (`myop_init_interface()`), return the current state object. The host uses this to read component state.
+
+4. **MUST be idempotent** - Can be called multiple times with updated data. Each call should fully re-render.
+
+### WRONG Examples
+
+```javascript
+// WRONG: Defined inside DOMContentLoaded (too late)
+document.addEventListener('DOMContentLoaded', () => {
+    window.myop_init_interface = function(data) { render(data); };
+});
+
+// WRONG: Async rendering (host expects synchronous update)
+window.myop_init_interface = async function(data) {
+    const extra = await fetch('/api/data');  // NO!
+    render(data, extra);
+};
+
+// WRONG: Deferred rendering
+window.myop_init_interface = function(data) {
+    setTimeout(() => render(data), 0);  // NO!
+};
+
+// WRONG: Missing getter mode
+window.myop_init_interface = function(data) {
+    render(data);  // What happens when called with no args?
+};
+```
+
+## myop_cta_handler
+
+**Direction:** Component -> Host Application
+
+**Purpose:** Send user actions (clicks, selections, form submissions) from the component to the host application. Also used for standard actions like requesting a size change.
+
+### Signature
+
+```javascript
+window.myop_cta_handler(action_id, payload);
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `action_id` | `string` | Action identifier (kebab-case, e.g. `'item-clicked'`) |
+| `payload` | `object` | Action-specific data |
+
+### Implementation Pattern
+
+```javascript
+(function() {
+    // Define a no-op default (host will override this)
+    window.myop_cta_handler = function(action, payload) {
+        // Will be replaced by host application
+    };
+
+    // Call it when user interacts
+    document.getElementById('app-root').addEventListener('click', function(e) {
+        var button = e.target.closest('button');
+        if (button) {
+            window.myop_cta_handler('button-clicked', {
+                buttonId: button.dataset.id,
+                label: button.textContent
+            });
+        }
+    });
+})();
+```
+
+### Standard Actions
+
+These action IDs have special meaning and are handled by the Myop SDK:
+
+| Action ID | Payload | Purpose |
+|-----------|---------|---------|
+| `'size-requested'` | `{ width?, height?, minWidth?, maxWidth?, minHeight?, maxHeight?, required? }` | Request the host to resize the component container |
+
+```javascript
+// Request more width
+window.myop_cta_handler('size-requested', {
+    width: 400,
+    minWidth: 300,
+    maxWidth: 600,
+    required: true   // true = content is clipped without this size
+                     // false = preference only, host may ignore
+});
+```
+
+### Custom Actions
+
+Define any custom actions your component needs. Use kebab-case for action IDs:
+
+```javascript
+// User selects an item
+window.myop_cta_handler('item-selected', { itemId: 'abc-123' });
+
+// Form submitted
+window.myop_cta_handler('form-submitted', {
+    name: 'John',
+    email: 'john@example.com'
+});
+
+// Status changed
+window.myop_cta_handler('status-changed', { from: 'draft', to: 'published' });
+
+// No-payload action
+window.myop_cta_handler('refresh-requested', {});
+```
+
+### Rules
+
+1. **Define at top-level** - Even though the host overrides it, defining a no-op default prevents errors if the component fires an action before the host sets up its handler.
+
+2. **Use kebab-case** for action IDs: `'item-clicked'` not `'itemClicked'` or `'ITEM_CLICKED'`.
+
+3. **Payload must be serializable** - Plain objects only. No DOM elements, functions, or class instances.
+
+4. **Document all actions** in the `MyopCtaPayloads` type definition so the host developer knows what to expect.
+
+## Preview Script
+
+The `<script id="myop_preview">` block provides mock data for development. In production, the Myop SDK replaces this with a real data call.
+
+```html
+<!-- Runs during development, removed in production -->
+<script id="myop_preview">
+    window.myop_init_interface({
+        title: 'Preview Mode',
+        items: [
+            { id: '1', label: 'Sample item 1' },
+            { id: '2', label: 'Sample item 2' },
+            { id: '3', label: 'Sample item 3' }
+        ]
+    });
+</script>
+```
+
+### Testing Delayed Load
+
+```html
+<script id="myop_preview">
+    // Simulate delayed data arrival
+    setTimeout(function() {
+        window.myop_init_interface({
+            title: 'Loaded after delay',
+            items: []
+        });
+    }, 1000);
+</script>
+```
+
+## Complete Example
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="myop:size" content='{"width":350,"height":"100%","minWidth":250}'>
+    <title>Task List</title>
+    <script type="myop/types">
+    interface MyopInitData {
+        tasks: Array<{
+            id: string;
+            title: string;
+            completed: boolean;
+        }>;
+    }
+
+    interface MyopCtaPayloads {
+        'task-toggled': { taskId: string; completed: boolean };
+        'task-deleted': { taskId: string };
+        'size-requested': {
+            width?: number | null;
+            height?: number | null;
+            minWidth?: number | null;
+            maxWidth?: number | null;
+            minHeight?: number | null;
+            maxHeight?: number | null;
+            required?: boolean;
+        };
+    }
+
+    declare function myop_init_interface(): MyopInitData;
+    declare function myop_init_interface(data: MyopInitData): void;
+    declare function myop_cta_handler<K extends keyof MyopCtaPayloads>(
+        action: K, payload: MyopCtaPayloads[K]
+    ): void;
+    </script>
+    <style>
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        html, body { width: 100%; height: 100%; overflow: hidden;
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            color: #333;
+        }
+        #app-root { width: 100%; height: 100%; display: flex; flex-direction: column; }
+        .header { padding: 12px 16px; border-bottom: 1px solid #eee; font-weight: 600; }
+        .task-list { flex: 1; overflow-y: auto; min-height: 0; }
+        .task { display: flex; align-items: center; padding: 10px 16px;
+            border-bottom: 1px solid #f0f0f0; gap: 10px; }
+        .task.done .task-title { text-decoration: line-through; color: #999; }
+        .task-title { flex: 1; }
+        .delete-btn { cursor: pointer; color: #999; border: none;
+            background: none; font-size: 16px; }
+        .delete-btn:hover { color: #e74c3c; }
+    </style>
+</head>
+<body>
+    <div id="app-root">
+        <div class="header">Tasks</div>
+        <div class="task-list"></div>
+    </div>
+
+    <script>
+    (function() {
+        var state = { tasks: [] };
+        var taskList = document.querySelector('.task-list');
+
+        function render(data) {
+            state = data;
+            taskList.innerHTML = data.tasks.map(function(task) {
+                return '<div class="task' + (task.completed ? ' done' : '') + '" data-id="' + task.id + '">' +
+                    '<input type="checkbox"' + (task.completed ? ' checked' : '') + '>' +
+                    '<span class="task-title">' + task.title + '</span>' +
+                    '<button class="delete-btn" data-action="delete">&times;</button>' +
+                '</div>';
+            }).join('');
+        }
+
+        window.myop_init_interface = function(data) {
+            if (!data) return state;
+            render(data);
+        };
+
+        window.myop_cta_handler = function(action, payload) {};
+
+        // Event delegation for all task interactions
+        taskList.addEventListener('click', function(e) {
+            var taskEl = e.target.closest('.task');
+            if (!taskEl) return;
+            var taskId = taskEl.dataset.id;
+
+            if (e.target.type === 'checkbox') {
+                window.myop_cta_handler('task-toggled', {
+                    taskId: taskId,
+                    completed: e.target.checked
+                });
+            } else if (e.target.dataset.action === 'delete') {
+                window.myop_cta_handler('task-deleted', { taskId: taskId });
+            }
+        });
+    })();
+    </script>
+
+    <script id="myop_preview">
+        window.myop_init_interface({
+            tasks: [
+                { id: '1', title: 'Review pull request', completed: false },
+                { id: '2', title: 'Update documentation', completed: true },
+                { id: '3', title: 'Deploy to staging', completed: false }
+            ]
+        });
+    </script>
+</body>
+</html>
+```
+
+## Host-Side Integration
+
+For context on how the host application consumes these functions in React (useful when debugging or advising host developers):
+
+### Option 1: Auto-Generated React Package (Recommended)
+
+Myop auto-generates a fully typed React package for every component. Install it directly:
+
+```bash
+npm install https://cloud.myop.dev/npm/{component-id}/react
+```
+
+Then import and use it like any React component — with full TypeScript types for `data` and all CTA event payloads:
+
+```tsx
+// Auto-generated package gives you a typed React component
+// e.g. npm install https://cloud.myop.dev/npm/{component-id}/react
+import { TaskList } from "@myop/task-list";
+
+function App() {
+    const [tasks, setTasks] = useState(fetchedTasks);
+
+    return (
+        <TaskList
+            data={{ tasks }}
+            onTaskToggled={(payload) => {
+                // payload is typed as { taskId: string; completed: boolean }
+                updateTask(payload.taskId, { completed: payload.completed });
+            }}
+            onTaskDeleted={(payload) => {
+                // payload is typed as { taskId: string }
+                deleteTask(payload.taskId);
+            }}
+        />
+    );
+}
+```
+
+**Why auto-generated packages are preferred:**
+- Fully typed — TypeScript types for `data` and all CTA event payloads are auto-generated
+- Zero configuration — no `componentId` needed, component is loaded automatically
+- Zero bundle impact — the package is a thin typed wrapper (~6KB total for `@myop/react`), actual component loads at runtime
+
+### Option 2: MyopComponent with `data` and `on` Props
+
+For cases where you don't want to install a per-component package, use `MyopComponent` directly:
+
+```tsx
+import { MyopComponent } from "@myop/react";
+
+function App() {
+    const [tasks, setTasks] = useState(fetchedTasks);
+
+    return (
+        <MyopComponent
+            componentId="your-component-id"
+            data={{ tasks }}
+            on={(action, payload) => {
+                switch (action) {
+                    case 'task-toggled':
+                        updateTask(payload.taskId, { completed: payload.completed });
+                        break;
+                    case 'task-deleted':
+                        deleteTask(payload.taskId);
+                        break;
+                }
+            }}
+        />
+    );
+}
+```
+
+You can also use typed specific handlers alongside the generic `on` handler:
+
+```tsx
+<MyopComponent<TaskData, TaskCtaPayloads>
+    componentId="your-component-id"
+    data={{ tasks }}
+    onTaskToggled={(payload) => {
+        updateTask(payload.taskId, { completed: payload.completed });
+    }}
+    onTaskDeleted={(payload) => {
+        deleteTask(payload.taskId);
+    }}
+/>
+```
+
+### Key Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `componentId` | `string` | The Myop component ID (not needed with auto-generated packages) |
+| `data` | `TData` | Data passed to the component via `myop_init_interface` |
+| `on` | `(action, payload) => void` | Generic handler for all CTA events |
+| `on[ActionName]` | `(payload) => void` | Typed handler for a specific CTA (e.g., `onTaskToggled`) |
+| `style` | `CSSProperties` | CSS styles for the container |
+| `environment` | `string` | Load from a specific environment (e.g., `"staging"`) |
+| `preview` | `boolean` | Load the unpublished preview version |
+
+### Preloading Components
+
+Preloading fetches and caches component configs before they render, eliminating the network delay when the component mounts. This is useful for components that appear on user navigation or behind tabs — preload them early so they render instantly when needed.
+
+```tsx
+import { preloadComponents, isPreloaded } from "@myop/react";
+
+// Preload on app startup or route entry
+await preloadComponents(["component-id-1", "component-id-2"]);
+
+// Optionally preload for a specific environment
+await preloadComponents(["component-id-1"], "staging");
+
+// Check if a component is already cached
+if (isPreloaded("component-id-1")) {
+    console.log("Ready — will render without loading delay");
+}
+```
+
+**How it works:**
+- `preloadComponents(ids, env?, preview?)` fetches each component config from the Myop cloud and caches it in memory. Uses `Promise.allSettled` so a single failure doesn't block the rest.
+- When `<MyopComponent>` (or an auto-generated component) later mounts with a preloaded ID, it hits the cache and loads instantly — no network request, no loader flash.
+- The cache is keyed by `{componentId}:{environment}:{preview|live}`, so the same component can be preloaded for different environments separately.
+- If no explicit `environment`/`preview` props are passed to the component, it automatically uses the params from the preload call.
+
+**When to preload:**
+- App startup — preload components used on the landing page
+- Route transitions — preload components for the next likely page
+- Tab containers — preload all tab contents when the container mounts
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `preloadComponents(ids, env?, preview?)` | `Promise<PromiseSettledResult[]>` | Fetch and cache component configs ahead of time |
+| `isPreloaded(id, env?, preview?)` | `boolean` | Check if a component is already cached |
+| `getPreloadedParams(id)` | `{ env, preview } \| undefined` | Get the environment/preview params used during preload |

package/dist/skills/myop-component/references/dev-workflow.md

@@ -0,0 +1,218 @@
+# Development Workflow & CLI Commands
+
+The Myop CLI provides commands for creating, developing, and deploying components.
+
+## Contents
+- [CLI Installation](#cli-installation)
+- [Commands Reference](#commands-reference)
+- [Create Command](#create-command)
+- [Dev Command](#dev-command)
+- [Sync Command](#sync-command)
+- [Authentication](#authentication)
+- [Configuration](#configuration)
+
+## CLI Installation
+
+```bash
+npm install -g @myop/cli
+```
+
+After installation, the `myop` command is available globally.
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `myop create` | Create a new component (interactive, starts dev server after) |
+| `myop dev` | Start dev server with file watching and HMR |
+| `myop push` | Upload component to Myop platform |
+| `myop sync` | Build and upload component to Myop platform |
+| `myop login` | Authenticate with Myop (opens browser for OAuth) |
+| `myop logout` | Clear stored credentials |
+| `myop whoami` | Show current authenticated user |
+| `myop --ci` | Output status as JSON (for CI/CD) |
+| `myop -m` / `myop --monorepo` | Monorepo mode: scan and dev multiple components |
+
+## Create Command
+
+Creates a new Myop component in the current directory.
+
+```bash
+myop create
+```
+
+**What it does:**
+1. Prompts for component name (defaults to directory name)
+2. Checks that `index.html` and `myop.config.json` don't already exist
+3. Creates `myop.config.json` with component metadata
+4. Creates `index.html` with a complete component template
+5. Automatically starts the dev server
+
+**Files created (single-file mode):**
+```
+./index.html          # Complete Myop component
+./myop.config.json    # Component metadata
+```
+
+**Files created (full project scaffold, when no package.json exists):**
+```
+./index.html
+./myop.config.json
+./package.json
+./build.js            # esbuild bundler
+./src/index.js
+./src/modules/app.js
+./src/modules/myop.js
+./src/styles/index.css
+./src/styles/main.css
+./.gitignore
+```
+
+**Important:** If `index.html` or `myop.config.json` already exists, the command exits with an error. Use `myop dev` for existing components.
+
+## Dev Command
+
+Starts a development server with file watching.
+
+```bash
+myop dev
+```
+
+**Features:**
+- Main server on **port 9292**
+- Management dashboard on **port 9293**
+- Watches `.js` and `.css` files for changes
+- Auto-rebuilds when files change (if `build.js` or `package.json` build script exists)
+- Hot Module Replacement for instant preview updates
+- Single HTML file mode (no build step needed for `index.html`-only components)
+
+**URLs during development:**
+| URL | Purpose |
+|-----|---------|
+| `http://localhost:9292` | Dev server dashboard |
+| `http://localhost:9292/view/<componentId>/` | Preview your component |
+
+**Monorepo mode:**
+```bash
+myop dev -m
+```
+Scans for all `myop.config.json` files in nested directories and lets you select which components to run simultaneously.
+
+### Build Triggering
+
+The dev server detects changes and triggers builds automatically:
+- If `build.js` exists: runs `node build.js`
+- If `package.json` has a `build` script: runs `npm run build`
+- If only `index.html` exists (single-file mode): serves directly, no build needed
+
+## Push Command
+
+Uploads the component directly to the Myop platform (no build step).
+
+```bash
+myop push
+```
+
+**What it does:**
+1. Reads `myop.config.json`
+2. Finds the HTML file to upload (`index.html` in root for single-file mode, or `dist/index.html`)
+3. Authenticates (prompts for login if needed)
+4. Uploads HTML to Myop via presigned URL
+5. Confirms upload
+6. Updates `myop.config.json` with `componentId` (first push only)
+
+**After first push:**
+- `myop.config.json` gets a real `componentId` (UUID)
+- `organization` field is added
+- Component appears on the dashboard
+
+**Dashboard URL after push:**
+```
+https://dashboard.myop.dev/dashboard/2.0/component/<componentId>
+```
+
+## Sync Command
+
+Builds and uploads the component to the Myop platform (for multi-file projects with a build step).
+
+```bash
+myop sync
+```
+
+**What it does:**
+1. Reads `myop.config.json`
+2. Runs `npm run build`
+3. Verifies `dist/index.html` exists
+4. Authenticates (prompts for login if needed)
+5. Uploads `dist/index.html` to Myop via presigned URL
+6. Confirms upload
+7. Updates `myop.config.json` with `componentId` (first sync only)
+
+## Authentication
+
+### Login
+```bash
+myop login
+```
+Opens a browser window for OAuth authentication. Tokens are stored locally at `~/.myop/credentials.json`.
+
+### Logout
+```bash
+myop logout
+```
+Clears stored credentials.
+
+### Check Status
+```bash
+myop whoami
+```
+Displays the email of the currently authenticated user, or indicates if not logged in.
+
+### Token Storage
+- Location: `~/.myop/credentials.json`
+- Permissions: `0o600` (owner read/write only)
+- Tokens refresh automatically when expired
+
+## Configuration
+
+### myop.config.json
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Component display name |
+| `componentId` | `string` | `"DEV"` initially, UUID after first sync |
+| `type` | `string` | Always `"html"` |
+| `author` | `string` | `"@myop-cli"` by default |
+| `HMR` | `boolean` | Hot Module Replacement enabled |
+| `organization` | `string` | Organization ID (added after sync) |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MYOP_MCP_URL` | MCP server URL (default: `https://mcp.myop.dev`) |
+
+### CI/CD Mode
+
+```bash
+myop --ci
+```
+
+Outputs JSON with version, config status, and auth status. No interactive prompts.
+
+```json
+{
+  "version": "0.1.40",
+  "config": {
+    "found": true,
+    "path": "./myop.config.json",
+    "name": "My Component",
+    "componentId": "abc-123",
+    "organization": "org-456"
+  },
+  "auth": {
+    "loggedIn": true,
+    "email": "user@example.com"
+  }
+}
+```