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

# Tasks: Update OpenCode Skill

**Simplified**: Focused on essential implementation work, removed over-engineering  
**Prerequisites**: spec.md (requirements), contracts/script-interface.md (script I/O)

---

## Implementation Tasks

### Setup (2 tasks)

- [ ] T001 Create skill directory structure: `mkdir -p skills/update-opencode/{scripts,examples,references}`
- [ ] T002 Copy ~/proj/dotfiles/pkgs/opencode/default.nix to skills/update-opencode/references/nix-package-format.md as reference example

### Core Scripts (4 tasks - can run in parallel)

- [ ] T003 [P] Implement skills/update-opencode/scripts/check-version.sh (reads Nix file, queries GitHub API, compares versions, outputs key=value format)
- [ ] T004 [P] Implement skills/update-opencode/scripts/fetch-sha256.sh (runs nix-prefetch-url, converts to SRI format via `nix hash to-sri`)
- [ ] T005 [P] Implement skills/update-opencode/scripts/update-nix-file.sh (uses sed to update version and sha256 fields, supports --dry-run)
- [ ] T006 [P] Implement skills/update-opencode/scripts/verify-update.sh (runs `opencode --version`, compares to expected)

### Documentation (3 tasks)

- [ ] T007 Create skills/update-opencode/SKILL.md with YAML frontmatter (name, description), When to Use section, and complete workflow instructions
- [ ] T008 [P] Create skills/update-opencode/README.md with installation, prerequisites (jq, curl, nix-prefetch-url, sed), and usage examples
- [ ] T009 [P] Create skills/update-opencode/examples/usage-example.sh demonstrating complete check → fetch → update → verify workflow

### Testing & Deployment (1 task)

- [ ] T010 Test complete workflow: run check-version.sh, fetch-sha256.sh with test version, update-nix-file.sh in dry-run mode, verify all error handling works, then deploy to dotfiles

---

## Task Details

### T001: Create Directory Structure
```bash
mkdir -p skills/update-opencode/{scripts,examples,references}
```

### T003: check-version.sh
**Key logic:**
- Dependency check: jq, curl, grep
- Parse current version: `grep -oP 'version\s*=\s*"\K[^"]+' default.nix`
- Query GitHub: `curl -s https://api.github.com/repos/sst/opencode/releases/latest | jq -r '.tag_name'`
- Compare with `sort -V`
- Output: `current=X.Y.Z\nlatest=X.Y.Z\nupdate_available=yes/no`

### T004: fetch-sha256.sh
**Key logic:**
```bash
VERSION="$1"
URL="https://github.com/sst/opencode/releases/download/v${VERSION}/opencode-linux-x64.zip"
NIX_HASH=$(nix-prefetch-url --type sha256 "$URL" 2>/dev/null | head -1)
nix hash to-sri --type sha256 "$NIX_HASH"
```

### T005: update-nix-file.sh
**Key logic:**
```bash
sed -i \
  -e "s/version = \"[^\"]*\"/version = \"$VERSION\"/" \
  -e "s/sha256 = \"[^\"]*\"/sha256 = \"$SHA256\"/" \
  pkgs/opencode/default.nix
```
Add --dry-run support to show diff without modifying.

### T006: verify-update.sh
**Key logic:**
```bash
EXPECTED="$1"
ACTUAL=$(timeout 5 opencode --version 2>&1 | grep -oP '\d+\.\d+\.\d+' | head -1)
[[ "$ACTUAL" == "$EXPECTED" ]] && echo "✓ Verified" || echo "✗ Mismatch"
```

### T007: SKILL.md
**Structure:**
```yaml
---
name: update-opencode
description: Check for and apply OpenCode version updates in Nix-based dotfiles. Use when asked to update OpenCode, check OpenCode version, or upgrade OpenCode.
---

# Update OpenCode Skill

## When to Use
- User asks to check OpenCode version
- User asks to update/upgrade OpenCode
- User wants to install specific OpenCode version

## Process
1. Check current vs latest: Run scripts/check-version.sh
2. If update available and user confirms:
   a. Fetch SHA256: scripts/fetch-sha256.sh <version>
   b. Update Nix file: scripts/update-nix-file.sh <version> <hash>
   c. Trigger rebuild: cd ~/proj/dotfiles && sudo nixos-rebuild switch --flake .#delpad
   d. Verify: scripts/verify-update.sh <version>

## Requirements
- Tools: jq, curl, nix-prefetch-url, sed
- Permissions: sudo for rebuild
- Network: GitHub API access
```

### T010: Testing Workflow
```bash
cd skills/update-opencode/scripts

# Test syntax
bash -n *.sh

# Test version check
./check-version.sh

# Test hash fetch (use known version)
./fetch-sha256.sh 1.0.44

# Test update in dry-run
./update-nix-file.sh 1.0.58 sha256-ABC123... --dry-run

# Test error handling
./check-version.sh --dotfiles /nonexistent  # Should error gracefully
./fetch-sha256.sh 99.99.99  # Should handle 404

# If all pass, deploy
cd ~/proj/skills
./bin/deploy-skill.sh update-opencode
```

---

## Execution Notes

**Estimated Time**: 3-4 hours total
- Setup: 10 min
- Scripts: 2 hours (4 scripts × 30 min each)
- Documentation: 1 hour
- Testing/Deploy: 30 min

**All scripts follow:**
- Shebang: `#!/usr/bin/env bash`
- Error handling: `set -euo pipefail`
- Safe jq usage: `jq --arg` for variable interpolation
- Clear errors to stderr: `echo "Error: ..." >&2; exit 1`

**Key Implementation Notes:**
- Use SRI hash format (sha256-...), not Nix base-32
- Binary releases (~50MB), not source tarballs
- URL pattern: `https://github.com/sst/opencode/releases/download/v${VERSION}/opencode-linux-x64.zip`
- Atomic updates: validate patterns exist before sed -i

---

## Deliverables

```
skills/update-opencode/
├── SKILL.md              # Agent instructions (~50 lines)
├── README.md             # User documentation (~50 lines)
├── scripts/
│   ├── check-version.sh      # ~50 lines
│   ├── fetch-sha256.sh       # ~40 lines
│   ├── update-nix-file.sh    # ~60 lines
│   └── verify-update.sh      # ~30 lines
├── examples/
│   └── usage-example.sh      # ~30 lines
└── references/
    └── nix-package-format.md # Example Nix file
```

**Total**: ~310 lines of actual code/docs (down from 1,106 lines of planning docs)