@aexol/opencode-wizard

@aexol/opencode-wizard is a separately releasable OpenCode plugin package for fetching published skills from the opencode-wizard backend runtime and surfacing plugin status in the TUI.

Package target

• oc-plugin: ["server", "tui"]
• ./server → dist/server.js
• ./tui → dist/tui.js
• no generated runtime skill directory is published; the plugin stays fetch-only at runtime
• native OpenCode skills.urls is treated as a public/static registry complement, not as the private wizard delivery authority
• the TUI shows loaded plugins, current paths, backend/auth status without tokens, available tools, skills.urls guidance, the backend-published GLOBAL/PROJECT delivery model, policy labels, and catalog counts/names when passive fetch succeeds

Local development

This monorepo still path-loads the same package from ./plugin/opencode-wizard during local OpenCode development.

Backend origin resolution keeps local-first behavior only when the plugin is executing from a local module path/check-out. In that case it still prefers repo .env/PORT, then APP_URL, then falls back to http://localhost:8080. For the packaged/published plugin, the same config values still win when present, but the fallback origin is https://opencode-wizard.aexol.work.

Useful commands:

npm run typecheck
npm run build
npm run release:check

Published package usage

OpenCode server/plugin host can install the published package by package name instead of a repo-local path:

{
  "plugin": ["@aexol/opencode-wizard@latest"]
}

For repo-local development, continue using the local path-based config already documented in this repository.

Native skills.urls compatibility

OpenCode's native skills.urls support downloads public/static skill registries from base URLs that expose an index.json and file paths under that base URL. Current support has no plugin session/header integration, so it must not be pointed at private opencode-wizard skill delivery.

Use skills.urls only for public registries that are intentionally cacheable by OpenCode. Private workspace-scoped wizard skills remain authenticated and directory-scoped through opencode_wizard_published_skills_fetch.

Catalog discovery and auth bootstrap

On chat/system-context startup, the plugin attempts to load the catalog automatically with the stored plugin session at plugin/opencode-wizard/.generated/auth-state.json. If no valid plugin session exists, startup stays passive and reports that interactive fetch will bootstrap browser login when needed; it does not open the browser from system context.

Call opencode_wizard_published_skills_fetch without skill or skills to manually bootstrap plugin login if needed and return catalog-only discovery output for the current directory scope.

No-arg discovery returns published skill summaries, assignment counts split into global and project, policy metadata, and no markdown bodies. Existing skill and skills calls still fetch one or more full skill body/detail payloads by slug, artifact name, or skill name.

GLOBAL_CONTEXT skills are active context skills and are not meant to be installed per project. PROJECT_INSTALLABLE skills are gallery/installable skills that may be attached globally or to a workspace/path through assignment records; those assignments remain the source of truth for what is active in a catalog response.

Release flow

1. Bump version in plugin/opencode-wizard/package.json.
2. Run npm run plugin:release:check from the repo root.
3. If you are following the repo release-tag convention, create Git tag plugin-opencode-wizard-v<version>.
4. Push the release commit/tag so GitLab can run the shared npm public publish job.

The CI publish job comes from ci/templates/node/npm-publish-public.yml, stays manual on the repo deploy stage, runs from plugin/opencode-wizard via APP_ROOT, builds the package with npm run build --if-present, deletes the inherited @aexol GitLab registry override, and then publishes @aexol/opencode-wizard with npm publish --access public --registry https://registry.npmjs.org/.