@ollie-shop/cli 0.3.4 → 1.0.0

package/CLAUDE_CLI.md

@@ -1,265 +0,0 @@
-# Claude CLI Guidance
-
-## Core Architecture Principle
-
-The CLI is a **thin presentation layer** that delegates ALL business logic to `@ollie-shop/core`. 
-
-### Architecture Flow
-
-```
-User Input → CLI (presentation) → @ollie-shop/core (business logic) → External Services
-                ↓                            ↓
-          Format Output              Handles all integrations:
-          Show Progress              - Supabase database
-          Display Errors             - AWS Builder service
-          Provide Next Steps         - File operations
-                                    - Validation logic
-```
-
-## Critical Rule: No Business Logic in CLI
-
-### ❌ NEVER do this in CLI:
-
-```typescript
-// BAD: Business logic in CLI
-import { createClient } from '@supabase/supabase-js';
-
-export class DatabaseService {
-  async listComponents() {
-    const supabase = createClient(...);
-    const { data } = await supabase.from('components').select();
-    return data;
-  }
-}
-```
-
-### ✅ ALWAYS do this:
-
-```typescript
-// GOOD: Delegate to core
-import { ComponentService } from '@ollie-shop/core';
-
-export const list = async (options: ListOptions) => {
-  const spinner = cliConsole.spinner('Loading components...');
-  
-  try {
-    const service = new ComponentService();
-    const components = await service.list(options);
-    
-    spinner.succeed();
-    cliConsole.table(components);
-  } catch (error) {
-    spinner.fail();
-    throw error;
-  }
-};
-```
-
-## What Belongs in CLI vs Core
-
-### CLI Package (`packages/cli/src/`)
-- **Command parsing** - Commander.js setup
-- **Option validation** - Zod schemas for CLI options
-- **User feedback** - Spinners, progress bars, tables
-- **Error formatting** - User-friendly error messages
-- **Authentication flow** - OAuth callback server
-- **File paths** - Resolve user-provided paths
-- **Next steps** - Guide users after operations
-
-### Core Package (`packages/core/src/services/`)
-- **All database operations** - Supabase queries
-- **Builder integration** - AWS CodeBuild client
-- **File operations** - Zip creation, validation
-- **Business validation** - Component/function rules
-- **API integrations** - External service calls
-- **State management** - Version handling
-- **Template rendering** - Component scaffolding
-
-## Current Core Services
-
-Based on the core package structure:
-
-```typescript
-// Available in @ollie-shop/core
-- ComponentService    // Component CRUD operations
-- FunctionService     // Function CRUD operations  
-- ProjectService      // Project initialization
-- TemplateService     // Template rendering
-
-// Need to be added to core (not CLI):
-- VersionService      // Version management
-- DatabaseService     // Supabase operations
-- BuilderService      // AWS Builder integration
-- OrganizationService // Org management
-- StoreService        // Store management
-```
-
-## Implementation Pattern
-
-### 1. CLI Action Structure
-
-```typescript
-// packages/cli/src/actions/component.actions.ts
-export const deploy = async (options: DeployOptions) => {
-  // 1. User feedback
-  const spinner = cliConsole.spinner('Deploying component...');
-  
-  try {
-    // 2. Resolve paths
-    const componentPath = path.resolve(options.path);
-    
-    // 3. Delegate to core
-    const { ComponentService } = await import('@ollie-shop/core');
-    const service = new ComponentService();
-    
-    const result = await service.deploy({
-      path: componentPath,
-      versionId: options.versionId
-    });
-    
-    // 4. Format output
-    spinner.succeed('Component deployed successfully');
-    
-    cliConsole.info('Deployment details:');
-    cliConsole.list([
-      `Build ID: ${result.buildId}`,
-      `Status: ${result.status}`,
-      `URL: ${result.url}`
-    ]);
-    
-    // 5. Next steps
-    cliConsole.dim('\nNext steps:');
-    cliConsole.list([
-      'View deployment status: ollieshop deploy status ' + result.buildId,
-      'Test component: ollieshop component test --id ' + result.componentId
-    ]);
-    
-  } catch (error) {
-    spinner.fail('Deployment failed');
-    
-    // 6. Error handling with suggestions
-    if (error instanceof BuildInProgressError) {
-      throw new OllieShopCLIError(
-        'A deployment is already in progress',
-        { componentId: error.componentId },
-        [
-          'Check status: ollieshop deploy status',
-          'Wait for completion or cancel the current build'
-        ]
-      );
-    }
-    
-    throw error;
-  }
-};
-```
-
-### 2. Core Service Pattern
-
-```typescript
-// packages/core/src/services/component.service.ts
-export class ComponentService {
-  constructor(
-    private db: DatabaseService,
-    private builder: BuilderService
-  ) {}
-  
-  async deploy(options: DeployOptions) {
-    // All business logic here
-    const component = await this.db.getComponent(options.versionId);
-    const zipFile = await this.createZip(options.path);
-    const build = await this.builder.createBuild({
-      type: 'component',
-      resourceId: component.id,
-      code: zipFile
-    });
-    
-    return {
-      buildId: build.id,
-      componentId: component.id,
-      status: build.status,
-      url: component.url
-    };
-  }
-}
-```
-
-## Services to Add to Core
-
-Based on the improvement plan, these services should be created in `@ollie-shop/core`, NOT in CLI:
-
-### 1. DatabaseService
-```typescript
-// packages/core/src/services/database.service.ts
-export class DatabaseService {
-  async listComponents(versionId: string);
-  async listFunctions(versionId: string);
-  async getComponent(componentId: string);
-  async updateComponent(id: string, data: Partial<Component>);
-  // ... all database operations
-}
-```
-
-### 2. BuilderService  
-```typescript
-// packages/core/src/services/builder.service.ts
-export class BuilderService {
-  async deployComponent(componentId: string, zipFile: File);
-  async deployFunction(functionId: string, zipFile: File);
-  async getBuildStatus(buildId: string);
-  async getBuildLogs(buildId: string);
-}
-```
-
-### 3. VersionService
-```typescript
-// packages/core/src/services/version.service.ts
-export class VersionService {
-  async create(storeId: string, options: CreateVersionOptions);
-  async list(storeId: string);
-  async setDefault(versionId: string);
-  async activate(versionId: string);
-  async delete(versionId: string);
-}
-```
-
-## Testing Strategy
-
-### CLI Tests
-Focus on:
-- Command parsing
-- Option validation  
-- Output formatting
-- Error message formatting
-- User flow (spinners, prompts)
-
-### Core Tests
-Focus on:
-- Business logic
-- Database operations
-- External service integration
-- Validation rules
-- Error conditions
-
-## Key Principles
-
-1. **CLI is disposable** - Could be replaced with a GUI without losing functionality
-2. **Core is essential** - Contains all business rules and integrations
-3. **Reusability** - Other tools (SDK, admin) can use core services
-4. **Testability** - Core services are easier to test without CLI layer
-5. **Maintainability** - Business logic changes happen in one place
-
-## Common Mistakes to Avoid
-
-1. **Don't create database queries in CLI** - Use core services
-2. **Don't implement validation logic in CLI** - Belongs in core
-3. **Don't call external APIs from CLI** - Core handles integrations
-4. **Don't manage state in CLI** - Core manages application state
-5. **Don't duplicate core functionality** - Always check if it exists first
-
-## Next Steps for Implementation
-
-1. **Audit existing core services** - See what's already available
-2. **Create missing services in core** - DatabaseService, BuilderService, etc.
-3. **Update CLI to use core services** - Remove any direct integrations
-4. **Add comprehensive tests** - Both CLI presentation and core logic