@devcortex/cli 1.3.0 → 1.3.3

package/README.md

@@ -0,0 +1,400 @@
+# `dcx` — DevCortex CLI
+
+> **Version:** 1.3.0  
+> **Package:** [`@devcortex/cli`](https://www.npmjs.com/package/@devcortex/cli)  
+> **Platform:** [devcortexai.com](https://www.devcortexai.com)
+
+The `dcx` CLI connects AI coding agents (Claude Code, OpenCode) to your [DevCortex](https://www.devcortexai.com) project. It handles authentication, project linking, `CLAUDE.md` generation, and live supervision — replacing manual curl workflows with two commands.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Without dcx                  With dcx              │
+│  ───────────────────          ──────────────────    │
+│  1. Login via curl            dcx login             │
+│  2. Fetch project ID                                │
+│  3. Generate API key          dcx start             │
+│  4. Write .mcp.json                                 │
+│  5. Download CLAUDE.md                              │
+│  6. Start claude                                    │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+npm install -g @devcortex/cli
+```
+
+Requires **Node.js 18 or higher**.
+
+> **Permission error?** If you see `EACCES: permission denied`, either:
+>
+> **Option 1 — use sudo (simplest):**
+> ```bash
+> sudo npm install -g @devcortex/cli
+> ```
+>
+> **Option 2 — use pnpm (recommended):**
+> ```bash
+> npm install -g pnpm
+> pnpm install -g @devcortex/cli
+> ```
+>
+> **Option 3 — configure npm user directory:**
+> ```bash
+> mkdir -p ~/.npm-global
+> npm config set prefix '~/.npm-global'
+> echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+> source ~/.bashrc
+> npm install -g @devcortex/cli
+> ```
+> Note: on some Linux systems the npm global symlink may not execute correctly.
+> If `dcx` produces no output after install, use pnpm or sudo instead.
+>
+> See [npm docs on fixing permissions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) for more options.
+
+Verify:
+
+```bash
+dcx --version
+dcx --help
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+dcx login
+
+# 2. Link your project directory to DevCortex
+cd ~/my-project
+dcx init
+
+# 3. Launch your AI agent with CLAUDE.md refreshed
+dcx start
+```
+
+`dcx start` fetches the latest requirements and issues from DevCortex, writes them to `CLAUDE.md`, and launches Claude Code (or OpenCode) — so your agent always starts with the current project context.
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `dcx login` | Authenticate and store token locally |
+| `dcx init` | Link current directory to a DevCortex project |
+| `dcx start` | Refresh `CLAUDE.md` and launch AI agent |
+| `dcx update` | Refresh `CLAUDE.md` without launching agent |
+| `dcx status` | Show project health summary |
+| `dcx logs` | Stream live audit events to terminal |
+| `dcx keys` | Manage project API keys |
+| `dcx list` | Query requirements, backlog, and issues |
+| `dcx export` | Export requirements to CSV |
+| `dcx import` | Import requirements from CSV |
+| `dcx test-mcp` | Self-diagnose MCP connection health |
+| `dcx issue` | Manage issues |
+
+---
+
+### `dcx login`
+
+```bash
+dcx login
+dcx login --email user@example.com --password mypassword
+```
+
+Authenticates with DevCortex and stores your JWT token in `~/.devcortex/config.json`.
+
+---
+
+### `dcx init`
+
+```bash
+dcx init
+dcx init --agent opencode      # generate AGENTS.md instead of CLAUDE.md
+dcx init --project <projectId> # skip project selector
+dcx init --force               # overwrite existing files
+```
+
+Links the current directory to a DevCortex project. Creates:
+
+| File                   |               Purpose                |    Commit?     |
+|------------------------|--------------------------------------|----------------|
+| `.mcp.json`            | MCP API key for agent connection     | ❌ No (secret) |
+| `CLAUDE.md`            | Agent constitution with requirements | ✅ Yes         |
+| `.devcortex-link.json` | Project link (no secrets)            | ✅ Yes         |
+
+`.mcp.json` is automatically added to `.gitignore`.
+
+---
+
+### `dcx start`
+
+```bash
+dcx start
+dcx start --agent claude
+dcx start --agent opencode
+dcx start --no-init    # skip CLAUDE.md refresh, launch immediately
+```
+
+Refreshes `CLAUDE.md` from the live database and launches your AI agent. Auto-detects Claude Code or OpenCode on your PATH.
+
+**Install Claude Code:**
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+**Install OpenCode:**
+```bash
+npm install -g opencode-ai
+```
+
+---
+
+### `dcx update`
+
+```bash
+dcx update
+dcx update --watch    # keep CLAUDE.md in sync continuously (polls every 60s)
+```
+
+Refreshes `CLAUDE.md` without launching an agent. Use `--watch` in a background terminal when requirements change frequently during a session.
+
+---
+
+### `dcx status`
+
+```bash
+dcx status
+dcx status --json    # machine-readable output
+```
+
+Displays project health: requirements count, open issues, MCP connection status, token validity, and spec version.
+
+---
+
+### `dcx logs`
+
+```bash
+dcx logs
+dcx logs --tail 50
+dcx logs --follow
+```
+
+Streams live audit events from DevCortex — shows what your AI agent is reading and writing in real time.
+
+---
+
+### `dcx keys`
+
+```bash
+dcx keys list                  # list all API keys for the project
+dcx keys regenerate            # rotate the key in .mcp.json
+dcx keys revoke <keyId>        # revoke a specific key
+```
+
+Manages project-scoped API keys used by the MCP server.
+
+---
+
+### `dcx list`
+
+```bash
+dcx list backlog
+dcx list backlog --status APPROVED
+dcx list issues
+dcx list issues --severity HIGH
+```
+
+Queries and displays requirements and issues from DevCortex.
+
+---
+
+### `dcx export`
+
+```bash
+dcx export --csv                        # print CSV to stdout
+dcx export --csv --out requirements.csv # write to file
+```
+
+Exports project requirements as CSV.
+
+---
+
+### `dcx import`
+
+```bash
+dcx import --csv requirements.csv            # import from file
+dcx import --csv requirements.csv --dry-run  # preview only
+```
+
+Imports requirements from CSV. Rows are matched by `reqId` — existing requirements are skipped, new ones are created.
+
+---
+
+### `dcx test-mcp`
+
+```bash
+dcx test-mcp
+```
+
+Self-diagnoses the MCP connection. Runs four checks:
+
+1. API reachable
+2. API key valid
+3. Project accessible
+4. MCP tools available
+
+```
+✔  1. API reachable
+✔  2. API key valid
+✔  3. Project accessible
+✔  4. MCP tools available
+
+✔ MCP connection healthy — 12 tools registered for my-org/My Project
+```
+
+Run this whenever Claude Code reports an MCP connection error.
+
+---
+
+## Typical Workflows
+
+### Start a new project
+
+```bash
+mkdir my-app && cd my-app
+dcx init
+dcx start
+```
+
+### Resume after a break
+
+```bash
+cd my-app
+dcx start    # refreshes CLAUDE.md then launches agent
+```
+
+### Monitor an agent session
+
+```bash
+# Terminal 1 — agent
+dcx start
+
+# Terminal 2 — live supervision
+dcx logs
+```
+
+### Keep CLAUDE.md in sync automatically
+
+```bash
+# Terminal 1 — watch for requirement changes
+dcx update --watch
+
+# Terminal 2 — agent (skip refresh since watch handles it)
+dcx start --no-init
+```
+
+### New team member setup
+
+```bash
+git clone https://github.com/org/my-project
+cd my-project
+dcx login
+dcx init      # generates personal .mcp.json (not committed)
+dcx start
+```
+
+### Diagnose MCP problems
+
+```bash
+dcx test-mcp
+# If key is stale:
+dcx init --force
+dcx test-mcp
+```
+
+---
+
+## Configuration
+
+Config is stored at `~/.devcortex/config.json`:
+
+```json
+{
+  "token": "eyJhbGci...",
+  "tokenExpiry": "2026-06-17T00:00:00.000Z",
+  "apiUrl": "https://api.devcortexai.com",
+  "defaultOrgSlug": "my-org",
+  "defaultProjectId": "cmmxbv3v..."
+}
+```
+
+### Environment Variables
+
+|    Variable    |      Description      |          Default              |
+|----------------|-----------------------|-------------------------------|
+| `DCX_API_URL`  | Override API URL      | `https://api.devcortexai.com` |
+| `DCX_NO_COLOR` | Disable colour output | unset                         |
+
+### Override API URL
+
+```bash
+dcx login --api-url https://staging-api.devcortexai.com
+dcx status --api-url https://staging-api.devcortexai.com
+```
+
+---
+
+## Troubleshooting
+
+**`✗ Not logged in — run dcx login first`**  
+Your token has expired (7-day TTL). Run `dcx login`.
+
+**`✗ No project linked — run dcx init first`**  
+Run `dcx init` in your project directory.
+
+**`✗ API unreachable`**  
+Check your internet connection or verify the API URL with `dcx status`.
+
+**`✗ No AI agent found`**  
+Install Claude Code (`npm install -g @anthropic-ai/claude-code`) or OpenCode (`npm install -g opencode-ai`).
+
+**MCP connection fails in Claude Code**  
+Run `dcx test-mcp` — it pinpoints exactly which of the four connection steps is failing and shows the fix.
+
+**Reset config**  
+```bash
+rm ~/.devcortex/config.json
+dcx login
+dcx init
+```
+
+---
+
+## Files Reference
+
+|        File            |    Location     |         Purpose          | Commit? |
+|------------------------|-----------------|--------------------------|---------|
+| `config.json`          | `~/.devcortex/` | Token + defaults         | ❌ No   |
+| `.mcp.json`            | Project root    | MCP API key              | ❌ No   |
+| `.devcortex-link.json` | Project root    | Project link             | ✅ Yes  |
+| `CLAUDE.md`            | Project root    | Claude Code constitution | ✅ Yes  |
+| `AGENTS.md`            | Project root    | OpenCode constitution    | ✅ Yes  |
+
+---
+
+## Links
+
+- **Platform:** [devcortexai.com](https://www.devcortexai.com)
+- **npm:** [npmjs.com/package/@devcortex/cli](https://www.npmjs.com/package/@devcortex/cli)
+- **Support:** [support@devcortexai.com](mailto:support@devcortexai.com)
+
+---
+
+*DevCortex is built by MainRobin Pty Ltd(https://www.devcortexai.com). © 2026 MainRobin Pty Ltd.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devcortex/cli",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "DevCortex CLI — structured requirements for agentic development",
   "type": "module",
   "bin": {