@onexapis/cli 1.0.0 → 1.0.2

package/README.md

@@ -1,330 +1,333 @@
-# @duongthiu/onex-cli
+# @onexapis/cli
 
-CLI tool for OneX theme development - scaffold themes, sections, blocks, and components with ease.
-
-Uses `@duongthiu/onex-core` for the core theme system.
+CLI tool for OneX theme development — scaffold, build, validate, and deploy themes using `@onexapis/core`.
 
 ## Installation
 
 ```bash
-# Install in your OneX project
-npm install -D @duongthiu/onex-cli
-
-# Or use globally
-npm install -g @duongthiu/onex-cli
+# Install globally
+npm install -g @onexapis/cli
 
-# Or use via npx
-npx @duongthiu/onex-cli <command>
+# Or within the monorepo
+cd packages/cli
+pnpm build
+npm install -g .
 ```
 
-## Commands
+Requires Node.js >= 18.
 
-### `onex init [theme-name]`
+## Quick Start
 
-Initialize a new OneX theme with complete structure.
+```bash
+# Create a new theme project
+onex init my-theme
 
-**Options:**
+# List all themes, sections, blocks, and components
+onex list
 
-- `-t, --template <template>` - Template to use (default, minimal)
+# Create a section in a theme
+onex create:section hero --theme simple
 
-**Example:**
+# Validate theme structure
+onex validate --theme simple
 
-```bash
-onex init my-theme
-onex init my-store -t ecommerce
-```
+# Build a theme
+onex build --theme simple
 
-**Generated structure:**
+# Upload to S3
+onex upload --theme simple
 
-```
-src/themes/my-theme/
-├── manifest.ts           # Theme metadata and exports
-├── theme.config.ts       # Design tokens (colors, typography, spacing)
-├── theme.layout.ts       # Header/footer configuration
-├── index.ts              # Main exports
-├── sections/             # Theme-specific sections
-├── blocks/               # Theme-specific blocks
-└── pages/
-    └── home.ts           # Default home page config
+# Clone a theme from S3
+onex clone simple
 ```
 
-### `onex create:section <name>` (alias: `cs`)
+## Commands
 
-Create a new section with schema and template files.
+### `onex init [project-name]`
 
-**Options:**
+Create a new OneX theme project from a template.
 
-- `-t, --theme <theme>` - Theme to create section in
-- `-c, --category <category>` - Section category (headers, content, footers, etc.)
-- `--template <template>` - Initial template variant
+| Option | Description |
+|---|---|
+| `-t, --template <template>` | Template to use (`default`, `minimal`) |
+| `--no-install` | Skip installing dependencies |
+| `--git` | Initialize a git repository |
+| `-y, --yes` | Skip prompts and use defaults |
 
-**Example:**
+### `onex create:section <name>` (alias: `cs`)
 
-```bash
-onex create:section hero -t my-theme -c heroes
-onex cs featured-products -t my-store -c ecommerce
-```
+Scaffold a new section inside a theme.
 
-**Generated files:**
+| Option | Description |
+|---|---|
+| `-t, --theme <theme>` | Target theme |
+| `-c, --category <category>` | Section category (`headers`, `content`, `footers`) |
+| `--template <template>` | Initial template variant (`default`, `minimal`) |
 
-```
-src/themes/my-theme/sections/hero/
-├── hero.schema.ts        # Section schema with settings
-├── hero-default.tsx      # Default template component
-└── index.ts              # Exports
+```bash
+onex create:section hero -t my-theme -c heroes
+onex cs featured-products -t my-store
 ```
 
 ### `onex create:block <name>` (alias: `cb`)
 
-Create a new block component (shared or theme-specific).
-
-**Options:**
+Scaffold a new block.
 
-- `-t, --theme <theme>` - Theme to create block in (optional, defaults to shared)
-
-**Example:**
+| Option | Description |
+|---|---|
+| `-t, --theme <theme>` | Target theme (optional) |
 
 ```bash
 onex create:block product-card
 onex cb testimonial-item -t my-theme
 ```
 
-**Generated files:**
-
-```
-src/features/blocks/product-card/
-├── product-card.schema.ts    # Block schema with settings
-├── product-card.tsx          # Block component
-└── index.ts                  # Exports
-```
-
 ### `onex create:component <name>` (alias: `cc`)
 
-Create a new UI component.
-
-**Options:**
+Scaffold a new UI component.
 
-- `-t, --type <type>` - Component type (ui, form, layout, content)
-
-**Example:**
+| Option | Description |
+|---|---|
+| `-t, --type <type>` | Component type (`ui`, `layout`, `form`) |
 
 ```bash
 onex create:component icon-badge
 onex cc custom-input -t form
 ```
 
-**Generated files:**
+### `onex list`
 
-```
-src/features/components/icon-badge/
-├── icon-badge.schema.ts      # Component schema with content/style fields
-├── icon-badge.tsx            # Component implementation
-└── index.ts                  # Exports
-```
+List available themes, sections, blocks, and components in the project.
 
-### `onex list`
+| Option | Description |
+|---|---|
+| `-s, --sections` | List sections only |
+| `-b, --blocks` | List blocks only |
+| `-c, --components` | List components only |
+| `-t, --theme <theme>` | Filter by theme |
 
-Display project inventory (themes, sections, blocks, components).
+### `onex validate`
 
-**Options:**
+Validate theme structure and files.
 
-- `-s, --sections` - List sections only
-- `-b, --blocks` - List blocks only
-- `-c, --components` - List components only
-- `-t, --theme <theme>` - Filter by theme
+| Option | Description |
+|---|---|
+| `-t, --theme <theme>` | Theme to validate |
+| `-f, --fix` | Auto-fix issues (not yet implemented) |
 
-**Example:**
+### `onex build`
 
-```bash
-onex list
-onex list -s -t my-theme
-onex list --blocks
-```
+Build a theme for production. Runs type-check, lint, and compilation.
 
-## Features
+| Option | Description |
+|---|---|
+| `-t, --theme <theme>` | Theme to build |
+| `-p, --production` | Production build with optimizations |
+| `-w, --watch` | Watch mode for development |
 
-### Interactive Prompts
+> **Note:** The theme's `package.json` must have `type-check` and `lint` scripts for the build to pass. Example:
+> ```json
+> { "scripts": { "type-check": "tsc --noEmit", "lint": "eslint src" } }
+> ```
 
-All commands feature interactive prompts for missing options:
+### `onex package`
 
-- Theme selection from available themes
-- Category selection with validation
-- Display names and descriptions
-- Template preferences
+Compile and package a theme as a distributable zip file.
 
-### Validation
+| Option | Description |
+|---|---|
+| `-t, --theme <theme>` | Theme to package |
+| `-o, --output <dir>` | Output directory |
+| `-n, --name <name>` | Custom package name |
+| `-m, --minify` | Minify compiled output |
+| `--skip-build` | Skip compilation, use existing compiled theme |
 
-- **Name Validation**: Ensures kebab-case format (e.g., `my-section`, `product-card`)
-- **Theme Validation**: Checks theme existence before creating sections/blocks
-- **Category Validation**: Validates against predefined categories
-- **Project Detection**: Ensures commands run within a OneX project
+### `onex deploy`
 
-### Smart Templates
+Upload a theme package to the API server.
 
-Generated files include:
+| Option | Description |
+|---|---|
+| `-t, --theme <theme>` | Theme to deploy |
+| `-p, --package <file>` | Specific package file to upload |
+| `--api-url <url>` | API server URL (default: `http://localhost:3001`) |
+| `-k, --api-key <key>` | API key for authentication |
+| `-e, --environment <env>` | Environment (`production`, `staging`, `development`) |
 
-- Proper TypeScript types from `@onex/core`
-- Best practice component structure
-- Commented TODOs for customization
-- Responsive design patterns
-- Accessibility considerations
+### `onex upload`
 
-### Beautiful Output
+Upload compiled theme to S3 as `bundle.zip` + `source.zip`.
 
-- Color-coded messages (success, error, warning, info)
-- Loading spinners for file operations
-- Clear next steps after each command
-- Relative file paths for easy navigation
+| Option | Description |
+|---|---|
+| `-t, --theme <theme>` | Theme to upload |
+| `-b, --bucket <name>` | S3 bucket name |
+| `-v, --version <version>` | Theme version |
+| `-e, --environment <env>` | Environment (`staging` or `production`) |
+| `--dry-run` | Show what would be uploaded without uploading |
+| `--skip-source` | Skip uploading `source.zip` |
+| `--source-dir <dir>` | Source directory path |
 
-## Usage in Project
+```bash
+# Dry run first
+onex upload --theme simple --dry-run
 
-### Option 1: Via pnpm scripts
+# Upload to staging
+onex upload --theme simple
 
-Add to `package.json`:
+# Upload to production
+onex upload --theme simple -e production
 
-```json
-{
-  "scripts": {
-    "onex": "node packages/cli/bin/onex.js"
-  }
-}
+# Override bucket
+onex upload --theme simple --bucket custom-bucket
 ```
 
-Then use:
+### `onex download`
 
-```bash
-pnpm onex list
-pnpm onex create:section hero -t my-theme
-```
+Download a compiled theme from S3.
 
-### Option 2: Direct execution
+| Option | Description |
+|---|---|
+| `-t, --theme-id <id>` | Theme ID to download |
+| `-v, --version <version>` | Theme version (default: `latest`) |
+| `-b, --bucket <name>` | S3 bucket name |
+| `-e, --environment <env>` | Environment (`staging` or `production`) |
+| `-o, --output <dir>` | Output directory (default: `./active-theme`) |
 
-```bash
-node packages/cli/bin/onex.js list
-node packages/cli/bin/onex.js create:section hero
-```
+### `onex clone <theme-name>`
+
+Clone theme source code from S3.
 
-### Option 3: Global installation
+| Option | Description |
+|---|---|
+| `-v, --version <version>` | Theme version (default: `latest`) |
+| `-o, --output <dir>` | Output directory |
+| `-b, --bucket <name>` | S3 bucket name |
+| `-e, --environment <env>` | Environment (`staging` or `production`) |
+| `--no-install` | Skip running `pnpm install` after clone |
 
 ```bash
-npm install -g @duongthiu/onex-cli
-onex list
-onex create:section hero
+onex clone simple
+onex clone simple -v 1.0.0 -o ./my-clone --no-install
 ```
 
-## Development
+## S3 Configuration
 
-### Building the CLI
+The `upload`, `download`, and `clone` commands use S3 for storage. The CLI **automatically loads `.env.local` and `.env`** from the project root, so you only need to configure once:
 
 ```bash
-cd packages/cli
-pnpm build
+# .env.local (at project root)
+BUCKET_NAME=my-bucket
+AWS_REGION=ap-southeast-1
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
 ```
 
-### Testing locally
+Then all S3 commands just work without extra flags:
 
 ```bash
-# From project root
-node packages/cli/bin/onex.js --help
-node packages/cli/bin/onex.js list
+onex upload --theme simple    # picks up bucket + credentials from .env.local
+onex clone simple             # same
+onex download -t simple       # same
 ```
 
-### Type Checking
+### Adapter Modes
 
 ```bash
-pnpm type-check
+# MinIO (set ADAPTER_MODE=vps)
+ADAPTER_MODE=vps
+MINIO_ENDPOINT=localhost:9000
+MINIO_ACCESS_KEY=minioadmin
+MINIO_SECRET_KEY=minioadmin
+
+# LocalStack (set ADAPTER_MODE=local)
+ADAPTER_MODE=local
 ```
 
-### Linting
+### Bucket Name Resolution
+
+Priority order:
+1. `--bucket` CLI flag
+2. `BUCKET_NAME` environment variable
+3. Default: `onex-themes-staging` or `onex-themes-prod` (based on `--environment`)
+
+## Theme Structure
+
+Themes live in the `themes/` directory at the project root:
 
-```bash
-pnpm lint
+```
+themes/
+  my-theme/
+    theme.config.ts        # Theme metadata (name, version, description)
+    bundle-entry.ts        # Build entry point
+    index.ts               # Theme exports
+    sections-registry.ts   # Section registry
+    theme.layout.ts        # Layout definition
+    package.json
+    tsconfig.json
+    sections/              # Section components
+      hero/
+      features/
+      ...
+    pages/                 # Page configurations
+      home.ts
+      about.ts
+      ...
 ```
 
-## Architecture
+## Project Detection
 
-### File Structure
+The CLI detects a OneX project by looking for a `themes/` directory (or legacy `src/themes/`) from the project root. Within themes, it recognizes any directory containing `theme.config.ts`, `bundle-entry.ts`, or `manifest.ts` as a valid theme.
+
+## Architecture
 
 ```
 packages/cli/
 ├── src/
 │   ├── cli.ts                  # Main CLI entry point
-│   ├── index.ts                # Programmatic API
+│   ├── index.ts                # Programmatic API exports
 │   ├── commands/
 │   │   ├── init.ts             # Theme initialization
 │   │   ├── create-section.ts   # Section scaffolding
 │   │   ├── create-block.ts     # Block scaffolding
 │   │   ├── create-component.ts # Component scaffolding
-│   │   └── list.ts             # Project inventory
+│   │   ├── list.ts             # Project inventory
+│   │   ├── validate.ts         # Theme validation
+│   │   ├── build.ts            # Theme build
+│   │   ├── package.ts          # Theme packaging
+│   │   ├── deploy.ts           # Deploy to API server
+│   │   ├── upload.ts           # Upload to S3
+│   │   ├── download.ts         # Download from S3
+│   │   └── clone.ts            # Clone source from S3
 │   └── utils/
 │       ├── logger.ts           # Console output utilities
-│       ├── file-helpers.ts     # File operations
+│       ├── file-helpers.ts     # File operations & project detection
 │       └── validators.ts       # Input validation
 ├── bin/
 │   └── onex.js                 # Executable entry point
+├── templates/                  # Scaffolding templates
 └── package.json
 ```
 
-### Dependencies
-
-- **commander**: CLI framework and command parsing
-- **inquirer**: Interactive prompts
-- **chalk**: Terminal string styling
-- **ora**: Elegant terminal spinners
-- **fs-extra**: Enhanced file system operations
-- **ejs**: Template rendering (for future template system)
-- **glob**: File pattern matching
-
-## Next Steps
-
-After generating files:
-
-1. **Sections**:
-   - Customize `section.schema.ts` with your settings
-   - Implement template component in `section-default.tsx`
-   - Register in theme `manifest.ts`
-
-2. **Blocks**:
-   - Define settings in `block.schema.ts`
-   - Implement component in `block.tsx`
-   - Register in `src/lib/registry/block-registry.ts`
-
-3. **Components**:
-   - Customize content/style fields in `component.schema.ts`
-   - Implement component in `component.tsx`
-   - Register in `src/lib/registry/component-registry.ts`
-
-## Examples
-
-### Creating a complete feature section
+## Development
 
 ```bash
-# 1. Create theme
-onex init ecommerce-theme
-
-# 2. Create hero section
-onex create:section hero -t ecommerce-theme -c heroes
+cd packages/cli
 
-# 3. Create product blocks
-onex create:block product-card
-onex create:block product-grid
+# Build
+pnpm build
 
-# 4. Create components
-onex create:component price-tag -t ui
-onex create:component add-to-cart -t ui
+# Watch mode
+pnpm dev
 
-# 5. Check inventory
-onex list -t ecommerce-theme
-```
-
-### Quick section creation
+# Type check
+pnpm type-check
 
-```bash
-# Create with all options
-onex cs testimonials -t my-theme -c testimonials
+# Lint
+pnpm lint
 
-# Interactive mode (prompts for options)
-onex cs testimonials
+# Install globally after building
+npm install -g . --force
 ```
 
 ## License