mrmd-server 0.1.21 → 0.1.22

package/README.md

@@ -1,17 +1,19 @@
-# mrmd-server
+# MRMD Server
 
-Run mrmd in any browser. Access your notebooks from anywhere.
+**Run MRMD in any browser.** Access your markdown notebooks from anywhere — your phone, tablet, or any machine with a browser.
+
+[![npm version](https://img.shields.io/npm/v/mrmd-server)](https://www.npmjs.com/package/mrmd-server)  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                    Your VPS / Cloud Server                   │
+│                    Your Server / VPS / Cloud                │
 │                                                             │
 │   ┌─────────────────────────────────────────────────────┐   │
 │   │                    mrmd-server                       │   │
-│   │  • HTTP API (full electronAPI equivalent)           │   │
-│   │  • Static file serving                              │   │
-│   │  • WebSocket for real-time events                   │   │
-│   │  • Token authentication                             │   │
+│   │  • Full MRMD UI served over HTTP                    │   │
+│   │  • Code execution (Python, JS, Bash, R, Julia)      │   │
+│   │  • Real-time collaboration via WebSocket            │   │
+│   │  • Token-based authentication                       │   │
 │   └─────────────────────────────────────────────────────┘   │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
@@ -25,23 +27,65 @@ Run mrmd in any browser. Access your notebooks from anywhere.
           └───────┘              └─────────┘       └─────────┘
 ```
 
+---
+
+## What is MRMD Server?
+
+MRMD Server is the headless/server version of [MRMD Electron](https://github.com/MaximeRivest/mrmd-electron). It provides the same markdown notebook experience without requiring a desktop app — just start the server and open it in any browser.
+
+**Use cases:**
+- Run notebooks on a remote GPU server, access from your laptop
+- Host shared notebooks for a team
+- Access your notebooks from your phone or tablet
+- Deploy on a cloud VM for always-on compute
+
+---
+
 ## Features
 
-- **Same UI as Electron** - Uses the exact same index.html from mrmd-electron
-- **Access from anywhere** - Phone, tablet, any browser
-- **Real-time collaboration** - Yjs sync works over WebSocket
-- **Token authentication** - Secure access with shareable links
-- **Portable compute** - Move your disk to a GPU server when needed
+### Same UI as Desktop
+The exact same editor, code execution, and collaboration features as MRMD Electron.
 
-## Quick Start
+### Access from Anywhere
+Open your notebooks in any browser — phone, tablet, another computer.
+
+### Real-Time Collaboration
+Share the URL with teammates. Changes sync instantly via Yjs CRDT.
+
+### Token Authentication
+Secure access with auto-generated or custom tokens. Share links safely.
+
+### Portable Compute
+Start the server wherever your data lives. GPU machine? Local workstation? Cloud VM? Just run `mrmd-server`.
+
+---
+
+## Installation
+
+### npm (recommended)
 
 ```bash
-# Install
-cd mrmd-packages/mrmd-server
-npm install
+npm install -g mrmd-server
+```
 
-# Start server in your project directory
+### npx (no install)
+
+```bash
 npx mrmd-server ./my-notebooks
+```
+
+### Requirements
+
+- **Node.js 18+**
+- **Python 3.11+** with [uv](https://github.com/astral-sh/uv) (for Python execution)
+
+---
+
+## Quick Start
+
+```bash
+# Start server in your project directory
+mrmd-server ./my-notebooks
 
 # Output:
 #   mrmd-server
@@ -54,9 +98,26 @@ npx mrmd-server ./my-notebooks
 #   http://localhost:8080?token=abc123xyz...
 ```
 
+Open the Access URL in your browser. That's it.
+
+---
+
 ## Usage
 
-### Basic Usage
+### Command Line Options
+
+```bash
+mrmd-server [options] [project-dir]
+
+Options:
+  -p, --port <port>     HTTP port (default: 8080)
+  -h, --host <host>     Bind address (default: 0.0.0.0)
+  -t, --token <token>   Auth token (auto-generated if not provided)
+  --no-auth             Disable authentication (local dev only!)
+  --help                Show help
+```
+
+### Examples
 
 ```bash
 # Start in current directory
@@ -68,163 +129,185 @@ mrmd-server ./my-project
 # Custom port
 mrmd-server -p 3000 ./my-project
 
-# With specific token
+# With specific token (for automation)
 mrmd-server -t my-secret-token ./my-project
 
 # No auth (local development only!)
-mrmd-server --no-auth ./my-project
+mrmd-server --no-auth
 ```
 
-### Remote Access
+---
 
-1. Start mrmd-server on your VPS:
-   ```bash
-   mrmd-server -p 8080 /home/you/notebooks
-   ```
+## Remote Access Setup
 
-2. Set up HTTPS (recommended) with nginx or caddy:
-   ```nginx
-   server {
-       listen 443 ssl;
-       server_name notebooks.example.com;
+### 1. Start the server on your remote machine
 
-       location / {
-           proxy_pass http://localhost:8080;
-           proxy_http_version 1.1;
-           proxy_set_header Upgrade $http_upgrade;
-           proxy_set_header Connection "upgrade";
-       }
-   }
-   ```
+```bash
+ssh your-server
+cd /path/to/notebooks
+mrmd-server -p 8080
+```
+
+### 2. Set up HTTPS with nginx (recommended)
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name notebooks.example.com;
 
-3. Access from anywhere:
-   ```
-   https://notebooks.example.com?token=YOUR_TOKEN
-   ```
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+}
+```
 
-### Share with Collaborators
+### 3. Access from anywhere
+
+```
+https://notebooks.example.com?token=YOUR_TOKEN
+```
+
+---
+
+## Sharing & Collaboration
+
+Share the URL (including the token) with collaborators:
 
-Just share the URL with the token:
 ```
 https://your-server.com?token=abc123xyz
 ```
 
-Collaborators get:
-- Real-time collaborative editing (Yjs)
-- Code execution (via the server)
-- Same UI as local Electron app
+Everyone with the URL gets:
+- Real-time collaborative editing
+- Code execution on your server
+- Full MRMD features
+
+---
 
 ## Architecture
 
-mrmd-server provides an HTTP API that mirrors Electron's IPC interface:
+MRMD Server mirrors the Electron app's IPC interface as an HTTP API:
 
-| Electron (IPC) | mrmd-server (HTTP) |
+| Electron (IPC) | MRMD Server (HTTP) |
 |----------------|-------------------|
 | `electronAPI.project.get(path)` | `GET /api/project?path=...` |
 | `electronAPI.file.write(path, content)` | `POST /api/file/write` |
 | `electronAPI.session.forDocument(path)` | `POST /api/session/for-document` |
 | `ipcRenderer.on('project:changed', cb)` | WebSocket `/events` |
 
-The browser loads `http-shim.js` which creates a `window.electronAPI` object that makes HTTP calls instead of IPC calls. The existing UI code works unchanged.
+The browser loads an HTTP shim that creates `window.electronAPI` making HTTP calls instead of IPC. The UI code works unchanged.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      mrmd-server                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │ Express     │  │ mrmd-sync   │  │ mrmd-       │         │
+│  │ HTTP API    │  │ (Yjs)       │  │ python/bash │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+└─────────────────────────────────────────────────────────────┘
+         │                  │                  │
+    HTTP/REST          WebSocket           Execution
+```
+
+---
 
 ## API Reference
 
 ### Authentication
 
-All API endpoints (except `/health` and `/auth/validate`) require authentication.
-
-Provide token via:
+All `/api/*` endpoints require authentication. Provide token via:
 - Query parameter: `?token=xxx`
 - Header: `Authorization: Bearer xxx`
 - Header: `X-Token: xxx`
 
-### Endpoints
-
-#### System
-- `GET /api/system/home` - Get home directory
-- `GET /api/system/recent` - Get recent files/venvs
-- `GET /api/system/ai` - Get AI server info
-- `POST /api/system/discover-venvs` - Start venv discovery
-
-#### Project
-- `GET /api/project?path=...` - Get project info
-- `POST /api/project` - Create project
-- `GET /api/project/nav?root=...` - Get navigation tree
-- `POST /api/project/watch` - Watch for changes
-- `POST /api/project/unwatch` - Stop watching
-
-#### Session
-- `GET /api/session` - List sessions
-- `POST /api/session` - Start session
-- `DELETE /api/session/:name` - Stop session
-- `POST /api/session/for-document` - Get/create session for document
-
-#### Bash
-- Same as Session, at `/api/bash/*`
-
-#### File
-- `GET /api/file/scan` - Scan for files
-- `POST /api/file/create` - Create file
-- `POST /api/file/create-in-project` - Create with FSML ordering
-- `POST /api/file/move` - Move/rename
-- `POST /api/file/reorder` - Drag-drop reorder
-- `DELETE /api/file?path=...` - Delete file
-- `GET /api/file/read?path=...` - Read file
-- `POST /api/file/write` - Write file
-
-#### Asset
-- `GET /api/asset` - List assets
-- `POST /api/asset/save` - Upload asset
-- `GET /api/asset/relative-path` - Calculate relative path
-- `GET /api/asset/orphans` - Find orphaned assets
-- `DELETE /api/asset` - Delete asset
-
-#### Runtime
-- `GET /api/runtime` - List runtimes
-- `DELETE /api/runtime/:id` - Kill runtime
-- `POST /api/runtime/:id/attach` - Attach to runtime
+### Core Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Health check (no auth) |
+| `GET /auth/validate?token=xxx` | Validate token (no auth) |
+| `GET /api/project?path=...` | Get project info |
+| `GET /api/file/read?path=...` | Read file |
+| `POST /api/file/write` | Write file |
+| `POST /api/session/for-document` | Get/create session for document |
+| `GET /api/runtime` | List active runtimes |
+| `DELETE /api/runtime/:id` | Kill a runtime |
 
 ### WebSocket Events
 
-Connect to `/events?token=xxx` to receive push events:
+Connect to `/events?token=xxx` for real-time updates:
 
 ```javascript
 const ws = new WebSocket('wss://server.com/events?token=xxx');
 ws.onmessage = (e) => {
   const { event, data } = JSON.parse(e.data);
-  // event: 'project:changed', 'venv-found', 'sync-server-died', etc.
+  // Events: 'project:changed', 'venv-found', 'sync-server-died', etc.
 };
 ```
 
-## Security Considerations
+---
+
+## Security
+
+1. **Always use HTTPS** in production — use nginx, caddy, or a cloud load balancer
+2. **Keep tokens secret** — treat them like passwords
+3. **Never use `--no-auth` on public networks**
+4. **Rotate tokens** if you suspect they're compromised
 
-1. **Always use HTTPS** in production (use nginx/caddy as reverse proxy)
-2. **Keep tokens secret** - treat them like passwords
-3. **Use `--no-auth` only for local development**
-4. **Rotate tokens** if compromised
+---
 
 ## Limitations
 
-Some Electron features can't work in browser:
+Some desktop features don't work in browser mode:
 
 | Feature | Browser Behavior |
 |---------|------------------|
-| `shell.showItemInFolder` | Returns path (can't open Finder) |
-| `shell.openPath` | Returns path (can't open local apps) |
-| Native titlebar | Standard browser chrome |
-| Offline | Requires server connection |
+| "Show in Finder" | Returns path (can't open native file browser) |
+| Native window controls | Standard browser chrome |
+| Offline mode | Requires server connection |
+
+---
 
 ## Development
 
 ```bash
+# Clone the monorepo
+git clone https://github.com/MaximeRivest/mrmd-packages.git
+cd mrmd-packages/mrmd-server
+
+# Install dependencies
+npm install
+
 # Run in dev mode
 npm run dev
-
-# The server will:
-# - Watch for file changes
-# - Auto-restart on changes
 ```
 
+---
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [MRMD Electron](https://github.com/MaximeRivest/mrmd-electron) | Desktop app (macOS, Windows, Linux) |
+| [mrmd-python](https://github.com/MaximeRivest/mrmd-python) | Python execution runtime |
+| [mrmd-editor](https://github.com/MaximeRivest/mrmd-editor) | CodeMirror-based editor component |
+| [mrmd-sync](https://github.com/MaximeRivest/mrmd-sync) | Yjs collaboration server |
+
+---
+
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <b>MRMD Server</b> — Your notebooks, anywhere.
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mrmd-server",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "HTTP server for mrmd - run mrmd in any browser, access from anywhere",
   "type": "module",
   "main": "src/index.js",
@@ -45,8 +45,8 @@
     "multer": "^1.4.5-lts.1",
     "chokidar": "^3.6.0",
     "fzf": "^0.5.2",
-    "mrmd-project": "^0.1.1",
+    "mrmd-project": "^0.1.2",
     "mrmd-electron": "^0.3.4",
-    "mrmd-sync": "^0.3.2"
+    "mrmd-sync": "^0.3.3"
   }
 }

package/src/api/file.js

@@ -27,8 +27,8 @@ export function createFileRoutes(ctx) {
       const os = await import('os');
       const root = req.query.root || ctx.projectDir || process.cwd() || os.default.homedir();
       const options = {
-        // Default to both .md and .ipynb (like Electron)
-        extensions: req.query.extensions?.split(',') || ['.md', '.ipynb'],
+        // Default to markdown-like docs and .ipynb (like Electron)
+        extensions: req.query.extensions?.split(',') || ['.md', '.qmd', '.ipynb'],
         maxDepth: parseInt(req.query.maxDepth) || 10,
         includeHidden: req.query.includeHidden === 'true',
       };

package/src/api/julia.js

@@ -1,17 +1,56 @@
 /**
  * Julia Session API routes
  *
- * Mirrors electronAPI.julia.*
+ * Mirrors electronAPI.julia.* using JuliaSessionService from mrmd-electron
  */
 
 import { Router } from 'express';
+import { Project } from 'mrmd-project';
 import { spawn } from 'child_process';
+import fs from 'fs';
 import path from 'path';
-import fs from 'fs/promises';
-import net from 'net';
 
-// Session registry: sessionName -> { port, process, cwd }
-const sessions = new Map();
+/**
+ * Detect project from a file path
+ */
+function detectProject(filePath) {
+  const root = Project.findRoot(filePath, (dir) => fs.existsSync(path.join(dir, 'mrmd.md')));
+  if (!root) return null;
+
+  try {
+    const mrmdPath = path.join(root, 'mrmd.md');
+    const content = fs.readFileSync(mrmdPath, 'utf8');
+    const config = Project.parseConfig(content);
+    return { root, config };
+  } catch (e) {
+    return { root, config: {} };
+  }
+}
+
+/**
+ * Check if Julia is available on the system
+ */
+async function isJuliaAvailable() {
+  return new Promise((resolve) => {
+    const proc = spawn('julia', ['--version'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    proc.on('close', (code) => {
+      resolve(code === 0);
+    });
+
+    proc.on('error', () => {
+      resolve(false);
+    });
+
+    // Timeout after 5 seconds
+    setTimeout(() => {
+      proc.kill();
+      resolve(false);
+    }, 5000);
+  });
+}
 
 /**
  * Create Julia routes
@@ -19,6 +58,7 @@ const sessions = new Map();
  */
 export function createJuliaRoutes(ctx) {
   const router = Router();
+  const { juliaSessionService } = ctx;
 
   /**
    * GET /api/julia
@@ -27,15 +67,7 @@ export function createJuliaRoutes(ctx) {
    */
   router.get('/', async (req, res) => {
     try {
-      const list = [];
-      for (const [name, session] of sessions) {
-        list.push({
-          name,
-          port: session.port,
-          cwd: session.cwd,
-          running: session.process && !session.process.killed,
-        });
-      }
+      const list = juliaSessionService.list();
       res.json(list);
     } catch (err) {
       console.error('[julia:list]', err);
@@ -66,9 +98,8 @@ export function createJuliaRoutes(ctx) {
   router.post('/', async (req, res) => {
     try {
       const { config } = req.body;
-      const { name, cwd } = config || {};
 
-      if (!name) {
+      if (!config?.name) {
         return res.status(400).json({ error: 'config.name required' });
       }
 
@@ -77,57 +108,14 @@ export function createJuliaRoutes(ctx) {
         return res.status(503).json({ error: 'Julia is not available on this system' });
       }
 
-      // Check if session already exists
-      if (sessions.has(name)) {
-        const existing = sessions.get(name);
-        if (existing.process && !existing.process.killed) {
-          return res.json({
-            name,
-            port: existing.port,
-            cwd: existing.cwd,
-            reused: true,
-          });
-        }
-      }
-
-      // Find free port
-      const port = await findFreePort(9001, 9100);
-      const workDir = cwd ? path.resolve(ctx.projectDir, cwd) : ctx.projectDir;
-
-      // Start Julia MRP server
-      // Note: This assumes mrmd-julia is installed and provides an MRP-compatible server
-      const proc = spawn('julia', [
-        '-e',
-        `using MrmdJulia; MrmdJulia.serve(${port})`,
-      ], {
-        cwd: workDir,
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-
-      // Wait for server to start (with timeout)
-      try {
-        await waitForPort(port, 15000);
-      } catch (err) {
-        proc.kill();
-        return res.status(500).json({ error: `Julia server failed to start: ${err.message}` });
-      }
-
-      sessions.set(name, {
-        port,
-        process: proc,
-        cwd: workDir,
-      });
-
-      proc.on('exit', (code) => {
-        console.log(`[julia] ${name} exited with code ${code}`);
-        sessions.delete(name);
-      });
+      const result = await juliaSessionService.start(config);
 
       res.json({
-        name,
-        port,
-        cwd: workDir,
-        url: `http://localhost:${port}/mrp/v1`,
+        name: result.name,
+        port: result.port,
+        cwd: result.cwd,
+        pid: result.pid,
+        url: `http://localhost:${result.port}/mrp/v1`,
       });
     } catch (err) {
       console.error('[julia:start]', err);
@@ -143,21 +131,11 @@ export function createJuliaRoutes(ctx) {
   router.delete('/:name', async (req, res) => {
     try {
       const { name } = req.params;
-      const session = sessions.get(name);
-
-      if (!session) {
-        return res.json({ success: true, message: 'Session not found' });
-      }
-
-      if (session.process && !session.process.killed) {
-        session.process.kill();
-      }
-
-      sessions.delete(name);
+      await juliaSessionService.stop(name);
       res.json({ success: true });
     } catch (err) {
       console.error('[julia:stop]', err);
-      res.status(500).json({ error: err.message });
+      res.json({ success: true, message: err.message });
     }
   });
 
@@ -169,26 +147,15 @@ export function createJuliaRoutes(ctx) {
   router.post('/:name/restart', async (req, res) => {
     try {
       const { name } = req.params;
-      const session = sessions.get(name);
-
-      if (!session) {
-        return res.status(404).json({ error: 'Session not found' });
-      }
-
-      // Kill existing
-      if (session.process && !session.process.killed) {
-        session.process.kill();
-      }
-
-      // Re-create
-      const cwd = session.cwd;
-      sessions.delete(name);
+      const result = await juliaSessionService.restart(name);
 
-      // Forward to start handler
-      req.body.config = { name, cwd };
-      // Recursively call POST /
-      // In production, extract logic to shared function
-      return res.redirect(307, '/api/julia');
+      res.json({
+        name: result.name,
+        port: result.port,
+        cwd: result.cwd,
+        pid: result.pid,
+        url: `http://localhost:${result.port}/mrp/v1`,
+      });
     } catch (err) {
       console.error('[julia:restart]', err);
       res.status(500).json({ error: err.message });
@@ -199,10 +166,13 @@ export function createJuliaRoutes(ctx) {
    * POST /api/julia/for-document
    * Get or create Julia session for a document
    * Mirrors: electronAPI.julia.forDocument(documentPath)
+   *
+   * Automatically detects project if projectConfig/projectRoot not provided
    */
   router.post('/for-document', async (req, res) => {
     try {
-      const { documentPath } = req.body;
+      let { documentPath, projectConfig, frontmatter, projectRoot } = req.body;
+
       if (!documentPath) {
         return res.status(400).json({ error: 'documentPath required' });
       }
@@ -212,134 +182,46 @@ export function createJuliaRoutes(ctx) {
         return res.json(null);
       }
 
-      const docName = `julia-${path.basename(documentPath, '.md')}`;
-
-      // Check if session exists
-      if (sessions.has(docName)) {
-        const session = sessions.get(docName);
-        return res.json({
-          name: docName,
-          port: session.port,
-          cwd: session.cwd,
-          url: `http://localhost:${session.port}/mrp/v1`,
-        });
+      // Auto-detect project if not provided
+      if (!projectConfig || !projectRoot) {
+        const detected = detectProject(documentPath);
+        if (detected) {
+          projectRoot = projectRoot || detected.root;
+          projectConfig = projectConfig || detected.config;
+        } else {
+          projectRoot = projectRoot || (ctx.projectDir || process.cwd());
+          projectConfig = projectConfig || {};
+        }
       }
 
-      // Create session
-      const fullPath = path.resolve(ctx.projectDir, documentPath);
-      const port = await findFreePort(9001, 9100);
-      const workDir = path.dirname(fullPath);
+      // Auto-parse frontmatter if not provided
+      if (!frontmatter) {
+        try {
+          const content = fs.readFileSync(documentPath, 'utf8');
+          frontmatter = Project.parseFrontmatter(content);
+        } catch (e) {
+          frontmatter = null;
+        }
+      }
 
-      const proc = spawn('julia', [
-        '-e',
-        `using MrmdJulia; MrmdJulia.serve(${port})`,
-      ], {
-        cwd: workDir,
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
+      const result = await juliaSessionService.getForDocument(
+        documentPath,
+        projectConfig,
+        frontmatter,
+        projectRoot
+      );
 
-      try {
-        await waitForPort(port, 15000);
-      } catch (err) {
-        proc.kill();
-        return res.json(null);
+      // Add url if we have a port
+      if (result?.port) {
+        result.url = `http://localhost:${result.port}/mrp/v1`;
       }
 
-      sessions.set(docName, {
-        port,
-        process: proc,
-        cwd: workDir,
-      });
-
-      res.json({
-        name: docName,
-        port,
-        cwd: workDir,
-        url: `http://localhost:${port}/mrp/v1`,
-      });
+      res.json(result);
     } catch (err) {
       console.error('[julia:forDocument]', err);
-      res.status(500).json({ error: err.message });
+      res.json(null);
     }
   });
 
   return router;
 }
-
-/**
- * Check if Julia is available
- */
-async function isJuliaAvailable() {
-  return new Promise((resolve) => {
-    const proc = spawn('julia', ['--version'], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    proc.on('close', (code) => {
-      resolve(code === 0);
-    });
-
-    proc.on('error', () => {
-      resolve(false);
-    });
-
-    // Timeout after 5 seconds
-    setTimeout(() => {
-      proc.kill();
-      resolve(false);
-    }, 5000);
-  });
-}
-
-/**
- * Find a free port in range
- */
-async function findFreePort(start, end) {
-  for (let port = start; port <= end; port++) {
-    if (await isPortFree(port)) {
-      return port;
-    }
-  }
-  throw new Error(`No free port found in range ${start}-${end}`);
-}
-
-/**
- * Check if port is free
- */
-function isPortFree(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-    server.once('error', () => resolve(false));
-    server.once('listening', () => {
-      server.close();
-      resolve(true);
-    });
-    server.listen(port, '127.0.0.1');
-  });
-}
-
-/**
- * Wait for port to be open
- */
-function waitForPort(port, timeout = 10000) {
-  return new Promise((resolve, reject) => {
-    const start = Date.now();
-
-    function check() {
-      const socket = net.connect(port, '127.0.0.1');
-      socket.once('connect', () => {
-        socket.end();
-        resolve();
-      });
-      socket.once('error', () => {
-        if (Date.now() - start > timeout) {
-          reject(new Error(`Timeout waiting for port ${port}`));
-        } else {
-          setTimeout(check, 200);
-        }
-      });
-    }
-
-    check();
-  });
-}

package/src/api/project.js

@@ -12,6 +12,23 @@ import { existsSync, readFileSync } from 'fs';
 import { watch } from 'chokidar';
 import { Project } from 'mrmd-project';
 
+const DOC_EXTENSIONS = ['.md', '.qmd'];
+
+function isDocFile(filePath) {
+  if (!filePath) return false;
+  const lower = filePath.toLowerCase();
+  return DOC_EXTENSIONS.some(ext => lower.endsWith(ext));
+}
+
+function stripDocExtension(fileName) {
+  if (!fileName) return '';
+  const lower = fileName.toLowerCase();
+  for (const ext of DOC_EXTENSIONS) {
+    if (lower.endsWith(ext)) return fileName.slice(0, -ext.length);
+  }
+  return fileName;
+}
+
 /**
  * Detect project from a file path
  * Returns { root, config } or null if not in a project
@@ -226,7 +243,7 @@ export function createProjectRoutes(ctx) {
       });
 
       watcher.on('all', (event, filePath) => {
-        if (filePath.endsWith('.md')) {
+        if (isDocFile(filePath)) {
           ctx.eventBus.projectChanged(watchPath);
         }
       });
@@ -411,7 +428,7 @@ async function buildNavTree(projectRoot, relativePath = '') {
 
     if (entry.isDirectory()) {
       const children = await buildNavTree(projectRoot, entryRelPath);
-      // Only include directories that have .md files (directly or nested)
+      // Only include directories that have markdown-like doc files (directly or nested)
       if (children.length > 0 || await hasIndexFile(path.join(projectRoot, entryRelPath))) {
         nodes.push({
           isFolder: true,
@@ -420,10 +437,10 @@ async function buildNavTree(projectRoot, relativePath = '') {
           children,
         });
       }
-    } else if (entry.name.endsWith('.md') && entry.name !== 'mrmd.md') {
+    } else if (isDocFile(entry.name) && entry.name !== 'mrmd.md') {
       nodes.push({
         isFolder: false,
-        title: cleanName(entry.name.replace(/\.md$/, '')),
+        title: cleanName(stripDocExtension(entry.name)),
         path: entryRelPath,
       });
     }
@@ -438,7 +455,7 @@ async function buildNavTree(projectRoot, relativePath = '') {
 async function hasIndexFile(dirPath) {
   try {
     const entries = await fs.readdir(dirPath);
-    return entries.some(e => e.endsWith('.md'));
+    return entries.some(e => isDocFile(e));
   } catch {
     return false;
   }

package/src/api/r.js

@@ -1,17 +1,56 @@
 /**
  * R Session API routes
  *
- * Mirrors electronAPI.r.* (if it existed in preload)
- * Provides R runtime management similar to Julia
+ * Mirrors electronAPI.r.* using RSessionService from mrmd-electron
  */
 
 import { Router } from 'express';
+import { Project } from 'mrmd-project';
 import { spawn } from 'child_process';
+import fs from 'fs';
 import path from 'path';
-import net from 'net';
 
-// Session registry: sessionName -> { port, process, cwd }
-const sessions = new Map();
+/**
+ * Detect project from a file path
+ */
+function detectProject(filePath) {
+  const root = Project.findRoot(filePath, (dir) => fs.existsSync(path.join(dir, 'mrmd.md')));
+  if (!root) return null;
+
+  try {
+    const mrmdPath = path.join(root, 'mrmd.md');
+    const content = fs.readFileSync(mrmdPath, 'utf8');
+    const config = Project.parseConfig(content);
+    return { root, config };
+  } catch (e) {
+    return { root, config: {} };
+  }
+}
+
+/**
+ * Check if R is available on the system
+ */
+async function isRAvailable() {
+  return new Promise((resolve) => {
+    const proc = spawn('R', ['--version'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    proc.on('close', (code) => {
+      resolve(code === 0);
+    });
+
+    proc.on('error', () => {
+      resolve(false);
+    });
+
+    // Timeout after 5 seconds
+    setTimeout(() => {
+      proc.kill();
+      resolve(false);
+    }, 5000);
+  });
+}
 
 /**
  * Create R routes
@@ -19,22 +58,16 @@ const sessions = new Map();
  */
 export function createRRoutes(ctx) {
   const router = Router();
+  const { rSessionService } = ctx;
 
   /**
    * GET /api/r
    * List all running R sessions
+   * Mirrors: electronAPI.r.list()
    */
   router.get('/', async (req, res) => {
     try {
-      const list = [];
-      for (const [name, session] of sessions) {
-        list.push({
-          name,
-          port: session.port,
-          cwd: session.cwd,
-          running: session.process && !session.process.killed,
-        });
-      }
+      const list = rSessionService.list();
       res.json(list);
     } catch (err) {
       console.error('[r:list]', err);
@@ -59,13 +92,13 @@ export function createRRoutes(ctx) {
   /**
    * POST /api/r
    * Start a new R session
+   * Mirrors: electronAPI.r.start(config)
    */
   router.post('/', async (req, res) => {
     try {
       const { config } = req.body;
-      const { name, cwd } = config || {};
 
-      if (!name) {
+      if (!config?.name) {
         return res.status(400).json({ error: 'config.name required' });
       }
 
@@ -74,57 +107,14 @@ export function createRRoutes(ctx) {
         return res.status(503).json({ error: 'R is not available on this system' });
       }
 
-      // Check if session already exists
-      if (sessions.has(name)) {
-        const existing = sessions.get(name);
-        if (existing.process && !existing.process.killed) {
-          return res.json({
-            name,
-            port: existing.port,
-            cwd: existing.cwd,
-            reused: true,
-          });
-        }
-      }
-
-      // Find free port
-      const port = await findFreePort(9101, 9200);
-      const workDir = cwd ? path.resolve(ctx.projectDir, cwd) : ctx.projectDir;
-
-      // Start R MRP server
-      // Note: This assumes mrmd-r is installed and provides an MRP-compatible server
-      const proc = spawn('Rscript', [
-        '-e',
-        `mrmd.r::serve(${port})`,
-      ], {
-        cwd: workDir,
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-
-      // Wait for server to start (with timeout)
-      try {
-        await waitForPort(port, 15000);
-      } catch (err) {
-        proc.kill();
-        return res.status(500).json({ error: `R server failed to start: ${err.message}` });
-      }
-
-      sessions.set(name, {
-        port,
-        process: proc,
-        cwd: workDir,
-      });
-
-      proc.on('exit', (code) => {
-        console.log(`[r] ${name} exited with code ${code}`);
-        sessions.delete(name);
-      });
+      const result = await rSessionService.start(config);
 
       res.json({
-        name,
-        port,
-        cwd: workDir,
-        url: `http://localhost:${port}/mrp/v1`,
+        name: result.name,
+        port: result.port,
+        cwd: result.cwd,
+        pid: result.pid,
+        url: `http://localhost:${result.port}/mrp/v1`,
       });
     } catch (err) {
       console.error('[r:start]', err);
@@ -135,53 +125,36 @@ export function createRRoutes(ctx) {
   /**
    * DELETE /api/r/:name
    * Stop an R session
+   * Mirrors: electronAPI.r.stop(sessionName)
    */
   router.delete('/:name', async (req, res) => {
     try {
       const { name } = req.params;
-      const session = sessions.get(name);
-
-      if (!session) {
-        return res.json({ success: true, message: 'Session not found' });
-      }
-
-      if (session.process && !session.process.killed) {
-        session.process.kill();
-      }
-
-      sessions.delete(name);
+      await rSessionService.stop(name);
       res.json({ success: true });
     } catch (err) {
       console.error('[r:stop]', err);
-      res.status(500).json({ error: err.message });
+      res.json({ success: true, message: err.message });
     }
   });
 
   /**
    * POST /api/r/:name/restart
    * Restart an R session
+   * Mirrors: electronAPI.r.restart(sessionName)
    */
   router.post('/:name/restart', async (req, res) => {
     try {
       const { name } = req.params;
-      const session = sessions.get(name);
-
-      if (!session) {
-        return res.status(404).json({ error: 'Session not found' });
-      }
-
-      // Kill existing
-      if (session.process && !session.process.killed) {
-        session.process.kill();
-      }
-
-      // Re-create
-      const cwd = session.cwd;
-      sessions.delete(name);
+      const result = await rSessionService.restart(name);
 
-      // Forward to start handler
-      req.body.config = { name, cwd };
-      return res.redirect(307, '/api/r');
+      res.json({
+        name: result.name,
+        port: result.port,
+        cwd: result.cwd,
+        pid: result.pid,
+        url: `http://localhost:${result.port}/mrp/v1`,
+      });
     } catch (err) {
       console.error('[r:restart]', err);
       res.status(500).json({ error: err.message });
@@ -191,10 +164,14 @@ export function createRRoutes(ctx) {
   /**
    * POST /api/r/for-document
    * Get or create R session for a document
+   * Mirrors: electronAPI.r.forDocument(documentPath)
+   *
+   * Automatically detects project if projectConfig/projectRoot not provided
    */
   router.post('/for-document', async (req, res) => {
     try {
-      const { documentPath } = req.body;
+      let { documentPath, projectConfig, frontmatter, projectRoot } = req.body;
+
       if (!documentPath) {
         return res.status(400).json({ error: 'documentPath required' });
       }
@@ -204,134 +181,46 @@ export function createRRoutes(ctx) {
         return res.json(null);
       }
 
-      const docName = `r-${path.basename(documentPath, '.md')}`;
-
-      // Check if session exists
-      if (sessions.has(docName)) {
-        const session = sessions.get(docName);
-        return res.json({
-          name: docName,
-          port: session.port,
-          cwd: session.cwd,
-          url: `http://localhost:${session.port}/mrp/v1`,
-        });
+      // Auto-detect project if not provided
+      if (!projectConfig || !projectRoot) {
+        const detected = detectProject(documentPath);
+        if (detected) {
+          projectRoot = projectRoot || detected.root;
+          projectConfig = projectConfig || detected.config;
+        } else {
+          projectRoot = projectRoot || (ctx.projectDir || process.cwd());
+          projectConfig = projectConfig || {};
+        }
       }
 
-      // Create session
-      const fullPath = path.resolve(ctx.projectDir, documentPath);
-      const port = await findFreePort(9101, 9200);
-      const workDir = path.dirname(fullPath);
+      // Auto-parse frontmatter if not provided
+      if (!frontmatter) {
+        try {
+          const content = fs.readFileSync(documentPath, 'utf8');
+          frontmatter = Project.parseFrontmatter(content);
+        } catch (e) {
+          frontmatter = null;
+        }
+      }
 
-      const proc = spawn('Rscript', [
-        '-e',
-        `mrmd.r::serve(${port})`,
-      ], {
-        cwd: workDir,
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
+      const result = await rSessionService.getForDocument(
+        documentPath,
+        projectConfig,
+        frontmatter,
+        projectRoot
+      );
 
-      try {
-        await waitForPort(port, 15000);
-      } catch (err) {
-        proc.kill();
-        return res.json(null);
+      // Add url if we have a port
+      if (result?.port) {
+        result.url = `http://localhost:${result.port}/mrp/v1`;
       }
 
-      sessions.set(docName, {
-        port,
-        process: proc,
-        cwd: workDir,
-      });
-
-      res.json({
-        name: docName,
-        port,
-        cwd: workDir,
-        url: `http://localhost:${port}/mrp/v1`,
-      });
+      res.json(result);
     } catch (err) {
       console.error('[r:forDocument]', err);
-      res.status(500).json({ error: err.message });
+      res.json(null);
     }
   });
 
   return router;
 }
-
-/**
- * Check if R is available
- */
-async function isRAvailable() {
-  return new Promise((resolve) => {
-    const proc = spawn('R', ['--version'], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    proc.on('close', (code) => {
-      resolve(code === 0);
-    });
-
-    proc.on('error', () => {
-      resolve(false);
-    });
-
-    // Timeout after 5 seconds
-    setTimeout(() => {
-      proc.kill();
-      resolve(false);
-    }, 5000);
-  });
-}
-
-/**
- * Find a free port in range
- */
-async function findFreePort(start, end) {
-  for (let port = start; port <= end; port++) {
-    if (await isPortFree(port)) {
-      return port;
-    }
-  }
-  throw new Error(`No free port found in range ${start}-${end}`);
-}
-
-/**
- * Check if port is free
- */
-function isPortFree(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-    server.once('error', () => resolve(false));
-    server.once('listening', () => {
-      server.close();
-      resolve(true);
-    });
-    server.listen(port, '127.0.0.1');
-  });
-}
-
-/**
- * Wait for port to be open
- */
-function waitForPort(port, timeout = 10000) {
-  return new Promise((resolve, reject) => {
-    const start = Date.now();
-
-    function check() {
-      const socket = net.connect(port, '127.0.0.1');
-      socket.once('connect', () => {
-        socket.end();
-        resolve();
-      });
-      socket.once('error', () => {
-        if (Date.now() - start > timeout) {
-          reject(new Error(`Timeout waiting for port ${port}`));
-        } else {
-          setTimeout(check, 200);
-        }
-      });
-    }
-
-    check();
-  });
-}

package/static/http-shim.js

@@ -299,7 +299,8 @@
 
       // Extract filename without extension for docName
       const fileName = filePath.split('/').pop();
-      const docName = fileName.replace(/\.md$/, '');
+      const lower = fileName.toLowerCase();
+      const docName = lower.endsWith('.md') ? fileName.replace(/\.md$/i, '') : fileName;
 
       // Use syncPort from project response (dynamically assigned per-project)
       const syncPort = project?.syncPort || 4444;