webtty 1.1.1 → 1.3.0

package/README.md

@@ -1,6 +1,14 @@
+<img src="assets/social-preview.png" width="600">
+
 # webtty
 
-A web TTY for running CLI/TUI applications in a browser tab, across platforms.
+Terminal UI in the browser. Run CLI/TUI applications in a browser tab, across platforms.
+
+```sh
+npx webtty           # start server + open a terminal in the browser
+npx webtty ls        # list sessions
+npx webtty help      # show all commands
+```
 
 ## Debugging
 

package/dist/cli/index.js

@@ -2156,38 +2156,161 @@ var {
   Help
 } = import__.default;
 
-// src/cli/http.ts
-import { spawn } from "node:child_process";
+// src/cli/commands.ts
+import * as childProcess2 from "node:child_process";
+import fs3 from "node:fs";
+import path3 from "node:path";
+
+// src/config.ts
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+function configDir() {
+  return path.join(process.env.HOME ?? os.homedir(), ".config", "webtty");
+}
+function getConfigPath() {
+  return path.join(configDir(), "config.json");
+}
+var DEFAULT_THEME = {
+  background: "#000000",
+  foreground: "#CCCCCC",
+  cursor: "#FFFFFF",
+  selection: "#FFFFFF",
+  black: "#0C0C0C",
+  red: "#C50F1F",
+  green: "#13A10E",
+  yellow: "#C19C00",
+  blue: "#0037DA",
+  purple: "#881798",
+  cyan: "#3A96DD",
+  white: "#CCCCCC",
+  brightBlack: "#767676",
+  brightRed: "#E74856",
+  brightGreen: "#16C60C",
+  brightYellow: "#F9F1A5",
+  brightBlue: "#3B78FF",
+  brightPurple: "#B4009E",
+  brightCyan: "#61D6D6",
+  brightWhite: "#F2F2F2"
+};
+var DEFAULT_CONFIG = {
+  port: 2346,
+  host: "127.0.0.1",
+  shell: process.platform === "win32" ? process.env.COMSPEC ?? "cmd.exe" : process.env.SHELL ?? "/bin/bash",
+  term: process.env.TERM ?? "xterm-256color",
+  colorTerm: "truecolor",
+  scrollback: 256 * 1024,
+  cols: 80,
+  rows: 24,
+  fontSize: 13,
+  fontFamily: "Menlo, Consolas, 'DejaVu Sans Mono', monospace",
+  cursorBlink: true,
+  copyOnSelect: true,
+  rightClickBehavior: "default",
+  logs: false,
+  theme: DEFAULT_THEME
+};
+function loadConfig() {
+  if (!fs.existsSync(getConfigPath())) {
+    try {
+      saveConfig(DEFAULT_CONFIG);
+    } catch (err) {
+      console.warn(`webtty: failed to write default config to ${getConfigPath()}: ${err.message}`);
+      return { ...DEFAULT_CONFIG };
+    }
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(getConfigPath(), "utf8");
+  } catch (err) {
+    throw new Error(`webtty: failed to read config at ${getConfigPath()}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`webtty: invalid JSON in config file ${getConfigPath()}`);
+  }
+  const p = parsed;
+  return {
+    ...DEFAULT_CONFIG,
+    ...typeof p.port === "number" && { port: p.port },
+    ...typeof p.host === "string" && { host: p.host },
+    ...typeof p.shell === "string" && { shell: p.shell },
+    ...typeof p.term === "string" && { term: p.term },
+    ...typeof p.colorTerm === "string" && { colorTerm: p.colorTerm },
+    ...typeof p.scrollback === "number" && { scrollback: p.scrollback },
+    ...typeof p.cols === "number" && { cols: p.cols },
+    ...typeof p.rows === "number" && { rows: p.rows },
+    ...typeof p.fontSize === "number" && { fontSize: p.fontSize },
+    ...typeof p.fontFamily === "string" && { fontFamily: p.fontFamily },
+    ...typeof p.cursorBlink === "boolean" && { cursorBlink: p.cursorBlink },
+    ...typeof p.copyOnSelect === "boolean" && { copyOnSelect: p.copyOnSelect },
+    ...typeof p.rightClickBehavior === "string" && {
+      rightClickBehavior: p.rightClickBehavior === "copyPaste" ? "copyPaste" : "default"
+    },
+    ...typeof p.logs === "boolean" && { logs: p.logs },
+    ...p.theme && typeof p.theme === "object" && { theme: { ...DEFAULT_THEME, ...p.theme } }
+  };
+}
+function saveConfig(_config) {
+  fs.mkdirSync(path.dirname(getConfigPath()), { recursive: true });
+  const content = JSON.stringify({
+    port: DEFAULT_CONFIG.port,
+    host: DEFAULT_CONFIG.host
+  }, null, 2);
+  fs.writeFileSync(getConfigPath(), content, "utf8");
+}
+
+// src/cli/http.ts
+import * as childProcess from "node:child_process";
+import fs2 from "node:fs";
+import path2 from "node:path";
 import { fileURLToPath } from "node:url";
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path.dirname(__filename2);
+var __dirname2 = path2.dirname(__filename2);
 var PORT = Number(process.env.PORT) || 2346;
 var BASE_URL = `http://127.0.0.1:${PORT}`;
+function logPath() {
+  return path2.join(configDir(), "server.log");
+}
 async function isServerRunning() {
   try {
-    await fetch(`${BASE_URL}/api/sessions`);
-    return true;
+    const res = await fetch(`${BASE_URL}/api/sessions`);
+    if (!res.ok)
+      return false;
+    const body = await res.json();
+    return Array.isArray(body);
   } catch {
     return false;
   }
 }
-async function startServer() {
+async function startServer(timeoutMs = 1e4, _spawn = childProcess.spawn) {
   const isBun = typeof globalThis.Bun !== "undefined";
   const isTs = isBun && __filename2.endsWith(".ts");
-  const serverEntry = path.resolve(__dirname2, isTs ? "../server/index.ts" : "../server/index.js");
-  if (!fs.existsSync(serverEntry)) {
+  const serverEntry = path2.resolve(__dirname2, isTs ? "../server/index.ts" : "../server/index.js");
+  if (!fs2.existsSync(serverEntry)) {
     console.error(`webtty: server entry not found at ${serverEntry}`);
     process.exit(1);
   }
-  const child = spawn(process.execPath, [serverEntry], {
+  const config = loadConfig();
+  let stdio = "ignore";
+  let logFd;
+  if (config.logs) {
+    const log = logPath();
+    fs2.mkdirSync(path2.dirname(log), { recursive: true });
+    logFd = fs2.openSync(log, "a");
+    stdio = ["ignore", logFd, logFd];
+  }
+  const child = _spawn(process.execPath, [serverEntry], {
     detached: true,
-    stdio: "ignore",
+    stdio,
     env: { ...process.env, PORT: String(PORT) }
   });
   child.unref();
-  const deadline = Date.now() + 1e4;
+  if (logFd !== undefined)
+    fs2.closeSync(logFd);
+  const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await isServerRunning())
       return;
@@ -2196,60 +2319,38 @@ async function startServer() {
   console.error("webtty: server did not start in time");
   process.exit(1);
 }
-function openBrowser(url) {
+async function stopServer(baseUrl = BASE_URL, timeoutMs = 5000) {
+  try {
+    const res = await fetch(`${baseUrl}/api/server/stop`, { method: "POST" });
+    if (!res.ok)
+      return false;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (!await isServerRunning())
+        return true;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function openBrowser(url, _spawn = childProcess.spawn) {
   if (process.env.WEBTTY_NO_OPEN === "1")
     return;
+  if (false)
+    ;
   if (process.platform === "win32") {
-    spawn("cmd.exe", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+    _spawn("cmd.exe", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
   } else {
     const cmd = process.platform === "darwin" ? "open" : "xdg-open";
-    spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+    _spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
   }
 }
 
 // src/cli/commands.ts
 function registerCommands(program2) {
-  program2.command("start").description("Start the webtty server").action(async () => {
-    if (await isServerRunning()) {
-      console.log("webtty is already running");
-      return;
-    }
-    await startServer();
-    console.log("webtty started");
-  });
-  program2.command("stop").description("Stop the webtty server").action(async () => {
-    try {
-      const res = await fetch(`${BASE_URL}/api/server/stop`, { method: "POST" });
-      if (res.ok) {
-        console.log("webtty stopped");
-      } else {
-        console.error(`webtty stop failed (status: ${res.status})`);
-        process.exit(1);
-      }
-    } catch {
-      console.log("webtty is not running");
-    }
-  });
-  program2.command("ls").description("List all sessions").action(async () => {
-    let res;
-    try {
-      res = await fetch(`${BASE_URL}/api/sessions`);
-    } catch {
-      console.log("webtty is not running");
-      process.exit(1);
-    }
-    const sessions = await res.json();
-    if (sessions.length === 0) {
-      console.log("no sessions");
-      return;
-    }
-    console.log("id\t\t\tconnected\tcreated");
-    for (const s of sessions) {
-      const created = new Date(s.createdAt).toLocaleString();
-      console.log(`${s.id}			${s.connected}		${created}`);
-    }
-  });
-  program2.command("run [id]").description("Create or reuse a session and open it in the browser").action(async (id) => {
+  program2.command("at [id]").alias("a").alias("attach").description("Attach to a new or existing session and open it").action(async (id) => {
     if (!await isServerRunning()) {
       await startServer();
     }
@@ -2290,7 +2391,31 @@ function registerCommands(program2) {
     console.log(url);
     openBrowser(url);
   });
-  program2.command("rm <id>").description("Kill a session and its PTY").action(async (id) => {
+  program2.command("ls [id]").alias("list").description("List all sessions, or filter by id substring").action(async (filter) => {
+    let res;
+    try {
+      res = await fetch(`${BASE_URL}/api/sessions`);
+    } catch {
+      console.log("webtty is not running");
+      process.exit(1);
+    }
+    const all = await res.json();
+    const sessions = filter ? all.filter((s) => s.id.includes(filter)) : all;
+    if (sessions.length === 0) {
+      console.log("no sessions");
+      return;
+    }
+    console.log("id\t\t\tconnected\tcreated");
+    for (const s of sessions) {
+      const created = new Date(s.createdAt).toLocaleString();
+      console.log(`${s.id}			${s.connected}		${created}`);
+    }
+  });
+  program2.command("rm [id]").alias("remove").description("Destroy a session").action(async (id) => {
+    if (!id) {
+      console.error("webtty: rm requires a session id");
+      process.exit(1);
+    }
     let res;
     try {
       res = await fetch(`${BASE_URL}/api/sessions/${encodeURIComponent(id)}`, {
@@ -2302,6 +2427,10 @@ function registerCommands(program2) {
     }
     if (res.status === 204) {
       console.log(`removed ${id}`);
+      if (res.headers.get("x-sessions-remaining") === "0") {
+        await stopServer();
+        console.log("no sessions remaining — webtty stopped");
+      }
     } else if (res.status === 404) {
       console.error(`session ${id} not found`);
       process.exit(1);
@@ -2310,7 +2439,11 @@ function registerCommands(program2) {
       process.exit(1);
     }
   });
-  program2.command("rename <id> <new-id>").description("Rename a session").action(async (id, newId) => {
+  program2.command("mv [id] [new-id]").alias("move").alias("rename").description("Rename a session").action(async (id, newId) => {
+    if (!id || !newId) {
+      console.error("webtty: rename requires two arguments: [id] [new-id]");
+      process.exit(1);
+    }
     let res;
     try {
       res = await fetch(`${BASE_URL}/api/sessions/${encodeURIComponent(id)}`, {
@@ -2333,12 +2466,84 @@ function registerCommands(program2) {
       process.exit(1);
     }
   });
+  program2.command("stop").description("Stop the webtty server").action(async () => {
+    if (!await isServerRunning()) {
+      console.log("webtty is not running");
+      return;
+    }
+    const ok = await stopServer();
+    if (ok) {
+      console.log("webtty stopped");
+    } else {
+      console.error("webtty stop failed");
+      process.exit(1);
+    }
+  });
+  program2.command("start").description("Start the webtty server").action(async () => {
+    if (await isServerRunning()) {
+      console.log("webtty is already running");
+      return;
+    }
+    await startServer();
+    console.log("webtty started");
+  });
+  program2.command("config").description("Open the config file in $EDITOR").action(() => {
+    const dir = configDir();
+    const configPath = path3.join(dir, "config.json");
+    fs3.mkdirSync(dir, { recursive: true });
+    if (!fs3.existsSync(configPath)) {
+      fs3.writeFileSync(configPath, `{}
+`, "utf8");
+    }
+    const editor = process.env.VISUAL ?? process.env.EDITOR ?? (process.platform === "win32" ? "notepad" : "vi");
+    childProcess2.spawnSync(editor, [configPath], { stdio: "inherit" });
+  });
+  program2.command("help").description("Show help — all commands and options").action(() => {
+    program2.outputHelp();
+  });
 }
 
 // src/cli/index.ts
+var CMDS_WITH_ARGS = new Set(["at", "rm", "ls", "mv"]);
+var CMD_NAME_WIDTH = "mv".length;
 var program2 = new Command;
-program2.name("webtty").description("Web TTY — run terminal sessions in a browser tab");
+program2.name("webtty").description("Launch Terminal UI in the browser.").configureHelp({
+  styleTitle(str) {
+    return str.replace(/:$/, "").toUpperCase();
+  },
+  subcommandTerm(cmd) {
+    const args = cmd.registeredArguments.map((arg) => arg.required ? `<${arg.name()}>` : `[${arg.name()}]`).join(" ");
+    const name = CMDS_WITH_ARGS.has(cmd.name()) ? cmd.name().padEnd(CMD_NAME_WIDTH) : cmd.name();
+    return args ? `${name} ${args}` : name;
+  },
+  formatHelp(cmd, helper) {
+    const helpWidth = helper.helpWidth ?? 80;
+    const termWidth = helper.padWidth(cmd, helper);
+    const callFormatItem = (term, description2) => helper.formatItem(term, termWidth, description2, helper);
+    const description = helper.commandDescription(cmd);
+    const descriptionBlock = description.length > 0 ? ["", helper.boxWrap(helper.styleCommandDescription(description), helpWidth), ""] : [];
+    const indent = "  ";
+    const usageWidth = "webtty [command]".length;
+    const usageBlock = [
+      helper.styleTitle("Usage:"),
+      `${indent}${helper.styleUsage("webtty".padEnd(usageWidth))}  ${helper.styleCommandDescription("Attach to main session and open it")}`,
+      `${indent}${helper.styleUsage("webtty [command]".padEnd(usageWidth))}  ${helper.styleCommandDescription("Execute a specific command")}`,
+      ""
+    ];
+    const commandGroups = helper.groupItems(cmd.commands, helper.visibleCommands(cmd), (sub) => sub.helpGroup?.() || "Commands:");
+    const commandsBlock = [];
+    commandGroups.forEach((commands, group) => {
+      const commandList = commands.map((sub) => callFormatItem(helper.styleSubcommandTerm(helper.subcommandTerm(sub)), helper.styleSubcommandDescription(helper.subcommandDescription(sub))));
+      commandsBlock.push(...helper.formatItemList(group, commandList, helper));
+    });
+    return [...descriptionBlock, ...usageBlock, ...commandsBlock].join(`
+`);
+  }
+});
 registerCommands(program2);
-program2.parse(process.argv);
+program2.action(async () => {
+  await program2.parseAsync(["at", "main"], { from: "user" });
+});
+program2.parseAsync(process.argv);
 
-//# debugId=1C9197F72FC17E7564756E2164756E21
+//# debugId=1ED78924E352A12364756E2164756E21