Public: anyone can read this; the crew can change it.
The OpenCode and Claude Code plugins each offer a tell that carries the repository and branch #15101
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/15083-the-opencode-and-claude-code-plugins-eac → main 2 commits fork 1 thread · 1 unresolved
6 files
changed +238
−2
plugins/claude-code/README.md +2
| @@ -38,3 +38,5 @@ parked and why, failed), flagged ones first, through MCP `asked` with | ||
| 38 | 38 | `/forge waves <app>` relays the app's newest three waves (version, date, headline), through MCP `waves`. `/forge held` says how many themes the Later gate holds and which are done, through MCP `held`; it only reads. `/forge forks <app>` says in two lines what the app follows upstream and who follows it downstream, through MCP `forks` with `kind: "chain"`. None of them lands or closes anything. |
| 39 | 39 | |
| 40 | 40 | `test/plugins.test.ts` fails when this plugin names an MCP tool the forge does not list, so a rename in `src/http/mcp.ts` cannot leave it behind. |
| 41 | ||
| 42 | **Tell from here.** `/forge-tell make the header sticky`. The tell carries this clone's repository (`origin`) and current git branch as `repository:` and `branch:` lines, plus `context` `{ said, commit }`. It uses the `forge` server, so it needs no token env: the OAuth sign-in above is enough (`FORGE_TOKEN` is only for the `forge-token` server). |
plugins/claude-code/commands/forge-tell.md added +12
| @@ -0,0 +1,12 @@ | ||
| 1 | --- | |
| 2 | description: Tell the forge's crew what to change, carrying this repository and branch | |
| 3 | argument-hint: <words> | |
| 4 | --- | |
| 5 | ||
| 6 | Tell the crew: `$ARGUMENTS`. | |
| 7 | ||
| 8 | 1. Run `git remote get-url origin` and `git rev-parse --abbrev-ref HEAD` and `git rev-parse HEAD`. Take the repository as `owner/name` from the remote's last two path segments. If there is no remote, ask which app. | |
| 9 | 2. Call the `forge` MCP server's `tell` with `repo` = that `owner/name`, `text` = the words, then a blank line, `repository: <owner/name>` and `branch: <the branch>`, and `context` = `said` (the words, verbatim) and `commit` (the HEAD id). | |
| 10 | 3. Relay in one line what it says and the issue's page. | |
| 11 | ||
| 12 | Never merge: a person lands changes. |
plugins/opencode/README.md +2
| @@ -39,3 +39,5 @@ Code Mode can also read `GET /contract/openapi.json`. | ||
| 39 | 39 | `/forge waves <app>` relays the app's newest three waves (version, date, headline), through MCP `waves`. `/forge held` says how many themes the Later gate holds and which are done, through MCP `held`; it only reads. `/forge forks <app>` says in two lines what the app follows upstream and who follows it downstream, through MCP `forks` with `kind: "chain"`. None of them lands or closes anything. |
| 40 | 40 | |
| 41 | 41 | `test/plugins.test.ts` fails when this plugin names an MCP tool the forge does not list, so a rename in `src/http/mcp.ts` cannot leave it behind. |
| 42 | ||
| 43 | **Tell from your editor.** Ask OpenCode: `use forge_tell: make the header sticky`. The plugin's `forge_tell` tool posts MCP `tell` with `repo` from `origin`, the text ending `repository: <owner/name>` and `branch: <current branch>`, and `context` `{ said, commit }` (the words and `git rev-parse HEAD`; the forge's `tell.context` accepts both, and `test/plugin-tell.test.ts` pins that against its schema). It needs `FORGE_TOKEN` (an `rw` token): the OAuth-only path has no token for it. A refusal (bad token, `ro` token, no `origin`, empty words) comes back as one sentence saying what to do. It uses the schema helper OpenCode ships, so no dependency is added; if that helper does not load, no tool is registered and one line says why. |
plugins/opencode/forge.ts +106 −2
| @@ -5,7 +5,7 @@ | ||
| 5 | 5 | * No logic lives here: the tools are the forge's own (`docs/MCP.md`). |
| 6 | 6 | */ |
| 7 | 7 | // The shape OpenCode loads; typed here so the forge need not install its SDK. |
| 8 | type Plugin = () => Promise<{ config: (config: Record<string, any>) => Promise<void> }>; | |
| 8 | type Plugin = () => Promise<{ tool?: Record<string, unknown>; config: (config: Record<string, any>) => Promise<void> }>; | |
| 9 | 9 | |
| 10 | 10 | const COMMAND = `Use the forge MCP tools for: $ARGUMENTS |
| 11 | 11 | - new <name> <words>: say the name and description back and ask the person to confirm. Only after the person says yes, call \`new_app\` with name and description (the words); relay in two lines the app's page (its url) and the next step (the first issue and who picked it up). If \`new_app\` refuses (name_taken, unverified, app_limit, repository_limit, storage_limit, no_such_agent), say its own message in one line; for name_taken, offer another name. Never retry without asking. |
| @@ -26,7 +26,109 @@ const COMMAND = `Use the forge MCP tools for: $ARGUMENTS | ||
| 26 | 26 | - forks <app>: call \`forks\` with repo and kind "chain"; say in two lines what it follows upstream (parent, grandparent, or none) and who follows it downstream (children, or none), noting a severed link. Read-only. |
| 27 | 27 | Never merge: a person lands changes.`; |
| 28 | 28 | |
| 29 | export const Forge: Plugin = async () => ({ | |
| 29 | /** Where the person is: the forge repository (owner/name, from `origin`) and the current branch. */ | |
| 30 | export interface Where { repo: string; branch: string; commit: string } | |
| 31 | ||
| 32 | /** `owner/name` from a git remote URL (https, ssh or scp form); "" when it holds none. */ | |
| 33 | export function repoOf(remote: string): string { | |
| 34 | const m = /([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/.exec(remote.trim()); | |
| 35 | return m ? `${m[1]}/${m[2]}` : ""; | |
| 36 | } | |
| 37 | ||
| 38 | /** The words of a tell: what the person said, then the repository and branch it was said on. */ | |
| 39 | export function tellBody(text: string, where: Where): { name: string; arguments: Record<string, unknown> } { | |
| 40 | const words = text.trim(); | |
| 41 | if (words === "") throw new Error("tell needs words"); | |
| 42 | if (where.repo === "") throw new Error("no forge repository: this clone has no origin remote"); | |
| 43 | return { | |
| 44 | name: "tell", | |
| 45 | arguments: { | |
| 46 | repo: where.repo, | |
| 47 | text: `${words}\n\nrepository: ${where.repo}\nbranch: ${where.branch}`, | |
| 48 | context: { said: words, ...(/^[0-9a-f]{7,64}$/.test(where.commit) ? { commit: where.commit } : {}) }, | |
| 49 | }, | |
| 50 | }; | |
| 51 | } | |
| 52 | ||
| 53 | /** Ask git (fixed arguments, no user text reaches a shell). */ | |
| 54 | function git(...args: string[]): string { | |
| 55 | const out = (globalThis as any).Bun.spawnSync(["git", ...args], { stdout: "pipe", stderr: "ignore" }); | |
| 56 | return out.exitCode === 0 ? new TextDecoder().decode(out.stdout).trim() : ""; | |
| 57 | } | |
| 58 | ||
| 59 | export const here = (): Where => ({ | |
| 60 | repo: repoOf(git("remote", "get-url", "origin")), | |
| 61 | branch: git("rev-parse", "--abbrev-ref", "HEAD"), | |
| 62 | commit: git("rev-parse", "HEAD"), | |
| 63 | }); | |
| 64 | ||
| 65 | /** The one sentence a person reads for what the forge answered (or failed to). */ | |
| 66 | export function tellAnswer(status: number, raw: string): string { | |
| 67 | if (status === 401 || status === 403) return "the forge refused the token: check FORGE_TOKEN is valid and an rw token (ro cannot tell), then try again"; | |
| 68 | if (status < 200 || status >= 300) return `the forge answered ${status}: nothing was told; try again in a moment`; | |
| 69 | let body: any; | |
| 70 | try { | |
| 71 | // An event-stream answer wraps the JSON in a `data:` line. | |
| 72 | const line = raw.split("\n").find((l) => l.startsWith("data:")); | |
| 73 | body = JSON.parse(line ? line.slice(5) : raw); | |
| 74 | } catch { | |
| 75 | return "the forge answered something unreadable: nothing was confirmed; check FORGE_URL"; | |
| 76 | } | |
| 77 | if (body?.error) return `the forge refused the tell: ${String(body.error.message ?? "unknown error").slice(0, 300)}`; | |
| 78 | const text = String(body?.result?.content?.[0]?.text ?? ""); | |
| 79 | if (body?.result?.isError) return `the forge refused the tell: ${text.slice(0, 300) || "unknown error"}`; | |
| 80 | try { | |
| 81 | const said = JSON.parse(text); | |
| 82 | if (typeof said.says === "string") return `${said.says}${typeof said.page === "string" ? ` ${said.page}` : ""}`.slice(0, 600); | |
| 83 | } catch {} | |
| 84 | return "told."; | |
| 85 | } | |
| 86 | ||
| 87 | /** Call the forge's `tell` over MCP with the token; the answer comes back as one plain sentence. */ | |
| 88 | export async function sendTell(text: string, where: Where = here(), url = process.env["FORGE_URL"], token = process.env["FORGE_TOKEN"], fetcher: typeof fetch = fetch): Promise<string> { | |
| 89 | if (!url || !token) return "forge_tell needs FORGE_URL and FORGE_TOKEN (an rw token): set both and restart OpenCode"; | |
| 90 | let params: ReturnType<typeof tellBody>; | |
| 91 | try { | |
| 92 | params = tellBody(text, where); | |
| 93 | } catch (e) { | |
| 94 | return e instanceof Error ? e.message : "nothing was told"; | |
| 95 | } | |
| 96 | try { | |
| 97 | const res = await fetcher(`${url.replace(/\/$/, "")}/mcp`, { | |
| 98 | method: "POST", | |
| 99 | headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` }, | |
| 100 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params }), | |
| 101 | }); | |
| 102 | return tellAnswer(res.status, await res.text()); | |
| 103 | } catch { | |
| 104 | return "could not reach the forge: check FORGE_URL and your connection"; | |
| 105 | } | |
| 106 | } | |
| 107 | ||
| 108 | /** Loads OpenCode's own helper; a plain specifier, resolved by OpenCode at runtime (the forge installs nothing). */ | |
| 109 | // @ts-ignore: the module exists only inside OpenCode. | |
| 110 | const openCodeHelper = (): Promise<any> => import("@opencode-ai/plugin"); | |
| 111 | ||
| 112 | /** The `forge_tell` tool, or none (said once on stderr) when OpenCode's helper cannot be loaded. */ | |
| 113 | export async function tellTools(load: () => Promise<any> = openCodeHelper, send = sendTell): Promise<Record<string, unknown>> { | |
| 114 | try { | |
| 115 | const { tool } = await load(); | |
| 116 | return { | |
| 117 | forge_tell: tool({ | |
| 118 | description: "Tell the forge's crew what to change in this repository; the request names the repository and current git branch", | |
| 119 | args: { text: tool.schema.string().describe("what to change") }, | |
| 120 | execute: async (a: { text: string }) => send(a.text), | |
| 121 | }), | |
| 122 | }; | |
| 123 | } catch (e) { | |
| 124 | console.error(`forge: no forge_tell tool, OpenCode's plugin helper did not load (${e instanceof Error ? e.message : "unknown"}); the /forge command still works`); | |
| 125 | return {}; | |
| 126 | } | |
| 127 | } | |
| 128 | ||
| 129 | /** The plugin, with the helper loader injectable; OpenCode calls `Forge`, which passes it its own context, never a loader. */ | |
| 130 | export const forgePlugin = (load?: () => Promise<any>): Plugin => async () => ({ | |
| 131 | tool: await tellTools(load), | |
| 30 | 132 | config: async (config: Record<string, any>) => { |
| 31 | 133 | const url = process.env["FORGE_URL"]; |
| 32 | 134 | const token = process.env["FORGE_TOKEN"]; |
| @@ -47,4 +149,6 @@ export const Forge: Plugin = async () => ({ | ||
| 47 | 149 | }, |
| 48 | 150 | }); |
| 49 | 151 | |
| 152 | export const Forge: Plugin = forgePlugin(); | |
| 153 | ||
| 50 | 154 | export default Forge; |
test/plugin-tell.test.ts added +109
| @@ -0,0 +1,109 @@ | ||
| 1 | /** The plugins' tell names the repository and the current branch in the request body. */ | |
| 2 | import { expect, test } from "bun:test"; | |
| 3 | import { readFileSync } from "node:fs"; | |
| 4 | import { forgePlugin, repoOf, sendTell, tellAnswer, tellBody, tellTools } from "../plugins/opencode/forge.ts"; | |
| 5 | import { parseContext } from "../src/actions/tell_context.ts"; | |
| 6 | import { tool as tellTool } from "../src/http/mcp/tools/tell.ts"; | |
| 7 | ||
| 8 | const where = { repo: "alice/game", branch: "feature/x", commit: "abc1234" }; | |
| 9 | ||
| 10 | test("repoOf reads owner/name from https and ssh remotes", () => { | |
| 11 | expect(repoOf("https://forge.example/alice/game.git")).toBe("alice/game"); | |
| 12 | expect(repoOf("ssh://[email protected]:2222/alice/game")).toBe("alice/game"); | |
| 13 | expect(repoOf("")).toBe(""); | |
| 14 | }); | |
| 15 | ||
| 16 | test("the tell body names the repository and the branch", () => { | |
| 17 | const { name, arguments: a } = tellBody("make it blue", where); | |
| 18 | expect(name).toBe("tell"); | |
| 19 | expect(a["repo"]).toBe("alice/game"); | |
| 20 | expect(a["text"]).toContain("repository: alice/game"); | |
| 21 | expect(a["text"]).toContain("branch: feature/x"); | |
| 22 | expect(() => tellBody(" ", where)).toThrow(); | |
| 23 | expect(() => tellBody("x", { ...where, repo: "" })).toThrow(); | |
| 24 | }); | |
| 25 | ||
| 26 | test("sendTell posts that body to /mcp with the bearer", async () => { | |
| 27 | let seen: any; | |
| 28 | const f = (async (u: string, init: any) => ((seen = { u, init }), new Response("ok"))) as any; | |
| 29 | await sendTell("hi", where, "https://f.example/", "tok", f); | |
| 30 | expect(seen.u).toBe("https://f.example/mcp"); | |
| 31 | expect(seen.init.headers.authorization).toBe("Bearer tok"); | |
| 32 | const body = JSON.parse(seen.init.body); | |
| 33 | expect(body.params.arguments.text).toContain("branch: feature/x"); | |
| 34 | }); | |
| 35 | ||
| 36 | test("/forge-tell says repository and branch", () => { | |
| 37 | const md = readFileSync(new URL("../plugins/claude-code/commands/forge-tell.md", import.meta.url), "utf8"); | |
| 38 | expect(md).toContain("repository: <owner/name>"); | |
| 39 | expect(md).toContain("branch: <the branch>"); | |
| 40 | }); | |
| 41 | ||
| 42 | const rpc = (result: unknown) => JSON.stringify({ jsonrpc: "2.0", id: 1, result }); | |
| 43 | const send = (status: number, body: string) => sendTell("hi", where, "https://f.example", "tok", (async () => new Response(body, { status })) as any); | |
| 44 | ||
| 45 | test("a 401 is one plain sentence about the token, not JSON", async () => { | |
| 46 | const said = await send(401, '{"error":"unauthorized"}'); | |
| 47 | expect(said).toContain("refused the token"); | |
| 48 | expect(said).toContain("rw"); | |
| 49 | expect(said).not.toContain("{"); | |
| 50 | }); | |
| 51 | ||
| 52 | test("an isError answer and a JSON-RPC error say what the forge said", async () => { | |
| 53 | expect(await send(200, rpc({ isError: true, content: [{ type: "text", text: "token is read-only" }] }))).toBe("the forge refused the tell: token is read-only"); | |
| 54 | expect(await send(200, JSON.stringify({ jsonrpc: "2.0", id: 1, error: { code: -32000, message: "nope" } }))).toBe("the forge refused the tell: nope"); | |
| 55 | expect(await send(500, "boom")).toContain("500"); | |
| 56 | expect(await send(200, "<html>")).toContain("unreadable"); | |
| 57 | }); | |
| 58 | ||
| 59 | test("a told answer relays the forge's sentence and page", () => { | |
| 60 | const text = JSON.stringify({ says: "Told.", page: "https://f.example/alice/game/issues/3" }); | |
| 61 | expect(tellAnswer(200, rpc({ content: [{ type: "text", text }] }))).toBe("Told. https://f.example/alice/game/issues/3"); | |
| 62 | }); | |
| 63 | ||
| 64 | test("a network failure is said in words", async () => { | |
| 65 | const said = await sendTell("hi", where, "https://f.example", "tok", (async () => { throw new Error("x"); }) as any); | |
| 66 | expect(said).toContain("could not reach"); | |
| 67 | }); | |
| 68 | ||
| 69 | const fakeHelper = async () => ({ tool: Object.assign((d: any) => d, { schema: { string: () => ({ describe: () => "string" }) } }) }); | |
| 70 | ||
| 71 | test("forge_tell's execute answers empty words and a missing remote in words", async () => { | |
| 72 | let n = 0; | |
| 73 | const tools: any = await tellTools(fakeHelper, (t) => (n++, sendTell(t, { ...where, repo: "" }, "https://f.example", "tok", (async () => new Response("")) as any))); | |
| 74 | expect(await tools.forge_tell.execute({ text: "x" })).toContain("no forge repository"); | |
| 75 | const blank: any = await tellTools(fakeHelper, (t) => sendTell(t, where, "https://f.example", "tok")); | |
| 76 | expect(await blank.forge_tell.execute({ text: " " })).toBe("tell needs words"); | |
| 77 | expect(n).toBe(1); | |
| 78 | }); | |
| 79 | ||
| 80 | test("Forge registers forge_tell with the helper and none, said once, without it", async () => { | |
| 81 | const withHelper = await forgePlugin(fakeHelper)(); | |
| 82 | expect(Object.keys(withHelper.tool!)).toEqual(["forge_tell"]); | |
| 83 | expect((withHelper.tool as any).forge_tell.args).toHaveProperty("text"); | |
| 84 | const seen: string[] = []; | |
| 85 | const log = console.error; | |
| 86 | console.error = (m: string) => void seen.push(m); | |
| 87 | try { | |
| 88 | const without = await forgePlugin(async () => { throw new Error("not found"); })(); | |
| 89 | expect(without.tool).toEqual({}); | |
| 90 | expect(typeof without.config).toBe("function"); | |
| 91 | } finally { | |
| 92 | console.error = log; | |
| 93 | } | |
| 94 | expect(seen).toHaveLength(1); | |
| 95 | expect(seen[0]).toContain("no forge_tell tool"); | |
| 96 | }); | |
| 97 | ||
| 98 | test("the server's tell takes the context keys the plugin sends", () => { | |
| 99 | const { arguments: a } = tellBody("x", where); | |
| 100 | const keys = Object.keys((tellTool.inputSchema as any).properties.context.properties); | |
| 101 | for (const k of Object.keys(a["context"] as object)) expect(keys).toContain(k); | |
| 102 | expect(parseContext(a["context"])).toEqual({ said: "x", commit: "abc1234" }); | |
| 103 | }); | |
| 104 | ||
| 105 | test("/forge-tell has its argument hint and names MCP tool tell", () => { | |
| 106 | const md = readFileSync(new URL("../plugins/claude-code/commands/forge-tell.md", import.meta.url), "utf8"); | |
| 107 | expect(md).toContain("argument-hint: <words>"); | |
| 108 | expect(md).toContain("`tell`"); | |
| 109 | }); |
test/plugins.test.ts +7
| @@ -29,6 +29,13 @@ const toolsNamed = (text: string): string[] => [...new Set(backticked(text))].fi | ||
| 29 | 29 | |
| 30 | 30 | const tools = new Set(toolNames()); |
| 31 | 31 | |
| 32 | test("plugins/claude-code/commands/forge-tell.md names only tools the forge has", () => { | |
| 33 | const text = read("plugins/claude-code/commands/forge-tell.md").replace(/^---\n[\s\S]*?\n---\n/, ""); | |
| 34 | const named = toolsNamed(text); | |
| 35 | expect(named).toContain("tell"); | |
| 36 | expect(named.filter((n) => !tools.has(n))).toEqual([]); | |
| 37 | }); | |
| 38 | ||
| 32 | 39 | for (const [label, text] of [ |
| 33 | 40 | ["plugins/claude-code/commands/forge.md", claudeText], |
| 34 | 41 | ["plugins/opencode/forge.ts", opencodeText], |
new above
offline
Non-blocking: the empty catch hides an unparsable success body and then reports "told.". Return a sentence that says the page is unknown.