@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 defaults to the deployed backend at https://opencode-wizard.aexol.work for both local path-loaded and packaged plugin usage. Set OPENCODE_WIZARD_BACKEND_ORIGIN explicitly to target a local/backend URL. Generic host APP_URL and PORT are ignored so released plugin usage does not accidentally target placeholder app URLs or the OpenCode host port.

Useful commands:

npm run typecheck
npm run test
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

Catalog discovery uses the backend-issued plugin session token stored at ~/.config/opencode/opencode-wizard.json (auth field); the plugin does not persist or send Microsoft/Entra tokens to GraphQL. If no valid plugin session exists, no-arg opencode_wizard_published_skills_fetch, explicit opencode_wizard_status, TUI status, and chat/system-context startup may start the browser Entra PKCE flow and exchange the callback for a fresh backend-issued plugin session.

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, project, user, and other, 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.

Workspace delivery still follows the backend contract: the plugin sends workspaceSlug when it has one, otherwise falls back to repositoryUrl. The plugin now prefers configured or learned workspace slug mappings over a repo-basename fallback, and learns durable slug-to-repo mappings from successful backend catalog responses so worktrees and nontrivial repo roots stay aligned.

Published skill fetches still support refresh: true, but normal cache entries now self-expire after 30 seconds and fetch/status payloads surface source, workspaceSlug, and workspaceSlugSource so stale-vs-refreshed behavior is visible without relying on manual cache deletion.

Use opencode_wizard_published_skill_preference_set for non-TUI preference actions (install, uninstall, ignore, unignore) against the same server-backed preference API used by the TUI overlay.

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/.