# getpkg - Package Manager for Dropshell Tools

getpkg is a command-line package manager that simplifies tool installation, management, and publishing for the dropshell ecosystem. Tools are installed to `~/.getpkg/` with executable symlinks in `~/.local/bin/getpkg/` and automatically added to your PATH with bash completion.

## Installation

Install getpkg with a single command:

```bash
curl https://getbin.xyz/getpkg-install | bash
```

After installation, restart your shell or run `source ~/.bashrc` to enable the new PATH and completion settings.

## Basic Usage

### Installing Tools

Install any tool from the getpkg registry:

```bash
# Install a tool
getpkg install ripgrep
```

### Managing Installed Tools

```bash
# List all available commands
getpkg help

# Update all installed tools
getpkg update

# Uninstall a tool
getpkg uninstall ripgrep

# Check getpkg version
getpkg version
```

## Available Commands

### Core Package Management

- **`getpkg install <tool_name>`** - Install or update a tool
- **`getpkg uninstall <tool_name>`** - Remove an installed tool
- **`getpkg update`** - Update getpkg and all installed tools

### Publishing (Requires SOS_WRITE_TOKEN)

- **`getpkg publish <tool_name[:ARCH]> <folder>`** - Upload a tool to getpkg.xyz
- **`getpkg unpublish <tool_name[:ARCH]>`** - Remove a published tool
- **`getpkg unpublish <hash>`** - Remove a published tool by hash

### Development Tools

- **`getpkg create <tool_name> <directory>`** - Create a new tool project
- **`getpkg hash <file_or_directory>`** - Calculate hash of files/directories

### Information

- **`getpkg version`** - Show getpkg version
- **`getpkg help`** - Show detailed help
- **`getpkg autocomplete`** - Show available commands for completion

## How It Works

### Installation Process

When you install a tool, getpkg:

1. **Downloads** the tool archive from getpkg.xyz
2. **Extracts** it to `~/.getpkg/<tool_name>/`
3. **Creates symlinks** for all executables in `~/.local/bin/getpkg/`
4. **Ensures PATH** includes `~/.local/bin/getpkg` (one-time setup)
5. **Enables completion** for the tool
6. **Runs setup** if a `setup_script.sh` exists
7. **Stores metadata** in `~/.config/getpkg/<tool_name>.json`

### Architecture Support

getpkg supports multiple architectures:
- `x86_64` (Intel/AMD 64-bit)
- `aarch64` (ARM 64-bit)  
- `universal` (cross-platform tools)

Tools are automatically downloaded for your architecture, with fallback to universal versions.

### File Locations

- **Tool files**: `~/.getpkg/<tool_name>/` (actual tool installation)
- **Executable symlinks**: `~/.local/bin/getpkg/` (in your PATH)
- **Configuration**: `~/.config/getpkg/`
- **PATH setup**: `~/.bashrc_getpkg` (sourced by `~/.bashrc`)

## Examples

### Installing Popular Tools

```bash
# Install development tools
getpkg ripgrep        # Fast grep alternative
getpkg fd             # Fast find alternative
getpkg bat            # Cat with syntax highlighting

# Install system utilities
getpkg whatsdirty     # Check git repo status
getpkg sos            # Simple object storage client
```

### Publishing Your Own Tools

```bash
# Set your publishing token
export SOS_WRITE_TOKEN="your-token-here"

# Create a new tool project
getpkg create mytool ./mytool-project

# Publish architecture-specific build
getpkg publish mytool:x86_64 ./build/

# Publish universal tool
getpkg publish mytool ./build/

# Remove published tool
getpkg unpublish mytool:x86_64
```

### Development Workflow

```bash
# Create tool structure
getpkg create awesome-tool ./awesome-tool
cd awesome-tool

# Build your tool...
# Add executable to the directory

# Test locally
./awesome-tool --version

# Publish when ready
getpkg publish awesome-tool:x86_64 .
```

## Environment Variables

- **`SOS_WRITE_TOKEN`** - Authentication token for publishing tools

## Troubleshooting

### Tool Not Found
If a tool isn't found after installation, ensure your shell has loaded the new PATH:
```bash
source ~/.bashrc
```

### Permission Issues
getpkg installs to your home directory and doesn't require root access. If you encounter permission issues, check that `~/.local/bin/` is writable.

### Network Issues
All tools are downloaded from `getpkg.xyz`. Ensure you have internet connectivity and the domain is accessible.

## Development

### Building getpkg

```bash
# Build debug version
cd getpkg && ./build.sh

# Run tests  
cd getpkg && ./test.sh

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

### Tool Development

When creating tools for getpkg:

1. Create a directory with your tool binary
2. Optionally include a `setup_script.sh` for post-install setup
3. The tool should support `version` and `autocomplete` subcommands
4. Use `getpkg publish` to upload to the registry

For more details, see the development documentation in each tool's directory.