99187460b1
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.
166 lines
7 KiB
Markdown
166 lines
7 KiB
Markdown
# Implementation Plan: Update OpenCode Skill
|
|
|
|
**Branch**: `002-update-opencode` | **Date**: 2025-11-11 | **Spec**: [spec.md](spec.md)
|
|
**Input**: Feature specification from `/specs/002-update-opencode/spec.md`
|
|
|
|
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
|
|
|
## Summary
|
|
|
|
Create an AI agent skill that automates checking for and applying OpenCode version updates in Nix-based dotfiles. The skill eliminates manual Nix file editing and SHA256 hash lookups by querying GitHub releases, fetching cryptographic hashes via nix-prefetch-url, updating package definitions, and triggering system rebuilds with user confirmation.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Bash (no specific version requirement - standard POSIX + bash extensions)
|
|
**Primary Dependencies**: `jq`, `curl`, `nix-prefetch-url`, `sed`/`awk`, GitHub API
|
|
**Storage**: Filesystem - modifies `~/proj/dotfiles/pkgs/opencode/default.nix`
|
|
**Testing**: Manual verification scripts, bash syntax validation (`bash -n`)
|
|
**Target Platform**: NixOS or Nix home-manager on Linux
|
|
**Project Type**: AI Agent Skill (Markdown documentation + Bash helper scripts)
|
|
**Performance Goals**: Version checks <10 seconds (network-dependent), updates <5 minutes (rebuild time)
|
|
**Constraints**: Requires network access to GitHub API, sudo for system rebuild, dotfiles at known path
|
|
**Scale/Scope**: Personal/small team use, single user per execution, ~5 helper scripts
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
**Skills Repository Constitution** (from `.specify/memory/constitution.md`):
|
|
|
|
The constitution template is empty/placeholder. Based on project AGENTS.md and observed patterns:
|
|
|
|
### I. Skill-First Design ✅ PASS
|
|
- Feature is designed as a standalone skill with clear scope
|
|
- SKILL.md will contain agent instructions
|
|
- Helper scripts are reusable and testable independently
|
|
|
|
### II. Bash Best Practices ✅ PASS
|
|
- FR-012 mandates: shebang, `set -euo pipefail`, error handling
|
|
- Follows established patterns from niri-window-capture skill
|
|
- Scripts will use `jq --arg` for safe variable handling
|
|
|
|
### III. Security Awareness ✅ PASS
|
|
- No security-sensitive operations (reading public GitHub data, modifying user's own files)
|
|
- No SECURITY.md required (unlike niri-window-capture which had invisible capture capability)
|
|
- User confirmation required before system modifications (FR-010)
|
|
|
|
### IV. Fail-Safe Design ✅ PASS
|
|
- FR-009: No partial modifications - atomic operations only
|
|
- FR-008: Clear error messages, fail fast
|
|
- No sophisticated recovery - rely on git revert
|
|
|
|
### V. Simplicity ✅ PASS
|
|
- Removed over-engineering (cross-validation, rate limit parsing, partial update detection)
|
|
- Focuses on core task: check, fetch, update, rebuild
|
|
- 12 focused requirements (down from 19 in initial draft)
|
|
|
|
**Gate Result**: ✅ **PASS** - No violations, no complexity justification needed
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/002-update-opencode/
|
|
├── plan.md # This file
|
|
├── spec.md # Feature specification (completed)
|
|
├── research.md # Phase 0 output (to be created)
|
|
├── data-model.md # Phase 1 output (to be created)
|
|
├── quickstart.md # Phase 1 output (to be created)
|
|
├── contracts/ # Phase 1 output (to be created)
|
|
│ └── script-interface.md # Bash script contracts
|
|
├── checklists/ # Spec validation (completed)
|
|
│ └── requirements.md
|
|
└── tasks.md # Phase 2 output (/speckit.tasks - not created yet)
|
|
```
|
|
|
|
### Source Code (skills repository root)
|
|
|
|
```text
|
|
skills/update-opencode/
|
|
├── SKILL.md # Agent instructions (main skill definition)
|
|
├── README.md # User-facing documentation
|
|
├── scripts/ # Helper bash scripts
|
|
│ ├── check-version.sh # Compare current vs latest
|
|
│ ├── fetch-sha256.sh # Get SHA256 for version
|
|
│ ├── update-nix-file.sh # Modify default.nix safely
|
|
│ └── verify-update.sh # Confirm version after rebuild
|
|
├── examples/ # Example usage and outputs
|
|
│ ├── usage-example.sh
|
|
│ └── example-output.txt
|
|
└── references/ # Supporting documentation
|
|
└── nix-package-format.md # Example Nix package structure
|
|
```
|
|
|
|
**Structure Decision**: AI Agent Skill structure (documentation + bash scripts). This is not a traditional software project but a skill for Claude Code/OpenCode agents. The skill lives in `skills/update-opencode/` and will be deployed to dotfiles via `bin/deploy-skill.sh` script. Follows established pattern from worklog and niri-window-capture skills.
|
|
|
|
## Complexity Tracking
|
|
|
|
*Not applicable - Constitution Check passed with no violations.*
|
|
|
|
---
|
|
|
|
## Phase 0: Research & Design Decisions
|
|
|
|
**Status**: ✅ Complete
|
|
|
|
**Research Tasks** (Completed):
|
|
|
|
1. **Nix Package File Parsing**: Determine safest approach to read/update `version = "X.Y.Z"` and `sha256 = "hash"` fields
|
|
- Options: sed with precise patterns, awk field replacement, nix-instantiate parsing
|
|
- Need to preserve formatting, comments, surrounding code
|
|
|
|
2. **GitHub API Usage**: Verify API endpoints and response structure for stable releases
|
|
- Confirm `/repos/sst/opencode/releases/latest` returns non-prerelease versions
|
|
- Document response fields: `tag_name`, `prerelease`, `tarball_url`
|
|
|
|
3. **nix-prefetch-url Invocation**: Determine correct syntax for fetching SHA256
|
|
- Command pattern for GitHub release tarballs
|
|
- Error handling for network failures
|
|
|
|
4. **Version Comparison Logic**: Simple semantic version comparison in bash
|
|
- Parse major.minor.patch format
|
|
- Determine if update available (newer vs current)
|
|
|
|
5. **System Rebuild Triggering**: Verify rebuild command and error handling
|
|
- Determine if `sudo nixos-rebuild switch` vs home-manager rebuild
|
|
- Capture rebuild output for error reporting
|
|
|
|
**Output**: ✅ `research.md` completed with all decisions documented
|
|
|
|
---
|
|
|
|
## Phase 1: Design & Contracts
|
|
|
|
**Status**: ✅ Complete
|
|
|
|
**Deliverables** (Completed):
|
|
|
|
1. **data-model.md**: Entity definitions
|
|
- VersionInfo (current, latest, updateAvailable)
|
|
- NixPackageFile (path, version, sha256, content)
|
|
- GitHubRelease (tag, tarballUrl, isPrerelease)
|
|
|
|
2. **contracts/script-interface.md**: Bash script contracts
|
|
- Input/output contracts for each helper script
|
|
- Exit codes, stdout format, stderr error messages
|
|
- Environment variables required
|
|
|
|
3. **quickstart.md**: Quick reference for skill usage
|
|
- How agents invoke the skill
|
|
- Example agent conversations
|
|
- Manual script invocation for testing
|
|
|
|
4. **Agent context update**: ✅ Completed
|
|
- Updated AGENTS.md with bash scripting context
|
|
- Added GitHub API and Nix tooling knowledge
|
|
- Documented dependencies: jq, curl, nix-prefetch-url, sed/awk
|
|
|
|
---
|
|
|
|
## Phase 2: Task Breakdown
|
|
|
|
**Status**: ⏳ Not started (separate command: `/speckit.tasks`)
|
|
|
|
This phase is handled by the `/speckit.tasks` command after planning is complete.
|