tmuxes 0.1.8 → 0.1.9

package/server/src/index.ts

@@ -0,0 +1,114 @@
+import express from 'express';
+import readline from 'node:readline';
+import { createServer } from 'node:http';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { config } from './config.js';
+import { log } from './logger.js';
+import { apiRouter } from './rest/router.js';
+import { attachWebSocket } from './ws/wsServer.js';
+import { disposeAll } from './ws/terminalSession.js';
+import { refreshTargets } from './targets.js';
+import { winShell } from './winshell/manager.js';
+import { openBrowser } from './openBrowser.js';
+
+const app = express();
+app.use(express.json({ limit: '5mb' }));
+app.use('/api', apiRouter);
+
+// Serve the built client. Published npm package bundles it at <pkg>/public;
+// in the dev monorepo it lives at server/../../client/dist.
+const here = dirname(fileURLToPath(import.meta.url));
+const clientDist = [join(here, '..', 'public'), join(here, '..', '..', 'client', 'dist')].find(existsSync);
+if (clientDist) {
+  app.use(express.static(clientDist));
+  // SPA fallback for non-API GET routes (avoids path-to-regexp '*' quirks in Express 5).
+  app.use((req, res, next) => {
+    if (req.method !== 'GET' || req.path.startsWith('/api')) return next();
+    res.sendFile(join(clientDist, 'index.html'));
+  });
+  log.info(`serving client from ${clientDist}`);
+}
+
+const server = createServer(app);
+attachWebSocket(server);
+
+server.listen(config.port, config.host, () => {
+  const url = `http://${config.host}:${config.port}`;
+  log.info(`tmuxes listening on ${url}`);
+  // Warm the target cache (discovers WSL distros on Windows) ahead of any WS.
+  void refreshTargets().catch((e) => log.warn(`initial target discovery failed: ${e}`));
+  // One-click launchers set TMUXES_OPEN=1 to pop the browser open.
+  if (process.env.TMUXES_OPEN) openBrowser(url);
+});
+
+let shuttingDown = false;
+function shutdown(signal: string): void {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  log.info(`received ${signal}, shutting down`);
+  // Restore the console we put into raw mode (Windows Ctrl+C handling).
+  try {
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  } catch {
+    /* ignore */
+  }
+  disposeAll();
+  winShell.disposeAll();
+  server.close(() => process.exit(0));
+  // Don't wait forever for lingering sockets.
+  setTimeout(() => process.exit(0), 3000).unref();
+}
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+// Console window closed (Windows) / terminal hangup (POSIX) → free the port.
+process.on('SIGHUP', () => shutdown('SIGHUP'));
+// Windows Ctrl+Break.
+if (process.platform === 'win32') process.on('SIGBREAK', () => shutdown('SIGBREAK'));
+
+// On Windows, node-pty's ConPTY backend breaks the normal CTRL_C_EVENT → SIGINT
+// path for the host process (see microsoft/node-pty#190), so `process.on('SIGINT')`
+// can't be relied on. Instead we read the raw Ctrl+C byte (0x03) straight from the
+// console, set up at startup (before any pty is spawned). This bypasses the signal
+// machinery entirely. Ctrl+Break still works via the SIGBREAK handler above.
+if (process.platform === 'win32') {
+  const stdin = process.stdin;
+  if (stdin.isTTY) {
+    try {
+      stdin.setRawMode(true); // deliver keys as bytes; Ctrl+C arrives as 0x03
+      stdin.resume();
+      stdin.on('data', (buf: Buffer) => {
+        if (buf.includes(0x03)) shutdown('Ctrl+C');
+      });
+    } catch {
+      // Fall back to the readline SIGINT bridge (needs explicit terminal mode).
+      readline
+        .createInterface({ input: stdin, terminal: true })
+        .on('SIGINT', () => shutdown('SIGINT'));
+    }
+  } else {
+    // stdin isn't a console TTY (e.g. piped) — best-effort bridge.
+    try {
+      readline
+        .createInterface({ input: stdin, terminal: true })
+        .on('SIGINT', () => shutdown('SIGINT'));
+    } catch {
+      /* nothing more we can do */
+    }
+  }
+}
+
+// If the port is already held (e.g. a previous run is still alive), exit with a
+// clear message instead of an unhandled-error stack trace.
+server.on('error', (err: NodeJS.ErrnoException) => {
+  if (err.code === 'EADDRINUSE') {
+    log.error(
+      `port ${config.port} is already in use — another tmuxes instance is still running. ` +
+        `Close it (or its window), then start again.`,
+    );
+  } else {
+    log.error(`server error: ${err.message}`);
+  }
+  process.exit(1);
+});

package/server/src/logger.ts

@@ -0,0 +1,16 @@
+/** Tiny timestamped console logger — no external dependency. */
+function ts(): string {
+  return new Date().toISOString();
+}
+
+export const log = {
+  info(msg: string, ...rest: unknown[]): void {
+    console.log(`[${ts()}] ${msg}`, ...rest);
+  },
+  warn(msg: string, ...rest: unknown[]): void {
+    console.warn(`[${ts()}] WARN ${msg}`, ...rest);
+  },
+  error(msg: string, ...rest: unknown[]): void {
+    console.error(`[${ts()}] ERROR ${msg}`, ...rest);
+  },
+};

package/{dist/monitor.js → server/src/monitor.ts}

@@ -1,9 +1,10 @@
-/** Compatibility shim for the sessions route.
- *
- * Agent status now comes directly from Claude Code / Codex lifecycle hooks via
- * tmux session options, so there is no terminal-output heuristic to annotate.
- */
-export function annotate(_targetId, sessions) {
-    return sessions;
-}
-//# sourceMappingURL=monitor.js.map
+import type { SessionInfo } from './tmux/formats.js';
+
+/** Compatibility shim for the sessions route.
+ *
+ * Agent status now comes directly from Claude Code / Codex lifecycle hooks via
+ * tmux session options, so there is no terminal-output heuristic to annotate.
+ */
+export function annotate(_targetId: string, sessions: SessionInfo[]): SessionInfo[] {
+  return sessions;
+}

package/server/src/openBrowser.ts

@@ -0,0 +1,28 @@
+import { spawn } from 'node:child_process';
+import { isWindows, isMac } from './platform.js';
+import { log } from './logger.js';
+
+/** Open `url` in the default browser (best-effort, detached). Used by the
+ *  one-click launchers when TMUXES_OPEN is set. */
+export function openBrowser(url: string): void {
+  try {
+    let file: string;
+    let args: string[];
+    if (isWindows) {
+      // `cmd /c start "" "<url>"` — the empty "" is the window title start needs.
+      file = 'cmd.exe';
+      args = ['/c', 'start', '', url];
+    } else if (isMac) {
+      file = 'open';
+      args = [url];
+    } else {
+      file = 'xdg-open';
+      args = [url];
+    }
+    const child = spawn(file, args, { detached: true, stdio: 'ignore' });
+    child.on('error', (e) => log.warn(`could not open browser: ${e.message}`));
+    child.unref();
+  } catch (e) {
+    log.warn(`could not open browser: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}

package/{dist/platform.js → server/src/platform.ts}

@@ -1,5 +1,4 @@
-/** Platform helpers. Windows has no native tmux, so it reaches tmux inside WSL
- *  via wsl.exe; macOS and Linux run tmux directly. */
-export const isWindows = process.platform === 'win32';
-export const isMac = process.platform === 'darwin';
-//# sourceMappingURL=platform.js.map
+/** Platform helpers. Windows has no native tmux, so it reaches tmux inside WSL
+ *  via wsl.exe; macOS and Linux run tmux directly. */
+export const isWindows = process.platform === 'win32';
+export const isMac = process.platform === 'darwin';

package/server/src/rest/router.ts

@@ -0,0 +1,290 @@
+import { Router, type Request, type Response, type NextFunction } from 'express';
+import { getTarget, isValidTargetId, refreshTargets, type Target } from '../targets.js';
+import { isValidSessionName } from '../validate.js';
+import {
+  TmuxError,
+  listSessions,
+  createSession,
+  renameSession,
+  killSession,
+  listWindows,
+  launchAgentInSession,
+  type LaunchAgent,
+} from '../tmux/sessions.js';
+import { annotate } from '../monitor.js';
+import {
+  getSessionCwd,
+  listDirectory,
+  listSessionDirectory,
+  readFilePreview,
+  resolveScopedPath,
+  writeFile,
+} from '../files.js';
+import { readFolders, writeFolders } from '../foldersStore.js';
+import { winShell, ManagerError } from '../winshell/manager.js';
+
+/** Cap on a saved file's size (matches the editor's text-only use). */
+const MAX_WRITE_BYTES = 5_000_000;
+
+type AsyncHandler = (req: Request, res: Response) => Promise<unknown>;
+
+const wrap =
+  (fn: AsyncHandler) =>
+  (req: Request, res: Response, next: NextFunction): void => {
+    fn(req, res).catch(next);
+  };
+
+/** Resolve :id → Target or throw a TmuxError with the right status. */
+function requireTarget(req: Request): Target {
+  const id = req.params.id;
+  if (!isValidTargetId(id)) throw new TmuxError(400, 'invalid target id');
+  const target = getTarget(id);
+  if (!target) throw new TmuxError(404, 'target not found');
+  return target;
+}
+
+function requireSessionName(raw: unknown): string {
+  if (!isValidSessionName(raw)) throw new TmuxError(400, 'invalid session name');
+  return raw;
+}
+
+function requireLaunchAgent(raw: unknown): LaunchAgent {
+  if (raw === 'claude' || raw === 'codex') return raw;
+  throw new TmuxError(400, 'invalid agent');
+}
+
+/** A filesystem path supplied via query. Passed as a single argv element (no
+ *  shell), so we only sanity-check shape, not contents — this app already
+ *  grants full shell access on the target by design. */
+function requirePath(raw: unknown): string {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > 4096 || raw.includes('\0')) {
+    throw new TmuxError(400, 'invalid path');
+  }
+  return raw;
+}
+
+async function requireSessionScopedPath(
+  target: Target,
+  session: unknown,
+  path: unknown,
+  opts: { forWrite?: boolean } = {},
+): Promise<string> {
+  const name = requireSessionName(session);
+  const rawPath = requirePath(path);
+  const cwd = await getSessionCwd(target, name);
+  return resolveScopedPath(target, cwd, rawPath, opts);
+}
+
+export const apiRouter = Router();
+
+apiRouter.get('/health', (_req, res) => {
+  res.json({ ok: true });
+});
+
+apiRouter.get(
+  '/targets',
+  wrap(async (_req, res) => {
+    // Re-discover (WSL distros / ssh config can change between loads).
+    res.json({ targets: await refreshTargets() });
+  }),
+);
+
+apiRouter.get(
+  '/targets/:id/sessions',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    const sessions = target.kind === 'winlocal' ? winShell.list() : await listSessions(target);
+    res.json({ sessions: annotate(target.id, sessions) });
+  }),
+);
+
+apiRouter.post(
+  '/targets/:id/sessions',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    const body = (req.body ?? {}) as { name?: unknown; command?: unknown; shell?: unknown };
+
+    const name = body.name === undefined || body.name === '' ? undefined : body.name;
+    if (name !== undefined && !isValidSessionName(name)) {
+      throw new TmuxError(400, 'invalid session name');
+    }
+    const command =
+      typeof body.command === 'string' && body.command.length > 0 ? body.command : undefined;
+
+    if (target.kind === 'winlocal') {
+      const shellId = typeof body.shell === 'string' ? body.shell : undefined;
+      res.status(201).json(winShell.create({ name, shellId, command }));
+      return;
+    }
+
+    const result = await createSession(target, { name, command });
+    res.status(201).json(result);
+  }),
+);
+
+apiRouter.patch(
+  '/targets/:id/sessions/:name',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    const name = requireSessionName(req.params.name);
+    const newName = (req.body ?? {}).newName;
+    if (!isValidSessionName(newName)) throw new TmuxError(400, 'invalid new session name');
+    if (target.kind === 'winlocal') {
+      winShell.rename(name, newName);
+      res.json({ name: newName });
+      return;
+    }
+    await renameSession(target, name, newName);
+    res.json({ name: newName });
+  }),
+);
+
+apiRouter.post(
+  '/targets/:id/sessions/:name/agent',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    if (target.kind === 'winlocal') throw new TmuxError(400, 'agent hooks require a tmux target');
+    const name = requireSessionName(req.params.name);
+    const agent = requireLaunchAgent((req.body ?? {}).agent);
+    await launchAgentInSession(target, name, agent);
+    res.json({ ok: true });
+  }),
+);
+
+apiRouter.delete(
+  '/targets/:id/sessions/:name',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    const name = requireSessionName(req.params.name);
+    if (target.kind === 'winlocal') {
+      winShell.kill(name);
+      res.status(204).end();
+      return;
+    }
+    await killSession(target, name);
+    res.status(204).end();
+  }),
+);
+
+apiRouter.get(
+  '/targets/:id/sessions/:name/windows',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    const name = requireSessionName(req.params.name);
+    if (target.kind === 'winlocal') {
+      res.json({ windows: winShell.windows(name) });
+      return;
+    }
+    res.json({ windows: await listWindows(target, name) });
+  }),
+);
+
+/** The file browser relies on tmux's pane cwd; native Windows shells have none. */
+function rejectIfWinlocal(target: Target): void {
+  if (target.kind === 'winlocal') {
+    throw new TmuxError(400, 'file browsing is not available for native shell sessions');
+  }
+}
+
+// --- File browser (current pane cwd + directory listing + file preview) ---
+
+apiRouter.get(
+  '/targets/:id/sessions/:name/cwd',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    rejectIfWinlocal(target);
+    const name = requireSessionName(req.params.name);
+    res.json({ cwd: await getSessionCwd(target, name) });
+  }),
+);
+
+apiRouter.get(
+  '/targets/:id/files',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    rejectIfWinlocal(target);
+    const path = await requireSessionScopedPath(target, req.query.session, req.query.path);
+    res.json({ path, entries: await listDirectory(target, path) });
+  }),
+);
+
+apiRouter.get(
+  '/targets/:id/sessions/:name/files',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    rejectIfWinlocal(target);
+    const name = requireSessionName(req.params.name);
+    const rawPath = req.query.path;
+    const path = rawPath === undefined ? undefined : requirePath(rawPath);
+    res.json(await listSessionDirectory(target, name, path));
+  }),
+);
+
+apiRouter.get(
+  '/targets/:id/file',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    rejectIfWinlocal(target);
+    const path = await requireSessionScopedPath(target, req.query.session, req.query.path);
+    res.json(await readFilePreview(target, path));
+  }),
+);
+
+apiRouter.put(
+  '/targets/:id/file',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    rejectIfWinlocal(target);
+    const body = (req.body ?? {}) as { session?: unknown; path?: unknown; content?: unknown };
+    const path = await requireSessionScopedPath(target, body.session, body.path, { forWrite: true });
+    if (typeof body.content !== 'string') throw new TmuxError(400, 'content must be a string');
+    if (Buffer.byteLength(body.content, 'utf8') > MAX_WRITE_BYTES) {
+      throw new TmuxError(413, 'file too large to save');
+    }
+    await writeFile(target, path, body.content);
+    res.json({ ok: true });
+  }),
+);
+
+// --- Sidebar folder organization, persisted on the target (syncs clients) ---
+
+apiRouter.get(
+  '/targets/:id/folders',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    res.json(await readFolders(target));
+  }),
+);
+
+apiRouter.put(
+  '/targets/:id/folders',
+  wrap(async (req, res) => {
+    const target = requireTarget(req);
+    const body = req.body as { folders?: unknown; assign?: unknown };
+    if (
+      !body ||
+      typeof body !== 'object' ||
+      Array.isArray(body) ||
+      !Array.isArray(body.folders) ||
+      typeof body.assign !== 'object' ||
+      body.assign === null
+    ) {
+      throw new TmuxError(400, 'invalid folders payload');
+    }
+    await writeFolders(target, {
+      folders: body.folders,
+      assign: body.assign as Record<string, unknown>,
+    });
+    res.json({ ok: true });
+  }),
+);
+
+// Central error mapper.
+apiRouter.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
+  if (err instanceof TmuxError || err instanceof ManagerError) {
+    res.status(err.status).json({ error: err.message });
+    return;
+  }
+  const message = err instanceof Error ? err.message : 'internal error';
+  res.status(500).json({ error: message });
+});

package/server/src/targetCommand.ts

@@ -0,0 +1,79 @@
+import { unlinkSync } from 'node:fs';
+import { runCommand, type CommandResult, type RunOptions } from './exec.js';
+import type { Target } from './targets.js';
+import { sshControlPath } from './tmux/builder.js';
+import { isWindows } from './platform.js';
+import { dropWindowsSshSession, runWindowsSshCommand } from './windowsSsh.js';
+
+type BuildArgv = (opts: { multiplex?: boolean }) => { file: string; args: string[] };
+
+const SSH_INTERRUPTION_RE =
+  /mux_client_request_session|Control socket connect|Broken pipe|Connection reset|Connection closed|Connection to .* closed|Connection timed out|Operation timed out|No route to host|Network is unreachable|Connection refused|kex_exchange_identification|banner exchange|stdio forwarding failed/i;
+
+const SSH_CLIENT_FAILURE_RE =
+  /Permission denied \(|Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED|Could not resolve hostname|Too many authentication failures|Connection timed out|Operation timed out|No route to host|Network is unreachable|Connection refused|Connection reset|Connection closed|Connection to .* closed|Broken pipe|kex_exchange_identification|banner exchange/i;
+
+function firstLine(stderr: string): string {
+  return stderr.trim().split('\n')[0] || 'ssh command failed';
+}
+
+function isInterruptedSsh(result: CommandResult): boolean {
+  return result.code !== 0 && SSH_INTERRUPTION_RE.test(result.stderr);
+}
+
+function isSshClientFailure(result: CommandResult): boolean {
+  return result.code !== 0 && SSH_CLIENT_FAILURE_RE.test(result.stderr);
+}
+
+/** Run a target command. If an SSH control master is stale/interrupted, retry
+ * exactly once using a fresh direct SSH connection. Authentication failures are
+ * not retried, to avoid repeated failed-login noise. */
+export async function runTargetCommand(
+  target: Target,
+  buildArgv: BuildArgv,
+  opts: RunOptions = {},
+): Promise<CommandResult> {
+  if (target.kind === 'ssh' && isWindows) return runWindowsTargetCommand(target, buildArgv, opts);
+
+  const firstArgv = buildArgv({ multiplex: true });
+  const first = await runCommand(firstArgv.file, firstArgv.args, opts);
+  if (target.kind !== 'ssh' || !isInterruptedSsh(first)) return first;
+
+  const controlPath = sshControlPath(target);
+  if (controlPath) {
+    try {
+      unlinkSync(controlPath);
+    } catch {
+      /* stale socket may already be gone */
+    }
+  }
+
+  const retryArgv = buildArgv({ multiplex: false });
+  const retry = await runCommand(retryArgv.file, retryArgv.args, opts);
+  if (retry.code === 0 || !isSshClientFailure(retry)) return retry;
+
+  return {
+    ...retry,
+    stderr: `SSH connection interrupted; one reconnect attempt failed: ${firstLine(retry.stderr)}\n${retry.stderr}`,
+  };
+}
+
+async function runWindowsTargetCommand(
+  target: Target,
+  buildArgv: BuildArgv,
+  opts: RunOptions,
+): Promise<CommandResult> {
+  const firstArgv = buildArgv({ multiplex: false });
+  const first = await runWindowsSshCommand(target, firstArgv.file, firstArgv.args, opts);
+  if (!isInterruptedSsh(first)) return first;
+
+  dropWindowsSshSession(target);
+  const retryArgv = buildArgv({ multiplex: false });
+  const retry = await runWindowsSshCommand(target, retryArgv.file, retryArgv.args, opts);
+  if (retry.code === 0 || !isSshClientFailure(retry)) return retry;
+
+  return {
+    ...retry,
+    stderr: `SSH connection interrupted; one reconnect attempt failed: ${firstLine(retry.stderr)}\n${retry.stderr}`,
+  };
+}