@newpeak/barista-cli 0.2.276 → 0.2.279
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +401 -356
- package/dist/commands/liberica/teams/employee-groups/employee-groups.d.ts +3 -0
- package/dist/commands/liberica/teams/employee-groups/employee-groups.d.ts.map +1 -0
- package/dist/commands/liberica/teams/employee-groups/employee-groups.js +71 -0
- package/dist/commands/liberica/teams/employee-groups/employee-groups.js.map +1 -0
- package/dist/commands/liberica/teams/employee-groups/index.d.ts +2 -0
- package/dist/commands/liberica/teams/employee-groups/index.d.ts.map +1 -0
- package/dist/commands/liberica/teams/employee-groups/index.js +2 -0
- package/dist/commands/liberica/teams/employee-groups/index.js.map +1 -0
- package/dist/commands/liberica/teams/index.d.ts.map +1 -1
- package/dist/commands/liberica/teams/index.js +2 -0
- package/dist/commands/liberica/teams/index.js.map +1 -1
- package/dist/core/api/client.d.ts +8 -0
- package/dist/core/api/client.d.ts.map +1 -1
- package/dist/core/api/client.js +32 -0
- package/dist/core/api/client.js.map +1 -1
- package/dist/core/config/manager.d.ts +28 -0
- package/dist/core/config/manager.d.ts.map +1 -1
- package/dist/core/config/manager.js +53 -0
- package/dist/core/config/manager.js.map +1 -1
- package/dist/types/team-employee-group.d.ts +41 -0
- package/dist/types/team-employee-group.d.ts.map +1 -0
- package/dist/types/team-employee-group.js +11 -0
- package/dist/types/team-employee-group.js.map +1 -0
- package/package.json +1 -1
- package/skills/barista-cli/data/commands.json +10 -1
- package/skills/barista-cli/data/commands.yaml +7 -1
package/README.md
CHANGED
|
@@ -1,356 +1,401 @@
|
|
|
1
|
-
# ☕ Barista CLI
|
|
2
|
-
|
|
3
|
-
> **Let AI assistants control production management systems** — Bridge AI tools (Claude Code, OpenCode, OpenClaw) to enterprise SaaS
|
|
4
|
-
|
|
5
|
-
[](https://gitlab.newpeaksh.com/coffee/coffee-barista-cli)
|
|
6
|
-
[](https://www.npmjs.com/package/@newpeak/barista-cli)
|
|
7
|
-
[](LICENSE)
|
|
8
|
-
[](https://www.npmjs.com/package/@newpeak/barista-cli)
|
|
9
|
-
[](https://nodejs.org/)
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## ⚡ Quick Start
|
|
14
|
-
|
|
15
|
-
### 1. Install
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
npm install -g @newpeak/barista-cli
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
### 2. Authenticate
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
# AI needs credentials to operate on behalf of user
|
|
25
|
-
barista liberica auth login prod-cn your-tenant your-username your-password
|
|
26
|
-
|
|
27
|
-
# Interactive login (prompts for missing info)
|
|
28
|
-
barista liberica auth login
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
### 3. AI Integration
|
|
32
|
-
|
|
33
|
-
```typescript
|
|
34
|
-
// In Claude Code / OpenCode / OpenClaw:
|
|
35
|
-
const orders = await $`barista liberica sales-orders list --env prod-cn --tenant your-tenant --json`
|
|
36
|
-
const { success, data } = JSON.parse(orders.stdout)
|
|
37
|
-
|
|
38
|
-
// AI parses and acts on the data
|
|
39
|
-
if (data.items.length > 0) {
|
|
40
|
-
console.log(`Found ${data.pagination.total} orders`)
|
|
41
|
-
}
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
**[View AI Integration Examples →](#ai-integration)**
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## 🤖 AI Integration
|
|
49
|
-
|
|
50
|
-
Barista CLI is designed for AI coding assistants. Every output is structured, every error is actionable.
|
|
51
|
-
|
|
52
|
-
### Supported AI Tools
|
|
53
|
-
|
|
54
|
-
| AI Tool | Integration | Install Skill |
|
|
55
|
-
|---------|------------|--------------|
|
|
56
|
-
| **Claude Code** | `$` backticks + `--json` | `barista skills install --ai claude` |
|
|
57
|
-
| **Cursor** | Terminal + `--json` | `barista skills install --ai cursor` |
|
|
58
|
-
| **Trae** | SOLO mode + skill | `barista skills install --ai trae` |
|
|
59
|
-
| **OpenCode** | Shell + `--json` | `barista skills install --ai opencode` |
|
|
60
|
-
| **Windsurf** | Terminal + `--json` | `barista skills install --ai windsurf` |
|
|
61
|
-
| **Copilot** | Terminal + `--json` | `barista skills install --ai copilot` |
|
|
62
|
-
| **Roo Code** | Terminal + `--json` | `barista skills install --ai roocode` |
|
|
63
|
-
| **Continue** | Terminal + `--json` | `barista skills install --ai continue` |
|
|
64
|
-
| **Gemini CLI** | Terminal + `--json` | `barista skills install --ai gemini` |
|
|
65
|
-
| _Codex, Kiro, Qoder, Droid_ | Terminal + `--json` | `barista skills install --ai <name>` |
|
|
66
|
-
|
|
67
|
-
### Integration Pattern
|
|
68
|
-
|
|
69
|
-
```typescript
|
|
70
|
-
// 1. Execute command with JSON output
|
|
71
|
-
const result = await $`barista liberica sales-orders list \
|
|
72
|
-
--env prod-cn \
|
|
73
|
-
--tenant your-tenant \
|
|
74
|
-
--json \
|
|
75
|
-
--page 1 \
|
|
76
|
-
--size 50`
|
|
77
|
-
|
|
78
|
-
// 2. Parse structured response
|
|
79
|
-
const { success, data, meta } = JSON.parse(result.stdout)
|
|
80
|
-
|
|
81
|
-
// 3. Work with data
|
|
82
|
-
const pendingOrders = data.items
|
|
83
|
-
|
|
84
|
-
// 4. Execute operations safely
|
|
85
|
-
for (const order of pendingOrders) {
|
|
86
|
-
// Always dry-run first (AI safety)
|
|
87
|
-
const preview = await $`barista liberica sales-orders delete ${order.id} --dry-run`
|
|
88
|
-
|
|
89
|
-
// Parse preview, verify, then execute with --force
|
|
90
|
-
// ...
|
|
91
|
-
}
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
### Response Envelope
|
|
95
|
-
|
|
96
|
-
All JSON responses follow this structure:
|
|
97
|
-
|
|
98
|
-
```json
|
|
99
|
-
{
|
|
100
|
-
"success": true,
|
|
101
|
-
"data": {
|
|
102
|
-
"items": [...],
|
|
103
|
-
"pagination": { "page": 1, "size": 20, "total": 150 }
|
|
104
|
-
},
|
|
105
|
-
"meta": {
|
|
106
|
-
"requestId": "req-abc123",
|
|
107
|
-
"timestamp": "2024-01-15T10:30:00Z",
|
|
108
|
-
"environment": "prod-cn",
|
|
109
|
-
"tenant": "your-tenant"
|
|
110
|
-
}
|
|
111
|
-
}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
**Error format:**
|
|
115
|
-
|
|
116
|
-
```json
|
|
117
|
-
{
|
|
118
|
-
"success": false,
|
|
119
|
-
"error": {
|
|
120
|
-
"code": "A150001",
|
|
121
|
-
"message": "Order not found"
|
|
122
|
-
},
|
|
123
|
-
"meta": {
|
|
124
|
-
"requestId": "req-xyz789",
|
|
125
|
-
"timestamp": "2024-01-15T10:30:00Z"
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
### AI Skills for Your Assistant
|
|
131
|
-
|
|
132
|
-
Install the barista-cli Skill so your AI assistant knows all available commands, system quirks, and safety rules:
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
# Interactive install (pick your platform)
|
|
136
|
-
barista skills install
|
|
137
|
-
|
|
138
|
-
# Direct install for specific AI tool
|
|
139
|
-
barista skills install --ai claude # → .claude/skills/barista-cli/SKILL.md
|
|
140
|
-
barista skills install --ai trae # → .trae/skills/barista-cli/SKILL.md
|
|
141
|
-
barista skills install --ai opencode # → .opencode/skills/barista-cli/SKILL.md
|
|
142
|
-
barista skills install --ai cursor # → .cursor/rules/barista-cli.mdc
|
|
143
|
-
|
|
144
|
-
# Global install (all projects)
|
|
145
|
-
barista skills install --ai claude --global
|
|
146
|
-
|
|
147
|
-
# List all supported platforms
|
|
148
|
-
barista skills install --list
|
|
149
|
-
|
|
150
|
-
# Search commands by intent (without the AI skill)
|
|
151
|
-
barista skills query "采购订单" # fuzzy search
|
|
152
|
-
barista skills query "入库单" --domain liberica # filter by service
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
**The Skill covers**: Liberica 76-module production management + Arabica subscription platform, with critical traps (email login, hidden --tenant, epoch timestamps), safety rules (dry-run→force), and auto-generated command data.
|
|
156
|
-
|
|
157
|
-
---
|
|
158
|
-
|
|
159
|
-
## 🚀 Features
|
|
160
|
-
|
|
161
|
-
### AI-First Design
|
|
162
|
-
|
|
163
|
-
| Feature | Description |
|
|
164
|
-
|---------|-------------|
|
|
165
|
-
| 🤖 **JSON-First Output** | All commands support `--json` for AI parsing |
|
|
166
|
-
| 📦 **Structured Responses** | Consistent `{success, data, meta}` envelope |
|
|
167
|
-
| 🔄 **Idempotent Operations** | Safe for AI retry loops |
|
|
168
|
-
| 🛡️ **Dry-Run by Default** | Destructive operations preview before execution |
|
|
169
|
-
| 🔐 **Secure Storage** | Credentials in system keychain, not env vars |
|
|
170
|
-
|
|
171
|
-
### Enterprise Connectivity
|
|
172
|
-
|
|
173
|
-
| Service | For | Capabilities |
|
|
174
|
-
|---------|-----|-------------|
|
|
175
|
-
| ☕ **Liberica** | Tenant employees | Production management: supply chain, inventory, BOM/routing, work orders, quality, finance, HR (70+ modules) |
|
|
176
|
-
| 🛒 **Arabica** | Members (membership) | Subscribe to Liberica: plan browsing, order placement, invoice download, enterprise registration |
|
|
177
|
-
|
|
178
|
-
> **Arabica → Liberica flow**: Register as member → register enterprise → subscribe to plan → get Liberica access → log in as employee
|
|
179
|
-
|
|
180
|
-
### Operational Safety
|
|
181
|
-
|
|
182
|
-
- 📊 **Audit Trail** — Every operation logged with request ID
|
|
183
|
-
- ⚠️ **Confirmation Guards** — `--dry-run` / `--force` for write operations
|
|
184
|
-
- 🏢 **Multi-Tenant Isolation** — Credentials isolated per tenant
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## 🔧 Command Reference
|
|
189
|
-
|
|
190
|
-
### Core Pattern
|
|
191
|
-
|
|
192
|
-
```
|
|
193
|
-
barista <service> <resource> <action> [options]
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
### Global Options
|
|
197
|
-
|
|
198
|
-
| Option | Description | Default |
|
|
199
|
-
|--------|-------------|---------|
|
|
200
|
-
| `--env` | Environment (dev\|test\|prod-cn\|prod-jp) | `dev` |
|
|
201
|
-
| `--tenant` | Tenant name | - |
|
|
202
|
-
| `--json` | JSON output | `false` |
|
|
203
|
-
| `--dry-run` | Preview mode (recommended for AI) | `false` |
|
|
204
|
-
| `--force` | Skip confirmation | `false` |
|
|
205
|
-
| `--page` | Page number | `1` |
|
|
206
|
-
| `--size` | Page size (max items) | `20` |
|
|
207
|
-
|
|
208
|
-
### Quick Reference
|
|
209
|
-
|
|
210
|
-
| Command | Description |
|
|
211
|
-
|---------|-------------|
|
|
212
|
-
| `barista context show` | Show current env/tenant context |
|
|
213
|
-
| `barista context use-env <env>` | Switch environment |
|
|
214
|
-
| `barista context use-tenant <tenant>` | Switch tenant |
|
|
215
|
-
| `barista liberica auth login <env> <tenant> <user> <pass>` | Liberica login (tenant employee) |
|
|
216
|
-
| `barista arabica auth login <env> <account> <pass>` | Arabica login (member) |
|
|
217
|
-
| `barista liberica sales-orders list --json` | List sales orders |
|
|
218
|
-
| `barista liberica purchase-orders list --json` | List purchase orders |
|
|
219
|
-
| `barista liberica transfer-in-forms create --dry-run ...` | Preview stock-in |
|
|
220
|
-
| `barista liberica materials list --json` | List materials |
|
|
221
|
-
| `barista arabica plans list --json` | Browse subscription plans |
|
|
222
|
-
| `barista arabica subscription current --json` | Check subscription |
|
|
223
|
-
| `barista skills install --ai claude` | Install AI skill |
|
|
224
|
-
| `barista skills query "采购订单"` | Search commands by intent |
|
|
225
|
-
|
|
226
|
-
**[→ Full Command Reference](./docs/commands/REFERENCE.md)**
|
|
227
|
-
|
|
228
|
-
---
|
|
229
|
-
|
|
230
|
-
## 🛡️ AI Safety Guidelines
|
|
231
|
-
|
|
232
|
-
### 1. Always Dry-Run First
|
|
233
|
-
|
|
234
|
-
```typescript
|
|
235
|
-
// ❌ Wrong - executing blindly
|
|
236
|
-
await $`barista liberica sales-orders delete 12345`
|
|
237
|
-
|
|
238
|
-
// ✅ Correct - preview first
|
|
239
|
-
const preview = await $`barista liberica sales-orders delete 12345 --dry-run`
|
|
240
|
-
// Parse preview, verify correctness, then:
|
|
241
|
-
await $`barista liberica sales-orders delete 12345 --force`
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
### 2. Check Success Before Proceeding
|
|
245
|
-
|
|
246
|
-
```typescript
|
|
247
|
-
const result = JSON.parse(stdout)
|
|
248
|
-
if (!result.success) {
|
|
249
|
-
// Handle error, don't continue
|
|
250
|
-
throw new Error(result.error?.message || result.meta?.message)
|
|
251
|
-
}
|
|
252
|
-
```
|
|
253
|
-
|
|
254
|
-
### 3. Use Request IDs for Debugging
|
|
255
|
-
|
|
256
|
-
```typescript
|
|
257
|
-
const { meta } = JSON.parse(stdout)
|
|
258
|
-
console.log(`Request ID: ${meta.requestId}`)
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
### 4. Respect Rate Limits
|
|
262
|
-
|
|
263
|
-
- Add delays between bulk operations
|
|
264
|
-
- Use `--size 100` for bulk fetches
|
|
265
|
-
- Cache responses when appropriate
|
|
266
|
-
|
|
267
|
-
---
|
|
268
|
-
|
|
269
|
-
## ⚙️ Configuration
|
|
270
|
-
|
|
271
|
-
### File Location
|
|
272
|
-
|
|
273
|
-
`~/.barista/config.yaml`
|
|
274
|
-
|
|
275
|
-
### Quick Config
|
|
276
|
-
|
|
277
|
-
```yaml
|
|
278
|
-
defaults:
|
|
279
|
-
env: prod-cn
|
|
280
|
-
tenant: your-tenant
|
|
281
|
-
service: liberica
|
|
282
|
-
|
|
283
|
-
environments:
|
|
284
|
-
prod-cn:
|
|
285
|
-
liberica:
|
|
286
|
-
baseUrl: "https://{tenant}.newpeaksh.com"
|
|
287
|
-
timeout: 60000
|
|
288
|
-
arabica:
|
|
289
|
-
baseUrl: "https://www.newpeaksh.com"
|
|
290
|
-
timeout: 60000
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
### Authentication
|
|
294
|
-
|
|
295
|
-
```bash
|
|
296
|
-
# Liberica (tenant employee login)
|
|
297
|
-
barista liberica auth login <env> <tenant> <username> <password>
|
|
298
|
-
barista liberica auth login # interactive prompt
|
|
299
|
-
|
|
300
|
-
# Arabica (member login — no tenant needed)
|
|
301
|
-
barista arabica auth login <env> <account> <password>
|
|
302
|
-
barista arabica auth login # interactive prompt
|
|
303
|
-
barista arabica auth register # register new member account
|
|
304
|
-
|
|
305
|
-
# Check / logout
|
|
306
|
-
barista auth status
|
|
307
|
-
barista auth logout --service liberica --env prod-cn
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
###
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
1
|
+
# ☕ Barista CLI
|
|
2
|
+
|
|
3
|
+
> **Let AI assistants control production management systems** — Bridge AI tools (Claude Code, OpenCode, OpenClaw) to enterprise SaaS
|
|
4
|
+
|
|
5
|
+
[](https://gitlab.newpeaksh.com/coffee/coffee-barista-cli)
|
|
6
|
+
[](https://www.npmjs.com/package/@newpeak/barista-cli)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://www.npmjs.com/package/@newpeak/barista-cli)
|
|
9
|
+
[](https://nodejs.org/)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## ⚡ Quick Start
|
|
14
|
+
|
|
15
|
+
### 1. Install
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install -g @newpeak/barista-cli
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### 2. Authenticate
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
# AI needs credentials to operate on behalf of user
|
|
25
|
+
barista liberica auth login prod-cn your-tenant your-username your-password
|
|
26
|
+
|
|
27
|
+
# Interactive login (prompts for missing info)
|
|
28
|
+
barista liberica auth login
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### 3. AI Integration
|
|
32
|
+
|
|
33
|
+
```typescript
|
|
34
|
+
// In Claude Code / OpenCode / OpenClaw:
|
|
35
|
+
const orders = await $`barista liberica sales-orders list --env prod-cn --tenant your-tenant --json`
|
|
36
|
+
const { success, data } = JSON.parse(orders.stdout)
|
|
37
|
+
|
|
38
|
+
// AI parses and acts on the data
|
|
39
|
+
if (data.items.length > 0) {
|
|
40
|
+
console.log(`Found ${data.pagination.total} orders`)
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**[View AI Integration Examples →](#ai-integration)**
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## 🤖 AI Integration
|
|
49
|
+
|
|
50
|
+
Barista CLI is designed for AI coding assistants. Every output is structured, every error is actionable.
|
|
51
|
+
|
|
52
|
+
### Supported AI Tools
|
|
53
|
+
|
|
54
|
+
| AI Tool | Integration | Install Skill |
|
|
55
|
+
|---------|------------|--------------|
|
|
56
|
+
| **Claude Code** | `$` backticks + `--json` | `barista skills install --ai claude` |
|
|
57
|
+
| **Cursor** | Terminal + `--json` | `barista skills install --ai cursor` |
|
|
58
|
+
| **Trae** | SOLO mode + skill | `barista skills install --ai trae` |
|
|
59
|
+
| **OpenCode** | Shell + `--json` | `barista skills install --ai opencode` |
|
|
60
|
+
| **Windsurf** | Terminal + `--json` | `barista skills install --ai windsurf` |
|
|
61
|
+
| **Copilot** | Terminal + `--json` | `barista skills install --ai copilot` |
|
|
62
|
+
| **Roo Code** | Terminal + `--json` | `barista skills install --ai roocode` |
|
|
63
|
+
| **Continue** | Terminal + `--json` | `barista skills install --ai continue` |
|
|
64
|
+
| **Gemini CLI** | Terminal + `--json` | `barista skills install --ai gemini` |
|
|
65
|
+
| _Codex, Kiro, Qoder, Droid_ | Terminal + `--json` | `barista skills install --ai <name>` |
|
|
66
|
+
|
|
67
|
+
### Integration Pattern
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
// 1. Execute command with JSON output
|
|
71
|
+
const result = await $`barista liberica sales-orders list \
|
|
72
|
+
--env prod-cn \
|
|
73
|
+
--tenant your-tenant \
|
|
74
|
+
--json \
|
|
75
|
+
--page 1 \
|
|
76
|
+
--size 50`
|
|
77
|
+
|
|
78
|
+
// 2. Parse structured response
|
|
79
|
+
const { success, data, meta } = JSON.parse(result.stdout)
|
|
80
|
+
|
|
81
|
+
// 3. Work with data
|
|
82
|
+
const pendingOrders = data.items
|
|
83
|
+
|
|
84
|
+
// 4. Execute operations safely
|
|
85
|
+
for (const order of pendingOrders) {
|
|
86
|
+
// Always dry-run first (AI safety)
|
|
87
|
+
const preview = await $`barista liberica sales-orders delete ${order.id} --dry-run`
|
|
88
|
+
|
|
89
|
+
// Parse preview, verify, then execute with --force
|
|
90
|
+
// ...
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Response Envelope
|
|
95
|
+
|
|
96
|
+
All JSON responses follow this structure:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"success": true,
|
|
101
|
+
"data": {
|
|
102
|
+
"items": [...],
|
|
103
|
+
"pagination": { "page": 1, "size": 20, "total": 150 }
|
|
104
|
+
},
|
|
105
|
+
"meta": {
|
|
106
|
+
"requestId": "req-abc123",
|
|
107
|
+
"timestamp": "2024-01-15T10:30:00Z",
|
|
108
|
+
"environment": "prod-cn",
|
|
109
|
+
"tenant": "your-tenant"
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
**Error format:**
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"success": false,
|
|
119
|
+
"error": {
|
|
120
|
+
"code": "A150001",
|
|
121
|
+
"message": "Order not found"
|
|
122
|
+
},
|
|
123
|
+
"meta": {
|
|
124
|
+
"requestId": "req-xyz789",
|
|
125
|
+
"timestamp": "2024-01-15T10:30:00Z"
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### AI Skills for Your Assistant
|
|
131
|
+
|
|
132
|
+
Install the barista-cli Skill so your AI assistant knows all available commands, system quirks, and safety rules:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
# Interactive install (pick your platform)
|
|
136
|
+
barista skills install
|
|
137
|
+
|
|
138
|
+
# Direct install for specific AI tool
|
|
139
|
+
barista skills install --ai claude # → .claude/skills/barista-cli/SKILL.md
|
|
140
|
+
barista skills install --ai trae # → .trae/skills/barista-cli/SKILL.md
|
|
141
|
+
barista skills install --ai opencode # → .opencode/skills/barista-cli/SKILL.md
|
|
142
|
+
barista skills install --ai cursor # → .cursor/rules/barista-cli.mdc
|
|
143
|
+
|
|
144
|
+
# Global install (all projects)
|
|
145
|
+
barista skills install --ai claude --global
|
|
146
|
+
|
|
147
|
+
# List all supported platforms
|
|
148
|
+
barista skills install --list
|
|
149
|
+
|
|
150
|
+
# Search commands by intent (without the AI skill)
|
|
151
|
+
barista skills query "采购订单" # fuzzy search
|
|
152
|
+
barista skills query "入库单" --domain liberica # filter by service
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
**The Skill covers**: Liberica 76-module production management + Arabica subscription platform, with critical traps (email login, hidden --tenant, epoch timestamps), safety rules (dry-run→force), and auto-generated command data.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 🚀 Features
|
|
160
|
+
|
|
161
|
+
### AI-First Design
|
|
162
|
+
|
|
163
|
+
| Feature | Description |
|
|
164
|
+
|---------|-------------|
|
|
165
|
+
| 🤖 **JSON-First Output** | All commands support `--json` for AI parsing |
|
|
166
|
+
| 📦 **Structured Responses** | Consistent `{success, data, meta}` envelope |
|
|
167
|
+
| 🔄 **Idempotent Operations** | Safe for AI retry loops |
|
|
168
|
+
| 🛡️ **Dry-Run by Default** | Destructive operations preview before execution |
|
|
169
|
+
| 🔐 **Secure Storage** | Credentials in system keychain, not env vars |
|
|
170
|
+
|
|
171
|
+
### Enterprise Connectivity
|
|
172
|
+
|
|
173
|
+
| Service | For | Capabilities |
|
|
174
|
+
|---------|-----|-------------|
|
|
175
|
+
| ☕ **Liberica** | Tenant employees | Production management: supply chain, inventory, BOM/routing, work orders, quality, finance, HR (70+ modules) |
|
|
176
|
+
| 🛒 **Arabica** | Members (membership) | Subscribe to Liberica: plan browsing, order placement, invoice download, enterprise registration |
|
|
177
|
+
|
|
178
|
+
> **Arabica → Liberica flow**: Register as member → register enterprise → subscribe to plan → get Liberica access → log in as employee
|
|
179
|
+
|
|
180
|
+
### Operational Safety
|
|
181
|
+
|
|
182
|
+
- 📊 **Audit Trail** — Every operation logged with request ID
|
|
183
|
+
- ⚠️ **Confirmation Guards** — `--dry-run` / `--force` for write operations
|
|
184
|
+
- 🏢 **Multi-Tenant Isolation** — Credentials isolated per tenant
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 🔧 Command Reference
|
|
189
|
+
|
|
190
|
+
### Core Pattern
|
|
191
|
+
|
|
192
|
+
```
|
|
193
|
+
barista <service> <resource> <action> [options]
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Global Options
|
|
197
|
+
|
|
198
|
+
| Option | Description | Default |
|
|
199
|
+
|--------|-------------|---------|
|
|
200
|
+
| `--env` | Environment (dev\|test\|prod-cn\|prod-jp) | `dev` |
|
|
201
|
+
| `--tenant` | Tenant name | - |
|
|
202
|
+
| `--json` | JSON output | `false` |
|
|
203
|
+
| `--dry-run` | Preview mode (recommended for AI) | `false` |
|
|
204
|
+
| `--force` | Skip confirmation | `false` |
|
|
205
|
+
| `--page` | Page number | `1` |
|
|
206
|
+
| `--size` | Page size (max items) | `20` |
|
|
207
|
+
|
|
208
|
+
### Quick Reference
|
|
209
|
+
|
|
210
|
+
| Command | Description |
|
|
211
|
+
|---------|-------------|
|
|
212
|
+
| `barista context show` | Show current env/tenant context |
|
|
213
|
+
| `barista context use-env <env>` | Switch environment |
|
|
214
|
+
| `barista context use-tenant <tenant>` | Switch tenant |
|
|
215
|
+
| `barista liberica auth login <env> <tenant> <user> <pass>` | Liberica login (tenant employee) |
|
|
216
|
+
| `barista arabica auth login <env> <account> <pass>` | Arabica login (member) |
|
|
217
|
+
| `barista liberica sales-orders list --json` | List sales orders |
|
|
218
|
+
| `barista liberica purchase-orders list --json` | List purchase orders |
|
|
219
|
+
| `barista liberica transfer-in-forms create --dry-run ...` | Preview stock-in |
|
|
220
|
+
| `barista liberica materials list --json` | List materials |
|
|
221
|
+
| `barista arabica plans list --json` | Browse subscription plans |
|
|
222
|
+
| `barista arabica subscription current --json` | Check subscription |
|
|
223
|
+
| `barista skills install --ai claude` | Install AI skill |
|
|
224
|
+
| `barista skills query "采购订单"` | Search commands by intent |
|
|
225
|
+
|
|
226
|
+
**[→ Full Command Reference](./docs/commands/REFERENCE.md)**
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## 🛡️ AI Safety Guidelines
|
|
231
|
+
|
|
232
|
+
### 1. Always Dry-Run First
|
|
233
|
+
|
|
234
|
+
```typescript
|
|
235
|
+
// ❌ Wrong - executing blindly
|
|
236
|
+
await $`barista liberica sales-orders delete 12345`
|
|
237
|
+
|
|
238
|
+
// ✅ Correct - preview first
|
|
239
|
+
const preview = await $`barista liberica sales-orders delete 12345 --dry-run`
|
|
240
|
+
// Parse preview, verify correctness, then:
|
|
241
|
+
await $`barista liberica sales-orders delete 12345 --force`
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### 2. Check Success Before Proceeding
|
|
245
|
+
|
|
246
|
+
```typescript
|
|
247
|
+
const result = JSON.parse(stdout)
|
|
248
|
+
if (!result.success) {
|
|
249
|
+
// Handle error, don't continue
|
|
250
|
+
throw new Error(result.error?.message || result.meta?.message)
|
|
251
|
+
}
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### 3. Use Request IDs for Debugging
|
|
255
|
+
|
|
256
|
+
```typescript
|
|
257
|
+
const { meta } = JSON.parse(stdout)
|
|
258
|
+
console.log(`Request ID: ${meta.requestId}`)
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### 4. Respect Rate Limits
|
|
262
|
+
|
|
263
|
+
- Add delays between bulk operations
|
|
264
|
+
- Use `--size 100` for bulk fetches
|
|
265
|
+
- Cache responses when appropriate
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## ⚙️ Configuration
|
|
270
|
+
|
|
271
|
+
### File Location
|
|
272
|
+
|
|
273
|
+
`~/.barista/config.yaml`
|
|
274
|
+
|
|
275
|
+
### Quick Config
|
|
276
|
+
|
|
277
|
+
```yaml
|
|
278
|
+
defaults:
|
|
279
|
+
env: prod-cn
|
|
280
|
+
tenant: your-tenant
|
|
281
|
+
service: liberica
|
|
282
|
+
|
|
283
|
+
environments:
|
|
284
|
+
prod-cn:
|
|
285
|
+
liberica:
|
|
286
|
+
baseUrl: "https://{tenant}.newpeaksh.com"
|
|
287
|
+
timeout: 60000
|
|
288
|
+
arabica:
|
|
289
|
+
baseUrl: "https://www.newpeaksh.com"
|
|
290
|
+
timeout: 60000
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### Authentication
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
# Liberica (tenant employee login)
|
|
297
|
+
barista liberica auth login <env> <tenant> <username> <password>
|
|
298
|
+
barista liberica auth login # interactive prompt
|
|
299
|
+
|
|
300
|
+
# Arabica (member login — no tenant needed)
|
|
301
|
+
barista arabica auth login <env> <account> <password>
|
|
302
|
+
barista arabica auth login # interactive prompt
|
|
303
|
+
barista arabica auth register # register new member account
|
|
304
|
+
|
|
305
|
+
# Check / logout
|
|
306
|
+
barista auth status
|
|
307
|
+
barista auth logout --service liberica --env prod-cn
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
**Common login traps:**
|
|
311
|
+
- Email usernames must use positional args (`barista liberica auth login dev sh my@email.com pass`), not `--username`
|
|
312
|
+
- Liberica = tenant username + password; Arabica = account + password (no tenant)
|
|
313
|
+
|
|
314
|
+
### Multi-Tenant Library Usage
|
|
315
|
+
|
|
316
|
+
For library consumers (bots, scripts) that need to call **multiple tenants in the same process**, two patterns are supported.
|
|
317
|
+
|
|
318
|
+
#### Pattern A — serial via `configManager.withContext`
|
|
319
|
+
|
|
320
|
+
```typescript
|
|
321
|
+
import { configManager } from '@newpeak/barista-cli/core/config/manager';
|
|
322
|
+
import { apiClient } from '@newpeak/barista-cli/core/api/client';
|
|
323
|
+
|
|
324
|
+
// 串行调用不同租户(每段结束后自动还原默认 context)
|
|
325
|
+
await configManager.withContext(
|
|
326
|
+
{ tenant: 'tenant-a', environment: 'env-x' },
|
|
327
|
+
() => apiClient.listTeamTasks({ status: 'PROCESSING' })
|
|
328
|
+
);
|
|
329
|
+
|
|
330
|
+
await configManager.withContext(
|
|
331
|
+
{ tenant: 'tenant-b', environment: 'env-x' },
|
|
332
|
+
() => apiClient.listTeamTasks({ status: 'PROCESSING' })
|
|
333
|
+
);
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
`Partial<Context>` means you can override only the fields that differ (e.g. just `tenant`); other fields fall back to your current config defaults. Exception-safe (`try/finally`) so failed inner calls do not leak overrides.
|
|
337
|
+
|
|
338
|
+
#### Pattern B — true parallel via `Promise.all`
|
|
339
|
+
|
|
340
|
+
Every `apiClient.METHOD(env, tenant, ...args)` already takes `(environment, tenant, …)` positionally, with `createAPIClient()` creating a fresh axios instance per call. That means `Promise.all` against N tenants **just works** — each concurrent call gets its own baseURL + its own token:
|
|
341
|
+
|
|
342
|
+
```typescript
|
|
343
|
+
import { apiClient } from '@newpeak/barista-cli/core/api/client';
|
|
344
|
+
|
|
345
|
+
// 真并行:每个请求走自己的 baseURL + Authorization,互不干扰
|
|
346
|
+
const [tasksA, tasksB, tasksC] = await Promise.all([
|
|
347
|
+
apiClient.listTeamTasks('dev', 'tenant-a', { status: 'PROCESSING' }),
|
|
348
|
+
apiClient.listTeamTasks('dev', 'tenant-b', { status: 'PROCESSING' }),
|
|
349
|
+
apiClient.listTeamTasks('prod-cn', 'tenant-c', { status: 'PROCESSING' }),
|
|
350
|
+
]);
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
Combine both patterns when needed — `withContext` for command-style code that reads `configManager.getCurrentContext()`, direct positional args for parallel-safe `Promise.all`.
|
|
354
|
+
|
|
355
|
+
> Both patterns rely on `tokenManager.getToken({service, environment, tenant})` being keyed by all three fields — which it is. Tokens for different tenants are cached and fetched independently.
|
|
356
|
+
|
|
357
|
+
> ⚠️ tenant / environment must be provided by the caller at runtime. Do not hardcode specific tenant names or environment names in code, examples, or tests (only the input-validation whitelist in `ConfigManager.setEnvironment` may list legal env values).
|
|
358
|
+
|
|
359
|
+
---
|
|
360
|
+
|
|
361
|
+
## ❓ Troubleshooting
|
|
362
|
+
|
|
363
|
+
### Auth Failures
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
barista auth status # check token status by env
|
|
367
|
+
barista liberica auth login dev tenant user pass # re-authenticate
|
|
368
|
+
barista context show # verify env + tenant
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
### API Errors
|
|
372
|
+
|
|
373
|
+
```bash
|
|
374
|
+
barista liberica sales-orders list --json # always --json for error codes
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
| Error | Meaning | Fix |
|
|
378
|
+
|-------|---------|-----|
|
|
379
|
+
| `B0301` | Token expired | Re-login |
|
|
380
|
+
| `A958001` | Wrong tenant (teams) | `barista context use-tenant <correct>` then retry |
|
|
381
|
+
| `B0001` | Date format error | Dates must be epoch ms (use `Date.now()`), not `"YYYY-MM-DD"` |
|
|
382
|
+
| `A0900006` | Email username via `--username` | Use positional args instead |
|
|
383
|
+
| `A1506` | teams issue close needs assignee | Use `update --status CLOSED --assign-to <id>` |
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## 📚 Related Projects
|
|
388
|
+
|
|
389
|
+
| Project | Description |
|
|
390
|
+
|---------|-------------|
|
|
391
|
+
| ☕ Liberica Backend | Production management SaaS backend |
|
|
392
|
+
| 🖥️ Liberica Frontend | Production management web UI |
|
|
393
|
+
| 📱 Liberica Mobile | Production management mobile app |
|
|
394
|
+
| 🛒 Arabica Backend | Online subscription SaaS backend |
|
|
395
|
+
| 🌐 Arabica Frontend | Online subscription web UI |
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
## 📄 License
|
|
400
|
+
|
|
401
|
+
[MIT](LICENSE) © Newpeak Technology
|