@qumra/cli 2.4.13 → 2.4.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Qumra Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @qumra/cli
+
+Official CLI for [Qumra Cloud](https://qumra.cloud) — build, develop, and deploy themes and apps for your e-commerce store.
+
+## Installation
+
+```bash
+npm install -g @qumra/cli
+```
+
+## Quick Start
+
+```bash
+# Login to your Qumra Cloud account
+qumra login
+
+# Initialize a new theme project
+qumra theme init
+
+# Start local development server with hot reload
+qumra theme dev
+
+# Publish your theme
+qumra theme publish
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `qumra login` | Login to your Qumra Cloud account |
+| `qumra logout` | Logout from your account |
+| `qumra info` | Show current user info |
+
+### Themes
+
+| Command | Description |
+|---------|-------------|
+| `qumra theme init` | Initialize a new theme project |
+| `qumra theme dev` | Start local development server with hot reload |
+| `qumra theme publish` | Publish theme to Qumra Cloud |
+| `qumra theme bundle` | Bundle theme for distribution |
+| `qumra theme patch` | Bump patch version and publish |
+| `qumra theme minor` | Bump minor version and publish |
+| `qumra theme major` | Bump major version and publish |
+
+### Apps
+
+| Command | Description |
+|---------|-------------|
+| `qumra app init` | Initialize a new app project |
+| `qumra app dev` | Start local development server with tunnel |
+| `qumra app deploy` | Deploy app to Qumra Cloud |
+
+### Generators
+
+| Command | Description |
+|---------|-------------|
+| `qumra generate widget` | Scaffold a new widget |
+
+## Theme Development
+
+Running `qumra theme dev` starts a local development environment with:
+
+- **Proxy server** — forwards requests to your store with local asset overrides
+- **Hot reload** — CSS changes apply instantly, other changes trigger a full reload
+- **File watcher** — automatically syncs file changes to the cloud
+
+## Requirements
+
+- Node.js >= 18
+
+## Documentation
+
+Full documentation is available at [docs.qumra.cloud](https://docs.qumra.cloud/docs/cli/intro).
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -304360,7 +304360,7 @@ class SectionBuilder {
     }
 }
 
-var version$2 = "2.4.13";
+var version$2 = "2.4.15";
 var pkg = {
 	version: version$2};
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qumra/cli",
-  "version": "2.4.13",
-  "description": "Professional CLI tool for Qumra Cloud - Shopify competitor",
+  "version": "2.4.15",
+  "description": "Official CLI for Qumra Cloud e-commerce platform. Build, develop, and deploy themes and apps.",
   "main": "dist/cli.js",
   "bin": {
     "qumra": "dist/cli.js"
@@ -21,8 +21,25 @@
     "release:major": "npm run build && npm version major && npm publish",
     "prepublishOnly": "npm run build"
   },
-  "author": "",
+  "homepage": "https://docs.qumra.cloud/docs/cli/intro",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "qumra",
+    "cli",
+    "ecommerce",
+    "ecommerce-platform",
+    "theme",
+    "storefront",
+    "headless-commerce",
+    "graphql"
+  ],
+  "author": "Qumra <support@qumra.cloud> (https://qumra.cloud)",
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@inquirer/search": "^4.1.0",
     "@nestjs/common": "^11.1.12",
@@ -30,8 +47,6 @@
     "@nestjs/microservices": "^11.1.12",
     "@nestjs/platform-express": "^11.1.12",
     "@nestjs/websockets": "^11.1.12",
-    "@types/blessed": "^0.1.27",
-    "@types/figlet": "^1.7.0",
     "archiver": "^7.0.1",
     "axios": "^1.10.0",
     "blessed": "^0.1.81",
@@ -42,7 +57,6 @@
     "cli-progress": "^3.12.0",
     "cli-table3": "^0.6.5",
     "cloudflared": "^0.7.1",
-    "commander": "^11.0.0",
     "conf": "^14.0.0",
     "express": "^4.18.2",
     "fast-glob": "^3.3.3",
@@ -69,6 +83,8 @@
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^11.0.0",
     "@types/archiver": "^7.0.0",
+    "@types/blessed": "^0.1.27",
+    "@types/figlet": "^1.7.0",
     "@types/cli-progress": "^3.11.6",
     "@types/conf": "^2.1.0",
     "@types/express": "^4.17.21",

package/.claude/settings.local.json

@@ -1,36 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(tree:*)",
-      "Bash(npm install:*)",
-      "Bash(npx ts-node:*)",
-      "Bash(node --loader ts-node/esm --experimental-specifier-resolution=node -r ts-node/register src/main.ts:*)",
-      "Bash(node -r ts-node/register src/main.ts:*)",
-      "Bash(npx tsx:*)",
-      "Bash(npm run build:*)",
-      "Bash(npx rollup:*)",
-      "Bash(npm uninstall:*)",
-      "Bash(./dist/cli.js:*)",
-      "Bash(node:*)",
-      "Bash(npm run start:*)",
-      "Bash(npm run dev:*)",
-      "Bash(npx tsc:*)",
-      "Bash(sudo rm:*)",
-      "Bash(npm ls:*)",
-      "Bash(ls:*)",
-      "Bash(npm run release:minor:*)",
-      "Bash(git add:*)",
-      "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(DEBUG=*)",
-      "Bash(npm link:*)",
-      "Bash(git commit:*)",
-      "Bash(git checkout:*)",
-      "Bash(git clean:*)",
-      "Bash(git merge:*)",
-      "Bash(git branch:*)"
-    ]
-  }
-}

package/CLAUDE.md

@@ -1,239 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Qumra CLI is a command-line tool for Qumra Cloud (e-commerce platform). Built with NestJS and nest-commander, bundled with Rollup, distributed as an npm package (`qumra-cloud`).
-
-## Common Commands
-
-```bash
-npm run dev           # Run source directly with tsx (recommended for development)
-npm run dev:watch     # Watch mode with tsx
-npm run build         # Clean and build with Rollup into dist/cli.js
-npm run build:watch   # Watch mode for Rollup builds
-npm run link          # Build and link globally for local testing
-npm start             # Run pre-built dist/cli.js
-```
-
-No lint or test commands are configured.
-
-## Architecture
-
-```
-src/
-├── main.ts              # CLI bootstrap with nest-commander CommandFactory
-├── app.module.ts        # Root module importing all feature modules
-├── common/              # Global shared services (@Global module)
-│   ├── auth/           # AuthService - token storage via StorageService
-│   ├── 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
-└── modules/            # Feature modules
-    ├── user/           # login, logout, info commands
-    ├── theme/          # init, dev, publish, bundle, patch/minor/major commands
-    ├── app/            # init, dev, deploy commands
-    └── generate/       # widget scaffolding command
-```
-
-## Key Patterns
-
-**Command Structure**: Commands extend `CommandRunner` from nest-commander. Commands are thin wrappers that delegate to services for business logic.
-
-**Service Injection**: All services use constructor injection with `@Injectable()`. CommonModule is `@Global()` so its services (Logger, Auth, Config, Storage, GraphQL, Tunnel) are available everywhere.
-
-**Configuration**:
-- Project config: `.qumra/qumra.config.json` (via ConfigService)
-- User config: `~/.config/qumra-cli/` (via StorageService using `conf` package)
-
-**API Communication**: GraphqlService wraps graphql-request and auto-injects auth token from AuthService.
-
-**File Watching**: ThemeWatcherService uses chokidar for live sync during `theme dev`.
-
-## 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

package/tsconfig.dev.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2019",
-    "module": "CommonJS",
-    "moduleResolution": "Node",
-    "outDir": "dist",
-    "rootDir": "src",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "allowSyntheticDefaultImports": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  },
-  "include": ["src/**/*"],
-  "ts-node": {
-    "esm": false
-  }
-}