forked from c-fu/arah2
araharah-executor
506ff68976
- Root Rams design docs (DESIGN.md, IDEAS.md) and GSD install-fix notes (GSD_FIX.md, gsd-fix.sh) - Four Telemetry Rams mockup screens + telemetry_rams/DESIGN.md (canonical token frontmatter) - .agents/ project skills (design-taste-frontend) + skills-lock.json - .gitignore: node_modules/dist/env secrets/OS junk; .planning stays local-only; Zone.Identifier scrubbed (9 files deleted)
84 lines
3.5 KiB
Markdown
84 lines
3.5 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/755 files intact,
|
|
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
|
|
|
|
- `which gsd-opencode` also resolved to a **Windows npm shim** (`/mnt/c/Users/.../npm/gsd-opencode`)
|
|
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`.
|
|
- 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.json` 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) |
|