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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/15083-the-opencode-and-claude-code-plugins-eac → main 2 commits fork 1 thread · 1 unresolved

  • Merged. scout/15083-the-opencode-and-claude-code-plugins-eac was merged into main as 24dd0c8.

Review

Sign in to review this change.
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
3838 `/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.
3939
4040 `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`.
3939 `/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.
4040
4141 `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 @@
55 * No logic lives here: the tools are the forge's own (`docs/MCP.md`).
66 */
77 // 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> }>;
99
1010 const COMMAND = `Use the forge MCP tools for: $ARGUMENTS
1111 - 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
2626 - 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.
2727 Never merge: a person lands changes.`;
2828
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)}`;

Non-blocking: the empty catch hides an unparsable success body and then reports "told.". Return a sentence that says the page is unknown.

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),
30132 config: async (config: Record<string, any>) => {
31133 const url = process.env["FORGE_URL"];
32134 const token = process.env["FORGE_TOKEN"];
@@ -47,4 +149,6 @@ export const Forge: Plugin = async () => ({
47149 },
48150 });
49151
152 export const Forge: Plugin = forgePlugin();
153
50154 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
2929
3030 const tools = new Set(toolNames());
3131
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
3239 for (const [label, text] of [
3340 ["plugins/claude-code/commands/forge.md", claudeText],
3441 ["plugins/opencode/forge.ts", opencodeText],

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs