# CLAUDE.md

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

## Project Overview

This repository contains Dropshell Tools - a collection of utilities that support dropshell development. The main tool is `getpkg`, a C++ command-line application that manages tool installation, updates, and publishing for the dropshell ecosystem.

## Repository Structure

- **getpkg**: Package manager for dropshell tools (C++23)
- **sos**: Simple object storage upload utility (Bash)
- **whatsdirty**: Git repository status checker (Bash)
- **dehydrate**: File to C++ code generator (C++)
- **bb64**: Base64 encoder/decoder (C++)
- **gp**: Git push utility (Bash)

## Architecture

### Core Components (getpkg)

- **getpkg**: Main C++ application (`getpkg/src/`)
  - `main.cpp`: CLI interface and command routing
  - `GetbinClient`: Multi-server HTTP client for downloading/uploading tools
  - `PackageMetadata`: Enhanced metadata with server tracking and migration support
  - `ServerManager`: Manages multiple package servers with write tokens
  - `BashrcEditor`: Manages ~/.bashrc_getpkg script modifications
  - `DropshellScriptManager`: Manages tool installation and configuration
  - `MigrationManager`: Handles legacy format migrations
  - `common/`: Shared utilities (archive_tgz, hash, output, temp_directory)

### Key Features

- **Multi-server support**: Fallback logic for package downloads
- **Architecture awareness**: Supports x86_64, aarch64, and universal packages
- **Migration support**: Handles upgrades from legacy single-server format
- **Static linking**: All tools built as static binaries for portability

### Build System

- Uses CMake with C++23 standard
- Docker-based builds with static linking
- Uses external build base image `gitea.jde.nz/public/dropshell-build-base:latest`
- Versioning based on timestamp format YYYY.MMDD.HHMM

## Common Commands

### Build Tools
```bash
# Build all tools (includes install from getbin.xyz)
./buildtestpublish_all.sh

# Build specific tool (getpkg)
cd getpkg && ./build.sh

# Test specific tool
cd getpkg && ./test.sh

# Publish specific tool (requires SOS_WRITE_TOKEN)
cd getpkg && ./publish.sh
```

### Development Workflow
```bash
# Check status of all git repositories
./whatsdirty/whatsdirty.sh

# Build debug version (default in build.sh)
export CMAKE_BUILD_TYPE="Debug"

# Build release version (used in publish.sh)
export CMAKE_BUILD_TYPE="Release"
```

## Tool Functionality

getpkg manages a tool ecosystem by:
- Installing tools to `~/.getpkg/<tool_name>/` with symlinks in `~/.local/bin/getpkg/`
- Managing bash completions and PATH updates via `~/.bashrc_getpkg`
- Storing tool metadata in `~/.config/getpkg/packages/` (JSON format)
- Supporting multi-server package distribution with fallback
- Publishing/downloading tools via object storage servers (default: getpkg.xyz)

## File Locations

- **Tool installations**: `~/.getpkg/<tool_name>/`
- **Executable symlinks**: `~/.local/bin/getpkg/` (added to PATH)
- **Package metadata**: `~/.config/getpkg/packages/<tool_name>.json`
- **Server configuration**: `~/.config/getpkg/servers.json`
- **Bash integration**: `~/.bashrc_getpkg` (sourced by ~/.bashrc)

## Publishing Requirements

Publishing requires the `SOS_WRITE_TOKEN` environment variable for authentication to the object storage system.

## Testing

- Tests create temporary files in `test_temp/` directory
- Docker-based test environment using same build image
- Run `cleanup_test_packages.sh` to remove orphaned test packages from servers

## Important Notes

- All builds use static linking for maximum portability
- Version format is YYYY.MMDD.HHMM (timestamp-based)
- Tools should support `version` and `autocomplete` subcommands
- Architecture-specific builds use suffixes like `:x86_64` or `:aarch64`