npm package: @pamudji/spechub
Description: This repo is the implementation of the product described in `SPEC.md`.
Latest version: 0.1.0

# SpecHub

This repo is the implementation of the product described in `SPEC.md`.

## What’s here (so far)
- `apps/gateway`: MCP-ish HTTP gateway with in-memory or Appwrite storage
- `scripts/appwrite-bootstrap.js`: creates Appwrite DB + collections used by the gateway
- `scripts/pat-create.js` / `scripts/pat-revoke.js`: manage Personal Access Tokens (PATs)
- `apps/gateway/test/*`: smoke tests (in-memory + real Appwrite)

## Run the gateway locally
```powershell
npm run dev:gateway
```

## MCP server details
- Endpoint: `POST /mcp` (JSON-RPC 2.0)
- Auth:
  - `AUTH_MODE=dev`: requires `Authorization: Bearer <DEV_PAT>` (default `dev-token`)
  - `AUTH_MODE=appwrite`: either `Authorization: Bearer <PAT>` or a dashboard session cookie (`spechub_session`)
- Optional SSE response mode: send `Accept: text/event-stream` (or add `?sse=1`) to get a single-event SSE response (non-streaming JSON-RPC result payload).

Env vars (optional):
- `PORT` (default: `8787`)
- `DEV_PAT` (default: `dev-token`) – bearer token accepted by the gateway
- `DEV_ADMIN_USER_IDS` (default: empty) – comma-separated user IDs that can force-unlock
- `ALLOWED_ORIGINS` (optional) – allowlist for browser Origins (same-origin is allowed automatically; CORS supports credentialed requests for allowed origins)
- Cookie auth (for cross-origin dashboards):
  - `COOKIE_SAMESITE=none` and `COOKIE_SECURE=1` (required if your dashboard is on a different “site”)
  - Optional: `COOKIE_DOMAIN=.example.com` (only works for shared parent domains)

### Quick smoke test
```powershell
$headers = @{
  Authorization = "Bearer dev-token"
  "Content-Type" = "application/json"
}

$body = @{
  jsonrpc = "2.0"
  id = 1
  method = "tools/list"
  params = @{}
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Method Post -Uri http://localhost:8787/mcp -Headers $headers -Body $body
```

## Minimal CLI wrapper (`/sh-*` style)
This repo includes a minimal Node wrapper that can drive the MCP gateway:
```powershell
npm run sh -- init --url http://localhost:8787 --pat dev-token --project demo
npm run sh -- plan mvp "Ship MVP"
npm run sh -- exec 1 --auto-complete
```

## No-clone usage (installable binaries)
If you want to use `/sh-*` style commands in other repos without cloning this repo, install from Git and use the `spechub` binary:
```bash
npm i -g @pamudji/spechub
spechub-gateway   # runs the MCP gateway
spechub install-claude   # writes `.claude/commands/sh-*.md` into the current repo
spechub install-mcp      # writes `.mcp.json` that registers `spechub-mcp` (stdio→HTTP bridge)
```

## Claude Code MCP setup (Option B: tools/resources directly)
Claude Code typically expects MCP servers over **stdio**. SpecHub’s gateway is **HTTP**, so use the included bridge:
- Install the package: `npm i -g @pamudji/spechub`
- In your repo: `spechub install-mcp --url https://<your-gateway>`
  - Defaults to an `npx`-based `.mcp.json` so collaborators don’t need a global install.
  - If you don’t want a PAT checked into the repo, omit `--pat` and set `SPECHUB_PAT` in your environment instead.
- Restart Claude Code so it reloads `.mcp.json`.

## Use a remote Appwrite backend
1) Create `.env` from `.env.example` and set:
- `STORAGE_BACKEND=appwrite`
- `AUTH_MODE=appwrite`
- `APPWRITE_ENDPOINT`, `APPWRITE_PROJECT_ID`, `APPWRITE_API_KEY`, `APPWRITE_DATABASE_ID`
2) (Optional) Usage metering:
- `ENABLE_APPWRITE_USAGE=1` records daily counters + append-only `usage_events` (shadow mode; never blocks core)

3) Bootstrap the Appwrite database + collections:
```powershell
npm run appwrite:bootstrap
```

4) Start the gateway:
```powershell
npm run dev:gateway
```

5) Sign up / log in via the dashboard (session cookie auth):
- Open `http://localhost:8787/dashboard`
- Use the “Signup / Login” section (this sets an HttpOnly `spechub_session` cookie)
- Click “Connect” with an empty PAT field (the dashboard will use the session cookie)

6) Create a PAT (for CLI or cross-site use), or use the dashboard PAT tools:
```powershell
npm run pat:create -- --userId YOUR_USER_ID --accountId YOUR_ACCOUNT_ID --roles owner
```

Notes:
- If you don’t use Appwrite Teams, the gateway treats your “account” as `user:<YOUR_USER_ID>` (this is what `dashboard/auth/whoami` returns in `accountIds`).
- If your dashboard is hosted on a different site/origin, use a PAT (simplest) or configure cookie auth with `COOKIE_SAMESITE=none` + `COOKIE_SECURE=1` and make your `fetch()` calls with `credentials: "include"`.

7) Open the UIs:
- Dev UI: `http://localhost:8787/`
- Dashboard: `http://localhost:8787/dashboard` (docs editor, usage, PAT management)