@newpeak/barista-cli 0.1.0

package/.eslintrc.json

@@ -0,0 +1,23 @@
+{
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "no-console": "off",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+  },
+  "ignorePatterns": ["dist/", "node_modules/", "*.js"]
+}

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/.sisyphus/notepads/liberica-employees/learnings.md

@@ -0,0 +1,73 @@
+# Liberica Employees - Learnings
+
+## API Patterns Observed
+
+- API expects token WITHOUT "Bearer " prefix
+- API prefix: /api
+- Pagination is 0-based on backend
+- Response fields: rows, pageNo, pageSize, totalRows
+- Backend error format: {success, code, message} directly (not nested under error object)
+- organizationId is `string` (was BigInteger), positionId is `string`
+
+## CRITICAL: BigInteger IDs
+
+**Backend returns BigInteger for all ID fields, which exceeds JavaScript number range.**
+
+```typescript
+// WRONG - Precision loss for IDs > 9007199254740991
+employeeId: number
+
+// CORRECT
+employeeId: string
+```
+
+**Affected interfaces:**
+- Employee.employeeId
+- Employee.organizationId
+- UpdateEmployeeRequest.employeeId
+- OrgListItem.id (for cached org/position lookups)
+
+## CRITICAL: Do NOT Use X-TENANT-ID Header
+
+The tenant is embedded in the JWT token. Passing `X-TENANT-ID` with string tenant name causes:
+```
+NumberFormatException: For input string: "shanghai"
+```
+
+Backend expects numeric tenant ID or no header at all.
+
+## HTTP Methods Matter
+
+| Endpoint | Method | Common Error |
+|----------|--------|--------------|
+| `/master/org/tree` | POST (not GET!) | A1504: 当前接口不支持GET方式请求 |
+| `/master/position/list` | GET | - |
+| `/employee/delete` | POST | - |
+
+## Error Response Normalization
+
+Backend returns errors in two formats - must normalize in handleApiError:
+
+```typescript
+// Format 1: Error at top level
+{ success: false, code: "A150001", message: "查询结果不存在" }
+
+// Format 2: Nested under error
+{ success: false, error: { code: "01001150001", message: "职员不存在" } }
+```
+
+## Implementation Decisions
+
+- In-memory cache (Map) for org/position lists with 5-minute TTL
+- Cache key: `${environment}:${tenant}`
+- Generic lookup types (OrgListItem, PositionListItem) with `id` + `name` for reuse across modules
+- Create command resolves names to IDs before building request; exits with descriptive error if not found
+- Position ID stays as string (backend contract)
+- All IDs use string type to handle BigInteger without precision loss
+
+## Debugging Tips
+
+1. Add `console.error('[DEBUG]', ...)` to see raw API responses
+2. Use `--json` flag to get full response data with IDs
+3. Token stored in `~/.barista/.barista-tokens` (binary format)
+4. Config stored in `~/.barista/config.yaml`

package/AGENTS.md

@@ -0,0 +1,270 @@
+# AGENTS.md - Barista CLI
+
+**Project**: Node.js CLI (TypeScript) for Liberica & Arabica services
+**Updated**: 2025-04-13
+
+## Quick Commands
+
+```bash
+cd coffee-barista-cli
+
+npm run build      # Build TypeScript
+npm run dev        # Watch mode
+npm run test:unit  # Run tests (single run)
+npm test           # Watch mode
+npm run lint       # ESLint check
+npm run lint -- --fix  # Auto-fix
+
+# Run CLI directly
+node ./bin/barista.js --help
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts                      # Main entry - Commander setup
+├── commands/
+│   ├── context.ts                # Context management
+│   ├── auth.ts                   # Auth commands
+│   ├── liberica/
+│   │   ├── index.ts              # Liberica service entry
+│   │   ├── auth/index.ts         # Liberica auth
+│   │   ├── context/index.ts      # Liberica context
+│   │   └── employees/            # Employee CRUD commands
+│   └── arabica/
+│       └── auth/                 # Arabica auth commands
+├── core/
+│   ├── auth/token-manager.ts     # Keychain token storage
+│   ├── config/manager.ts         # YAML config (~/.barista/config.yaml)
+│   └── api/client.ts             # API client (axios wrapper)
+└── types/
+    ├── index.ts
+    ├── employee.ts
+    ├── org.ts
+    └── position.ts
+```
+
+## CRITICAL: API Integration Rules
+
+**These rules are hard-won. Breaking them causes silent failures.**
+
+### 1. BigInteger IDs → Use String Type
+
+Backend returns BigInteger for all ID fields, exceeding JS `number` range (max: 9007199254740991).
+
+```typescript
+// WRONG - precision loss
+employeeId: number
+
+// CORRECT
+employeeId: string
+```
+
+**All ID fields from backend MUST be `string`.**
+
+### 2. Do NOT Use X-TENANT-ID Header
+
+Tenant is embedded in JWT token. Passing `X-TENANT-ID` causes:
+```
+NumberFormatException: For input string: "shanghai"
+```
+
+```typescript
+// WRONG
+{ headers: { 'X-TENANT-ID': tenant } }
+
+// CORRECT - omit header entirely
+```
+
+### 3. Authorization: No "Bearer " Prefix
+
+```typescript
+// WRONG
+'Authorization': `Bearer ${token}`
+
+// CORRECT
+'Authorization': token
+```
+
+### 4. HTTP Methods Vary by Endpoint
+
+Always check the backend controller for correct method:
+
+| Endpoint | Method | Notes |
+|----------|--------|-------|
+| `/employee/page` | GET | Paginated list |
+| `/employee/detail` | GET | Single item |
+| `/employee/add\|edit\|delete` | POST | Write operations |
+| `/master/org/tree` | POST | NOT GET |
+| `/master/position/list` | GET | - |
+
+### 5. Error Response Has Two Formats
+
+Backend returns errors in different structures:
+
+```typescript
+// Format 1: Top-level error (common)
+{ success: false, code: "A150001", message: "查询结果不存在" }
+
+// Format 2: Nested under 'error'
+{ success: false, error: { code: "01001150001", message: "职员不存在" } }
+```
+
+Must normalize in `handleApiError()`.
+
+### 6. Pagination: 0-Based, Use pageNo/pageSize
+
+```typescript
+// CLI page 1 → API page 0
+const pageNo = parseInt(options.page) - 1;
+// Query: /employee/page?pageNo=0&pageSize=20
+```
+
+### 7. Response Field Names Differ
+
+| Backend | Common Mistake |
+|---------|---------------|
+| `rows` | `records` |
+| `pageNo` | `current` |
+| `pageSize` | `size` |
+| `totalRows` | `total` |
+
+## Common Issues & Fixes
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `A1504: 不支持GET方式` | Wrong HTTP method | Use POST for `/org/tree` |
+| `NumberFormatException` | Using `X-TENANT-ID` header | Remove header |
+| Precision loss on IDs | Using `number` for BigInteger | Use `string` |
+| "not found" for valid ID | ID truncated due to precision loss | Use string type |
+| Empty data despite records | Field name mismatch | Check `rows` not `records` |
+
+## CLI Conventions
+
+### Command Structure
+- Factory functions: `createXxxCommand(): Command`
+- Subcommands via `.addCommand()`
+- Commander.js 12 (not oclif/yargs)
+
+### Output Formatting
+- TTY auto-detection: tables for humans, JSON for scripts
+- `--json` flag forces JSON output
+- `chalk` for colors, `cli-table3` for tables
+
+### Imports
+- Use `.js` extension even in TypeScript: `'../../core/config/manager.js'`
+- Async parse: `program.parseAsync()` not `parse()`
+
+## Token & Config
+
+- Tokens: System keychain only (keytar), NOT files
+- Key: `{service}:{environment}:{tenant}` (e.g., `liberica:dev:shanghai`)
+- Config: `~/.barista/config.yaml`
+- First run creates config with defaults
+
+## Adding Commands (MANDATORY: Design First)
+
+1. Read `docs/COMMAND_DESIGN_SPEC.md`
+2. Find backend Controller endpoints (check facade modules)
+3. Create design doc at `docs/commands/{service}/{resource}/{action}.md`
+4. Implement following existing patterns
+5. Write unit tests
+6. Verify: `npm run build && npm run test:unit`
+
+## Functional Verification Workflow
+
+**Always verify new commands against the real API before committing.**
+
+### Standard Test Environment
+
+```bash
+# Environment: dev
+# Tenant: shanghai
+# User: admin@shanghai.newpeaksh.com
+# Password: 123456
+```
+
+### Workflow
+
+```bash
+cd coffee-barista-cli
+
+# 1. Build
+npm run build
+
+# 2. Login to Liberica
+node ./bin/barista.js liberica auth login dev shanghai admin@shanghai.newpeaksh.com 123456
+
+# 3. Verify login
+node ./bin/barista.js context show
+
+# 4. Test command (use --json to see full IDs)
+node ./bin/barista.js liberica employees list --json
+
+# 5. Test specific operations
+node ./bin/barista.js liberica employees get <id>
+node ./bin/barista.js liberica employees create -n "测试" --no "9999"
+node ./bin/barista.js liberica employees delete <id> --force
+
+# 6. For create with org/position:
+node ./bin/barista.js liberica employees create \
+  -n "测试员工" \
+  -p "13300000000" \
+  -e "test@example.com" \
+  -s M \
+  --org "销售部" \
+  --position "经理" \
+  --no "TEST001"
+```
+
+### Why This Matters
+
+- Unit tests mock the API but don't catch real integration issues
+- BigInteger ID precision only shows with actual API responses
+- Backend may return different error formats than mocks
+- HTTP method issues only appear with real calls
+
+### Troubleshooting
+
+```bash
+# Check current context
+node ./bin/barista.js context show
+
+# Re-login if token expired
+node ./bin/barista.js liberica auth login dev shanghai admin@shanghai.newpeaksh.com 123456
+
+# Debug: use --json to see full response
+node ./bin/barista.js liberica employees list --json
+
+# Debug: check API calls
+# Add to client.ts temporarily:
+console.error('[DEBUG]', JSON.stringify(response.data));
+```
+
+## Testing
+
+- Vitest with TypeScript
+- Mock `keytar` and `axios`
+- Tests co-located: `tests/unit/commands/...`
+
+## Key Files Reference
+
+| Purpose | File |
+|---------|------|
+| API client | `src/core/api/client.ts` |
+| Types | `src/types/employee.ts`, `org.ts`, `position.ts` |
+| Commands | `src/commands/liberica/employees/*.ts` |
+| Integration lessons | `docs/INTEGRATION_NOTES.md` |
+| Command design | `docs/COMMAND_DESIGN_SPEC.md` |
+
+## Environment URLs
+
+```
+Liberica: https://{tenant}-{env}.newpeaksh.com
+  dev:     https://{tenant}-dev.newpeaksh.com
+  prod-jp: https://{tenant}.newpeakjp.com
+
+Arabica: https://arabica-{env}.newpeaksh.com
+  prod:   https://www.newpeaksh.com
+```

package/CONTRIBUTING.md

@@ -0,0 +1,291 @@
+# Contributing to Barista CLI
+
+Thank you for your interest in contributing to Barista CLI! This document provides guidelines and instructions for contributing.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### Initial Setup
+
+```bash
+# Clone the repository
+git clone https://gitlab.newpeaksh.com/coffee/coffee-barista-cli.git
+cd coffee-barista-cli
+
+# Install dependencies
+npm install
+
+# Link CLI for local development
+npm link
+
+# Verify installation
+barista --version
+```
+
+### VS Code Setup
+
+Recommended extensions:
+- ESLint
+- Prettier
+- TypeScript Vue Plugin (Volar)
+
+## Development Workflow
+
+### ⚠️ IMPORTANT: Design First, Code Later
+
+**Before writing ANY code, you MUST complete the design phase.**
+
+Skipping design leads to:
+- Wrong API endpoints (like Arabica register using `/api/member/user/register` instead of `/member/user/register`)
+- Missing required parameters
+- Inconsistent command structures
+- Rework and wasted time
+
+### 1. Design Phase (MANDATORY)
+
+1. Read `docs/COMMAND_DESIGN_SPEC.md`
+2. Find backend Controller:
+   ```bash
+   # Example: Find the register endpoint
+   grep -r "register" --include="*.java" ../coffee-arabica-end/facade/
+   ```
+3. Document the command design:
+   - API endpoint and HTTP method
+   - All parameters (required vs optional)
+   - Request/Response DTOs
+   - Error codes and handling
+4. Create design document: `docs/commands/{service}/{resource}/{action}/index.md`
+5. **Get design reviewed** before coding
+
+### 2. Create a Branch
+
+```bash
+git checkout -b feature/my-feature
+# or
+git checkout -b fix/bug-description
+```
+
+### 3. Implement Changes (After Design Approved)
+
+- Write TypeScript code following the approved design
+- Follow existing command patterns
+- Add or update tests
+- Update documentation if needed
+
+### 4. Run Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run tests in watch mode
+npm test -- --watch
+```
+
+### 5. Lint and Format
+
+```bash
+# Check code style
+npm run lint
+
+# Auto-fix linting issues
+npm run lint -- --fix
+
+# Format code with Prettier
+npm run format
+```
+
+### 6. Build
+
+```bash
+# Build TypeScript
+npm run build
+
+# Watch mode for development
+npm run dev
+```
+
+### 7. Commit Changes
+
+Follow commit message conventions (see below).
+
+### 8. Push and Create PR
+
+```bash
+git push origin feature/my-feature
+# Then create PR via GitLab UI
+```
+
+## Code Style
+
+We use ESLint and Prettier for code formatting:
+
+- **TypeScript**: Strict mode enabled
+- **ESM**: All code uses ES modules with `.js` extensions in imports
+- **Semicolons**: Required
+- **Quotes**: Single quotes for strings
+- **Indentation**: 2 spaces
+
+### Import Order
+
+```typescript
+// 1. Node.js built-ins
+import fs from 'fs';
+import path from 'path';
+
+// 2. External packages
+import chalk from 'chalk';
+import { Command } from 'commander';
+
+// 3. Internal packages (relative)
+import { configManager } from '../core/config/manager.js';
+import { tokenManager } from '../core/auth/token-manager.js';
+import type { Context, Config } from '../types/index.js';
+```
+
+## Commit Message Conventions
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| feat | New feature |
+| fix | Bug fix |
+| docs | Documentation changes |
+| style | Formatting, missing semicolons, etc. |
+| refactor | Code refactoring |
+| test | Adding tests |
+| chore | Maintenance tasks |
+
+### Examples
+
+```bash
+# Feature
+git commit -m "feat(liberica): add orders cancel command"
+
+# Bug fix
+git commit -m "fix(auth): handle token expiration gracefully"
+
+# Documentation
+git commit -m "docs: update README with new command examples"
+
+# Refactoring
+git commit -m "refactor(config): extract environment validation"
+```
+
+## Testing
+
+### Test Structure
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+describe('module name', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should do something specific', () => {
+    // Arrange
+    const input = 'test';
+
+    // Act
+    const result = functionUnderTest(input);
+
+    // Assert
+    expect(result).toBe('expected');
+  });
+});
+```
+
+### Running Specific Tests
+
+```bash
+# Run tests matching a pattern
+npm test -- orders
+
+# Run with coverage
+npm test -- --coverage
+
+# Run in watch mode for specific file
+npm test -- src/commands/context.test.ts --watch
+```
+
+## Project Structure
+
+```
+coffee-barista-cli/
+├── bin/
+│   └── barista              # CLI entry point
+├── src/
+│   ├── index.ts             # Main entry
+│   ├── commands/            # Command implementations
+│   │   ├── context.ts
+│   │   ├── auth.ts
+│   │   ├── liberica/
+│   │   │   ├── orders.ts
+│   │   │   ├── products.ts
+│   │   │   └── index.ts
+│   │   └── arabica/
+│   │       └── index.ts
+│   ├── core/                # Core functionality
+│   │   ├── config/
+│   │   │   └── manager.ts
+│   │   └── auth/
+│   │       └── token-manager.ts
+│   ├── types/
+│   │   └── index.ts
+│   └── utils/
+├── tests/
+│   ├── unit/               # Unit tests
+│   ├── integration/        # Integration tests
+│   └── fixtures/           # Test fixtures
+├── docs/                   # Documentation
+└── package.json
+```
+
+## Documentation
+
+When adding new features, update relevant docs:
+
+- **New command**: 
+  1. **必须先**阅读 [命令设计规范](./docs/COMMAND_DESIGN_SPEC.md)
+  2. 编写设计文档（按规范模板）
+  3. 更新 `docs/COMMANDS.md`
+- **Architecture changes**: Update `docs/ARCHITECTURE.md`
+- **README.md**: Update if CLI interface changes
+
+## Pull Request Checklist
+
+- [ ] Code follows style guidelines (lint passes)
+- [ ] Tests added/updated and passing
+- [ ] Documentation updated
+- [ ] Commit messages follow conventions
+- [ ] Build succeeds (`npm run build`)
+
+## Questions?
+
+For questions or discussions:
+- Open an issue in the repository
+- Contact the development team
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.