mdinterface 0.2.0 → 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.2.0",
+  "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",

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

@@ -28,17 +28,36 @@ try {
 
 // ---------- 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")}`
   );
@@ -74,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.
@@ -83,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 });
@@ -130,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 });
@@ -349,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);
   });
@@ -448,7 +488,7 @@ function ensureSpawnHelperExecutable() {
 
 // Turn a spawn failure into a specific, actionable message instead of a generic one.
 function diagnosePtyFailure(e) {
-  const msg = (e && e.message) || String(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";
@@ -545,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) => {
@@ -648,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
@@ -700,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,
@@ -746,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
 }
 
@@ -773,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);
 }
@@ -782,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}"`);