@o2vend/theme-cli 1.0.32

package/README.md

@@ -0,0 +1,425 @@
+# O2VEND Theme CLI
+
+**Standalone command-line tool for developing O2VEND themes locally.**
+
+The O2VEND Theme CLI is a complete development environment for creating, testing, and packaging O2VEND themes. It works independently and doesn't require access to the main O2VEND webstore solution.
+
+## Installation
+
+Install globally via npm:
+
+```bash
+npm install -g @o2vend/theme-cli
+```
+
+Verify installation:
+
+```bash
+o2vend --version
+```
+
+## Quick Start
+
+### 1. Get Started with a Theme
+
+**Option A: Use the O2VEND Theme Starter (Recommended)**
+
+Clone the ready-to-use starter template:
+
+```bash
+git clone https://github.com/Jeyan-Technologies/o2vend-theme-starter.git
+cd o2vend-theme-starter
+npm run setup
+o2vend serve
+```
+
+**Option B: Create a New Theme**
+
+Initialize a new theme from scratch:
+
+```bash
+o2vend init my-theme
+cd my-theme
+o2vend serve
+```
+
+### 2. Start Development Server
+
+```bash
+o2vend serve
+```
+
+This will:
+- Start a local development server at `http://localhost:3000`
+- Launch a mock API server for testing
+- Enable hot reload for instant preview
+- Open your browser automatically
+
+## Commands
+
+### `serve`
+
+Start development server with hot reload:
+
+```bash
+o2vend serve [options]
+
+Options:
+  -m, --mode <mode>           API mode (mock|real) [default: mock]
+  -p, --port <port>           Server port [default: 3000]
+  --host <host>               Server host [default: localhost]
+  -t, --theme <themePath>     Path to theme directory [default: current]
+  -e, --env <envFile>         Path to .env file [default: .env]
+  --open                       Open browser automatically [default: true]
+  --no-open                   Don't open browser
+  --mock-api-port <port>      Mock API port [default: 3001]
+```
+
+**Examples:**
+```bash
+# Start in mock mode (default) - works offline
+o2vend serve
+
+# Connect to real O2VEND API
+o2vend serve --mode real
+
+# Custom port
+o2vend serve --port 8080
+
+# Don't open browser automatically
+o2vend serve --no-open
+```
+
+### `init <name>`
+
+Initialize a new theme project:
+
+```bash
+o2vend init my-theme
+```
+
+Creates a new theme directory with:
+- Complete theme structure (templates, sections, widgets, assets)
+- Configuration files (`settings_schema.json`, `settings_data.json`)
+- Example templates and widgets
+- VS Code configuration
+- `.env` file template
+
+### `validate`
+
+Validate theme structure and configuration:
+
+```bash
+o2vend validate
+```
+
+Checks for:
+- Required theme files and directories
+- Valid Liquid syntax
+- Proper theme structure
+- Configuration file validity
+- Widget template compatibility
+
+### `check`
+
+Check theme for issues and best practices:
+
+```bash
+o2vend check
+```
+
+Performs various checks:
+- Syntax errors in Liquid templates
+- Missing required files
+- Performance issues
+- Accessibility concerns
+- Best practice violations
+
+### `optimize`
+
+Analyze and optimize theme performance:
+
+```bash
+o2vend optimize
+```
+
+Provides analysis for:
+- CSS file sizes
+- JavaScript file sizes
+- Image optimization opportunities
+- Asset bundling recommendations
+- Performance metrics
+
+### `package`
+
+Package theme for O2VEND marketplace submission:
+
+```bash
+o2vend package [options]
+
+Options:
+  -o, --output <path>         Output ZIP file path [default: dist/theme.zip]
+  --validate                   Run validation before packaging
+  --theme-id <id>             Theme ID for theme.json
+  --theme-name <name>         Theme name for theme.json
+  --theme-version <version>   Theme version for theme.json
+  --author <author>           Author name for theme.json
+  --description <description> Theme description for theme.json
+```
+
+Creates a marketplace-ready ZIP file with:
+- `theme.json` manifest (auto-generated if missing)
+- All theme files
+- Optional `migrations` folder
+- Proper file structure
+
+## Environment Variables
+
+Create a `.env` file in your theme directory:
+
+```env
+# API Configuration (for real API mode)
+O2VEND_TENANT_ID=your-tenant-id
+O2VEND_API_KEY=your-api-key
+O2VEND_API_BASE_URL=https://api.o2vend.com
+
+# Development Server
+PORT=3000
+HOST=localhost
+MOCK_API_PORT=3001
+
+# Options
+OPEN_BROWSER=true
+DEBUG_API_ERRORS=false
+```
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `O2VEND_TENANT_ID` | Tenant ID (real mode) | - |
+| `O2VEND_API_KEY` | API Key (real mode) | - |
+| `O2VEND_API_BASE_URL` | API Base URL (real mode) | - |
+| `PORT` | Development server port | `3000` |
+| `HOST` | Development server host | `localhost` |
+| `MOCK_API_PORT` | Mock API server port | `3001` |
+| `OPEN_BROWSER` | Auto-open browser | `true` |
+| `DEBUG_API_ERRORS` | Debug API errors | `false` |
+
+## Features
+
+### Hot Reload
+
+Automatic browser refresh on file changes:
+- **CSS changes** - Injected without page reload
+- **Liquid/JS changes** - Full page reload
+- **File watching** - Automatic change detection
+- **WebSocket-based** - Real-time updates
+
+### Mock API
+
+Built-in mock API provides realistic test data for offline development:
+- Products (20+ sample items)
+- Categories (10+ sample items)
+- Brands (8+ sample items)
+- Widgets (multiple sections: hero, products, footer)
+- Store information
+- Shopping cart simulation
+
+Perfect for:
+- Developing themes without API access
+- Testing theme layouts
+- Prototyping new designs
+- Learning O2VEND theme structure
+
+### Real API Mode
+
+Connect to actual O2VEND Storefront API:
+- Full API compatibility
+- Authentication support
+- Widget loading from API
+- Real-time data from your tenant
+- Product, category, and brand data
+
+### Theme Structure
+
+O2VEND themes follow a specific structure:
+
+```
+theme/
+├── layout/
+│   └── theme.liquid          # Main layout template
+├── templates/
+│   ├── index.liquid          # Homepage
+│   ├── product.liquid        # Product page
+│   ├── collection.liquid    # Collection page
+│   └── ...
+├── sections/
+│   ├── header.liquid
+│   ├── footer.liquid
+│   └── ...
+├── widgets/
+│   ├── product.liquid
+│   ├── banner.liquid
+│   └── ...
+├── snippets/
+│   └── ...
+├── assets/
+│   ├── theme.css
+│   ├── theme.js
+│   └── ...
+└── config/
+    ├── settings_schema.json
+    └── settings_data.json
+```
+
+**Important:** Templates, sections, and widgets are **predefined by O2VEND** and come from the O2VEND Storefront API. You can customize existing files but **cannot create new templates, sections, or widget types**.
+
+## Usage Examples
+
+### Development Workflow
+
+```bash
+# 1. Start development server
+o2vend serve
+
+# 2. Make changes to theme files
+# Edit templates, sections, widgets, or assets
+
+# 3. Validate theme structure
+o2vend validate
+
+# 4. Check for issues
+o2vend check
+
+# 5. Optimize assets
+o2vend optimize
+
+# 6. Package for marketplace
+o2vend package
+```
+
+### Connecting to Real API
+
+```bash
+# Create .env file
+cat > .env << EOF
+O2VEND_TENANT_ID=your-tenant-id
+O2VEND_API_KEY=your-api-key
+O2VEND_API_BASE_URL=https://api.o2vend.com
+EOF
+
+# Start server in real mode
+o2vend serve --mode real
+```
+
+### Custom Theme Development
+
+```bash
+# Create new theme
+o2vend init my-custom-theme
+
+# Navigate to theme
+cd my-custom-theme
+
+# Start development
+o2vend serve
+
+# Customize theme files
+# Edit theme/layout/theme.liquid
+# Edit theme/templates/index.liquid
+# Edit theme/assets/theme.css
+
+# Validate and package
+o2vend validate
+o2vend package
+```
+
+## Theme Development Guidelines
+
+### Customizing Templates
+
+Modify files in `theme/templates/` to change page layouts. For example:
+- `templates/index.liquid` - Homepage
+- `templates/product.liquid` - Product detail page
+- `templates/collection.liquid` - Collection listing page
+
+**Note:** All templates are provided by O2VEND. You can customize them but cannot create new ones.
+
+### Customizing Sections
+
+Modify files in `theme/sections/` to change reusable content blocks:
+- `sections/header.liquid` - Site header
+- `sections/footer.liquid` - Site footer
+- `sections/hero.liquid` - Hero banner section
+
+**Note:** All sections are provided by O2VEND. You can customize them but cannot create new ones.
+
+### Customizing Widgets
+
+Modify files in `theme/widgets/` to change how dynamic content components are rendered:
+- `widgets/product.liquid` - Product display widget
+- `widgets/banner.liquid` - Banner widget
+- `widgets/carousel.liquid` - Carousel widget
+
+**Note:** Widget templates are provided by O2VEND. Widgets themselves are managed through the O2VEND admin panel and loaded via the Storefront API. You can customize widget templates but cannot create new widget types.
+
+### Customizing Assets
+
+Modify files in `theme/assets/` for CSS, JavaScript, and images:
+- `assets/theme.css` - Main stylesheet
+- `assets/theme.js` - Main JavaScript
+- `assets/components.css` - Component styles
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Use a different port
+o2vend serve --port 8080
+```
+
+### Layout Not Found Error
+
+Make sure your templates use the correct layout path:
+```liquid
+{% layout 'layout/theme' %}
+```
+
+The layout file should be at: `theme/layout/theme.liquid`
+
+### API Connection Issues
+
+If using real API mode:
+1. Verify `.env` file has correct credentials
+2. Check API base URL is correct
+3. Ensure tenant ID and API key are valid
+4. Try mock mode first: `o2vend serve --mode mock`
+
+### Hot Reload Not Working
+
+1. Check browser console for WebSocket errors
+2. Verify firewall isn't blocking WebSocket connections
+3. Try refreshing the page manually
+4. Restart the server: `o2vend serve`
+
+## Support & Resources
+
+- **[O2VEND Developer Documentation](https://o2vend.com/developer/)** - Complete API documentation and guides
+- **Support Email:** support@o2vend.com or developer@jeyantechnologies.com
+- **Support Desk:** [O2VEND Support Portal](https://o2vend.atlassian.net/servicedesk/customer/portals)
+- **Community:** [O2VEND Community Program](https://o2vend.com/community)
+- **Partnership:** [O2VEND Partnership Program](https://o2vend.com/partnership)
+- **Developer Portal:** [www.o2vend.com](https://www.o2vend.com)
+
+## Related Tools
+
+- **[O2VEND Theme Starter](https://github.com/Jeyan-Technologies/o2vend-theme-starter)** - Ready-to-use starter template with complete default theme
+- **[O2VEND Liquid VS Code Extension](https://marketplace.visualstudio.com/items?itemName=O2VEND.o2vend-liquid)** - Syntax highlighting and IntelliSense for O2VEND Liquid templates
+
+## License
+
+MIT License - See LICENSE file
+
+---
+
+**Ready to build amazing O2VEND themes?** Start with the [O2VEND Theme Starter](https://github.com/Jeyan-Technologies/o2vend-theme-starter) or create your own with `o2vend init`!

package/bin/o2vend

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * O2VEND Theme CLI Entry Point
+ */
+
+const { program } = require('commander');
+const path = require('path');
+const fs = require('fs');
+
+// For development: use src/ if it exists, otherwise use lib/
+const srcDir = path.join(__dirname, '../src');
+const libDir = path.join(__dirname, '../lib');
+const commandsDir = fs.existsSync(path.join(srcDir, 'commands')) ? srcDir : libDir;
+
+const initCommand = require(path.join(commandsDir, 'commands/init'));
+const serveCommand = require(path.join(commandsDir, 'commands/serve'));
+const validateCommand = require(path.join(commandsDir, 'commands/validate'));
+const checkCommand = require(path.join(commandsDir, 'commands/check'));
+const generateCommand = require(path.join(commandsDir, 'commands/generate'));
+const optimizeCommand = require(path.join(commandsDir, 'commands/optimize'));
+const packageCommand = require(path.join(commandsDir, 'commands/package'));
+
+const packageJson = require('../package.json');
+
+program
+  .name('o2vend')
+  .description('O2VEND Theme Development CLI')
+  .version(packageJson.version);
+
+// Add commands directly (no nested 'theme' command)
+program
+  .addCommand(initCommand)
+  .addCommand(serveCommand)
+  .addCommand(validateCommand)
+  .addCommand(checkCommand)
+  .addCommand(generateCommand)
+  .addCommand(optimizeCommand)
+  .addCommand(packageCommand);
+
+program.parse();
+

package/config/widget-map.json

@@ -0,0 +1,50 @@
+{
+  "BannerWidget": "carousel",
+  "Banner": "carousel",
+  "BrandWidget": "brand",
+  "Brand": "brand",
+  "BrandWidgetCarousel": "brand-carousel",
+  "BrandCarousel": "brand-carousel",
+  "CarouselWidget": "carousel",
+  "Carousel": "carousel",
+  "CategoryListCarouselWidget": "category-list-carousel",
+  "CategoryListCarousel": "category-list-carousel",
+  "CategoryListWidget": "category-list",
+  "CategoryList": "category-list",
+  "CategoryWidget": "category",
+  "Category": "category",
+  "DiscountTimeWidget": "discount-time",
+  "DiscountTime": "discount-time",
+  "FooterWidget": "footer",
+  "FooterMenu": "footer-menu",
+  "GalleryWidget": "gallery",
+  "Gallery": "gallery",
+  "HeaderWidget": "header",
+  "HeaderMenu": "header-menu",
+  "HtmlWidget": "html",
+  "Html": "html",
+  "NewsWidget": "news",
+  "News": "news",
+  "ProductCanvasWidget": "product-canvas",
+  "ProductCanvas": "product-canvas",
+  "ProductCarouselWidget": "product-carousel",
+  "ProductCarousel": "product-carousel",
+  "ProductGridWidget": "product-grid",
+  "ProductGrid": "product-grid",
+  "ProductWidget": "product",
+  "Product": "product",
+  "RecentlyViewedWidget": "recently-viewed",
+  "RecentlyViewed": "recently-viewed",
+  "SimpleProductWidget": "simple-product",
+  "SimpleProduct": "simple-product",
+  "SingleProductWidget": "single-product",
+  "SingleProduct": "single-product",
+  "SpaceBarWidget": "spacebar",
+  "SpaceBar": "spacebar",
+  "SpaceBarWidgetCarousel": "spacebar-carousel",
+  "SpaceBarCarousel": "spacebar-carousel",
+  "SplashWidget": "splash",
+  "Splash": "splash",
+  "TestimonialCarousel": "testimonial-carousel"
+}
+