@retasc/cli 1.38.2 → 1.39.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.39.0 (2026-08-30)
+
+- **RTSC-793** — `retasc setup` now wires Cursor, OpenCode and Gemini CLI too, bringing it
+  to six harnesses. Until this release those three could be installed and running on your
+  machine and `setup` would say nothing about them: it only ever named harnesses it already
+  knew, so an unsupported one was not reported as skipped, it was invisible, and the receipt
+  read as complete. That is the same silent half-install the previous release existed to end,
+  one harness over.
+  Each was admitted the same way the first three were, by checking a real installation rather
+  than a config format from memory. The check that decides it is whether the harness starts
+  its MCP server in the project directory, because the entry we write names no project and
+  works out the folder for itself; one that started somewhere else would resolve every folder
+  to the same wrong place with no symptom. All three passed.
+  Cursor is wired by editing `~/.cursor/mcp.json` directly, and carefully: that file is named
+  .json but Cursor accepts comments in it, so we splice our entry in textually and leave every
+  comment, every other server and everything else exactly where it was. OpenCode and Gemini
+  are wired through their own `opencode mcp add` and `gemini mcp add`, which is better than a
+  writer of ours when a harness ships one that works: their file format stays their business.
+  Note for Cursor users: it is `cursor-agent`, the agent, that gets the tools. The `cursor`
+  command is the editor launcher and is a different program.
+  Also fixed: the setup receipt could run a path into the word beside it, printing
+  `~/.codex/config.tomlupdated`, which read like a corrupted path in the one place whose job
+  is to say plainly that everything worked.
+
 ## 1.38.2 (2026-08-30)
 
 - **RTSC-789** — `bind` keeps this folder's key instead of minting a new one on every run.

package/dist/commands/setup.js

@@ -66,8 +66,12 @@ export function runSetup(opts) {
 export function printSetup(r) {
     if (!r.wired.length && !r.failed.length) {
         console.log("No MCP harness found on this machine.");
-        console.log("Install Claude Code, Codex or Grok and run `retasc setup` again, or bind a folder\n" +
-            "with `retasc bind` and paste the config block it prints into your own client.");
+        // Named from the registry rather than a hand-kept list: RTSC-780 shipped three and
+        // RTSC-793 added three more, and a sentence naming only the original three would have
+        // told a Cursor user to install Codex.
+        console.log(`Install one of ${HARNESSES.map((h) => h.label).join(", ")} and run \`retasc setup\` again,\n` +
+            "or bind a folder with `retasc bind` and paste the config block it prints into your\n" +
+            "own client.");
         return;
     }
     console.log("\n" +

package/dist/lib/card.js

@@ -50,8 +50,14 @@ export function card(title, rows, footer) {
         // A note sits in a third column, so the values stay in one scannable rail. Without a
         // note the value simply runs on — padding it anyway would leave a trench of spaces
         // in the middle of the card.
+        //
+        // The value is fitted one column NARROWER than its rail so a gutter always survives.
+        // `fit` pads to exactly VALUE, so a value of exactly that width, or one ellipsed to
+        // it, butted straight against the note: `~/.codex/config.tomlupdated`. It read as a
+        // corrupted path in the one surface whose job is to say calmly that this worked
+        // (RTSC-793 — RTSC-780's three rows all happened to be shorter).
         const body = r.note
-            ? `${fit(r.label, LABEL)}${fit(r.value, VALUE)}${r.note}`
+            ? `${fit(r.label, LABEL)}${fit(r.value, VALUE - 1)} ${r.note}`
             : `${fit(r.label, LABEL)}${r.value}`;
         out.push(line(body));
     }

package/dist/lib/harness.js

@@ -13,10 +13,16 @@
 // with cwd set to the project directory, so the proxy can resolve the folder itself.
 //
 // Adding a harness is one entry in HARNESSES. Deliberately NOT populated from theory:
-// each entry here was checked against a real installation. Cursor, Windsurf, Gemini CLI,
-// OpenCode and VS Code all have a known config shape and belong here, but writing an
-// unverified serializer into somebody's global agent config is not a thing to ship on a
-// guess — they go in as each is confirmed.
+// every entry here was checked against a real installation, and the check that gates
+// admission is the cwd one — a harness whose stdio server does not start in the project
+// directory cannot use the `auto` marker at all, because one global entry would then
+// resolve every folder to the same wrong place, silently.
+//
+// Verified so far: Claude Code, Codex, Grok (RTSC-780), then Cursor, OpenCode and Gemini
+// CLI (RTSC-793), each confirmed by wiring a probe server that logs process.cwd() and
+// running the harness from two different directories. Windsurf and VS Code are NOT
+// candidates: they are editors, not agent harnesses, and were dropped from RTSC-780's
+// original map rather than left sitting in it forever.
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -147,22 +153,186 @@ function tomlHarness(id, label, path, bin) {
         },
     };
 }
-// --- JSON (./.mcp.json in the folder) ---------------------------------------
-/** Merge the retasc entry into a `{ mcpServers: {…} }` document, leaving every
- *  other server and unknown key byte-for-byte where it was. */
-export function mergeMcpServers(before, entry) {
-    let doc = {};
-    if (before.trim()) {
-        try {
-            doc = JSON.parse(before);
+// --- JSONC (Cursor) ---------------------------------------------------------
+// `~/.cursor/mcp.json` is named .json and is NOT parsed as JSON: cursor-agent reads a
+// file containing `// comments` without complaint (verified against a real install,
+// RTSC-793). So the same rule the TOML splice follows applies here — this is the user's
+// own config, and a JSON.parse/JSON.stringify round-trip would silently delete every
+// comment in it and reflow the rest.
+//
+// Hence a textual splice, and hence the small JSONC scanner below rather than a parser
+// dependency. It only ever has to find one member and replace its value; everything it
+// does not understand it steps over untouched, which is exactly the property we want
+// from something editing a file we did not write.
+/** Step over whitespace and JSONC comments, returning the next index that is neither. */
+function skipTrivia(text, i) {
+    for (;;) {
+        while (i < text.length && /\s/.test(text[i]))
+            i++;
+        if (text.startsWith("//", i)) {
+            const nl = text.indexOf("\n", i);
+            i = nl === -1 ? text.length : nl + 1;
+            continue;
         }
-        catch {
-            doc = {};
+        if (text.startsWith("/*", i)) {
+            const end = text.indexOf("*/", i + 2);
+            i = end === -1 ? text.length : end + 2;
+            continue;
+        }
+        return i;
+    }
+}
+/** `i` points at the opening quote. Returns the index just past the closing quote. */
+function endOfString(text, i) {
+    i++;
+    while (i < text.length) {
+        if (text[i] === "\\")
+            i += 2;
+        else if (text[i] === '"')
+            return i + 1;
+        else
+            i++;
+    }
+    return i;
+}
+/** `i` points at the first character of a value. Returns the index just past it.
+ *  Nesting is tracked so an object value containing commas ends in the right place. */
+function endOfValue(text, i) {
+    i = skipTrivia(text, i);
+    if (text[i] === '"')
+        return endOfString(text, i);
+    if (text[i] === "{" || text[i] === "[") {
+        let depth = 0;
+        while (i < text.length) {
+            const c = text[i];
+            if (c === '"') {
+                i = endOfString(text, i);
+                continue;
+            }
+            if (c === "/" && (text[i + 1] === "/" || text[i + 1] === "*")) {
+                i = skipTrivia(text, i);
+                continue;
+            }
+            if (c === "{" || c === "[")
+                depth++;
+            else if (c === "}" || c === "]") {
+                depth--;
+                if (depth === 0)
+                    return i + 1;
+            }
+            i++;
         }
+        return i;
     }
-    doc.mcpServers = doc.mcpServers ?? {};
-    doc.mcpServers[SERVER_NAME] = entry;
-    return JSON.stringify(doc, null, 2) + "\n";
+    while (i < text.length && !/[,}\]\s]/.test(text[i]))
+        i++;
+    return i;
+}
+/**
+ * The members of the object whose `{` is at `open`, with the span of each value.
+ *
+ * `advance` is load-bearing, not defensive tidiness. `endOfValue` stops AT its
+ * terminator set, so on a character already in that set (a stray `]`) it returns the
+ * index it was handed, and a loop that trusted it would spin forever. That input is not
+ * exotic: this parses a file a human hand-edits, and a dropped bracket is the ordinary
+ * way one gets malformed. `retasc setup` hanging with no output, taking `bind` and the
+ * whole of onboarding with it, is a far worse failure than any misparse — so every path
+ * through this loop moves at least one character, and a document we cannot understand
+ * ends as a document we scanned to the end of.
+ */
+function membersOf(text, open) {
+    const members = [];
+    let i = open + 1;
+    const advance = (next) => (next > i ? next : i + 1);
+    for (;;) {
+        i = skipTrivia(text, i);
+        if (i >= text.length || text[i] === "}")
+            return { members };
+        if (text[i] === ",") {
+            i++;
+            continue;
+        }
+        if (text[i] !== '"') {
+            i = advance(endOfValue(text, i));
+            continue;
+        }
+        const start = i;
+        const keyEnd = endOfString(text, i);
+        const name = text.slice(start + 1, keyEnd - 1);
+        const j = skipTrivia(text, keyEnd);
+        if (text[j] !== ":") {
+            i = advance(keyEnd);
+            continue;
+        }
+        const valueStart = skipTrivia(text, j + 1);
+        const valueEnd = endOfValue(text, valueStart);
+        members.push({ name, start, valueStart, valueEnd });
+        i = advance(valueEnd);
+    }
+}
+/** The first top-level `{`, or -1 if this document has no root object. */
+function rootObject(text) {
+    const i = skipTrivia(text, 0);
+    return text[i] === "{" ? i : -1;
+}
+/**
+ * Put `value` at `mcpServers.<name>`, leaving every comment, every other server and
+ * every unknown key exactly where they were.
+ *
+ * Three cases, in the order they are cheapest to be sure about: no usable document at
+ * all (write a fresh one), a document with no `mcpServers` (insert the whole object),
+ * and a document that already has one (replace our member's value, or insert it).
+ */
+export function spliceJsonServer(text, name, value) {
+    const indent = (s, by) => s.split("\n").join(`\n${by}`);
+    const root = rootObject(text);
+    if (root === -1) {
+        return `{\n  "mcpServers": {\n    ${JSON.stringify(name)}: ${indent(value, "    ")}\n  }\n}\n`;
+    }
+    const { members } = membersOf(text, root);
+    const servers = members.find((m) => m.name === "mcpServers");
+    if (!servers) {
+        const block = `"mcpServers": {\n    ${JSON.stringify(name)}: ${indent(value, "    ")}\n  }`;
+        // A trailing comma is only correct if something follows; an empty root gets neither.
+        const sep = members.length ? ",\n  " : "\n  ";
+        const head = members.length ? text.slice(0, members[0].start) : text.slice(0, root + 1);
+        const tail = members.length ? text.slice(members[0].start) : text.slice(root + 1);
+        return members.length
+            ? `${head}${block}${sep}${tail}`
+            : `${head}${sep}${block}\n${tail}`;
+    }
+    // `mcpServers` present but not an OBJECT. Scanning on would treat the rest of the
+    // document as its members and splice our entry one character into a number or a
+    // string, writing a corrupt file over a config we were handed intact — the one
+    // outcome this whole textual approach exists to prevent. We own this key, and a
+    // non-object here is already meaningless to every harness that reads it, so replace
+    // the value wholesale and leave the rest of the document alone.
+    if (text[servers.valueStart] !== "{") {
+        const fresh = `{\n    ${JSON.stringify(name)}: ${indent(value, "    ")}\n  }`;
+        return text.slice(0, servers.valueStart) + fresh + text.slice(servers.valueEnd);
+    }
+    const inner = membersOf(text, servers.valueStart);
+    const mine = inner.members.find((m) => m.name === name);
+    if (mine) {
+        return text.slice(0, mine.valueStart) + indent(value, "    ") + text.slice(mine.valueEnd);
+    }
+    const at = servers.valueStart + 1;
+    const insert = `\n    ${JSON.stringify(name)}: ${indent(value, "    ")}${inner.members.length ? "," : ""}`;
+    return text.slice(0, at) + insert + text.slice(at);
+}
+/** True when `mcpServers.<name>` is already present — the receipt's "updated" vs "new". */
+export function hasJsonServer(text, name) {
+    const root = rootObject(text);
+    if (root === -1)
+        return false;
+    const servers = membersOf(text, root).members.find((m) => m.name === "mcpServers");
+    if (!servers || text[servers.valueStart] !== "{")
+        return false;
+    return membersOf(text, servers.valueStart).members.some((m) => m.name === name);
+}
+/** Our entry, in the shape Cursor reads: command + args + env. */
+export function jsonServerValue(entry) {
+    return JSON.stringify({ command: entry.command, args: entry.args, env: entry.env }, null, 2);
 }
 // --- Claude Code ------------------------------------------------------------
 /**
@@ -217,11 +387,139 @@ const claudeCode = {
         return { ok: true, path: "Claude Code (user scope)", replaced: had.status === 0 };
     },
 };
+// --- Cursor -----------------------------------------------------------------
+/**
+ * `cursor-agent`, NOT `cursor`.
+ *
+ * They are two different binaries and only one of them is a harness: `cursor` is the
+ * VS Code-style IDE launcher (`--diff`, `--merge`, `--goto`), while `cursor-agent` is
+ * the agent, and `cursor-agent mcp login` names `.cursor/mcp.json` or `~/.cursor/mcp.json`
+ * as where it reads servers from. Detecting on `cursor` would report a harness we had
+ * not wired anything usable into.
+ *
+ * The one adapter here that writes its own file: `cursor-agent mcp` offers login, list,
+ * enable and disable, but no `add`.
+ */
+const cursor = {
+    id: "cursor",
+    label: "Cursor",
+    configPath: () => join(home(), ".cursor", "mcp.json"),
+    detect: () => existsSync(join(home(), ".cursor")) || onPath("cursor-agent"),
+    install(entry) {
+        const p = join(home(), ".cursor", "mcp.json");
+        const before = readIfExists(p);
+        try {
+            writeConfig(p, spliceJsonServer(before, SERVER_NAME, jsonServerValue(entry)));
+        }
+        catch (e) {
+            return { ok: false, reason: String(e?.message ?? e) };
+        }
+        return { ok: true, path: p, replaced: hasJsonServer(before, SERVER_NAME) };
+    },
+};
+// --- harnesses with their own `mcp add` -------------------------------------
+/**
+ * OpenCode and Gemini both ship the thing Claude Code ships and Codex, Grok and Cursor
+ * do not: a supported command for this. Each was checked against a real install
+ * (RTSC-793) for the three properties that decide whether calling it beats writing the
+ * file ourselves, and both have all three: it preserves comments and key order, it
+ * leaves other servers and unknown keys alone, and re-adding the same name REPLACES
+ * rather than failing (so `runSetup` on every bind stays idempotent).
+ *
+ * Given that, shelling out is strictly better than a serializer of ours: their config
+ * format is theirs to change, and a format change breaks our writer silently while
+ * their own command keeps working.
+ *
+ * `replaced` is read from the file rather than from what the command prints, so the
+ * receipt does not depend on anybody's wording staying put.
+ */
+function addCommandHarness(opts) {
+    return {
+        id: opts.id,
+        label: opts.label,
+        configPath: opts.configPath,
+        // Gated on RETASC_HOME for the same reason Claude Code is: this shells out to a
+        // command that resolves the REAL home, so a test home has to stop it at DETECTION.
+        // An undetected harness is never installed into.
+        detect: () => !process.env.RETASC_HOME && onPath(opts.bin),
+        install(entry) {
+            const before = readIfExists(opts.configPath());
+            const r = spawnSync(opts.bin, opts.args(entry), { encoding: "utf8" });
+            if (r.error)
+                return { ok: false, reason: r.error.message };
+            if (r.status !== 0) {
+                const msg = (r.stderr || r.stdout || "").trim().split("\n").pop() || `exited ${r.status}`;
+                return { ok: false, reason: msg };
+            }
+            return {
+                ok: true,
+                path: opts.configPath(),
+                replaced: before.includes(`"${SERVER_NAME}"`),
+            };
+        },
+    };
+}
+/** `~/.config/opencode/`, XDG-aware — OpenCode honours XDG_CONFIG_HOME, so resolving it
+ *  to `~/.config` unconditionally would name the wrong file in the receipt. */
+function opencodeConfig() {
+    const xdg = process.env.XDG_CONFIG_HOME || join(home(), ".config");
+    return join(xdg, "opencode", "opencode.jsonc");
+}
+/**
+ * `opencode mcp add <name> --env K=V -- <command> <args...>`.
+ *
+ * The `--` is required: without a URL or a command after it, `add` refuses. Note the
+ * stored shape is unlike every other harness here — the key is `mcp` rather than
+ * `mcpServers`, it carries `"type": "local"`, `command` is ONE array of command plus
+ * args, and env is spelled `environment`. A generic mcpServers writer would produce a
+ * file OpenCode ignores, which is the other half of why this one shells out.
+ */
+const opencode = addCommandHarness({
+    id: "opencode",
+    label: "OpenCode",
+    bin: "opencode",
+    configPath: opencodeConfig,
+    args: (entry) => [
+        "mcp", "add", SERVER_NAME,
+        ...Object.entries(entry.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]),
+        "--", entry.command, ...entry.args,
+    ],
+});
+/**
+ * `gemini mcp add -s user -t stdio -e K=V <name> <command> <args...>`.
+ *
+ * Scope `user`, for the reason the whole marker exists: one entry, correct in every
+ * folder. The default is `project`, which would write a `.gemini/` into whichever
+ * directory `retasc setup` happened to run in.
+ *
+ * Two Gemini quirks, neither ours to fix but both worth knowing before someone reports
+ * them as our bug. `gemini mcp list` reports a freshly added server as `Disabled` and
+ * `gemini mcp enable <name>` answers `Server not found` for it — yet the server does
+ * start and connect on a real run, so `list` is not a verification signal. And Gemini
+ * gates on trusted folders: in an untrusted directory it refuses to start and NO MCP
+ * server loads, which looks exactly like a failed install.
+ */
+const gemini = addCommandHarness({
+    id: "gemini",
+    label: "Gemini CLI",
+    bin: "gemini",
+    configPath: () => join(home(), ".gemini", "settings.json"),
+    args: (entry) => [
+        "mcp", "add",
+        "-s", "user",
+        "-t", "stdio",
+        ...Object.entries(entry.env).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
+        SERVER_NAME, entry.command, ...entry.args,
+    ],
+});
 // --- the registry -----------------------------------------------------------
 export const HARNESSES = [
     claudeCode,
     tomlHarness("codex", "Codex", () => join(home(), ".codex", "config.toml"), "codex"),
     tomlHarness("grok", "Grok", () => join(home(), ".grok", "config.toml"), "grok"),
+    cursor,
+    opencode,
+    gemini,
 ];
 /** Every harness actually present on this machine. */
 export function detectHarnesses(list = HARNESSES) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.38.2",
+  "version": "1.39.0",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {