@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, always-exposed shared tools, skills.urls guidance, the backend-published wizard global / wizard project / wizard user 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 artifacts remain authenticated and directory-scoped through opencode_wizard_artifact_fetch or compatibility opencode_wizard_published_skills_fetch; same-named native/local seed skill bodies are not authoritative for wizard-listed skills.

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_catalog_fetch, compatibility 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.

The shared plugin tools opencode_wizard_catalog_fetch, opencode_wizard_artifact_fetch, opencode_wizard_artifact_preference_set, compatibility published-skill tools, and opencode_wizard_status are always exposed by the plugin. Missing auth, forbidden role, backend, or catalog problems are reported by tool output/status metadata instead of hiding these shared tools; only opencode_wizard_editor_publish_skill stays editor-only.

Call opencode_wizard_catalog_fetch with artifactKind: SKILL or compatibility 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. Canonical opencode_wizard_artifact_fetch with artifactKind: SKILL and compatibility skill/skills calls fetch one or more full skill body/detail payloads by slug, artifact name, or skill name. DESIGN_DOC uses generic wizard artifact persistence and returns metadata-only catalogs plus explicit DESIGN.md body/files detail fetches for effective assignments. Use the fetched markdownDocument/markdownBody as the authoritative wizard skill body before applying a wizard-listed skill.

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. Try refresh: true and report the tool-output auth/catalog/source/cache/workspace-resolution state before deleting ~/.cache/opencode/*.

Use opencode_wizard_artifact_preference_set or compatibility 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/.