oc-ls-stats/TUIPLUGIN.md

TUI Plugin Investigation - oc-ls-stats

Problem

The @troed/oc-ls-stats TUI plugin installs successfully via opencode plugin but produces no visible output in the OpenCode TUI.

Key Findings

1. OpenCode Plugin Architecture

• Server plugins: Configured in opencode.jsonc under plugin array, shown in /status
• TUI plugins: Configured in ~/.config/opencode/tui.json under plugin array, NOT shown in /status
• These are two completely separate plugin loaders

2. TUI Plugin Installation

• Command: opencode plugin "<package>@latest" --global
• Installs to: ~/.cache/opencode/packages/<package>@latest/node_modules/<package>/
• For scoped packages: ~/.cache/opencode/packages/@scope/package@latest/node_modules/@scope/package/
• Config updated: ~/.config/opencode/tui.json
• Peer deps installed to: ~/.config/opencode/node_modules/

3. TUI Plugin Loading

• TUI config loaded in a separate process from the main OpenCode instance
• Logs show only: "loading tui config" and "applying tui config"
• No plugin loading errors appear in logs (same as working oc-tps)
• Plugin loading happens silently - no success/error logs

4. Registry Configuration

• ~/.npmrc:

  registry=https://registry.npmjs.org/
  //git.sync.wtf/api/packages/troed/npm/:_authToken=590922c3fe27e44cd5a216f14375cff575e52b5c
  @troed:registry=https://git.sync.wtf/api/packages/troed/npm/
  

• Public npm for @opencode-ai/* and other unscoped packages
• Forgejo registry for @troed/* scoped packages

5. Package Structure (working vs non-working)

Both plugins have identical structure:

{
  "name": "@troed/oc-ls-stats",
  "version": "0.0.x",
  "type": "module",
  "exports": { "./tui": { "import": "./tui.tsx" } },
  "peerDependencies": {
    "@opencode-ai/plugin": "*",
    "@opentui/core": "*",
    "@opentui/solid": "*",
    "solid-js": "*"
  }
}

Export format (identical):

const plugin: TuiPluginModule & { id: string } = {
  id: "oc-tps",
  tui,
}
export default plugin

6. What We Tried (all failed)

• Pointing to file directly (file:///path/to/tui.tsx) - didn't work
• Adding oc-plugin field to package.json - didn't work
• Adding main field to package.json - didn't work
• Tuple format in tui.json - rejected by OpenCode
• Copying file to ~/.config/opencode/plugins/ - didn't work
• Publishing to Forgejo without scope - peer deps resolve from Forgejo (404)
• Publishing with scope (@troed/) - installs but no output
• Manual npm install to ~/.config/opencode/node_modules/ - no output
• Adding console.log - not visible (TUI runs in separate process)
• Adding early slot registration - no output
• Wrapping loadConfigUrls in try-catch - no output
• Simplified slot handler to static text - no output
• Multiple version bumps and reinstalls - no output

7. Stale Cache Issues

• OpenCode caches plugins in ~/.cache/opencode/packages/
• Stale entries from manual installs can persist
• Multiple stale directories created during debugging:
  • ~/.cache/opencode/packages/oc-ls-stats@latest (empty)
  • ~/.cache/opencode/packages/@troed/oc-ls-stats:latest (colon in name)
  • ~/.cache/opencode/packages/troed/oc-ls-stats@latest (missing @)
• Must manually clear cache before reinstalling: rm -rf ~/.cache/opencode/packages/@troed/oc-ls-stats@latest

8. Background Dependency Install Error

• ~/.opencode/package.json has "@opencode-ai/plugin": "1.4.9" as dependency
• OpenCode tries to install this from Forgejo (404) during startup
• This is a separate issue from TUI plugin loading
• The package is already installed in ~/.opencode/node_modules/

9. Working Reference: oc-tps

• Installed via: opencode plugin oc-tps@latest --global
• Cache location: ~/.cache/opencode/packages/oc-tps@latest/node_modules/oc-tps/
• tui.json: "oc-tps@latest" (unscoped)
• Shows TPS output correctly
• NOT listed in /status (expected for TUI plugins)
• No log output (same as oc-ls-stats)

10. Current State

• @troed/oc-ls-stats@0.0.8 published to Forgejo
• Installed in cache with correct version
• tui.json: ["@troed/oc-ls-stats@latest"]
• Peer deps installed in ~/.config/opencode/node_modules/
• Slot registration added at start of tui function
• Static text output in slot handler
• Still no visible output

Conclusion

The plugin installs and appears to load (same log pattern as working oc-tps), but produces no output. The root cause is unknown. Possible causes:

1. OpenCode's TUI plugin loader has an issue with scoped packages
2. There's a runtime error that's not being logged
3. The slot registration is not being triggered for some reason
4. There's a difference in how the TUI process resolves modules for scoped vs unscoped packages

Next Steps

• Compare the exact module resolution path between oc-tps and oc-ls-stats
• Check if the TUI process can actually import the scoped package
• Verify the slot registration is being called (maybe via a side effect)
• Check if there's a TUI-specific debug mode or log output