test: Add 11 and update 3 files

CLAUDE.md

@@ -6,19 +6,35 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 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
+### Core Components (getpkg)
 
 - **getpkg**: Main C++ application (`getpkg/src/`)
   - `main.cpp`: CLI interface and command routing
-  - `ArchiveManager`: Handles .tgz archive creation/extraction
-  - `BashrcEditor`: Manages ~/.bashrc_dropshell_tool script modifications
+  - `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
-  - `GetbinClient`: HTTP client for downloading/uploading tools
+  - `MigrationManager`: Handles legacy format migrations
+  - `common/`: Shared utilities (archive_tgz, hash, output, temp_directory)
 
-- **sos**: Simple object storage utility
-- **whatsdirty**: Git repository status checker
+### 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
 
@@ -59,11 +75,33 @@ export CMAKE_BUILD_TYPE="Release"
 ## Tool Functionality
 
 getpkg manages a tool ecosystem by:
-- Installing tools to `~/.local/bin/getpkg/<tool_name>/`
-- Managing bash completions and aliases via `~/.bashrc_getpkg`
-- Storing tool metadata in `~/.config/getpkg/`
-- Publishing/downloading tools via getbin.xyz object storage
+- 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.
+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`