@joe-broadhead/opencode-github 0.0.0 → 0.0.2

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.2] - 2026-11-04
+
+### Fixed
+
+- **Security:** `github_api` checked its permission rules against the path as written, but sent the request to the
+  path after the URL parser removed percent-encoded dot segments such as `.%2e`, `%2e.` and `%2e`. A write could
+  therefore reach another repository or endpoint than the one an allow or deny rule named, and the prompt showed the
+  wrong path. It now refuses a `.` or `..` segment however it is encoded (double encoding too) and a percent-encoded
+  character a path can hold as itself, such as `%6F` for `o`, with `API_PATH_INVALID`, before any prompt or request.
+  The path that rules and the prompt see is exactly the path sent, on GitHub.com and with `host`, for uploads too.
+- **Security:** `github_api` rules could be dodged by case and by redirects. GitHub reads owner and repository names
+  (and organisation, user, team, environment, label, secret and variable names) without regard to case, so a deny on
+  `/repos/owner/prod/*` did not stop `/repos/Owner/Prod/…`. The permission resource now has those names in lower
+  case; write rules that way. The status lists rules with an upper-case owner or repo name, which never match, under
+  "Rules that never match". And a redirect could take a call to a path no rule had checked: a change now never
+  follows one (`API_REDIRECTED`, naming the new path), a read follows one within the API only after the permission
+  check passes for the new path, and a read redirected outside the API fails with `API_REDIRECT_OFF_HOST`. Downloads
+  still follow GitHub's storage redirects without the token. The tools RPC's `api` method does the same.
+- Status listed agents whose own rules already ask for or deny GitHub's tools, such as agents that end with
+  `* * ask`, as agents without default rules. It now lists an agent only when its rules would let a GitHub tool run
+  without asking.
+- Status said "Nothing to do." while it listed agents without default rules. The next step now names them and the
+  fix.
+- `github_api` downloads had no size limit. A download now stops at 2 GiB with `API_DOWNLOAD_TOO_LARGE`, checked
+  against `Content-Length` and while it streams, and the partial file is removed.
+- A `github_api` download without `overwrite` could replace a file created while it ran. It now keeps that file and
+  fails with `API_FILE_EXISTS`.
+- A download to a file that already exists asked for approval first and only then failed. It is now refused before
+  the prompt.
+- The scripting docs said `opencode api` runs in the directory you call it from. It runs in the OpenCode service's
+  default location, your home directory; the docs now say how to target a project. They also say that `opencode api`
+  exits with status 1 on an RPC error, and that a tool with no structured content returns its text as `output`.
+- The README says to run `opencode reload` after install, how to update, and orders Uninstall as sign out, remove,
+  data folders (none) and copied rules. Its sign-out step is `opencode auth logout GitHub <login>`: without the
+  account's label the command needs an interactive terminal, and a token left behind after removing the plugin no
+  longer shows in `opencode auth list`.
+- `/github-status` and the dialog left out the Account and Agents without default rules rows when they were empty,
+  and `/github-status` had no title line. Every row is now shown, with `none` where it is empty, under
+  "GitHub status".
+
+### Changed
+
+- `POST /markdown` and `POST /markdown/raw` through `github_api` are reads: they only render Markdown, so they run
+  without a prompt and also while read-only. Every other POST is still a write.
+- Code Mode shows a description for the `github` namespace, and every `github_api` input field has one.
+- `issue_artifact_read` (a read) and `issue_artifact_write` (a write), which github-mcp-server v2.1.0 adds to the
+  `issues` toolset behind a feature flag the plugin does not turn on, are known tools.
+- A script's `TOOL_UNAVAILABLE` next step names the toolsets that are off by default, and says to add the method's
+  toolset to `toolsets` and run `opencode reload`.
+- The tools RPC's shared module is updated: `describe` given any input but nothing or `{}` answers
+  `describe takes no input`, an envelope that is not an object gets a plain message, a permission refusal names the
+  action that was refused, and a server that reconnects during a call gives `CONNECTING` instead of
+  `CONNECTION_FAILED`.
+- OpenCode 2.2.5 is a tested release. The status calls 2.2.3, 2.2.4 and 2.2.5 tested, and a later 2.2 release
+  "untested; supported range >=2.2.3 <2.3.0". `HOST_UNTESTED` and the `allowUntestedHost` warning now say "outside
+  the supported range".
+- The status RPC (`github.platform`) has the fields every plugin of this family shares
+  ([Scripting](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/scripting.md#status)):
+  - new `version`, the plugin's version;
+  - `host` is `{ version, range, tested }`; `host.warning` is now `hostWarning`;
+  - `state` values: `needs_auth` is now `sign_in_required`, `pending` is now `connecting`, and `not_registered` is
+    now `not_configured`.
+
+## [0.0.1] - 2026-11-03
+
+### Added
+
+- The tools RPC, `github.platform.tools`: a script can call GitHub's known MCP reads, and `api` (`github_api` limited
+  to REST GET and HEAD and single GraphQL queries), with no model, through `opencode api`, as a session and its agent.
+  It gets exactly the access that agent's model has: a tool its rules hide is refused, OpenCode checks each MCP call
+  against the agent's and the session's rules, and an ask is refused at once because no one is there to answer it.
+  `describe` lists the methods with each tool's live input schema. GitHub's writes, `ui_get` and any tool GitHub adds
+  later are never methods, and `api` refuses changes, downloads and uploads with `SCRIPT_READ_ONLY` before any
+  request. With `host` (GitHub Enterprise Server) only `api` runs. `docs/scripting.md` explains it.
+
+### Changed
+
+- `check_dependency_vulnerabilities`, which GitHub's hosted server now lists in the `dependabot` toolset, is a known
+  read: it looks up a list of packages in the GitHub Advisory Database and changes nothing, so it runs without a
+  prompt, and `/github-status` no longer lists it as unknown.
+
 ## [0.0.0] - 2026-11-01
 
 ### Added

package/README.md

@@ -7,8 +7,9 @@ Unofficial; not affiliated with GitHub. GitHub is a trademark of GitHub, Inc.
 
 ## Requirements
 
-- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3 and 2.2.4. On any other release the plugin refuses to load (see
-  [`allowUntestedHost`](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/configuration.md#allowuntestedhost)).
+- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5. A later 2.2 release loads too, and the status marks it
+  untested. Outside `>=2.2.3 <2.3.0` the plugin does not load, unless you set
+  [`allowUntestedHost`](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/configuration.md#allowuntestedhost).
 - macOS or Linux.
 - A GitHub account.
 
@@ -18,7 +19,14 @@ Unofficial; not affiliated with GitHub. GitHub is a trademark of GitHub, Inc.
 opencode plugin add @joe-broadhead/opencode-github
 ```
 
-Restart OpenCode. `opencode mcp list` then shows `github  needs authentication` until you sign in.
+Run `opencode reload`, or restart OpenCode. Then run `/github-status`: it shows `Connection: sign-in required` until
+you sign in, and `opencode mcp list` shows `github  needs authentication`.
+
+### Update
+
+Update with `opencode plugin update @joe-broadhead/opencode-github`, then run `opencode reload`. Your options and
+rules stay as they are. An entry pinned to a version (`@joe-broadhead/opencode-github@0.0.1`) does not update: remove
+the `@<version>` from its `plugins` entry first.
 
 ## Sign in
 
@@ -52,7 +60,8 @@ permissions above.
 A fine-grained token reaches only the repositories you select, and GitHub enforces that. For writes
 (`readOnly: false`), give the token write access to what those tools change, for example Issues or Pull requests.
 
-To sign out, run `opencode auth logout GitHub`, or remove the account in `/connect` → **GitHub**.
+To sign out, run `opencode auth logout GitHub <login>`, where `<login>` is the account's label, your GitHub login,
+or remove the account in `/connect` → **GitHub**.
 
 ## Use
 
@@ -69,8 +78,9 @@ branch protection, rulesets, Actions variables, downloading artifacts and logs t
 GitHub's REST or GraphQL API with your GitHub sign-in, for example
 `{ "method": "GET", "path": "/repos/OWNER/REPO/branches/main/protection" }` or
 `{ "graphql": { "query": "query { viewer { login } }" } }`. GET, HEAD and a single GraphQL query read; every other
-call changes GitHub, asks first, and is refused while the plugin is read-only. Requests go only to GitHub's API; a
-redirect to file storage is followed without your token. `download: { path }` saves a response to a file in the
+call changes GitHub, asks first, and is refused while the plugin is read-only. Requests go only to GitHub's API. A
+change never follows a redirect; a read follows one within the API only after asking for the new path, and only a
+download follows one to GitHub's file storage, without your token. `download: { path }` saves a response to a file in the
 project, and `upload: { path, contentType }` sends a project file as a release asset; both ask first.
 
 Three skills come with it:
@@ -82,6 +92,17 @@ Three skills come with it:
 
 Each skill reports findings and changes nothing on GitHub unless you ask.
 
+**Scripts.** A script or a cron job can call GitHub's read tools and `github_api`'s reads with no model, through
+`opencode api`. It runs as a session and its agent, under that agent's permission rules and the session's own.
+Scripts can never change anything on GitHub:
+
+```sh
+opencode api post /api/rpc/github.platform.tools/pull_request_read \
+  -d '{"input":{"sessionID":"ses_…","input":{"method":"get","owner":"OWNER","repo":"REPO","pullNumber":42}}}'
+```
+
+See [Scripting](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/scripting.md).
+
 **Status.** `/github` in the TUI, or **GitHub: Status** in the command palette, opens a dialog with the state, the
 account and access, the tools (with the names of any the plugin does not know yet), the agents that miss the default
 rules with the rules to paste, the OpenCode check and the next step. `r` refreshes it and `Esc` closes it. It also
@@ -111,13 +132,16 @@ Your own rules and saved approvals still win:
   ```
 
   Every rule needs a `"resource"`. OpenCode skips a rule without it.
-- `github_api` rules match `METHOD /path`, and `*` matches any text, slashes included. This lets the agent change one
-  owner's repositories without a prompt, and never delete anything:
+- `github_api` rules match `METHOD /path`, and `*` matches any text, slashes included. **Write owner and repo names
+  in lower case**: GitHub reads them without regard to case, so the plugin checks `/repos/Owner/Prod/…` as
+  `/repos/owner/prod/…`, and a rule with an upper-case name never matches (the status warns about it). The same holds
+  for organisation, user and team names, and environment, label, secret and variable names. This lets the agent change
+  one owner's repositories without a prompt, and never delete anything:
 
   ```json
   {
     "permissions": [
-      { "action": "github_api", "resource": "POST /repos/OWNER/*", "effect": "allow" },
+      { "action": "github_api", "resource": "POST /repos/my-org/*", "effect": "allow" },
       { "action": "github_api", "resource": "DELETE *", "effect": "deny" }
     ]
   }
@@ -204,7 +228,7 @@ overrides user and project config, so members only sign in:
 ## Troubleshooting
 
 `/github-status` and the `/github` dialog show the rows Connection, Account, Access, Toolsets, Host, Tools, Agents
-without default rules, OpenCode and Next step. The Connection row and its next step:
+without default rules, OpenCode and Next step, with `none` where a row is empty. The Connection row and its next step:
 
 | Connection | Next step |
 | --- | --- |
@@ -216,14 +240,22 @@ without default rules, OpenCode and Next step. The Connection row and its next s
 | `not configured` | Restart OpenCode. If GitHub is still missing, check that no other plugin removes the MCP server named github. |
 | `conflict` | Your OpenCode config or another plugin defines its own MCP server named github, so this plugin left it unchanged. Rename or remove that server to use this plugin's GitHub sign-in. |
 
+A **Rules that never match** row lists `github_api` rules with an upper-case owner or repo name (see
+[Permissions](#permissions)), and the next step gives the lower-case form. Otherwise, when the connection needs
+nothing, the next step names the agents without default rules and how to fix them (see
+[Permissions](#permissions)); on an untested OpenCode release it names the tested ones. Otherwise it is "Nothing to do."
+
 Error codes:
 
 | Code | What to do |
 | --- | --- |
-| `HOST_UNTESTED` | OpenCode is outside `>=2.2.3 <2.3.0`. Update OpenCode or the plugin, or set the option `allowUntestedHost: true` to load it anyway, with a warning in the status. |
+| `HOST_UNTESTED` | OpenCode is outside the supported range `>=2.2.3 <2.3.0`. Update OpenCode or the plugin, or set the option `allowUntestedHost: true` to load it anyway, with a warning in the status. |
 | `OPTIONS_INVALID` | An option is unknown or has a wrong value; the message names it. Fix that option for the plugin in `opencode.json`. |
 | `SIGN_IN_…`, `TOKEN_…`, `DEVICE_…`, `CLIENT_ID_UNKNOWN` | Sign-in failed. The message ends with the next step; [the error codes](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/configuration.md#errors) list them all. |
 
+A script's errors from the tools RPC have their own codes, listed in
+[Scripting](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/scripting.md#errors).
+
 Other problems:
 
 | You see | What to do |
@@ -236,15 +268,24 @@ Other problems:
 
 ## Uninstall
 
-1. Sign out: `opencode auth logout GitHub`.
-2. Run `opencode plugin remove @joe-broadhead/opencode-github`, and remove any default rules you copied into agents.
-3. On GitHub, delete the token under **Settings → Developer settings → Personal access tokens**, or, after a device
-   sign-in, revoke the OAuth App under **Settings → Applications → Authorized OAuth Apps**.
+Sign out first: once the plugin is removed, `opencode auth list` no longer shows the GitHub sign-in, but OpenCode
+still stores its token.
+
+1. Sign out: `opencode auth logout GitHub <login>`, where `<login>` is the account's label in `/connect`, your GitHub
+   login (with `host`: `opencode auth logout "GitHub Enterprise" <login>`). Without `<login>` it asks you to pick the
+   account, which works only in an interactive terminal. Then, on GitHub, delete the token under **Settings →
+   Developer settings → Personal access tokens**, or, after a device sign-in, revoke the OAuth App under **Settings →
+   Applications → Authorized OAuth Apps**.
+2. Run `opencode plugin remove @joe-broadhead/opencode-github`, then `opencode reload`.
+3. Data folders: none. The plugin stores nothing of its own.
+4. Remove the default rules you copied into agents' own `permissions`.
 
 ## Links
 
 - [Configuration](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/configuration.md): options,
   toolsets, permission rules and error codes.
+- [Scripting](https://github.com/joe-broadhead/opencode-github/blob/HEAD/docs/scripting.md): calling GitHub's reads
+  from scripts, with no model.
 - [Security](https://github.com/joe-broadhead/opencode-github/blob/HEAD/SECURITY.md): network endpoints,
   credentials, untrusted content and reporting a vulnerability.
 - [Contributing](https://github.com/joe-broadhead/opencode-github/blob/HEAD/CONTRIBUTING.md): development, checks