npm package: @onexapis/cli
Description: CLI tool for OneX theme development - scaffolds themes using @onexapis/core
Author: OneX Team
Latest version: 1.1.48

# @onexapis/cli

CLI tool for OneX theme development — scaffold, build, validate, and deploy themes using `@onexapis/core`.

## Installation

```bash
# Install globally
npm install -g @onexapis/cli

# Or within the monorepo
cd packages/cli
pnpm build
npm install -g .
```

Requires Node.js >= 18.

## Quick Start

```bash
# 1. Login to OneX platform
onexthm login

# 2. Create a new theme project
onexthm init my-theme
cd my-theme

# 3. Develop with live preview
onexthm dev

# 4. Publish to marketplace (authenticated, secure)
onexthm publish
```

## Theme Developer Flow

```
onexthm login                  # Authenticate with OneX platform
onexthm init my-store          # Scaffold theme from template (7 sections, 3 pages)
cd my-store
onexthm dev                    # Live preview at localhost:3456
onexthm create:section pricing # Add new section
onexthm validate               # Check structure
onexthm build                  # Compile for production
onexthm publish                # Register → build → upload → scan → publish
onexthm whoami                 # Check logged-in status
onexthm logout                 # End session
```

## Commands

### `onexthm init [project-name]`

Create a new OneX theme project from a template.

| 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          |

### `onexthm create:section <name>` (alias: `cs`)

Scaffold a new section inside a theme.

| Option                      | Description                                        |
| --------------------------- | -------------------------------------------------- |
| `-t, --theme <theme>`       | Target theme                                       |
| `-c, --category <category>` | Section category (`headers`, `content`, `footers`) |
| `--template <template>`     | Initial template variant (`default`, `minimal`)    |

```bash
onexthm create:section hero -t my-theme -c heroes
onexthm cs featured-products -t my-store
```

### `onexthm create:block <name>` (alias: `cb`)

Scaffold a new block.

| Option                | Description             |
| --------------------- | ----------------------- |
| `-t, --theme <theme>` | Target theme (optional) |

```bash
onexthm create:block product-card
onexthm cb testimonial-item -t my-theme
```

### `onexthm create:component <name>` (alias: `cc`)

Scaffold a new UI component.

| Option              | Description                             |
| ------------------- | --------------------------------------- |
| `-t, --type <type>` | Component type (`ui`, `layout`, `form`) |

```bash
onexthm create:component icon-badge
onexthm cc custom-input -t form
```

### `onexthm list`

List available themes, sections, blocks, and components in the project.

| Option                | Description          |
| --------------------- | -------------------- |
| `-s, --sections`      | List sections only   |
| `-b, --blocks`        | List blocks only     |
| `-c, --components`    | List components only |
| `-t, --theme <theme>` | Filter by theme      |

### `onexthm validate`

Validate theme structure and files.

| Option                | Description                           |
| --------------------- | ------------------------------------- |
| `-t, --theme <theme>` | Theme to validate                     |
| `-f, --fix`           | Auto-fix issues (not yet implemented) |

### `onexthm build`

Build a theme for production. Runs type-check, lint, and compilation.

| Option                | Description                         |
| --------------------- | ----------------------------------- |
| `-t, --theme <theme>` | Theme to build                      |
| `-p, --production`    | Production build with optimizations |
| `-w, --watch`         | Watch mode for development          |

> **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" } }
> ```

### `onexthm package`

Compile and package a theme as a distributable zip file.

| 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 |

### `onexthm deploy`

Upload a theme package to the API server.

| 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`) |

### `onexthm upload`

Upload compiled theme to S3 as `bundle.zip` + `source.zip`.

| 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                         |

```bash
# Dry run first
onexthm upload --theme simple --dry-run

# Upload to staging
onexthm upload --theme simple

# Upload to production
onexthm upload --theme simple -e production

# Override bucket
onexthm upload --theme simple --bucket custom-bucket
```

### `onexthm download`

Download a compiled theme from S3.

| 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`) |

### `onexthm clone <theme-name>`

Clone theme source code from S3.

| Option                    | Description                               |
| ------------------------- | ----------------------------------------- |
| `-v, --version <version>` | Theme version (default: `latest`)         |
| `-n, --name <name>`       | New theme name (skips interactive prompt) |
| `-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
onexthm clone simple
onexthm clone simple -n my-store
onexthm clone simple -v 1.0.0 -o ./my-clone --no-install
```

### `onexthm login`

Authenticate with the OneX platform. Stores encrypted JWT token in `~/.onexthm/auth.json`.

```bash
onexthm login
# Email: dev@example.com
# Password: ********
# ✓ Logged in! Token stored securely.
```

Required before `onexthm publish`. Token auto-refreshes on expiry.

### `onexthm logout`

Clear stored authentication tokens.

```bash
onexthm logout
```

### `onexthm whoami`

Show current logged-in developer info.

```bash
onexthm whoami
# Email: dev@example.com
# Company: 9e61d187-...
# Status: ✓ Active
```

### `onexthm publish`

Build, scan, and publish theme to the marketplace. Requires login.

```bash
onexthm publish
# ✓ Logged in as dev@example.com
# Publishing my-store v1.0.0...
#   1. Registering theme...     ✓
#   2. Building...              ✓ (54 KB)
#   3. Getting upload URL...    ✓
#   4. Uploading bundle...      ✓
#   5. Uploading source...      ✓
#   6. Scanning & publishing... ✓ Published!
```

| Option               | Description          |
| -------------------- | -------------------- |
| `-t, --theme <path>` | Theme directory path |

Security features:

- **Ownership check** — only theme owner can publish updates
- **Presigned URLs** — no AWS credentials needed
- **Security scan** — blocks eval(), XSS, crypto mining, data exfiltration
- **Audit logging** — every publish is logged with developer identity

### `onexthm config` (Legacy)

Interactive setup for S3 credentials. **Not needed for `onexthm publish`** — use `onexthm login` instead.

```bash
onexthm config
```

| Key                      | Description           | Required |
| ------------------------ | --------------------- | -------- |
| `AWS_ACCESS_KEY_ID`      | AWS Access Key ID     | Yes      |
| `AWS_SECRET_ACCESS_KEY`  | AWS Secret Access Key | Yes      |
| `AWS_REGION`             | AWS Region            | No       |
| `BUCKET_NAME`            | S3 Bucket Name        | No       |
| `NEXT_PUBLIC_API_URL`    | API URL               | No       |
| `NEXT_PUBLIC_COMPANY_ID` | Company ID            | No       |

Run this once after installing the CLI. Re-run anytime to update values.

## S3 Configuration

The `upload`, `download`, and `clone` commands use S3 for storage.

### Recommended: use `onexthm config`

```bash
# One-time setup — saves credentials to ~/.onexthm/.env
onexthm config
```

After running `onexthm config`, all S3 commands work from any directory:

```bash
onexthm clone simple             # works anywhere
onexthm upload --theme simple    # picks up config automatically
onexthm download -t simple       # same
```

### Manual configuration

The CLI loads env files in this order (first found wins):

1. **Project-level**: `.env.local` and `.env` at the project root
2. **Global**: `~/.onexthm/.env` (set by `onexthm config`, or create manually)

### Adapter Modes

```bash
# 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
```

### 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:

```
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
      ...
```

## Project Detection

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 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
│   │   ├── 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
│   │   └── config.ts           # CLI credential setup
│   └── utils/
│       ├── logger.ts           # Console output utilities
│       ├── file-helpers.ts     # File operations & project detection
│       └── validators.ts       # Input validation
├── bin/
│   └── onexthm.js                 # Executable entry point
├── templates/                  # Scaffolding templates
└── package.json
```

## Development

```bash
cd packages/cli

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm type-check

# Lint
pnpm lint

# Install globally after building
npm install -g . --force
```

## License

MIT