# Alpha CLI

> A comprehensive command-line interface for building, managing, and publishing plugin-based applications in the Alpha ecosystem.

[![Version](https://img.shields.io/badge/version-1.0.19-blue.svg)](https://www.npmjs.com/package/@jatahworx/alpha-cli)
[![License](https://img.shields.io/badge/license-ISC-green.svg)](LICENSE)

Alpha CLI streamlines the development workflow for creating modular, reusable components and modules that integrate seamlessly into the Alpha platform. Built on modern web standards (Lit, TypeScript, Vite), it provides scaffolding, live development, building, and publishing capabilities.

---


## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
  - [Workspaces](#workspaces)
  - [Components vs Modules](#components-vs-modules)
  - [Attribute System](#attribute-system)
- [Commands](#commands)
  - [new](#new-name)
  - [generate](#generate--g)
  - [build](#build-type-pluginname)
  - [start](#start-options)
  - [serve](#serve)
  - [auth](#auth-command)
  - [publish](#publish-packagename-options)
  - [deprecate](#deprecate-packagename-options)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Development Workflow](#development-workflow)
- [Best Practices](#best-practices)
- [Docker & Kubernetes Deployment](#docker--kubernetes-deployment)
- [Troubleshooting](#troubleshooting)
- [API Reference](#api-reference)
- [Contributing](#contributing)

---


## Overview

Alpha CLI is a professional development tool for creating plugin-based applications. It supports two fundamental plugin types:

| Plugin Type    | Purpose                                  | Access Pattern           | Use Cases                               |
|---------------|------------------------------------------|-------------------------|----------------------------------------|
| **Components** | UI elements with drag-and-drop capability | Canvas placement        | Buttons, forms, data grids, charts      |
| **Modules**    | Globally accessible utilities             | `alpha.plugins` or `ap` | API clients, helpers, services, utilities |

### Key Capabilities

- **Project Scaffolding**: Complete workspace setup with TypeScript, Docker, and Kubernetes support
- **Code Generation**: Handlebars-based templates with automatic formatting
- **Live Development**: Vite-powered dev server with hot reload
- **Build System**: Production-optimized builds with minification
- **Authentication**: OpenID Connect integration for secure publishing
- **Publishing**: One-command deployment to Alpha marketplace
- **Version Management**: Semantic versioning with automatic package.json updates

---

## Features

### Development Features

- ✅ TypeScript-first with full type safety
- ✅ Lit-based web components (standards-compliant)
- ✅ Hot module reload for rapid iteration
- ✅ Automatic code formatting with Prettier
- ✅ Interactive CLI prompts for streamlined workflows
- ✅ Component testing interface auto-generated

### Build Features

- ✅ Vite bundling with ES modules
- ✅ TypeScript compilation
- ✅ Production minification
- ✅ Docker containerization
- ✅ Kubernetes Helm charts

### Publishing Features

- ✅ OpenID Connect authentication
- ✅ Automatic version bumping (patch/minor/major)
- ✅ Asset management (icons, screenshots)
- ✅ Metadata tracking (packageId, versionId)
- ✅ Package deprecation support

---

## Installation

### Prerequisites

- Node.js 20+ (recommended: 22.x)
- npm 9+
- Git
- Docker (optional, for containerization)

### Global Installation

```sh
npm install -g @jatahworx/alpha-cli
```

### Verify Installation

```sh
alpha --version
# Output: 1.0.0
```

### Post-Installation

Alpha CLI automatically creates configuration files on first install:

```
~/.alphaconfigs/
├── auth.json          # Authentication tokens
└── preferences.json   # User preferences
```

---

## Quick Start

### 1. Create a New Workspace

```sh
alpha new my-app
cd my-app
```

**What gets created:**
```
my-app/
├── .configs/              # Workspace configuration
│   ├── auth.json         # Auth config (placeholders)
│   └── preferences.json  # User preferences
├── .vscode/              # VSCode settings
├── helmchart/            # Kubernetes deployment
├── packages/             # Plugin directory (empty initially)
├── Dockerfile            # Container definition
├── index.html            # Entry HTML with test interface
├── index.ts              # Application entry point
├── public-api.ts         # Public exports
├── tsconfig.json         # TypeScript config
├── plugin.json           # Workspace metadata
├── package.json          # npm workspace configuration
└── ATTRIBUTE.md          # Attribute documentation
```

### 2. Generate Your First Component

```sh
alpha generate component counter --description "A simple counter"
# Alias: alpha g c counter
```

**Generated structure:**
```
packages/counter/
├── package.json
├── counter.component.ts    # Main component class
├── counter.spec.ts         # Test file
├── counter.styles.ts       # Lit CSS styles
└── assets/
    ├── icon/
    │   └── default-icon.png
    └── images/
```

**Generated component code:**
```typescript
@AlphaComponent({
    componentName: 'counter',
    componentVersion: '1.0.0',
    label: 'Counter',
    selector: 'comp-counter',
    category: 'Input',
    icon: 'sample.png'
})
export class Counter extends LitElement {
    @AlphaAttribute({
        type: ATTRIBUTE_TYPE.PROPERTY,
        uiType: UI_TYPE.INPUT,
        label: 'Initial Count',
        defaultValue: 0,
        placeholder: 'Enter label',
        fieldMappings: 'value'
    })
    @property({ type: Number })
    value = 0;

    // Event handlers with decorators...
    @AlphaAttribute({
        type: ATTRIBUTE_TYPE.EVENT,
        label: 'On Increment',
        event: 'onIncrement'
    })
    increment(event) {
        this.value++;
        this.dispatchEvent(new CustomEvent('onIncrement', {
            detail: { event, element: this, value: this.value },
            bubbles: true,
            composed: true
        }));
    }
}
```

### 3. Start Development Server

```sh
alpha start
# Server running at http://localhost:6969
```

The dev server provides:
- **Hot reload**: Changes reflect instantly
- **Testing interface**: Auto-generated UI to test components
- **Component registry**: All components available in `globalThis.aci`

### 4. Build for Production

```sh
alpha build plugins
# or build specific plugin:
alpha build plugins counter
```

### 5. Publish to Marketplace

```sh
# Authenticate first
alpha auth login

# Publish with version bump
alpha publish counter --version-type patch
```

---

## Core Concepts

### Workspaces

Alpha projects are **npm workspaces** containing multiple plugins. Every workspace has:

#### `plugin.json` (Required)
```json
{
    "name": "my-app",
    "componentSelectorPrefix": "comp",
    "moduleSelectorPrefix": "mod"
}
```

- **name**: Workspace identifier
- **componentSelectorPrefix**: Prefix for component selectors (e.g., `comp-button`)
- **moduleSelectorPrefix**: Prefix for module IDs (e.g., `mod-api-client`)

#### Workspace Validation
Most commands require a valid workspace with both `plugin.json` and `package.json`. Exceptions:
- `alpha new` (creates workspace)
- `alpha auth login` (global authentication)

---

### Components vs Modules

#### Components: UI Building Blocks

**Characteristics:**
- Extend `LitElement` from Lit framework
- Draggable onto canvas in Alpha builder
- Configurable via **attribute system** (properties, events, validations)
- Have visual representation (render method)
- Support lifecycle hooks
- Can dispatch custom events

**Selector Pattern:**
```typescript
selector: '{prefix}-{kebab-case-name}'
// Example: 'comp-user-profile'
```

**Component Example:**
```typescript
@AlphaComponent({
    selector: 'comp-user-card',
    label: 'User Card',
    category: 'Display'
})
export class UserCard extends LitElement {
    @property({ type: Object })
    user = null;

    render() {
        return html`
            <div class="card">
                <h3>${this.user?.name}</h3>
                <p>${this.user?.email}</p>
            </div>
        `;
    }
}
```

#### Modules: Global Utilities

**Characteristics:**
- Plain JavaScript/TypeScript classes
- No UI rendering
- Globally accessible via `alpha.plugins` or `ap` namespace
- Service classes, API clients, helpers
- Lifecycle hooks: `init()` and `onRegister()`

**Module Example:**
```javascript
class ApiClient {
    init() {
        console.log('ApiClient initialized');
    }

    onRegister() {
        console.log('ApiClient registered');
    }

    async fetchData(url) {
        return fetch(url).then(r => r.json());
    }
}

alpha.registerPlugins('mod-api-client', new ApiClient());
```

**Access pattern:**
```javascript
// In your application:
const data = await alpha['mod-api-client'].fetchData('/api/users');
// or
const data = await ap['mod-api-client'].fetchData('/api/users');
```

---

### Attribute System

Attributes define the **configurable interface** for components. They use TypeScript decorators to annotate properties and methods.

#### Three Attribute Types

| Type | Purpose | Decorator Target | Example Use Case |
|------|---------|------------------|------------------|
| **PROPERTY** | Data input configuration | Class properties | Text inputs, toggles, dropdowns |
| **EVENT** | User interaction handlers | Methods | Click handlers, form submissions |
| **VALIDATION** | Input validation rules | Properties | Required fields, pattern matching |

#### Supported UI Types

| UI Type | Description | Options Format | Use Case |
|---------|-------------|----------------|----------|
| `input` | Text input field | `{ maxLength: number }` | Simple text values |
| `toggle` | Boolean switch | None | On/off states |
| `dropdown` | Single selection | `Array<{ displayText, value }>` | Predefined choices |
| `multi-select` | Multiple selection | `Array<{ displayText, value }>` | Multiple choices |
| `typed-input` | Data binding input | `Array<{ name, value }>` | Variable binding |
| `range` | Numeric slider | `{ minLabel, maxLabel, minRange, maxRange }` | Numeric ranges |
| `color-picker` | Color selector | None | Color values |
| `data-source` | Data source binding | Field mappings | API endpoints |
| `data-set` | Data collection | Field mappings | Arrays/lists |
| `table-actions` | Table action buttons | Actions array | CRUD operations |
| `data-mapping` | Field mapping interface | Complex mappings | Data transformation |

#### Field Mappings

Field mappings connect attribute values to component properties:

**Simple mapping (string path):**
```typescript
@AlphaAttribute({
    uiType: UI_TYPE.INPUT,
    fieldMappings: 'userName'  // Maps directly to this.userName
})
userName = '';
```

**Complex mapping (object with paths):**
```typescript
@AlphaAttribute({
    uiType: UI_TYPE.TYPED_INPUT,
    fieldMappings: {
        type: 'options.mappingType',    // Nested path
        value: 'options.modelPath'      // Nested path
    }
})
options = {
    mappingType: '',
    modelPath: ''
};
```

**Data source mapping:**
```typescript
@AlphaAttribute({
    uiType: UI_TYPE.DATA_SOURCE,
    fieldMappings: {
        response: 'dataSource.response',
        label: 'dataSource.labelField',
        value: 'dataSource.valueField'
    }
})
dataSource = { response: [], labelField: '', valueField: '' };
```

#### Complete Attribute Example

```typescript
@AlphaAttribute({
    type: ATTRIBUTE_TYPE.PROPERTY,         // Attribute type
    uiType: UI_TYPE.DROPDOWN,              // UI control
    label: 'Select Theme',                 // Display label
    category: 'Appearance',                // Grouping category
    placeholder: 'Choose a theme',         // Placeholder text
    defaultValue: 'light',                 // Default selection
    options: [                             // Dropdown options
        { displayText: 'Light Mode', value: 'light' },
        { displayText: 'Dark Mode', value: 'dark' },
        { displayText: 'Auto', value: 'auto' }
    ],
    fieldMappings: 'theme'                 // Maps to this.theme
})
@property({ type: String })
theme = 'light';
```

---

## Commands

### `new <name>`

Create a new Alpha workspace with complete project structure.

**Syntax:**
```sh
alpha new <project-name>
```

**What happens:**
1. Creates directory structure
2. Initializes npm workspace (`workspaces: ["packages/*"]`)
3. Generates configuration files (`plugin.json`, `tsconfig.json`, `.env`)
4. Sets up Docker and Kubernetes templates
5. Creates VSCode settings
6. Installs dependencies:
   - **DevDependencies**: `lit`, `typescript`
   - **Dependencies**: `express`, `@jatahworx/alpha-annotations-lib`
7. Adds npm scripts:
   - `build`: Runs `alpha build`
   - `start`: Runs `alpha start`
   - `serve`: Runs `alpha serve`

**Example:**
```sh
alpha new ecommerce-components
cd ecommerce-components
```

**Generated `plugin.json`:**
```json
{
    "name": "ecommerce-components",
    "componentSelectorPrefix": "comp",
    "moduleSelectorPrefix": "mod"
}
```

---

### `generate` | `g`

Generate components, modules, or attributes with pre-configured templates.

#### Generate Component

**Syntax:**
```sh
alpha generate component <name> [options]
alpha g c <name> [options]
```

**Options:**
- `-d, --description <text>` - Component description

**Example:**
```sh
alpha g c product-card --description "Displays product information"
```

**Generated files:**
```
packages/product-card/
├── package.json                     # npm package config
├── product-card.component.ts        # Main component class
├── product-card.spec.ts             # Test file
├── product-card.styles.ts           # Lit CSS styles
└── assets/
    ├── icon/default-icon.png
    └── images/
```

**Naming conventions applied:**
- **File names**: `kebab-case` (`product-card.component.ts`)
- **Class names**: `PascalCase` (`ProductCard`)
- **Selectors**: `{prefix}-{kebab-case}` (`comp-product-card`)

**Automatic updates:**
- `public-api.ts` receives new export statement
- Code formatted with Prettier
- Component registered in workspace

---

#### Generate Module

**Syntax:**
```sh
alpha generate module <name> [options]
alpha g m <name> [options]
```

**Options:**
- `-d, --description <text>` - Module description

**Example:**
```sh
alpha g m cart-service --description "Shopping cart management"
```

**Generated structure:**
```
packages/cart-service/
├── package.json
├── index.js                         # Module class with lifecycle hooks
└── assets/
```

**Generated code pattern:**
```javascript
class CartService {
    init() {
        // Initialization logic
        console.log('CartService initialized');
    }

    onRegister() {
        // Registration hook
        console.log('CartService registered');
    }

    // Your methods here
}

// Global registration
alpha.registerPlugins('mod-cart-service', new CartService());
```

---

#### Generate Attribute

Add configurable attributes to existing components using interactive prompts or CLI options.

**Syntax:**
```sh
alpha generate attribute [componentName] [options]
alpha g a [componentName] [options]
```

**Options:**
- `-t, --type <type>` - Attribute type: `property`, `event`, or `validation`
- `-u, --ui-type <uiType>` - UI control type (see [UI Types](#supported-ui-types))
- `-l, --label <label>` - Display label in builder
- `-e, --event <event>` - Event name (required for event type)
- `-c, --category <category>` - Grouping category
- `-p, --placeholder <placeholder>` - Placeholder text
- `-d, --defaultValue <value>` - Default value
- `-o, --options <options...>` - Options for dropdowns/selects
- `-f, --fieldMappings <mappings>` - Field mapping configuration
- `-n, --validation <rules>` - Validation rules

**Interactive Mode (Recommended):**
```sh
alpha g a product-card
# Prompts for each configuration option
```

**CLI Mode:**
```sh
alpha g a product-card \
  --type property \
  --ui-type input \
  --label "Product Name" \
  --placeholder "Enter product name" \
  --defaultValue "" \
  --fieldMappings "productName"
```

**How it works:**
1. Uses `ts-morph` library to parse TypeScript AST
2. Adds `@AlphaAttribute` decorator to property/method
3. Adds Lit `@property` decorator for properties
4. Preserves existing code structure
5. Formats code with Prettier

**Example output:**
```typescript
@AlphaAttribute({
    type: ATTRIBUTE_TYPE.PROPERTY,
    uiType: UI_TYPE.INPUT,
    label: 'Product Name',
    placeholder: 'Enter product name',
    defaultValue: '',
    fieldMappings: 'productName'
})
@property({ type: String })
productName = '';
```

---

### `build <type> [pluginName]`

Build plugins for production or create Docker images.

**Syntax:**
```sh
alpha build <plugins|docker> [pluginName]
```

**Arguments:**
- `<type>` - **Required**: `plugins` or `docker`
- `[pluginName]` - **Optional**: Specific plugin to build (builds all if omitted)

#### Build Plugins

**Single plugin:**
```sh
alpha build plugins product-card
```

**All plugins:**
```sh
alpha build plugins
```

**Build process:**
1. TypeScript compilation: `npx tsc -p ./tsconfig.json`
2. Vite bundling with optimizations:
   - Minification enabled
   - ES module format
   - Tree shaking
   - Source maps (optional)
3. Output to `dist/` directory
4. Asset copying

**Output structure:**
```
packages/product-card/dist/
├── product-card.component.js    # Bundled component
├── product-card.component.d.ts  # Type definitions
└── assets/                      # Copied assets
```

#### Build Docker

**Syntax:**
```sh
alpha build docker
```

**Dockerfile details:**
- **Base image**: `node:20-alpine3.19`
- **Working directory**: `/usr/src/app`
- **Port**: 3000
- **Entry point**: `node index.js`
- Production dependencies only (`--omit=dev`)

**What gets included:**
- `plugins-server/` directory
- `package.json` and `.npmrc`
- Built plugins from `packages/*/dist/`

---

### `start [options]`

Start a Vite-powered development server with hot module reloading.

**Syntax:**
```sh
alpha start [--port <port>]
```

**Options:**
- `-p, --port <port>` - Server port (default: `6969`)

**Example:**
```sh
alpha start --port 8080
```

**Server features:**
- ✅ Hot Module Replacement (HMR)
- ✅ TypeScript compilation on-the-fly
- ✅ CSS injection without page reload
- ✅ Error overlay in browser
- ✅ Fast rebuild with Vite's esbuild integration

**Testing Interface:**
The `index.ts` file provides an auto-generated testing UI:
```typescript
// Components automatically registered in globalThis.aci
const components = globalThis.aci;

// Creates fieldsets with input controls for each property
// Automatically listens to all custom events
// Logs event details to console
```

**Access:**
```
http://localhost:6969
```

---

### `serve`

Start an Express server to serve built plugins in production.

**Syntax:**
```sh
alpha serve
```

**Environment variables:**
```env
PORT=666                      # Server port
BASE_PATH=/plugins-service   # Base URL path
PLUGIN_DIR_ROOT=plugins      # Plugin directory name
```

**Endpoints:**
- `GET /ping` - Health check endpoint
- `GET /plugins/*` - Static file serving

**Example:**
```sh
# Start server
alpha serve

# Access plugins
curl http://localhost:666/plugins-service/ping
# Response: "pong"

curl http://localhost:666/plugins/product-card/dist/product-card.component.js
```

**Production deployment:**
```sh
# With custom config
PORT=3000 BASE_PATH=/api/plugins alpha serve
```

---

### `auth [command]`

Manage authentication with the Alpha marketplace using OpenID Connect.

#### `auth login`

Authenticate with the Alpha identity server.

**Syntax:**
```sh
alpha auth login
```

**Authentication flow:**
1. Starts local Fastify server on port configured in `.env` (default: 32231)
2. Opens browser to authentication URL
3. User authenticates with credentials
4. Identity server redirects to local callback
5. CLI receives authorization code
6. Exchanges code for access/refresh tokens
7. Stores tokens in `~/.alphaconfigs/auth.json`

**Environment variables (.env):**
```env
PORT=32231
ISSUER_URL=https://ids.neutrinos.co
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
```

**Stored token format:**
```json
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "v1.MRlF8Y0L0Q...",
    "token_type": "Bearer",
    "expires_at": 1704067200,
    "scope": "openid profile email address phone offline_access user"
}
```

**Token features:**
- Automatic refresh with `refresh_token` grant
- Token introspection for validation
- Secure storage in user home directory

**Process termination:**
- `SIGINT` (Ctrl+C): Graceful shutdown
- `SIGTERM`: Server cleanup

---

#### `auth state`

Check current authentication status.

**Syntax:**
```sh
alpha auth state
```

**Note:** Currently displays "state" message. Full implementation shows:
- Token expiration time
- User information
- Scopes granted
- Token validity

---

### `publish [packageName] [options]`

Publish a plugin to the Alpha marketplace with versioning and metadata.

**Syntax:**
```sh
alpha publish [packageName] [options]
```

**Arguments:**
- `[packageName]` - Plugin to publish. If omitted, shows interactive list.

**Options:**
- `-t, --version-type <type>` - Version bump: `patch`, `minor`, or `major`
- `-d, --display-name <name>` - Display name in marketplace
- `-i, --icon <path>` - Path to icon file (PNG/JPG recommended)
- `-m, --images <paths...>` - Paths to screenshot images (space-separated)

**Examples:**

**Interactive publish:**
```sh
alpha publish
# Shows list of packages to select
# Prompts for version type and metadata
```

**Quick patch release:**
```sh
alpha publish product-card --version-type patch
```

**Full metadata publish:**
```sh
alpha publish product-card \
  --version-type minor \
  --display-name "Product Card Component" \
  --icon ./packages/product-card/assets/icon/icon.png \
  --images ./screenshots/desktop.png ./screenshots/mobile.png
```

**Publishing workflow:**
1. **Authentication check**: Verifies valid access token
2. **Package validation**:
   - Checks if package exists in workspace
   - Verifies not deprecated
   - Validates package.json
3. **Version management**:
   - Runs `npm version <type> -w <package>` if version-type provided
   - Updates package.json with new version
4. **Build**:
   - Executes `alpha build plugins <package>`
   - Validates dist/ output exists
5. **Archive creation**:
   - Creates ZIP file of dist/ directory
   - Temporary file in system temp directory
6. **Upload**:
   - Assembles FormData with:
     - `file`: ZIP archive
     - `icon`: Icon file
     - `images[]`: Screenshot files
     - `package`: Package metadata JSON
     - `version`: Version metadata JSON
   - POSTs to: `https://alpha.neutrinos-apps.com/marketplace-headless/api/packages`
7. **Metadata update**:
   - Updates package.json with `packageId` and `versionId` from response
   - Writes updated package.json
8. **Cleanup**:
   - Deletes temporary ZIP file

**Package metadata sent:**
```json
{
    "name": "product-card",
    "displayName": "Product Card Component",
    "description": "Displays product information",
    "category": "Display",
    "icon": "icon.png",
    "images": ["desktop.png", "mobile.png"]
}
```

**Version metadata sent:**
```json
{
    "version": "1.0.1",
    "changelog": "Bug fixes and improvements"
}
```

**After publish, package.json updated:**
```json
{
    "name": "product-card",
    "version": "1.0.1",
    "packageId": "pkg_abc123",
    "versionId": "ver_xyz789"
}
```

**Requirements:**
- ✅ Must be authenticated (`alpha auth login`)
- ✅ Package must be buildable
- ✅ Valid package.json with name and version
- ✅ Icon file must exist if path provided
- ✅ Image files must exist if paths provided

---

### `deprecate [packageName] [options]`

Mark a package as deprecated in the marketplace, preventing future installs.

**Syntax:**
```sh
alpha deprecate [packageName] [options]
```

**Arguments:**
- `[packageName]` - Package to deprecate. If omitted, shows interactive list.

**Options:**
- `-y, --yes` - Skip confirmation prompt

**Examples:**

**Interactive deprecation:**
```sh
alpha deprecate
# Shows list of published packages
# Prompts for confirmation
```

**Direct deprecation with confirmation:**
```sh
alpha deprecate old-component --yes
```

**What happens:**
1. Validates package exists and is published (has `packageId`)
2. Shows confirmation prompt (unless `-y` flag used)
3. Makes API call to mark package as deprecated
4. Package remains visible but cannot be installed
5. Existing installations continue to work

**Use cases:**
- Replacing with better alternative
- Security vulnerabilities
- No longer maintained
- Breaking changes in new version

**Note:** Deprecation is **not reversible** via CLI. Contact support to restore deprecated packages.

---

## Architecture

### Project Structure Deep Dive

```
my-workspace/
├── .configs/                        # Workspace-specific config
│   ├── auth.json                   # Auth placeholders (workspace-level)
│   └── preferences.json            # User preferences
├── .vscode/                        # VSCode configuration
│   └── settings.json               # TypeScript, formatting settings
├── helmchart/                      # Kubernetes deployment
│   ├── Chart.yaml                  # Helm chart metadata
│   ├── values.yaml                 # Configuration values
│   └── templates/
│       ├── deployment.yaml         # K8s deployment
│       ├── service.yaml            # K8s service
│       ├── ingress.yaml            # Ingress rules
│       └── configmap.yaml          # Environment config
├── packages/                       # Plugin directory (npm workspace)
│   ├── my-component/
│   │   ├── package.json           # Plugin package config
│   │   ├── my-component.component.ts
│   │   ├── my-component.spec.ts
│   │   ├── my-component.styles.ts
│   │   ├── dist/                  # Build output (gitignored)
│   │   └── assets/
│   │       ├── icon/
│   │       │   └── default-icon.png
│   │       └── images/
│   └── my-module/
│       ├── package.json
│       ├── index.js
│       └── assets/
├── Dockerfile                      # Container definition
├── .dockerignore                   # Docker exclusions
├── index.html                      # Entry HTML with test UI
├── index.ts                        # App entry, component registration
├── public-api.ts                   # Public exports
├── tsconfig.json                   # TypeScript config
├── plugin.json                     # Workspace metadata (REQUIRED)
├── package.json                    # Workspace package.json
├── .env                            # Environment variables (gitignored)
├── .gitignore                      # Git exclusions
└── ATTRIBUTE.md                    # Attribute system documentation
```

### Component Architecture

**Component lifecycle:**
```typescript
import { LitElement, html } from 'lit';
import { property } from 'lit/decorators.js';

@AlphaComponent({
    componentName: 'my-component',
    componentVersion: '1.0.0',
    label: 'My Component',
    selector: 'comp-my-component',
    category: 'Custom',
    icon: 'icon.png'
})
@adoptAlphaCommonStyle()  // Adopts global Alpha styles
export class MyComponent extends LitElement {
    // 1. Static styles (scoped to component)
    static styles = componentStyles;

    // 2. Decorated properties (reactive)
    @AlphaAttribute({...})
    @property({ type: String })
    title = '';

    // 3. Lifecycle methods (Lit standard)
    connectedCallback() {
        super.connectedCallback();
        // Component added to DOM
    }

    disconnectedCallback() {
        super.disconnectedCallback();
        // Component removed from DOM
    }

    // 4. Render method (required)
    render() {
        return html`<div>${this.title}</div>`;
    }

    // 5. Event handlers (can be decorated)
    @AlphaAttribute({
        type: ATTRIBUTE_TYPE.EVENT,
        label: 'On Click',
        event: 'onClick'
    })
    handleClick(e) {
        this.dispatchEvent(new CustomEvent('onClick', {
            detail: { event: e, element: this },
            bubbles: true,
            composed: true
        }));
    }
}
```

**Component registration:**
```typescript
// Auto-generated in index.ts
import { MyComponent } from './packages/my-component/my-component.component';
customElements.define('comp-my-component', MyComponent);
```

### Module Architecture

**Module structure:**
```javascript
class ApiService {
    constructor() {
        this.baseUrl = '';
        this.headers = {};
    }

    // Called during registration
    init() {
        console.log('ApiService initialized');
        this.baseUrl = alpha.config.apiUrl || '';
    }

    // Called after registration
    onRegister() {
        console.log('ApiService registered');
    }

    // Public methods
    async get(endpoint) {
        return fetch(`${this.baseUrl}${endpoint}`, {
            headers: this.headers
        }).then(r => r.json());
    }

    async post(endpoint, data) {
        return fetch(`${this.baseUrl}${endpoint}`, {
            method: 'POST',
            headers: { ...this.headers, 'Content-Type': 'application/json' },
            body: JSON.stringify(data)
        }).then(r => r.json());
    }
}

// Global registration
alpha.registerPlugins('mod-api-service', new ApiService());
```

**Module access:**
```javascript
// In any component or module
const users = await alpha['mod-api-service'].get('/users');
// or
const users = await ap['mod-api-service'].get('/users');
```

### Build System Architecture

**TypeScript → Vite → Optimized Bundle**

```
┌─────────────────┐
│  Source (.ts)   │
└────────┬────────┘
         │
         ├─ TypeScript Compiler (tsc)
         │  ├─ Type checking
         │  └─ .d.ts generation
         │
         ▼
┌─────────────────┐
│ JavaScript (.js)│
└────────┬────────┘
         │
         ├─ Vite Bundler
         │  ├─ esbuild transpilation
         │  ├─ Tree shaking
         │  ├─ Minification
         │  ├─ Code splitting
         │  └─ Asset handling
         │
         ▼
┌─────────────────┐
│ dist/ (output)  │
│  ├─ .js bundle  │
│  ├─ .d.ts types │
│  └─ assets/     │
└─────────────────┘
```

**Vite configuration (generated):**
```javascript
export default defineConfig({
    build: {
        lib: {
            entry: './packages/my-component/my-component.component.ts',
            formats: ['es'],
            fileName: 'my-component.component'
        },
        rollupOptions: {
            external: ['lit', 'lit/decorators.js'],
            output: {
                dir: './packages/my-component/dist'
            }
        },
        minify: true,
        sourcemap: false
    }
});
```

---

## Configuration

### Environment Variables

#### Development Server (.env)
```env
# Auth callback server
PORT=32231

# OpenID Connect provider
ISSUER_URL=https://ids.neutrinos.co

# OAuth credentials
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
```

#### Production Plugin Server
```env
# Server configuration
PORT=666
BASE_PATH=/plugins-service
PLUGIN_DIR_ROOT=plugins
```

### Configuration Files

#### 1. plugin.json (Workspace metadata)
```json
{
    "name": "my-workspace",
    "componentSelectorPrefix": "comp",
    "moduleSelectorPrefix": "mod"
}
```

**Fields:**
- `name`: Workspace identifier (required)
- `componentSelectorPrefix`: Prefix for component selectors (default: "comp")
- `moduleSelectorPrefix`: Prefix for module IDs (default: "mod")

---

#### 2. package.json (npm workspace)
```json
{
    "name": "my-workspace",
    "version": "1.0.0",
    "type": "module",
    "workspaces": [
        "packages/*"
    ],
    "scripts": {
        "build": "alpha build plugins",
        "start": "alpha start",
        "serve": "alpha serve"
    },
    "devDependencies": {
        "lit": "^3.1.4",
        "typescript": "^5.2.2"
    },
    "dependencies": {
        "express": "^4.19.2",
        "@jatahworx/alpha-annotations-lib": "^1.0.3"
    }
}
```

**Key fields:**
- `"type": "module"`: Enables ES modules
- `workspaces`: npm workspace configuration
- Scripts automatically added by `alpha new`

---

#### 3. tsconfig.json (TypeScript configuration)
```json
{
    "compilerOptions": {
        "target": "ES2020",
        "module": "ESNext",
        "lib": ["ES2020", "DOM", "DOM.Iterable"],
        "experimentalDecorators": true,
        "useDefineForClassFields": false,
        "moduleResolution": "bundler",
        "resolveJsonModule": true,
        "isolatedModules": true,
        "noEmit": true,
        "strict": false,
        "skipLibCheck": true
    },
    "include": ["packages/**/*", "index.ts"],
    "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
```

**Key settings:**
- `experimentalDecorators`: Required for Alpha decorators
- `useDefineForClassFields`: false for compatibility
- `noEmit`: true (Vite handles compilation)

---

#### 4. ~/.alphaconfigs/auth.json (User authentication)
```json
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "v1.MRlF8Y0L0Q...",
    "token_type": "Bearer",
    "expires_at": 1704067200,
    "scope": "openid profile email address phone offline_access user"
}
```

**Location:** User home directory (`~/.alphaconfigs/`)
**Security:** Keep this file secure; contains authentication tokens

---

#### 5. ~/.alphaconfigs/preferences.json (User preferences)
```json
{
    "theme": "light",
    "language": "en",
    "showNotifications": true
}
```

**Fields:**
- `theme`: UI theme preference
- `language`: Locale/language code
- `showNotifications`: Enable/disable CLI notifications

---

## Development Workflow

### Complete Project Lifecycle

#### Phase 1: Project Initialization
```sh
# Create workspace
alpha new ecommerce-app
cd ecommerce-app

# Authenticate for publishing later
alpha auth login
```

---

#### Phase 2: Component Development
```sh
# Generate UI components
alpha g c product-card --description "Product display card"
alpha g c shopping-cart --description "Shopping cart widget"
alpha g c checkout-form --description "Checkout form"

# Generate utility modules
alpha g m api-client --description "API communication"
alpha g m cart-manager --description "Cart state management"
alpha g m payment-processor --description "Payment processing"
```

---

#### Phase 3: Attribute Configuration

**Add properties to product-card:**
```sh
# Product name
alpha g a product-card \
  --type property \
  --ui-type input \
  --label "Product Name" \
  --fieldMappings "productName"

# Product price
alpha g a product-card \
  --type property \
  --ui-type typed-input \
  --label "Price Binding" \
  --category "Data Binding" \
  --options '{"name":"CO","value":"co"}' \
  --fieldMappings '{"type":"priceBinding.type","value":"priceBinding.value"}'

# Add to cart event
alpha g a product-card \
  --type event \
  --label "On Add To Cart" \
  --event "onAddToCart"
```

---

#### Phase 4: Development & Testing
```sh
# Start dev server
alpha start

# Open browser to http://localhost:6969
# Test components in auto-generated UI
# Edit code and see instant updates
```

**Testing interface auto-generates:**
- Input fields for each property attribute
- Buttons for each event attribute
- Event log in console
- Component preview area

---

#### Phase 5: Build & Validation
```sh
# Build all plugins
alpha build plugins

# Verify dist/ output
ls packages/product-card/dist/
# Output: product-card.component.js, product-card.component.d.ts, assets/

# Build specific plugin
alpha build plugins shopping-cart
```

---

#### Phase 6: Publishing

**First publish (new package):**
```sh
alpha publish product-card \
  --display-name "Product Card Component" \
  --icon ./packages/product-card/assets/icon/icon.png \
  --images ./screenshots/product-card-1.png ./screenshots/product-card-2.png
```

**Update publish (version bump):**
```sh
# Patch release (1.0.0 → 1.0.1)
alpha publish product-card --version-type patch

# Minor release (1.0.1 → 1.1.0)
alpha publish product-card --version-type minor

# Major release (1.1.0 → 2.0.0)
alpha publish product-card --version-type major
```

---

#### Phase 7: Production Deployment

**Docker build:**
```sh
# Build Docker image
alpha build docker

# Tag and push (manual)
docker tag my-workspace:latest your-registry/my-workspace:latest
docker push your-registry/my-workspace:latest
```

**Kubernetes deployment:**
```sh
# Update Helm values
vim helmchart/values.yaml

# Deploy with Helm
helm install my-app ./helmchart \
  --namespace alpha \
  --create-namespace \
  --set image.repository=your-registry/my-workspace \
  --set image.tag=latest
```

---

### Iterative Development Pattern

```
┌────────────────────────────────────────────────┐
│                                                │
│  1. Edit component code                       │
│  2. Browser auto-reloads (HMR)                │
│  3. Test in browser                           │
│  4. Repeat steps 1-3                          │
│                                                │
└────────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────┐
│                                                │
│  5. Build for production                      │
│  6. Publish to marketplace                    │
│  7. Deploy to production                      │
│                                                │
└────────────────────────────────────────────────┘
```

---

## Best Practices

### 1. Component Design

**✅ DO:**
- Keep components small and focused
- Use semantic HTML
- Implement proper accessibility (ARIA labels, keyboard navigation)
- Use Lit's reactive properties for state management
- Dispatch custom events for parent communication
- Document attributes with clear labels and placeholders

**❌ DON'T:**
- Create monolithic components with too many responsibilities
- Use global state directly (use modules instead)
- Manipulate DOM directly (use Lit templates)
- Forget to clean up event listeners in `disconnectedCallback`

**Example good component:**
```typescript
@AlphaComponent({
    selector: 'comp-user-avatar',
    label: 'User Avatar',
    category: 'Display'
})
export class UserAvatar extends LitElement {
    @AlphaAttribute({
        type: ATTRIBUTE_TYPE.PROPERTY,
        uiType: UI_TYPE.INPUT,
        label: 'User Name',
        fieldMappings: 'userName'
    })
    @property({ type: String })
    userName = '';

    @AlphaAttribute({
        type: ATTRIBUTE_TYPE.PROPERTY,
        uiType: UI_TYPE.INPUT,
        label: 'Avatar URL',
        fieldMappings: 'avatarUrl'
    })
    @property({ type: String })
    avatarUrl = '';

    render() {
        return html`
            <div class="avatar">
                <img
                    src="${this.avatarUrl || '/default-avatar.png'}"
                    alt="${this.userName}"
                    @error="${this._handleImageError}"
                />
                <span>${this.userName}</span>
            </div>
        `;
    }

    _handleImageError(e) {
        e.target.src = '/default-avatar.png';
    }
}
```

---

### 2. Module Design

**✅ DO:**
- Use modules for shared logic and services
- Implement proper error handling
- Use TypeScript for type safety
- Provide clear method documentation
- Return promises for async operations

**❌ DON'T:**
- Store component-specific logic in modules
- Use modules for UI rendering
- Create circular dependencies between modules

**Example good module:**
```javascript
class ApiClient {
    constructor() {
        this.baseUrl = '';
        this.token = null;
    }

    init() {
        this.baseUrl = alpha.config.apiUrl;
        this.token = alpha.auth.getToken();
    }

    /**
     * Fetch data from API endpoint
     * @param {string} endpoint - API endpoint path
     * @param {Object} options - Fetch options
     * @returns {Promise<any>}
     */
    async fetch(endpoint, options = {}) {
        try {
            const response = await fetch(`${this.baseUrl}${endpoint}`, {
                ...options,
                headers: {
                    'Authorization': `Bearer ${this.token}`,
                    ...options.headers
                }
            });

            if (!response.ok) {
                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
            }

            return await response.json();
        } catch (error) {
            console.error('API fetch error:', error);
            throw error;
        }
    }
}

alpha.registerPlugins('mod-api-client', new ApiClient());
```

---

### 3. Attribute Configuration

**✅ DO:**
- Use meaningful labels and categories
- Provide helpful placeholder text
- Set sensible default values
- Use appropriate UI types for data types
- Group related attributes with categories

**❌ DON'T:**
- Create too many attributes (keep it simple)
- Use vague labels like "Value" or "Data"
- Skip default values
- Use complex field mappings unnecessarily

**Example good attribute configuration:**
```typescript
// Good: Clear, well-documented attribute
@AlphaAttribute({
    type: ATTRIBUTE_TYPE.PROPERTY,
    uiType: UI_TYPE.DROPDOWN,
    label: 'Button Size',
    category: 'Appearance',
    placeholder: 'Select size',
    defaultValue: 'medium',
    options: [
        { displayText: 'Small', value: 'small' },
        { displayText: 'Medium', value: 'medium' },
        { displayText: 'Large', value: 'large' }
    ],
    fieldMappings: 'size'
})
@property({ type: String })
size = 'medium';
```

---

### 4. Version Management

**Semantic Versioning Guidelines:**
- **Patch (1.0.0 → 1.0.1)**: Bug fixes, no API changes
- **Minor (1.0.1 → 1.1.0)**: New features, backward compatible
- **Major (1.1.0 → 2.0.0)**: Breaking changes

**Best practices:**
```sh
# Bug fix
alpha publish my-component --version-type patch

# New attribute added
alpha publish my-component --version-type minor

# Attribute removed or renamed
alpha publish my-component --version-type major
```

---

### 5. Asset Management

**Icon requirements:**
- Format: PNG recommended
- Size: 256x256px minimum
- Transparent background
- Simple, recognizable design

**Screenshot requirements:**
- Format: PNG or JPG
- Size: 1200x800px recommended
- Show component in use
- Multiple views (desktop, mobile)

**Organization:**
```
packages/my-component/
└── assets/
    ├── icon/
    │   └── icon.png           # 256x256px
    └── images/
        ├── desktop-view.png   # 1200x800px
        ├── mobile-view.png    # 750x1334px
        └── tablet-view.png    # 1024x768px
```

---

### 6. Code Organization

**Recommended structure:**
```typescript
// 1. Imports
import { LitElement, html } from 'lit';
import { property } from 'lit/decorators.js';
import { AlphaAttribute, ATTRIBUTE_TYPE, UI_TYPE } from '@jatahworx/alpha-annotations-lib';

// 2. Decorators
@AlphaComponent({...})
@adoptAlphaCommonStyle()

// 3. Class definition
export class MyComponent extends LitElement {
    // 3.1. Static members
    static styles = componentStyles;

    // 3.2. Decorated properties (public first)
    @AlphaAttribute({...})
    @property({ type: String })
    publicProp = '';

    // 3.3. Non-decorated properties (private)
    private _internalState = null;

    // 3.4. Lifecycle methods
    connectedCallback() { super.connectedCallback(); }
    disconnectedCallback() { super.disconnectedCallback(); }

    // 3.5. Render method
    render() { return html``; }

    // 3.6. Event handlers (decorated)
    @AlphaAttribute({...})
    handleEvent() {}

    // 3.7. Private methods
    private _helperMethod() {}
}
```

---

## Docker & Kubernetes Deployment

### Docker Deployment

#### Dockerfile (Auto-generated)
```dockerfile
FROM node:20-alpine3.19

WORKDIR /usr/src/app

COPY plugins-server ./plugins-server
COPY package*.json ./
COPY .npmrc ./

RUN npm ci --omit=dev

EXPOSE 3000

CMD ["node", "index.js"]
```

#### Build and Run
```sh
# Build image
alpha build docker
# or manually:
docker build -t my-workspace:latest .

# Run container
docker run -p 3000:3000 \
  -e PORT=3000 \
  -e BASE_PATH=/plugins-service \
  -e PLUGIN_DIR_ROOT=plugins \
  my-workspace:latest

# Access
curl http://localhost:3000/plugins-service/ping
```

#### Multi-stage Build (Optimization)
```dockerfile
# Build stage
FROM node:20-alpine3.19 AS builder
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build

# Production stage
FROM node:20-alpine3.19
WORKDIR /usr/src/app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/plugins-server ./plugins-server
COPY --from=builder /app/package*.json ./
RUN npm ci --omit=dev
EXPOSE 3000
CMD ["node", "index.js"]
```

---

### Kubernetes Deployment

#### Helm Chart Structure
```
helmchart/
├── Chart.yaml              # Chart metadata
├── values.yaml             # Configuration values
└── templates/
    ├── deployment.yaml     # Pod deployment
    ├── service.yaml        # Service definition
    ├── ingress.yaml        # Ingress rules
    ├── configmap.yaml      # Environment config
    └── _helpers.tpl        # Template helpers
```

#### values.yaml (Configuration)
```yaml
replicaCount: 2

image:
  repository: docker.neutrinos.co/my-workspace
  tag: "latest"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80
  targetPort: 3000

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: plugins.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: plugins-tls
      hosts:
        - plugins.example.com

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

env:
  PORT: "3000"
  BASE_PATH: "/plugins-service"
  PLUGIN_DIR_ROOT: "plugins"

livenessProbe:
  httpGet:
    path: /ping
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ping
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5
```

#### Deploy with Helm
```sh
# Create namespace
kubectl create namespace alpha

# Install chart
helm install my-app ./helmchart \
  --namespace alpha \
  --values ./helmchart/values.yaml

# Upgrade
helm upgrade my-app ./helmchart \
  --namespace alpha \
  --values ./helmchart/values.yaml

# Uninstall
helm uninstall my-app --namespace alpha

# Check status
kubectl get pods -n alpha
kubectl get svc -n alpha
kubectl get ingress -n alpha
```

#### Health Checks
```yaml
# Liveness probe (restart if fails)
livenessProbe:
  httpGet:
    path: /ping
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

# Readiness probe (remove from load balancer if fails)
readinessProbe:
  httpGet:
    path: /ping
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 2
```

---

## Troubleshooting

### Common Issues & Solutions

#### 1. Command not found: alpha
**Problem:** CLI not accessible globally

**Solution:**
```sh
# Reinstall globally
npm install -g @jatahworx/alpha-cli

# Check installation
which alpha
npm list -g @jatahworx/alpha-cli

# Add to PATH if needed (macOS/Linux)
export PATH="$PATH:$(npm prefix -g)/bin"
```

---

#### 2. Not a valid workspace directory
**Problem:** Command requires valid workspace but can't find `plugin.json`

**Solution:**
```sh
# Check current directory
ls -la
# Should see plugin.json and package.json

# If missing, create workspace
cd ..
alpha new my-workspace
cd my-workspace

# Or ensure plugin.json exists
echo '{"name":"my-workspace","componentSelectorPrefix":"comp","moduleSelectorPrefix":"mod"}' > plugin.json
```

---

#### 3. Authentication failed
**Problem:** Unable to authenticate with marketplace

**Solutions:**
```sh
# 1. Check .env file exists and has correct credentials
cat .env
# Should show: PORT, ISSUER_URL, CLIENT_ID, CLIENT_SECRET

# 2. Verify network connectivity
curl https://ids.neutrinos.co/.well-known/openid-configuration

# 3. Clear old auth tokens
rm ~/.alphaconfigs/auth.json

# 4. Retry login
alpha auth login

# 5. Check port not in use
lsof -i :32231
# If port occupied, change PORT in .env
```

---

#### 4. Build errors

**Problem:** Build fails with TypeScript errors

**Solutions:**
```sh
# 1. Check TypeScript configuration
cat tsconfig.json
# Ensure experimentalDecorators: true

# 2. Install dependencies
npm install

# 3. Clear cache and rebuild
rm -rf node_modules package-lock.json
npm install
npm run build

# 4. Check for syntax errors
npx tsc --noEmit

# 5. Verify Lit imports
# Ensure: import { LitElement } from 'lit';
# Not: import { LitElement } from 'lit-element'; (old version)
```

---

#### 5. Port already in use

**Problem:** Dev server port occupied

**Solutions:**
```sh
# 1. Use different port
alpha start --port 8080

# 2. Find process using port
lsof -i :6969
# or
netstat -tuln | grep 6969

# 3. Kill process
kill -9 <PID>

# 4. Change default port in package.json scripts
"start": "alpha start --port 8080"
```

---

#### 6. Component not rendering

**Problem:** Component appears blank in browser

**Checklist:**
```typescript
// 1. Verify custom element defined
customElements.get('comp-my-component');  // Should not be undefined

// 2. Check render method returns template
render() {
    return html`<div>Content</div>`;  // ✅
    // Not: return '<div>Content</div>';  // ❌
}

// 3. Verify styles are applied
static styles = componentStyles;  // ✅
// Not: static style = componentStyles;  // ❌ (typo)

// 4. Check browser console for errors
// Open DevTools > Console

// 5. Verify selector in HTML
<comp-my-component></comp-my-component>  // ✅
// Not: <my-component></my-component>  // ❌
```

---

#### 7. Attribute not appearing in builder

**Problem:** Decorated attribute doesn't show in builder UI

**Checklist:**
```typescript
// 1. Verify decorator import
import { AlphaAttribute, ATTRIBUTE_TYPE, UI_TYPE } from '@jatahworx/alpha-annotations-lib';

// 2. Check decorator syntax
@AlphaAttribute({
    type: ATTRIBUTE_TYPE.PROPERTY,  // ✅ Use constant
    // Not: type: 'property',  // ❌ String literal
    uiType: UI_TYPE.INPUT,
    label: 'My Property',
    fieldMappings: 'myProperty'
})
@property({ type: String })  // ✅ Lit decorator required
myProperty = '';

// 3. Verify experimentalDecorators enabled
// In tsconfig.json: "experimentalDecorators": true

// 4. Rebuild component
alpha build plugins my-component
```

---

#### 8. Publish fails

**Problem:** Unable to publish to marketplace

**Solutions:**
```sh
# 1. Verify authentication
alpha auth state

# 2. Check package built successfully
ls packages/my-component/dist/
# Should contain .js and .d.ts files

# 3. Validate package.json
cat packages/my-component/package.json
# Must have: name, version

# 4. Ensure not deprecated
# Check package.json for "deprecated": true

# 5. Verify icon/images exist
ls packages/my-component/assets/icon/
ls packages/my-component/assets/images/

# 6. Check network connectivity
curl https://alpha.neutrinos-apps.com/marketplace-headless/api/packages

# 7. Review error message
# Common errors:
# - "Package already exists": Use --version-type
# - "Unauthorized": Run alpha auth login
# - "Invalid icon": Check file path and format
```

---

#### 9. Module not accessible

**Problem:** Cannot access module via `alpha['mod-my-module']`

**Checklist:**
```javascript
// 1. Verify registration
alpha.registerPlugins('mod-my-module', new MyModule());  // ✅
// Not: alpha.plugins['mod-my-module'] = new MyModule();  // ❌

// 2. Check module ID matches selector prefix
// In plugin.json: "moduleSelectorPrefix": "mod"
// Module ID must start with "mod-"

// 3. Import module in index.ts
import './packages/my-module/index.js';

// 4. Check console for registration confirmation
// Should see: "Plugin registered..."

// 5. Verify alpha object exists
console.log(globalThis.alpha);  // Should be defined
```

---

#### 10. Docker build fails

**Problem:** Docker image build errors

**Solutions:**
```sh
# 1. Verify Dockerfile exists
ls Dockerfile

# 2. Check plugins-server directory
ls plugins-server/

# 3. Build plugins first
alpha build plugins

# 4. Verify .npmrc exists (if using private registry)
ls .npmrc

# 5. Check Docker daemon running
docker info

# 6. Review build logs
alpha build docker --verbose

# 7. Manual build with detailed output
docker build -t my-workspace:latest . --progress=plain
```

---

## API Reference

### CLI Commands Summary

| Command | Alias | Arguments | Options | Description |
|---------|-------|-----------|---------|-------------|
| `new <name>` | - | `<name>` | - | Create workspace |
| `generate component <name>` | `g c` | `<name>` | `-d` | Generate component |
| `generate module <name>` | `g m` | `<name>` | `-d` | Generate module |
| `generate attribute [component]` | `g a` | `[component]` | `-t -u -l -e -c -p -d -o -f -n` | Generate attribute |
| `build <type> [plugin]` | - | `<type> [plugin]` | - | Build plugins/docker |
| `start` | - | - | `-p` | Start dev server |
| `serve` | - | - | - | Start plugin server |
| `auth login` | - | - | - | Authenticate |
| `auth state` | - | - | - | Check auth status |
| `publish [package]` | - | `[package]` | `-t -d -i -m` | Publish package |
| `deprecate [package]` | - | `[package]` | `-y` | Deprecate package |

### Decorator Reference

#### @AlphaComponent
```typescript
@AlphaComponent({
    componentName: string;      // Component identifier
    componentVersion: string;   // Semantic version
    label: string;              // Display name
    selector: string;           // Custom element tag
    category?: string;          // Builder category
    icon?: string;              // Icon filename
})
```

#### @AlphaAttribute
```typescript
@AlphaAttribute({
    type: ATTRIBUTE_TYPE;       // PROPERTY | EVENT | VALIDATION
    uiType?: UI_TYPE;          // Input control type
    label: string;              // Display label
    event?: string;             // Event name (for EVENT type)
    category?: string;          // Grouping category
    placeholder?: string;       // Placeholder text
    defaultValue?: any;         // Default value
    options?: any;              // Control-specific options
    fieldMappings?: string | object;  // Property mapping
    validation?: object;        // Validation rules
})
```

#### @adoptAlphaCommonStyle
```typescript
@adoptAlphaCommonStyle()
// Applies global Alpha styles to component
```

### Constants Reference

#### ATTRIBUTE_TYPE
```typescript
enum ATTRIBUTE_TYPE {
    PROPERTY = 'property',
    EVENT = 'event',
    VALIDATION = 'validation'
}
```

#### UI_TYPE
```typescript
enum UI_TYPE {
    INPUT = 'input',
    TOGGLE = 'toggle',
    DROPDOWN = 'dropdown',
    MULTI_SELECT = 'multi-select',
    TYPED_INPUT = 'typed-input',
    RANGE = 'range',
    COLOR_PICKER = 'color-picker',
    DATA_SOURCE = 'data-source',
    DATA_SET = 'data-set',
    TABLE_ACTIONS = 'table-actions',
    DATA_MAPPING = 'data-mapping'
}
```

---

## Contributing

Alpha CLI is maintained by **JataHworx**. We welcome contributions!

### Development Setup

```sh
# Clone repository (if open source)
git clone https://github.com/jatahworx/alpha-cli.git
cd alpha-cli

# Install dependencies
npm install

# Link for local development
npm link

# Test changes
alpha --version
```

### Code Standards

- **Language**: TypeScript for new features, JavaScript for templates
- **Formatting**: Prettier (configured automatically)
- **Linting**: ESLint (if configured)
- **Commits**: Conventional Commits format

### Commit Message Format
```
<type>(<scope>): <subject>

<body>

<footer>
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes
- `refactor`: Code refactoring
- `test`: Test updates
- `chore`: Build/tool changes

**Example:**
```
feat(generate): add support for TypeScript modules

- Update module template to use TypeScript
- Add type definitions to generated code
- Update documentation

Closes #123
```

### Pull Request Process

1. Fork the repository
2. Create feature branch: `git checkout -b feat/my-feature`
3. Make changes and commit: `git commit -am 'feat: add new feature'`
4. Push to branch: `git push origin feat/my-feature`
5. Open Pull Request with description of changes

---

## License

ISC

---

## Additional Resources

- **Attribute Documentation**: See [ATTRIBUTE.md](ATTRIBUTE.md) in workspace
- **Lit Documentation**: https://lit.dev
- **TypeScript Handbook**: https://www.typescriptlang.org/docs/
- **Vite Documentation**: https://vitejs.dev
- **Alpha Platform**: https://alpha.neutrinos-apps.com
- **JataHworx**: Contact for enterprise support

---

## Version History

### 1.0.19 (Current - 2024)
- ✅ Component and module generation with templates
- ✅ Comprehensive attribute system with 11 UI types
- ✅ OpenID Connect authentication
- ✅ Build system for plugins and Docker
- ✅ Vite-powered development server
- ✅ Publish and deprecate commands
- ✅ Workspace validation and management
- ✅ Interactive CLI prompts
- ✅ Automatic code formatting
- ✅ Kubernetes Helm chart support

### Future Roadmap
- 🔜 Component testing utilities
- 🔜 Plugin versioning and rollback
- 🔜 Theme customization
- 🔜 Plugin marketplace browser
- 🔜 Auto-documentation generation
- 🔜 Performance profiling tools

---

## Support

For issues, questions, or feature requests:

- **Documentation**: See [ATTRIBUTE.md](ATTRIBUTE.md) in your workspace
- **GitHub Issues**: Report bugs and request features
- **Email**: support@jatahworx.com
- **Enterprise Support**: Available for production deployments

---

**Built with ❤️ by JataHworx**

*Making plugin development simple, fast, and enjoyable.*