termdeck-cli 1.0.2

package/src/terminal.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Opening a *brand new* OS terminal window in a project folder.
+ *
+ * Termdeck never opens a terminal for the dev server (those logs are piped into
+ * the TUI) \u2014 this module is only used for the "Open Editor" / "Open Agent"
+ * CTAs, where a real interactive shell is what the user wants.
+ */
+
+const crossSpawn = require('cross-spawn');
+const { which, shellQuote, appleScriptString } = require('./util');
+
+/** Commands that are shell built-ins / launch a terminal window. */
+function buildTerminalCandidates({ cwd, command, platform = process.platform }) {
+  const candidates = [];
+  // Keeps the window open after the command exits, so errors stay readable.
+  const keepOpen = `${command}; exec bash`;
+
+  if (platform === 'darwin') {
+    const shellCommand = `cd ${shellQuote(cwd)} && ${command}`;
+    const script = [
+      'tell application "Terminal"',
+      '  activate',
+      `  do script ${appleScriptString(shellCommand)}`,
+      'end tell',
+    ];
+    const args = [];
+    script.forEach((line) => args.push('-e', line));
+
+    candidates.push({
+      id: 'macos-terminal',
+      bin: 'osascript',
+      args,
+      available: true,
+    });
+    return candidates;
+  }
+
+  if (platform === 'win32') {
+    // Windows Terminal first (prettier + tab support), then a plain console.
+    candidates.push({
+      id: 'windows-terminal',
+      bin: 'wt.exe',
+      args: ['-d', cwd, 'cmd', '/k', command],
+      available: Boolean(which('wt.exe')),
+    });
+
+    candidates.push({
+      id: 'cmd-start',
+      bin: process.env.ComSpec || 'cmd.exe',
+      // NOTE: windowsVerbatimArguments means we do our own quoting here. `/D`
+      // sets the working directory of the new window, and `start ""` supplies
+      // the required (empty) window title.
+      args: ['/c', 'start', '""', '/D', `"${cwd}"`, 'cmd.exe', '/k', `"${command}"`],
+      verbatim: true,
+      available: true,
+    });
+    return candidates;
+  }
+
+  // Linux / BSD: try every common emulator, in order of popularity.
+  const emulators = [
+    { id: 'gnome-terminal', bin: 'gnome-terminal', args: ['--working-directory', cwd, '--', 'bash', '-lc', keepOpen] },
+    { id: 'konsole', bin: 'konsole', args: ['--workdir', cwd, '-e', 'bash', '-lc', keepOpen] },
+    { id: 'xfce4-terminal', bin: 'xfce4-terminal', args: ['--working-directory', cwd, '-x', 'bash', '-lc', keepOpen] },
+    { id: 'kitty', bin: 'kitty', args: ['--directory', cwd, 'bash', '-lc', keepOpen] },
+    { id: 'alacritty', bin: 'alacritty', args: ['--working-directory', cwd, '-e', 'bash', '-lc', keepOpen] },
+    { id: 'wezterm', bin: 'wezterm', args: ['start', '--cwd', cwd, '--', 'bash', '-lc', keepOpen] },
+    {
+      id: 'x-terminal-emulator',
+      bin: 'x-terminal-emulator',
+      args: ['-e', 'bash', '-lc', `cd ${shellQuote(cwd)} && ${keepOpen}`],
+    },
+    {
+      id: 'xterm',
+      bin: 'xterm',
+      args: ['-e', 'bash', '-lc', `cd ${shellQuote(cwd)} && ${keepOpen}`],
+    },
+  ];
+
+  emulators.forEach((emulator) => {
+    candidates.push({ ...emulator, available: Boolean(which(emulator.bin)) });
+  });
+
+  return candidates;
+}
+
+/** Human readable form of a candidate, for logs and `--dry-run`. */
+function formatTerminalCommand(candidate) {
+  if (!candidate) return '';
+  const args = candidate.args.map((arg) => (/\s/.test(arg) ? JSON.stringify(arg) : arg));
+  return `${candidate.bin} ${args.join(' ')}`.trim();
+}
+
+/** Put a user-preferred emulator (TERMDECK_TERMINAL) at the front of the list. */
+function applyPreference(candidates, prefer) {
+  if (!prefer) return candidates;
+  const wanted = String(prefer).toLowerCase();
+  const index = candidates.findIndex(
+    (c) => c.id.toLowerCase() === wanted || c.bin.toLowerCase() === wanted || c.bin.toLowerCase().startsWith(wanted)
+  );
+  if (index <= 0) return candidates;
+  const preferred = candidates[index];
+  return [preferred, ...candidates.filter((_, i) => i !== index)];
+}
+
+/** Resolve when the child actually started; reject on ENOENT/EPERM. */
+function waitForSpawn(child, timeoutMs = 5000) {
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const finish = (fn, value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      child.removeListener('spawn', onSpawn);
+      child.removeListener('error', onError);
+      fn(value);
+    };
+    const onSpawn = () => finish(resolve);
+    const onError = (err) => finish(reject, err);
+    const timer = setTimeout(() => finish(reject, new Error('timed out starting terminal')), timeoutMs);
+    if (timer.unref) timer.unref();
+
+    child.once('spawn', onSpawn);
+    child.once('error', onError);
+  });
+}
+
+/**
+ * Spawn a new OS terminal window, cd into `cwd` and run `command` there.
+ *
+ * @returns {Promise<{ok: boolean, terminal?: string, command?: string, error?: string}>}
+ */
+async function openInNewTerminal({ cwd, command, platform = process.platform, prefer = process.env.TERMDECK_TERMINAL, dryRun = false }) {
+  const candidates = applyPreference(buildTerminalCandidates({ cwd, command, platform }), prefer);
+  const usable = candidates.filter((c) => c.available);
+
+  if (usable.length === 0) {
+    return {
+      ok: false,
+      error: `No terminal emulator found. Tried: ${candidates.map((c) => c.id).join(', ')}. Set TERMDECK_TERMINAL to your emulator.`,
+    };
+  }
+
+  if (dryRun) {
+    return { ok: true, terminal: usable[0].id, command: formatTerminalCommand(usable[0]), dryRun: true };
+  }
+
+  const errors = [];
+  for (const candidate of usable) {
+    try {
+      const child = crossSpawn(candidate.bin, candidate.args, {
+        detached: true,
+        stdio: 'ignore',
+        windowsVerbatimArguments: candidate.verbatim === true,
+      });
+      await waitForSpawn(child);
+      // A late failure must never crash the TUI.
+      child.on('error', () => {});
+      child.unref();
+      return { ok: true, terminal: candidate.id, command: formatTerminalCommand(candidate) };
+    } catch (err) {
+      errors.push(`${candidate.id}: ${err.message}`);
+    }
+  }
+
+  return { ok: false, error: errors.join(' | ') };
+}
+
+module.exports = {
+  buildTerminalCandidates,
+  formatTerminalCommand,
+  openInNewTerminal,
+};

package/src/util.js

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * Small shared helpers used across termdeck.
+ *
+ * Everything in here is intentionally dependency free and side-effect free so it
+ * can be unit tested without a terminal (see test/run.js).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/* ------------------------------------------------------------------ *
+ * Terminal output helpers
+ * ------------------------------------------------------------------ */
+
+// Covers CSI sequences (\x1b[...m), OSC sequences (\x1b]...\x07) and the
+// `ESC ( B` style charset selects that npm/vite sometimes emit.
+const ANSI_RE = /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z0-9]*(?:;[-a-zA-Z0-9\/#&.:=?%@~_]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+
+/** Remove ANSI colour/control codes from a chunk of terminal output. */
+function stripAnsi(input) {
+  return String(input == null ? '' : input).replace(ANSI_RE, '');
+}
+
+/**
+ * Escape `{`/`}` for blessed's tag parser. Blessed treats `{red-fg}` as markup,
+ * so raw log output (JSON, JSX, template literals...) has to be escaped or it
+ * renders as garbage. `{open}`/`{close}` are blessed's literal brace tags.
+ */
+function escapeBraces(text) {
+  // Single pass: replacing `{` first would then rewrite the `}` of the
+  // `{open}` tag we just inserted.
+  return String(text == null ? '' : text).replace(/[{}]/g, (ch) => (ch === '{' ? '{open}' : '{close}'));
+}
+
+/** Truncate plain text to `width` characters, adding an ellipsis when cut. */
+function truncate(text, width) {
+  const str = String(text == null ? '' : text);
+  if (!Number.isFinite(width) || width <= 1) return str;
+  if (str.length <= width) return str;
+  return str.slice(0, Math.max(0, width - 1)) + '\u2026';
+}
+
+/** Right-pad/left-pad a label to a fixed width. */
+function padEnd(text, width) {
+  const str = String(text == null ? '' : text);
+  return str.length >= width ? str : str + ' '.repeat(width - str.length);
+}
+
+/** `HH:MM:SS` timestamp for log lines. */
+function timestamp(date = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${p(date.getHours())}:${p(date.getMinutes())}:${p(date.getSeconds())}`;
+}
+
+/* ------------------------------------------------------------------ *
+ * Dev-server output parsing
+ * ------------------------------------------------------------------ */
+
+const URL_RE = /https?:\/\/[^\s"'`<>()[\]{}|\\^]+/gi;
+const HOST_PORT_RE = /\b(localhost|127\.0\.0\.1|0\.0\.0\.0)\s*:\s*(\d{2,5})\b/i;
+// Last-resort: "Port 3000", "port: 5173", "using port 8080".
+const PORT_RE = /\bport\b[^\d\n]{0,24}?(\d{2,5})\b/i;
+const LOCAL_HOSTS = /(^|\/\/)(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(:|\/|$)/i;
+
+/** `http://0.0.0.0:3000/` -> `http://localhost:3000`. */
+function normalizeLocalUrl(url) {
+  return String(url == null ? '' : url)
+    .trim()
+    .replace(/\/\/(0\.0\.0\.0)/, '//localhost')
+    .replace(/\/\/(\[::1\]|::1)/, '//localhost')
+    .replace(/[.,;:)\]}'"`]+$/, '')
+    .replace(/\/+$/, '');
+}
+
+/**
+ * Pull the first "local" URL out of a line of dev-server output.
+ * Returns null when the line does not advertise a local address.
+ */
+function extractLocalUrl(text) {
+  const clean = stripAnsi(text);
+
+  const urls = clean.match(URL_RE);
+  if (urls) {
+    for (const raw of urls) {
+      const candidate = raw.replace(/[.,;:)\]}'"`]+$/, '');
+      if (LOCAL_HOSTS.test(candidate)) return normalizeLocalUrl(candidate);
+    }
+  }
+
+  const hostPort = clean.match(HOST_PORT_RE);
+  if (hostPort) return normalizeLocalUrl(`http://${hostPort[1]}:${hostPort[2]}`);
+
+  const port = clean.match(PORT_RE);
+  if (port) return `http://localhost:${port[1]}`;
+
+  return null;
+}
+
+/**
+ * Split a stream chunk into complete lines, keeping the unfinished tail in
+ * `carry` (mutated in place so callers can pipe chunks straight through).
+ */
+function splitLines(chunk, carry = { rest: '' }) {
+  carry.rest += String(chunk == null ? '' : chunk);
+  const parts = carry.rest.split(/\r\n|\n|\r/);
+  carry.rest = parts.pop();
+  return parts.filter((line) => line.trim() !== '');
+}
+
+/* ------------------------------------------------------------------ *
+ * OS helpers
+ * ------------------------------------------------------------------ */
+
+/**
+ * Minimal `which(1)`: look a binary up on PATH.
+ * Avoids spawning a child process just to test for an executable.
+ */
+function which(bin, env = process.env) {
+  if (!bin) return null;
+  const exts = process.platform === 'win32'
+    ? String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [''];
+  const dirs = String(env.PATH || env.Path || '').split(path.delimiter).filter(Boolean);
+  const hasExt = path.extname(bin) !== '';
+
+  for (const dir of dirs) {
+    for (const ext of hasExt ? [''] : exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        if (fs.statSync(candidate).isFile()) return candidate;
+      } catch (_) {
+        /* keep looking */
+      }
+    }
+  }
+  return null;
+}
+
+/** POSIX single-quote a value so it survives a shell round trip. */
+function shellQuote(value) {
+  return `'${String(value == null ? '' : value).replace(/'/g, `'\\''`)}'`;
+}
+
+/** Quote a value for embedding inside an AppleScript string literal. */
+function appleScriptString(value) {
+  return `"${String(value == null ? '' : value)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r?\n/g, ' ')}"`;
+}
+
+/**
+ * Kill a child process *and* its children (npm -> node -> vite, etc).
+ * Windows needs `taskkill /T`; on POSIX we spawn the tree detached and kill the
+ * whole process group.
+ */
+function killTree(child, { signal = 'SIGTERM' } = {}) {
+  if (!child || child.pid == null) return false;
+  if (child.exitCode !== null || child.signalCode) return false;
+
+  const pid = child.pid;
+
+  if (process.platform === 'win32') {
+    try {
+      spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      return true;
+    } catch (_) {
+      try {
+        child.kill();
+        return true;
+      } catch (_) {
+        return false;
+      }
+    }
+  }
+
+  try {
+    process.kill(-pid, signal);
+  } catch (_) {
+    try {
+      child.kill(signal);
+    } catch (_) {
+      return false;
+    }
+  }
+
+  // Escalate if the dev server ignores SIGTERM. `unref` keeps this timer from
+  // holding the process open.
+  const timer = setTimeout(() => {
+    if (child.exitCode !== null || child.signalCode) return;
+    try {
+      process.kill(-pid, 'SIGKILL');
+    } catch (_) {
+      /* already gone */
+    }
+  }, 3000);
+  if (timer.unref) timer.unref();
+
+  return true;
+}
+
+module.exports = {
+  stripAnsi,
+  escapeBraces,
+  truncate,
+  padEnd,
+  timestamp,
+  normalizeLocalUrl,
+  extractLocalUrl,
+  splitLines,
+  which,
+  shellQuote,
+  appleScriptString,
+  killTree,
+};