dropshell/CLAUDE.md

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)

# 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)

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

cd source && ./test.sh

Publishing Release

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