@peaske7/readit 0.2.0 → 0.3.0-rc.0

package/vscode-readit/.mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "forge_extension": {
+      "url": "http://localhost:51079/mcp"
+    }
+  }
+}

package/vscode-readit/.vscodeignore

@@ -0,0 +1,7 @@
+.vscode/**
+src/**
+node_modules/**
+tsconfig.json
+.gitignore
+.mcp.json
+**/*.map

package/vscode-readit/bun.lock

@@ -0,0 +1,78 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "vscode-readit",
+      "devDependencies": {
+        "@types/node": "^25.5.2",
+        "@types/vscode": "^1.110.0",
+        "esbuild": "^0.25.12",
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.25.12", "https://npm.flatt.tech/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", { "os": "aix", "cpu": "ppc64" }, "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA=="],
+
+    "@esbuild/android-arm": ["@esbuild/android-arm@0.25.12", "https://npm.flatt.tech/@esbuild/android-arm/-/android-arm-0.25.12.tgz", { "os": "android", "cpu": "arm" }, "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg=="],
+
+    "@esbuild/android-arm64": ["@esbuild/android-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz", { "os": "android", "cpu": "arm64" }, "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg=="],
+
+    "@esbuild/android-x64": ["@esbuild/android-x64@0.25.12", "https://npm.flatt.tech/@esbuild/android-x64/-/android-x64-0.25.12.tgz", { "os": "android", "cpu": "x64" }, "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg=="],
+
+    "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg=="],
+
+    "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.25.12", "https://npm.flatt.tech/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz", { "os": "darwin", "cpu": "x64" }, "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA=="],
+
+    "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz", { "os": "freebsd", "cpu": "arm64" }, "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg=="],
+
+    "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.25.12", "https://npm.flatt.tech/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz", { "os": "freebsd", "cpu": "x64" }, "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ=="],
+
+    "@esbuild/linux-arm": ["@esbuild/linux-arm@0.25.12", "https://npm.flatt.tech/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz", { "os": "linux", "cpu": "arm" }, "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw=="],
+
+    "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ=="],
+
+    "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.25.12", "https://npm.flatt.tech/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz", { "os": "linux", "cpu": "ia32" }, "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA=="],
+
+    "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.25.12", "https://npm.flatt.tech/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz", { "os": "linux", "cpu": "none" }, "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng=="],
+
+    "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.25.12", "https://npm.flatt.tech/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz", { "os": "linux", "cpu": "none" }, "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw=="],
+
+    "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.25.12", "https://npm.flatt.tech/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz", { "os": "linux", "cpu": "ppc64" }, "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA=="],
+
+    "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.25.12", "https://npm.flatt.tech/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz", { "os": "linux", "cpu": "none" }, "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w=="],
+
+    "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.25.12", "https://npm.flatt.tech/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz", { "os": "linux", "cpu": "s390x" }, "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg=="],
+
+    "@esbuild/linux-x64": ["@esbuild/linux-x64@0.25.12", "https://npm.flatt.tech/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz", { "os": "linux", "cpu": "x64" }, "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw=="],
+
+    "@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz", { "os": "none", "cpu": "arm64" }, "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg=="],
+
+    "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.25.12", "https://npm.flatt.tech/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz", { "os": "none", "cpu": "x64" }, "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ=="],
+
+    "@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz", { "os": "openbsd", "cpu": "arm64" }, "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A=="],
+
+    "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.25.12", "https://npm.flatt.tech/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz", { "os": "openbsd", "cpu": "x64" }, "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw=="],
+
+    "@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz", { "os": "none", "cpu": "arm64" }, "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg=="],
+
+    "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.25.12", "https://npm.flatt.tech/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz", { "os": "sunos", "cpu": "x64" }, "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w=="],
+
+    "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.25.12", "https://npm.flatt.tech/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz", { "os": "win32", "cpu": "arm64" }, "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg=="],
+
+    "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.25.12", "https://npm.flatt.tech/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz", { "os": "win32", "cpu": "ia32" }, "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ=="],
+
+    "@esbuild/win32-x64": ["@esbuild/win32-x64@0.25.12", "https://npm.flatt.tech/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz", { "os": "win32", "cpu": "x64" }, "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA=="],
+
+    "@types/node": ["@types/node@25.5.2", "https://npm.flatt.tech/@types/node/-/node-25.5.2.tgz", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
+
+    "@types/vscode": ["@types/vscode@1.110.0", "https://npm.flatt.tech/@types/vscode/-/vscode-1.110.0.tgz", {}, "sha512-AGuxUEpU4F4mfuQjxPPaQVyuOMhs+VT/xRok1jiHVBubHK7lBRvCuOMZG0LKUwxncrPorJ5qq/uil3IdZBd5lA=="],
+
+    "esbuild": ["esbuild@0.25.12", "https://npm.flatt.tech/esbuild/-/esbuild-0.25.12.tgz", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.25.12", "@esbuild/android-arm": "0.25.12", "@esbuild/android-arm64": "0.25.12", "@esbuild/android-x64": "0.25.12", "@esbuild/darwin-arm64": "0.25.12", "@esbuild/darwin-x64": "0.25.12", "@esbuild/freebsd-arm64": "0.25.12", "@esbuild/freebsd-x64": "0.25.12", "@esbuild/linux-arm": "0.25.12", "@esbuild/linux-arm64": "0.25.12", "@esbuild/linux-ia32": "0.25.12", "@esbuild/linux-loong64": "0.25.12", "@esbuild/linux-mips64el": "0.25.12", "@esbuild/linux-ppc64": "0.25.12", "@esbuild/linux-riscv64": "0.25.12", "@esbuild/linux-s390x": "0.25.12", "@esbuild/linux-x64": "0.25.12", "@esbuild/netbsd-arm64": "0.25.12", "@esbuild/netbsd-x64": "0.25.12", "@esbuild/openbsd-arm64": "0.25.12", "@esbuild/openbsd-x64": "0.25.12", "@esbuild/openharmony-arm64": "0.25.12", "@esbuild/sunos-x64": "0.25.12", "@esbuild/win32-arm64": "0.25.12", "@esbuild/win32-ia32": "0.25.12", "@esbuild/win32-x64": "0.25.12" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg=="],
+
+    "typescript": ["typescript@5.9.3", "https://npm.flatt.tech/typescript/-/typescript-5.9.3.tgz", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "https://npm.flatt.tech/undici-types/-/undici-types-7.18.2.tgz", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}

package/vscode-readit/icon.svg

@@ -0,0 +1,10 @@
+<svg viewBox="-75 -80 150 160" xmlns="http://www.w3.org/2000/svg">
+<g fill="#E07A50">
+<path d="M-8 -68 C-24 -66, -48 -52, -56 -30 C-64 -8, -58 18, -44 36 C-30 54, -8 66, 14 66 C36 66, 54 52, 60 32 C66 12, 58 -12, 44 -30 C30 -48, 10 -56, -2 -62 C-6 -64, -4 -70, -8 -68Z"/>
+<circle cx="6" cy="-4" r="26" fill="#fff"/>
+<circle cx="6" cy="-4" r="18" fill="#E07A50"/>
+<circle cx="6" cy="-4" r="10" fill="#fff"/>
+<circle cx="10" cy="-6" r="4.5"/>
+<path d="M30 -18 C38 -26, 50 -34, 56 -44 C60 -50, 56 -56, 50 -52 C44 -46, 36 -32, 30 -22Z"/>
+</g>
+</svg>

package/vscode-readit/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "vscode-readit",
+  "displayName": "readit",
+  "description": "Review Markdown documents with inline comments — powered by readit",
+  "version": "0.0.1",
+  "publisher": "peaske7",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/peaske7/readit"
+  },
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": [
+    "Other",
+    "Visualization"
+  ],
+  "keywords": [
+    "markdown",
+    "review",
+    "comments",
+    "preview"
+  ],
+  "activationEvents": [
+    "onLanguage:markdown",
+    "onCommand:readit.openPreview",
+    "onCommand:readit.openPreviewToSide"
+  ],
+  "icon": "icon.svg",
+  "main": "./dist/extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "readit.openPreview",
+        "title": "readit: Open Preview",
+        "icon": {
+          "light": "icon.svg",
+          "dark": "icon.svg"
+        }
+      },
+      {
+        "command": "readit.openPreviewToSide",
+        "title": "readit: Open Preview to the Side",
+        "icon": {
+          "light": "icon.svg",
+          "dark": "icon.svg"
+        }
+      }
+    ],
+    "menus": {
+      "editor/title": [
+        {
+          "when": "resourceLangId == markdown",
+          "command": "readit.openPreviewToSide",
+          "group": "navigation"
+        }
+      ],
+      "explorer/context": [
+        {
+          "when": "resourceLangId == markdown",
+          "command": "readit.openPreview",
+          "group": "navigation"
+        }
+      ],
+      "editor/context": [
+        {
+          "when": "resourceLangId == markdown",
+          "command": "readit.openPreview",
+          "group": "navigation"
+        }
+      ]
+    },
+    "keybindings": [
+      {
+        "command": "readit.openPreviewToSide",
+        "key": "ctrl+shift+r",
+        "mac": "cmd+shift+r",
+        "when": "resourceLangId == markdown"
+      }
+    ],
+    "configuration": {
+      "title": "readit",
+      "properties": {
+        "readit.bunPath": {
+          "type": "string",
+          "default": "bun",
+          "description": "Path to the Bun runtime executable."
+        },
+        "readit.serverPort": {
+          "type": "number",
+          "default": 0,
+          "description": "Port for the readit server. 0 = auto-select a free port."
+        }
+      }
+    }
+  },
+  "scripts": {
+    "build": "esbuild src/extension.ts --bundle --outfile=dist/extension.js --external:vscode --format=cjs --platform=node --minify",
+    "watch": "esbuild src/extension.ts --bundle --outfile=dist/extension.js --external:vscode --format=cjs --platform=node --sourcemap --watch",
+    "typecheck": "tsc --noEmit",
+    "package": "vsce package"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@types/vscode": "^1.110.0",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.9.3"
+  }
+}

package/vscode-readit/src/extension.ts

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import * as vscode from "vscode";
+import { ServerManager } from "./server-manager";
+import { ReaditWebviewProvider } from "./webview-provider";
+
+let serverManager: ServerManager | undefined;
+let webviewProvider: ReaditWebviewProvider | undefined;
+let outputChannel: vscode.OutputChannel | undefined;
+
+/**
+ * Resolves the readit CLI dist/ directory for the mono-repo layout and throws
+ * if the built CLI is not available before the extension tries to start it.
+ */
+function resolveReaditDistDir(extensionPath: string): string {
+  const monoRepoDist = path.resolve(extensionPath, "..", "dist");
+  if (!existsSync(path.join(monoRepoDist, "index.js"))) {
+    throw new Error(
+      "Could not find readit/dist/index.js. Build the readit CLI before using the VS Code extension.",
+    );
+  }
+  return monoRepoDist;
+}
+
+/**
+ * Gets the absolute file path from a command argument or the active editor.
+ */
+function resolveFilePath(arg?: vscode.Uri): string | undefined {
+  // When invoked from explorer context menu or editor title, arg is a Uri
+  if (arg instanceof vscode.Uri) {
+    return arg.fsPath;
+  }
+
+  // Fall back to active editor
+  const editor = vscode.window.activeTextEditor;
+  if (editor && editor.document.languageId === "markdown") {
+    return editor.document.uri.fsPath;
+  }
+
+  return undefined;
+}
+
+export function activate(context: vscode.ExtensionContext): void {
+  outputChannel = vscode.window.createOutputChannel("readit");
+  serverManager = new ServerManager(outputChannel);
+  webviewProvider = new ReaditWebviewProvider(
+    context.extensionUri,
+    serverManager,
+    outputChannel,
+  );
+
+  let readitDistDir: string;
+  try {
+    readitDistDir = resolveReaditDistDir(context.extensionPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    outputChannel.appendLine(message);
+    void vscode.window.showErrorMessage(`readit: ${message}`);
+    return;
+  }
+
+  // readit.openPreview — opens in the active column
+  const openPreview = vscode.commands.registerCommand(
+    "readit.openPreview",
+    async (arg?: vscode.Uri) => {
+      const filePath = resolveFilePath(arg);
+      if (!filePath) {
+        vscode.window.showWarningMessage(
+          "readit: No Markdown file is open or selected.",
+        );
+        return;
+      }
+
+      await webviewProvider!.openPreview(
+        filePath,
+        readitDistDir,
+        vscode.ViewColumn.Active,
+      );
+    },
+  );
+
+  // readit.openPreviewToSide — opens beside the current editor
+  const openPreviewToSide = vscode.commands.registerCommand(
+    "readit.openPreviewToSide",
+    async (arg?: vscode.Uri) => {
+      const filePath = resolveFilePath(arg);
+      if (!filePath) {
+        vscode.window.showWarningMessage(
+          "readit: No Markdown file is open or selected.",
+        );
+        return;
+      }
+
+      await webviewProvider!.openPreview(
+        filePath,
+        readitDistDir,
+        vscode.ViewColumn.Beside,
+      );
+    },
+  );
+
+  context.subscriptions.push(
+    outputChannel,
+    serverManager,
+    webviewProvider,
+    openPreview,
+    openPreviewToSide,
+  );
+}
+
+export function deactivate(): void {
+  // Disposables registered on context.subscriptions are cleaned up automatically.
+  // Explicit cleanup as a safety net:
+  webviewProvider?.dispose();
+  serverManager?.dispose();
+  outputChannel?.dispose();
+}

package/vscode-readit/src/server-manager.ts

@@ -0,0 +1,272 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import * as net from "node:net";
+import * as vscode from "vscode";
+
+/**
+ * Manages the lifecycle of a readit Bun server process.
+ *
+ * Spawns `bun dist/index.js <file> --no-open --port <port>` as a child process.
+ * Subsequent files are attached via POST /api/documents to the running server.
+ * The server is killed when the extension deactivates or the last panel closes.
+ */
+export class ServerManager implements vscode.Disposable {
+  private process: ChildProcess | null = null;
+  private port: number | null = null;
+  private outputChannel: vscode.OutputChannel;
+  private startPromise: Promise<number> | null = null;
+
+  constructor(outputChannel: vscode.OutputChannel) {
+    this.outputChannel = outputChannel;
+  }
+
+  /** Returns the port of the running server, or null if not started. */
+  getPort(): number | null {
+    return this.port;
+  }
+
+  /** Returns the base URL of the running server. */
+  getBaseUrl(): string | null {
+    if (this.port === null) return null;
+    return `http://127.0.0.1:${this.port}`;
+  }
+
+  /** True if the server process is running. */
+  isRunning(): boolean {
+    return this.process !== null && this.process.exitCode === null;
+  }
+
+  /**
+   * Ensures the server is running and the given file is loaded.
+   * If the server is not started, spawns it with the file.
+   * If already running, attaches the file via the HTTP API.
+   * Returns the port number.
+   */
+  async ensureRunning(
+    filePath: string,
+    readitDistDir: string,
+  ): Promise<number> {
+    if (this.startPromise) {
+      const port = await this.startPromise;
+      await this.attachFile(filePath);
+      return port;
+    }
+
+    if (this.isRunning() && this.port !== null) {
+      await this.attachFile(filePath);
+      return this.port;
+    }
+
+    return this.start(filePath, readitDistDir);
+  }
+
+  /**
+   * Starts the Bun server process.
+   * Resolves with the port once the server is healthy.
+   */
+  private start(filePath: string, readitDistDir: string): Promise<number> {
+    this.startPromise = this.doStart(filePath, readitDistDir);
+    return this.startPromise;
+  }
+
+  private async doStart(
+    filePath: string,
+    readitDistDir: string,
+  ): Promise<number> {
+    const config = vscode.workspace.getConfiguration("readit");
+    const bunPath = config.get<string>("bunPath", "bun");
+    const configPort = config.get<number>("serverPort", 0);
+
+    const port = configPort > 0 ? configPort : await findFreePort();
+
+    const cliEntry = vscode.Uri.joinPath(
+      vscode.Uri.file(readitDistDir),
+      "index.js",
+    ).fsPath;
+
+    const args = [cliEntry, filePath, "--no-open", "--port", String(port)];
+
+    this.outputChannel.appendLine(
+      `Starting readit server: ${bunPath} ${args.join(" ")}`,
+    );
+
+    return new Promise<number>((resolve, reject) => {
+      const child = spawn(bunPath, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          NODE_ENV: "production",
+        },
+      });
+
+      this.process = child;
+      let settled = false;
+      let timer: NodeJS.Timeout | undefined;
+
+      const rejectStartup = (message: string) => {
+        if (settled) return;
+        settled = true;
+        if (timer) {
+          clearInterval(timer);
+        }
+        this.cleanup(child);
+        reject(new Error(message));
+      };
+
+      child.stdout?.on("data", (data: Buffer) => {
+        this.outputChannel.appendLine(data.toString().trimEnd());
+      });
+
+      child.stderr?.on("data", (data: Buffer) => {
+        this.outputChannel.appendLine(`[stderr] ${data.toString().trimEnd()}`);
+      });
+
+      child.on("error", (err) => {
+        this.outputChannel.appendLine(`Server process error: ${err.message}`);
+        rejectStartup(
+          `Failed to start readit server. Is Bun installed? (${err.message})`,
+        );
+      });
+
+      const handleProcessExit = (
+        code: number | null,
+        signal: NodeJS.Signals | null,
+      ) => {
+        this.outputChannel.appendLine(
+          `Server process exited with code ${code}${signal ? ` (signal: ${signal})` : ""}`,
+        );
+        if (!settled) {
+          rejectStartup(
+            `readit server exited before it became ready (${code === null ? (signal ?? "unknown") : `code ${code}`})`,
+          );
+          return;
+        }
+        this.cleanup(child);
+      };
+
+      child.on("exit", handleProcessExit);
+
+      // Poll for server readiness
+      const maxWaitMs = 15_000;
+      const intervalMs = 200;
+      const startTime = Date.now();
+
+      timer = setInterval(async () => {
+        if (Date.now() - startTime > maxWaitMs) {
+          clearInterval(timer);
+          child.kill("SIGTERM");
+          rejectStartup("readit server failed to start within 15 seconds");
+          return;
+        }
+
+        try {
+          const res = await fetch(`http://127.0.0.1:${port}/api/health`);
+          if (res.ok) {
+            clearInterval(timer);
+            settled = true;
+            this.port = port;
+            this.outputChannel.appendLine(`Server ready on port ${port}`);
+            resolve(port);
+          }
+        } catch {
+          // Not ready yet, keep polling
+        }
+      }, intervalMs);
+    });
+  }
+
+  /**
+   * Attaches a file to the running server via POST /api/documents.
+   */
+  private async attachFile(filePath: string): Promise<void> {
+    if (this.port === null) return;
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${this.port}/api/documents`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ path: filePath }),
+      });
+
+      if (!res.ok) {
+        const raw = await res.text();
+        let errorMessage = res.statusText;
+        if (raw) {
+          try {
+            const data = JSON.parse(raw) as { error?: string };
+            errorMessage = data.error ?? raw;
+          } catch {
+            errorMessage = raw;
+          }
+        }
+        this.outputChannel.appendLine(
+          `Failed to attach file ${filePath}: ${errorMessage}`,
+        );
+      } else {
+        const data = (await res.json()) as {
+          status?: string;
+          fileName?: string;
+        };
+        this.outputChannel.appendLine(
+          `File ${data.fileName ?? filePath}: ${data.status ?? "attached"}`,
+        );
+      }
+    } catch (err) {
+      this.outputChannel.appendLine(
+        `Error attaching file: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /** Stops the server process. */
+  stop(): void {
+    const child = this.process;
+    if (child) {
+      this.outputChannel.appendLine("Stopping readit server...");
+      child.kill("SIGTERM");
+      let hasExited = false;
+
+      // Force kill after 3 seconds
+      const forceKillTimer = setTimeout(() => {
+        if (!hasExited && child.exitCode === null) {
+          child.kill("SIGKILL");
+        }
+      }, 3_000);
+
+      child.once("exit", () => {
+        hasExited = true;
+        clearTimeout(forceKillTimer);
+      });
+    }
+    this.cleanup();
+  }
+
+  private cleanup(child?: ChildProcess): void {
+    if (child && this.process !== child) {
+      return;
+    }
+    this.process = null;
+    this.port = null;
+    this.startPromise = null;
+  }
+
+  dispose(): void {
+    this.stop();
+  }
+}
+
+/** Finds a free TCP port by binding to port 0 and reading the assigned port. */
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr && typeof addr === "object") {
+        const port = addr.port;
+        server.close(() => resolve(port));
+      } else {
+        server.close(() => reject(new Error("Could not determine free port")));
+      }
+    });
+    server.on("error", reject);
+  });
+}