@joe-broadhead/opencode-slack 0.0.0 → 0.0.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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
+
+- A `jelly` section in `package.json`: each tool with its permission, its default effect and whether it only reads, the skill ids. 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.
+- Hosted callbacks, so sign-in works when OpenCode runs on another machine ([#1](https://github.com/joe-broadhead/opencode-slack/issues/1)): `oauth.redirect_uri` also accepts an `https:` URL with a path and no credentials, query or fragment, together with the new `oauth.callback_port`, the port of OpenCode's local callback listener, which a reverse proxy forwards the address to. The server config then carries `callback_port`, and status shows the port in `callbackPort` and its `Callback` row. `oauth.callback_port` is refused with a loopback redirect, whose own port is the listener's. The docs explain how to add a hosted address to the Slack app's Redirect URLs, and how two sign-ins on one machine avoid colliding on port 8765.
+- `presetBy` on the `jelly.signIns` Slack app step: with `oauth.client_id` set in the plugin options, the step is done, so Jelly asks nobody to paste a client ID.
+
+### Changed
+
+- The `oauth.redirect_uri` errors say which rule an `http:` URL broke, and their next step names both a loopback and a hosted example. The `Callback` status row says to register the URL in the app's Redirect URLs.
+
 ## [0.0.0] - 2026-11-01
 
 ### Added

package/README.md

@@ -21,7 +21,7 @@ opencode plugin add @joe-broadhead/opencode-slack
 
    If your organisation already set the client ID for you (see [Organisation rollout](#organisation-rollout)), there is no **Slack app** entry; go straight to step 2.
 2. **Sign in to Slack.** Run `/connect` and choose **Slack**. In the TUI, press `o` or Enter to open the sign-in page in your browser. In a terminal, `opencode mcp auth slack` opens the browser automatically. `/mcps` → `slack` is an equivalent way in.
-3. Slack shows the workspace, the account and what the app asks for. Approve it. Slack sends the browser back to `http://localhost:8765/callback`, and OpenCode finishes the sign-in.
+3. Slack shows the workspace, the account and what the app asks for. Approve it. Slack sends the browser back to the callback, `http://localhost:8765/callback` unless you set another, and OpenCode finishes the sign-in.
 
 `/slack-status` now shows `connected` and the Slack tools it found. OpenCode stores the credential and refreshes it. To sign out, run `opencode mcp logout slack`.
 
@@ -106,7 +106,7 @@ Do not put this block in the top-level `permissions`. OpenCode adds top-level ru
 
 ## Configure
 
-Everything works without options. Options set the client ID for everyone (instead of `/connect`), the callback URL, the scopes, a client secret for apps without PKCE, the server name and the host check. To pass them, use the object form of the `plugins` entry:
+Everything works without options. Options set the client ID for everyone (instead of `/connect`), the callback URL and its local port, the scopes, a client secret for apps without PKCE, the server name and the host check. To pass them, use the object form of the `plugins` entry:
 
 ```jsonc
 {
@@ -116,6 +116,14 @@ Everything works without options. Options set the client ID for everyone (instea
 }
 ```
 
+**OpenCode on another machine.** The default callback, `http://localhost:8765/callback`, works only when the browser runs on OpenCode's machine. Otherwise use a hosted callback: an `https:` address the browser can reach, which a reverse proxy forwards to OpenCode's local listener on `oauth.callback_port`:
+
+```jsonc
+"oauth": { "client_id": "YOUR_SLACK_CLIENT_ID", "redirect_uri": "https://host.example/oauth/return", "callback_port": 8766 }
+```
+
+Add the address to the Slack app's **OAuth & Permissions → Redirect URLs** (or `oauth_config.redirect_urls` in the [manifest](https://github.com/joe-broadhead/opencode-slack/blob/HEAD/docs/slack-app-manifest.json)). Slack matches the host and port exactly. [The callback: loopback or hosted](https://github.com/joe-broadhead/opencode-slack/blob/HEAD/docs/configuration.md#the-callback-loopback-or-hosted) explains the proxy and how two sign-ins on one machine avoid colliding on port 8765.
+
 [docs/configuration.md](https://github.com/joe-broadhead/opencode-slack/blob/HEAD/docs/configuration.md) lists every option, the scopes each tool needs, the permission rules and the status model.
 
 ## Organisation rollout
@@ -165,6 +173,8 @@ If status itself cannot be read, `/slack-status` says `STATUS_UNAVAILABLE`; run
 - **Slack asks you to request approval:** your workspace requires admin approval for apps or scopes. Ask an admin to approve the app, then sign in again.
 - **Slack refuses the app for MCP:** turn on **Agents → Slack Model Context Protocol (MCP) Server** in the app settings. The app must be internal to your organisation or published in the Slack Marketplace.
 - **The browser cannot open `localhost:8765` after Slack approves:** OpenCode listens for the callback on `127.0.0.1` only. If your browser tries IPv6 for `localhost`, replace `localhost` with `127.0.0.1` in the address bar. To avoid it, register `http://127.0.0.1:8765/callback` in the app and set it as `oauth.redirect_uri`.
+- **The browser cannot open `localhost:8765` because OpenCode runs on another machine:** the browser's `localhost` is not OpenCode's. Use a [hosted callback](https://github.com/joe-broadhead/opencode-slack/blob/HEAD/docs/configuration.md#the-callback-loopback-or-hosted).
+- **Sign-in fails because the callback port is in use:** another sign-in on this machine is waiting on port 8765. Finish it first, or give this OpenCode its own callback, such as `http://localhost:8767/callback`, registered in the Slack app too.
 
 **A Slack tool fails**
 

package/dist/index.js

@@ -3,6 +3,8 @@ import { Plugin } from "@opencode/plugin";
 
 // src/defaults.ts
 var DEFAULT_REDIRECT_URI = "http://localhost:8765/callback";
+var HOSTED_REDIRECT_EXAMPLE = "https://host.example/oauth/return";
+var CALLBACK_PORT_EXAMPLE = 8766;
 var DEFAULT_SCOPES = ["channels:history", "channels:read", "search:read.public", "users:read"];
 var DEFAULT_SERVER = "slack";
 var APP_MANIFEST_URL = "https://github.com/joe-broadhead/opencode-slack/blob/HEAD/docs/slack-app-manifest.json";
@@ -96,7 +98,7 @@ function isTestedHost(version) {
 
 // src/options.ts
 var TOP_KEYS = ["oauth", "server", "allowUntestedHost"];
-var OAUTH_KEYS = ["client_id", "redirect_uri", "scopes", "client_secret"];
+var OAUTH_KEYS = ["client_id", "redirect_uri", "callback_port", "scopes", "client_secret"];
 var SERVER_NAME = /^[A-Za-z0-9_-]+$/;
 var NO_SPACES2 = /^\S+$/;
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -108,14 +110,17 @@ function redirectProblem(value) {
   } catch {
     return "Must be a valid URL.";
   }
-  if (url.protocol !== "http:") return "Must use http:.";
-  if (url.hostname !== "localhost" && url.hostname !== "127.0.0.1") return "Must use the host localhost or 127.0.0.1.";
-  if (url.port === "") return "Must include an explicit port.";
+  if (url.protocol !== "http:" && url.protocol !== "https:") return "Must use http: or https:.";
+  if (url.protocol === "http:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+    return "An http: URL must use the host localhost or 127.0.0.1.";
+  }
+  if (url.protocol === "http:" && url.port === "") return "An http: URL must include an explicit port.";
   if (url.username !== "" || url.password !== "") return "Must not include credentials.";
   if (value.includes("?") || value.includes("#")) return "Must not include a query or fragment.";
   if (url.pathname === "/") return "Must include a path, such as /callback.";
   return void 0;
 }
+var isPort = (value) => typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
 function parseOptions(input) {
   const raw = input ?? {};
   if (!isRecord(raw)) return fail("options", "Plugin options must be an object.", "Set options to an object, or remove them.");
@@ -136,7 +141,18 @@ function parseOptions(input) {
   const redirectUri = oauth.redirect_uri ?? DEFAULT_REDIRECT_URI;
   const redirectError = typeof redirectUri === "string" ? redirectProblem(redirectUri) : "Must be a string.";
   if (typeof redirectUri !== "string" || redirectError !== void 0) {
-    return fail("oauth.redirect_uri", redirectError ?? "Must be a string.", `Use the loopback URL registered in your Slack app, for example ${DEFAULT_REDIRECT_URI}.`);
+    return fail("oauth.redirect_uri", redirectError ?? "Must be a string.", `Use a URL listed in the app's Redirect URLs, for example ${DEFAULT_REDIRECT_URI} or ${HOSTED_REDIRECT_EXAMPLE}.`);
+  }
+  const hosted = new URL(redirectUri).protocol === "https:";
+  const callbackPort = oauth.callback_port;
+  if (callbackPort !== void 0 && !isPort(callbackPort)) {
+    return fail("oauth.callback_port", "Must be a whole number from 1 to 65535.", `Set it to the local port that receives the forwarded callback, for example ${CALLBACK_PORT_EXAMPLE}.`);
+  }
+  if (callbackPort !== void 0 && !hosted) {
+    return fail("oauth.callback_port", "Applies only to an https: oauth.redirect_uri.", "Remove it: with a loopback oauth.redirect_uri, OpenCode listens on that URL's port.");
+  }
+  if (callbackPort === void 0 && hosted) {
+    return fail("oauth.callback_port", "Must be set with an https: oauth.redirect_uri.", `Set it to the local port your proxy forwards the redirect to, for example ${CALLBACK_PORT_EXAMPLE}.`);
   }
   const scopes = oauth.scopes ?? DEFAULT_SCOPES;
   const isScope = (scope) => typeof scope === "string" && NO_SPACES2.test(scope);
@@ -164,6 +180,7 @@ function parseOptions(input) {
     options: {
       ...clientId === void 0 ? {} : { clientId },
       redirectUri,
+      ...callbackPort === void 0 ? {} : { callbackPort },
       scopes: [...scopes],
       ...clientSecret === void 0 ? {} : { clientSecret },
       server,
@@ -248,6 +265,7 @@ var status = object({
   server: object({ name: text, url: text }, ["name", "url"]),
   client: object({ id: text, mode: { enum: ["public_pkce", "confidential"] }, source: { enum: ["options", "connect"] } }, ["id", "mode", "source"]),
   callback: text,
+  callbackPort: { type: "integer" },
   scopes: texts,
   asksBefore: texts,
   tools: object({
@@ -280,6 +298,7 @@ function serverConfig(options, client) {
     oauth: {
       client_id: client.id,
       redirect_uri: options.redirectUri,
+      ...options.callbackPort === void 0 ? {} : { callback_port: options.callbackPort },
       scope: options.scopes.join(" "),
       ...client.secret === void 0 ? {} : { client_secret: client.secret }
     }
@@ -402,6 +421,7 @@ function buildStatus(input) {
         client: { id: client.id, mode: client.secret === void 0 ? "public_pkce" : "confidential", source: client.source }
       },
       callback: options.redirectUri,
+      ...options.callbackPort === void 0 ? {} : { callbackPort: options.callbackPort },
       scopes: options.scopes
     },
     asksBefore: ASKS_BEFORE,
@@ -443,6 +463,11 @@ function buildStatus(input) {
   const status2 = input.servers.find((item) => item.name === server)?.status;
   return { ...base, ...connection(server, status2, unguardedAgents, names.length) };
 }
+function callbackRow(callback, port) {
+  const register = "register exactly this URL in the app's Redirect URLs";
+  if (port === void 0) return `${callback} (${register})`;
+  return `${callback} (${register}, and forward it to http://127.0.0.1:${port}${new URL(callback).pathname}, where OpenCode listens)`;
+}
 var CLIENT_SOURCE = { options: "set in plugin options", connect: "saved in /connect" };
 function stateLabel(status2) {
   switch (status2.state) {
@@ -477,7 +502,7 @@ function statusRows(status2) {
     const mode = status2.client.mode === "public_pkce" ? "public, PKCE" : "confidential, secret set";
     rows.push({ label: "Client", value: `${status2.client.id} (${mode}; ${CLIENT_SOURCE[status2.client.source]})` });
   }
-  if (status2.callback !== void 0) rows.push({ label: "Callback", value: `${status2.callback} (register exactly this URL in the Slack app)` });
+  if (status2.callback !== void 0) rows.push({ label: "Callback", value: callbackRow(status2.callback, status2.callbackPort) });
   if (status2.scopes !== void 0) rows.push({ label: "Scopes", value: status2.scopes.join(" ") });
   rows.push({
     label: "Tools",

package/dist/tui.js

@@ -25,6 +25,7 @@ var status = object({
   server: object({ name: text, url: text }, ["name", "url"]),
   client: object({ id: text, mode: { enum: ["public_pkce", "confidential"] }, source: { enum: ["options", "connect"] } }, ["id", "mode", "source"]),
   callback: text,
+  callbackPort: { type: "integer" },
   scopes: texts,
   asksBefore: texts,
   tools: object({
@@ -97,6 +98,11 @@ function defaultRules(server) {
 // src/status.ts
 var quote = (rule) => `{ "action": "${rule.action}", "resource": "${rule.resource}", "effect": "${rule.effect}" }`;
 var remedy = (server) => `[${defaultRules(server).map(quote).join(", ")}]`;
+function callbackRow(callback, port) {
+  const register = "register exactly this URL in the app's Redirect URLs";
+  if (port === void 0) return `${callback} (${register})`;
+  return `${callback} (${register}, and forward it to http://127.0.0.1:${port}${new URL(callback).pathname}, where OpenCode listens)`;
+}
 var CLIENT_SOURCE = { options: "set in plugin options", connect: "saved in /connect" };
 function stateLabel(status2) {
   switch (status2.state) {
@@ -131,7 +137,7 @@ function statusRows(status2) {
     const mode = status2.client.mode === "public_pkce" ? "public, PKCE" : "confidential, secret set";
     rows.push({ label: "Client", value: `${status2.client.id} (${mode}; ${CLIENT_SOURCE[status2.client.source]})` });
   }
-  if (status2.callback !== void 0) rows.push({ label: "Callback", value: `${status2.callback} (register exactly this URL in the Slack app)` });
+  if (status2.callback !== void 0) rows.push({ label: "Callback", value: callbackRow(status2.callback, status2.callbackPort) });
   if (status2.scopes !== void 0) rows.push({ label: "Scopes", value: status2.scopes.join(" ") });
   rows.push({
     label: "Tools",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joe-broadhead/opencode-slack",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Unofficial OpenCode plugin for Slack",
   "keywords": [
     "opencode",
@@ -55,5 +55,201 @@
     "esbuild": "0.28.2",
     "solid-js": "1.9.17",
     "typescript": "5.9.3"
+  },
+  "jelly": {
+    "title": "Slack",
+    "tools": [
+      {
+        "name": "slack.slack_search_public",
+        "permission": "slack_slack_search_public",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_search_channels",
+        "permission": "slack_slack_search_channels",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_search_users",
+        "permission": "slack_slack_search_users",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_read_channel",
+        "permission": "slack_slack_read_channel",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_read_thread",
+        "permission": "slack_slack_read_thread",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_read_user_profile",
+        "permission": "slack_slack_read_user_profile",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_read_canvas",
+        "permission": "slack_slack_read_canvas",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_list_channel_members",
+        "permission": "slack_slack_list_channel_members",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_get_reactions",
+        "permission": "slack_slack_get_reactions",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_list_user_channels",
+        "permission": "slack_slack_list_user_channels",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_read_list",
+        "permission": "slack_slack_read_list",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_search_emojis",
+        "permission": "slack_slack_search_emojis",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_search_public_and_private",
+        "permission": "slack_slack_search_public_and_private",
+        "effect": "ask",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_read_file",
+        "permission": "slack_slack_read_file",
+        "effect": "ask",
+        "readOnly": true
+      },
+      {
+        "name": "slack.slack_send_message",
+        "permission": "slack_slack_send_message",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_send_message_draft",
+        "permission": "slack_slack_send_message_draft",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_schedule_message",
+        "permission": "slack_slack_schedule_message",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_create_canvas",
+        "permission": "slack_slack_create_canvas",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_update_canvas",
+        "permission": "slack_slack_update_canvas",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_add_reaction",
+        "permission": "slack_slack_add_reaction",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_get_file_upload_url",
+        "permission": "slack_slack_get_file_upload_url",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_complete_file_upload",
+        "permission": "slack_slack_complete_file_upload",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_create_conversation",
+        "permission": "slack_slack_create_conversation",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_create_list",
+        "permission": "slack_slack_create_list",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_update_list",
+        "permission": "slack_slack_update_list",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_add_list_record",
+        "permission": "slack_slack_add_list_record",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "slack.slack_update_list_record",
+        "permission": "slack_slack_update_list_record",
+        "effect": "ask",
+        "readOnly": false
+      }
+    ],
+    "skills": [
+      "slack-search"
+    ],
+    "rpc": [],
+    "views": [],
+    "signIns": [
+      {
+        "id": "app",
+        "label": "Slack app",
+        "integration": "slack-app",
+        "presetBy": "oauth.client_id",
+        "help": {
+          "url": "https://github.com/joe-broadhead/opencode-slack/blob/HEAD/docs/slack-app-manifest.json",
+          "label": "Create the Slack app from its manifest, then paste its client ID"
+        }
+      },
+      {
+        "id": "slack",
+        "label": "Slack",
+        "server": "slack",
+        "after": "app"
+      }
+    ],
+    "contributes": {
+      "homeFeeds": [],
+      "homeWidgets": [],
+      "workKinds": [],
+      "settings": []
+    }
   }
 }