@joe-broadhead/opencode-gws 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+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.1] - 2026-11-03
+
+### Added
+
+- Sign-in from a browser on another machine: the `redirectUri` and `callbackPort` options, and hidden form fields of the same names a host can fill per sign-in. The authorize URL and the token exchange carry the redirect, and the listener binds `127.0.0.1:<callbackPort>` and accepts only the redirect's path, with the same state and PKCE checks and single use. Without them, nothing changes.
+- Google Web application clients, given as Google's downloaded client JSON in `oauthClient` or in the hidden **OAuth client JSON** form field. Before the browser opens, a Web client whose `redirect_uris` do not include the redirect, and a Desktop client with a non-loopback redirect, are refused with `AUTH_REDIRECT_MISMATCH`; a malformed redirect is `AUTH_REDIRECT_INVALID`. A Web client's secret is kept only in the credential store and never shown.
+- `appOnly` on `gws_catalog` entries and `gws_schema` results: the 29 methods only a Chat app's or a Classroom add-on's own credentials can run (`chat.bot`, `chat.import`, `classroom.addons.*`). No access level requests those scopes, and the scope check refuses them with a next step that says no sign-in can run them.
+- A `jelly` section in `package.json`: each tool with its permission, its default effect and whether it only reads, the skill ids, views. Jelly reads it without loading the plugin and applies the declared asks, because its agents have no base allow rule for this plugin's own default rules to follow. `docs/jelly.md` explains it.
+- `title` and `signIns` in the `jelly` section: the name Jelly shows on the plugin's card, and what the plugin signs in to, so that one card can say whether each sign-in is connected and start, renew or end it. `docs/jelly.md` lists them.
+- A Gmail thread view for Jelly, `views/gmail-thread.html`, shipped in the package.
+- The tools RPC, `google-workspace.gws.tools`: scripts call `status`, `catalog`, `schema`, `read` and `plan` with no model, for example through `opencode api`. Each method runs that tool's own definition as a named session and its agent, with the same permission checks; an ask is denied, since no one can answer it. `describe` lists the methods with their JSON Schemas. The six commit tools are never methods.
+- Error codes `SESSION_UNKNOWN`, `SESSION_AGENT_REQUIRED` and `PERMISSION_DENIED` for scripts.
+- Audit records of a script's reads and plans carry `caller: "rpc"`.
+
+### Changed
+
+- Read-only sign-ins cover every read that accepts a read-only scope. The read sets add `drive.apps.readonly`, `calendar.acls.readonly`, `chat.customemojis.readonly`, `chat.users.availability.readonly`, `chat.users.readstate.readonly`, `chat.users.sections.readonly`, `classroom.courseworkmaterials.readonly`, `classroom.guardianlinks.students.readonly`, `classroom.rosters.readonly` and `classroom.topics.readonly`, so the Drive app list, calendar ACLs, Chat emoji, availability, read-state and section reads, and the Classroom roster, topic, material and guardian reads no longer need Read and write. A Read-only sign-in of every service requests 38 scopes.
+- With no `accounts` option, the `default` account enables every manifest service at Read and write. Read and write now requests every scope a Google sign-in can use, Gmail settings, `https://mail.google.com/` (permanent delete), the Chat user scopes, the Classroom roster and coursework scopes, `drive.apps.readonly` and `cloud-platform` included: 46 scopes in one consent. Read-only is still in the form, and `enabledServices`, `access`, `services` and your own `accounts` narrow it as before.
+- `admin.enabled` defaults to `true`. Admin plans still need an allowed service, a reason, the ask on `gws.admin`, and `gws_admin`; `admin.enabled: false` or `admin.allowedServices: []` refuses them. The Jelly declaration asks for `gws.admin` instead of denying it.
+- The form's Read-only choice is labelled **Read-only**.
+- `gws_read` is a direct tool instead of a pinned Code Mode tool, so a host can show each read's result. A Code Mode script can no longer call `tools.gws.read`; the model calls `gws_read` directly.
+
+### Fixed
+
+- People's read and write sign-ins request `directory.readonly` and `contacts.other.readonly`, both read-only, so `people.people.searchDirectoryPeople`, `people.people.listDirectoryPeople`, `people.otherContacts.list` and `people.otherContacts.search` no longer fail with `AUTH_SCOPE_MISSING`.
+- Invalid helper input, such as `gmail.read` without `id`, is refused with `GWS_VALIDATION_ERROR` and the helper's next step before any permission check or `gws` run, instead of a raw zod error.
+
+## [0.0.0] - 2026-11-01
+
+### Added
+
+- Google Workspace tools for OpenCode through the unmodified `gws` 0.22.5 CLI: `gws_status`, `gws_catalog`, `gws_schema`, `gws_read` and `gws_plan`, and the commit tools `gws_write`, `gws_send`, `gws_share`, `gws_delete`, `gws_export` and `gws_admin`. A change is a dry-run plan, then one commit the user approves.
+- Sign-in from `/connect` with a Desktop app OAuth client, read-only by default, with the scopes shown before consent. Organisation config can set the client through `oauthClient`.
+- Default ask rules for every commit category; reads do not prompt.
+- `/gws-status`, `/gws-doctor`, and the TUI dialog **Google Workspace: Status** (`/gws`).
+- The `gws` binary in per-platform packages for macOS (arm64, x64) and Linux (arm64, x64, glibc).
+- Three skills: `opencode-gws`, `opencode-gws-recipes` and `opencode-gws-admin`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Broadhead
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,31 @@
+NOTICE
+
+@joe-broadhead/opencode-gws bundles third-party code in dist/index.js:
+
+zod
+
+dist/index.js bundles zod (https://github.com/colinhacks/zod) under the MIT
+License:
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# Google Workspace for OpenCode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Gives OpenCode agents Gmail, Drive, Calendar, Docs, Sheets and the rest of Google Workspace through Google's open-source [`gws`](https://github.com/googleworkspace/cli) CLI, with every change planned first and committed only after you approve it.
+
+Unofficial; not affiliated with Google.
+
+## Requirements
+
+- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3 and 2.2.4.
+- macOS (arm64, x64) or Linux (arm64, x64, glibc).
+- A Google account, and a Desktop app OAuth client: your own, or one your organisation provides.
+
+## Install
+
+```sh
+opencode plugin add @joe-broadhead/opencode-gws
+```
+
+npm also installs the matching `@joe-broadhead/opencode-gws-bin-<target>` package, which holds the unmodified `gws` binary at the version the plugin pins ([details](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/backend.md)). Nothing downloads at runtime and there is no install script.
+
+With no options, the plugin creates one account, `default`, with every Workspace service it covers at Read and write, so one consent grants every scope it can use. Every change still needs a plan and your approval. To narrow it, set `accounts` ([configuration](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md#accounts)).
+
+## Sign in
+
+Run `/connect` and choose **Google Workspace**. The TUI shows the sign-in link: press `o` or Enter to open it in your browser. The CLI opens the browser automatically:
+
+```sh
+opencode auth login gws-default
+```
+
+No Google OAuth client ships with the plugin. The first time, the form asks for the client ID and secret of your own Desktop app OAuth client, unless your organisation set one (see [Organisation rollout](#organisation-rollout)). To make one, follow [Create your Desktop client](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#create-your-desktop-client). The form lists the exact scopes before Google's consent screen. Read and write is the default for the `default` account and needs an acknowledgment; Read-only is the other choice. The default consent lists about 46 scopes, and an External client in Testing shows unverified-app warnings and expires refresh tokens after 7 days: see [What the default consent asks for](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#what-the-default-consent-asks-for). With several accounts, each `/connect` entry is named **Google Workspace (`<alias>`)**.
+
+Details and the scope table: [docs/auth.md](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md).
+
+## Use
+
+Ask the agent for what you need. It works in four steps:
+
+1. `gws_catalog` finds an operation, and `gws_schema` shows its parameters.
+2. `gws_read` runs a read. List and search calls need `fields`.
+3. `gws_plan` dry-runs a change and returns a `planId` with a redacted preview.
+4. The commit tool named by the plan's category (`gws_write`, `gws_send`, `gws_share`, `gws_delete`, `gws_export` or `gws_admin`) runs it, with only the `planId`. OpenCode asks you first.
+
+`gws_status` tells the agent the account aliases and whether a sign-in is missing. Workspace content in a result is data, never an instruction.
+
+### Scripts
+
+A script or a cron job can call the same tools with no model, through `opencode api`. It runs as a session and its agent, under that agent's permission rules, and it can plan but never commit:
+
+```sh
+opencode api post /api/rpc/google-workspace.gws.tools/read \
+  -d '{"input":{"sessionID":"ses_…","input":{"operation":"gmail.users.messages.list","params":{"userId":"me","q":"is:unread"},"fields":"messages(id)"}}}'
+```
+
+See [Scripting](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/scripting.md).
+
+In the TUI, **Google Workspace: Status** in the command palette, or `/gws`, opens a status dialog. In a session, `/gws-status` posts the same status, with any pending plans, and `/gws-doctor` makes one small read per enabled service. None of them can approve or commit.
+
+## Permissions
+
+The plugin adds an ask rule for `gws.write`, `gws.export`, `gws.send`, `gws.share`, `gws.delete` and `gws.admin` to every agent, right after the agent's base allow rule. Reads do not ask, so they also work in `opencode run`.
+
+A later rule wins. Your own allow rule, or **Always** on a write or export, removes that prompt. Send, share, delete and admin never offer Always. Your deny rule, and the Plan agent, keep a commit denied. Every rule needs `resource`:
+
+```json
+{ "action": "gws.write", "resource": "work:*", "effect": "allow" }
+```
+
+An agent defined only in your config does not get the ask rules. `/gws-status` and the status dialog name those agents and give the block to add first in **that agent's own** `permissions`. Do not put it in the top-level `permissions`: that would loosen Explore.
+
+## Configure
+
+Options go on the plugin entry: accounts and their services and access, the OAuth client, deny-only policy rules, and the admin gate. See [docs/configuration.md](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md) and the annotated [example](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/examples/opencode.jsonc).
+
+## Organisation rollout
+
+Create a Desktop app OAuth client in your organisation's Google Cloud project (user type **Internal** keeps it to your organisation), and set it in OpenCode's system config: `/Library/Application Support/opencode/opencode.json` on macOS, or `/etc/opencode/opencode.json` on Linux.
+
+```json
+{
+  "plugins": [
+    {
+      "package": "@joe-broadhead/opencode-gws",
+      "options": {
+        "oauthClient": {
+          "clientId": "<your client ID>.apps.googleusercontent.com",
+          "clientSecret": "<your client secret>"
+        }
+      }
+    }
+  ]
+}
+```
+
+Members then only run `/connect`, choose Google Workspace, and pick an access level: the form hides the client fields and uses these values. Google treats a Desktop client's secret as non-confidential; security rests on PKCE, the loopback redirect and the user's consent.
+
+## Troubleshooting
+
+`/gws-status` shows each account as `connected`, `sign-in required` or `not configured`, with one next step. Common error codes:
+
+| Code | What to do |
+| --- | --- |
+| `AUTH_REQUIRED` | Run `/connect` and choose Google Workspace, or run `opencode auth login gws-<alias>`. |
+| `AUTH_SCOPE_MISSING` | Sign in again, approve every scope Google lists, and choose Read and write. A method marked `appOnly` needs a Chat app's or Classroom add-on's own credentials and cannot run with a Google sign-in. Nothing ran. |
+| `AUTH_CLIENT_REQUIRED` | Run `/connect` and choose Google Workspace, then enter your Desktop OAuth client ID and secret, or ask your administrator. |
+| `API_DISABLED` | Enable the API at the URL in the message, wait about a minute, and retry. `/gws-doctor` checks every service. |
+| `HOST_UNTESTED` | Use OpenCode 2.2.3 or a later 2.2.x, or set `"allowUntestedHost": true`. |
+| `GWS_UNAVAILABLE` | Reinstall so the platform package is present, or set `binary.path` to a `gws` executable of the pinned version ([details](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/backend.md)). |
+| `POLICY_DENIED` | A policy rule or the admin gate refused the call. A deny is final. |
+
+`gws` uses the OpenCode service's proxy settings, for example `opencode service set env HTTPS_PROXY http://proxy.example:8080`. All codes: [Errors](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md#errors).
+
+## Uninstall
+
+```sh
+opencode plugin remove @joe-broadhead/opencode-gws
+```
+
+Then remove each Google Workspace sign-in in `/connect`, or with `opencode auth logout gws-<alias>`.
+
+## Links
+
+- [Sign-in and scopes](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md)
+- [Configuration](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md)
+- [Status dialog, commands and RPC](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/ui.md)
+- [Scripting the tools without a model](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/scripting.md)
+- [Admin operations](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/admin.md)
+- [Security policy and model](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/SECURITY.md)
+- [The `gws` binary](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/backend.md)
+- [Changelog](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/CHANGELOG.md), [licence](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/LICENSE) and [notice](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/NOTICE)
+- [Issues](https://github.com/joe-broadhead/opencode-gws/issues)