forked from c-fu/arah2
araharah-executor
91ad0c9d93
- New: docs/ARCHITECTURE.md, docs/GETTING-STARTED.md, docs/DEVELOPMENT.md, docs/TESTING.md, docs/CONFIGURATION.md (colored mermaid diagrams, quoted labels) - Regenerated README.md (arah² / arah2bot naming, canonical clone URL) - New per-package READMEs: theme/, bot/, web/ - Verified 13 docs against the live codebase (2 fix iterations + 2 residual corrections); corrected 56 stale claims across AGENTS/DESIGN/IDEAS/GSD_FIX
85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
# GSD_FIX.md — Notes on repairing the GSD-OpenCode install
|
|
|
|
**Date:** 2026-10-21
|
|
**Package:** `gsd-opencode` v1.38.5 (installed via `npx gsd-opencode` → global scope, `~/.config/opencode/`)
|
|
|
|
## Symptoms
|
|
|
|
Inside OpenCode, none of the `/gsd-*` commands were available, and `gsd-sdk` appeared broken/missing.
|
|
|
|
## Root causes (two separate issues)
|
|
|
|
### 1. Slash commands were registered under the wrong names — `/gsd/gsd-*`, not `/gsd-*`
|
|
|
|
The v1.38.5 distribution manager installs the 88 GSD command files into a **nested subdirectory**:
|
|
|
|
```
|
|
~/.config/opencode/commands/gsd/gsd-plan-phase.md
|
|
~/.config/opencode/commands/gsd/gsd-execute-phase.md
|
|
...
|
|
```
|
|
|
|
This layout predates OpenCode V2's command discovery rules. In V2, nested paths become
|
|
**namespaced** slash commands (documented at https://opencode.ai/v2/docs/commands/):
|
|
|
|
- `commands/gsd/gsd-execute-phase.md` → `/gsd/gsd-execute-phase` (what OpenCode registered)
|
|
- instead of `/gsd-execute-phase` (what the GSD README documents and users expect)
|
|
|
|
Verified against the running service via `opencode api get /api/command`: every command was
|
|
registered as `gsd/gsd-*`, so typing `/gsd-*` found nothing — they "seemed" missing even though
|
|
the files were all present (the installer's `gsd-opencode check` reported 755/843 files verified
|
|
— 755 passing out of the 843-file manifest — which is exactly why the health check did not catch this).
|
|
|
|
**Fix:** flattened the command files:
|
|
|
|
```bash
|
|
mv ~/.config/opencode/commands/gsd/*.md ~/.config/opencode/commands/
|
|
rmdir ~/.config/opencode/commands/gsd
|
|
```
|
|
|
|
OpenCode hot-reloads command files, so the `/gsd-*` names registered immediately (confirmed via
|
|
the `/api/command` endpoint — 88 flat `gsd-*` commands, zero `gsd/gsd-*` entries).
|
|
|
|
### 2. `gsd-sdk` was a dangling symlink into the ephemeral npx cache
|
|
|
|
Running the installer via `npx gsd-opencode` leaves the "global" binaries pointing into
|
|
`~/.npm/_npx/*.*/node_modules/.bin/`, which npx may garbage-collect at any time:
|
|
|
|
```
|
|
~/.local/bin/gsd-sdk -> ~/.npm/_npx/2ada84fac427087c/node_modules/.bin/gsd-sdk # fragile
|
|
```
|
|
|
|
Every GSD command/agent shells out to `gsd-sdk query …`; when the npx cache is pruned, all of
|
|
those calls die silently.
|
|
|
|
**Fix:** installed a pinned global copy and re-pointed the shim:
|
|
|
|
```bash
|
|
npm install -g gsd-opencode
|
|
ln -sf ~/.nvm/versions/node/v24.18.0/bin/gsd-sdk ~/.local/bin/gsd-sdk
|
|
```
|
|
|
|
Verified with `gsd-sdk query state.load` (succeeds) and `gsd-sdk --version`.
|
|
|
|
## Side notes
|
|
|
|
- At the time of this repair, `which gsd-opencode` also resolved to a **Windows npm shim**
|
|
(under `/mnt/c/Users/.../npm/`) on the WSL PATH, from a previous install on the Windows side.
|
|
Harmless but confusing; the Linux binaries under `~/.nvm/.../bin` now take precedence for
|
|
`gsd-sdk`. That shim has since been removed and is no longer on the current PATH.
|
|
- The installer's own health checker (`gsd-opencode check`) still expects the old nested
|
|
`commands/gsd/` layout and will report the 88 flattened files as "missing" — this is a false
|
|
positive caused by the checker not knowing about OpenCode V2's namespacing rules. The files
|
|
are fine where OpenCode can find them.
|
|
- After changing GSD model profiles, note the package requires a full OpenCode restart
|
|
(agent→model mappings come from `opencode.jsonc` and are read at startup).
|
|
|
|
## Current state
|
|
|
|
| Item | Status |
|
|
|---|---|
|
|
| `/gsd-*` slash commands | ✅ 88 registered flat at `~/.config/opencode/commands/` |
|
|
| `gsd-sdk` CLI | ✅ stable symlink to global npm install (`~/.nvm/.../bin/gsd-sdk`) |
|
|
| Agents / skills / rules / sdk files | ✅ untouched, integrity verified |
|
|
| `gsd-opencode check` | ⚠️ reports false "missing files" (stale checker, see above) |
|