@ollie-shop/cli 0.3.3 → 1.0.0

package/README.md

@@ -1,711 +0,0 @@
-# @ollie-shop/cli
-
-Internal CLI for managing Ollie Shop components, functions, store versions, and projects.
-
-## Quick Start
-
-```bash
-# Run CLI from monorepo root
-pnpm --filter @ollie-shop/cli cli
-
-# Or from the CLI package directory
-cd packages/cli
-npm run cli
-
-# With arguments
-npm run cli -- component create --name my-component
-npm run cli -- store-version create --store 123e4567-e89b-12d3-a456-426614174000 --name "Holiday Theme"
-
-# Enable debug output
-DEBUG=ollie:* npm run cli -- login
-```
-
-## Features Overview
-
-### 🏪 Store Version Management
-- Create, manage, and deploy different store configurations
-- A/B testing and gradual rollouts
-- Template-based version creation
-
-### 🧩 Component System
-- Create React components for checkout customization
-- Build, validate, and deploy components
-- Slot-based component architecture (header, main, sidebar, footer)
-- **NEW**: Interactive component creation wizard
-- **NEW**: Rich deployment progress visualization
-
-### ⚡ Function Management
-- Create serverless functions for checkout logic
-- Event-driven architecture (cart, customer, shipping, payment, order)
-- Local testing and cloud deployment
-
-### 📋 Template System
-- Pre-built checkout templates
-- Apply templates to store versions
-- Preview before applying
-
-### 🚀 Enhanced Developer Experience (Phase 1)
-- **Smart Error Recovery**: Actionable suggestions for common errors
-- **Context-Aware Commands**: Shows relevant commands based on current directory
-- **Interactive Mode**: Step-by-step wizards for complex operations
-- **Rich Progress Visualization**: Detailed deployment progress with stats
-
-## Architecture Overview
-
-### Command Flow
-
-```
-User Input
-    │
-    ▼
-CLI Entry (src/index.ts)
-    │
-    ├─> Command Parser (Commander.js)
-    │   └─> Global Options (--verbose, --quiet, etc.)
-    │
-    ├─> Command Registration (src/commands/*.ts)
-    │   └─> Option Schemas (Zod validation)
-    │
-    ├─> Action Execution (src/actions/*.ts)
-    │   ├─> Console Output (utils/cliConsole.ts)
-    │   ├─> Spinner Management
-    │   └─> Lazy Load @ollie-shop/core
-    │
-    └─> Error Handling
-        └─> Recovery Suggestions
-```
-
-### Core Files
-
-#### `src/index.ts` - CLI Entry Point
-```typescript
-export class OllieShopCLI {
-  private program: Command;
-  
-  constructor() {
-    // Sets up Commander instance
-    // Registers global options
-    // Configures error handling
-  }
-  
-  async run(argv: string[]): Promise<void> {
-    // Parses arguments
-    // Validates global options
-    // Executes command
-  }
-}
-```
-
-#### `src/commands/` - Command Registration
-Each command file exports a function that:
-1. Creates a Commander command
-2. Defines options with Zod schemas
-3. Binds to action handler
-
-```typescript
-// Example: component.ts
-export function registerComponentCommands(program: Command) {
-  const cmd = program.command('component');
-  
-  cmd.command('create')
-     .option('--name <name>', 'Component name')
-     .option('--slot <slot>', 'Component slot')
-     .action(async (options) => {
-       const validated = componentOptionsSchema.parse(options);
-       await componentActions.createComponent(validated, cliConsole);
-     });
-}
-```
-
-#### `src/actions/` - Business Logic Delegation
-Actions handle:
-- User feedback (spinners, messages)
-- Core service delegation
-- Error transformation
-
-```typescript
-// Example: component.actions.ts
-export async function createComponent(options: ComponentOptions, cliConsole: CliConsole) {
-  const spinner = cliConsole.spinner('Creating component...');
-  try {
-    // Lazy load core service
-    const { createComponent: createComponentService } = await import('@ollie-shop/core');
-    
-    const result = await createComponentService(options);
-    spinner.succeed('Component created');
-    
-    // Show next steps
-    cliConsole.nextSteps('Next steps', [
-      { description: 'Navigate to directory', command: `cd ${result}` },
-      { description: 'Install dependencies', command: 'npm install' },
-      { description: 'Start development', command: 'npm run dev' }
-    ]);
-  } catch (error) {
-    spinner.fail('Failed to create component');
-    throw error;
-  }
-}
-```
-
-### CLI Console Utility
-
-The `cliConsole` utility (`src/utils/cliConsole.ts`) provides consistent output formatting:
-
-```typescript
-interface CliConsole {
-  // Basic output
-  log(message: string): void;
-  error(message: string): void;
-  warn(message: string): void;
-  info(message: string): void;
-  success(message: string): void;
-  
-  // Formatting
-  dim(message: string): void;
-  bold(message: string): void;
-  
-  // Complex output
-  list(items: string[]): void;
-  table(data: any[]): void;
-  json(data: any): void;
-  
-  // Interactive
-  spinner(message: string): Ora;
-  confirm(message: string): Promise<boolean>;
-  prompt(questions: any[]): Promise<any>;
-}
-```
-
-Usage patterns:
-```typescript
-// Simple messages
-cliConsole.success('✓ Build completed');
-cliConsole.error('✗ Validation failed');
-
-// Formatted lists
-cliConsole.info('Available templates:');
-cliConsole.list(['default', 'grocery', 'sales']);
-
-// Spinners for async operations
-const spinner = cliConsole.spinner('Building...');
-await longOperation();
-spinner.succeed('Build complete');
-
-// Interactive prompts
-const confirm = await cliConsole.confirm('Deploy to production?');
-```
-
-### Authentication Flow
-
-```typescript
-// src/actions/auth.actions.ts
-1. Start local server on port 7777
-2. Open browser to auth endpoint
-3. Wait for callback with credentials
-4. Save to ~/.ollie-shop/credentials.json
-5. Return user info (currently mocked)
-```
-
-### Error Handling
-
-Custom error class with recovery suggestions:
-
-```typescript
-class OllieShopCLIError extends Error {
-  constructor(
-    message: string,
-    public context?: Record<string, any>,
-    public suggestions?: string[]
-  ) {
-    super(message);
-  }
-}
-
-// Usage
-throw new OllieShopCLIError(
-  'Component not found',
-  { path: './src/components' },
-  [
-    'Run "ollieshop component create" to create a new component',
-    'Check that you are in the correct directory'
-  ]
-);
-```
-
-### Input Validation & DX Enhancements
-
-All CLI commands now feature enhanced validation with helpful error messages:
-
-#### Component Name Validation
-```bash
-# ❌ Invalid: uppercase letters
-$ ollieshop component create --name TestComponent
-Error: Invalid component name: Must be lowercase with hyphens only
-Examples: header-nav, shopping-cart, product-list
-
-# ✅ Valid: kebab-case
-$ ollieshop component create --name test-component
-```
-
-#### Function Validation
-```bash
-# ❌ Invalid: wrong invocation type
-$ ollieshop function create --name test --invocation invalid
-Error: Invalid function invocation type
-Valid invocations: request, response
-
-# ✅ Valid: proper invocation
-$ ollieshop function create --name validate-order --invocation request
-```
-
-#### UUID Validation (Store Versions)
-```bash
-# ❌ Invalid: not a UUID
-$ ollieshop store-version create --store abc123 --name v2
-Error: Invalid store ID: Must be a valid store ID
-Example: 123e4567-e89b-12d3-a456-426614174000
-
-# ✅ Valid: proper UUID format
-$ ollieshop store-version create --store 123e4567-e89b-12d3-a456-426614174000 --name v2
-```
-
-#### Validation Features
-- **Early validation**: Errors caught at parse time, not after processing
-- **Helpful examples**: Error messages include valid examples
-- **Format hints**: Shows expected formats (kebab-case, UUID, etc.)
-- **Enum suggestions**: Lists all valid options for enums
-- **Required fields**: Clear indication when fields are missing
-- **Help integration**: `--help` shows examples for each command
-
-### Component Validation
-
-The `component validate` command checks for:
-- **Required files**: `index.tsx`, `package.json`, `meta.json`
-- **Valid TypeScript/JavaScript**: Source files compile without errors
-- **Component metadata**: Valid meta.json structure
-- **Package dependencies**: All required dependencies present
-
-```bash
-# Validate a component (components are created in ./components/<name>/)
-$ ollieshop component validate --path ./components/my-component
-
-# Or validate from within component directory (automatic path detection)
-$ cd components/my-component
-$ ollieshop component validate
-```
-
-### Automatic Path Detection
-
-The CLI now automatically detects when you're inside a component or function directory:
-
-```bash
-# Navigate to component directory
-$ cd components/header-nav
-
-# These commands automatically use the current directory
-$ ollieshop component validate   # No --path needed
-$ ollieshop component build      # No --path needed
-$ ollieshop component deploy     # No --path needed
-
-# Same works for functions
-$ cd functions/validate-order
-$ ollieshop function validate    # No --path needed
-$ ollieshop function build       # No --path needed
-$ ollieshop function test        # No --path needed
-$ ollieshop function deploy      # No --path needed
-```
-
-The CLI detects the project type by looking for:
-- **Components**: `meta.json` with type "component" or presence of `index.tsx`/`index.jsx`
-- **Functions**: `meta.json` with type "function" or presence of `index.ts`/`index.js`
-
-If you're not in the right directory type, you'll get helpful error messages:
-```bash
-# In a function directory trying to run component command
-$ ollieshop component validate
-Error: Current directory appears to be a function, not a component.
-Please navigate to a component directory or specify --path
-
-# In project root
-$ ollieshop component validate
-Error: No component found in current directory.
-Try navigating to a component directory:
-  cd components/<component-name>
-Or specify the path:
-  --path ./components/<component-name>
-```
-
-### 🚀 Enhanced Developer Experience Features
-
-#### Smart Error Recovery
-When errors occur, the CLI now provides actionable suggestions:
-
-```bash
-$ ollieshop component create --name MyComponent
-
-❌ Component name validation failed
-
-💡 Possible solutions:
-  1. Use lowercase letters and hyphens only (e.g., header-nav)
-  2. Examples: shopping-cart, product-list
-
-📍 Context:
-  Current directory: /Users/dev/project
-```
-
-#### Context-Aware Command Suggestions
-Running `ollieshop` without arguments shows context-aware suggestions:
-
-```bash
-$ ollieshop
-
-📍 Current location:
-  You're in a component directory: header-nav
-
-Common commands for this component:
-  validate   Check component validity
-  build      Build for production
-  dev        Start development server
-  deploy     Deploy to cloud
-
-Recent commands:
-  ollieshop validate --fix (2 min ago)
-  ollieshop build --watch (1 hour ago)
-
-💡 Tip: Run 'ollieshop dev' to start developing this component
-```
-
-#### Interactive Mode
-Use `--interactive` flag for step-by-step guidance:
-
-```bash
-$ ollieshop component create --interactive
-
-🎨 Component Creation Wizard
-
-? Component name: shopping-cart
-? Component slot: › 
-❯ Header
-  Main (default)
-  Sidebar  
-  Footer
-
-? Language: › 
-❯ TypeScript (recommended)
-  JavaScript
-
-? Include test files? (Y/n)
-
-[Preview] This will run: ollieshop component create --name shopping-cart --slot header
-
-? Create this component? (Y/n)
-```
-
-#### Rich Progress Visualization
-Deployment now shows detailed progress:
-
-```bash
-$ ollieshop component deploy --wait
-
-🚀 Starting deployment...
-
-🔍 Validating      ████████████████████ 100% | 0.3s ✓
-🔨 Building        ███████████░░░░░░░░░  60% | 1.2s | Bundling dependencies...
-⚡ Optimizing      ░░░░░░░░░░░░░░░░░░░░   0% | Queued
-🚀 Deploying       ░░░░░░░░░░░░░░░░░░░░   0% | Queued
-✅ Verifying       ░░░░░░░░░░░░░░░░░░░░   0% | Queued
-
-📊 Build Stats:
-  • Bundle size: 127KB (gzipped: 42KB)
-  • Tree shaking: Removed 18 unused exports
-  • Dependencies: 12 (3 updated)
-
-✅ Deployment completed successfully!
-
-Deployment URL: https://cdn.ollie.shop/components/header-nav-v1.2.0.js
-Total time: 3.4s
-```
-
-### Function Validation
-
-The `function validate` command checks for:
-- **Required files**: `index.ts` or `index.js`, `package.json`, `meta.json`
-- **Valid exports**: Handler function properly exported
-- **Function metadata**: Valid meta.json structure
-- **Package dependencies**: All required dependencies present
-
-```bash
-# Validate a function (functions are created in ./functions/<name>/)
-$ ollieshop function validate --path ./functions/my-function
-
-# Or validate from within function directory
-$ cd functions/my-function
-$ ollieshop function validate
-```
-
-## Command Implementation Status
-
-### ✅ Fully Implemented & Delegated to Core
-These commands are fully functional and delegate to `@ollie-shop/core`:
-
-**Store Version Management**
-- `store-version create` - Create new store version
-- `store-version list` - List all versions for a store
-- `store-version get` - Get version details
-- `store-version activate/deactivate` - Toggle version status
-- `store-version set-default` - Set default version
-- `store-version clone` - Clone existing version
-- `store-version delete` - Delete version
-
-**Component Management**
-- `component create` - Create new component
-- `component build` - Build component
-- `component validate` - Validate component structure
-- `component deploy` - Deploy component with build status polling
-- `component deploy-status` - Check deployment status
-
-**Function Management**
-- `function create` - Create new function
-- `function build` - Build function
-- `function validate` - Validate function structure
-- `function test` - Test function locally
-- `function deploy` - Deploy function with build status polling
-- `function deploy-status` - Check deployment status
-
-**Template Management**
-- `template list` - List available templates
-- `template apply` - Apply template to version
-- `template preview` - Preview template
-
-**Project Management**
-- `project init` - Initialize new project
-- `project info` - Show project information
-- `project link` - Link to existing project
-
-### 🔄 Partially Implemented
-These commands have basic functionality but need database integration:
-- `component list` - Shows empty list (needs Supabase)
-- `function list` - Shows empty list (needs Supabase)
-
-### 🔧 CLI-Only Features
-- `login` - OAuth flow with local server
-- `whoami` - Shows current user (mocked)
-- `docs` - Opens documentation
-- `help` - Shows command help
-- `version` - Shows CLI version
-
-## Testing the CLI Locally
-
-### Manual Testing Checklist
-
-```bash
-# 1. Test authentication
-npm run cli -- login
-npm run cli -- whoami
-
-# 2. Test store version commands
-npm run cli -- store-version create --store 123e4567-e89b-12d3-a456-426614174000 --name "Test Version"
-npm run cli -- store-version list --store 123e4567-e89b-12d3-a456-426614174000
-npm run cli -- store-version get <version-id>
-npm run cli -- store-version activate <version-id>
-npm run cli -- store-version set-default <version-id>
-
-# 3. Test component commands
-npm run cli -- component create --name test-component --slot header
-# Note: Components are created in ./components/<name>/ directory
-npm run cli -- component validate --path ./components/test-component
-npm run cli -- component build --path ./components/test-component
-npm run cli -- component deploy --path ./components/test-component
-npm run cli -- component deploy-status <build-id>
-npm run cli -- component list
-
-# 4. Test function commands
-npm run cli -- function create --name test-function --event cart --timing before
-# Note: Functions are created in ./functions/<name>/ directory
-npm run cli -- function validate --path ./functions/test-function
-npm run cli -- function build --path ./functions/test-function
-npm run cli -- function test --path ./functions/test-function
-npm run cli -- function deploy --path ./functions/test-function
-npm run cli -- function deploy-status <build-id>
-npm run cli -- function list
-
-# 5. Test template commands
-npm run cli -- template list
-npm run cli -- template preview default
-npm run cli -- template apply minimal --version <version-id>
-
-# 6. Test project commands
-npm run cli -- project init test-project --template default
-npm run cli -- project info
-npm run cli -- project link <project-id>
-
-# 7. Test error handling
-npm run cli -- component create  # Missing required --name
-npm run cli -- invalid-command   # Unknown command
-
-# 8. Test global options
-npm run cli -- --verbose component create --name test-component
-npm run cli -- --quiet component build
-npm run cli -- --no-color component list
-```
-
-### Debugging
-
-```bash
-# Enable debug output
-DEBUG=ollie:* npm run cli -- component create --name Test
-
-# Use Node debugger
-node --inspect-brk ./dist/bin/cli.js component create --name Test
-
-# Check generated files
-ls -la ~/.ollie-shop/
-cat ~/.ollie-shop/credentials.json
-```
-
-## Adding New Commands
-
-1. **Create command file** in `src/commands/`:
-```typescript
-// src/commands/newfeature.command.ts
-export const newFeatureCommand = (program: Command) => {
-  const cmd = program
-    .command('newfeature')
-    .description('New feature description');
-    
-  // Add subcommands
-  cmd.command('action')
-     .option('--param <value>', 'Parameter description')
-     .action(newFeatureActions.action);
-};
-```
-
-2. **Create action file** in `src/actions/`:
-```typescript
-// src/actions/newfeature.actions.ts
-export const action = async (options: NewFeatureOptions) => {
-  const spinner = cliConsole.spinner('Processing...');
-  
-  try {
-    // Delegate to core
-    const { NewFeatureService } = await import('@ollie-shop/core');
-    const service = new NewFeatureService();
-    await service.process(options);
-    
-    spinner.succeed('Complete');
-  } catch (error) {
-    spinner.fail('Failed');
-    throw error;
-  }
-};
-```
-
-3. **Register in main CLI**:
-```typescript
-// src/commands/index.ts
-export * from './newfeature.command';
-```
-
-## Core Integration Pattern
-
-The CLI follows a strict delegation pattern:
-
-```typescript
-// CLI Layer - User interaction only
-async function createComponent(options) {
-  // 1. Show spinner
-  const spinner = cliConsole.spinner('Creating...');
-  
-  try {
-    // 2. Lazy load core service
-    const { ComponentService } = await import('@ollie-shop/core');
-    
-    // 3. Delegate all logic to core
-    const service = new ComponentService();
-    const result = await service.create(options);
-    
-    // 4. Show success and next steps
-    spinner.succeed('Created');
-    showNextSteps(result);
-    
-  } catch (error) {
-    // 5. Handle errors with context
-    spinner.fail('Failed');
-    handleError(error);
-  }
-}
-```
-
-## Configuration Files
-
-### `ollie.json` Structure
-```json
-{
-  "storeId": "uuid",
-  "versionId": "uuid", 
-  "platform": "vtex",
-  "platformStoreId": "string",
-  "sessionId": "uuid",
-  "props": {},
-  "theme": {}
-}
-```
-
-### Credentials Storage
-```json
-// ~/.ollie-shop/credentials.json
-{
-  "accessToken": "jwt-token",
-  "refreshToken": "refresh-token",
-  "expiresAt": "2024-01-01T00:00:00Z"
-}
-```
-
-## Development Workflow
-
-```bash
-# 1. Make changes to CLI
-cd packages/cli
-vim src/commands/component.command.ts
-
-# 2. Build and test
-pnpm build
-npm run cli -- component create --name Test
-
-# 3. Test with core changes
-cd ../core
-pnpm build
-cd ../cli
-npm run cli -- component create --name Test
-
-# 4. Run tests (when implemented)
-pnpm test
-```
-
-## Known Issues & TODOs
-
-### High Priority
-1. Implement real authentication (currently returns mock user)
-2. Add Supabase integration for list commands
-3. Connect to AWS Builder service
-4. Implement dev server with Vite
-
-### Medium Priority
-1. Add comprehensive test suite
-2. Implement progress bars for long operations
-3. Add command aliases (e.g., `oc` for `ollieshop component`)
-4. Cache command results where appropriate
-
-### Low Priority
-1. Add shell completion
-2. Implement update notifications
-3. Add telemetry (with opt-out)
-4. Create interactive mode
-
-## Debugging Tips
-
-1. **Check core delegation**: Most issues are in `@ollie-shop/core`, not CLI
-2. **Validate schemas**: Zod errors show what's missing
-3. **Use verbose mode**: `--verbose` shows additional output
-4. **Check credentials**: `cat ~/.ollie-shop/credentials.json`
-5. **Clear state**: `rm -rf ~/.ollie-shop` to start fresh