@codevector/cli 0.3.2

package/README.md

@@ -0,0 +1,182 @@
+# codevector — CodeVector CLI
+
+Wire your AI coding tools through a corporate gateway in one command. One API key, per-seat attribution, budget + rate limits, secret-scanning, usage reporting — without every developer manually editing config files.
+
+```bash
+npm i -g @codevector/cli   # or: pnpm add -g @codevector/cli
+codevector auth login
+codevector configure
+```
+
+That's the whole onboarding. Pick a tool, pick a scope, done.
+
+---
+
+## Requirements
+
+- **Node.js >= 20**
+
+---
+
+## What it does
+
+- **Signs you in** with a per-seat API key issued by your gateway admin.
+- **Writes the right config file** for each supported coding tool so its model traffic routes through the gateway instead of calling upstream providers directly.
+- **Picks the right scope** (global, project-wide, or per-machine) based on what you want and what the tool supports.
+- **Installs an acceptance-tracking hook** that fires at session end for tools that expose lifecycle events. Feeds the gateway's usage reporting.
+- **Stays out of your way.** Idempotent writes. Deep-merges into existing settings files — won't clobber your theme, your other hooks, your existing env vars.
+
+---
+
+## Supported tools
+
+| Tool                             | Config path (user scope)                 | Scopes                 | Key storage                                                | Hooks wired           |
+| -------------------------------- | ---------------------------------------- | ---------------------- | ---------------------------------------------------------- | --------------------- |
+| **Claude Code**                  | `~/.claude/settings.json`                | user / project / local | literal in JSON (`ANTHROPIC_AUTH_TOKEN`)                   | `Stop` + `SessionEnd` |
+| **opencode** (sst/opencode)      | `~/.config/opencode/opencode.json`       | user / project / local | literal (user + local); env-var reference in project scope | —                     |
+| **qwen-code** (Alibaba Qwen CLI) | `~/.qwen/settings.json` + `~/.qwen/.env` | user / project / local | `.env` file alongside settings (`envKey` reference)        | `Stop` + `SessionEnd` |
+| **codex** (OpenAI codex CLI)     | `~/.codex/config.toml`                   | **user only**          | shell env var (codex does not auto-load `.env`)            | not wired             |
+
+Each writer emits both Anthropic and OpenAI-compatible provider entries where the tool supports both wire formats. codex is OpenAI-only.
+
+---
+
+## Scope model
+
+Three scopes, same names across every supported tool that allows more than one:
+
+| Scope     | Where the file lives                                                                             | Committed to git?               | Recommended for                                           |
+| --------- | ------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------------- |
+| `user`    | your home directory (`~/.claude/…`, `~/.codex/…`, etc.)                                          | no (outside the repo)           | your personal default across every project                |
+| `project` | this repo's config dir (`./.claude/settings.json`, etc.)                                         | **yes** — shared with teammates | base URL only; we never embed the API key here            |
+| `local`   | this repo's local-override file (`./.claude/settings.local.json`, `./opencode.json`, `./.qwen/`) | no — auto-gitignored            | the usual default: per-seat API key stays on your machine |
+
+`local` is the default when you don't pass `--scope`. The CLI adds gitignore entries automatically for tools that don't natively ignore their local file.
+
+**Secret hygiene:** `project` scope will never write your API key to disk. It writes an env-var reference (`{env:CODEVECTOR_GATEWAY_KEY}` or an `envKey` field) and prints a note telling you to export the variable yourself. This is the only safe way to commit a config file.
+
+---
+
+## Commands
+
+```bash
+codevector auth login                         # sign in — prompts for gateway URL + API key
+codevector auth logout                        # delete local credentials; hooks are left in place
+codevector auth whoami                        # print identity the current API key resolves to
+codevector configure                          # interactive: pick tools, pick scope
+codevector configure claude-code --scope local # non-interactive: scriptable for onboarding
+codevector configure --all                    # every supported tool at once
+codevector configure opencode --scope user    # wire up opencode globally
+codevector models list                        # list models you can reach through the gateway
+codevector models list --kind chat            # filter by kind: chat or embedding
+codevector models list --json                 # emit raw JSON for scripting
+codevector models sync                        # refresh model list in an existing opencode.json
+codevector models sync --scope local          # with explicit scope
+codevector models sync --path /path/to/opencode.json  # with explicit path
+codevector usage                              # show your gateway usage (today by default)
+codevector usage --days 7                     # last 7 days
+codevector usage --json                       # emit raw JSON for scripting
+codevector status                             # who am I, where am I pointed, what models can I use
+codevector doctor                             # health checks: creds, network, hook install, settings
+codevector version                            # print CLI version
+codevector init                               # writes .codevector.json (projectName + ticket pattern)
+codevector init --project my-app              # with explicit project name
+codevector init --ticket-pattern "JIRA-\d+"   # with custom ticket extraction regex
+```
+
+Every command supports `--help`. Commands that need input will prompt interactively when flags are missing, but every flag still works for scripting.
+
+### Auth options
+
+```bash
+codevector auth login --gateway-url https://gateway.corp.com       # non-interactive URL
+codevector auth login --api-key "$GATEWAY_KEY"                      # non-interactive key
+codevector auth login --gateway-url https://gateway.corp.com --api-key "$KEY"  # fully scriptable
+```
+
+---
+
+## Typical flows
+
+**First-time onboarding** (what to put in your team wiki):
+
+```bash
+codevector auth login              # paste the gateway URL + API key your admin emailed you
+codevector configure claude-code   # default scope is local — safe per-seat, gitignored
+codevector doctor                  # confirm everything's wired
+```
+
+**Configuring multiple tools in one go:**
+
+```bash
+codevector configure --all --scope local
+```
+
+**CI-friendly, no prompts:**
+
+```bash
+codevector auth login --gateway-url https://gateway.corp.com --api-key "$GATEWAY_KEY"
+codevector configure claude-code --scope user
+```
+
+**Inspecting what got written:**
+
+```bash
+codevector status
+codevector doctor
+```
+
+**Checking your usage:**
+
+```bash
+codevector usage --days 30
+codevector usage --json | jq .totals
+```
+
+**Syncing models for opencode:**
+
+```bash
+codevector models sync --scope local   # refresh model list after admin adds models
+```
+
+---
+
+## Safe config merging
+
+`codevector configure` adds the gateway settings to your existing config files without overwriting what's already there:
+
+- Your theme, custom env vars, and other hooks are left untouched.
+- Running `codevector configure` a second time won't create duplicate entries — it's safe to re-run.
+- If a config file is corrupted or in an unexpected format, we'll let you know instead of overwriting it.
+
+---
+
+## Credentials
+
+Stored at `~/.config/codevector/credentials.json` (chmod `0600`). Contains gateway URL, API key, user ID, email, and a timestamp. `codevector auth logout` deletes this file.
+
+`codevector doctor` warns if the file mode is looser than `0600`.
+
+Override the config root with `CODEVECTOR_CONFIG_DIR`.
+
+---
+
+## Limitations
+
+- **Cursor requires manual setup.** Cursor stores its settings in an internal database, so the CLI can't configure it automatically. Find step-by-step instructions on your gateway dashboard.
+- **codex is user-scope only.** codex (OpenAI's CLI) has no project or local config. `codevector configure codex --scope project` returns a skipped status with a clear message.
+- **codex doesn't auto-load `.env`.** After configuring codex, export `CODEVECTOR_GATEWAY_KEY` in your shell rc yourself. The CLI prints the line to paste.
+
+---
+
+## Config file reference
+
+| Tool              | File                                                      | Format                 |
+| ----------------- | --------------------------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude/settings.json` / `.claude/settings.local.json` | JSON                   |
+| opencode          | `~/.config/opencode/opencode.json` / `./opencode.json`    | JSON (JSONC tolerated) |
+| qwen-code         | `~/.qwen/settings.json` / `.qwen/settings.json`           | JSON                   |
+| qwen-code secrets | `~/.qwen/.env` / `.qwen/.env`                             | dotenv                 |
+| codex             | `~/.codex/config.toml`                                    | TOML                   |
+| codevector credentials   | `~/.config/codevector/credentials.json`                          | JSON (chmod 0600)      |
+| codevector hook script   | `~/.config/codevector/hooks/acceptance.sh`                       | shell                  |

package/bin/codevector.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/hooks/acceptance.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# CodeVector acceptance-telemetry hook.
+# Invoked by Claude Code on Stop / SessionEnd events. Never blocks the user's
+# session — any failure exits 0 silently.
+#
+# Claude Code delivers the hook payload as JSON on stdin:
+#   { "hook_event_name": "Stop" | "SessionEnd", "session_id": "...",
+#     "transcript_path": "...", "cwd": "...", ... }
+# and sets $CLAUDE_PROJECT_DIR to the project root.
+set -u
+
+CREDS="${HOME}/.config/codevector/credentials.json"
+[ -f "$CREDS" ] || exit 0
+
+API_KEY=$(jq -r .apiKey "$CREDS" 2>/dev/null) || exit 0
+GATEWAY_URL=$(jq -r .gatewayUrl "$CREDS" 2>/dev/null) || exit 0
+[ -n "$API_KEY" ] || exit 0
+[ -n "$GATEWAY_URL" ] || exit 0
+
+# Read the Claude Code hook payload from stdin. If stdin is empty or invalid
+# JSON, fall back to event="stop" so we still emit *something*.
+STDIN_PAYLOAD=$(cat 2>/dev/null || true)
+RAW_EVENT=$(printf '%s' "$STDIN_PAYLOAD" | jq -r '.hook_event_name // "Stop"' 2>/dev/null || echo "Stop")
+case "$RAW_EVENT" in
+  SessionEnd|session_end) EVENT="session_end" ;;
+  *) EVENT="stop" ;;
+esac
+
+# Resolve project root: prefer CLAUDE_PROJECT_DIR (set by Claude Code), else the
+# `cwd` field on the stdin payload, else the shell's $PWD.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$PROJECT_DIR" ]; then
+  PROJECT_DIR=$(printf '%s' "$STDIN_PAYLOAD" | jq -r '.cwd // ""' 2>/dev/null || true)
+fi
+[ -n "$PROJECT_DIR" ] || PROJECT_DIR="$PWD"
+
+PROJECT=""
+TICKET=""
+if git -C "$PROJECT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  REMOTE=$(git -C "$PROJECT_DIR" remote get-url origin 2>/dev/null || true)
+  if [ -n "$REMOTE" ]; then
+    PROJECT=$(echo "$REMOTE" | sed -E 's|^.*[/:]([^/]+)(\.git)?$|\1|' | sed -E 's|\.git$||')
+  fi
+  BRANCH=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || true)
+  if [ -n "$BRANCH" ]; then
+    TICKET=$(echo "$BRANCH" | grep -oE '[A-Z]+-[0-9]+' | head -1 || true)
+  fi
+fi
+
+if [ -f "${PROJECT_DIR}/.codevector.json" ]; then
+  OVERRIDE=$(jq -r '.projectName // empty' "${PROJECT_DIR}/.codevector.json" 2>/dev/null || true)
+  if [ -n "$OVERRIDE" ]; then
+    PROJECT="$OVERRIDE"
+  fi
+fi
+
+PAYLOAD=$(jq -n \
+  --arg event "$EVENT" \
+  --arg project "$PROJECT" \
+  --arg ticket "$TICKET" \
+  '{event:$event} + (if $project=="" then {} else {project:$project} end) + (if $ticket=="" then {} else {ticket:$ticket} end)')
+
+curl -sS -m 5 -X POST "${GATEWAY_URL%/}/gateway/telemetry/acceptance" \
+  -H "x-api-key: ${API_KEY}" \
+  -H "content-type: application/json" \
+  --data "$PAYLOAD" \
+  >/dev/null 2>&1 || true
+
+exit 0