tandem-editor 0.11.2 → 0.12.0

package/README.md

@@ -41,7 +41,7 @@ claude plugin marketplace add bloknayrb/tandem
 claude plugin install tandem@tandem-editor
 ```
 
-**Tandem must be running on the host before the plugin can do anything.** The plugin spawns two stdio MCP processes (`tandem mcp-stdio` and `tandem channel`) that proxy to `http://localhost:3479`. If the server isn't up they fail fast and log "Tandem server not reachable at …". Start the Tauri desktop app or run `tandem start` on the host first, then open Claude.
+**Tandem must be running on the host before the plugin can do anything.** The plugin spawns two stdio MCP processes (`tandem mcp-stdio` and `tandem channel`) that proxy to `http://127.0.0.1:3479`. If the server isn't up they fail fast and log "Tandem server not reachable at …". Start the Tauri desktop app or run `tandem start` on the host first, then open Claude.
 
 ### Legacy stdio channel shim
 
@@ -116,7 +116,7 @@ npm run doctor    # checks Node.js, MCP config, server health, ports
 Or check the raw health endpoint:
 
 ```bash
-curl http://localhost:3479/health
+curl http://127.0.0.1:3479/health
 # → {"status":"ok","version":"0.8.0","transport":"http","hasSession":false}
 ```
 
@@ -132,7 +132,7 @@ npm install
 npm run dev:standalone   # starts backend (:3478/:3479), editor client (:5173), and monitor
 ```
 
-Open <http://localhost:5173> — you'll see `sample/welcome.md` loaded automatically on first run. The `.mcp.json` in the repo configures Claude Code automatically when run from this directory.
+Open <http://127.0.0.1:5173> — you'll see `sample/welcome.md` loaded automatically on first run. The `.mcp.json` in the repo configures Claude Code automatically when run from this directory.
 
 </details>
 
@@ -197,12 +197,12 @@ See the full [Roadmap](docs/roadmap.md) and [Known Limitations](docs/roadmap.md#
 ## Documentation
 
 - **[User Guide](docs/user-guide.md)** — How to use Tandem: editor UI, annotations, chat, review mode, keyboard shortcuts
-- [MCP Tool Reference](docs/mcp-tools.md) — 28 MCP tools (25 active, 3 deprecated stubs) + channel API endpoints
+- [MCP Tool Reference](docs/mcp-tools.md) — 29 MCP tools (26 active, 3 deprecated stubs) + channel API endpoints
 - [Architecture](docs/architecture.md) — System design, data flows, coordinate systems, channel push
 - [Workflows](docs/workflows.md) — Claude Code usage patterns: text iteration, cross-referencing, multi-model
 - [Roadmap](docs/roadmap.md) — Phase 2+ roadmap, known issues, future extensions
-- [Design Decisions](docs/decisions.md) — ADR-001 through ADR-024
-- [Lessons Learned](docs/lessons-learned.md) — 48 implementation lessons
+- [Design Decisions](docs/decisions.md) — ADR-001 through ADR-030
+- [Lessons Learned](docs/lessons-learned.md) — 73 implementation lessons
 
 ## CLI Commands
 
@@ -231,12 +231,12 @@ Tandem registers two MCP connections: **HTTP** for document tools (28 tools incl
   "mcpServers": {
     "tandem": {
       "type": "http",
-      "url": "http://localhost:3479/mcp"
+      "url": "http://127.0.0.1:3479/mcp"
     },
     "tandem-channel": {
       "command": "npx",
       "args": ["tsx", "src/channel/index.ts"],
-      "env": { "TANDEM_URL": "http://localhost:3479" }
+      "env": { "TANDEM_URL": "http://127.0.0.1:3479" }
     }
   }
 }
@@ -252,7 +252,7 @@ All optional — defaults work out of the box.
 | ---------------------------------- | ----------------------- | --------------------------------------------------------------- |
 | `TANDEM_PORT`                      | `3478`                  | Hocuspocus WebSocket port                                       |
 | `TANDEM_MCP_PORT`                  | `3479`                  | MCP HTTP + REST API port                                        |
-| `TANDEM_URL`                       | `http://localhost:3479` | Channel shim server URL                                         |
+| `TANDEM_URL`                       | `http://127.0.0.1:3479` | Channel shim server URL                                         |
 | `TANDEM_TRANSPORT`                 | `http`                  | Transport mode (`http` or `stdio`)                              |
 | `TANDEM_NO_SAMPLE`                 | unset                   | Set to `1` to skip auto-opening `sample/welcome.md`             |
 | `TANDEM_CLAUDE_CMD`                | `claude`                | Claude Code executable name (for `tandem setup` auto-detection) |

package/dist/channel/index.js

@@ -17993,13 +17993,19 @@ var StdioServerTransport = class {
   }
 };
 
+// src/shared/api-paths.ts
+var API_EVENTS = "/api/events";
+var API_CHANNEL_AWARENESS = "/api/channel-awareness";
+var API_CHANNEL_ERROR = "/api/channel-error";
+var API_CHANNEL_REPLY = "/api/channel-reply";
+var API_CHANNEL_PERMISSION = "/api/channel-permission";
+var API_MODE = "/api/mode";
+
 // src/shared/constants.ts
 var DEFAULT_MCP_PORT = 3479;
 var TANDEM_REPO_URL = "https://github.com/bloknayrb/tandem";
 var TANDEM_ISSUES_NEW_URL = `${TANDEM_REPO_URL}/issues/new`;
 var MAX_FILE_SIZE = 50 * 1024 * 1024;
-var MAX_WS_PAYLOAD = 10 * 1024 * 1024;
-var IDLE_TIMEOUT = 30 * 60 * 1e3;
 var SESSION_MAX_AGE = 30 * 24 * 60 * 60 * 1e3;
 var CHANNEL_MAX_RETRIES = 5;
 var CHANNEL_RETRY_DELAY_MS = 2e3;
@@ -18030,7 +18036,7 @@ function resolveTandemUrlCandidate(override) {
   for (const url of candidates) {
     if (url !== void 0 && url.trim() !== "") return url.trim();
   }
-  return `http://localhost:${DEFAULT_MCP_PORT}`;
+  return `http://127.0.0.1:${DEFAULT_MCP_PORT}`;
 }
 function resolveAuthTokenCandidate(override) {
   const candidates = [
@@ -18186,6 +18192,33 @@ function formatEventMeta(event) {
   return meta;
 }
 
+// src/shared/types.ts
+var AnnotationTypeSchema = external_exports.enum(["highlight", "note", "comment"]);
+var AnnotationStatusSchema = external_exports.enum(["pending", "accepted", "dismissed"]);
+var HighlightColorSchema = external_exports.enum(["yellow", "green", "blue", "pink"]);
+var SeveritySchema = external_exports.enum(["info", "warning", "error", "success"]);
+var TandemModeSchema = external_exports.enum(["solo", "tandem"]);
+var AuthorSchema = external_exports.enum(["user", "claude", "import"]);
+var ReplyAuthorSchema = external_exports.enum(["user", "claude"]);
+var AnnotationActionSchema = external_exports.enum(["accept", "dismiss"]);
+var ExportFormatSchema = external_exports.enum(["markdown", "json"]);
+var DocumentFormatSchema = external_exports.enum(["md", "txt", "html", "docx"]);
+var ToolErrorCodeSchema = external_exports.enum([
+  "RANGE_GONE",
+  "RANGE_MOVED",
+  "FILE_LOCKED",
+  "FILE_NOT_FOUND",
+  "NO_DOCUMENT",
+  "INVALID_RANGE",
+  "INVALID_ARGUMENT",
+  "NOT_FOUND",
+  "ANNOTATION_RESOLVED",
+  "FORMAT_ERROR",
+  "PERMISSION_DENIED"
+]);
+var ChannelErrorCodeSchema = external_exports.enum(["CHANNEL_CONNECT_FAILED", "MONITOR_CONNECT_FAILED"]);
+var CHANNEL_CONNECT_FAILED = "CHANNEL_CONNECT_FAILED";
+
 // src/channel/event-bridge.ts
 var AWARENESS_DEBOUNCE_MS = 500;
 var MODE_CACHE_TTL_MS = 2e3;
@@ -18208,12 +18241,12 @@ async function startEventBridge(mcp, tandemUrl) {
         console.error("[Channel] SSE connection exhausted, reporting error and exiting");
         try {
           await fetchWithTimeout(
-            `${tandemUrl}/api/channel-error`,
+            `${tandemUrl}${API_CHANNEL_ERROR}`,
             {
               method: "POST",
               headers: { "Content-Type": "application/json" },
               body: JSON.stringify({
-                error: "CHANNEL_CONNECT_FAILED",
+                error: CHANNEL_CONNECT_FAILED,
                 message: `Channel shim lost connection after ${CHANNEL_MAX_RETRIES} retries.`
               })
             },
@@ -18222,7 +18255,7 @@ async function startEventBridge(mcp, tandemUrl) {
         } catch (reportErr) {
           console.error(
             "[Channel] Could not report failure to server:",
-            describeFetchError(reportErr, "/api/channel-error", CHANNEL_ERROR_REPORT_TIMEOUT_MS)
+            describeFetchError(reportErr, API_CHANNEL_ERROR, CHANNEL_ERROR_REPORT_TIMEOUT_MS)
           );
         }
         process.exit(1);
@@ -18241,7 +18274,7 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
   );
   let res;
   try {
-    res = await authFetch(`${tandemUrl}/api/events`, { headers, signal: connectCtrl.signal });
+    res = await authFetch(`${tandemUrl}${API_EVENTS}`, { headers, signal: connectCtrl.signal });
   } finally {
     clearTimeout(connectTimer);
   }
@@ -18265,7 +18298,7 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
   const AWARENESS_CLEAR_MS = 3e3;
   function clearAwareness(documentId) {
     fetchWithTimeout(
-      `${tandemUrl}/api/channel-awareness`,
+      `${tandemUrl}${API_CHANNEL_AWARENESS}`,
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -18279,7 +18312,11 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
     ).catch((err) => {
       console.error(
         "[Channel] clearAwareness failed (non-fatal):",
-        describeFetchError(err, "/api/channel-awareness clear", CHANNEL_AWARENESS_FETCH_TIMEOUT_MS)
+        describeFetchError(
+          err,
+          `${API_CHANNEL_AWARENESS} clear`,
+          CHANNEL_AWARENESS_FETCH_TIMEOUT_MS
+        )
       );
     });
   }
@@ -18288,7 +18325,7 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
     const event = pendingAwareness;
     pendingAwareness = null;
     fetchWithTimeout(
-      `${tandemUrl}/api/channel-awareness`,
+      `${tandemUrl}${API_CHANNEL_AWARENESS}`,
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -18304,7 +18341,7 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
         "[Channel] Awareness update failed:",
         describeFetchError(
           err,
-          "/api/channel-awareness update",
+          `${API_CHANNEL_AWARENESS} update`,
           CHANNEL_AWARENESS_FETCH_TIMEOUT_MS
         )
       );
@@ -18400,7 +18437,11 @@ async function getCachedMode(tandemUrl) {
   const now = Date.now();
   if (now - cachedModeAt < MODE_CACHE_TTL_MS) return cachedMode;
   try {
-    const res = await fetchWithTimeout(`${tandemUrl}/api/mode`, {}, CHANNEL_MODE_FETCH_TIMEOUT_MS);
+    const res = await fetchWithTimeout(
+      `${tandemUrl}${API_MODE}`,
+      {},
+      CHANNEL_MODE_FETCH_TIMEOUT_MS
+    );
     if (res.ok) {
       const { mode } = await res.json();
       cachedMode = mode;
@@ -18411,7 +18452,7 @@ async function getCachedMode(tandemUrl) {
   } catch (err) {
     console.error(
       "[Channel] Mode check failed, delivering event (fail-open):",
-      describeFetchError(err, "/api/mode", CHANNEL_MODE_FETCH_TIMEOUT_MS)
+      describeFetchError(err, API_MODE, CHANNEL_MODE_FETCH_TIMEOUT_MS)
     );
     cachedModeAt = now;
   }
@@ -18473,7 +18514,7 @@ async function runChannel(opts = {}) {
       const args = req.params.arguments;
       try {
         const res = await fetchWithTimeout(
-          `${tandemUrl}/api/channel-reply`,
+          `${tandemUrl}${API_CHANNEL_REPLY}`,
           {
             method: "POST",
             headers: { "Content-Type": "application/json" },
@@ -18507,7 +18548,7 @@ async function runChannel(opts = {}) {
               type: "text",
               text: `Failed to send reply: ${describeFetchError(
                 err,
-                "/api/channel-reply",
+                API_CHANNEL_REPLY,
                 CHANNEL_REPLY_FETCH_TIMEOUT_MS
               )}`
             }
@@ -18530,7 +18571,7 @@ async function runChannel(opts = {}) {
   mcp.setNotificationHandler(PermissionRequestSchema, async ({ params }) => {
     try {
       const res = await fetchWithTimeout(
-        `${tandemUrl}/api/channel-permission`,
+        `${tandemUrl}${API_CHANNEL_PERMISSION}`,
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
@@ -18551,7 +18592,7 @@ async function runChannel(opts = {}) {
     } catch (err) {
       console.error(
         "[Channel] Failed to forward permission request:",
-        describeFetchError(err, "/api/channel-permission", CHANNEL_PERMISSION_FETCH_TIMEOUT_MS)
+        describeFetchError(err, API_CHANNEL_PERMISSION, CHANNEL_PERMISSION_FETCH_TIMEOUT_MS)
       );
     }
   });
@@ -18577,7 +18618,7 @@ async function checkServerReachable(url, timeoutMs = 2e3) {
     parsed = new URL(url);
   } catch {
     console.error(
-      `[Channel] Invalid TANDEM_URL: "${url}" \u2014 expected format: http://localhost:3479`
+      `[Channel] Invalid TANDEM_URL: "${url}" \u2014 expected format: http://127.0.0.1:3479`
     );
     return false;
   }