kob-cli 1.0.0

package/AGENTS.md

@@ -0,0 +1,351 @@
+# AGENTS.md - KOB CLI Agent Specification
+
+## Overview
+
+This document provides comprehensive specifications for AI agents working on the KOB CLI project. It covers architecture, development guidelines, and best practices.
+
+## Architecture
+
+### High-Level Design
+
+```
+┌─────────────────────────────────────────────┐
+│              CLI Entry Point                 │
+│            (src/index.ts)                    │
+└──────────────┬──────────────────────────────┘
+               │
+               │ Commander.js
+               ▼
+┌─────────────────────────────────────────────┐
+│            Command Layer                     │
+│  (src/commands/*.ts)                         │
+│  - auth.ts, chat.ts, stream.ts              │
+│  - models.ts, projects.ts, rules.ts         │
+│  - credits.ts                                │
+└──────────────┬──────────────────────────────┘
+               │
+               │ Business Logic
+               ▼
+┌─────────────────────────────────────────────┐
+│            Utility Layer                     │
+│  (src/utils/*.ts)                            │
+│  - api.ts (HTTP Client)                      │
+│  - config.ts (Configuration)                 │
+│  - format.ts (Output Formatting)             │
+│  - errors.ts (Error Handling)                │
+└──────────────┬──────────────────────────────┘
+               │
+               │ Fetch API
+               ▼
+┌─────────────────────────────────────────────┐
+│          KOB AI API Server                   │
+│  https://www.kob-ai.dev/api/*                 │
+└─────────────────────────────────────────────┘
+```
+
+### Module Responsibilities
+
+#### 1. Entry Point (`src/index.ts`)
+- Initialize Commander.js program
+- Register all commands
+- Display help text
+- Parse command-line arguments
+
+#### 2. Command Layer (`src/commands/`)
+
+**auth.ts**
+- `auth:verify` - Verify API credentials
+- `balance` - Check credit balance
+
+**chat.ts**
+- `chat` - Single message to AI
+- `chat:interactive` - REPL mode for conversation
+
+**stream.ts**
+- `stream` - Real-time streaming AI responses
+
+**models.ts**
+- `models` - List available AI models
+
+**projects.ts**
+- `projects:list` - List all projects
+- `projects:create` - Create new project
+- `projects:update` - Update existing project
+- `projects:delete` - Delete project
+
+**rules.ts**
+- `rules:list` - List project rules
+- `rules:create` - Create new rule
+- `rules:update` - Update existing rule
+- `rules:delete` - Delete rule
+
+**credits.ts**
+- `credits:history` - View credit top-up history
+
+#### 3. Utility Layer (`src/utils/`)
+
+**api.ts**
+- `KobApiClient` class
+- HTTP methods: GET, POST, PATCH, DELETE
+- Streaming support with async generators
+- Automatic authentication injection
+- Error handling
+
+**config.ts**
+- `getConfig()` - Load environment variables
+- `validateConfig()` - Validate configuration
+- Fallback to default values
+
+**format.ts**
+- `formatDate()` - Format timestamps
+- `formatProjects()` - Format project list
+- `formatRules()` - Format rules list
+- `formatCreditHistory()` - Format credit history
+- `formatUsage()` - Format usage statistics
+
+**errors.ts**
+- `ApiError` class - Custom error type
+- `handleApiError()` - User-friendly error messages
+- `validateRequired()` - Input validation
+
+#### 4. Type Definitions (`src/types/index.ts`)
+- All TypeScript interfaces
+- API response types
+- Request/Response schemas
+
+## Development Guidelines
+
+### Adding New Commands
+
+1. **Create Command File**
+```typescript
+// src/commands/mycommand.ts
+import { Command } from 'commander';
+import { KobApiClient } from '../utils/api.js';
+import { getConfig } from '../utils/config.js';
+
+export const myCommand = new Command('mycommand')
+  .description('My new command')
+  .action(async () => {
+    // Implementation
+  });
+```
+
+2. **Register in Entry Point**
+```typescript
+// src/index.ts
+import { myCommand } from './commands/mycommand.js';
+program.addCommand(myCommand);
+```
+
+### API Client Usage
+
+```typescript
+const config = getConfig();
+const client = new KobApiClient(config);
+
+// POST request
+const data = await client.post<ResponseType>('/api/endpoint', {
+  key: 'value'
+});
+
+// GET request
+const data = await client.get<ResponseType>('/api/endpoint', {
+  param: 'value'
+});
+
+// Streaming
+for await (const event of client.stream('/api/stream', body)) {
+  if (event.type === 'chunk') {
+    // Handle chunk
+  }
+}
+```
+
+### Error Handling Pattern
+
+```typescript
+try {
+  const spinner = ora('Loading...').start();
+  
+  // API call
+  const data = await client.post('/api/endpoint', body);
+  
+  spinner.succeed('Success!');
+  console.log(data);
+} catch (error) {
+  spinner.fail('Failed');
+  handleApiError(error);
+}
+```
+
+### Type Safety
+
+Always use TypeScript types:
+```typescript
+import type { ChatResponse } from '../types/index.js';
+
+const data = await client.post<ChatResponse>('/api/ai/chat', body);
+// data is properly typed
+```
+
+## Testing Strategy
+
+### Manual Testing Checklist
+
+1. **Authentication**
+   - [ ] `auth:verify` with valid credentials
+   - [ ] `auth:verify` with invalid credentials
+   - [ ] `balance` command
+
+2. **Chat**
+   - [ ] `chat` with different providers
+   - [ ] `chat:interactive` mode
+   - [ ] Chat with project rules
+
+3. **Streaming**
+   - [ ] `stream` with different models
+   - [ ] Stream error handling
+
+4. **Models**
+   - [ ] `models` list all
+   - [ ] `models --provider` filter
+   - [ ] `models --format json`
+
+5. **Projects**
+   - [ ] Create, list, update, delete
+
+6. **Rules**
+   - [ ] Create, list, update, delete
+   - [ ] Different rule types
+
+7. **Credits**
+   - [ ] `credits:history` with pagination
+
+### Common Test Scenarios
+
+```bash
+# Test authentication
+bun dev auth:verify
+
+# Test chat
+bun dev chat "Hello" --provider DeepSeek --model deepseek-chat
+
+# Test streaming
+bun dev stream "Tell me a story" --model deepseek-chat
+
+# Test projects
+bun dev projects:create "Test Project"
+bun dev projects:list
+```
+
+## Best Practices
+
+### Code Style
+
+1. **Use async/await** - Not promises or callbacks
+2. **Type everything** - No `any` types unless necessary
+3. **Error handling** - Always use try/catch with handleApiError
+4. **User feedback** - Use ora spinners for loading states
+5. **Output formatting** - Use chalk for colors, format functions for consistency
+
+### Performance
+
+1. **Lazy loading** - Import only what's needed
+2. **Connection reuse** - Single API client instance per command
+3. **Streaming** - Use for long responses to improve UX
+
+### Security
+
+1. **Environment variables** - Never hardcode credentials
+2. **Validation** - Validate all user inputs
+3. **Error messages** - Don't expose sensitive info in errors
+
+## Common Issues & Solutions
+
+### Issue: Type import errors
+**Solution:** Use `import type` for types
+```typescript
+import type { ChatResponse } from '../types/index.js';
+```
+
+### Issue: Undefined content in streams
+**Solution:** Check for undefined before using
+```typescript
+if (event.content) {
+  process.stdout.write(event.content);
+}
+```
+
+### Issue: Missing environment variables
+**Solution:** Check .env file or export variables
+```bash
+export KOB_API_KEY=xxx
+export KOB_API_KEY=xxx
+```
+
+## Future Enhancements
+
+### Potential Features
+
+1. **Conversation Export**
+   - Export chat history to file
+   - Multiple formats (JSON, Markdown, TXT)
+
+2. **Batch Operations**
+   - Process multiple messages from file
+   - Bulk project/rule management
+
+3. **Configuration File**
+   - Save default provider/model preferences
+   - Multiple profile support
+
+4. **Plugin System**
+   - Custom command plugins
+   - Third-party integrations
+
+5. **Advanced Formatting**
+   - Markdown rendering in terminal
+   - Syntax highlighting for code
+
+6. **Caching**
+   - Cache model list
+   - Cache frequently accessed data
+
+## Dependencies
+
+### Production
+- `commander` - CLI framework
+- `chalk` - Terminal styling
+- `ora` - Loading spinners
+
+### Development
+- `@types/bun` - Bun type definitions
+- `typescript` - TypeScript compiler
+
+## Build & Deployment
+
+### Development
+```bash
+bun dev <command>
+```
+
+### Production Build
+```bash
+bun run build
+# Creates kob-cli.exe
+```
+
+### Global Installation
+```bash
+bun install -g .
+# or
+bun link
+```
+
+## Reference
+
+- **API Documentation**: See `/my-app/docs/` directory
+- **Type Definitions**: `src/types/index.ts`
+- **API Client**: `src/utils/api.ts`
+- **Commands**: `src/commands/*.ts`

package/INSTALL.md

@@ -0,0 +1,84 @@
+# 🎯 Installation Guide
+
+## ติดตั้ง KOB CLI เพื่อใช้คำสั่ง `kob`
+
+### ขั้นตอนที่ 1: ติดตั้ง Dependencies
+
+```bash
+cd kob-cli
+bun install
+```
+
+### ขั้นตอนที่ 2: ลงทะเบียนคำสั่ง `kob`
+
+```bash
+bun link
+```
+
+คำสั่งนี้จะสร้าง symlink ให้คุณสามารถใช้ `kob` ได้จากทุกที่!
+
+### ขั้นตอนที่ 3: ตั้งค่า API Credentials
+
+สร้างไฟล์ `.env` ในโฟลเดอร์ `kob-cli`:
+
+```env
+KOB_API_BASE_URL=https://www.kob-ai.dev
+KOB_API_KEY=kob_YOUR_API_KEY
+```
+
+**วิธีรับ API Key:**
+1. เข้า https://www.kob-ai.dev
+2. ไปที่ "Token Keys"
+3. สร้าง Key ใหม่
+4. คัดลอก `api_key` มาใส่ใน `.env`
+
+### ขั้นตอนที่ 4: ทดสอบ
+
+```bash
+kob --version
+# ควรแสดง: 1.0.0
+
+kob auth:verify
+# ควรแสดงข้อมูลผู้ใช้ของคุณ
+```
+
+## ✅ พร้อมใช้งาน!
+
+ตอนนี้คุณสามารถใช้คำสั่ง `kob` แทน `bun run src/index.ts` ได้แล้ว
+
+**ตัวอย่าง:**
+```bash
+# แทนที่จะพิมพ์:
+bun run src/index.ts chat "Hello"
+
+# พิมพ์แค่:
+kob chat "Hello"
+```
+
+## 📝 หมายเหตุ
+
+- คำสั่ง `bun link` ต้องรันเพียงครั้งเดียว
+- หากอัปเดตโค้ด ไม่ต้อง link ใหม่
+- หากต้องการลบการ link: `bun unlink kob-cli`
+
+## ❓ ปัญหาที่พบบ่อย
+
+### "kob: command not found"
+
+**วิธีแก้:**
+```bash
+cd kob-cli
+bun link
+```
+
+### Permission denied (Linux/Mac)
+
+```bash
+chmod +x src/index.ts
+```
+
+### Windows PowerShell Execution Policy
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```

package/LICENSE

@@ -0,0 +1,34 @@
+KOB AI CLI - Non-Commercial Open Source License
+
+Copyright (c) 2025 KOB AI Project Owner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, subject to the following conditions:
+
+1. **Non-Commercial Use Only**
+   The Software may only be used for non-commercial purposes. Commercial use,
+   including but not limited to using the Software as part of a commercial
+   product or service, selling the Software, or using the Software for
+   commercial gain, is strictly prohibited without prior written permission
+   from the copyright holder.
+
+2. **Attribution**
+   Any use of the Software must retain the above copyright notice, this list
+   of conditions, and the following disclaimer.
+
+3. **Open Contribution**
+   Contributions to the Software are welcome and encouraged. By contributing,
+   you agree that your contributions will be licensed under the same terms.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For commercial licensing inquiries, please contact the project owner.