mdinterface 0.1.1 → 0.2.1

package/README.md

@@ -48,10 +48,18 @@ CDN, no first-load internet requirement.
     node server.js path/to/doc.md
     # prints a URL like http://localhost:7777/?t=… — open THAT (it carries a session token)
 
+Or start with **no file** — you get an empty canvas and a file browser; pick a `.md` and the
+session begins. The folder of that first document becomes Claude's working directory for the
+rest of the session, so launch from (or pick within) the project you want Claude to work in:
+
+    node server.js
+    # empty canvas → Browse → pick a doc; Claude starts in that doc's folder
+
 Options:
 
     --port 8000        # different port
     --cmd "claude --continue"   # custom launch command (or set MDINTERFACE_CMD)
+    --help             # usage and exit
 
 ## Use
 

package/mcp-server.js

@@ -213,7 +213,7 @@ function handle(msg) {
     result(id, {
       protocolVersion: params?.protocolVersion || "2025-06-18",
       capabilities: { tools: {} },
-      serverInfo: { name: "mdinterface", version: "0.1.0" },
+      serverInfo: { name: "mdinterface", version: require("./package.json").version },
     });
   } else if (method === "tools/list") {
     result(id, { tools: TOOLS });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdinterface",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "A live markdown canvas wired to Claude Code. Highlight a passage to set both the context and the scope, ask, and Claude edits exactly that and leaves the rest alone.",
   "license": "MIT",
   "author": "Kevin Sundstrom",
@@ -18,6 +18,7 @@
   },
   "scripts": {
     "start": "bash start.sh",
+    "mdinterface": "node server.js",
     "lint": "biome check .",
     "format": "biome format --write .",
     "typecheck": "tsc --noEmit",
@@ -51,9 +52,11 @@
   ],
   "dependencies": {
     "express": "^4.19.0",
-    "node-pty": "^1.0.0",
     "ws": "^8.17.0"
   },
+  "optionalDependencies": {
+    "node-pty": "^1.0.0"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.0.0",
     "@types/express": "^4.17.21",

package/public/index.html

@@ -387,7 +387,11 @@ function connect() {
       if (!editingEl) render(msg.content);
     }
     if (msg.type === "history") undoBtn.disabled = !msg.canUndo;
+    if (msg.type === "nodoc") showNoDoc();
     if (msg.type === "opened") {
+      // Leaving the no-document state: the server is starting Claude now, so reset the
+      // terminal for its fresh output and dismiss the picker.
+      if (nodoc) { nodoc = false; closeBrowser(); term.reset(); }
       setDocMeta(msg.path, msg.name);
       filepicker.classList.remove("error");
       // New document — reset the diff baseline so the whole thing isn't flagged as
@@ -401,6 +405,19 @@ function showMissing() {
   lastSrc = ""; prevBlocks = []; prevEls = []; flashedEls = []; notionLink.hidden = true;
   docEl.innerHTML = '<p style="color:var(--ink-soft);font-style:italic">The document is no longer on disk — waiting for it to return…</p>';
 }
+// No file was given at launch. Show a hint + the file browser; Claude doesn't start until a
+// document is picked (its folder becomes the working directory). Set by the server's "nodoc".
+let nodoc = false;
+function showNoDoc() {
+  nodoc = true;
+  lastSrc = ""; prevBlocks = []; prevEls = []; flashedEls = []; notionLink.hidden = true;
+  docEl.innerHTML = '<p style="color:var(--ink-soft);font-style:italic">No document open — pick a <code>.md</code> file to start. The folder you choose becomes Claude’s working directory.</p>';
+  document.title = "mdinterface — pick a document";
+  term.reset();
+  term.writeln("\x1b[2m  No Claude session yet — pick a document to begin.\x1b[0m");
+  showHeader();
+  openBrowser(); // pop the file browser at the launch directory
+}
 connect();
 
 // ---------- block rendering + change flash ----------
@@ -794,7 +811,7 @@ restartBtn.addEventListener("click", () => {
 const header = document.querySelector("header");
 let headerHide;
 function showHeader() { clearTimeout(headerHide); header.classList.add("show"); }
-function hideHeaderSoon(delay) { clearTimeout(headerHide); headerHide = setTimeout(() => header.classList.remove("show"), delay); }
+function hideHeaderSoon(delay) { if (nodoc) return; clearTimeout(headerHide); headerHide = setTimeout(() => header.classList.remove("show"), delay); }
 document.addEventListener("mousemove", (e) => { if (e.clientY <= 6) showHeader(); });
 header.addEventListener("mouseenter", showHeader);
 header.addEventListener("mouseleave", () => hideHeaderSoon(300));

package/server.js

@@ -16,21 +16,48 @@ const path = require("node:path");
 const os = require("node:os");
 const crypto = require("node:crypto");
 const { WebSocketServer } = require("ws");
-const pty = require("node-pty");
+// node-pty powers the embedded terminal pane. It's an OPTIONAL native dependency (see
+// optionalDependencies in package.json): if it didn't install or build, the rendered canvas,
+// the file watcher, and the selection bridge all still come up — only the in-window terminal
+// is disabled, and you run `claude` in your own terminal instead (the hooks still feed it the
+// selection off disk). The specific reason is surfaced to the user at spawn time.
+let pty = null;
+try {
+  pty = require("node-pty");
+} catch {}
 
 // ---------- args ----------
 const args = process.argv.slice(2);
-const fileArg = args.find((a) => !a.startsWith("--"));
-if (!fileArg) {
-  console.error("Usage: mdinterface <file.md> [--port 7777] [--cmd claude]");
-  process.exit(1);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(
+    "mdinterface — a live markdown canvas wired to Claude Code.\n\n" +
+      "Usage:\n" +
+      "  mdinterface [file.md] [--port 7777] [--cmd claude]\n\n" +
+      "Run with a file to open it directly, or with no file to start on an empty\n" +
+      "canvas and pick one in the file browser. The folder of the first document\n" +
+      "opened becomes Claude's working directory for the rest of the session.\n\n" +
+      "Options:\n" +
+      "  --port <n>   Port to listen on (default 7777)\n" +
+      '  --cmd <cmd>  Command run in the terminal pane (default "claude";\n' +
+      "               or set MDINTERFACE_CMD)\n" +
+      "  -h, --help   Show this help and exit\n\n" +
+      "The printed URL carries a per-launch token — open that exact URL."
+  );
+  process.exit(0);
 }
-let DOC = path.resolve(fileArg); // reassignable: the toolbar file picker can switch docs
-if (!fs.existsSync(DOC)) {
+// The file is the first bare argument — but skip values that belong to a value-taking flag
+// (`--port 7777`, `--cmd claude`), or with no file they'd be misread as the filename.
+const VALUE_FLAGS = new Set(["--port", "--cmd"]);
+const fileArg = args.find((a, i) => !a.startsWith("--") && !VALUE_FLAGS.has(args[i - 1]));
+// The file is optional: with none, mdinterface opens an empty canvas and the file browser,
+// and initializes the session (hooks, MCP, watcher, Claude) when you pick the first document.
+// reassignable: the toolbar file picker can switch documents.
+let DOC = fileArg ? path.resolve(fileArg) : null;
+if (DOC && !fs.existsSync(DOC)) {
   console.error(`File not found: ${DOC}`);
   process.exit(1);
 }
-if (fs.statSync(DOC).isDirectory()) {
+if (DOC && fs.statSync(DOC).isDirectory()) {
   console.error(
     `${DOC} is a directory — point me at a markdown file, e.g.:\n  node server.js ${path.join(fileArg, "doc.md")}`
   );
@@ -66,7 +93,11 @@ app.use(express.static(path.join(__dirname, "public")));
 app.get("/doc", (req, res) => {
   if (req.query.t !== TOKEN) return res.status(403).end();
   // path is returned (for the file picker) but only to a token-holding client.
-  res.json({ name: path.basename(DOC), path: DOC, content: read() });
+  res.json(
+    DOC
+      ? { name: path.basename(DOC), path: DOC, content: read() }
+      : { name: null, path: null, content: "" }
+  );
 });
 // Directory listing for the file browser: folders (to navigate) + markdown files. Token
 // gated. Lists any dir the user can read — same reach the PTY already has.
@@ -75,7 +106,9 @@ app.get("/ls", (req, res) => {
   const dir =
     typeof req.query.dir === "string" && req.query.dir
       ? path.resolve(req.query.dir)
-      : path.dirname(DOC);
+      : DOC
+        ? path.dirname(DOC)
+        : process.cwd(); // no doc yet → browse from where mdinterface was launched
   let ents;
   try {
     ents = fs.readdirSync(dir, { withFileTypes: true });
@@ -122,14 +155,22 @@ function read() {
 // The canvas never types into Claude. Instead the current selection is mirrored to a
 // file, and a UserPromptSubmit hook injects that file as context on the user's next
 // message — so Claude is ambiently aware of what's selected, with zero prompt noise.
-const CLAUDE_DIR = path.join(path.dirname(DOC), ".claude");
-const SEL_FILE = path.join(CLAUDE_DIR, "mdinterface-selection.txt");
+// Folder-derived paths. When launched with no file, DOC is null and these stay null until
+// the first document is opened (openDoc → initDocSession), which anchors them to its folder.
+let CLAUDE_DIR = null;
+let SEL_FILE = null;
 
 // ---------- runtime file: how the separate MCP process reaches this server ----------
 // canvas_edit writes the open document directly; canvas_open POSTs back to this server. The
 // MCP process reads port/token/doc from this file before each call, so edits follow the
 // toolbar file picker. Edits always apply immediately — undo is the Undo button (or git).
-const RUNTIME_FILE = path.join(CLAUDE_DIR, "mdinterface-runtime.json");
+let RUNTIME_FILE = null;
+// Anchor the support-file paths to the open document's folder. Called once the doc is known.
+function wireDocPaths() {
+  CLAUDE_DIR = path.join(path.dirname(DOC), ".claude");
+  SEL_FILE = path.join(CLAUDE_DIR, "mdinterface-selection.txt");
+  RUNTIME_FILE = path.join(CLAUDE_DIR, "mdinterface-runtime.json");
+}
 function writeRuntime() {
   try {
     fs.mkdirSync(CLAUDE_DIR, { recursive: true });
@@ -341,18 +382,25 @@ function installMcpServer() {
   }
 }
 
-installHooks();
-installMcpServer();
-writeRuntime(); // mode + callback info for the MCP server
-writeSelection("", []); // start clean
+// Per-document session setup: anchor the support files + hooks to the doc's folder, register
+// the MCP server, and seed the runtime/selection files. Runs at boot when a file was given on
+// the command line, or on the first openDoc when launched with no file.
+function initDocSession() {
+  wireDocPaths();
+  installHooks();
+  installMcpServer();
+  writeRuntime(); // mode + callback info for the MCP server
+  writeSelection("", []); // start clean
+}
+if (DOC) initDocSession();
 
 for (const sig of ["exit", "SIGINT", "SIGTERM"]) {
   process.on(sig, () => {
     try {
-      fs.writeFileSync(SEL_FILE, "");
+      if (SEL_FILE) fs.writeFileSync(SEL_FILE, "");
     } catch {}
     try {
-      fs.unlinkSync(RUNTIME_FILE);
+      if (RUNTIME_FILE) fs.unlinkSync(RUNTIME_FILE);
     } catch {} // gone → MCP server defaults back to auto
     if (sig !== "exit") process.exit(0);
   });
@@ -405,13 +453,65 @@ function onPtyData(d) {
     flushTerm();
   }, TERM_FLUSH_MS);
 }
+// pnpm, Yarn PnP, CI caches, and Docker COPY frequently strip the +x bit from node-pty's
+// prebuilt spawn-helper, which makes pty.spawn die — the single most common runtime failure.
+// Restore it in-process, since a postinstall script can't help the people who hit this most
+// (--ignore-scripts / pnpm users disable postinstall). Returns true if it actually fixed a bit.
+function ensureSpawnHelperExecutable() {
+  let fixed = false;
+  try {
+    const root = path.dirname(require.resolve("node-pty/package.json")); // works wherever it's hoisted
+    for (const base of [path.join(root, "prebuilds"), path.join(root, "build", "Release")]) {
+      let ents;
+      try {
+        ents = fs.readdirSync(base, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      const files = [];
+      for (const ent of ents) {
+        if (ent.isDirectory()) files.push(path.join(base, ent.name, "spawn-helper"));
+        else if (ent.name === "spawn-helper") files.push(path.join(base, ent.name));
+      }
+      for (const f of files) {
+        try {
+          if (!(fs.statSync(f).mode & 0o111)) {
+            fs.chmodSync(f, 0o755);
+            fixed = true;
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+  return fixed;
+}
+
+// Turn a spawn failure into a specific, actionable message instead of a generic one.
+function diagnosePtyFailure(e) {
+  const msg = e?.message || String(e);
+  let hint;
+  if (/NODE_MODULE_VERSION|compiled against|different Node/i.test(msg))
+    hint = "node-pty was built for a different Node version — rebuild it:\n  npm rebuild node-pty";
+  else if (/spawn-helper|EACCES|ENOENT|permission/i.test(msg))
+    hint =
+      "node-pty's spawn-helper is missing or not executable:\n" +
+      "  chmod +x node_modules/node-pty/prebuilds/*/spawn-helper\n  npm rebuild node-pty";
+  else hint = "Reinstall the native module:\n  npm rebuild node-pty";
+  return (
+    `Embedded terminal could not start (${msg}).\n${hint}\n` +
+    `The canvas and selection bridge still work — run \`${CLAUDE_CMD}\` in your own terminal beside this window.`
+  );
+}
+
 function spawnPty(cols = 100, rows = 32) {
+  if (!pty) return null; // optional dependency absent — startShell shows the fallback message
+  ensureSpawnHelperExecutable(); // proactively fix a stripped +x bit before we spawn
   const env = { ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor" };
   const cwd = path.dirname(DOC);
   const sh = process.env.SHELL || (os.platform() === "win32" ? "powershell.exe" : "/bin/bash");
   const opts = { name: "xterm-256color", cols, rows, cwd, env };
-  // Launch through the user's interactive login shell so PATH, rc files,
-  // and aliases apply — this is how `claude` is normally found.
+  // Launch through the user's interactive login shell so PATH, rc files, and aliases apply —
+  // this is how `claude` is normally found.
   try {
     return pty.spawn(sh, ["-ilc", CLAUDE_CMD], opts);
   } catch (e) {
@@ -419,18 +519,18 @@ function spawnPty(cols = 100, rows = 32) {
       `Could not start "${CLAUDE_CMD}" via ${sh} (${e.message}); opening a plain shell.`
     );
   }
-  try {
-    return pty.spawn(sh, [], opts);
-  } catch (e) {
-    console.error(
-      `PTY could not start at all (${e.message}).\n` +
-        `node-pty's prebuilt spawn-helper may have lost its executable bit. Restore it:\n` +
-        `  chmod +x node_modules/node-pty/prebuilds/*/spawn-helper\n` +
-        `If there's no prebuilt binary for your platform, build it instead:\n` +
-        `  npm rebuild node-pty`
-    );
-    return null;
+  // Plain-shell fallback. If even this fails, a stripped +x bit on spawn-helper is the usual
+  // cause: self-heal it and retry once before giving up with a diagnosis.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      return pty.spawn(sh, [], opts);
+    } catch (e) {
+      if (attempt === 0 && ensureSpawnHelperExecutable()) continue; // fixed a bit → retry
+      console.error(diagnosePtyFailure(e));
+      return null;
+    }
   }
+  return null;
 }
 
 // Start the PTY and wire BOTH its data and exit handlers (the earlier version reattached
@@ -445,7 +545,13 @@ let rapidExits = 0;
 function startShell() {
   shell = spawnPty(ptyCols, ptyRows); // respawn at the current size, not the 100x32 default
   if (!shell) {
-    broadcast({ type: "term", data: "Terminal unavailable — see server console for the fix.\r\n" });
+    // Two cases, both non-fatal: node-pty isn't installed at all, or it is but the spawn
+    // failed (details already in the server console via diagnosePtyFailure). Either way the
+    // canvas + selection bridge work, so point the user at running claude in their own terminal.
+    const data = pty
+      ? "\r\nEmbedded terminal could not start (see the server console). The canvas and selection still work — run claude in your own terminal beside this window and it gets the same context.\r\n"
+      : "\r\nEmbedded terminal disabled: node-pty isn't installed. The canvas and selection still work — run claude in your own terminal beside this window (it gets the same context via the hooks). To enable the in-window terminal: npm i node-pty\r\n";
+    broadcast({ type: "term", data });
     return;
   }
   shellSpawnAt = Date.now();
@@ -479,17 +585,24 @@ const clients = new Set();
 wss.on("connection", (ws) => {
   clients.add(ws);
   let reconnect = false;
-  if (!shell) {
-    termBuffer = "";
-    rapidExits = 0; // a fresh manual connect (e.g. reload) earns a clean slate of retries
-    startShell();
-  } else if (termBuffer) {
-    // Reconnect (e.g. page reload): replay the current screen for instant content, and
-    // flag for a forced repaint once this client's real size lands (see resize handler).
-    ws.send(JSON.stringify({ type: "term", data: termBuffer }));
-    reconnect = true;
+  if (DOC) {
+    if (!shell) {
+      termBuffer = "";
+      rapidExits = 0; // a fresh manual connect (e.g. reload) earns a clean slate of retries
+      startShell();
+    } else if (termBuffer) {
+      // Reconnect (e.g. page reload): replay the current screen for instant content, and
+      // flag for a forced repaint once this client's real size lands (see resize handler).
+      ws.send(JSON.stringify({ type: "term", data: termBuffer }));
+      reconnect = true;
+    }
+    ws.send(JSON.stringify({ type: "doc", content: read(), missing: !fs.existsSync(DOC) }));
+  } else {
+    // No document yet (launched with no file): don't spawn Claude — its working directory is
+    // unknown until the first pick. Tell the client to show the picker instead of a terminal.
+    // The message handler below still runs, so the client's "open" pick is honored.
+    ws.send(JSON.stringify({ type: "nodoc" }));
   }
-  ws.send(JSON.stringify({ type: "doc", content: read(), missing: !fs.existsSync(DOC) }));
   ws.send(JSON.stringify({ type: "history", canUndo: history.length > 0 }));
 
   ws.on("message", (raw) => {
@@ -582,7 +695,7 @@ function broadcast(obj) {
 // and which would otherwise silence a file-level watch. A slow polling watch stays on
 // as a safety net; the `last` check keeps either path from double-broadcasting.
 let last = read();
-let lastMissing = !fs.existsSync(DOC);
+let lastMissing = Boolean(DOC) && !fs.existsSync(DOC); // no doc yet → not "missing", just unset
 let updateTimer = null;
 // Undo history: prior document contents, newest last. Every observed change (from Claude,
 // the canvas, or an external editor) pushes the previous version, so the doc-side Undo
@@ -634,7 +747,7 @@ function startWatcher() {
   }
   fs.watchFile(DOC, { interval: 1000 }, maybeUpdate); // fallback safety net
 }
-startWatcher();
+if (DOC) startWatcher(); // with no file yet, the watcher starts when the first doc is opened
 
 // Switch the active document at runtime (toolbar file picker) WITHOUT restarting the
 // Claude session. Only the content document changes; the support files (selection,
@@ -680,18 +793,32 @@ function openDoc(rawPath) {
     };
   if (resolved === DOC) return { error: "That document is already open." };
 
+  const firstDoc = DOC === null; // launched with no file → this pick initializes the session
   DOC = resolved;
   history.length = 0;
   historyBytes = 0;
   last = read();
   lastMissing = !fs.existsSync(DOC);
-  writeRuntime(); // runtime.doc → new path, so canvas_edit edits the right file
-  writeSelection("", []); // clear the (now-irrelevant) selection
+  if (firstDoc) {
+    // Anchor support files + hooks to this folder and register the MCP server, exactly as a
+    // file-on-launch start does at boot. The session's working directory is fixed from here.
+    initDocSession();
+  } else {
+    writeRuntime(); // runtime.doc → new path, so canvas_edit edits the right file
+    writeSelection("", []); // clear the (now-irrelevant) selection
+  }
   startWatcher(); // watch the new file/folder
 
   broadcast({ type: "opened", path: DOC, name: path.basename(DOC) });
   broadcast({ type: "doc", content: read(), missing: lastMissing });
   broadcastHistory();
+  // First document: now that the working directory is known, start Claude. Connected clients
+  // receive its output via broadcast. (Switching docs later preserves the session — no respawn.)
+  if (firstDoc && !shell) {
+    termBuffer = "";
+    rapidExits = 0;
+    startShell();
+  }
   return { ok: true }; // no shell.kill() — the Claude session is preserved
 }
 
@@ -707,7 +834,7 @@ function onServerError(e) {
         `    mdinterface ${JSON.stringify(path.basename(DOC))} --port 8001\n`
     );
   } else {
-    console.error(`\n  mdinterface could not start: ${(e && e.message) || e}\n`);
+    console.error(`\n  mdinterface could not start: ${e?.message || e}\n`);
   }
   process.exit(1);
 }
@@ -716,7 +843,7 @@ wss.on("error", onServerError);
 
 server.listen(PORT, "127.0.0.1", () => {
   const url = `http://localhost:${PORT}/?t=${TOKEN}`;
-  console.log(`mdinterface ▸ ${path.basename(DOC)} ▸ ${url}`);
+  console.log(`mdinterface ▸ ${DOC ? path.basename(DOC) : "(pick a document)"} ▸ ${url}`);
   const opener =
     os.platform() === "darwin" ? "open" : os.platform() === "win32" ? "start" : "xdg-open";
   require("node:child_process").exec(`${opener} "${url}"`);