# Update OpenCode Skill

Automate checking for and applying OpenCode version updates in Nix-based dotfiles.

## Features

- **Check versions**: Compare current OpenCode installation against latest GitHub release
- **Auto-update**: Fetch SHA256 hashes and update Nix package definitions
- **Verify installations**: Confirm successful updates after rebuild
- **Version pinning**: Install specific versions for compatibility

## Installation

### Global Installation (Recommended)

1. Copy this skill to your dotfiles:
```bash
cd ~/proj/skills
./bin/deploy-skill.sh update-opencode
```

2. Follow displayed instructions to update `modules/ai-skills.nix` in your dotfiles

3. Rebuild system:
```bash
cd ~/proj/dotfiles
sudo nixos-rebuild switch --flake .#<hostname>
```

4. Verify installation:
```bash
ls ~/.claude/skills/update-opencode
ls ~/.config/opencode/skills/update-opencode
```

### Project-Local Installation (Alternative)

For use in a specific project only:
```bash
mkdir -p .claude/skills .opencode/skills
cp -r ~/proj/skills/skills/update-opencode .claude/skills/
cp -r ~/proj/skills/skills/update-opencode .opencode/skills/
```

## Prerequisites

**Required tools:**
- `jq` - JSON parsing
- `curl` - HTTP requests
- `nix-prefetch-url` - Binary hash computation
- `sed` - File editing
- `grep` - Pattern matching

**Required access:**
- Read/write to dotfiles repository (`~/proj/dotfiles` by default)
- `sudo` permissions for `nixos-rebuild switch`
- Network access to GitHub API

**Verify prerequisites:**
```bash
command -v jq curl nix-prefetch-url sed grep && echo "✓ All tools available"
```

## Usage

### With AI Agents (Claude Code / OpenCode)

Simply ask the agent:
- "Check for OpenCode updates"
- "Update OpenCode to latest"
- "Install OpenCode version 1.0.44"

The agent will use this skill automatically.

### Manual Usage

**Check current vs latest version:**
```bash
~/.claude/skills/update-opencode/scripts/check-version.sh
```

**Fetch SHA256 for specific version:**
```bash
~/.claude/skills/update-opencode/scripts/fetch-sha256.sh 1.0.51
```

**Update Nix file (dry-run first):**
```bash
~/.claude/skills/update-opencode/scripts/update-nix-file.sh 1.0.51 sha256-ABC... --dry-run
~/.claude/skills/update-opencode/scripts/update-nix-file.sh 1.0.51 sha256-ABC...
```

**Rebuild system:**
```bash
cd ~/proj/dotfiles
sudo nixos-rebuild switch --flake .#<hostname>
```

**Verify installation:**
```bash
~/.claude/skills/update-opencode/scripts/verify-update.sh 1.0.51
```

## Configuration

**Custom dotfiles path:**
```bash
# Set via environment variable
export DOTFILES_PATH=~/my-dotfiles

# Or pass as argument
./check-version.sh --dotfiles ~/my-dotfiles
./update-nix-file.sh 1.0.51 sha256-ABC... --dotfiles ~/my-dotfiles
```

## Troubleshooting

**"Error: Nix file not found"**
- Verify dotfiles path is correct
- Check that `pkgs/opencode/default.nix` exists

**"Error: Failed to query GitHub API"**
- Check network connectivity
- Verify GitHub API is reachable: `curl -s https://api.github.com/repos/sst/opencode/releases/latest`
- Check for rate limiting (60 requests/hour unauthenticated)

**"Error: Failed to fetch or hash"**
- Verify version exists on GitHub releases
- Check network connectivity to GitHub
- Ensure `nix-prefetch-url` is installed

**"Verification failed: Version mismatch"**
- Rebuild may not have completed successfully
- Check rebuild logs for errors
- Try re-running: `cd ~/proj/dotfiles && sudo nixos-rebuild switch --flake .#<hostname>`

**"Error: Required command not found"**
- Install missing tools via Nix or system package manager
- For NixOS, add to `environment.systemPackages` in configuration

## Files

```
skills/update-opencode/
├── SKILL.md                          # Agent instructions
├── README.md                         # This file
├── scripts/
│   ├── check-version.sh              # Compare versions
│   ├── fetch-sha256.sh               # Fetch SRI hash
│   ├── update-nix-file.sh            # Modify Nix file
│   └── verify-update.sh              # Verify installation
├── examples/
│   └── usage-example.sh              # Complete workflow demo
└── references/
    └── nix-package-format.md         # Nix package structure reference
```

## Examples

See `examples/usage-example.sh` for a complete workflow demonstration.

## Security

- All scripts validate input formats before execution
- File modifications are atomic (all-or-nothing)
- No partial updates - failures abort before system changes
- Dry-run mode available for safe preview

## License

Part of the AI Skills collection. See repository root for license information.
