96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Dropshell is a system management tool for server operations, written in C++. It provides a command-line interface for managing remote servers and services through Docker containers.
|
|
|
|
## Build Commands
|
|
|
|
The build system uses Docker for consistent, reproducible builds across all environments.
|
|
|
|
### Development Build (Debug)
|
|
```bash
|
|
# From repository root
|
|
./build.sh
|
|
# Or with environment variables
|
|
CMAKE_BUILD_TYPE=Debug INSTALL_LOCAL=true ./build.sh
|
|
```
|
|
This builds a debug version using Docker and optionally installs to ~/.local/bin/dropshell
|
|
|
|
### Production Build (Release)
|
|
```bash
|
|
CMAKE_BUILD_TYPE=Release ./build.sh
|
|
```
|
|
|
|
### Legacy Build Scripts
|
|
The scripts in `source/build_native.sh` and `source/build_production.sh` now call the Docker-based build system.
|
|
|
|
### Build Options
|
|
- `CMAKE_BUILD_TYPE`: Debug or Release (default: Debug)
|
|
- `INSTALL_LOCAL`: true/false - auto-install to ~/.local/bin (default: true)
|
|
- `NO_CACHE`: true/false - disable Docker build cache (default: false)
|
|
|
|
### Running Tests
|
|
```bash
|
|
cd source && ./test.sh
|
|
```
|
|
|
|
### Publishing Release
|
|
```bash
|
|
cd source && ./publish.sh
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
- **Command System**: Commands are registered through CommandRegistry (src/commands/command_registry.hpp). Each command has a handler function and optional autocomplete support. Commands can require config and/or agent installation.
|
|
|
|
- **Service Management**: Services are managed through LocalServiceInfo structures (src/services.hpp). Services are created from templates and installed on remote servers via Docker containers.
|
|
|
|
- **Server Management**: Servers represent remote hosts that run services. Server configuration includes SSH connection details and installed services.
|
|
|
|
- **Template System**: Templates define the structure for services. They are loaded from template sources and used to create new service instances.
|
|
|
|
- **Agent Components**:
|
|
- Local agent (agent-local/): Installed on the developer's machine
|
|
- Remote agent (agent-remote/): Installed on remote servers to manage services
|
|
|
|
### Key Design Patterns
|
|
|
|
- **Singleton Configuration**: Global configuration accessed through gConfig()
|
|
- **Command Registry Pattern**: All commands register themselves with the central registry
|
|
- **Static Binary Distribution**: Uses musl-libc for fully static executables that work across Linux distributions
|
|
|
|
### Important Files
|
|
|
|
- **src/main.cpp**: Entry point, handles command dispatch and validation
|
|
- **src/config.cpp/hpp**: Configuration management
|
|
- **src/services.cpp/hpp**: Service operations and metadata
|
|
- **src/servers.cpp/hpp**: Server management functions
|
|
- **src/templates.cpp/hpp**: Template loading and management
|
|
- **cmake_prebuild.sh**: Generates autogen files before build
|
|
|
|
### Build System
|
|
|
|
- Uses CMake with Ninja generator
|
|
- Fetches dependencies: libassert, cpptrace, nlohmann/json
|
|
- Generates version info from timestamps
|
|
- Creates fully static binaries using musl cross-compilation toolchain
|
|
|
|
## Common Operations
|
|
|
|
### Adding a New Command
|
|
1. Create command implementation in src/commands/
|
|
2. Register with CommandRegistry including handler, help text, and argument requirements
|
|
3. Add autocomplete handler if needed
|
|
|
|
### Modifying Service Behavior
|
|
- Service definitions are in src/services.cpp
|
|
- Remote agent scripts in source/agent-remote/ handle service operations on servers
|
|
|
|
### Working with Templates
|
|
- Templates are loaded from configured sources by TemplateManager
|
|
- Template metadata and files are cached locally |