@specforge/cli 0.1.0

package/README.md

@@ -0,0 +1,781 @@
+# @specforge/mcp
+
+MCP (Model Context Protocol) server for SpecForge - enables AI agents to interact with your projects, specifications, epics, and tickets.
+
+## Installation
+
+```bash
+npm install -g @specforge/mcp
+```
+
+Or install locally:
+
+```bash
+npm install @specforge/mcp
+```
+
+## Getting Your API Key
+
+1. Log in to the SpecForge webapp
+2. Navigate to **Settings > API Keys**
+3. Click **Create New API Key**
+4. Select the permissions you need (read, write, or both)
+5. Copy the key immediately - it's only shown once!
+
+API keys have the format: `sf_live_xxxxxxxxxxxxxxxxxxxxxx`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SPECFORGE_API_KEY` | Yes | Your API key from the webapp |
+| `SPECFORGE_API_URL` | Yes | The MCP API Gateway URL from your deployment |
+| `SPECFORGE_DEBUG` | No | Set to `true` to enable debug logging |
+
+## AI Client Configuration
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "specforge": {
+      "command": "specforge",
+      "env": {
+        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
+        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "specforge": {
+      "command": "specforge",
+      "env": {
+        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
+        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
+      }
+    }
+  }
+}
+```
+
+Or set environment variables in your shell and run:
+
+```bash
+export SPECFORGE_API_KEY="sf_live_your_api_key_here"
+export SPECFORGE_API_URL="https://your-api-gateway-url.amazonaws.com/prod"
+specforge
+```
+
+### Cursor
+
+Add to your Cursor MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "specforge": {
+      "command": "npx",
+      "args": ["-y", "@specforge/mcp"],
+      "env": {
+        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
+        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot VS Code Extension
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "github.copilot.advanced": {
+    "mcp": {
+      "servers": {
+        "specforge": {
+          "command": "specforge",
+          "env": {
+            "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
+            "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot CLI
+
+Create a config file at `~/.config/gh-copilot/mcp.json`:
+
+```json
+{
+  "servers": {
+    "specforge": {
+      "command": "specforge",
+      "env": {
+        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
+        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
+      }
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+Configure using environment variables:
+
+```bash
+export SPECFORGE_API_KEY="sf_live_your_api_key_here"
+export SPECFORGE_API_URL="https://your-api-gateway-url.amazonaws.com/prod"
+
+# Then configure your Codex CLI to use the MCP server
+codex --mcp-server specforge
+```
+
+### ChatGPT Desktop
+
+Add to ChatGPT Desktop's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "specforge": {
+      "command": "specforge",
+      "env": {
+        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
+        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to Windsurf's settings:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "specforge": {
+        "command": "specforge",
+        "env": {
+          "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
+          "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
+        }
+      }
+    }
+  }
+}
+```
+
+### Generic MCP Client
+
+For any MCP-compatible client, the server uses stdio transport:
+
+```bash
+# Start the server with environment variables
+SPECFORGE_API_KEY="sf_live_xxx" SPECFORGE_API_URL="https://xxx" specforge
+```
+
+The server communicates via JSON-RPC over stdin/stdout.
+
+## Available Tools
+
+The SpecForge MCP server provides the following tool categories:
+
+### Core Operations
+- `list_projects` - List all accessible projects
+- `get_project` - Get project details
+- `list_specifications` - List specifications in a project
+- `get_specification` - Get specification details
+- `list_epics` - List epics in a specification
+- `get_epic` - Get epic details
+- `list_tickets` - List tickets in an epic
+- `get_ticket` - Get ticket details with implementation steps
+
+### Context & AI Tools
+- `get_implementation_context` - Get full context for implementing a ticket
+- `get_next_actionable_tickets` - Get tickets ready to work on
+- `get_blocked_tickets` - Get blocked tickets with reasons
+- `get_critical_path` - Get the critical implementation path
+
+### Workflow & Tracking
+- `start_work_session` - Start working on a ticket
+- `complete_work_session` - Mark work complete with summary
+- `report_progress` - Report progress on a ticket
+
+### Testing Tools
+- `report_test_results` - Report test results for a ticket
+- `get_ticket_test_status` - Get test status
+- `validate_ticket_completion` - Validate completion criteria
+
+### Discovery Tools
+- `discover_work_session` - Report bugs, tech debt, or new requirements
+- `get_pending_discoveries` - Get unresolved discoveries
+- `resolve_discovery` - Mark a discovery as resolved
+
+### Status & Analytics
+- `get_specification_status` - Get specification progress
+- `get_epic_status` - Get epic progress
+- `get_implementation_summary` - Get overall project summary
+- `get_blockers_report` - Get blocking dependencies
+
+### Search Tools
+- `search_tickets` - Search tickets by text
+- `find_tickets_by_file` - Find tickets affecting a file
+- `find_tickets_by_tag` - Find tickets with specific tags
+- `find_related_tickets` - Find related tickets
+
+### Git Integration
+- `link_commit` - Link a commit to a ticket
+- `link_pull_request` - Link a PR to a ticket
+- `get_ticket_commits` - Get commits for a ticket
+- `get_ticket_prs` - Get PRs for a ticket
+
+### Blueprint Management
+- `blueprint` - Manage specification blueprints (diagrams, mockups, ADRs)
+  - Operations: `create`, `get`, `update`, `list`, `delete`, `link`, `unlink`, `get_for_ticket`
+  - Categories: flowchart, architecture, state, sequence, erd, mockup, adr, component, deployment, api
+  - See [Blueprint Documentation](/docs/mcp/tools/blueprint.md)
+
+### Project Sharing
+- `list_project_members` - List all members of a project
+- `invite_to_project` - Invite a user by email
+- `remove_project_member` - Remove a member from project
+- `update_member_role` - Change a member's role (owner, editor, viewer)
+- `list_invitations` - List pending invitations
+- `accept_project_invitation` - Accept an invitation
+- `decline_project_invitation` - Decline an invitation
+- See [Project Sharing Documentation](/docs/mcp/collaboration/)
+
+## CLI Commands
+
+The SpecForge MCP package includes a CLI for project configuration and management.
+
+### Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate with your API key |
+| `init` | Initialize SpecForge in a project |
+| `configure` | Configure output preferences |
+| `doctor` | Diagnose configuration issues |
+| `status` | Show specification status |
+| `projects` | List accessible projects |
+| `specs` | List specifications |
+| `switch` | Switch project/specification context |
+| `tickets` | List tickets |
+| `ticket <id>` | Show ticket details |
+| `next` | Get next actionable ticket |
+| `blocked` | List blocked tickets |
+| `session` | Show session status |
+| `session start` | Start implementation session |
+| `session end` | End current session |
+| `call <tool>` | Directly call an MCP tool |
+| `tools` | List available MCP tools |
+| `test` | Test API connection |
+| `whoami` | Show current user/config |
+| `autopilot run` | Start autonomous implementation |
+| `autopilot status` | Show autopilot session status |
+| `autopilot pause` | Pause active session |
+| `autopilot resume` | Resume paused session |
+| `autopilot abort` | Stop and cleanup session |
+
+### Setup Commands
+
+#### login
+
+```bash
+specforge login [--api-key <key>] [--force]
+```
+
+Authenticate with the SpecForge API.
+
+| Option | Description |
+|--------|-------------|
+| `--api-key <key>` | Provide API key non-interactively (for CI/scripts) |
+| `-f, --force` | Overwrite existing authentication |
+
+Examples:
+```bash
+specforge login                    # Interactive login
+specforge login --api-key sf_live_xxx  # Non-interactive
+specforge login --force            # Re-authenticate
+```
+
+#### init
+
+```bash
+specforge init [--project <id>] [--spec <id>] [--format <format>] [--force]
+```
+
+Initialize SpecForge in the current directory.
+
+| Option | Description |
+|--------|-------------|
+| `--project <id>` | Project ID (non-interactive mode) |
+| `--spec <id>` | Specification ID (non-interactive mode) |
+| `--format <format>` | Output format: json or toon |
+| `-f, --force` | Overwrite existing configuration |
+
+Creates:
+- `.mcp.json` - Claude Code MCP server configuration
+- `.specforge.json` - Project-specific settings
+
+Examples:
+```bash
+specforge init                          # Interactive setup
+specforge init --project proj_abc       # Set project
+specforge init --project proj_abc --spec spec_xyz --format toon
+```
+
+#### configure
+
+```bash
+specforge configure [--format <format>] [--project <id>]
+```
+
+Configure default preferences.
+
+#### doctor
+
+```bash
+specforge doctor [--json]
+```
+
+Diagnose configuration and connection issues.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON for scripting |
+
+Check categories:
+- Configuration - Config files presence
+- Authentication - API key format and validity
+- Connection - API connectivity and response time
+- Project Access - Access to configured project/specification
+
+### Navigation Commands
+
+#### switch
+
+```bash
+specforge switch [--project <id>] [--spec <id>]
+```
+
+Switch between projects or specifications.
+
+#### projects
+
+```bash
+specforge projects [--json] [--toon]
+```
+
+List all accessible projects.
+
+#### specs
+
+```bash
+specforge specs [--project <id>] [--status <status>] [--json]
+```
+
+List specifications for the current or specified project.
+
+### Query Commands
+
+#### status
+
+```bash
+specforge status [--spec <id>] [--json]
+```
+
+Show current specification status with progress metrics.
+
+#### tickets
+
+```bash
+specforge tickets [--epic <id>] [--status <status>] [--limit <n>] [--json]
+```
+
+List tickets for the current specification.
+
+#### ticket
+
+```bash
+specforge ticket <id> [--json] [--context]
+```
+
+Show full details for a specific ticket.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+| `--context` | Include implementation context |
+
+#### next
+
+```bash
+specforge next [--spec <id>] [--count <n>] [--json]
+```
+
+Get the next actionable tickets (dependencies satisfied).
+
+#### blocked
+
+```bash
+specforge blocked [--spec <id>] [--json]
+```
+
+List blocked tickets with blocking reasons.
+
+### Session Commands
+
+#### session
+
+```bash
+specforge session [--json]
+```
+
+Show current implementation session status.
+
+#### session start
+
+```bash
+specforge session start [specId] [--mode <mode>] [--max-tickets <n>] [--stop-on-failure] [--force]
+```
+
+Start a new implementation session.
+
+| Option | Description |
+|--------|-------------|
+| `[specId]` | Target specification (uses current if omitted) |
+| `--mode <mode>` | Session mode: single, autonomous, guided |
+| `--max-tickets <n>` | Maximum tickets to process |
+| `--stop-on-failure` | Stop on first failure |
+| `--force` | End existing session and start new |
+
+#### session end
+
+```bash
+specforge session end [--status <status>] [--summary <text>]
+```
+
+End the current implementation session.
+
+| Option | Description |
+|--------|-------------|
+| `--status <status>` | End status: completed or aborted |
+| `--summary <text>` | Custom session summary |
+
+### Debug Commands
+
+#### call
+
+```bash
+specforge call <tool> [--args <json>] [--format <format>] [--raw]
+```
+
+Directly call an MCP tool with JSON arguments.
+
+Examples:
+```bash
+specforge call list_projects
+specforge call get_ticket --args='{"ticketId":"abc123"}'
+specforge call list_tickets --format toon
+```
+
+#### tools
+
+```bash
+specforge tools [--category <category>] [--search <query>] [--json]
+```
+
+List available MCP tools with optional filtering.
+
+#### test
+
+```bash
+specforge test
+```
+
+Test API connection and authentication. Shows response time and user info.
+
+#### whoami
+
+```bash
+specforge whoami [--json]
+```
+
+Show current user information and configuration settings.
+
+### Autopilot Commands
+
+Autopilot enables autonomous ticket implementation using Claude Code. See [full documentation](/docs/mcp/autopilot/).
+
+#### autopilot run
+
+```bash
+specforge autopilot run [options]
+```
+
+Start autonomous ticket implementation.
+
+| Option | Description |
+|--------|-------------|
+| `-s, --spec <id>` | Specification ID |
+| `-e, --epic <id>` | Only implement tickets from this epic |
+| `-p, --parallel <n>` | Number of parallel workers (1-10) |
+| `-c, --max-cost <usd>` | Maximum cost in USD |
+| `-n, --dry-run` | Show plan without executing |
+| `-w, --watch` | Watch mode with live dashboard |
+| `-r, --resume <id>` | Resume a previous run |
+
+Examples:
+```bash
+specforge autopilot run --dry-run      # Preview
+specforge autopilot run --parallel 2   # Run with 2 workers
+specforge autopilot run --max-cost 10  # Limit to $10
+specforge autopilot run --watch        # Live dashboard
+```
+
+#### autopilot status
+
+```bash
+specforge autopilot status [options]
+```
+
+Show current autopilot session status.
+
+| Option | Description |
+|--------|-------------|
+| `-w, --watch` | Live updates (2s refresh) |
+| `-v, --verbose` | Show detailed dashboard |
+| `--json` | Output as JSON |
+
+#### autopilot pause / resume / abort
+
+```bash
+specforge autopilot pause              # Pause gracefully
+specforge autopilot resume             # Resume latest session
+specforge autopilot abort --force      # Stop and cleanup
+```
+
+### Configuration Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| Global config | `~/.specforge/config.json` | API key, default format |
+| Project config | `.specforge.json` | Project/spec IDs, format override |
+| MCP config | `.mcp.json` | Claude Code integration |
+
+Configuration priority (highest to lowest):
+1. Environment variables
+2. Project config (`.specforge.json`)
+3. Global config (`~/.specforge/config.json`)
+4. Default values
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SPECFORGE_API_KEY` | API key (overrides config) |
+| `SPECFORGE_API_URL` | API endpoint URL |
+| `SPECFORGE_FORMAT` | Output format (json/toon) |
+| `SPECFORGE_DEBUG` | Enable debug mode (true/false) |
+
+### Exit Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| 0 | SUCCESS | Successful execution |
+| 1 | ERROR | General error |
+| 2 | AUTH_ERROR | Authentication failed |
+| 3 | CONFIG_ERROR | Configuration error |
+| 4 | NETWORK_ERROR | Network/API error |
+| 5 | NOT_FOUND | Resource not found |
+| 6 | VALIDATION_ERROR | Input validation error |
+
+### Automation & CI/CD
+
+Non-interactive usage for scripts:
+
+```bash
+# Authenticate via environment or flag
+export SPECFORGE_API_KEY="sf_live_xxx"
+specforge login --api-key $SPECFORGE_API_KEY
+
+# Initialize non-interactively
+specforge init --project $PROJECT_ID --spec $SPEC_ID --format json --force
+
+# Check health (exits 1 on failure)
+specforge doctor --json
+
+# Get tickets as JSON for processing
+specforge tickets --json | jq '.[]'
+
+# Get next actionable ticket ID
+specforge next --json | jq -r '.tickets[0].id'
+```
+
+### Global Options
+
+These options work with any command:
+
+| Option | Description |
+|--------|-------------|
+| `--debug` | Enable debug output |
+| `--no-color` | Disable colored output |
+| `--json` | Output in JSON format |
+| `-v, --version` | Show version |
+| `-h, --help` | Show command help |
+
+## Troubleshooting
+
+### "SPECFORGE_API_KEY environment variable is required"
+
+Make sure you've set the `SPECFORGE_API_KEY` environment variable with your API key from the SpecForge webapp.
+
+```bash
+# Check if it's set
+echo $SPECFORGE_API_KEY
+
+# Set it
+export SPECFORGE_API_KEY="sf_live_your_key_here"
+```
+
+### "Invalid API key format"
+
+API keys must start with `sf_live_`. If your key doesn't match this format, regenerate it in the webapp.
+
+### "SPECFORGE_API_URL environment variable is required"
+
+You need to provide the API Gateway URL from your SpecForge deployment. This is output when you deploy the backend.
+
+### Connection Timeouts
+
+If you're experiencing connection issues:
+
+1. Verify your API URL is correct
+2. Check your network connection
+3. Enable debug mode to see detailed logs:
+
+```bash
+export SPECFORGE_DEBUG=true
+specforge
+```
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+export SPECFORGE_DEBUG=true
+```
+
+This will output detailed logs to stderr, including:
+- Configuration loaded
+- Tool calls received
+- API requests made
+- Response data
+
+### Server Not Starting
+
+1. Ensure Node.js 18+ is installed
+2. Check that the package is installed globally: `npm list -g @specforge/mcp`
+3. Try reinstalling: `npm install -g @specforge/mcp`
+
+### Permission Denied
+
+If you get "permission denied" when running `specforge`:
+
+```bash
+# On macOS/Linux
+chmod +x $(which specforge)
+
+# Or run with node directly
+node $(npm root -g)/@specforge/mcp/dist/index.js
+```
+
+## Development
+
+To contribute to the MCP server:
+
+```bash
+# Clone the repo
+git clone https://github.com/your-org/specforge.git
+cd specforge/mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Link for local testing
+npm link
+
+# Run in development mode
+npm run dev
+```
+
+### Channel-aware build
+
+The CLI ships as two distinct npm packages:
+
+| Channel | Package | Endpoints | Config dir |
+|---------|---------|-----------|------------|
+| `stable` | `@specforge/cli` | `mcp.specforge.tech` (primary) + `mcp.specforge.com.br` (fallback) | `~/.specforge/` |
+| `canary` | `@specforge/canary-cli` | `devmcp.specforge.tech` + `devmcp.specforge.com.br` | `~/.specforge-canary/` |
+
+The build picks the channel from `SPECFORGE_BUILD_CHANNEL` (defaults to
+`stable` when unset). To build a canary tarball locally:
+
+```bash
+SPECFORGE_BUILD_CHANNEL=canary pnpm --filter @specforge/cli build
+```
+
+The CD workflows (`.github/workflows/deploy-{dev,prod}.yml`) set this env
+var on the `publish-cli-{canary,stable}` jobs so the published tarballs
+contain the matching endpoint literals.
+
+### Endpoint resolver and overrides
+
+On first call in a process, the MCP transport probes
+`CHANNEL.endpoint.healthPrimary` (2 s timeout). On a DNS-class failure
+(`ENOTFOUND`, `ENETUNREACH`, TLS handshake, timeout) it falls over to
+`CHANNEL.endpoint.healthFallback`. The selection is cached for 5 minutes
+under `~/${CHANNEL.configDir}/mcp-endpoint-cache.json`. The CLI REST
+client uses the same resolver with `cli-rest-endpoint-cache.json`.
+
+To bypass the resolver (for ops smokes or self-hosting):
+
+```bash
+export SPECFORGE_API_URL=https://your-mcp.example/local
+export SPECFORGE_CLI_REST_URL=https://your-cli.example
+```
+
+Reachable-but-rejecting responses (4xx/5xx, `ECONNRESET` mid-stream) do
+NOT trigger fallover — the backend was reachable, just unhealthy.
+
+## License
+
+MIT