@newpeak/barista-cli 0.1.19 → 0.1.21

package/README.zh.md

@@ -1,340 +1,340 @@
-# ☕ Barista CLI
-
-> **让 AI 助手操控生产管理系统** — Bridge AI tools (Claude Code, OpenCode, OpenClaw) to enterprise SaaS
-
-[![npm version](https://img.shields.io/npm/v/@newpeak/barista-cli.svg?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
-[![Weekly Downloads](https://img.shields.io/npm/dw/@newpeak/barista-cli?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square)](https://nodejs.org/)
-
----
-
-## ⚡ Quick Start
-
-### 1. Install
-
-```bash
-npm install -g @newpeak/barista-cli
-```
-
-### 2. Authenticate
-
-```bash
-# AI needs credentials to operate on behalf of user
-barista liberica auth login prod-cn your-tenant your-username your-password
-
-# Interactive login (prompts for missing info)
-barista liberica auth login
-```
-
-### 3. AI Integration
-
-```typescript
-// In Claude Code / OpenCode / OpenClaw:
-const orders = await $`barista liberica orders list --env prod-cn --tenant your-tenant --json`
-const { success, data } = JSON.parse(orders.stdout)
-
-// AI parses and acts on the data
-if (data.items.length > 0) {
-  console.log(`Found ${data.pagination.total} orders`)
-}
-```
-
-**[View AI Integration Examples →](#ai-integration)**
-
----
-
-## 🤖 AI Integration
-
-Barista CLI is designed for AI coding assistants. Every output is structured, every error is actionable.
-
-### Supported AI Tools
-
-| AI Tool | Integration Method | Status |
-|---------|-------------------|--------|
-| **Claude Code** | `$` backticks + `--json` | ✅ Verified |
-| **OpenCode** | Shell command + JSON parse | ✅ Verified |
-| **OpenClaw** | Shell command + JSON parse | ✅ Verified |
-| **Cursor** | Terminal integration | ✅ Compatible |
-| **Continue** | CLI subprocess | ✅ Compatible |
-
-### Integration Pattern
-
-```typescript
-// 1. Execute command with JSON output
-const result = await $`barista liberica orders list \
-  --env prod-cn \
-  --tenant your-tenant \
-  --status pending \
-  --json \
-  --page 1 \
-  --size 50`
-
-// 2. Parse structured response
-const { success, data, meta } = JSON.parse(result.stdout)
-
-if (!success) {
-  throw new Error(`API Error: ${meta.code || meta.error?.code} - ${meta.message || meta.error?.message}`)
-}
-
-// 3. Work with data
-const pendingOrders = data.items
-console.log(`Found ${data.pagination.total} pending orders`)
-
-// 4. Execute operations safely
-for (const order of pendingOrders) {
-  // Always dry-run first (AI safety)
-  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`
-
-  // Parse preview, verify, then execute with --force
-  // ...
-}
-```
-
-### Response Envelope
-
-All JSON responses follow this structure:
-
-```json
-{
-  "success": true,
-  "data": {
-    "items": [...],
-    "pagination": { "page": 1, "size": 20, "total": 150 }
-  },
-  "meta": {
-    "requestId": "req-abc123",
-    "timestamp": "2024-01-15T10:30:00Z",
-    "environment": "prod-cn",
-    "tenant": "your-tenant"
-  }
-}
-```
-
-**Error format:**
-
-```json
-{
-  "success": false,
-  "error": {
-    "code": "A150001",
-    "message": "Order not found"
-  },
-  "meta": {
-    "requestId": "req-xyz789",
-    "timestamp": "2024-01-15T10:30:00Z"
-  }
-}
-```
-
-### Skills for Claude Code
-
-Install reusable skill files:
-
-```bash
-# Skills are located at ~/.barista/claude/skills/
-barista skills install
-```
-
-**Available skills:**
-- `orders.md` — Order management workflow
-- `products.md` — Product search and sync
-- `warehouses.md` — Inventory operations
-- `subscriptions.md` — Arabica subscription management
-
----
-
-## 🚀 Features
-
-### AI-First Design
-
-| Feature | Description |
-|---------|-------------|
-| 🤖 **JSON-First Output** | All commands support `--json` for AI parsing |
-| 📦 **Structured Responses** | Consistent `{success, data, meta}` envelope |
-| 🔄 **Idempotent Operations** | Safe for AI retry loops |
-| 🛡️ **Dry-Run by Default** | Destructive operations preview before execution |
-| 🔐 **Secure Storage** | Credentials in system keychain, not env vars |
-
-### Enterprise Connectivity
-
-| Service | Capabilities |
-|---------|-------------|
-| ☕ **Liberica** | Orders, products, inventory, warehouses, production planning |
-| 🛒 **Arabica** | Subscription plans, billing, invoices, enterprise management |
-| 🔗 **Cross-Service** | Quote from order, sync between systems |
-
-### Operational Safety
-
-- 📊 **Audit Trail** — Every operation logged with request ID
-- ⚠️ **Confirmation Guards** — `--dry-run` / `--force` for write operations
-- 🏢 **Multi-Tenant Isolation** — Credentials isolated per tenant
-
----
-
-## 🔧 Command Reference
-
-### Core Pattern
-
-```
-barista <service> <resource> <action> [options]
-```
-
-### Global Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--env` | Environment (dev\|test\|prod-cn\|prod-jp) | `dev` |
-| `--tenant` | Tenant name | - |
-| `--json` | JSON output | `false` |
-| `--dry-run` | Preview mode (recommended for AI) | `false` |
-| `--force` | Skip confirmation | `false` |
-| `--page` | Page number | `1` |
-| `--size` | Page size (max items) | `20` |
-
-### Quick Reference
-
-| Command | Description |
-|---------|-------------|
-| `barista context show` | Show current env/tenant context |
-| `barista context use-env <env>` | Switch environment |
-| `barista liberica orders list --json` | List orders (AI format) |
-| `barista liberica orders get <id> --json` | Get order detail |
-| `barista liberica orders create --dry-run ...` | Preview create |
-| `barista liberica products search --keyword <kw> --json` | Search products |
-| `barista arabica plans list --json` | List subscription plans |
-| `barista arabica invoices list --json` | List invoices |
-
-**[→ Full Command Reference](./docs/commands/REFERENCE.md)**
-
----
-
-## 🛡️ AI Safety Guidelines
-
-### 1. Always Dry-Run First
-
-```typescript
-// ❌ Wrong - executing blindly
-await $`barista liberica orders cancel 12345`
-
-// ✅ Correct - preview first
-const preview = await $`barista liberica orders cancel 12345 --dry-run`
-// Parse preview, verify correctness, then:
-await $`barista liberica orders cancel 12345 --force`
-```
-
-### 2. Check Success Before Proceeding
-
-```typescript
-const result = JSON.parse(stdout)
-if (!result.success) {
-  // Handle error, don't continue
-  throw new Error(result.error?.message || result.meta?.message)
-}
-```
-
-### 3. Use Request IDs for Debugging
-
-```typescript
-const { meta } = JSON.parse(stdout)
-console.log(`Request ID: ${meta.requestId}`)
-```
-
-### 4. Respect Rate Limits
-
-- Add delays between bulk operations
-- Use `--size 100` for bulk fetches
-- Cache responses when appropriate
-
----
-
-## ⚙️ Configuration
-
-### File Location
-
-`~/.barista/config.yaml`
-
-### Quick Config
-
-```yaml
-defaults:
-  env: prod-cn
-  tenant: your-tenant
-  service: liberica
-
-environments:
-  prod-cn:
-    liberica:
-      baseUrl: "https://{tenant}.newpeaksh.com"
-      timeout: 60000
-    arabica:
-      baseUrl: "https://www.newpeaksh.com"
-      timeout: 60000
-```
-
-### Authentication
-
-```bash
-# Credential login (recommended)
-barista liberica auth login <env> <tenant> <username> <password>
-
-# Check auth status
-barista auth status
-
-# Logout
-barista auth logout --service liberica --env prod-cn
-```
-
----
-
-## ❓ Troubleshooting
-
-### Auth Failures
-
-```bash
-# Check current status
-barista auth status
-
-# Re-authenticate
-barista liberica auth login prod-cn your-tenant your-username your-password
-
-# Check context
-barista context show
-```
-
-### API Errors
-
-```bash
-# Always use --json to get error codes
-barista liberica orders list --json
-
-# Error response includes requestId for debugging
-# "requestId": "req-abc123"
-```
-
-### Timeout Issues
-
-```bash
-# Switch to closer environment
-barista context use-env dev
-
-# Or adjust timeout in config.yaml
-```
-
----
-
-## 📚 Related Projects
-
-| Project | Description |
-|---------|-------------|
-| ☕ Liberica Backend | Production management SaaS backend |
-| 🖥️ Liberica Frontend | Production management web UI |
-| 📱 Liberica Mobile | Production management mobile app |
-| 🛒 Arabica Backend | Online subscription SaaS backend |
-| 🌐 Arabica Frontend | Online subscription web UI |
-
----
-
-## 📄 License
-
-[MIT](LICENSE) © Newpeak Technology
+# ☕ Barista CLI
+
+> **让 AI 助手操控生产管理系统** — Bridge AI tools (Claude Code, OpenCode, OpenClaw) to enterprise SaaS
+
+[![npm version](https://img.shields.io/npm/v/@newpeak/barista-cli.svg?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+[![Weekly Downloads](https://img.shields.io/npm/dw/@newpeak/barista-cli?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square)](https://nodejs.org/)
+
+---
+
+## ⚡ Quick Start
+
+### 1. Install
+
+```bash
+npm install -g @newpeak/barista-cli
+```
+
+### 2. Authenticate
+
+```bash
+# AI needs credentials to operate on behalf of user
+barista liberica auth login prod-cn your-tenant your-username your-password
+
+# Interactive login (prompts for missing info)
+barista liberica auth login
+```
+
+### 3. AI Integration
+
+```typescript
+// In Claude Code / OpenCode / OpenClaw:
+const orders = await $`barista liberica orders list --env prod-cn --tenant your-tenant --json`
+const { success, data } = JSON.parse(orders.stdout)
+
+// AI parses and acts on the data
+if (data.items.length > 0) {
+  console.log(`Found ${data.pagination.total} orders`)
+}
+```
+
+**[View AI Integration Examples →](#ai-integration)**
+
+---
+
+## 🤖 AI Integration
+
+Barista CLI is designed for AI coding assistants. Every output is structured, every error is actionable.
+
+### Supported AI Tools
+
+| AI Tool | Integration Method | Status |
+|---------|-------------------|--------|
+| **Claude Code** | `$` backticks + `--json` | ✅ Verified |
+| **OpenCode** | Shell command + JSON parse | ✅ Verified |
+| **OpenClaw** | Shell command + JSON parse | ✅ Verified |
+| **Cursor** | Terminal integration | ✅ Compatible |
+| **Continue** | CLI subprocess | ✅ Compatible |
+
+### Integration Pattern
+
+```typescript
+// 1. Execute command with JSON output
+const result = await $`barista liberica orders list \
+  --env prod-cn \
+  --tenant your-tenant \
+  --status pending \
+  --json \
+  --page 1 \
+  --size 50`
+
+// 2. Parse structured response
+const { success, data, meta } = JSON.parse(result.stdout)
+
+if (!success) {
+  throw new Error(`API Error: ${meta.code || meta.error?.code} - ${meta.message || meta.error?.message}`)
+}
+
+// 3. Work with data
+const pendingOrders = data.items
+console.log(`Found ${data.pagination.total} pending orders`)
+
+// 4. Execute operations safely
+for (const order of pendingOrders) {
+  // Always dry-run first (AI safety)
+  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`
+
+  // Parse preview, verify, then execute with --force
+  // ...
+}
+```
+
+### Response Envelope
+
+All JSON responses follow this structure:
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "pagination": { "page": 1, "size": 20, "total": 150 }
+  },
+  "meta": {
+    "requestId": "req-abc123",
+    "timestamp": "2024-01-15T10:30:00Z",
+    "environment": "prod-cn",
+    "tenant": "your-tenant"
+  }
+}
+```
+
+**Error format:**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "A150001",
+    "message": "Order not found"
+  },
+  "meta": {
+    "requestId": "req-xyz789",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### Skills for Claude Code
+
+Install reusable skill files:
+
+```bash
+# Skills are located at ~/.barista/claude/skills/
+barista skills install
+```
+
+**Available skills:**
+- `orders.md` — Order management workflow
+- `products.md` — Product search and sync
+- `warehouses.md` — Inventory operations
+- `subscriptions.md` — Arabica subscription management
+
+---
+
+## 🚀 Features
+
+### AI-First Design
+
+| Feature | Description |
+|---------|-------------|
+| 🤖 **JSON-First Output** | All commands support `--json` for AI parsing |
+| 📦 **Structured Responses** | Consistent `{success, data, meta}` envelope |
+| 🔄 **Idempotent Operations** | Safe for AI retry loops |
+| 🛡️ **Dry-Run by Default** | Destructive operations preview before execution |
+| 🔐 **Secure Storage** | Credentials in system keychain, not env vars |
+
+### Enterprise Connectivity
+
+| Service | Capabilities |
+|---------|-------------|
+| ☕ **Liberica** | Orders, products, inventory, warehouses, production planning |
+| 🛒 **Arabica** | Subscription plans, billing, invoices, enterprise management |
+| 🔗 **Cross-Service** | Quote from order, sync between systems |
+
+### Operational Safety
+
+- 📊 **Audit Trail** — Every operation logged with request ID
+- ⚠️ **Confirmation Guards** — `--dry-run` / `--force` for write operations
+- 🏢 **Multi-Tenant Isolation** — Credentials isolated per tenant
+
+---
+
+## 🔧 Command Reference
+
+### Core Pattern
+
+```
+barista <service> <resource> <action> [options]
+```
+
+### Global Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--env` | Environment (dev\|test\|prod-cn\|prod-jp) | `dev` |
+| `--tenant` | Tenant name | - |
+| `--json` | JSON output | `false` |
+| `--dry-run` | Preview mode (recommended for AI) | `false` |
+| `--force` | Skip confirmation | `false` |
+| `--page` | Page number | `1` |
+| `--size` | Page size (max items) | `20` |
+
+### Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `barista context show` | Show current env/tenant context |
+| `barista context use-env <env>` | Switch environment |
+| `barista liberica orders list --json` | List orders (AI format) |
+| `barista liberica orders get <id> --json` | Get order detail |
+| `barista liberica orders create --dry-run ...` | Preview create |
+| `barista liberica products search --keyword <kw> --json` | Search products |
+| `barista arabica plans list --json` | List subscription plans |
+| `barista arabica invoices list --json` | List invoices |
+
+**[→ Full Command Reference](./docs/commands/REFERENCE.md)**
+
+---
+
+## 🛡️ AI Safety Guidelines
+
+### 1. Always Dry-Run First
+
+```typescript
+// ❌ Wrong - executing blindly
+await $`barista liberica orders cancel 12345`
+
+// ✅ Correct - preview first
+const preview = await $`barista liberica orders cancel 12345 --dry-run`
+// Parse preview, verify correctness, then:
+await $`barista liberica orders cancel 12345 --force`
+```
+
+### 2. Check Success Before Proceeding
+
+```typescript
+const result = JSON.parse(stdout)
+if (!result.success) {
+  // Handle error, don't continue
+  throw new Error(result.error?.message || result.meta?.message)
+}
+```
+
+### 3. Use Request IDs for Debugging
+
+```typescript
+const { meta } = JSON.parse(stdout)
+console.log(`Request ID: ${meta.requestId}`)
+```
+
+### 4. Respect Rate Limits
+
+- Add delays between bulk operations
+- Use `--size 100` for bulk fetches
+- Cache responses when appropriate
+
+---
+
+## ⚙️ Configuration
+
+### File Location
+
+`~/.barista/config.yaml`
+
+### Quick Config
+
+```yaml
+defaults:
+  env: prod-cn
+  tenant: your-tenant
+  service: liberica
+
+environments:
+  prod-cn:
+    liberica:
+      baseUrl: "https://{tenant}.newpeaksh.com"
+      timeout: 60000
+    arabica:
+      baseUrl: "https://www.newpeaksh.com"
+      timeout: 60000
+```
+
+### Authentication
+
+```bash
+# Credential login (recommended)
+barista liberica auth login <env> <tenant> <username> <password>
+
+# Check auth status
+barista auth status
+
+# Logout
+barista auth logout --service liberica --env prod-cn
+```
+
+---
+
+## ❓ Troubleshooting
+
+### Auth Failures
+
+```bash
+# Check current status
+barista auth status
+
+# Re-authenticate
+barista liberica auth login prod-cn your-tenant your-username your-password
+
+# Check context
+barista context show
+```
+
+### API Errors
+
+```bash
+# Always use --json to get error codes
+barista liberica orders list --json
+
+# Error response includes requestId for debugging
+# "requestId": "req-abc123"
+```
+
+### Timeout Issues
+
+```bash
+# Switch to closer environment
+barista context use-env dev
+
+# Or adjust timeout in config.yaml
+```
+
+---
+
+## 📚 Related Projects
+
+| Project | Description |
+|---------|-------------|
+| ☕ Liberica Backend | Production management SaaS backend |
+| 🖥️ Liberica Frontend | Production management web UI |
+| 📱 Liberica Mobile | Production management mobile app |
+| 🛒 Arabica Backend | Online subscription SaaS backend |
+| 🌐 Arabica Frontend | Online subscription web UI |
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © Newpeak Technology