@joe-broadhead/opencode-linear 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 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.3] - 2026-11-04
+
+### Added
+
+- `linear_issues`, the plugin's own tool: the Linear issues assigned to you, in any state, as a table of identifier,
+  title, state, priority and link (25 rows by default, at most 100). It reads them through Linear's `list_issues`,
+  holds no credential, and runs without asking, through a new default rule
+  `{ "action": "linear_issues", "resource": "*", "effect": "allow" }`. It is a direct tool, offered even when Code
+  Mode holds Linear's other tools, so that Jelly can draw its result as a table. It is not a method of the tools RPC.
+  Its errors are `AUTH_REQUIRED` and `UPSTREAM_UNREADABLE`, documented in the configuration guide.
+- `/linear-status` and the status RPC count `linear_issues` among the Linear tools, never as an unknown one.
+- A `jelly` section in `package.json` for [Jelly](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/docs/jelly.md): the plugin's title, each of its 78 tools with its
+  permission, default effect and whether it only reads, the skills, the sign-in, a table card for `linear_issues`, and
+  a "My Linear issues" Home feed that refreshes every 15 minutes. Jelly reads it without loading the plugin.
+
+## [0.0.2] - 2026-11-04
+
+### Added
+
+- OpenCode 2.2.5 is a tested release, next to 2.2.3 and 2.2.4.
+- Code Mode's catalog now describes the `linear` namespace: what Linear's tools do, whether changes are available and
+  ask first, and that Linear content is untrusted.
+- The status RPC has `version`, the plugin's version, and `host.range`, the supported range.
+- The status RPC declares the error `unavailable`. When status cannot be read, it answers
+  `STATUS_UNAVAILABLE: Could not read Linear's status (…).` with a next step, instead of OpenCode's bare error, and the
+  `/linear` dialog shows both.
+
+### Changed
+
+- The status RPC (`linear.workspace` `status`) uses the field names every plugin of this family shares. Scripts that
+  read it need these changes:
+  - `connection` is now `state`, with the shared states: `pending` is now `connecting`, `needs_sign_in` is now
+    `sign_in_required`, and a `linear` server at another URL than your `access` uses is now `conflict`;
+  - `agentsWithoutRules` is now `unguardedAgents`;
+  - `host.warning` is gone, and the `OpenCode` row says why an untested host runs; `host.version` is `null` when
+    OpenCode reports no version; `host.tested` is true only for 2.2.3, 2.2.4 and 2.2.5;
+  - `unknownTools` holds at most 20 names, only those made of lowercase letters, digits and `_`, and the new
+    `unknownCount` counts every unknown tool;
+  - `error` is set only for a failed connection: OpenCode's reason on one line of at most 160 characters, with any URL
+    cut before its query. Status no longer shows OpenCode's text for a needed sign-in, which can hold an
+    authorization URL.
+- On a release inside `>=2.2.3 <2.3.0` other than 2.2.3, 2.2.4 and 2.2.5, Linear starts as before, and status calls
+  the version untested. The `OpenCode` row reads, for example, `2.2.5 (tested; supported range >=2.2.3 <2.3.0)`.
+- `HOST_UNTESTED`'s next step is now `Use OpenCode >=2.2.3 <2.3.0, or set the plugin option "allowUntestedHost": true
+  to run anyway.`
+- While agents lack the default rules, the next step says the whole fix: put the block first in each listed agent's
+  own `permissions`, followed by your top-level rules for `linear_*` tools. Scripts reading only `nextStep` get it too.
+- The tools RPC's `describe` accepts only `{}` or nothing, and otherwise answers `describe takes no input`. An envelope
+  that is not an object gets one plain message, a refusal names the action that was refused, and a call during which
+  Linear reconnects answers `CONNECTING` instead of `CONNECTION_FAILED`. `docs/scripting.md` lists the envelope
+  messages.
+
+### Fixed
+
+- Linear's read-only server no longer lists `whoami`, but the plugin still counted it as one of 42 known reads: the
+  tools RPC's `whoami` method always answered `TOOL_UNAVAILABLE`, and the `linear` skill told the model to call it.
+  The known reads are now exactly the 41 tools that server lists, so `whoami` is no longer a method of the tools RPC
+  or allowed by the default rules; if Linear serves it again, it asks before it runs. The skill and the docs use
+  `get_user` with `query` `"me"` for the signed-in user, and `describe` shows which methods the server for your access
+  lists now.
+- The README's Uninstall steps failed: once the plugin was removed and OpenCode reloaded, `opencode mcp logout linear`
+  answered "MCP server not found", and the sign-ins stayed in OpenCode's credential store, including the other
+  access's, which that command never reaches. Uninstall now signs out first, of both accesses, checks with
+  `opencode auth list`, then removes the plugin.
+- The README now says what to do after `opencode plugin add` (run `opencode reload`, then `/linear-status`) and how to
+  update the plugin.
+- `docs/scripting.md` said `opencode api` runs in the directory you call it from. It runs in the OpenCode service's
+  default location, your home directory; the doc now says how to target a project. It also says that `opencode api`
+  exits with status 1 for an RPC error, and that a result with only text has that text as its `output`.
+
 ## [0.0.1] - 2026-11-03
 
 ### Added

package/README.md

@@ -7,7 +7,8 @@ Unofficial; not affiliated with Linear.
 
 ## Requirements
 
-- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3 and 2.2.4.
+- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5. Outside that range the plugin does not start, unless
+  you set `allowUntestedHost`.
 - macOS or Linux.
 - A Linear account.
 
@@ -17,9 +18,22 @@ Unofficial; not affiliated with Linear.
 opencode plugin add @joe-broadhead/opencode-linear
 ```
 
-Restart OpenCode if it is running. The plugin registers Linear's MCP server under the name `linear`, adds default
-permission rules, the `/linear-status` command, the `/linear` status view and two skills. It adds no tools of its own:
-the tools are Linear's, and OpenCode handles the connection, the sign-in and the stored credentials.
+Run `opencode reload`, or restart OpenCode. Then run `/linear-status`: it shows `sign-in required` until you sign in
+(see [Sign in](#sign-in)).
+
+The plugin registers Linear's MCP server under the name `linear`, adds default permission rules, the `/linear-status`
+command, the `/linear` status view, two skills and one tool of its own, `linear_issues`. Every other tool is Linear's,
+and OpenCode handles the connection, the sign-in and the stored credentials.
+
+`linear_issues` answers the issues assigned to you as a table: identifier, title, state, priority and link. It reads
+them through Linear's own `list_issues`, under that tool's sign-in and permission rules, and holds no credential. It is
+a direct tool, offered to the model even when Code Mode holds Linear's other tools, because
+[Jelly](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/docs/jelly.md) draws a tool's result as a table only
+for a direct call, not for one made inside Code Mode.
+
+**Update** with `opencode plugin update @joe-broadhead/opencode-linear`, then run `opencode reload`. An entry pinned
+to a version, such as `@joe-broadhead/opencode-linear@0.0.1`, does not update: remove the `@version` from its
+`plugins` entry first.
 
 ## Sign in
 
@@ -38,7 +52,8 @@ OpenCode shows its "MCP server needs authentication" notice.
 
 To sign out, or to change workspace, run `opencode mcp logout linear` while the access you want to change is the one
 configured. It removes the stored sign-ins for that access only. Or remove the account in `/connect` → Linear. Then
-sign in again and pick the workspace on Linear's consent page.
+sign in again and pick the workspace on Linear's consent page. To sign out of both before you remove the plugin, see
+[Uninstall](#uninstall).
 
 ## Use
 
@@ -76,9 +91,11 @@ The plugin adds these rules to every agent, directly after the agent's base rule
 
 1. `{ "action": "linear_*", "resource": "*", "effect": "ask" }`: every Linear tool asks, including tools Linear adds
    later.
-2. One `allow` rule for each of Linear's 42 read tools, listed in
+2. One `allow` rule for each of Linear's 41 read tools, listed in
    [`src/linear-tools.ts`](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/src/linear-tools.ts). These
    run without a prompt.
+3. `{ "action": "linear_issues", "resource": "*", "effect": "allow" }`: the plugin's own `linear_issues`, which only
+   reads, runs without a prompt too. Its call to `list_issues` still follows that tool's rules.
 
 So reads run, and every change asks before it runs. Everything that comes later than these rules still wins: an
 agent's own stricter rules (Plan cannot edit, Explore cannot use Linear), your `permissions` in `opencode.json`, and
@@ -103,7 +120,7 @@ Set options with the object form of the plugin entry:
 | Option | Values | Default | Effect |
 | --- | --- | --- | --- |
 | `access` | `"read"` or `"write"` | `"read"` | `"read"` uses Linear's read-only server and the `read` scope. `"write"` uses `https://mcp.linear.app/mcp` with `read write`, and adds the `linear-write` skill. |
-| `allowUntestedHost` | `true` or `false` | `false` | Starts on an OpenCode version outside the tested line, with a warning in status. |
+| `allowUntestedHost` | `true` or `false` | `false` | Starts on an OpenCode version outside `>=2.2.3 <2.3.0`, with a warning in status. |
 
 Switching `access` changes the server address, and read and write access each have their own sign-in. If you have
 never signed in with the new access, run `/connect` and choose Linear, then press `o` or Enter to open the link. If you
@@ -145,28 +162,42 @@ Run `/linear-status` first. Its last line is the next step.
 | Connection: conflict | Your config has an `mcp.servers.linear` entry with a URL other than the one your `access` uses. Point it at that URL or remove it, then restart OpenCode. |
 | Tools: unknown | Linear added tools the plugin does not know yet. They ask before they run. |
 | Agents without default rules | Put the printed block first in each listed agent's own `permissions`, followed by your top-level rules for `linear_*` tools. |
-| OpenCode: host untested | OpenCode is outside `>=2.2.3 <2.3.0` and `allowUntestedHost` is set. If Linear misbehaves, use a tested OpenCode. |
+| OpenCode: untested | OpenCode is not 2.2.3, 2.2.4 or 2.2.5. Inside `>=2.2.3 <2.3.0` the plugin runs normally; outside it, it runs only because `allowUntestedHost` is set. If Linear misbehaves, use a tested release. |
 | Signed in to the wrong workspace, for example after switching `access` | Read and write access each have their own sign-in, and Linear's consent page decides the workspace. With the wrong access still configured, run `opencode mcp logout linear` (or remove the account in `/connect` → Linear), then sign in again and pick the workspace. |
 | A Linear tool is refused in `opencode run` | Nobody could answer its prompt. Add an `allow` rule for that tool. |
 | `/linear` is missing | The plugin did not start. Run `/plugins` to see the error. |
 | `OPTIONS_INVALID` | An option is unknown or has a wrong value. The message names the option and the accepted values. |
-| `HOST_UNTESTED` | Your OpenCode is outside `>=2.2.3 <2.3.0`. Use a tested OpenCode, or set `"allowUntestedHost": true` to try anyway. |
+| `HOST_UNTESTED` | Your OpenCode is outside `>=2.2.3 <2.3.0`, so the plugin did not start. Use OpenCode `>=2.2.3 <2.3.0`, or set `"allowUntestedHost": true` to run anyway. |
 | `STATUS_UNAVAILABLE` | The status could not be read, or the plugin is not running. Follow the next step in the message. |
 | `SKILLS_INVALID` | A skill file in the package is missing or broken. Reinstall the plugin. |
+| `AUTH_REQUIRED` from `linear_issues` | OpenCode does not list Linear's `list_issues`, usually because you are not signed in. Run `/connect` and choose Linear; if you are signed in, run `/linear-status`. |
+| `UPSTREAM_UNREADABLE` from `linear_issues` | Linear's `list_issues` answered with something other than a list of issues. Ask for `list_issues` with assignee `me` instead, and update the plugin. |
 
 A script's errors from the tools RPC have their own codes, listed in
 [Scripting](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/docs/scripting.md#errors).
 
 ## Uninstall
 
-```sh
-opencode plugin remove @joe-broadhead/opencode-linear
-opencode mcp logout linear
-```
+Sign out while the plugin is still installed: once it is removed, OpenCode no longer knows the `linear` server, so
+`opencode mcp logout linear` fails with `MCP server not found: linear` and the sign-ins stay in OpenCode's credential
+store. Read access and write access each have their own sign-in, and OpenCode signs out only the one for the `access`
+configured now.
+
+1. Sign out: `opencode mcp logout linear`. Right after OpenCode starts or reloads, it can answer
+   `MCP server not found: linear` for a few seconds; wait, then run it again.
+2. If you ever used the other access, sign out of it too. Set `"access"` in the plugin's `plugins` entry in
+   `opencode.json` to the other value (`"write"`, or `"read"`, the default), for example
+   `{ "package": "@joe-broadhead/opencode-linear", "options": { "access": "write" } }`, run `opencode reload`, then
+   run `opencode mcp logout linear` again.
+3. Check: `opencode auth list` no longer lists **Linear**.
+4. Remove the plugin: `opencode plugin remove @joe-broadhead/opencode-linear`, then `opencode reload`.
+   `opencode mcp list` no longer lists `linear`.
+5. Remove any Linear rules you copied into your agents' own `permissions`.
 
 ## Links
 
 - [Configuration](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/docs/configuration.md)
+- [In Jelly](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/docs/jelly.md)
 - [Architecture](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/docs/architecture.md)
 - [Contributing](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/CONTRIBUTING.md)
 - [Security](https://github.com/joe-broadhead/opencode-linear/blob/HEAD/SECURITY.md)