@newpeak/barista-cli 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,184 @@
+# Architecture Documentation
+
+## Project Overview
+
+Barista CLI is an AI-native command-line tool that bridges AI agents (Claude Code, etc.) with the Liberica production management SaaS and Arabica sales platform. It provides a unified interface for managing production orders, products, and related operations across both services.
+
+## Technical Stack
+
+| Component | Technology | Purpose |
+|-----------|------------|---------|
+| Language | TypeScript 5.4+ | Type safety, modern JS features |
+| CLI Framework | Commander.js 12 | Command parsing, help generation |
+| HTTP Client | Axios | API communication |
+| Auth Storage | Keytar | System keychain integration |
+| Config Storage | YAML (js-yaml) | Human-readable config files |
+| Output | Chalk + cli-table3 | Formatted CLI output |
+| Testing | Vitest | Unit and integration testing |
+
+## Architecture Decisions
+
+### 1. Direct HTTP Calls (NOT MCP)
+
+We use direct HTTP API calls instead of MCP (Model Context Protocol) for several reasons:
+
+- **Simplicity**: MCP adds unnecessary complexity for a CLI tool
+- **Control**: Direct HTTP gives full control over request/response handling
+- **Compatibility**: Works with any HTTP-capable environment
+- **Performance**: Lower overhead than protocol buffering
+
+### 2. Token-Based Auth (NOT OAuth2)
+
+Token-based authentication was chosen over OAuth2 because:
+
+- **CLI-First**: OAuth2 flows are browser-based, not suited for CLI
+- **Simplicity**: Token storage and refresh is straightforward
+- **Security**: Tokens stored in system keychain, not files
+- **Backend Constraints**: Cannot modify backend authentication flow
+
+### 3. JSON + Table Output (TTY Auto-Detection)
+
+Output format strategy:
+
+- **TTY Detected**: Show colored table output for human readability
+- **Pipe/Redirect**: Auto-switch to JSON for scripting and AI integration
+- **Explicit Flag**: `--json` flag forces JSON output regardless of TTY
+
+## Multi-Environment Support
+
+Barista CLI supports four environments:
+
+| Environment | Liberica URL Pattern | Arabica URL |
+|-------------|---------------------|-------------|
+| dev | `{tenant}-dev.newpeaksh.com` | arabica-dev.newpeaksh.com |
+| test | `{tenant}-test.newpeaksh.com` | arabica-test.newpeaksh.com |
+| prod-cn | `{tenant}.newpeaksh.com` | www.newpeaksh.com |
+| prod-jp | `{tenant}.newpeakjp.com` | members.newpeakjp.com |
+
+## Multi-Tenant Support
+
+Liberica is a multi-tenant system where each customer (tenant) has isolated data. The CLI supports:
+
+- **Tenant Switching**: `barista context use-tenant <name>`
+- **Per-Tenant Tokens**: Each tenant+environment combination has its own token
+- **URL Templating**: Tenant ID is injected into API URLs
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Barista CLI                              │
+├─────────────────────────────────────────────────────────────────┤
+│  bin/barista (entry point)                                      │
+│       │                                                          │
+│       ▼                                                          │
+│  src/index.ts (main)                                            │
+│       │                                                          │
+│       ├── configManager ──────────────────► ~/.barista/config.yaml
+│       │                                                          │
+│       ├── tokenManager ───────────────────► System Keychain     │
+│       │                                                          │
+│       ├── createContextCommand()                               │
+│       ├── createAuthCommand()                                   │
+│       ├── createLibericaCommand() ────────► Liberica API         │
+│       │                                     (Axios HTTP)        │
+│       └── createArabicaCommand() ────────► Arabica API           │
+│                                             (Axios HTTP)        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Module Structure
+
+```
+src/
+├── index.ts                 # Main entry, Commander setup
+├── commands/
+│   ├── context.ts          # Context management commands
+│   ├── auth.ts             # Authentication commands
+│   ├── liberica/
+│   │   └── index.ts        # Liberica service commands
+│   └── arabica/
+│       └── index.ts        # Arabica service commands
+├── core/
+│   ├── config/
+│   │   └── manager.ts      # Config loading/saving
+│   └── auth/
+│       └── token-manager.ts # Keychain token storage
+├── types/
+│   └── index.ts            # TypeScript interfaces
+└── utils/
+    └── (formatters, validators, etc.)
+```
+
+## Constraints
+
+**Critical Constraint**: Cannot modify backend code
+
+- Liberica and Arabica backend systems are external and immutable
+- CLI must work within existing API contracts
+- No backend changes can be requested to accommodate CLI needs
+- API responses must be handled as-is
+
+## Configuration File
+
+Config is stored at `~/.barista/config.yaml`:
+
+```yaml
+defaults:
+  env: dev
+  tenant: default
+  service: liberica
+
+environments:
+  dev:
+    liberica:
+      baseUrl: "https://{tenant}-dev.newpeaksh.com"
+      timeout: 30000
+    arabica:
+      baseUrl: "https://arabica-dev.newpeaksh.com"
+      timeout: 30000
+
+output:
+  format: table
+  color: true
+  timestamp: true
+```
+
+## Security Considerations
+
+1. **Token Storage**: All tokens stored in system keychain, never in files
+2. **Environment Isolation**: Each environment+service+tenant combination has separate token
+3. **No Credential Logging**: Tokens never appear in logs or error messages
+4. **Secure Defaults**: Config created with minimal defaults on first run
+
+## Error Handling
+
+All API errors follow a standard response structure:
+
+```typescript
+interface APIResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+  meta?: {
+    requestId?: string;
+    timestamp?: string;
+    pagination?: PaginationInfo;
+  };
+}
+```
+
+## Detailed Specifications
+
+For detailed command specifications, API schemas, and implementation details, refer to the plans in `.sisyphus/plans/`.
+
+## Future Considerations
+
+- [ ] Add integration tests with mock servers
+- [ ] Support for config file templates
+- [ ] Interactive wizard for initial setup
+- [ ] Completion scripts for bash/zsh

package/docs/COMMANDS.md

@@ -0,0 +1,352 @@
+# Command Development Guide
+
+## 完整命令参考
+
+所有命令的完整清单（包括已实现和待开发）请查看 [命令参考](./commands/REFERENCE.md)。
+
+## Command Naming Convention
+
+All Barista CLI commands follow a consistent naming pattern:
+
+```
+barista <service> <resource> <action> [options]
+```
+
+**Examples:**
+- `barista liberica orders list`
+- `barista liberica products search --keyword "coffee"`
+- `barista arabica members get 12345`
+- `barista context show`
+
+## Command Structure
+
+```
+barista
+├── context        # Context management
+│   ├── show
+│   ├── use-env
+│   └── use-tenant
+├── auth           # Authentication
+│   ├── login
+│   ├── status
+│   └── logout
+├── liberica       # Liberica service
+│   ├── orders
+│   ├── products
+│   └── production
+└── arabica        # Arabica service
+    ├── members
+    ├── enterprises
+    ├── products
+    ├── subscriptions
+    └── access
+```
+
+## Creating a New Command
+
+### Step 1: Create Command File
+
+Create a new file in `src/commands/{service}/`:
+
+```typescript
+// src/commands/liberica/orders.ts
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { configManager } from '../../core/config/manager.js';
+import { tokenManager } from '../../core/auth/token-manager.js';
+import axios from 'axios';
+
+export function createOrdersCommand(): Command {
+  const ordersCommand = new Command('orders');
+  ordersCommand.description('Manage Liberica orders');
+
+  // List subcommand
+  ordersCommand
+    .command('list')
+    .description('List all orders')
+    .option('--page <number>', 'Page number', '1')
+    .option('--size <number>', 'Page size', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      const context = configManager.getCurrentContext();
+      const token = await tokenManager.getToken({
+        service: 'liberica',
+        environment: context.environment,
+        tenant: context.tenant,
+      });
+
+      if (!token) {
+        console.error(chalk.red('✗ Not logged in. Run "barista auth login" first.'));
+        process.exit(1);
+      }
+
+      try {
+        const baseUrl = configManager.getEnvironmentUrl('liberica', context.environment);
+        const response = await axios.get(`${baseUrl}/api/v1/orders`, {
+          headers: { Authorization: `Bearer ${token}` },
+          params: { page: options.page, size: options.size },
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(response.data, null, 2));
+        } else {
+          // Render table output
+          console.log(chalk.bold('\n📋 Orders\n'));
+          // ... table rendering logic
+        }
+      } catch (error) {
+        console.error(chalk.red('✗ Failed to fetch orders:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  return ordersCommand;
+}
+```
+
+### Step 2: Register in Parent index.ts
+
+Update `src/commands/liberica/index.ts`:
+
+```typescript
+import { Command } from 'commander';
+import { createOrdersCommand } from './orders.js';
+
+export function createLibericaCommand(): Command {
+  const libericaCommand = new Command('liberica');
+  libericaCommand.description('Liberica production management operations');
+
+  libericaCommand.addCommand(createOrdersCommand());
+  // Add more subcommands here...
+
+  return libericaCommand;
+}
+```
+
+### Step 3: Write Tests
+
+Create `tests/unit/commands/liberica/orders.test.ts`:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createOrdersCommand } from '../../../src/commands/liberica/orders.js';
+
+describe('liberica orders', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should create orders command', () => {
+    const command = createOrdersCommand();
+    expect(command.name()).toBe('orders');
+  });
+});
+```
+
+### Step 4: Verify
+
+```bash
+npm run build
+npm test
+node ./bin/barista liberica orders --help
+```
+
+## Output Formatting Standards
+
+### JSON Output
+
+Use `--json` flag for machine-readable output:
+
+```bash
+barista liberica orders list --json
+```
+
+Output:
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "pagination": { "page": 1, "size": 20, "total": 100 }
+  }
+}
+```
+
+### Table Output (TTY)
+
+For human-readable output when stdout is a terminal:
+
+```typescript
+import chalk from 'chalk';
+import Table from 'cli-table3';
+
+function formatOrdersTable(orders: Order[]): void {
+  const table = new Table({
+    head: ['ID', 'Product', 'Quantity', 'Status', 'Created'],
+    colWidths: [10, 30, 10, 15, 20],
+  });
+
+  for (const order of orders) {
+    table.push([
+      order.id,
+      order.productName,
+      order.quantity,
+      formatStatus(order.status),
+      order.createdAt,
+    ]);
+  }
+
+  console.log(table.toString());
+}
+
+function formatStatus(status: string): string {
+  const colors: Record<string, chalk.Chalk> = {
+    pending: chalk.yellow,
+    in_production: chalk.blue,
+    completed: chalk.green,
+    cancelled: chalk.red,
+  };
+  return colors[status] ? colors[status](status) : status;
+}
+```
+
+### Auto-Detection
+
+Detect output format automatically:
+
+```typescript
+function shouldUseJson(): boolean {
+  return process.stdout.isTTY === false || process.argv.includes('--json');
+}
+```
+
+## Error Handling Patterns
+
+### API Errors
+
+```typescript
+import { APIResponse } from '../../types/index.js';
+
+async function fetchOrders(): Promise<Order[]> {
+  try {
+    const response = await axios.get<APIResponse<Order[]>>('/api/orders');
+    
+    if (!response.data.success) {
+      throw new Error(response.data.error?.message || 'Unknown error');
+    }
+    
+    return response.data.data || [];
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      if (error.response) {
+        // Server responded with error
+        const status = error.response.status;
+        if (status === 401) {
+          throw new Error('Authentication failed. Run "barista auth login"');
+        } else if (status === 403) {
+          throw new Error('Access denied');
+        }
+      } else if (error.request) {
+        // No response received
+        throw new Error('Network error. Check your connection.');
+      }
+    }
+    throw error;
+  }
+}
+```
+
+### User Errors
+
+```typescript
+function validateOrderId(id: string): number {
+  const numericId = parseInt(id, 10);
+  if (isNaN(numericId) || numericId <= 0) {
+    console.error(chalk.red(`✗ Invalid order ID: ${id}`));
+    process.exit(1);
+  }
+  return numericId;
+}
+```
+
+## Dry-Run Mode Implementation
+
+For destructive operations, implement dry-run:
+
+```typescript
+ordersCommand
+  .command('cancel <order-id>')
+  .description('Cancel an order')
+  .option('--dry-run', 'Preview without executing')
+  .option('--confirm', 'Skip confirmation prompt')
+  .action(async (orderId: string, options) => {
+    const order = await fetchOrder(orderId);
+
+    console.log(chalk.bold('\n🔍 Cancel Order Preview\n'));
+    console.log(`  ${chalk.gray('Order ID:')} ${orderId}`);
+    console.log(`  ${chalk.gray('Product:')} ${order.productName}`);
+    console.log(`  ${chalk.gray('Quantity:')} ${order.quantity}\n`);
+
+    if (options.dryRun) {
+      console.log(chalk.yellow('⚠ Dry-run mode: No changes made\n'));
+      return;
+    }
+
+    if (!options.confirm) {
+      const { confirmed } = await inquirer.prompt([
+        { type: 'confirm', name: 'confirmed', message: 'Confirm cancellation?' },
+      ]);
+      if (!confirmed) {
+        console.log(chalk.gray('Cancelled.'));
+        return;
+      }
+    }
+
+    await cancelOrder(orderId);
+    console.log(chalk.green('✓ Order cancelled\n'));
+  });
+```
+
+## Testing Commands
+
+### Mocking Dependencies
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import axios from 'axios';
+
+vi.mock('axios');
+const mockedAxios = vi.mocked(axios);
+
+describe('orders list', () => {
+  it('should list orders successfully', async () => {
+    mockedAxios.get.mockResolvedValue({
+      data: {
+        success: true,
+        data: [
+          { id: '1', productName: 'Coffee Machine', quantity: 10 },
+        ],
+      },
+    });
+
+    // Test implementation...
+  });
+});
+```
+
+## Full Command Reference
+
+### 已实现命令
+
+查看 [命令参考](./commands/REFERENCE.md) 获取完整的命令清单和状态。
+
+### 命令设计规范
+
+**新增命令必须先编写设计文档**，参考 `COMMAND_DESIGN_SPEC.md` 第2节模板，包含：
+- 后端接口引用（Controller、DTO位置）
+- CLI参数设计
+- 字段映射表
+- 错误码引用
+- 开发流程检查清单
+
+所有待开发命令的状态和优先级请查看 [命令参考](./commands/REFERENCE.md)。