Skip to content

CLAUDE.md

Latest commit

 

History

History
173 lines (143 loc) · 6.55 KB

CLAUDE.md

File metadata and controls

173 lines (143 loc) · 6.55 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Procman is a comprehensive process manager with web interface, real-time monitoring, and user management capabilities. It provides daemon/service functionality with HTTP API, WebSocket support, and a React-based frontend for managing processes.

Build Commands

Basic Build

# Build for current platform
go build -o procman ./cmd/procman

# Build with version info (use build.sh for full build)
./build.sh

Cross-Platform Builds

# Linux
GOOS=linux GOARCH=amd64 go build -o procman-linux ./cmd/procman

# Windows
GOOS=windows GOARCH=amd64 go build -o procman.exe ./cmd/procman

# macOS
GOOS=darwin GOARCH=amd64 go build -o procman-macos ./cmd/procman

Testing

# Run comprehensive tests
./test.sh

# Run specific test scripts
./test-e2e.sh          # End-to-end tests
./test-daemon-simple.sh # Daemon functionality tests
./test-concurrency.sh   # Concurrency tests
./test-performance.sh   # Performance tests

# Manual testing
./procman --help
./procman run  # foreground mode for debugging

Architecture

Current Implementation

The implementation provides a full-featured process management system:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI (main)    │───▶│    Daemon       │───▶│   HTTP Server   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Process Manager │    │  Auth System    │    │ WebSocket Hub   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                       │
                              ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │ Log Management  │    │ Terminal Mgmt   │
                       └─────────────────┘    └─────────────────┘

Package Structure

  • cmd/procman/ - CLI entry point with command parsing and HTTP client functionality
  • pkg/config/ - Configuration management (CLI flags, env vars, JSON config)
  • pkg/daemon/ - Cross-platform daemon implementation with process management
  • pkg/server/ - HTTP server using Gin with authentication middleware
  • pkg/process/ - Process lifecycle management and monitoring
  • pkg/procfile/ - Procfile parsing and validation
  • pkg/auth/ - JWT-based authentication with file-based user storage
  • pkg/websocket/ - WebSocket hub for real-time communication
  • pkg/terminal/ - Web-based terminal session management
  • pkg/logstream/ - Real-time log streaming and filtering
  • pkg/events/ - Event bus for component communication
  • pkg/storage/ - File-based storage mechanisms
  • web/ - React-based frontend application

Configuration Hierarchy

Configuration is applied in this order (later overrides earlier):

  1. Default values
  2. JSON config file (~/.procman/config.json)
  3. Environment variables (PROCMAN_*)
  4. Command line flags

Key Features

Daemon Commands

  • start - Start as daemon/background service
  • stop - Stop running daemon
  • status - Check daemon status
  • restart - Restart daemon
  • run - Run in foreground (for debugging)

Process Management

  • up - Start all processes or specific processes
  • down - Stop all processes or specific processes
  • ps - List all processes and their status
  • logs - Show logs for processes with filtering options

HTTP API Endpoints

  • GET /health - Health check
  • POST /auth/login - User authentication
  • GET /api/v1/processes - List all processes
  • POST /api/v1/processes/:id/start - Start a process
  • POST /api/v1/processes/:id/stop - Stop a process
  • GET /api/v1/processes/:id/logs - Get process logs
  • GET /api/v1/admin/users - User management (admin only)
  • GET /ws - WebSocket connection
  • GET /terminal/ws - Terminal WebSocket

Authentication & Authorization

  • JWT-based authentication with Bearer tokens
  • Role-based access control (admin, user, viewer)
  • File-based user storage (simple username/password)
  • Admin token for system operations

Cross-Platform Support

  • Linux: Uses fork/exec and PID files
  • Windows: Uses Windows service APIs
  • Signal handling for graceful shutdown
  • Procfile support for process definitions

Development Notes

Go Version Requirements

  • Requires Go 1.23 or later
  • If system Go version is incompatible, use: export GOTOOLCHAIN=go1.23.12
  • Uses modern Go features including generics and structured logging

Frontend Development

The web interface is a React-based SPA located in the web/ directory:

cd web
npm install
npm run dev    # Development server
npm run build  # Production build

Current State

The codebase implements a complete process management system including:

  • Full daemon functionality with process lifecycle management
  • HTTP API with authentication and authorization
  • Real-time log streaming with WebSocket support
  • Web-based terminal access
  • React frontend with real-time updates
  • Comprehensive test suite

Storage Strategy

As specified in the project requirements:

  • User authentication uses simple file storage (one username per line)
  • General storage uses file system or SQLite to avoid external dependencies
  • Configuration and data stored in ~/.procman/ by default

Environment Variables

  • PROCMAN_PORT - HTTP server port (default: 8080)
  • PROCMAN_PID_FILE - PID file path
  • PROCMAN_LOG_FILE - Log file path
  • PROCMAN_DATA_DIR - Data directory path
  • PROCMAN_ADMIN_TOKEN - Admin authentication token

Testing Strategy

The project includes comprehensive E2E testing across multiple stages:

  • Stage 1: Basic daemon functionality
  • Stage 2: Process management operations
  • Stage 3: Log streaming and terminal access
  • Stage 4: Authentication and user management
  • Stage 5: Performance and concurrency testing