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

# Feature Specification: Update OpenCode Skill

**Feature Branch**: `002-update-opencode`  
**Created**: 2025-11-11  
**Status**: Draft  
**Input**: User description: "Implement update-opencode skill for checking and applying OpenCode version updates in Nix-based dotfiles setup"

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Check for OpenCode Updates (Priority: P1)

An operations team member or developer wants to know if a newer version of OpenCode is available without manually checking GitHub releases or editing configuration files.

**Why this priority**: This is the minimum viable functionality - being able to query version information. It delivers immediate value by automating the manual check process and provides awareness of available updates without any system changes.

**Independent Test**: Can be fully tested by invoking the skill with "check for OpenCode updates" and verifying it returns current version, latest available version, and whether an update is available. No system modifications required.

**Acceptance Scenarios**:

1. **Given** OpenCode is installed via Nix at version 1.0.44, **When** user asks agent to check OpenCode version, **Then** agent reports current version (1.0.44), latest GitHub release version, and whether update is available
2. **Given** user is already on latest version, **When** checking for updates, **Then** agent confirms system is up-to-date with no action needed
3. **Given** GitHub API is unreachable, **When** checking for updates, **Then** agent reports network error with clear message and does not fail silently

---

### User Story 2 - Apply OpenCode Update (Priority: P2)

A user discovers an update is available and wants to apply it by having the agent automatically update the Nix package definition, fetch the correct SHA256 hash, and trigger a system rebuild.

**Why this priority**: This is the core automation value - eliminating manual Nix file editing and SHA256 fetching. Depends on P1 (checking versions) but delivers the main time-saving benefit.

**Independent Test**: Can be tested by requesting "update OpenCode to version X" with the agent performing file updates, rebuild trigger, and verification. Requires P1 to detect version mismatch first.

**Acceptance Scenarios**:

1. **Given** newer version exists (e.g., 1.0.51), **When** user confirms update after being presented with rebuild impact summary, **Then** agent fetches SHA256 for new version, updates `pkgs/opencode/default.nix` with new version and hash, triggers system rebuild, and reports success
2. **Given** update is requested but already on latest, **When** update command issued, **Then** agent confirms no update needed and does not trigger rebuild
3. **Given** SHA256 fetch fails for new release, **When** attempting update, **Then** agent reports error clearly and does not modify Nix files or trigger rebuild
4. **Given** Nix file update succeeds but rebuild fails, **When** update attempted, **Then** agent reports rebuild failure with error details and suggests rollback or manual intervention

---

### User Story 3 - Update to Specific Version (Priority: P3)

A user needs to update (or downgrade) to a specific OpenCode version for compatibility reasons, such as maintaining compatibility with a specific plugin version.

**Why this priority**: This is an advanced use case for version pinning. While valuable for production stability, most users will use P2 (latest version). Can be implemented after core functionality works.

**Independent Test**: Can be tested independently by requesting "update OpenCode to version 1.0.44" and verifying the agent installs that specific version regardless of what's latest.

**Acceptance Scenarios**:

1. **Given** user specifies target version (e.g., "update to 1.0.44"), **When** agent processes request, **Then** agent fetches that specific version's SHA256, updates Nix file to target version, rebuilds, and verifies
2. **Given** specified version doesn't exist on GitHub, **When** update requested, **Then** agent reports version not found and lists available versions
3. **Given** downgrading from 1.0.51 to 1.0.44, **When** update executed, **Then** agent warns about downgrade, proceeds if confirmed, and successfully installs older version

---

### Edge Cases

- What if the Nix package file (`default.nix`) has unexpected structure or is missing? (Report error, don't attempt to parse)
- What if GitHub API fails? (Report error, suggest manual check)
- What if nix-prefetch-url fails? (Report error, don't modify files)

## Requirements *(mandatory)*

### Functional Requirements

**Core Functionality:**
- **FR-001**: Skill MUST read current OpenCode version from `pkgs/opencode/default.nix` in dotfiles repository
- **FR-002**: Skill MUST query GitHub API for latest stable release (excluding pre-releases)
- **FR-003**: Skill MUST compare versions and report status (up-to-date, update available, or error)
- **FR-004**: Skill MUST fetch SHA256 hash using `nix-prefetch-url` for target version
- **FR-005**: Skill MUST update version and SHA256 in `pkgs/opencode/default.nix` preserving file structure
- **FR-006**: Skill MUST trigger system rebuild after updating package definition
- **FR-007**: Skill MUST verify successful update by running `opencode --version`

**Error Handling:**
- **FR-008**: Skill MUST report clear errors for network failures, missing files, or invalid versions
- **FR-009**: Skill MUST not modify files if any prerequisite step fails

**User Interaction:**
- **FR-010**: Skill MUST confirm with user before triggering system rebuild
- **FR-011**: Skill MUST support updating to specific version for pinning

**Quality:**
- **FR-012**: Helper scripts MUST follow bash best practices (shebang, `set -euo pipefail`, error handling)

### Key Entities

- **OpenCode Version**: Semantic version string (e.g., "1.0.44") representing installed or available OpenCode CLI version
- **Nix Package Definition**: File at `pkgs/opencode/default.nix` containing version, SHA256 hash, and package metadata
- **GitHub Release**: Release artifact on `sst/opencode` repository with version tag, release assets, and metadata
- **SHA256 Hash**: Cryptographic hash of OpenCode release tarball required for Nix package integrity verification

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users can check for updates and apply them without manual Nix file editing or SHA256 lookups
- **SC-002**: Update process fails safely - no partial modifications if any step errors
- **SC-003**: Skill correctly identifies current version, latest version, and whether update is available
- **SC-004**: Skill supports version pinning for compatibility (install specific version)

## Clarifications

### Session 2025-11-11

- Q: How should the agent handle rebuild confirmation? → A: Ask user to confirm before triggering rebuild
- Removed over-engineering: Cross-validation, rate limit parsing, partial update detection - these add complexity without clear value for personal/small-team use

## Assumptions

- Dotfiles repository is located at `~/proj/dotfiles` with predictable structure
- OpenCode package definition is at `pkgs/opencode/default.nix` within dotfiles
- System uses NixOS or Nix home-manager with rebuild command available
- User has network access to GitHub API (api.github.com)
- User has permissions to modify dotfiles and trigger system rebuild
- Nix package definition follows standard format with `version = "X.Y.Z"` and `sha256 = "hash"` fields
- GitHub releases follow semantic versioning (major.minor.patch)
- User wants stable releases by default (not alpha/beta/rc versions)
- System rebuild command is `sudo nixos-rebuild switch --flake .#delpad` or user can specify alternative
- Verification can be done by running `opencode --version` after rebuild

## Scope

### In Scope

- Check current version from Nix file
- Query GitHub for latest stable release
- Compare versions and report status
- Fetch SHA256 hash with nix-prefetch-url
- Update Nix file (version + hash)
- Trigger system rebuild
- Verify update with `opencode --version`
- Support specific version pinning
- Basic error handling (fail fast, clear messages)

### Out of Scope

- Non-Nix installations (npm, binary)
- Automatic/scheduled checks
- Automatic rollback (use git revert)
- Plugin compatibility checking
- GUI/web interface
- Multiple dotfiles repos
- Cross-platform (Nix-only)
- Sophisticated error recovery
- Rate limit handling beyond "fail with error"
- Audit logging (not needed for personal use)
- Cross-validation of multiple sources

## Dependencies

- **External**: GitHub API (api.github.com)
- **Tools**: `nix-prefetch-url`, `jq`, `curl`, `sed`/`awk`
- **Environment**: NixOS or home-manager with rebuild command
- **Permissions**: Sudo for rebuild

## Constraints

- Requires network access to GitHub
- Rebuild takes several minutes
- Assumes dotfiles at `~/proj/dotfiles`
- Assumes standard Nix package file structure
- OpenCode needs restart after rebuild