# @lwelliott/cortex-spm — v1.10.28

**CLI-driven software project manager** — run a daemon, manage projects through a React dashboard, and chat with AI agents — all from one binary.

[![npm version](https://img.shields.io/npm/v/@lwelliott/cortex-spm)](https://www.npmjs.com/package/@lwelliott/cortex-spm)
[![License](https://img.shields.io/npm/l/@lwelliott/cortex-spm)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](package.json)
[![Tests](https://img.shields.io/badge/tests-2122%20passing-brightgreen)](https://github.com/lwelliot/cortex-spm/actions)
![GitHub last commit](https://img.shields.io/github/last-commit/lwelliot/cortex-spm)

> **Latest release:** [v1.10.28](CHANGELOG.md) — the session store is now per-project and per-connection (never anchored at the daemon's cwd), so sessions restore and resume after a daemon restart from any directory; a first message sent immediately after connect no longer gets dropped; and the e2e suite no longer touches real project state

---

## Overview

Cortex-SPM is a service management and project dashboard tool. It runs as a background daemon, exposes a REST + WebSocket API, and serves a React-based frontend for managing software projects, tasks, reviews, test reports, and documents.

It depends on **[cortex-cli](https://github.com/lwelliot/cortex-cli)** for project metadata management and auditing.

## Quick Start

```bash
# Install globally
npm install -g @lwelliot/cortex-spm

# Build and start the daemon
cortex-spm start

# Open the dashboard
open http://localhost:16888
```

## Features

### CLI Daemon
- **Lifecycle management** — `start`, `stop`, `restart`, `status` commands with PID-based process control
- **Token authentication** — generate, list, and revoke API tokens
- **i18n** — full English and Chinese localization for all CLI messages
- **Single-binary build** — esbuild bundles the entire application into one file with embedded web assets

### Dashboard
- **Project Dashboard** — system status cards, recent activity feed, WebSocket live updates
- **Kanban Board** — 5-column status-based task management with detail panel
- **Task List** — sortable/filterable table with status, owner, priority columns
- **Review Reports** — card grid with verdict badges and findings detail view
- **Test Reports** — card grid with pass/fail badges and test case results
- **Documents View** — type-filtered document browser, sortable table, detail modal with markdown rendering
- **Document Relation Graph** — SVG visualization of document relationships with color-coded hierarchy
- **SRC Source Code Display** — load source files from the filesystem with syntax highlighting
- **Theme Switching** — light/dark themes via CSS custom properties, persisted to localStorage
- **i18n** — English/Chinese with locale-aware date/number formatting
- **Project Switcher** — create, switch, and remove projects with context propagation

### AI Chat
- **ACP Bridge Provider** — WebSocket-based chat via backend ACP proxy
- **Chat UI** — streaming rendering, connection status, keyboard shortcuts, error retry
- **Attachment upload** — user-selected files upload to the backend (`pmp/sessions/{session_id}/`) with animated progress, then reach the agent as local file paths in the prompt
- **Session management** — session catalog with drawer switching, backend-persisted active session (`claude-sessions.json`), backend-first per-session history reload
- **Agent command from settings (global)** — `agentCommand`/`selectedProvider` configured on the Settings page persist to the global `~/.cortex-spm/settings.json` store and are applied to every agent spawn (both Claude Code and ACP proxies); save failures are surfaced
- **Configuration** — global agent command, provider selection, token expiry, test connection
- **Chat History** — per-session history with backend persistence (`messages.json`) + local restore; re-entry reloads the transcript via native Claude session resume
- **Multi-message turns** — every agent message of a long-running task renders as its own live bubble; transcript stays complete across navigation and session switches

### API
- **REST API** — CRUD for documents, tasks, reviews, test reports, and graph queries
- **WebSocket API** — real-time events with heartbeat, reconnection, and message routing
- **Event Broadcasting** — server-sent events for live UI updates

## Architecture

Cortex-SPM is a single-file binary (esbuild bundle with embedded web assets). No external runtime dependencies beyond Node.js 18+.

```
cortex-spm/
├── src/
│   ├── bin/            CLI entry point
│   ├── lib/
│   │   ├── cli/        Parser, lifecycle, token commands
│   │   ├── config.js   Configuration defaults
│   │   ├── daemon/     PID file, daemon process
│   │   ├── auth/       Token store
│   │   ├── logging/    Structured logger
│   │   └── server/     HTTP + WebSocket servers
│   └── frontend/       React SPA + chat components
├── dist/               Build output
├── locales/            i18n translation files
├── prototype/          UI mockups and screenshots
├── pmp/                Project management database
├── releases/           Release notes
└── tests/              Automated test suites
```

## Dependencies

- **[cortex-cli](https://github.com/lwelliot/cortex-cli)** — required for project metadata management and database auditing. Install it alongside cortex-spm for full functionality.

## Testing

The project includes 2400+ automated tests across all suites, all passing:

```bash
npm test
```

Test categories:
- CLI and lifecycle tests
- HTTP API and WebSocket tests
- Frontend component and integration tests
- ACP proxy and bridge provider tests
- i18n and localization tests
- Build and fixture tests

### Integration / E2E Tests

The Chat UI E2E suite is a pytest + pytest-playwright suite at `tests/e2e/` (real-only, fail-not-skip). The canonical runner is `scripts/run_e2e.py` (test-exec skill).

```bash
# Run E2E tests (real daemon + browser)
npm run test:e2e

# Run E2E tests with a headed browser
npm run test:e2e:headed

# Run E2E tests with Playwright debugging (PWDEBUG)
npm run test:e2e:debug
```

### Real Mode Testing (single-mode real, Task 0003)

All E2E tests run in real mode against a live daemon and a real, authenticated Claude CLI. There is no `TEST_ENV`, no mock gateway, and no environment-gated skip path: when a real-environment prerequisite is unavailable, the affected E2E tests FAIL with a clear reason (fail-not-skip policy). Mock-gateway behavior remains available only for non-E2E integration coverage (boundary mocks at `tests/integration/harness/fixtures/`).

**Prerequisites:**

1. **Claude CLI installed and authenticated:**
   ```bash
   npm install -g @anthropic-ai/claude-code
   claude login
   ```

2. **Built binary at `dist/cortex-spm`:**
   ```bash
   npm run build
   ```

3. **Ports available:** The daemon uses port `16889` (override with `TEST_DAEMON_PORT`).

**Running E2E / real-mode tests:**

```bash
# Playwright browser E2E (tests/e2e/, real daemon + real Claude CLI)
npm run test:e2e

# Real-mode proxy/harness E2E (tests/integration/real-mode/, vitest-based)
npx vitest run tests/integration/real-mode/

# Run pre-flight checks standalone (validate prerequisites)
npx tsx tests/integration/harness/preflight-checks.ts

# Run individual real-mode test suites
npx vitest run tests/integration/real-mode/preflight-checks.test.ts
npx vitest run tests/integration/real-mode/subprocess-cleanup.test.ts
npx vitest run tests/integration/real-mode/playwright-adaptation.test.ts
```

**Environment variables:**

| Variable | Default | Description |
|----------|---------|-------------|
| `TEST_DAEMON_PORT` | `16889` | Daemon port for test session |
| `CLAUDE_CLI_PATH` | `claude` (from PATH) | Path to Claude CLI binary |
| `TEST_BUILD_AUTO` | `0` | Set to `1` to auto-build binary before tests |
| `TEST_WORKERS` | `1` | Number of Playwright workers in real mode |

**Real mode notes (Task 0003):**
- E2E defaults to 1 worker to prevent concurrent Claude CLI spawns.
- Tests take longer due to Claude CLI spawn latency (3-7s on Windows, up to 30s first message).
- An unavailable real environment (missing built binary, missing/unauthenticated Claude CLI, port in use) FAILS the affected E2E tests with a clear reason via the pre-flight gate — never skipped, never blocked. CI must provision the real stack (built binary + authenticated Claude CLI) or accept the failures as the E2E gate.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## License

MIT — see [LICENSE](LICENSE) for details.