qumra-cli 2.1.0 → 2.4.2

package/.claude/settings.local.json

@@ -23,7 +23,14 @@
       "Bash(git commit -m \"$\\(cat <<''EOF''\nfeat: Replace qumra-engine with local proxy server\n\n- Add ThemeProxyService for proxying requests to store URL\n- Add ThemeHotReloadService for WebSocket-based live reload\n- Add ThemeAssetMapperService for mapping CDN URLs to local files\n- Update ThemeWatcherService with file change callback\n- Remove qumra-engine dependency\n- Add http-proxy-middleware and cheerio dependencies\n\nThis implements a Shopify-style development experience where:\n- Local assets \\(CSS, JS, images\\) are served from the theme folder\n- HTML responses are rewritten to use local asset URLs\n- CSS changes are hot-swapped without full page reload\n- Other changes trigger full page reload\n- All files are still uploaded to server for SSR\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
       "Bash(npm version:*)",
       "Bash(npm publish)",
-      "Bash(npm publish:*)"
+      "Bash(npm publish:*)",
+      "Bash(DEBUG=*)",
+      "Bash(npm link:*)",
+      "Bash(git commit:*)",
+      "Bash(git checkout:*)",
+      "Bash(git clean:*)",
+      "Bash(git merge:*)",
+      "Bash(git branch:*)"
     ]
   }
 }

package/CLAUDE.md

@@ -30,6 +30,7 @@ src/
 │   ├── config/         # ConfigService - project-level .qumra/qumra.config.json
 │   ├── storage/        # StorageService - user-level ~/.config/qumra-cli/
 │   ├── logger/         # LoggerService - formatted console output with chalk
+│   │   └── blessed-ui.ts # BlessedUI - Terminal UI with panels and shortcuts
 │   ├── graphql/        # GraphqlService - graphql-request wrapper with auth
 │   ├── tunnel/         # TunnelService - cloudflared tunnel management
 │   └── constants.ts    # API endpoints and constants
@@ -57,9 +58,182 @@ src/
 ## External Services
 
 - GraphQL API: `https://api.qumra.cloud/graphql`
+- REST Upload API: `https://api.qumra.cloud/v1/upload`
 - Realtime WebSocket: `wss://realtime.qumra.cloud`
 - Login Portal: `https://app.qumra.cloud/auth/login`
+- Theme Editor: `https://app.qumra.cloud/store/{subdomain}/themes/{appThemeId}`
 
 ## Build Configuration
 
 Rollup bundles `src/main.ts` into `dist/cli.js` as CommonJS with shebang. External packages: qumra-engine, NestJS packages, fsevents.
+
+---
+
+## Theme Dev Command (`qumra theme dev`)
+
+### Overview
+
+The theme dev command starts a local development server for theme development with:
+- Proxy server to forward requests to the store
+- Hot reload for live updates
+- File watcher for syncing changes
+- BlessedUI for terminal interface
+
+### Flow
+
+1. Load `qumra.config.json` to get `themeVersionId`
+2. Show store selection (inquirer prompt)
+3. Install theme on store via `installTheme` mutation → returns `appTheme._id`
+4. Start hot reload WebSocket server
+5. Start proxy server
+6. Start BlessedUI terminal interface
+7. Start file watcher
+
+### Key IDs
+
+- `themeId` - The theme's unique ID (from qumra.config.json)
+- `themeVersionId` - The specific version ID (from qumra.config.json)
+- `appTheme._id` - Returned from `installTheme` mutation, used for:
+  - Proxy header: `X-Qumra-App-Theme`
+  - Theme Editor URL
+  - File sync operations
+
+### Services Architecture
+
+#### ThemeProxyService (`theme-proxy.service.ts`)
+
+Express server that:
+- Serves local `/assets` from theme folder
+- Proxies all other requests to store URL
+- Adds headers:
+  - `X-Qumra-Dev-Mode: true`
+  - `X-Qumra-App-Theme: {appTheme._id}`
+- Injects hot reload script into HTML responses
+- Adds dev mode indicator badge
+
+**Important**: Don't rewrite asset URLs in HTML - just serve `/assets` locally and let backend URLs pass through unchanged.
+
+#### ThemeWatcherService (`theme-watcher.service.ts`)
+
+File watcher using chokidar with different sync handlers per folder:
+
+| Folder | File Type | Sync Method | Endpoint |
+|--------|-----------|-------------|----------|
+| `assets` | all | CDN Presigned URL | GraphQL `CdnPresignedUrl` → upload to presigned URL |
+| `layouts` | `.njk` | REST Upload | `POST /v1/upload` |
+| `templates` | `.njk` | REST Upload | `POST /v1/upload` |
+| `ui` | `.njk`, `.css` | REST Upload | `POST /v1/upload` |
+| `locales` | `.json` | REST Upload | `POST /v1/upload` |
+| `widgets` | `.njk` | REST Upload | `POST /v1/upload` |
+| `widgets` | `.json` | GraphQL | `SyncWidget` mutation |
+| `pages` | `.json` | GraphQL | `SyncThemePage` mutation |
+| `settings` | `.json` | GraphQL | `UpdateThemeVersionSettings` mutation |
+
+**Features**:
+- 300ms debounce to prevent rapid consecutive syncs
+- No initial sync on startup (only watches for changes)
+- Different handlers based on file type and folder
+
+#### ThemeHotReloadService (`theme-hot-reload.service.ts`)
+
+WebSocket server (Socket.IO) for live reload:
+- Listens for file changes from watcher
+- Notifies connected browsers
+- CSS changes: hot swap without page reload
+- Other changes: full page reload
+
+**Client Script**: Injected into HTML before `</body>`:
+```html
+<script src="https://cdn.socket.io/4.6.0/socket.io.min.js"></script>
+<script>
+(function() {
+  var socket = io('http://localhost:{port}');
+  socket.on('file-change', function(event) {
+    if (event.type === 'css') {
+      // Hot swap CSS
+    } else {
+      window.location.reload();
+    }
+  });
+})();
+</script>
+```
+
+**Important**: Socket.IO library must be loaded BEFORE the client script that uses it.
+
+### BlessedUI (`blessed-ui.ts`)
+
+Terminal UI using `blessed` library:
+- Info box with theme/store details and URLs
+- Log panel for sync/proxy activity
+- Footer with keyboard shortcuts (q: quit, o: open browser, s: open store, e: theme editor)
+
+**Gotchas**:
+- Must set `mouse: false` to prevent click-exit issues
+- Don't use `console.log` after BlessedUI starts (interferes with terminal control)
+- Wait ~100ms after inquirer prompt before starting BlessedUI (stdin release)
+
+### GraphQL Mutations
+
+```graphql
+# Install theme on store
+mutation InstallTheme($input: InstallThemeInput!) {
+  installTheme(input: $input) {
+    _id  # This is appTheme._id
+  }
+}
+
+# Sync page
+mutation SyncThemePage($input: SyncThemePageInput!) {
+  syncThemePage(input: $input) { success message }
+}
+
+# Sync widget schema
+mutation SyncWidget($input: SyncWidgetInput!) {
+  syncWidget(input: $input) { success message }
+}
+
+# Update settings
+mutation UpdateThemeVersionSettings($input: UpdateThemeVersionSettingsInput!) {
+  updateThemeVersionSettings(input: $input) { success message }
+}
+
+# Get CDN presigned URL for assets
+mutation CdnPresignedUrl($cdnPresignedInput: CdnPresignedInput!) {
+  cdnPresignedUrl(cdnPresignedInput: $cdnPresignedInput) {
+    success message presignedUrl
+  }
+}
+```
+
+### Settings Files
+
+The `settings/` folder has specific JSON files:
+- `settings-schema.json` - Theme settings schema
+- `settings-data.json` - Theme settings values
+- `header-schema.json` - Header settings schema
+- `header-data.json` - Header settings values
+- `footer-schema.json` - Footer settings schema
+- `footer-data.json` - Footer settings values
+- `templates-settings.json` - Templates configuration
+
+---
+
+## App Dev Command (`qumra app dev`)
+
+Similar to theme dev but:
+- Uses cloudflared tunnel for HTTPS
+- Spawns `npx react-router dev` child process
+- Updates app's `developmentUrl` on backend
+
+---
+
+## Reference: Old CLI (`../qumra-cli`)
+
+The new NestJS CLI should match the old CLI's behavior. Key reference files:
+- `src/services/themes/watcher/` - File sync handlers
+- `src/utils/uploadFileToServer.ts` - REST upload to `/v1/upload`
+- `src/utils/uploadFileToCdnPresignedUrl.ts` - CDN upload via presigned URL
+- `src/utils/syncThemePage.ts` - GraphQL page sync
+- `src/utils/syncWidgetSchema.ts` - GraphQL widget sync
+- `src/utils/syncThemeVersionSettings.ts` - GraphQL settings sync