@newpeak/barista-cli 0.1.19 → 0.1.21

package/README.ja.md

@@ -1,340 +1,340 @@
-# ☕ Barista CLI
-
-> **AIアシスタントに生産管理システムを操作させる** — AIツール（Claude Code、OpenCode、OpenClaw）と企業向け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/)
-
----
-
-## ⚡ クイックスタート
-
-### 1. インストール
-
-```bash
-npm install -g @newpeak/barista-cli
-```
-
-### 2. 認証
-
-```bash
-# AIはユーザーの代わりに操作するために認証情報が必要です
-barista liberica auth login prod-cn your-tenant your-username your-password
-
-# インタラクティブログイン（不足情報の入力を促す）
-barista liberica auth login
-```
-
-### 3. AI統合
-
-```typescript
-// 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がデータを解析して操作
-if (data.items.length > 0) {
-  console.log(`Found ${data.pagination.total} orders`)
-}
-```
-
-**[AI統合の例を見る →](#ai-integration)**
-
----
-
-## 🤖 AI統合
-
-Barista CLIはAIコーディングアシスタント向けに設計されています。すべての出力は構造化され、すべてのエラーは対処可能です。
-
-### 対応AIツール
-
-| AIツール | 連携方法 | ステータス |
-|---------|---------|-----------|
-| **Claude Code** | `$` バッククォート + `--json` | ✅ 検証済み |
-| **OpenCode** | シェルコマンド + JSON解析 | ✅ 検証済み |
-| **OpenClaw** | シェルコマンド + JSON解析 | ✅ 検証済み |
-| **Cursor** | ターミナル連携 | ✅ 対応 |
-| **Continue** | CLIサブプロセス | ✅ 対応 |
-
-### 連携パターン
-
-```typescript
-// 1. JSON出力でコマンド実行
-const result = await $`barista liberica orders list \
-  --env prod-cn \
-  --tenant your-tenant \
-  --status pending \
-  --json \
-  --page 1 \
-  --size 50`
-
-// 2. 構造化レスポンスを解析
-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. データを処理
-const pendingOrders = data.items
-console.log(`Found ${data.pagination.total} pending orders`)
-
-// 4. 安全に変更を実行
-for (const order of pendingOrders) {
-  // 常にまずドライラン（AI安全確保）
-  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`
-
-  // プレビューを解析、検証、--forceで実行
-  // ...
-}
-```
-
-### レスポンスエンベロープ
-
-すべてのJSONレスポンスは以下の構造に従います：
-
-```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"
-  }
-}
-```
-
-**エラー形式：**
-
-```json
-{
-  "success": false,
-  "error": {
-    "code": "A150001",
-    "message": "Order not found"
-  },
-  "meta": {
-    "requestId": "req-xyz789",
-    "timestamp": "2024-01-15T10:30:00Z"
-  }
-}
-```
-
-### Claude Code用スキル
-
-再利用者スキルファイルをインストール：
-
-```bash
-# スキルは ~/.barista/claude/skills/ に配置
-barista skills install
-```
-
-**利用可能なスキル：**
-- `orders.md` — 注文管理ワークフロー
-- `products.md` — 商品検索と同期
-- `warehouses.md` — 在庫操作
-- `subscriptions.md` — Arabicaサブスクリプション管理
-
----
-
-## 🚀 機能
-
-### AIファースト設計
-
-| 機能 | 説明 |
-|-----|------|
-| 🤖 **JSONファースト出力** | すべてのコマンドがAI解析用に`--json`をサポート |
-| 📦 **構造化レスポンス** | 一貫した`{success, data, meta}`エンベロープ |
-| 🔄 **冪等操作** | AIリトライループでも安全 |
-| 🛡️ **デフォルトでドライラン** | 破壊的操作は実行前にプレビュー |
-| 🔐 **セキュア保存** | 認証情報はenv変数ではなくシステムキーチェーンに保存 |
-
-### 企業連携
-
-| サービス | 機能 |
-|---------|------|
-| ☕ **Liberica** | 注文、商品、在庫、倉庫、生産計画 |
-| 🛒 **Arabica** | サブスクリプションプラン、請求、請求書、企業管理 |
-| 🔗 **クロスサービス** | 注文から見積、システム間同期 |
-
-### 運用安全
-
-- 📊 **監査証跡** — 操作ごとにリクエストIDでログ記録
-- ⚠️ **確認保護** — `--dry-run` / `--force` で書き込み操作を保護
-- 🏢 **マルチテナント隔離** — 認証情報はテナントごとに分離
-
----
-
-## 🔧 コマンドリファレンス
-
-### コアパターン
-
-```
-barista <service> <resource> <action> [options]
-```
-
-### グローバルオプション
-
-| オプション | 説明 | デフォルト |
-|-----------|------|----------|
-| `--env` | 環境 (dev\|test\|prod-cn\|prod-jp) | `dev` |
-| `--tenant` | テナント名 | - |
-| `--json` | JSON出力 | `false` |
-| `--dry-run` | プレビューモード（AI推奨） | `false` |
-| `--force` | 確認スキップ | `false` |
-| `--page` | ページ番号 | `1` |
-| `--size` | ページサイズ（最大件数） | `20` |
-
-### クイックリファレンス
-
-| コマンド | 説明 |
-|---------|------|
-| `barista context show` | 現在のenv/テナントコンテキストを表示 |
-| `barista context use-env <env>` | 環境を切り替え |
-| `barista liberica orders list --json` | 注文一覧（AI形式） |
-| `barista liberica orders get <id> --json` | 注文詳細取得 |
-| `barista liberica orders create --dry-run ...` | 作成プレビュー |
-| `barista liberica products search --keyword <kw> --json` | 商品検索 |
-| `barista arabica plans list --json` | サブスクリプションプラン一覧 |
-| `barista arabica invoices list --json` | 請求書一覧 |
-
-**[→ 詳細コマンドリファレンス](./docs/commands/REFERENCE.md)**
-
----
-
-## 🛡️ AI安全ガイドライン
-
-### 1. 常にまずドライランを実行
-
-```typescript
-// ❌ 間違い — 盲目的に実行
-await $`barista liberica orders cancel 12345`
-
-// ✅ 正しい — まずプレビュー
-const preview = await $`barista liberica orders cancel 12345 --dry-run`
-// プレビューを解析、検証してから：
-await $`barista liberica orders cancel 12345 --force`
-```
-
-### 2. 続行前に成功を確認
-
-```typescript
-const result = JSON.parse(stdout)
-if (!result.success) {
-  // エラーを処理、続行しない
-  throw new Error(result.error?.message || result.meta?.message)
-}
-```
-
-### 3. デバッグにリクエストIDを使用
-
-```typescript
-const { meta } = JSON.parse(stdout)
-console.log(`Request ID: ${meta.requestId}`)
-```
-
-### 4. レート制限を遵守
-
-- 一括操作間に遅延を追加
-- 一括取得には`--size 100`を使用
-- 適切な場面でレスポンスをキャッシュ
-
----
-
-## ⚙️ 設定
-
-### ファイル場所
-
-`~/.barista/config.yaml`
-
-### クイック設定
-
-```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
-```
-
-### 認証
-
-```bash
-# 認証情報ログイン（推奨）
-barista liberica auth login <env> <tenant> <username> <password>
-
-# 認証状態確認
-barista auth status
-
-# ログアウト
-barista auth logout --service liberica --env prod-cn
-```
-
----
-
-## ❓ トラブルシューティング
-
-### 認証失敗
-
-```bash
-# 現在の状態を確認
-barista auth status
-
-# 再認証
-barista liberica auth login prod-cn your-tenant your-username your-password
-
-# コンテキスト確認
-barista context show
-```
-
-### APIエラー
-
-```bash
-# 常に--jsonでエラーコードを取得
-barista liberica orders list --json
-
-# エラーレスポンスにはデバッグ用のrequestIdが含まれる
-# "requestId": "req-abc123"
-```
-
-### タイムアウト
-
-```bash
-# より近い環境に切り替え
-barista context use-env dev
-
-# またはconfig.yamlでタイムアウトを調整
-```
-
----
-
-## 📚 関連プロジェクト
-
-| プロジェクト | 説明 |
-|------------|------|
-| ☕ Liberica Backend | 生産管理SaaSバックエンド |
-| 🖥️ Liberica Frontend | 生産管理Web UI |
-| 📱 Liberica Mobile | 生産管理モバイルアプリ |
-| 🛒 Arabica Backend | オンラインサブスクリプションSaaSバックエンド |
-| 🌐 Arabica Frontend | オンラインサブスクリプションWeb UI |
-
----
-
-## 📄 ライセンス
-
-[MIT](LICENSE) © Newpeak Technology
+# ☕ Barista CLI
+
+> **AIアシスタントに生産管理システムを操作させる** — AIツール（Claude Code、OpenCode、OpenClaw）と企業向け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/)
+
+---
+
+## ⚡ クイックスタート
+
+### 1. インストール
+
+```bash
+npm install -g @newpeak/barista-cli
+```
+
+### 2. 認証
+
+```bash
+# AIはユーザーの代わりに操作するために認証情報が必要です
+barista liberica auth login prod-cn your-tenant your-username your-password
+
+# インタラクティブログイン（不足情報の入力を促す）
+barista liberica auth login
+```
+
+### 3. AI統合
+
+```typescript
+// 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がデータを解析して操作
+if (data.items.length > 0) {
+  console.log(`Found ${data.pagination.total} orders`)
+}
+```
+
+**[AI統合の例を見る →](#ai-integration)**
+
+---
+
+## 🤖 AI統合
+
+Barista CLIはAIコーディングアシスタント向けに設計されています。すべての出力は構造化され、すべてのエラーは対処可能です。
+
+### 対応AIツール
+
+| AIツール | 連携方法 | ステータス |
+|---------|---------|-----------|
+| **Claude Code** | `$` バッククォート + `--json` | ✅ 検証済み |
+| **OpenCode** | シェルコマンド + JSON解析 | ✅ 検証済み |
+| **OpenClaw** | シェルコマンド + JSON解析 | ✅ 検証済み |
+| **Cursor** | ターミナル連携 | ✅ 対応 |
+| **Continue** | CLIサブプロセス | ✅ 対応 |
+
+### 連携パターン
+
+```typescript
+// 1. JSON出力でコマンド実行
+const result = await $`barista liberica orders list \
+  --env prod-cn \
+  --tenant your-tenant \
+  --status pending \
+  --json \
+  --page 1 \
+  --size 50`
+
+// 2. 構造化レスポンスを解析
+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. データを処理
+const pendingOrders = data.items
+console.log(`Found ${data.pagination.total} pending orders`)
+
+// 4. 安全に変更を実行
+for (const order of pendingOrders) {
+  // 常にまずドライラン（AI安全確保）
+  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`
+
+  // プレビューを解析、検証、--forceで実行
+  // ...
+}
+```
+
+### レスポンスエンベロープ
+
+すべてのJSONレスポンスは以下の構造に従います：
+
+```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"
+  }
+}
+```
+
+**エラー形式：**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "A150001",
+    "message": "Order not found"
+  },
+  "meta": {
+    "requestId": "req-xyz789",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### Claude Code用スキル
+
+再利用者スキルファイルをインストール：
+
+```bash
+# スキルは ~/.barista/claude/skills/ に配置
+barista skills install
+```
+
+**利用可能なスキル：**
+- `orders.md` — 注文管理ワークフロー
+- `products.md` — 商品検索と同期
+- `warehouses.md` — 在庫操作
+- `subscriptions.md` — Arabicaサブスクリプション管理
+
+---
+
+## 🚀 機能
+
+### AIファースト設計
+
+| 機能 | 説明 |
+|-----|------|
+| 🤖 **JSONファースト出力** | すべてのコマンドがAI解析用に`--json`をサポート |
+| 📦 **構造化レスポンス** | 一貫した`{success, data, meta}`エンベロープ |
+| 🔄 **冪等操作** | AIリトライループでも安全 |
+| 🛡️ **デフォルトでドライラン** | 破壊的操作は実行前にプレビュー |
+| 🔐 **セキュア保存** | 認証情報はenv変数ではなくシステムキーチェーンに保存 |
+
+### 企業連携
+
+| サービス | 機能 |
+|---------|------|
+| ☕ **Liberica** | 注文、商品、在庫、倉庫、生産計画 |
+| 🛒 **Arabica** | サブスクリプションプラン、請求、請求書、企業管理 |
+| 🔗 **クロスサービス** | 注文から見積、システム間同期 |
+
+### 運用安全
+
+- 📊 **監査証跡** — 操作ごとにリクエストIDでログ記録
+- ⚠️ **確認保護** — `--dry-run` / `--force` で書き込み操作を保護
+- 🏢 **マルチテナント隔離** — 認証情報はテナントごとに分離
+
+---
+
+## 🔧 コマンドリファレンス
+
+### コアパターン
+
+```
+barista <service> <resource> <action> [options]
+```
+
+### グローバルオプション
+
+| オプション | 説明 | デフォルト |
+|-----------|------|----------|
+| `--env` | 環境 (dev\|test\|prod-cn\|prod-jp) | `dev` |
+| `--tenant` | テナント名 | - |
+| `--json` | JSON出力 | `false` |
+| `--dry-run` | プレビューモード（AI推奨） | `false` |
+| `--force` | 確認スキップ | `false` |
+| `--page` | ページ番号 | `1` |
+| `--size` | ページサイズ（最大件数） | `20` |
+
+### クイックリファレンス
+
+| コマンド | 説明 |
+|---------|------|
+| `barista context show` | 現在のenv/テナントコンテキストを表示 |
+| `barista context use-env <env>` | 環境を切り替え |
+| `barista liberica orders list --json` | 注文一覧（AI形式） |
+| `barista liberica orders get <id> --json` | 注文詳細取得 |
+| `barista liberica orders create --dry-run ...` | 作成プレビュー |
+| `barista liberica products search --keyword <kw> --json` | 商品検索 |
+| `barista arabica plans list --json` | サブスクリプションプラン一覧 |
+| `barista arabica invoices list --json` | 請求書一覧 |
+
+**[→ 詳細コマンドリファレンス](./docs/commands/REFERENCE.md)**
+
+---
+
+## 🛡️ AI安全ガイドライン
+
+### 1. 常にまずドライランを実行
+
+```typescript
+// ❌ 間違い — 盲目的に実行
+await $`barista liberica orders cancel 12345`
+
+// ✅ 正しい — まずプレビュー
+const preview = await $`barista liberica orders cancel 12345 --dry-run`
+// プレビューを解析、検証してから：
+await $`barista liberica orders cancel 12345 --force`
+```
+
+### 2. 続行前に成功を確認
+
+```typescript
+const result = JSON.parse(stdout)
+if (!result.success) {
+  // エラーを処理、続行しない
+  throw new Error(result.error?.message || result.meta?.message)
+}
+```
+
+### 3. デバッグにリクエストIDを使用
+
+```typescript
+const { meta } = JSON.parse(stdout)
+console.log(`Request ID: ${meta.requestId}`)
+```
+
+### 4. レート制限を遵守
+
+- 一括操作間に遅延を追加
+- 一括取得には`--size 100`を使用
+- 適切な場面でレスポンスをキャッシュ
+
+---
+
+## ⚙️ 設定
+
+### ファイル場所
+
+`~/.barista/config.yaml`
+
+### クイック設定
+
+```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
+```
+
+### 認証
+
+```bash
+# 認証情報ログイン（推奨）
+barista liberica auth login <env> <tenant> <username> <password>
+
+# 認証状態確認
+barista auth status
+
+# ログアウト
+barista auth logout --service liberica --env prod-cn
+```
+
+---
+
+## ❓ トラブルシューティング
+
+### 認証失敗
+
+```bash
+# 現在の状態を確認
+barista auth status
+
+# 再認証
+barista liberica auth login prod-cn your-tenant your-username your-password
+
+# コンテキスト確認
+barista context show
+```
+
+### APIエラー
+
+```bash
+# 常に--jsonでエラーコードを取得
+barista liberica orders list --json
+
+# エラーレスポンスにはデバッグ用のrequestIdが含まれる
+# "requestId": "req-abc123"
+```
+
+### タイムアウト
+
+```bash
+# より近い環境に切り替え
+barista context use-env dev
+
+# またはconfig.yamlでタイムアウトを調整
+```
+
+---
+
+## 📚 関連プロジェクト
+
+| プロジェクト | 説明 |
+|------------|------|
+| ☕ Liberica Backend | 生産管理SaaSバックエンド |
+| 🖥️ Liberica Frontend | 生産管理Web UI |
+| 📱 Liberica Mobile | 生産管理モバイルアプリ |
+| 🛒 Arabica Backend | オンラインサブスクリプションSaaSバックエンド |
+| 🌐 Arabica Frontend | オンラインサブスクリプションWeb UI |
+
+---
+
+## 📄 ライセンス
+
+[MIT](LICENSE) © Newpeak Technology