# CLAUDE.md

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

## Overview

SOS (Simple Object Storage) is a Bash script client for uploading files to a simple object storage server. The repository contains the main `sos` script for uploading files, along with testing and publishing infrastructure.

## Key Commands

### Testing
```bash
./test.sh  # Run comprehensive test suite with Docker container
```

### Publishing
```bash
./publish.sh  # Publish sos tool to getpkg.xyz and getbin.xyz
```

### Direct Usage
```bash
./sos upload <server> <file> <label:tag> [label:tag ...]
# Example: ./sos upload getbin.xyz ./file.txt file:latest version:1.0
```

## Architecture

### Core Components

1. **sos** - Main bash script (233 lines)
   - Handles file uploads to object storage servers
   - Supports deduplication via SHA-256 hashing
   - Manages authentication via SOS_WRITE_TOKEN environment variable
   - Falls back to getpkg for hash calculation if sha256sum/shasum unavailable

2. **test.sh** - Comprehensive test suite
   - Sets up Docker-based test environment
   - Tests upload, retrieval, deduplication, metadata updates
   - Validates authentication and error handling
   - Automatically cleans up test resources

3. **publish.sh** - Release automation
   - Publishes to getpkg.xyz (package registry)
   - Uploads to getbin.xyz using sos itself
   - Injects version timestamps during build

### Key Technical Details

- **Authentication**: Uses Bearer token authentication stored in `SOS_WRITE_TOKEN` or `~/.config/sos/write_token.txt`
- **Deduplication**: Calculates SHA-256 hash locally before upload to check if file already exists
- **Label System**: Files are tagged with `label:tag` format for versioning and organization
- **Test Mode**: Set `SOS_TEST_MODE=1` to use HTTP instead of HTTPS for local testing
- **Dependencies**: Requires curl, jq for JSON parsing; optionally uses sha256sum/shasum or falls back to getpkg

### Server Endpoints Used
- `/exists/<hash>` - Check if file already exists
- `/upload` - Upload new file with metadata
- `/update` - Update metadata for existing file
- `/hash/<label:tag>` - Get hash for a labeled file
- `/meta/<hash>` - Get metadata for a file by hash
- `/<label:tag>` or `/<hash>` - Download file

## Development Notes

- The script uses strict error handling (`set -euo pipefail`)
- Temporary directories are automatically cleaned up on exit
- Version placeholders are replaced during publishing
- Tests require Docker for running the SOS server container