@openthink/ui-leaf 0.3.0

package/dist/cli.js

@@ -0,0 +1,672 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { createInterface } from "readline";
+
+// src/index.ts
+import { resolve as resolve2 } from "path";
+
+// src/dev-server.ts
+import { randomBytes, timingSafeEqual as nodeTimingSafeEqual } from "crypto";
+import { rmSync } from "fs";
+import { mkdtemp, readdir, rm, stat, writeFile } from "fs/promises";
+import { createRequire } from "module";
+import { createServer as createTcpServer } from "net";
+import { tmpdir } from "os";
+import { dirname, join, resolve, sep } from "path";
+import { createRsbuild } from "@rsbuild/core";
+import { pluginReact } from "@rsbuild/plugin-react";
+import open, { apps } from "open";
+var uiLeafRequire = createRequire(import.meta.url);
+var reactPath = dirname(uiLeafRequire.resolve("react/package.json"));
+var reactDomPath = dirname(uiLeafRequire.resolve("react-dom/package.json"));
+var ORIGINAL_STDOUT_WRITE = process.stdout.write.bind(process.stdout);
+var stdoutRedirectCount = 0;
+async function findFreePort() {
+  return new Promise((resolve3, reject) => {
+    const server = createTcpServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr !== "object") {
+        server.close();
+        reject(new Error("ui-leaf: failed to obtain a free port from the OS"));
+        return;
+      }
+      const port = addr.port;
+      server.close(() => resolve3(port));
+    });
+  });
+}
+var STALE_TEMPDIR_AGE_MS = 24 * 60 * 60 * 1e3;
+async function sweepStaleTempDirs() {
+  try {
+    const root = tmpdir();
+    const entries = await readdir(root, { withFileTypes: true });
+    const cutoff = Date.now() - STALE_TEMPDIR_AGE_MS;
+    await Promise.all(
+      entries.filter((e) => e.isDirectory() && e.name.startsWith("ui-leaf-")).map(async (e) => {
+        const path = join(root, e.name);
+        try {
+          const info = await stat(path);
+          if (info.mtimeMs < cutoff) {
+            await rm(path, { recursive: true, force: true });
+          }
+        } catch {
+        }
+      })
+    );
+  } catch {
+  }
+}
+function redirectStdoutToStderr() {
+  stdoutRedirectCount++;
+  if (stdoutRedirectCount === 1) {
+    process.stdout.write = ((chunk, enc, cb) => process.stderr.write(chunk, enc, cb));
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    stdoutRedirectCount--;
+    if (stdoutRedirectCount === 0) {
+      process.stdout.write = ORIGINAL_STDOUT_WRITE;
+    }
+  };
+}
+async function openInAppMode(url) {
+  const candidates = [apps.chrome, apps.edge, apps.brave];
+  for (const app of candidates) {
+    try {
+      await open(url, { app: { name: app, arguments: [`--app=${url}`] } });
+      return true;
+    } catch {
+    }
+  }
+  return false;
+}
+var STRICT_CSP = [
+  "default-src 'self'",
+  "connect-src 'self'",
+  "img-src 'self' data: https:",
+  "font-src 'self' https: data:",
+  "style-src 'self' 'unsafe-inline'",
+  "script-src 'self' 'unsafe-eval' 'unsafe-inline'"
+].join("; ");
+function resolveCsp(opt) {
+  if (!opt || opt === "off") return null;
+  if (opt === "strict") return STRICT_CSP;
+  return opt;
+}
+function escapeForScriptTag(json) {
+  return json.replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+async function readJsonBody(req) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of req) {
+    const buf = chunk;
+    total += buf.length;
+    if (total > 1024 * 1024) {
+      throw new Error("request body exceeds 1 MiB limit");
+    }
+    chunks.push(buf);
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  return text ? JSON.parse(text) : void 0;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  return nodeTimingSafeEqual(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+var DEFAULT_LOOPBACK_HOSTNAMES = ["127.0.0.1", "localhost", "::1"];
+function parseHostHeader(value) {
+  const trimmed = value.trim();
+  if (trimmed === "") return null;
+  if (trimmed.startsWith("[")) {
+    const close = trimmed.indexOf("]");
+    if (close === -1) return null;
+    return trimmed.slice(1, close).toLowerCase();
+  }
+  const colon = trimmed.indexOf(":");
+  return (colon === -1 ? trimmed : trimmed.slice(0, colon)).toLowerCase();
+}
+function isAllowedHost(value, allowed) {
+  const host = value === void 0 ? null : parseHostHeader(value);
+  return host !== null && allowed.has(host);
+}
+function isAllowedOrigin(value, allowed) {
+  if (value === void 0 || value === "" || value === "null") return true;
+  try {
+    let hostname = new URL(value).hostname.toLowerCase();
+    if (hostname.startsWith("[") && hostname.endsWith("]")) {
+      hostname = hostname.slice(1, -1);
+    }
+    return allowed.has(hostname);
+  } catch {
+    return false;
+  }
+}
+async function startDevServer(opts) {
+  const {
+    view,
+    data,
+    viewsRoot,
+    mutations = {},
+    title = "ui-leaf",
+    port,
+    openBrowser = true,
+    shell = "tab",
+    heartbeatTimeoutMs = 75e3,
+    startupGraceMs = 3e4,
+    csp,
+    allowedHosts,
+    silent = false
+  } = opts;
+  const cspHeader = resolveCsp(csp);
+  const allowedHostSet = new Set(DEFAULT_LOOPBACK_HOSTNAMES);
+  for (const h of allowedHosts ?? []) allowedHostSet.add(h.toLowerCase());
+  const allowedHostList = [...allowedHostSet].join(", ");
+  const resolvedPort = port === 0 ? await findFreePort() : port ?? 5810;
+  const restoreStdout = silent ? redirectStdoutToStderr() : null;
+  let tempDir = null;
+  let cleanupOnExit = null;
+  try {
+    let checkAuth2 = function(req) {
+      const header = req.headers.authorization ?? "";
+      const match = /^Bearer (.+)$/.exec(header);
+      if (!match) return false;
+      return timingSafeEqual(match[1], token);
+    }, sendJson2 = function(res, status, body) {
+      res.writeHead(status, { "Content-Type": "application/json" });
+      res.end(body === void 0 ? "" : JSON.stringify(body));
+    };
+    var checkAuth = checkAuth2, sendJson = sendJson2;
+    if (view.includes("/") || view.includes("\\")) {
+      throw new Error(
+        `ui-leaf: view '${view}' must be a bare identifier with no path separators`
+      );
+    }
+    const viewsRootAbs = resolve(viewsRoot);
+    const viewAbs = resolve(viewsRootAbs, `${view}.tsx`);
+    if (!viewAbs.startsWith(viewsRootAbs + sep)) {
+      throw new Error(
+        `ui-leaf: view '${view}' resolves outside viewsRoot`
+      );
+    }
+    try {
+      await stat(viewAbs);
+    } catch {
+      throw new Error(
+        `ui-leaf: view '${view}' not found at ${viewAbs} (looked for .tsx; viewsRoot=${viewsRoot})`
+      );
+    }
+    const token = randomBytes(32).toString("hex");
+    tempDir = await mkdtemp(join(tmpdir(), "ui-leaf-"));
+    const dirToSweep = tempDir;
+    cleanupOnExit = () => {
+      try {
+        rmSync(dirToSweep, { recursive: true, force: true });
+      } catch {
+      }
+    };
+    process.on("exit", cleanupOnExit);
+    void sweepStaleTempDirs();
+    const entryPath = join(dirToSweep, "entry.tsx");
+    await writeFile(
+      entryPath,
+      `import { createRoot } from "react-dom/client";
+import View from ${JSON.stringify(viewAbs)};
+
+const ctx = (globalThis).__UI_LEAF__ || {};
+const data = ctx.data;
+const token = ctx.token;
+
+async function mutate(name, args) {
+  const res = await fetch("/mutate", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(token ? { Authorization: "Bearer " + token } : {}),
+    },
+    body: JSON.stringify({ name, args }),
+  });
+  const text = await res.text().catch(function () { return ""; });
+  if (!res.ok) {
+    var detail = text;
+    try {
+      var parsed = text ? JSON.parse(text) : null;
+      if (parsed && typeof parsed === "object" && typeof parsed.error === "string") {
+        detail = parsed.error;
+      }
+    } catch (_) { /* keep raw text */ }
+    throw new Error("ui-leaf: mutation '" + name + "' failed (" + res.status + "): " + detail);
+  }
+  return text ? JSON.parse(text) : undefined;
+}
+
+async function heartbeat() {
+  try {
+    await fetch("/heartbeat", {
+      method: "POST",
+      headers: token ? { Authorization: "Bearer " + token } : {},
+    });
+  } catch {
+    /* server may have shut down; ignore */
+  }
+}
+setInterval(heartbeat, 5000);
+heartbeat();
+
+const el = document.getElementById("root");
+if (!el) throw new Error("ui-leaf: #root element missing");
+createRoot(el).render(<View data={data} mutate={mutate} />);
+`
+    );
+    const dataInline = escapeForScriptTag(JSON.stringify(data));
+    const tokenInline = JSON.stringify(token);
+    const titleEscaped = title.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const htmlPath = join(dirToSweep, "index.html");
+    await writeFile(
+      htmlPath,
+      `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${titleEscaped}</title>
+    <script>window.__UI_LEAF__ = { data: ${dataInline}, token: ${tokenInline} };</script>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>
+`
+    );
+    let lastHeartbeatAt = Date.now();
+    let closeRequested = false;
+    let resolveClosed = () => {
+    };
+    const closed = new Promise((r) => {
+      resolveClosed = r;
+    });
+    const rsbuild = await createRsbuild({
+      cwd: dirToSweep,
+      rsbuildConfig: {
+        plugins: [pluginReact()],
+        ...silent ? { logLevel: "silent" } : {},
+        source: { entry: { index: entryPath } },
+        // 5810 is unused by the major Node dev tools (vite=5173, parcel=1234,
+        // webpack=8080, next/CRA=3000). rsbuild auto-bumps to the next free
+        // port if 5810 is busy, so collisions are graceful.
+        server: { port: resolvedPort, host: "127.0.0.1" },
+        // Note: `dev.setupMiddlewares` is deprecated as of rsbuild 2.x in
+        // favor of `server.setup`, but the new API has a different signature
+        // and bypasses the rsbuild CSRF middleware in ways that break our
+        // POST endpoints. Sticking with the deprecated path for v1.
+        dev: {
+          setupMiddlewares: [
+            (middlewares) => {
+              middlewares.unshift(async (req, res, next) => {
+                const hostOk = isAllowedHost(req.headers.host, allowedHostSet);
+                const originOk = isAllowedOrigin(req.headers.origin, allowedHostSet);
+                if (!hostOk || !originOk) {
+                  const offender = !hostOk ? `Host "${req.headers.host ?? "(absent)"}"` : `Origin "${req.headers.origin}"`;
+                  res.statusCode = 403;
+                  res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                  res.end(
+                    `ui-leaf: refusing request with ${offender} \u2014 only the following hostnames are accepted to prevent DNS rebinding: ${allowedHostList}. Open the dev server at http://localhost:${resolvedPort}/ or http://127.0.0.1:${resolvedPort}/, or pass { allowedHosts: ["my-alias"] } to mount() to permit a custom alias.
+`
+                  );
+                  return;
+                }
+                const url2 = req.url ?? "";
+                if (req.method === "POST" && url2 === "/heartbeat") {
+                  if (!checkAuth2(req)) {
+                    sendJson2(res, 401, { error: "unauthorized" });
+                    return;
+                  }
+                  lastHeartbeatAt = Date.now();
+                  sendJson2(res, 204, void 0);
+                  return;
+                }
+                if (req.method === "POST" && url2 === "/mutate") {
+                  if (!checkAuth2(req)) {
+                    sendJson2(res, 401, { error: "unauthorized" });
+                    return;
+                  }
+                  let body;
+                  try {
+                    body = await readJsonBody(req);
+                  } catch (err) {
+                    sendJson2(res, 400, {
+                      error: err instanceof Error ? err.message : "bad request"
+                    });
+                    return;
+                  }
+                  const name = body?.name;
+                  if (typeof name !== "string" || name.length === 0) {
+                    sendJson2(res, 400, { error: "missing mutation name" });
+                    return;
+                  }
+                  if (!Object.hasOwn(mutations, name)) {
+                    sendJson2(res, 404, {
+                      error: `ui-leaf: no mutation handler registered for '${name}'. Add it to the mutations: { } map passed to mount().`
+                    });
+                    return;
+                  }
+                  const handler = mutations[name];
+                  try {
+                    const result = await handler(body.args);
+                    sendJson2(res, 200, result ?? null);
+                  } catch (err) {
+                    sendJson2(res, 500, {
+                      error: err instanceof Error ? err.message : String(err)
+                    });
+                  }
+                  return;
+                }
+                next();
+              });
+              if (cspHeader) {
+                middlewares.unshift((_req, res, next) => {
+                  res.setHeader("Content-Security-Policy", cspHeader);
+                  next();
+                });
+              }
+            }
+          ]
+        },
+        html: { template: htmlPath },
+        tools: {
+          rspack: {
+            resolve: {
+              alias: {
+                react: reactPath,
+                "react-dom": reactDomPath
+              }
+            }
+          }
+        }
+      }
+    });
+    const devServer = await rsbuild.startDevServer();
+    const actualPort = devServer.port;
+    const url = `http://127.0.0.1:${actualPort}`;
+    const startedAt = Date.now();
+    let heartbeatWatcher;
+    const cleanup = async () => {
+      if (closeRequested) return;
+      closeRequested = true;
+      if (heartbeatWatcher) clearInterval(heartbeatWatcher);
+      await devServer.server.close();
+      await rm(dirToSweep, { recursive: true, force: true });
+      if (cleanupOnExit) process.off("exit", cleanupOnExit);
+      if (restoreStdout) restoreStdout();
+      resolveClosed();
+    };
+    heartbeatWatcher = setInterval(() => {
+      const now = Date.now();
+      if (now - startedAt < startupGraceMs) return;
+      if (now - lastHeartbeatAt > heartbeatTimeoutMs) {
+        void cleanup();
+      }
+    }, 1e3);
+    if (openBrowser) {
+      if (shell === "app") {
+        const launched = await openInAppMode(url);
+        if (!launched) {
+          process.stderr.write(
+            `ui-leaf: shell:"app" requested but no Chromium browser found; falling back to default browser tab.
+`
+          );
+          await open(url);
+        }
+      } else {
+        await open(url);
+      }
+    }
+    return {
+      url,
+      port: actualPort,
+      closed,
+      close: cleanup
+    };
+  } catch (err) {
+    if (tempDir) {
+      try {
+        rmSync(tempDir, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    if (cleanupOnExit) process.off("exit", cleanupOnExit);
+    restoreStdout?.();
+    throw err;
+  }
+}
+
+// src/index.ts
+async function mount(opts) {
+  const viewsRoot = opts.viewsRoot ?? resolve2(process.cwd(), "views");
+  const server = await startDevServer({
+    view: opts.view,
+    data: opts.data,
+    viewsRoot,
+    mutations: opts.mutations,
+    title: opts.title,
+    port: opts.port,
+    openBrowser: opts.openBrowser,
+    shell: opts.shell,
+    heartbeatTimeoutMs: opts.heartbeatTimeoutMs,
+    startupGraceMs: opts.startupGraceMs,
+    csp: opts.csp,
+    allowedHosts: opts.allowedHosts,
+    silent: opts.silent
+  });
+  const onSignal = (signal) => {
+    void (async () => {
+      await server.close();
+      process.kill(process.pid, signal);
+    })();
+  };
+  const sigint = () => onSignal("SIGINT");
+  const sigterm = () => onSignal("SIGTERM");
+  process.once("SIGINT", sigint);
+  process.once("SIGTERM", sigterm);
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      process.off("SIGINT", sigint);
+      process.off("SIGTERM", sigterm);
+      await server.close();
+      return {
+        url: server.url,
+        port: server.port,
+        closed: Promise.resolve(),
+        close: server.close
+      };
+    }
+    opts.signal.addEventListener(
+      "abort",
+      () => void server.close(),
+      { once: true }
+    );
+  }
+  const closed = server.closed.finally(() => {
+    process.off("SIGINT", sigint);
+    process.off("SIGTERM", sigterm);
+  });
+  return {
+    url: server.url,
+    port: server.port,
+    closed,
+    close: server.close
+  };
+}
+
+// src/cli.ts
+var realStdoutWrite = process.stdout.write.bind(process.stdout);
+var args = process.argv.slice(2);
+if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+  process.stdout.write(
+    [
+      "ui-leaf \u2014 Customizable browser views, on demand, for any CLI.",
+      "",
+      "Usage:",
+      "  ui-leaf mount         Read a JSON config from stdin and mount a view.",
+      "                        See https://github.com/OpenThinkAi/ui-leaf for",
+      "                        the full stdio protocol spec.",
+      "",
+      "  ui-leaf --version     Print version.",
+      "  ui-leaf --help        Print this message.",
+      ""
+    ].join("\n")
+  );
+  process.exit(0);
+}
+if (args[0] === "--version" || args[0] === "-v") {
+  const { createRequire: createRequire2 } = await import("module");
+  const require2 = createRequire2(import.meta.url);
+  const pkg = require2("../package.json");
+  process.stdout.write(`${pkg.version}
+`);
+  process.exit(0);
+}
+if (args[0] !== "mount") {
+  process.stderr.write(`ui-leaf: unknown command "${args[0]}"
+`);
+  process.exit(1);
+}
+if (args[1] === "--help" || args[1] === "-h" || process.stdin.isTTY) {
+  process.stdout.write(
+    [
+      "ui-leaf mount \u2014 read a JSON config from stdin and mount a view.",
+      "",
+      "Protocol: line-delimited JSON over stdio.",
+      "  stdin  line 1 = config object",
+      "         lines 2+ = mutation responses {type:result|error,id,...}",
+      "  stdout {type:ready,url,port}, {type:mutate,id,name,args},",
+      "         {type:closed}, {type:error,message}",
+      "",
+      "Full spec: https://github.com/OpenThinkAi/ui-leaf#driving-ui-leaf-from-a-non-node-cli",
+      "",
+      "Example:",
+      `  echo '{"view":"spec","viewsRoot":"/abs/path","data":{}}' | ui-leaf mount`,
+      ""
+    ].join("\n")
+  );
+  process.exit(0);
+}
+try {
+  await runMount();
+} catch (err) {
+  emit({
+    type: "error",
+    message: err instanceof Error ? err.message : String(err)
+  });
+  process.exit(1);
+}
+function emit(event) {
+  realStdoutWrite(`${JSON.stringify(event)}
+`);
+}
+async function runMount() {
+  const rl = createInterface({ input: process.stdin });
+  let nextId = 0;
+  const pending = /* @__PURE__ */ new Map();
+  let configReceived = false;
+  let configResolve;
+  let configReject;
+  const configPromise = new Promise((res, rej) => {
+    configResolve = res;
+    configReject = rej;
+  });
+  let mountedView = null;
+  let stdinClosed = false;
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    if (!configReceived) {
+      configReceived = true;
+      try {
+        const config2 = JSON.parse(trimmed);
+        configResolve(config2);
+      } catch (err) {
+        emit({
+          type: "error",
+          message: `failed to parse config JSON: ${err instanceof Error ? err.message : String(err)}`
+        });
+        process.exit(1);
+      }
+      return;
+    }
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+    const p = pending.get(msg.id);
+    if (!p) return;
+    pending.delete(msg.id);
+    if (msg.type === "result") p.resolve(msg.value);
+    else if (msg.type === "error") p.reject(new Error(msg.message));
+  });
+  rl.on("close", () => {
+    stdinClosed = true;
+    for (const { reject } of pending.values()) {
+      reject(new Error("ui-leaf: stdin closed by parent before mutation responded"));
+    }
+    pending.clear();
+    if (!configReceived) {
+      configReject(new Error("ui-leaf: stdin closed before config received"));
+      return;
+    }
+    if (mountedView) {
+      void mountedView.close();
+    }
+  });
+  const config = await configPromise;
+  const mutations = {};
+  for (const name of config.mutations ?? []) {
+    mutations[name] = (mutationArgs) => {
+      const id = ++nextId;
+      return new Promise((resolve3, reject) => {
+        pending.set(id, { resolve: resolve3, reject });
+        emit({ type: "mutate", id, name, args: mutationArgs });
+      });
+    };
+  }
+  const mountOpts = {
+    view: config.view,
+    viewsRoot: config.viewsRoot,
+    data: config.data,
+    mutations,
+    title: config.title,
+    port: config.port,
+    openBrowser: config.openBrowser,
+    shell: config.shell,
+    csp: config.csp,
+    heartbeatTimeoutMs: config.heartbeatTimeoutMs,
+    startupGraceMs: config.startupGraceMs,
+    silent: true
+    // bridge owns stdout; rsbuild output must stay silent
+  };
+  try {
+    const view = await mount(mountOpts);
+    mountedView = view;
+    if (stdinClosed) {
+      void view.close();
+    }
+    emit({ type: "ready", url: view.url, port: view.port });
+    await view.closed;
+    emit({ type: "closed" });
+    process.exit(0);
+  } catch (err) {
+    emit({
+      type: "error",
+      message: err instanceof Error ? err.message : String(err)
+    });
+    process.exit(1);
+  }
+}
+//# sourceMappingURL=cli.js.map