@newpeak/barista-cli 0.1.6 → 0.1.7

package/README.en.md

@@ -0,0 +1,714 @@
+# ☕ Barista CLI
+
+<p align="center">
+  <a href="./README.md"><img src="https://img.shields.io/badge/-简体中文-green?style=flat-square" alt="简体中文"></a>
+  <a href="./README.en.md"><img src="https://img.shields.io/badge/-English-blue?style=flat-square" alt="English"></a>
+  <a href="./README.ja.md"><img src="https://img.shields.io/badge/-日本語-red?style=flat-square" alt="日本語"></a>
+  <a href="./README.vi.md"><img src="https://img.shields.io/badge/-Tiếng%20Việt-green?style=flat-square" alt="Tiếng Việt"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/AI--Native-CLI-blue?style=flat-square" alt="AI-Native">
+  <img src="https://img.shields.io/badge/Liberica-Production%20SaaS-green?style=flat-square" alt="Liberica">
+  <img src="https://img.shields.io/badge/Arabica-Sales%20Platform-orange?style=flat-square" alt="Arabica">
+  <img src="https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square" alt="Node.js 18+">
+</p>
+
+<p align="center">
+  <strong>AI-Native CLI Tool</strong> that seamlessly bridges Liberica Production Management SaaS and Arabica Sales Platform
+</p>
+
+---
+
+## 📋 Table of Contents
+
+- [Project Introduction](#project-introduction)
+- [Quick Start](#quick-start)
+- [Architecture Design](#architecture-design)
+- [Command Documentation](#command-documentation)
+- [Advanced Features](#advanced-features)
+- [Configuration](#configuration)
+- [AI Integration](#ai-integration)
+- [Development Guide](#development-guide)
+- [Contributing](#contributing)
+
+---
+
+## Project Introduction
+
+Barista CLI is an AI-Native command-line tool designed specifically for the Newpeak ecosystem. It provides a unified interface for managing Liberica Production Management SaaS and Arabica Sales Platform.
+
+### Core Features
+
+| Feature | Description |
+|---------|-------------|
+| 🌍 **Multi-Environment Support** | Seamless switching between dev, test, prod-cn, and prod-jp environments |
+| 🏢 **Multi-Tenant Architecture** | Supports multi-tenant environment configuration and isolation |
+| 🔐 **Token Authentication** | Securely stored in system keychain with environment isolation |
+| 🧪 **Dry-Run Mode** | All write operations support preview to avoid mistakes |
+| 🤖 **AI Integration** | JSON output format optimized for Claude Code |
+| 🔄 **Cross-Service Operations** | Data synchronization between Liberica and Arabica |
+
+### Use Cases
+
+- **Production Planning Management**: Create, query, and cancel production orders
+- **Product Data Management**: Cross-platform product search and synchronization
+- **Customer Operations**: Query customer information and generate quotes
+- **AI Automation**: Automate business processes through Claude Code
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install via npm
+npm install -g @newpeak/barista-cli
+
+# Or via yarn
+yarn global add @newpeak/barista-cli
+
+# Verify installation
+barista --version
+```
+
+### Initial Configuration
+
+```bash
+# 1. Initialize config directory
+barista init
+
+# 2. Set environment (choose default environment)
+barista context use-env dev
+
+# 3. Set tenant
+barista context use-tenant your-tenant
+
+# 4. Login to get Token
+barista auth login --service liberica --env dev
+
+# 5. Verify login status
+barista auth status
+```
+
+### Basic Usage Examples
+
+```bash
+# View current context
+barista context show
+
+# List all orders (Liberica)
+barista liberica orders list
+
+# Search products (supports fuzzy search)
+barista liberica products search --keyword "coffee machine"
+
+# View Arabica product catalog
+barista arabica products public-catalog
+
+# Create production order (dry-run preview mode)
+barista liberica orders create --product-id 123 --quantity 100 --dry-run
+```
+
+---
+
+## Architecture Design
+
+### Environment Mapping
+
+#### Liberica (Production Management SaaS)
+
+| Environment | Domain Format | Description |
+|-------------|---------------|-------------|
+| dev | `{tenant}-dev.newpeaksh.com` | Development environment |
+| test | `{tenant}-test.newpeaksh.com` | Test environment |
+| prod-cn | `{tenant}.newpeaksh.com` | China production environment |
+| prod-jp | `{tenant}.newpeakjp.com` | Japan production environment |
+
+#### Arabica (Sales Platform)
+
+| Environment | Domain | Description |
+|-------------|--------|-------------|
+| dev | `arabica-dev.newpeaksh.com` | Development environment |
+| test | `arabica-test.newpeaksh.com` | Test environment |
+| prod-cn | `www.newpeaksh.com` | China production environment |
+| prod-jp | `members.newpeakjp.com` | Japan production environment |
+
+### Authentication Mechanism
+
+Barista CLI uses Token-based authentication:
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   Barista CLI   │────▶│   Auth Server    │────▶│   API Servers   │
+│                 │     │                  │     │                 │
+│ • Login Request │     │ • Verify Creds   │     │ • Verify Token  │
+│ • Store Token   │◀────│ • Issue JWT      │◀────│ • Return Data   │
+│   (Keychain)    │     │                  │     │                 │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+```
+
+**Security Features:**
+
+- **Keychain Storage**: Tokens are securely stored in system keychain (macOS Keychain, Windows Credential, Linux Secret Service)
+- **Auto Skip Auth**: Public interfaces (like product catalog queries) do not require authentication
+- **Environment Isolation**: Each environment and tenant uses independent tokens
+- **Token Refresh**: Supports automatic refresh of tokens nearing expiration
+
+---
+
+## Command Documentation
+
+> **Complete Command Reference**: For a complete reference of all commands (including implemented and planned), please see [Command Reference](./docs/commands/REFERENCE.md).
+
+### Command Structure
+
+```
+barista <service> <resource> <action> [options]
+```
+
+**Examples:**
+
+```bash
+barista liberica orders list --page 1 --size 20
+barista arabica quotes calculate --product-id 123 --quantity 10
+```
+
+### Global Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--env` | Specify environment | `--env prod-cn` |
+| `--tenant` | Specify tenant | `--tenant electionjp` |
+| `--service` | Specify service | `--service liberica` |
+| `--dry-run` | Preview mode | `--dry-run` |
+| `--json` | JSON output | `--json` |
+| `--help` | Show help | `--help` |
+
+### Context Management
+
+Context management is used to quickly switch working environments, avoiding the need to specify environment parameters for every command.
+
+```bash
+# View current context
+barista context show
+
+# Output example:
+# ┌─────────────┬─────────────────┐
+# │ Property    │ Value           │
+# ├─────────────┼─────────────────┤
+# │ Current Env │ dev             │
+# │ Current Tenant│ electionjp    │
+# │ Current Service│ liberica     │
+# │ Token Status│ Logged In       │
+# │ Token Expiry│ 2024-12-31      │
+# └─────────────┴─────────────────┘
+
+# Switch environment
+barista context use-env [dev|test|prod-cn|prod-jp]
+
+# Switch tenant
+barista context use-tenant <tenant-name>
+
+# Switch default service
+barista context use-service [liberica|arabica]
+```
+
+### Authentication Management
+
+```bash
+# Login to get Token
+barista auth login --service <service> --env <env> [--tenant <tenant>]
+
+# Example: Login to Liberica development environment
+barista auth login --service liberica --env dev --tenant electionjp
+
+# Check login status
+barista auth status
+
+# Output example:
+# ✓ Liberica (dev) - Logged In (Expires: 2024-12-31)
+# ✗ Liberica (test) - Not Logged In
+# ✓ Arabica (prod-cn) - Logged In (Expires: 2024-12-30)
+
+# Logout (clear Token)
+barista auth logout --service <service> --env <env>
+
+# Logout all environments
+barista auth logout --all
+```
+
+### Liberica Commands
+
+#### Order Management
+
+```bash
+# List orders (paginated)
+barista liberica orders list [--page <n>] [--size <n>] [--status <status>]
+
+# Get single order details
+barista liberica orders get <order-id>
+
+# Create order
+barista liberica orders create \
+  --product-id <id> \
+  --quantity <n> \
+  [--delivery-date <date>] \
+  [--note <text>]
+
+# Cancel order
+barista liberica orders cancel <order-id> [--reason <text>]
+```
+
+#### Product Management
+
+```bash
+# Search products
+barista liberica products search --keyword <keyword> [--category <id>]
+
+# Get product details
+barista liberica products get <product-id>
+
+# Get public product list (no auth required)
+barista liberica products public-list [--category <id>] [--page <n>]
+```
+
+#### Production Planning
+
+```bash
+# View production schedule
+barista liberica production schedule [--start-date <date>] [--end-date <date>]
+
+# Reschedule production
+barista liberica production reschedule <order-id> --new-date <date> [--dry-run]
+
+# Query capacity
+barista liberica production capacity [--date <date>] [--line <line-id>]
+```
+
+### Arabica Commands
+
+#### Product Management
+
+```bash
+# List products
+barista arabica products list [--page <n>] [--size <n>] [--category <id>]
+
+# Search products
+barista arabica products search --keyword <keyword>
+
+# Get product catalog (public interface)
+barista arabica products public-catalog [--lang <zh|jp|en>]
+```
+
+#### Quote Management
+
+```bash
+# Calculate quote
+barista arabica quotes calculate \
+  --product-id <id> \
+  --quantity <n> \
+  [--options <json>]
+
+# Create quote
+barista arabica quotes create \
+  --customer-id <id> \
+  --items <json> \
+  [--valid-days <n>]
+```
+
+#### Customer Management
+
+```bash
+# Search customers
+barista arabica customers search --keyword <keyword> [--type <type>]
+
+# Get customer details
+barista arabica customers get <customer-id>
+```
+
+### Cross-Service Commands
+
+Cross-service commands enable data synchronization and business process衔接 between Liberica and Arabica.
+
+```bash
+# Generate quote from order
+barista cross quote-from-order <order-id> [--target-service arabica]
+
+# Output example:
+# ✓ Quote Generated
+# ┌──────────┬────────────┐
+# │ Property │ Value      │
+# ├──────────┼────────────┤
+# │ Order ID │ 12345      │
+# │ Quote ID │ QT-2024-001│
+# │ Amount   │ ¥50,000    │
+# │ Validity │ 30 days    │
+# └──────────┴────────────┘
+
+# Sync order status to Arabica
+barista cross sync-order <order-id> [--direction liberica-to-arabica]
+```
+
+---
+
+## Advanced Features
+
+### Dry-Run Mode
+
+Dry-Run mode allows you to preview the impact of write operations before executing them, avoiding mistakes.
+
+```bash
+# All write operations support --dry-run option
+barista liberica orders create --product-id 123 --quantity 100 --dry-run
+
+# Output example:
+# 🔍 Dry-Run Mode: Operation will not be executed
+# ┌─────────────────┬──────────────────────┐
+# │ Operation       │ Create Order         │
+# ├─────────────────┼──────────────────────┤
+# │ Product         │ Coffee Machine Pro (ID: 123) │
+# │ Quantity        │ 100                  │
+# │ Estimated Amount│ ¥50,000              │
+# │ Estimated Delivery│ 2024-12-31         │
+# │ Impact          │ Add one order record │
+# └─────────────────┴──────────────────────┘
+# 
+# ⚠️  Confirm execution? Add --confirm option or remove --dry-run
+```
+
+**Default Dry-Run Operations:**
+
+The following destructive operations have Dry-Run mode enabled by default and require explicit confirmation:
+
+- Cancel order
+- Delete product
+- Batch update
+
+### JSON Output Format
+
+Barista CLI supports JSON output for script processing and AI integration:
+
+```bash
+barista liberica orders list --json
+
+# Output example:
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "id": "12345",
+        "productName": "Coffee Machine Pro",
+        "quantity": 100,
+        "status": "in_production",
+        "createdAt": "2024-01-15T10:30:00Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "size": 20,
+      "total": 150
+    }
+  }
+}
+```
+
+---
+
+## Configuration
+
+### Configuration File
+
+The configuration file is located at `~/.barista/config.yaml`:
+
+```yaml
+# Barista CLI Configuration File
+
+# Default context settings
+defaults:
+  env: dev
+  tenant: electionjp
+  service: liberica
+
+# Environment configuration
+environments:
+  dev:
+    liberica:
+      baseUrl: "https://{tenant}-dev.newpeaksh.com"
+      timeout: 30000
+    arabica:
+      baseUrl: "https://arabica-dev.newpeaksh.com"
+      timeout: 30000
+  
+  test:
+    liberica:
+      baseUrl: "https://{tenant}-test.newpeaksh.com"
+      timeout: 30000
+    arabica:
+      baseUrl: "https://arabica-test.newpeaksh.com"
+      timeout: 30000
+  
+  prod-cn:
+    liberica:
+      baseUrl: "https://{tenant}.newpeaksh.com"
+      timeout: 60000
+    arabica:
+      baseUrl: "https://www.newpeaksh.com"
+      timeout: 60000
+  
+  prod-jp:
+    liberica:
+      baseUrl: "https://{tenant}.newpeakjp.com"
+      timeout: 60000
+    arabica:
+      baseUrl: "https://members.newpeakjp.com"
+      timeout: 60000
+
+# Output configuration
+output:
+  format: table  # table | json
+  color: true
+  timestamp: true
+```
+
+### Multi-Tenant Configuration
+
+Supports configuring multiple tenants for quick switching:
+
+```bash
+# Add tenant configuration
+barista config add-tenant \
+  --name customer-a \
+  --liberica-id customer-a-id \
+  --arabica-id customer-a-arabica-id
+
+# List configured tenants
+barista config list-tenants
+
+# Quick switch tenant
+barista context use-tenant customer-a
+```
+
+---
+
+## AI Integration
+
+Barista CLI is optimized for AI programming assistants, especially Claude Code.
+
+### Claude Code Usage Examples
+
+```typescript
+// Using Barista CLI in Claude Code
+// Example: Get order list and analyze
+
+const result = await $`barista liberica orders list --json --page 1 --size 10`;
+const orders = JSON.parse(result.stdout);
+
+// Analyze order data
+const analysis = orders.data.items.map(order => ({
+  id: order.id,
+  status: order.status,
+  amount: order.amount
+}));
+```
+
+### Skills Files
+
+Barista CLI provides Claude Code Skills files, located at:
+
+```
+~/.barista/claude/skills/
+├── orders.md       # Order management skills
+├── products.md     # Product management skills
+├── quotes.md       # Quote management skills
+└── customers.md    # Customer management skills
+```
+
+**Example Skills File:**
+
+```markdown
+# Order Management Skills
+
+## List Pending Orders
+
+When user asks about pending orders:
+
+1. Execute command: barista liberica orders list --status pending --json
+2. Parse the returned JSON
+3. Summarize order count and total amount
+4. List key information for the top 5 orders
+
+## Create New Order
+
+When user needs to create an order:
+
+1. Confirm product ID and quantity
+2. Use dry-run preview: barista liberica orders create --dry-run ...
+3. Execute actual command after user confirmation
+```
+
+### AI-Friendly Output
+
+All commands support the `--json` option, returning structured JSON data:
+
+```bash
+# Query with structured output
+barista liberica orders get 12345 --json
+
+{
+  "success": true,
+  "data": {
+    "id": "12345",
+    "status": "in_production",
+    "product": {
+      "id": "100",
+      "name": "Coffee Machine Pro"
+    },
+    "quantity": 100,
+    "amount": 50000,
+    "timeline": {
+      "created": "2024-01-15T10:30:00Z",
+      "delivery": "2024-02-15"
+    }
+  },
+  "meta": {
+    "requestId": "req-abc123",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+---
+
+## Development Guide
+
+### Project Structure
+
+```
+coffee-barista-cli/
+├── bin/
+│   └── barista.js              # Entry file
+├── src/
+│   ├── commands/               # Command implementations
+│   │   ├── context/            # Context management commands
+│   │   ├── auth/               # Authentication commands
+│   │   ├── liberica/           # Liberica service commands
+│   │   │   ├── orders.js
+│   │   │   ├── products.js
+│   │   │   └── production.js
+│   │   ├── arabica/            # Arabica service commands
+│   │   │   ├── products.js
+│   │   │   ├── quotes.js
+│   │   │   └── customers.js
+│   │   └── cross/              # Cross-service commands
+│   ├── core/                   # Core modules
+│   │   ├── auth.js             # Authentication management
+│   │   ├── config.js           # Configuration management
+│   │   ├── context.js          # Context management
+│   │   └── api-client.js       # API client
+│   ├── utils/                  # Utility functions
+│   │   ├── formatter.js        # Output formatting
+│   │   ├── validator.js        # Parameter validation
+│   │   └── keychain.js         # Keychain operations
+│   └── templates/              # Template files
+├── skills/                     # Claude Code Skills
+├── tests/                      # Test files
+├── package.json
+└── README.md
+```
+
+### Local Development
+
+```bash
+# 1. Clone repository
+git clone https://gitlab.newpeaksh.com/coffee/coffee-barista-cli.git
+cd coffee-barista-cli
+
+# 2. Install dependencies
+npm install
+
+# 3. Link globally (development mode)
+npm link
+
+# 4. Verify link
+barista --version
+
+# 5. Run tests
+npm test
+
+# 6. Code linting
+npm run lint
+```
+
+### Adding New Commands
+
+**Important**: New commands must follow the [Command Design Specification](./docs/COMMAND_DESIGN_SPEC.md), including design documentation, technical review, and other complete processes.
+
+For detailed steps, please refer to:
+- [Complete Command Reference](./docs/commands/REFERENCE.md) - All command list and development priorities
+- [Command Design Specification](./docs/COMMAND_DESIGN_SPEC.md#5-command-development-process)
+- [Command Development Guide](./docs/COMMANDS.md)
+
+---
+
+## Contributing
+
+We welcome all forms of contributions, including but not limited to:
+
+- 🐛 Reporting bugs
+- 💡 Suggesting new features
+- 📝 Improving documentation
+- 🔧 Submitting code fixes
+- ✨ Adding new features
+
+### Commit Conventions
+
+Please follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```bash
+# Fix bug
+fix: fix order list pagination issue
+
+# Add feature
+feat: add inventory query command
+
+# Documentation update
+docs: update environment mapping in README
+
+# Code refactoring
+refactor: refactor API client error handling
+```
+
+### Development Workflow
+
+1. Fork this repository
+2. Create feature branch: `git checkout -b feature/my-feature`
+3. Commit changes: `git commit -m 'feat: add some feature'`
+4. Push branch: `git push origin feature/my-feature`
+5. Create Pull Request
+
+---
+
+## Related Projects
+
+| Project | Description | Link |
+|---------|-------------|------|
+| ☕ Liberica Backend | Production Management SaaS Backend | [coffee-liberica-end](https://gitlab.newpeaksh.com/coffee/coffee-liberica-end) |
+| 🖥️ Liberica Frontend | Production Management Web Frontend | [coffee-liberica-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-front) |
+| 📱 Liberica Mobile | Production Management Mobile | [coffee-liberica-mobile-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-mobile-front) |
+| 🛒 Arabica Backend | Sales Platform Backend | [coffee-arabica-end](https://gitlab.newpeaksh.com/coffee/coffee-arabica-end) |
+| 🌐 Arabica Frontend | Sales Platform Frontend | [coffee-arabica-front](https://gitlab.newpeaksh.com/coffee/coffee-arabica-front) |
+
+---
+
+## License
+
+[MIT](LICENSE) © Newpeak Technology
+
+---
+
+<p align="center">
+  Powered by ☕
+</p>