skills/specs/002-update-opencode/quickstart.md

# Quick Start: Update OpenCode Skill

**Feature**: 002-update-opencode  
**Date**: 2025-11-11  
**For**: Developers and AI agents

---

## For AI Agents (Claude Code / OpenCode)

### When to Use This Skill

The skill activates when users ask to:
- "Check for OpenCode updates"
- "Update OpenCode to the latest version"
- "Install OpenCode version X.Y.Z"
- "Is there a newer version of OpenCode available?"

### Agent Workflow

**P1: Check for Updates (Read-Only)**
```
1. User: "Check for OpenCode updates"
2. Agent invokes: skills/update-opencode/scripts/check-version.sh
3. Agent reports:
   - Current version: 1.0.44
   - Latest version: 1.0.58
   - Update available: Yes
```

**P2: Apply Update (Modifies System)**
```
1. User: "Update OpenCode to latest"
2. Agent runs: ./check-version.sh to verify update needed
3. Agent asks: "Update will trigger system rebuild (~5 min). Continue? (yes/no)"
4. User confirms: "yes"
5. Agent executes:
   a. ./fetch-sha256.sh 1.0.58
   b. ./update-nix-file.sh 1.0.58 <hash>
   c. Trigger: sudo nixos-rebuild switch --flake ~/proj/dotfiles#delpad
6. Agent verifies: ./verify-update.sh 1.0.58
7. Agent reports: "✓ OpenCode updated to 1.0.58"
```

**P3: Version Pinning**
```
1. User: "Install OpenCode 1.0.44"
2. Agent follows same P2 workflow but with specific version
3. Agent warns if downgrading: "Current: 1.0.58 → Target: 1.0.44 (downgrade)"
```

### Error Handling for Agents

**Network failures:**
```
Agent: "Cannot reach GitHub API. Check network connection."
```

**Nix file not found:**
```
Agent: "OpenCode package definition not found at ~/proj/dotfiles/pkgs/opencode/default.nix"
```

**SHA256 fetch fails:**
```
Agent: "Failed to fetch SHA256 for version 1.0.58. Version may not exist."
```

**Rebuild fails:**
```
Agent: "System rebuild failed. See error above. Revert with: cd ~/proj/dotfiles && git diff pkgs/opencode/default.nix"
```

---

## For Manual Testing

### Check Current vs Latest Version

```bash
cd skills/update-opencode/scripts
./check-version.sh
```

**Expected output:**
```
current=1.0.44
latest=1.0.58
update_available=yes
```

### Fetch SHA256 for Specific Version

```bash
./fetch-sha256.sh 1.0.58
```

**Expected output:**
```
0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z
```

(Takes 1-4 seconds)

### Preview Nix File Changes (Dry Run)

```bash
./update-nix-file.sh 1.0.58 0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z --dry-run
```

**Expected output:**
```diff
--- /home/user/proj/dotfiles/pkgs/opencode/default.nix
+++ /home/user/proj/dotfiles/pkgs/opencode/default.nix
@@ -2,7 +2,7 @@
-  version = "1.0.44";
+  version = "1.0.58";
-  sha256 = "oldhasholdhasholdhasholdhashol";
+  sha256 = "0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z";
```

### Apply Update (Actual Modification)

```bash
# Update Nix file
./update-nix-file.sh 1.0.58 0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z

# Trigger rebuild
cd ~/proj/dotfiles
sudo nixos-rebuild switch --flake .#delpad

# Verify
cd ~/proj/skills/skills/update-opencode/scripts
./verify-update.sh 1.0.58
```

### Full Workflow Test

```bash
#!/usr/bin/env bash
# Test complete update workflow (safe - uses dry-run)

set -euo pipefail

cd "$(dirname "$0")"

echo "==> Checking for updates..."
version_info=$(./check-version.sh)
eval "$version_info"

echo "Current: $current"
echo "Latest: $latest"
echo "Update available: $update_available"

if [[ "$update_available" == "yes" ]]; then
  echo ""
  echo "==> Fetching SHA256 for version $latest..."
  hash=$(./fetch-sha256.sh "$latest")
  echo "Hash: $hash"
  
  echo ""
  echo "==> Previewing Nix file changes (dry-run)..."
  ./update-nix-file.sh "$latest" "$hash" --dry-run
  
  echo ""
  echo "✓ Test complete (no actual changes made)"
else
  echo ""
  echo "✓ Already on latest version"
fi
```

---

## Prerequisites

**System requirements:**
- NixOS or Nix home-manager
- Network access to api.github.com
- Sudo access for system rebuild

**Tool dependencies:**
```bash
# Check if required tools are available
for cmd in curl jq nix-prefetch-url grep sed; do
  command -v "$cmd" >/dev/null 2>&1 || echo "Missing: $cmd"
done
```

**Dotfiles structure:**
```
~/proj/dotfiles/
└── pkgs/
    └── opencode/
        └── default.nix  # Must contain version = "..." and sha256 = "..."
```

---

## Common Issues

### "opencode command not found" after rebuild

**Cause**: Shell hasn't reloaded environment  
**Fix**: Restart shell or run: `hash -r`

### "Network error" when checking versions

**Cause**: GitHub API unreachable or rate limited  
**Fix**: Check network, wait if rate limited (60 req/hour for unauthenticated)

### "Version pattern not found in file"

**Cause**: Nix file has unexpected format  
**Fix**: Verify file contains exactly: `version = "X.Y.Z";` and `sha256 = "hash";`

### "nix-prefetch-url failed"

**Cause**: Version doesn't exist on GitHub or network issue  
**Fix**: Verify version exists: `curl -s https://api.github.com/repos/sst/opencode/releases | jq '.[].tag_name'`

---

## Skill File Structure

```
skills/update-opencode/
├── SKILL.md                  # Agent reads this for instructions
├── README.md                 # Humans read this for documentation
├── scripts/
│   ├── check-version.sh      # Compare current vs latest
│   ├── fetch-sha256.sh       # Get hash for version
│   ├── update-nix-file.sh    # Modify default.nix
│   └── verify-update.sh      # Confirm version after rebuild
├── examples/
│   ├── usage-example.sh      # Complete workflow example
│   └── example-output.txt    # Sample script outputs
└── references/
    └── nix-package-format.md # Example Nix package structure
```

---

## Next Steps

After skill implementation:

1. **Test each script independently** with sample data
2. **Test full workflow** with actual OpenCode versions
3. **Deploy to dotfiles** using `./bin/deploy-skill.sh update-opencode`
4. **Configure Nix** to install skill to `~/.claude/skills/` and `~/.config/opencode/skills/`
5. **Test with agent** by asking "check for OpenCode updates"