@corenel/sidecar 0.1.1 → 0.1.3

package/README.md

@@ -1,40 +1,40 @@
-# @corenel/sidecar
-
-A small local capability server for [Prompd](https://prompd.app). Run it next to the
-web app and the browser can reach your machine — most usefully, your **local LLMs**
-(Ollama, LM Studio, vLLM) **without CORS**, plus your filesystem and (opt-in) shell.
-
-It runs only while the command is open, binds to loopback by default, and pairs with
-a token the app reads once.
-
-## Use
-
-In Prompd, open **Connect a sidecar** and follow the steps, or run it directly:
-
-```bash
-npx @corenel/sidecar --allow-origin https://prompd.app
-```
-
-It prints a pairing token; paste that into the app. The `--allow-origin` flag must
-match the site you're connecting from (the app fills it in for you).
-
-## Options
-
-| Flag | Default | What |
-|------|---------|------|
-| `--allow-origin <url>` | _(none)_ | Browser origin allowed to connect. Required for a web page. Repeatable. |
-| `--port <n>` | `4858` | Port to listen on. |
-| `--root <dir>` | cwd | Root the file tools are confined to. |
-| `--allow-shell` | off | Enable the `shell_exec` tool (RCE on your machine — opt-in). |
-| `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box; keep the token secret. |
-| `--tls-cert <f>` `--tls-key <f>` | _(none)_ | Serve `wss://` (needed for a remote sidecar from an https page). |
-
-## Security
-
-- Loopback by default; a browser connection requires both the pairing token **and** an
-  allowed Origin.
-- The HTTP proxy (for local LLMs) only reaches **loopback** hosts — it can't be used as
-  an SSRF pivot to internal services.
-- `shell_exec` is off unless you pass `--allow-shell`.
-
-Licensed under Elastic-2.0.
+# @corenel/sidecar
+
+A small local capability server for [Prompd](https://prompd.app). Run it next to the
+web app and the browser can reach your machine — most usefully, your **local LLMs**
+(Ollama, LM Studio, vLLM) **without CORS**, plus your filesystem and (opt-in) shell.
+
+It runs only while the command is open, binds to loopback by default, and pairs with
+a token the app reads once.
+
+## Use
+
+In Prompd, open **Connect a sidecar** and follow the steps, or run it directly:
+
+```bash
+npx @corenel/sidecar --allow-origin https://prompd.app
+```
+
+It prints a pairing token; paste that into the app. The `--allow-origin` flag must
+match the site you're connecting from (the app fills it in for you).
+
+## Options
+
+| Flag | Default | What |
+|------|---------|------|
+| `--allow-origin <url>` | _(none)_ | Browser origin allowed to connect. Required for a web page. Repeatable. |
+| `--port <n>` | `4858` | Port to listen on. |
+| `--root <dir>` | cwd | Root the file tools are confined to. |
+| `--allow-shell` | off | Enable the `shell_exec` tool (RCE on your machine — opt-in). |
+| `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box; keep the token secret. |
+| `--tls-cert <f>` `--tls-key <f>` | _(none)_ | Serve `wss://` (needed for a remote sidecar from an https page). |
+
+## Security
+
+- Loopback by default; a browser connection requires both the pairing token **and** an
+  allowed Origin.
+- The HTTP proxy (for local LLMs) only reaches **loopback** hosts — it can't be used as
+  an SSRF pivot to internal services.
+- `shell_exec` is off unless you pass `--allow-shell`.
+
+Licensed under Elastic-2.0.

package/dist/cli.js

@@ -3,7 +3,8 @@ import { createRequire as __cr } from 'node:module'; const require = __cr(import
 
 // src/cli.ts
 import { resolve as resolve2 } from "node:path";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
+import { spawn as spawn4 } from "node:child_process";
 
 // src/server.ts
 import { WebSocketServer } from "ws";
@@ -278,6 +279,7 @@ function startSidecar(opts) {
     wss2.on("connection", onConnection);
     return new Promise((resolveHandle, reject) => {
       httpsServer.on("error", reject);
+      wss2.on("error", reject);
       httpsServer.listen(opts.port, host, () => {
         const addr = httpsServer.address();
         const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
@@ -317,42 +319,47 @@ function withinRoot(root, abs) {
   const rel = relative(root, abs);
   return rel === "" || !rel.startsWith("..") && !isAbsolute(rel) && rel.split(sep)[0] !== "..";
 }
-function confine(root, p) {
-  const abs = resolve(root, p);
-  if (!withinRoot(root, abs)) throw new Error(`path escapes the sidecar root: ${p}`);
+function activeRoot(roots, rootArg) {
+  const r = typeof rootArg === "string" ? rootArg : "";
+  return roots.includes(r) ? r : roots[0];
+}
+function confine(roots, rootArg, p) {
+  const abs = resolve(activeRoot(roots, rootArg), p);
+  if (!roots.some((root) => withinRoot(root, abs))) throw new Error(`path escapes the sidecar roots: ${p}`);
   return abs;
 }
-async function assertRealWithinRoot(root, abs) {
-  const realRoot = await fs.realpath(root);
+async function assertRealWithinRoot(roots, abs) {
+  const realRoots = await Promise.all(roots.map((r) => fs.realpath(r)));
   let probe = abs;
   for (; ; ) {
     try {
       const real = await fs.realpath(probe);
-      if (!withinRoot(realRoot, real)) throw new Error(`path escapes the sidecar root via symlink: ${abs}`);
+      if (!realRoots.some((rr) => withinRoot(rr, real))) throw new Error(`path escapes the sidecar roots via symlink: ${abs}`);
       return;
     } catch (e) {
       if (e instanceof Error && e.message.includes("via symlink")) throw e;
       const parent = dirname(probe);
-      if (parent === probe) throw new Error(`cannot resolve path under the sidecar root: ${abs}`);
+      if (parent === probe) throw new Error(`cannot resolve path under the sidecar roots: ${abs}`);
       probe = parent;
     }
   }
 }
+var ROOT_PARAM = { type: "string", description: "which pre-approved root to resolve the path against (its absolute path; defaults to the primary root)" };
 var MAX_READ_BYTES = 16 * 1024 * 1024;
-function nodeFsTools(root) {
+function nodeFsTools(roots) {
   return [
     {
       name: "fs_read_file",
-      description: "Read a UTF-8 text file from the sidecar machine, relative to its root.",
+      description: "Read a UTF-8 text file from the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
-        properties: { path: { type: "string", description: "path relative to the sidecar root" } },
+        properties: { path: { type: "string", description: "path relative to the chosen root" }, root: ROOT_PARAM },
         required: ["path"]
       },
       namespace: "fs",
       async run(args) {
-        const abs = confine(root, String(args.path ?? ""));
-        await assertRealWithinRoot(root, abs);
+        const abs = confine(roots, args.root, String(args.path ?? ""));
+        await assertRealWithinRoot(roots, abs);
         const st = await fs.stat(abs);
         if (st.size > MAX_READ_BYTES) {
           throw new Error(`file too large to read (${st.size} bytes; max ${MAX_READ_BYTES})`);
@@ -362,36 +369,56 @@ function nodeFsTools(root) {
     },
     {
       name: "fs_write_file",
-      description: "Write a UTF-8 text file on the sidecar machine, relative to its root.",
+      description: "Write a UTF-8 text file on the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
         properties: {
-          path: { type: "string", description: "path relative to the sidecar root" },
-          content: { type: "string" }
+          path: { type: "string", description: "path relative to the chosen root" },
+          content: { type: "string" },
+          root: ROOT_PARAM
         },
         required: ["path", "content"]
       },
       namespace: "fs",
       mutates: true,
       async run(args) {
-        const abs = confine(root, String(args.path ?? ""));
+        const abs = confine(roots, args.root, String(args.path ?? ""));
         await fs.mkdir(dirname(abs), { recursive: true });
-        await assertRealWithinRoot(root, abs);
+        await assertRealWithinRoot(roots, abs);
         await fs.writeFile(abs, String(args.content ?? ""), "utf8");
         return `wrote ${args.path}`;
       }
     },
+    {
+      name: "fs_read_bytes",
+      description: "Read a file from the sidecar machine as base64 (for previewing media/binary the text read would mangle), relative to a pre-approved root.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string", description: "path relative to the chosen root" }, root: ROOT_PARAM },
+        required: ["path"]
+      },
+      namespace: "fs",
+      async run(args) {
+        const abs = confine(roots, args.root, String(args.path ?? ""));
+        await assertRealWithinRoot(roots, abs);
+        const st = await fs.stat(abs);
+        if (st.size > MAX_READ_BYTES) {
+          throw new Error(`file too large to read (${st.size} bytes; max ${MAX_READ_BYTES})`);
+        }
+        return (await fs.readFile(abs)).toString("base64");
+      }
+    },
     {
       name: "fs_list_dir",
-      description: "List the entries of a directory on the sidecar machine, relative to its root.",
+      description: "List the entries of a directory on the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
-        properties: { path: { type: "string", description: 'directory relative to the sidecar root (default ".")' } }
+        properties: { path: { type: "string", description: 'directory relative to the chosen root (default ".")' }, root: ROOT_PARAM }
       },
       namespace: "fs",
       async run(args) {
-        const abs = confine(root, String(args.path ?? "."));
-        await assertRealWithinRoot(root, abs);
+        const abs = confine(roots, args.root, String(args.path ?? "."));
+        await assertRealWithinRoot(roots, abs);
         const entries = await fs.readdir(abs, { withFileTypes: true });
         return entries.map((e) => e.isDirectory() ? `${e.name}/` : e.name).join("\n");
       }
@@ -401,15 +428,16 @@ function nodeFsTools(root) {
 var DEFAULT_TIMEOUT_MS = 6e4;
 var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT = 1e5;
-function nodeShellTool(root) {
+function nodeShellTool(roots) {
   return {
     name: "shell_exec",
-    description: "Run a shell command on the sidecar machine (commands a browser cannot spawn). Runs in the sidecar root by default; returns the exit status plus combined stdout/stderr.",
+    description: "Run a shell command on the sidecar machine (commands a browser cannot spawn). Runs in a pre-approved root by default; returns the exit status plus combined stdout/stderr.",
     parameters: {
       type: "object",
       properties: {
         command: { type: "string", description: "the shell command line to run" },
-        cwd: { type: "string", description: 'working directory relative to the sidecar root (default ".")' },
+        cwd: { type: "string", description: 'working directory relative to the chosen root (default ".")' },
+        root: ROOT_PARAM,
         timeout_ms: { type: "number", description: `max run time in ms (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})` }
       },
       required: ["command"]
@@ -420,8 +448,8 @@ function nodeShellTool(root) {
     async run(args) {
       const command = String(args.command ?? "").trim();
       if (!command) return "Error: no command given";
-      const cwd = confine(root, String(args.cwd ?? "."));
-      await assertRealWithinRoot(root, cwd);
+      const cwd = confine(roots, args.root, String(args.cwd ?? "."));
+      await assertRealWithinRoot(roots, cwd);
       const timeout = Math.min(Math.max(Number(args.timeout_ms) || DEFAULT_TIMEOUT_MS, 1), MAX_TIMEOUT_MS);
       return runShell(command, cwd, timeout);
     }
@@ -675,7 +703,7 @@ function extractTunnelUrl(s) {
 }
 var START_TIMEOUT_MS2 = 25e3;
 function tunnelArgs(port, host = "localhost") {
-  return ["tunnel", "--no-autoupdate", "--url", `http://${host}:${port}`];
+  return ["tunnel", "--no-autoupdate", "--protocol", "http2", "--url", `http://${host}:${port}`];
 }
 var tail2 = (s, n = 6) => s.trim().split("\n").slice(-n).join("\n");
 function cloudflaredBins() {
@@ -780,12 +808,12 @@ registerTunnel(zrokProvider);
 
 // src/cli.ts
 function parseArgs(argv) {
-  const out = { port: 4858, host: "127.0.0.1", root: process.cwd(), allowOrigins: [], allowShell: false, allowLan: false, selfSigned: false };
+  const out = { port: 4858, host: "127.0.0.1", roots: [], allowOrigins: [], allowShell: false, allowLan: false, selfSigned: false, open: false, appUrl: "https://prompd.app" };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--port") out.port = Number(argv[++i]);
     else if (a === "--host") out.host = argv[++i];
-    else if (a === "--root") out.root = resolve2(argv[++i]);
+    else if (a === "--root") out.roots.push(resolve2(argv[++i]));
     else if (a === "--allow-origin") out.allowOrigins.push(argv[++i]);
     else if (a === "--allow-shell") out.allowShell = true;
     else if (a === "--allow-lan") out.allowLan = true;
@@ -794,13 +822,53 @@ function parseArgs(argv) {
     else if (a === "--self-signed") out.selfSigned = true;
     else if (a === "--tunnel") out.tunnel = argv[++i];
     else if (a === "--tunnel-name") out.tunnelName = argv[++i];
+    else if (a === "--open") out.open = true;
+    else if (a === "--app-url") out.appUrl = argv[++i];
+    else if (a === "--sidecar" || a === "start") {
+    } else throw new Error(`unknown argument: ${a}
+valid flags: ${KNOWN_FLAGS.join(" ")}`);
   }
   return out;
 }
+var KNOWN_FLAGS = [
+  "--port",
+  "--host",
+  "--root",
+  "--allow-origin",
+  "--allow-shell",
+  "--allow-lan",
+  "--tls-cert",
+  "--tls-key",
+  "--self-signed",
+  "--tunnel",
+  "--tunnel-name",
+  "--open",
+  "--app-url"
+];
 var isIp2 = (s) => /^\d{1,3}(?:\.\d{1,3}){3}$/.test(s);
+function openBrowser(url) {
+  const p = process.platform;
+  const cmd = p === "darwin" ? "open" : p === "win32" ? "cmd" : "xdg-open";
+  const args = p === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn4(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
 var DEFAULT_ALLOWED_ORIGINS = ["https://prompd.app", "https://www.prompd.app", "https://prmd.ai", "https://www.prmd.ai"];
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.roots.length === 0) args.roots = [process.cwd()];
+  args.roots = [...new Set(args.roots)];
+  for (const r of args.roots) {
+    let ok = false;
+    try {
+      ok = statSync(r).isDirectory();
+    } catch {
+      ok = false;
+    }
+    if (!ok) throw new Error(`--root is not a directory: ${r}`);
+  }
   const token = await loadOrCreateToken();
   if (args.tlsCert && !args.tlsKey || !args.tlsCert && args.tlsKey) {
     throw new Error("TLS needs both --tls-cert and --tls-key");
@@ -831,12 +899,12 @@ async function main() {
     port: args.port,
     host: args.host,
     token,
-    tools: [...nodeFsTools(args.root), ...args.allowShell ? [nodeShellTool(args.root)] : []],
+    tools: [...nodeFsTools(args.roots), ...args.allowShell ? [nodeShellTool(args.roots)] : []],
     allowedOrigins,
     tls,
-    // Advertised in the handshake so the host can show the working directory when
-    // browsing this sidecar as a file source.
-    info: { root: args.root, platform: process.platform },
+    // Advertised in the handshake so the host can show the available working
+    // directories and let the user pick one (confined to the union of roots).
+    info: { root: args.roots[0], roots: args.roots, platform: process.platform },
     log: slog,
     allowLan: args.allowLan
   });
@@ -855,7 +923,7 @@ async function main() {
   process.stdout.write(
     [
       `corenel sidecar listening on ${scheme}://${handle.host}:${handle.port}`,
-      `  root:  ${args.root}`,
+      args.roots.length === 1 ? `  root:  ${args.roots[0]}` : `  roots: ${args.roots.join("\n         ")}   (${args.roots.length} approved; pick the active one in the app)`,
       `  tools: fs_read/write/list${args.allowShell ? " + shell_exec" : "  (shell off; pass --allow-shell to enable)"}`,
       `  token: ${token}  (also at ${tokenPath()})`,
       tunnelWss ? `  connect at: ${tunnelWss}   (public ${args.tunnel} tunnel${args.tunnelName ? ", stable" : ""} \u2014 pair from any device with this URL + the token)` : `  connect at: ${connectUrls.join("  ")}`,
@@ -866,6 +934,13 @@ async function main() {
       ""
     ].filter((l) => l !== null).join("\n")
   );
+  if (args.open) {
+    const loopback = `${handle.secure ? "wss" : "ws"}://127.0.0.1:${handle.port}`;
+    const target = `${args.appUrl.replace(/\/$/, "")}/studio#sidecar=${encodeURIComponent(loopback)}&token=${encodeURIComponent(token)}`;
+    process.stdout.write(`  opening ${args.appUrl} (auto-pairing)\u2026
+`);
+    openBrowser(target);
+  }
   const shutdown = () => {
     const closeServer = () => handle.close().then(() => process.exit(0));
     if (tunnel) void tunnel.stop().catch(() => {
@@ -876,7 +951,9 @@ async function main() {
   process.on("SIGTERM", shutdown);
 }
 main().catch((e) => {
-  process.stderr.write(`corenel-sidecar: ${e instanceof Error ? e.message : String(e)}
+  const code = e?.code;
+  const msg = code === "EADDRINUSE" ? `port already in use \u2014 another sidecar may be running. Stop it, or pass --port <n>.` : e instanceof Error ? e.message : String(e);
+  process.stderr.write(`corenel-sidecar: ${msg}
 `);
   process.exit(1);
 });

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "@corenel/sidecar",
-  "version": "0.1.1",
-  "type": "module",
-  "license": "Elastic-2.0",
-  "description": "Prompd sidecar — a local capability server. Run it next to Prompd (prompd.app) so the browser app can reach your machine: local LLMs (Ollama/LM Studio/vLLM) without CORS, your filesystem, and (opt-in) shell.",
-  "keywords": ["prompd", "corenel", "sidecar", "ollama", "local-llm", "cors"],
-  "bin": {
-    "corenel-sidecar": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "node build.mjs",
-    "prepublishOnly": "node build.mjs",
-    "start": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit",
-    "verify": "tsx src/verify.ts"
-  },
-  "dependencies": {
-    "selfsigned": "^2.4.1",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "@corenel/protocol": "workspace:*",
-    "@corenel/harness": "workspace:*",
-    "@types/node": "^24.13.1",
-    "@types/ws": "^8.5.13",
-    "esbuild": "^0.21.5",
-    "tsx": "^4.19.2",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@corenel/sidecar",
+  "version": "0.1.3",
+  "type": "module",
+  "license": "Elastic-2.0",
+  "description": "Prompd sidecar — a local capability server. Run it next to Prompd (prompd.app) so the browser app can reach your machine: local LLMs (Ollama/LM Studio/vLLM) without CORS, your filesystem, and (opt-in) shell.",
+  "keywords": ["prompd", "corenel", "sidecar", "ollama", "local-llm", "cors"],
+  "bin": {
+    "corenel-sidecar": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "node build.mjs",
+    "start": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "tsx src/verify.ts"
+  },
+  "dependencies": {
+    "selfsigned": "^2.4.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@corenel/protocol": "workspace:*",
+    "@corenel/harness": "workspace:*",
+    "@types/node": "^24.13.1",
+    "@types/ws": "^8.5.13",
+    "esbuild": "^0.21.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  }
+}