opencode-ext-connector 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +34 -15
  3. package/docs/README.ko.md +34 -15
  4. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,18 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.3 - 2026-09-06
4
+
5
+ - Document official npm package installation through OpenCode's `plugin` field,
6
+ including pinned installs, deterministic updates, and removal guidance
7
+ - Maintain active branch history by removing obsolete commit attribution
8
+ trailers while preserving source trees; existing published tags and
9
+ provenance remain unchanged
10
+ - Exercise package loading through the exact npm package spec from an isolated
11
+ offline OpenCode cache with no registry access
12
+ - Harden npm publishing with immutable action and toolchain pins, a no-OIDC
13
+ verification job, and a checksummed tarball-only OIDC publish job
14
+ - Keep provider and runtime behavior unchanged
15
+
3
16
  ## 0.3.2 - 2026-09-06
4
17
 
5
18
  - Remove the obsolete npm token fallback so releases publish only through
package/README.md CHANGED
@@ -13,13 +13,13 @@
13
13
 
14
14
  **English** · [한국어](docs/README.ko.md) · [Documentation](#documentation)
15
15
 
16
- [Status](#status) · [Requirements](#requirements) · [Quick Install](#quick-install) · [Configuration](#configuration) · [First-Time Connection](#first-time-connection) · [Providers](#providers) · [Troubleshooting](#troubleshooting) · [Documentation](#documentation) · [Testing](#testing) · [License and Disclaimer](#license-and-disclaimer)
16
+ [Status](#status) · [Requirements](#requirements) · [Quick Install](#quick-install) · [Configuration](#configuration) · [Update and Remove](#update-and-remove) · [First-Time Connection](#first-time-connection) · [Providers](#providers) · [Troubleshooting](#troubleshooting) · [Documentation](#documentation) · [Testing](#testing) · [License and Disclaimer](#license-and-disclaimer)
17
17
 
18
18
  </div>
19
19
 
20
20
  ## Status
21
21
 
22
- > Independent unofficial community plugin, version **0.3.2**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
22
+ > Independent unofficial community plugin, version **0.3.3**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
23
23
 
24
24
  Reuse the Claude, Cursor, Command Code, and Ollama sessions you already have. One `opencode.json` plugin entry publishes live catalogs into OpenCode. Claude and Cursor stay disconnected until OpenCode has a marker or OAuth record and the vendor session is present. Command Code may use an OpenCode-stored direct API key or an existing CLI session/key. Ollama requires the exact session marker plus a responsive localhost daemon.
25
25
 
@@ -39,31 +39,33 @@ No vendor CLI has to be installed where OpenCode runs. Claude and Command Code r
39
39
 
40
40
  ## Quick Install
41
41
 
42
- Build this repository, then point OpenCode at the compiled module:
42
+ Choose either the global `~/.config/opencode/opencode.json` or project-level `opencode.json`, then add the package to the official singular `plugin` field:
43
43
 
44
- ```bash
45
- bun install
46
- bun run build
44
+ ```jsonc
45
+ {
46
+ "$schema": "https://opencode.ai/config.json",
47
+ "plugin": [
48
+ "opencode-ext-connector"
49
+ ]
50
+ }
47
51
  ```
48
52
 
49
- In `opencode.json` / `opencode.jsonc` (official `plugin` field):
53
+ OpenCode installs configured npm plugins with Bun at startup and caches them. For a reproducible installation, use an exact published version instead:
50
54
 
51
55
  ```jsonc
52
56
  {
53
57
  "$schema": "https://opencode.ai/config.json",
54
- "plugin": [
55
- "file:///absolute/path/to/opencode-ext-connector/dist/index.js"
56
- ]
58
+ "plugin": ["opencode-ext-connector@0.3.3"]
57
59
  }
58
60
  ```
59
61
 
60
- Use that direct `dist/index.js` URL from a trusted, user-owned `file://` build. A package-directory URL does not load this connector's named legacy auth hooks.
62
+ Fully quit and restart OpenCode after adding or changing the entry; a reload is not enough.
61
63
 
62
64
  The one package entry exposes the catalog plugin plus the Claude, Cursor, Command Code, and Ollama auth hooks. Provider ids: `claude`, `cursor`, `command-code`, `ollama`. Model ids come from each provider's live catalog, with documented fallbacks `default` (Cursor) and `Qwen/Qwen3.8-Max` (Command Code) when a live list is empty.
63
65
 
64
66
  ## Configuration
65
67
 
66
- OpenCode passes plugin options as the second item of a two-element tuple.
68
+ OpenCode passes plugin options as the second item of a two-element tuple. Use the npm package name as the first item.
67
69
 
68
70
  Omitted `providers` enables all four. An explicit list is a strict allow-list. Explicit `[]` disables all.
69
71
 
@@ -85,7 +87,7 @@ Writeback is off by default so this plugin does not mutate credential stores unl
85
87
  "$schema": "https://opencode.ai/config.json",
86
88
  "plugin": [
87
89
  [
88
- "file:///absolute/path/to/opencode-ext-connector/dist/index.js",
90
+ "opencode-ext-connector",
89
91
  {
90
92
  "writeBackCredentials": true
91
93
  }
@@ -112,9 +114,26 @@ Anthropic rotates the refresh token on every refresh and invalidates the previou
112
114
 
113
115
  Machines that refresh on their own — including a Claude Code install that is used interactively — must not share the file. Log in separately there.
114
116
 
117
+ ## Update and Remove
118
+
119
+ To update deterministically, check the desired published version, replace the `plugin` entry with that exact spec, then fully restart OpenCode:
120
+
121
+ ```bash
122
+ npm view opencode-ext-connector version
123
+ ```
124
+
125
+ ```jsonc
126
+ {
127
+ "$schema": "https://opencode.ai/config.json",
128
+ "plugin": ["opencode-ext-connector@<version>"]
129
+ }
130
+ ```
131
+
132
+ Do not rely on an unpinned entry to refresh its cached package automatically on restart. To remove the connector, remove its entry from `plugin` and fully restart OpenCode. Cached package files are inert when the package is not configured.
133
+
115
134
  ## First-Time Connection
116
135
 
117
- 1. **Fully restart OpenCode** after adding the plugin URL. Quit the process and start it again so the named legacy auth hooks load. A reload or periodic catalog refresh is not instance reconstruction.
136
+ 1. **Fully restart OpenCode** after adding the npm package entry or version spec. Quit the process and start it again so the named legacy auth hooks load. A reload or periodic catalog refresh is not instance reconstruction.
118
137
  2. **Confirm local prerequisites** for the providers you enabled. Claude and Cursor need their vendor sessions. Command Code needs either an API key you will store in OpenCode or an existing CLI session/key. Ollama needs a process you trust on `http://localhost:11434`; Cloud still requires a separate `ollama signin`.
119
138
  3. **Run `/connect`** for each provider you want. Claude and Cursor record a marker or OAuth entry only after the vendor session is available. Command Code can store a direct API key in OpenCode or reuse an existing CLI session/key. Ollama stores the exact session marker only when the localhost daemon responds. Models publish only after that provider-specific rule is met.
120
139
  4. **Verify the catalogs.** Confirm Claude, Cursor, and Command Code models appear in OpenCode. For Ollama, run `opencode models ollama` and confirm locally pulled models plus Cloud tags discovered unauthenticated, without connector-supplied credentials.
@@ -138,7 +157,7 @@ The standalone SDK entry is `opencode-ext-connector/ollama`. It can generate wit
138
157
 
139
158
  | Symptom | What to check |
140
159
  | --- | --- |
141
- | `/connect` methods missing | The plugin URL must be a trusted, user-owned `file:///absolute/path/to/opencode-ext-connector/dist/index.js`. A package-directory URL does not load named legacy auth hooks. Fully restart OpenCode after changing it. |
160
+ | `/connect` methods missing | Confirm `plugin` contains `"opencode-ext-connector"` or an exact published `"opencode-ext-connector@<version>"` spec, then fully restart OpenCode. |
142
161
  | Provider enabled but no models | Omitted `providers` enables all four; an explicit list is a strict allow-list. Claude and Cursor need a marker or OAuth record plus the vendor session; Command Code may use an OpenCode-stored API key or a CLI session/key; Ollama needs the exact marker plus a responsive localhost daemon. Fully restart after `/connect` so instance reconstruction picks up new membership. |
143
162
  | Claude works until the next start | Default `writeBackCredentials: false` keeps refreshed tokens in memory. A rotated refresh token then fails on the next process start unless writeback is enabled. |
144
163
  | Claude reports `invalid_grant` on a copied credential file | Another copy of the same login already refreshed and rotated the refresh token. Give one machine ownership of refresh and set `credentialRefresh: { mode: "never" }` on the others, or log in separately. |
package/docs/README.ko.md CHANGED
@@ -13,13 +13,13 @@
13
13
 
14
14
  [English](../README.md) · **한국어** · [문서](#문서)
15
15
 
16
- [상태](#상태) · [요구 사항](#요구-사항) · [빠른 설치](#빠른-설치) · [설정](#설정) · [최초 연결](#최초-연결) · [프로바이더](#프로바이더) · [문제 해결](#문제-해결) · [문서](#문서) · [테스트](#테스트) · [라이선스 및 면책 조항](#라이선스-및-면책-조항)
16
+ [상태](#상태) · [요구 사항](#요구-사항) · [빠른 설치](#빠른-설치) · [설정](#설정) · [업데이트 및 제거](#업데이트-및-제거) · [최초 연결](#최초-연결) · [프로바이더](#프로바이더) · [문제 해결](#문제-해결) · [문서](#문서) · [테스트](#테스트) · [라이선스 및 면책 조항](#라이선스-및-면책-조항)
17
17
 
18
18
  </div>
19
19
 
20
20
  ## 상태
21
21
 
22
- > 독립적인 비공식 커뮤니티 플러그인, 버전 **0.3.2**. CI에 설치된 OpenCode CLI를 대상으로 legacy multi-function 로더를 패키지 E2E 테스트로 검증합니다. `@opencode-ai/plugin@1.18.18`은 컴파일 시 사용하는 플러그인 API 대상이며 OpenCode 런타임 버전 고정이 아닙니다. 소스는 BSD-3-Clause입니다. 이 프로젝트는 OpenCode 또는 어떤 프로바이더와도 제휴, 보증, 후원, 승인 관계가 없습니다. 전체 조건은 [라이선스 및 면책 조항](#라이선스-및-면책-조항)에 있습니다.
22
+ > 독립적인 비공식 커뮤니티 플러그인, 버전 **0.3.3**. CI에 설치된 OpenCode CLI를 대상으로 legacy multi-function 로더를 패키지 E2E 테스트로 검증합니다. `@opencode-ai/plugin@1.18.18`은 컴파일 시 사용하는 플러그인 API 대상이며 OpenCode 런타임 버전 고정이 아닙니다. 소스는 BSD-3-Clause입니다. 이 프로젝트는 OpenCode 또는 어떤 프로바이더와도 제휴, 보증, 후원, 승인 관계가 없습니다. 전체 조건은 [라이선스 및 면책 조항](#라이선스-및-면책-조항)에 있습니다.
23
23
 
24
24
  이미 가지고 있는 Claude, Cursor, Command Code, Ollama 세션을 재사용합니다. `opencode.json` 플러그인 항목 하나가 라이브 카탈로그를 OpenCode에 공개합니다. Claude와 Cursor는 OpenCode에 마커 또는 OAuth 레코드가 있고 벤더 세션이 있을 때까지 연결되지 않은 상태로 유지됩니다. Command Code는 OpenCode에 저장된 직접 API 키 또는 기존 CLI 세션/키를 사용할 수 있습니다. Ollama는 정확한 세션 마커와 응답하는 localhost 데몬이 필요합니다.
25
25
 
@@ -39,31 +39,33 @@ OpenCode가 실행되는 곳에 벤더 CLI를 설치할 필요가 없습니다.
39
39
 
40
40
  ## 빠른 설치
41
41
 
42
- 이 저장소를 빌드한 뒤, 컴파일된 모듈을 OpenCode에 지정합니다:
42
+ 전역 `~/.config/opencode/opencode.json` 또는 프로젝트 수준 `opencode.json` 중 하나를 선택한 뒤, 공식 단수 `plugin` 필드에 패키지를 추가하십시오:
43
43
 
44
- ```bash
45
- bun install
46
- bun run build
44
+ ```jsonc
45
+ {
46
+ "$schema": "https://opencode.ai/config.json",
47
+ "plugin": [
48
+ "opencode-ext-connector"
49
+ ]
50
+ }
47
51
  ```
48
52
 
49
- `opencode.json` / `opencode.jsonc` (공식 `plugin` 필드):
53
+ OpenCode는 시작 시 Bun으로 설정된 npm 플러그인을 설치하고 캐시합니다. 재현 가능한 설치가 필요하면 정확한 공개 버전을 대신 사용하십시오:
50
54
 
51
55
  ```jsonc
52
56
  {
53
57
  "$schema": "https://opencode.ai/config.json",
54
- "plugin": [
55
- "file:///absolute/path/to/opencode-ext-connector/dist/index.js"
56
- ]
58
+ "plugin": ["opencode-ext-connector@0.3.3"]
57
59
  }
58
60
  ```
59
61
 
60
- 신뢰할 수 있는, 사용자가 소유한 `file://` 빌드의 직접 `dist/index.js` URL을 사용하십시오. 패키지 디렉터리 URL은 이 커넥터의 named legacy auth hook을 로드하지 않습니다.
62
+ 항목을 추가하거나 변경한 뒤 OpenCode를 완전히 종료하고 다시 시작하십시오. 리로드만으로는 충분하지 않습니다.
61
63
 
62
64
  패키지 항목 하나가 카탈로그 플러그인과 Claude, Cursor, Command Code, Ollama 인증 hook을 노출합니다. 프로바이더 id: `claude`, `cursor`, `command-code`, `ollama`. 모델 id는 각 프로바이더의 라이브 카탈로그에서 가져오며, 라이브 목록이 비어 있으면 문서화된 fallback은 Cursor의 `default`와 Command Code의 `Qwen/Qwen3.8-Max`입니다.
63
65
 
64
66
  ## 설정
65
67
 
66
- OpenCode는 플러그인 옵션을 두 요소 튜플의 두 번째 항목으로 전달합니다.
68
+ OpenCode는 플러그인 옵션을 두 요소 튜플의 두 번째 항목으로 전달합니다. 첫 번째 항목에는 npm 패키지 이름을 사용하십시오.
67
69
 
68
70
  `providers`를 생략하면 네 프로바이더가 모두 활성화됩니다. 명시적 목록은 엄격한 allow-list입니다. 명시적 `[]`는 모두 비활성화합니다.
69
71
 
@@ -85,7 +87,7 @@ writeback은 기본적으로 꺼져 있어, 요청하지 않는 한 이 플러
85
87
  "$schema": "https://opencode.ai/config.json",
86
88
  "plugin": [
87
89
  [
88
- "file:///absolute/path/to/opencode-ext-connector/dist/index.js",
90
+ "opencode-ext-connector",
89
91
  {
90
92
  "writeBackCredentials": true
91
93
  }
@@ -112,9 +114,26 @@ Anthropic은 갱신할 때마다 refresh 토큰을 회전시키고 이전 토큰
112
114
 
113
115
  대화형으로 사용하는 Claude Code 설치처럼 스스로 갱신하는 머신은 파일을 공유하면 안 됩니다. 그곳에서는 별도로 로그인하십시오.
114
116
 
117
+ ## 업데이트 및 제거
118
+
119
+ 결정론적으로 업데이트하려면 원하는 공개 버전을 확인하고 `plugin` 항목을 해당 정확한 spec으로 바꾼 뒤 OpenCode를 완전히 재시작하십시오:
120
+
121
+ ```bash
122
+ npm view opencode-ext-connector version
123
+ ```
124
+
125
+ ```jsonc
126
+ {
127
+ "$schema": "https://opencode.ai/config.json",
128
+ "plugin": ["opencode-ext-connector@<version>"]
129
+ }
130
+ ```
131
+
132
+ 고정하지 않은 항목이 재시작 시 캐시된 패키지를 자동으로 갱신한다고 기대하지 마십시오. 커넥터를 제거하려면 `plugin`에서 해당 항목을 삭제하고 OpenCode를 완전히 재시작하십시오. 패키지가 설정되어 있지 않으면 캐시된 패키지 파일은 비활성입니다.
133
+
115
134
  ## 최초 연결
116
135
 
117
- 1. 플러그인 URL을 추가한 뒤 **OpenCode를 완전히 재시작**하십시오. 프로세스를 종료한 다음 다시 시작해야 named legacy auth hook이 로드됩니다. 리로드나 주기적 카탈로그 갱신은 인스턴스 재생성이 아닙니다.
136
+ 1. npm 패키지 항목 또는 버전 spec을 추가한 뒤 **OpenCode를 완전히 재시작**하십시오. 프로세스를 종료한 다음 다시 시작해야 named legacy auth hook이 로드됩니다. 리로드나 주기적 카탈로그 갱신은 인스턴스 재생성이 아닙니다.
118
137
  2. 활성화한 프로바이더의 **로컬 전제 조건을 확인**하십시오. Claude와 Cursor는 벤더 세션이 필요합니다. Command Code는 OpenCode에 저장할 API 키 또는 기존 CLI 세션/키가 필요합니다. Ollama는 `http://localhost:11434`에서 신뢰하는 프로세스가 필요하며, Cloud는 별도로 `ollama signin`이 여전히 필요합니다.
119
138
  3. 원하는 각 프로바이더에 대해 **`/connect`를 실행**하십시오. Claude와 Cursor는 벤더 세션이 사용 가능할 때만 마커 또는 OAuth 항목을 기록합니다. Command Code는 OpenCode에 직접 API 키를 저장하거나 기존 CLI 세션/키를 재사용할 수 있습니다. Ollama는 localhost 데몬이 응답할 때만 정확한 세션 마커를 저장합니다. 모델은 그 프로바이더별 규칙이 충족된 뒤에만 공개됩니다.
120
139
  4. **카탈로그를 확인**하십시오. Claude, Cursor, Command Code 모델이 OpenCode에 나타나는지 확인합니다. Ollama는 `opencode models ollama`를 실행하여 로컬로 pull된 모델과, 커넥터가 자격 증명을 제공하지 않은 채 비인증으로 발견된 Cloud 태그를 확인하십시오.
@@ -138,7 +157,7 @@ Ollama `/connect`는 로컬 데몬을 조사하고 정확한 세션 마커를
138
157
 
139
158
  | 증상 | 확인할 것 |
140
159
  | --- | --- |
141
- | `/connect` 메서드가 없음 | 플러그인 URL은 신뢰할 수 있는, 사용자가 소유한 `file:///absolute/path/to/opencode-ext-connector/dist/index.js`여야 합니다. 패키지 디렉터리 URL은 named legacy auth hook을 로드하지 않습니다. 변경한 뒤 OpenCode를 완전히 재시작하십시오. |
160
+ | `/connect` 메서드가 없음 | `plugin`에 `"opencode-ext-connector"` 또는 정확한 공개 `"opencode-ext-connector@<version>"` spec이 있는지 확인한 뒤 OpenCode를 완전히 재시작하십시오. |
142
161
  | 프로바이더가 활성화됐지만 모델이 없음 | `providers`를 생략하면 네 프로바이더가 모두 활성화됩니다. 명시적 목록은 엄격한 allow-list입니다. Claude와 Cursor는 마커 또는 OAuth 레코드와 벤더 세션이 필요하고, Command Code는 OpenCode에 저장된 API 키 또는 CLI 세션/키를 사용할 수 있으며, Ollama는 정확한 마커와 응답하는 localhost 데몬이 필요합니다. `/connect` 후 완전히 재시작해야 인스턴스 재생성이 새 소속을 반영합니다. |
143
162
  | Claude가 다음 시작 전까지만 동작함 | 기본 `writeBackCredentials: false`는 갱신된 토큰을 메모리에만 둡니다. 회전된 refresh 토큰은 writeback을 켜지 않으면 다음 프로세스 시작에서 실패합니다. |
144
163
  | 복사한 자격 증명 파일에서 Claude가 `invalid_grant`를 보고함 | 같은 로그인의 다른 사본이 이미 갱신해서 refresh 토큰이 회전됐습니다. 한 머신에만 갱신 소유권을 주고 나머지에는 `credentialRefresh: { mode: "never" }`를 설정하거나, 별도로 로그인하십시오. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-ext-connector",
3
- "version": "0.3.2",
3
+ "version": "0.3.3",
4
4
  "description": "External provider connector for OpenCode",
5
5
  "type": "module",
6
6
  "license": "BSD-3-Clause",