[Bug] Plugin loader fails due to inconsistent directory structure in ~/.cache/opencode/packages

[KaysonSear]

While troubleshooting a plugin loading failure (oh-my-openagent), I discovered that the 'opencode plugin install' command creates a nested structure in '/.cache/opencode/packages/@latest/node_modules//'. However, the plugin loader (service=plugin) seems to expect the entry point at '/.cache/opencode/packages/@latest/node_modules/package.json'.

This results in the following error:
'ERROR service=plugin path=oh-my-openagent@latest error=ENOENT: no such file or directory, open /home/user/.cache/opencode/packages/oh-my-openagent@latest/node_modules/package.json failed to resolve plugin server entry'

Manual fix involves symlinking the nested package.json to the root of node_modules. Additionally, it appears that the REAL active plugins are resolved from '~/.cache/opencode/node_modules/', leading to confusion when 'opencode plugin install' creates a separate 'packages/' directory that is then partially ignored or incorrectly resolved by the runtime.

Tested on opencode v1.14.18.

[Edison-A-N]

Root Cause Analysis

I hit the same issue with GitHub shorthand plugins (Edison-A-N/opencode-preview). Traced it to commit c9326fc19 (PR #18308 — "refactor: replace BunProc with Npm module using @npmcli/arborist").

The bug

In Npm.add() → resolveEntryPoint(), after arborist installs a dependency, loadVirtual() is called and first.path returns the wrapper directory (e.g. ~/.cache/opencode/packages/Edison-A-N/opencode-preview/) instead of the actual package directory (~/.cache/opencode/packages/Edison-A-N/opencode-preview/node_modules/opencode-preview/).

This means readPluginPackage(target) reads the wrapper package.json:

{"dependencies":{"opencode-preview":"github:Edison-A-N/opencode-preview"}}

...which has no exports, no main — so plugin resolution fails.

For GitHub shorthand specs, there's a second issue: npa("Edison-A-N/opencode-preview") parses as a GitHub type where hit.name is null. The fallback in resolvePluginTarget uses the raw spec string as the package name, producing an impossible path like node_modules/Edison-A-N/package.json.

Log

ERROR service=plugin path=Edison-A-N/opencode-preview error=ENOENT: no such file or directory, open '/home/user/.cache/opencode/packages/Edison-A-N/opencode-preview/node_modules/Edison-A-N/package.json' failed to resolve plugin server entry

Reproduction

1. Add "Edison-A-N/opencode-preview" (or any GitHub shorthand) to opencode.json plugins
2. Start opencode — plugin fails to load

Environment

opencode v1.14.19, Linux

[wzharies]

Another related scenario: f27eb8f09 ("fix plugins reinstalling too often") added an existsSafe(dir) check in Npm.add() that skips arborist entirely if the cache directory already exists. The problem is it only checks whether the directory exists, not whether the installation is actually complete.

If arborist fails mid-install (network timeout, process killed, etc.), it leaves behind an empty ~/.cache/opencode/packages/<plugin>@latest/ directory with no node_modules inside. On every subsequent restart, existsSafe returns true → arborist is skipped → same ENOENT, permanently. The plugin can never self-recover until the user manually rm -rf the cache directory.

A minimal fix would be to check for node_modules/<name>/package.json instead of just the parent directory.

opencode v1.14.21, Linux

[Echokovo]

I fixed it by just delete the folder ~\.cache\opencode\packages and restart opencode

[Edison-A-N]

Deleting ~/.cache/opencode/packages works, but only until the next restart — the same ENOENT comes back.

The root cause is in Npm.add(): on cache hit it uses npa(pkg).name to reconstruct the path, but for github: specifiers npa() returns name: null, falling back to the raw spec string as the directory name (e.g. node_modules/github:Edison-A-N/...), which doesn't exist. First install works fine because reify() + tree.edgesOut resolves the correct name; cache hit skips reify and gets it wrong.

Filed #24437 with details and a proposed fix.