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

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:

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:

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:

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:

---
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

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)