Skip to content

feat(AI-014): bootstrap OpenCode on Windows via winget SST.opencode#78

Merged
mlorentedev merged 1 commit into
mainfrom
feat/AI-014-opencode-windows-bootstrap
May 21, 2026
Merged

feat(AI-014): bootstrap OpenCode on Windows via winget SST.opencode#78
mlorentedev merged 1 commit into
mainfrom
feat/AI-014-opencode-windows-bootstrap

Conversation

@mlorentedev
Copy link
Copy Markdown
Owner

Summary

Mirror of AI-011 (Linux bootstrap, PRs #34/#36/#37, 2026-05-16) on the Windows side. The Linux path uses `curl -fsSL https://opencode.ai/install | bash`; empirical probe 2026-05-21 against winget revealed `SST.opencode` (v1.15.6) is published natively, user-scope installable, PATH handled by winget itself. That is substantially cleaner than the original AI-014 backlog entry's "admin-conditional curl-bash equivalent or npm install" hypothesis and reduces this spec from ~150 LOC of admin-detection logic to ~75 LOC of straight mirror.

Changes

  1. setup-windows.ps1 section 1c: append `SST.opencode` to existing `$tools` winget array. Idempotent via foreach's per-tool `Get-Command opencode` guard. Inherits section's post-loop PATH refresh.
  2. setup-windows.ps1 new section 2d (after 2c Obsidian CLI):
    • Deploy `ai/opencode/opencode.jsonc` to `%USERPROFILE%.config\opencode\opencode.jsonc` using SHA256 byte-equality test before copy (reconcile-not-skip, mirror of setup-linux.sh:415-428's `cmp -s`).
    • Sync `ai/opencode/commands/*.md` to `%USERPROFILE%.config\opencode\commands\` with add/skip/remove-orphan counters identical to setup-linux.sh:430-465.
  3. scripts/healthcheck.ps1 sec 10/12: drop the "AI-014 pending" parenthetical from SKIP messages. PASS path (`Test-Command 'opencode'` true + jsonc deployed) was already wired.
  4. tests/setup-windows.bats: 3 new asserts locking the `SST.opencode` entry, the SHA256-guarded jsonc deploy, and the orphan-removal in commands sync.

Spec at `specs/AI-014-opencode-windows-bootstrap/`. Production diff 74 LOC (≥ 50 threshold), spec-gate satisfied.

Empirical probe (2026-05-21)

```
PS> winget search opencode --source winget
opencode SST.opencode 1.15.6
OpenCode SST.OpenCodeDesktop 1.15.6 ProductCode: opencode

PS> Invoke-WebRequest https://opencode.ai/install.ps1 -Method Head
404 Not Found # confirms no PowerShell installer upstream

PS> Invoke-RestMethod https://registry.npmjs.org/opencode-ai | %{ $_.'dist-tags'.latest }
1.15.7 # npm fallback available, not chosen
```

`SST.opencode` (NOT `SST.OpenCodeDesktop` — that is the GUI). User-scope, no admin, winget manages PATH.

Test plan

  • PowerShell AST `[Parser]::ParseFile` → clean for both setup-windows.ps1 + healthcheck.ps1
  • `Invoke-ScriptAnalyzer -Settings .PSScriptAnalyzerSettings.psd1 -Severity Error,Warning` → clean (no em-dash regression from BUG-014)
  • ASCII-only check → 0 non-ASCII chars
  • 3 new bats asserts in `tests/setup-windows.bats`
  • CI green
  • Empirical run on user's Windows: `winget install SST.opencode` succeeds non-elevated; `opencode --version` returns 1.15.x; `opencode.jsonc` SHA256 matches source; commands dir has 12 .md files

Coexistence note

The Hive MCP write-lock race between Claude Code and OpenCode (documented in `40-runbooks/guide-opencode-go-setup.md`) applies cross-OS. Until the hive flock follow-up merges, do not run `oc` and `claude` in parallel on the same repo. Safe pattern: sequential per repo, OR different repos in parallel.

Out of scope

  • Porting `scripts/skills-to-opencode.sh` to PowerShell (regeneration stays Linux/CI concern)
  • Automating the `/connect` flow (intentionally manual, API-key paste required)
  • A separate Windows runbook (the existing `guide-opencode-go-setup.md` is OS-agnostic for /connect/PAYG/troubleshooting; a small "Windows install delta" section gets folded post-merge)

Lesson candidate

"When porting a Linux feature to Windows, probe the native package manager (winget) FIRST before assuming the Linux install path (curl-bash, npm) is the only option. The cleaner channel often exists but is invisible to a Linux-first design."

Mirror of AI-011 (Linux bootstrap, PRs #34/#36/#37, 2026-05-16) on the
Windows side. The Linux path uses `curl -fsSL https://opencode.ai/install
| bash`; empirical probe 2026-05-21 against winget revealed
`SST.opencode` (v1.15.6) is published natively, user-scope installable,
PATH handled by winget itself. That is substantially cleaner than the
original AI-014 backlog entry's "admin-conditional curl-bash equivalent
or npm install" hypothesis and reduces this spec from ~150 LOC of
admin-detection logic to ~75 LOC of straight mirror.

Changes (3 production files, 1 test file, ~98 LOC):

1. setup-windows.ps1 section 1c: append `SST.opencode` to the existing
   `$tools` winget array. Idempotent via the foreach's per-tool
   `Get-Command opencode` guard. Inherits the section's post-loop
   PATH refresh.

2. setup-windows.ps1 new section 2d (after 2c Obsidian CLI):
     (a) Deploy `ai/opencode/opencode.jsonc` to
         `%USERPROFILE%\.config\opencode\opencode.jsonc` using SHA256
         byte-equality test before copy (reconcile-not-skip,
         mirror of setup-linux.sh:415-428's cmp -s).
     (b) Sync `ai/opencode/commands/*.md` to
         `%USERPROFILE%\.config\opencode\commands\` with add/skip/
         remove-orphan counters identical to setup-linux.sh:430-465.

3. scripts/healthcheck.ps1 sec 10/12: drop the "AI-014 pending"
   parenthetical from SKIP messages. The PASS path (Test-Command
   'opencode' true + jsonc deployed) was already wired; this just
   removes the now-obsolete pointer.

4. tests/setup-windows.bats: 3 new asserts locking the SST.opencode
   entry, the SHA256-guarded jsonc deploy, and the orphan-removal in
   the commands sync.

Spec at specs/AI-014-opencode-windows-bootstrap/. Production diff 74
LOC (>= 50 threshold) so spec-gate enforces a spec folder, satisfied.

Empirical probe transcript captured in verification.md:
  - winget search opencode -> SST.opencode v1.15.6 user-installable
  - opencode.ai/install.ps1 -> 404 (no PowerShell installer upstream)
  - npm opencode-ai -> v1.15.7 (fallback channel, not chosen)

Coexistence constraint with Claude Code (Hive MCP write lock race) is
documented in 40-runbooks/guide-opencode-go-setup.md; that runbook is
OS-agnostic for /connect / PAYG-guardrail / troubleshooting and a small
Windows install delta gets folded post-merge.

Lesson candidate (post-merge):
  "When porting a Linux feature to Windows, probe the native package
   manager (winget) FIRST before assuming the Linux install path is
   the only option. The cleaner channel often exists but is invisible
   to a Linux-first design."
@mlorentedev mlorentedev merged commit 407ae15 into main May 21, 2026
6 checks passed
@mlorentedev mlorentedev deleted the feat/AI-014-opencode-windows-bootstrap branch May 21, 2026 17:54
mlorentedev added a commit that referenced this pull request May 21, 2026
Move from specs/ to specs/archive/ per SDD lifecycle close (the
folder move IS the archive marker; status: archived frontmatter
update deferred to per-spec follow-up if needed).

This session shipped (today, 2026-05-21):
  - AI-014-opencode-windows-bootstrap (PR #78)
  - BUG-014-claude-mem-marketplace-register (PR #75)
  - BUG-016-claude-mem-heal-v13-refresh (PR #83)
  - BUG-017-claude-mem-heal-hooks-json-race (PR #84)
  - BUG-018-userpromptsubmit-continue-directive (PR #85)
  - REFACTOR-003-diff-check-ps1 (PR #82)

Catch-up archive (merged earlier weeks but specs/ folder lingered):
  - BUG-007-remove-github-plugin-broken (PR #65, 2026-05-19)
  - BUG-011-mcp-loop-claude-json-guard (PR #69, 2026-05-20)
  - BUG-012-claude-mem-marketplace-junction (PR #70, 2026-05-20)
  - SDD-005-github-copilot-instructions-sync (PR #62, 2026-05-19)
  - SDD-006-vault-integrity-check (PR #63, 2026-05-19)

Active specs remaining in specs/ (not yet merged):
  - REFACTOR-002-paths-in-env-contract (queued, still draft)
  - WIN-002-windows-smoke-sweep (partial closure via PR #73, full
    clean-VM sweep still open)

33 file moves total (3 files per spec × 11 specs). Zero content change.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant