getpkg/CLAUDE.md

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

# 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

# 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