Add Claude

CLAUDE.md

@@ -0,0 +1,163 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**kvs-sh** is an interactive CLI shell for the KVS (Key-Value Store) distributed database. Think `mongosh`, `psql`, or `redis-cli` but for KVS. Single Go file implementation (~600 lines) with readline support for command history and auto-completion.
+
+## KVS Server Reference
+
+The complete KVS server source code is located at `../kvs/` relative to this repository. Reference it when:
+- Understanding API contracts and response formats
+- Verifying authentication/authorization behavior
+- Checking endpoint paths and HTTP methods
+- Understanding data structures (StoredValue, Member, User, Group types)
+- Implementing new shell commands for backend features
+
+Key server locations:
+- `../kvs/server/handlers.go` - All API endpoint implementations
+- `../kvs/server/routes.go` - Route definitions and HTTP methods
+- `../kvs/types/types.go` - Canonical type definitions (StoredValue, etc.)
+- `../kvs/auth/` - JWT authentication and permission system details
+- `../kvs/README.md` - Complete API documentation with curl examples
+- `../kvs/CLAUDE.md` - Server architecture and development guidance
+
+When adding new commands to kvs-sh, always verify the actual backend implementation in `../kvs/` rather than making assumptions about API behavior.
+
+## Build & Run
+
+```bash
+# Build
+go build -o kvs-shell
+
+# Run
+./kvs-shell
+
+# Install to system
+go install
+```
+
+## Quick Start with Server
+
+```bash
+# 1. Start KVS server (in ../kvs/)
+cd ../kvs && ./kvs config.yaml
+
+# 2. Load root token (if database is fresh)
+source .root-token
+
+# 3. Run shell
+./kvs-shell
+
+# 4. In shell:
+# connect http://localhost:8080
+# auth $KVS_ROOT_TOKEN
+# put test/data '{"hello":"world"}'
+```
+
+**Important:** If auth fails with "token not found", the database has old data. Either:
+- Create a new token via the API, or
+- Wipe database: `rm -rf ../kvs/data && mkdir ../kvs/data` (restart server to generate root token)
+
+## Testing
+
+```bash
+go test ./...
+```
+
+## Architecture
+
+### Single-File Design
+Everything lives in `main.go` - intentionally kept simple. The shell is a stateful REPL that maintains:
+- HTTP client connection to KVS backend
+- Current JWT auth token
+- In-memory profile storage (username, token, server URL combinations)
+- Active profile selection
+
+### Core Components
+
+**KVSClient (main.go:49)**: Central state container holding:
+- `baseURL`: KVS server endpoint
+- `currentToken`: JWT for authentication
+- `profiles`: In-memory map of saved user profiles (NOT persisted to disk yet)
+- `httpClient`: Reusable HTTP client with 30s timeout
+
+**Command Router (main.go:465)**: Main loop uses switch statement on first word of input, delegates to `handle*` methods
+
+**Command Parser (main.go:527)**: Custom parser respecting quotes - critical for JSON arguments like `put key '{"foo": "bar"}'`
+
+**Auto-completion (main.go:503)**: Prefix tree using readline library for tab completion of commands
+
+### HTTP Communication Pattern
+All API calls go through `doRequest()` (main.go:85) which:
+1. Serializes body to JSON if present
+2. Sets `Authorization: Bearer <token>` header if token exists
+3. Returns `(body, statusCode, error)` tuple
+4. Delegates HTTP status interpretation to caller
+
+### Key Backend API Mappings
+- `GET /kv/<key>` → Returns `StoredValue` with UUID, timestamp, data
+- `PUT /kv/<key>` → Accepts raw JSON, returns UUID + timestamp
+- `DELETE /kv/<key>` → Returns 204 on success
+- `GET /members/` → Returns array of cluster `Member` objects
+- `GET /api/users/<uuid>` → Returns `User` object
+- `GET /health` → Returns service status map
+
+### Type Definitions (main.go:18-46)
+Backend response structures are mirrored in the client:
+- `StoredValue`: The core KV response with UUID, timestamp (int64 unix millis), and `json.RawMessage` data
+- `Member`: Cluster member info with ID, address, last_seen timestamp
+- `User`: User record with nickname hash, groups array, created/updated timestamps
+- `Group`: Group definition (defined but not yet used in commands)
+
+### Profile System
+Profiles are in-memory only (see roadmap for persistence plan). When you `profile use <name>`, it swaps the client's token, userUUID, and baseURL atomically. The `*` marker in profile listings indicates active profile.
+
+### Color Scheme
+Uses fatih/color package with semantic coloring:
+- Cyan: labels, headers, structured data keys
+- Green: success messages, confirmations
+- Yellow: warnings, "not found" states
+- Red: errors, invalid usage
+- Magenta: banner/title text
+
+### Command Parsing - Critical Implementation Details
+
+**parseCommand()** (main.go:527-570): Handles both single (`'`) and double (`"`) quotes intelligently.
+
+**Key behavior:**
+- Quotes are **only stripped** when they delimit an entire argument (start and end)
+- Supports both `'` and `"` as quote delimiters
+- Tracks which quote type started the argument to handle nesting correctly
+- Preserves quotes that appear mid-argument (for unquoted JSON)
+
+**Examples:**
+```bash
+put key '{"foo":"bar"}'       # ✅ Strips outer ', preserves inner "
+put key {"foo":"bar"}         # ✅ Works (no spaces, compact JSON)
+put key {"foo": "bar"}        # ❌ Fails - spaces split into multiple args
+put key "{\"foo\":\"bar\"}"   # ✅ Works (escaped quotes in double-quoted arg)
+```
+
+**JSON Error Handling** (main.go:393-425):
+- `printJSONError()` provides user-friendly error messages with examples
+- Detects error type (invalid chars, incomplete JSON, etc.) and shows context-specific tips
+- Shows what input was received to help debug quoting issues
+
+## Backend Assumptions
+
+The shell expects the KVS backend to:
+1. Accept JWT tokens in `Authorization: Bearer <token>` header
+2. Return timestamps as Unix milliseconds (int64)
+3. Use standard REST semantics (404 for not found, 204 for delete, 200/201 for success)
+4. Accept raw JSON payloads for PUT operations (not wrapped in metadata)
+
+## Known Limitations & Roadmap Items
+
+1. **No persistent profiles** - restart loses all `profile add` data (roadmap #1)
+2. **No metadata commands** - backend supports owner/group/permissions but shell doesn't expose yet (roadmap #6)
+3. **No group management** - `Group` type defined but no CRUD operations (roadmap #5)
+4. **No TLS support** - HTTP only, no certificate handling (roadmap #8)
+5. **No tab completion for keys** - only completes command names, not dynamic keys from server (roadmap #10)
+6. **user create not implemented** - Listed in help but just shows "not implemented" message