docs: migrate-v1 lists a catalogs plugin context domain that does not exist #55628

Activity

1. opencode-agent commented on Oct 15, 2026

   

   opencode-agentBot

   on Oct 15, 2026 – with OpenCode Agent

   Contributor

   More actions

   Thanks for the detailed report. I was able to reproduce this on 2.0.29.

   The script below starts with a fresh config and loads one local plugin from the global opencode.jsonc. In its setup(), the plugin calls ctx.catalog.transform(...), which is what the migration guide's "catalogs" domain suggests. It then checks GET /api/plugin. The plugin is reported as failed with TypeError: undefined is not an object (evaluating 'ctx.catalog.transform'). The context has no catalog key at all. It has provider, model, command, integration, mcp, reference, skill, storage, vcs, worktree, websearch and others.

   This still happens on the latest dev (7ced591c), and /build/plugins/migrate-v1 there still lists "catalogs". It looks like the catalog domain was split into separate provider and model registries in #48901, and the guide wasn't updated to match.

   As you suggested, ctx.provider.transform / ctx.model.transform look like the current way to publish providers and models from a plugin.

   Reproduction script (repro.sh)

   #!/usr/bin/env bash
   # Repro for #55628: the migrate-v1 guide lists a "catalogs" plugin context domain,
   # but ctx.catalog does not exist, so a plugin calling ctx.catalog.transform() fails to load.
   # Usage: ./repro.sh                                (uses `opencode` from PATH)
   #        OC_DEV=/path/to/opencode-checkout ./repro.sh   (runs from source)
   set -u
   P=$(mktemp -d /tmp/opencode/catalog-probe.XXXX)
   mkdir -p "$P/plugin"
   cat > "$P/plugin/index.ts" <<TS
   import { writeFileSync } from "node:fs"
   export default {
     id: "catalog-probe",
     async setup(ctx: any) {
       writeFileSync("$P/ctx-keys.txt", "ctx keys: " + Object.keys(ctx).sort().join(",") + "\ntypeof ctx.catalog: " + typeof ctx.catalog + "\n")
       // What a plugin trusting the migrate-v1 guide's "catalogs" domain would do:
       await ctx.catalog.transform(() => {})
     },
   }
   TS
   # Isolated HOME; load the plugin from the global config, like the report
   export HOME="$P/home"
   mkdir -p "$HOME/.config/opencode"
   printf '{ "plugins": ["%s"] }\n' "$P/plugin" > "$HOME/.config/opencode/opencode.jsonc"
   cd "$P"
   if [ -n "${OC_DEV:-}" ]; then
     OC=(bun --conditions=browser --preload="$OC_DEV/packages/tui/node_modules/@opentui/solid/scripts/preload.js" "$OC_DEV/packages/cli/src/index.ts")
   else
     OC=(opencode)
   fi
   "${OC[@]}" --version
   export OPENCODE_SERVER_PASSWORD=repro-$RANDOM
   PORT=$((40000 + RANDOM % 20000))
   "${OC[@]}" serve --hostname 127.0.0.1 --port $PORT >"$P/serve.log" 2>&1 &
   SERVE=$!
   for i in $(seq 1 30); do
     out=$("${OC[@]}" api --server http://127.0.0.1:$PORT get /api/plugin 2>/dev/null | tr '{' '\n' | grep -A3 '"id":"catalog-probe"')
     echo "$out" | grep -q '"status":"\(failed\|active\)"' && break
     sleep 2
   done
   echo "--- /api/plugin entry for catalog-probe:"; echo "$out"
   echo "--- from inside setup():"; cat "$P/ctx-keys.txt" 2>/dev/null
   kill $SERVE 2>/dev/null || true

   Run it: bash repro.sh
2. opencode-agent

   added

   reproduced

   on Oct 15, 2026
3. KeenaNet commented on Oct 15, 2026

   

   KeenaNet

   on Oct 15, 2026

   Author

   More actions

   Additional evidence that narrows this down: this is not stale prose in the guide, it is an undocumented rename of a
   first-class domain.

   @opencode-ai/plugin@1.18.18 (the V1 SDK, which also ships a V2 plugin API) types the member explicitly:

   // dist/v2/effect/context.d.ts
   export interface PluginContext {
       readonly options: PluginOptions;
       readonly agent: AgentHooks & Reload;
       readonly aisdk: AISDKHooks;
       readonly catalog: CatalogHooks & Reload;   // present in 1.18.x
       readonly command: CommandHooks & Reload;
       readonly integration: IntegrationHooks & Reload;
       readonly plugin: PluginDomain;
       readonly reference: ReferenceHooks & Reload;
       readonly skill: SkillHooks & Reload;
   }

   // dist/v2/effect/catalog.d.ts
   export interface CatalogDraft {
       readonly provider: {
           list(): readonly CatalogProviderRecord[];
           get(providerID: string): CatalogProviderRecord | undefined;
           update(providerID: string, update: (provider: ProviderV2Info) => void): void;
           remove(providerID: string): void;
       };
       readonly model: {
           get(providerID: string, modelID: string): ModelV2Info | undefined;
           update(providerID: string, modelID: string, update: (model: ModelV2Info) => void): void;
           remove(providerID: string, modelID: string): void;
           readonly default: { get(): ...; set(providerID: string, modelID: string): void; };
       };
   }
   export type CatalogHooks = Hooks<{ transform: CatalogDraft }>;

   @opencode/plugin@2.0.29 has no catalog domain, but its ProviderEditor and ModelEditor carry the same operations
   as CatalogDraft.provider and CatalogDraft.model (plus add), and they are now top-level ctx.provider /
   ctx.model domains with their own transform and reload.

   So ctx.catalog.transform(...) and ctx.catalog.reload() no longer exist under that name — and a plugin author coding
   against the 1.18.x V2 API had a typed ctx.catalog to target.

   What is missing is the migration step. The plugin migration guide jumps from V1 hooks straight to
   ctx.provider.transform / ctx.model.transform without ever mentioning that ctx.catalog was renamed and split, while
   the same guide's prose still lists catalogs as a current context domain.

   Suggested mapping to document:

   1.18.x V2 API	OpenCode 2 / @opencode/plugin
   ctx.catalog.transform(draft => …)	ctx.provider.transform(...) and/or ctx.model.transform(...)
   ctx.catalog.reload()	ctx.provider.reload() / ctx.model.reload()
   draft.provider.update(id, fn)	editor.update(id, fn) on ctx.provider
   draft.model.update(providerID, modelID, fn)	editor.update(providerID, modelID, fn) on ctx.model

   Concrete downstream effect, unchanged from the report: cursor-oauth-opencode@0.22.1 depends on
   @opencode-ai/plugin@^1.2.27, calls ctx.catalog in its V2 entrypoint, and cannot load on OpenCode 2.0.29.