Add project documentation and ignore rules

Document usage, endpoints, model aliases, build commands, and local-only paths.

Author: dev2k6

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.gitignore

@@ -0,0 +1,21 @@
+# Binaries
+bin/
+
+# Drafts
+.drafts/
+
+# Claude config
+.claude/
+
+# Go build cache
+go.sum
+*.exe
+*.exe~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/

README.md

@@ -0,0 +1,239 @@
+# CommandCode Proxy Server
+
+OpenAI-compatible proxy server for the CommandCode API. It exposes `/v1/chat/completions` and `/v1/models` endpoints so OpenAI-compatible clients can call CommandCode models through a local HTTP server.
+
+Repository: https://github.com/dev2k6/command-code-proxy-server
+
+Version: `v1.0.0`
+
+## Features
+
+- OpenAI-compatible chat completions endpoint
+- Streaming and non-streaming responses
+- OpenAI-compatible model list endpoint
+- Short model name mapping
+- Optional default API key from CLI
+- Per-request API key via `Authorization` header
+- Configurable host and port
+- Checks GitHub tags for a newer proxy version and displays it next to the current version
+
+## Requirements
+
+- Go 1.26.2 or newer
+
+## Run
+
+```bash
+go run main.go
+```
+
+Default server address:
+
+```text
+http://127.0.0.1:55990
+```
+
+## CLI options
+
+```bash
+go run main.go [options]
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `-host` | `127.0.0.1` | Host to bind the server to |
+| `-port` | `55990` | Port to run the server on |
+| `-api-key` | empty | Optional default CommandCode API key |
+| `-version` | `false` | Print version and exit |
+
+Examples:
+
+```bash
+# Run on default host and port
+go run main.go
+
+# Run on a custom port
+go run main.go -port 8080
+
+# Expose on all interfaces
+go run main.go -host 0.0.0.0
+
+# Use a default API key for all requests that do not include Authorization
+go run main.go -api-key your-commandcode-api-key
+
+# Print version
+go run main.go -version
+```
+
+## Build
+
+Build for the current platform:
+
+```bash
+go build -o bin/command-code-proxy
+```
+
+Cross-compile for Windows and Linux:
+
+```bash
+GOOS=windows GOARCH=amd64 go build -o bin/command-code-proxy.exe
+GOOS=linux GOARCH=amd64 go build -o bin/command-code-proxy
+```
+
+## API key behavior
+
+The proxy uses the API key in this order:
+
+1. `Authorization` header from the incoming client request
+2. `-api-key` CLI value
+3. If neither exists, the request returns `401 Unauthorized`
+
+Header format:
+
+```http
+Authorization: Bearer your-commandcode-api-key
+```
+
+## Endpoints
+
+### Health check
+
+```http
+GET /health
+```
+
+Response:
+
+```json
+{"status":"ok"}
+```
+
+### List models
+
+```http
+GET /v1/models
+```
+
+Returns an OpenAI-compatible model list.
+
+### Chat completions
+
+```http
+POST /v1/chat/completions
+```
+
+Example non-streaming request:
+
+```bash
+curl http://127.0.0.1:55990/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-commandcode-api-key" \
+  -d '{
+    "model": "deepseek-v4-pro",
+    "messages": [
+      {"role": "system", "content": "You are helpful."},
+      {"role": "user", "content": "Hello"}
+    ],
+    "stream": false
+  }'
+```
+
+Example streaming request:
+
+```bash
+curl -N http://127.0.0.1:55990/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-commandcode-api-key" \
+  -d '{
+    "model": "deepseek-v4-pro",
+    "messages": [
+      {"role": "user", "content": "Write a short poem."}
+    ],
+    "stream": true
+  }'
+```
+
+## Supported model aliases
+
+The proxy accepts full model IDs and these short aliases:
+
+| Alias | Maps to |
+| --- | --- |
+| `deepseek-v4-pro`, `deepseek-v4`, `deepseek-pro` | `deepseek/deepseek-v4-pro` |
+| `deepseek-v4-flash`, `deepseek-flash` | `deepseek/deepseek-v4-flash` |
+| `minimax-m2.7`, `minimax2.7` | `MiniMaxAI/MiniMax-M2.7` |
+| `minimax-m2.5`, `minimax2.5`, `minimax` | `MiniMaxAI/MiniMax-M2.5` |
+| `glm-5.1` | `zai-org/GLM-5.1` |
+| `glm-5` | `zai-org/GLM-5` |
+| `kimi-k2.6`, `kimi2.6` | `moonshotai/Kimi-K2.6` |
+| `kimi-k2.5`, `kimi2.5` | `moonshotai/Kimi-K2.5` |
+| `qwen-3.6-max-preview`, `qwen3.6-max` | `Qwen/Qwen3.6-Max-Preview` |
+| `qwen-3.6-plus`, `qwen3.6-plus`, `qwen3.6` | `Qwen/Qwen3.6-Plus` |
+| `step-3.5-flash`, `step3.5` | `stepfun/Step-3.5-Flash` |
+| `gemini-3.1-flash-lite`, `gemini-flash-lite` | `google/gemini-3.1-flash-lite` |
+
+Unknown model names are passed through unchanged.
+
+## Project structure
+
+```text
+.
+├── README.md
+├── go.mod
+├── go.sum
+├── main.go
+├── bin
+│   ├── command-code-proxy
+│   └── command-code-proxy.exe
+└── internal
+    ├── api
+    │   ├── commandcode.go
+    │   └── openai.go
+    ├── proxy
+    │   ├── convert.go
+    │   ├── model.go
+    │   └── proxy.go
+    ├── server
+    │   └── server.go
+    ├── update
+    │   └── update.go
+    └── version
+        └── version.go
+```
+
+## How it works
+
+1. Client sends an OpenAI-compatible request to the local proxy.
+2. The proxy extracts system messages, maps the model name, and converts messages to CommandCode format.
+3. The proxy sends the request to `https://api.commandcode.ai/alpha/generate`.
+4. CommandCode streaming NDJSON events are converted back to OpenAI-compatible SSE chunks or collected into a single JSON response.
+
+## Version check
+
+On startup and when running `-version`, the proxy calls:
+
+```text
+https://api.github.com/repos/dev2k6/command-code-proxy-server/tags
+```
+
+If the latest GitHub tag is newer than the current app version, the version line is displayed as:
+
+```text
+v1.0.0 (latest: v1.x.x)
+```
+
+## CommandCode version header
+
+The upstream request includes:
+
+```http
+x-command-code-version: <latest npm command-code version>
+```
+
+The value is fetched from:
+
+```text
+https://registry.npmjs.org/command-code/latest
+```
+
+The fetched version is cached for 30 minutes. If the registry request fails, the proxy uses the last cached version, or `unknown` if no version has been fetched yet.