@lwelliott/cortex-spm

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

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 for project metadata management and auditing.

Quick Start

# 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
• Configuration — agent command presets, session label, working directory, test connection
• Chat History — per-agent + per-project history with dual-source persistence

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 — required for project metadata management and database auditing. Install it alongside cortex-spm for full functionality.

Testing

The project includes 2006 automated tests across 101 test files, all passing:

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

Changelog

See CHANGELOG.md for release history.

License

MIT — see LICENSE for details.