dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
skills/specs/002-update-opencode/spec.md
dan 99187460b1 feat(update-opencode): add skill for automating OpenCode version updates in Nix 
Implement complete workflow for checking and applying OpenCode updates:
- check-version.sh: Compare current vs latest GitHub release
- fetch-sha256.sh: Fetch SHA256 hash using nix-prefetch-url
- update-nix-file.sh: Update Nix package definition with dry-run support
- verify-update.sh: Verify installed version matches expectation

Includes comprehensive documentation (SKILL.md for agents, README.md for users)
and full spec in specs/002-update-opencode/ with user stories and acceptance criteria.

Eliminates manual Nix file editing and hash lookups for OpenCode updates.
2025-11-15 13:35:58 -08:00

8.8 KiB
Raw Blame History

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