termdeck-cli 1.0.2

package/src/devServer.js

@@ -0,0 +1,246 @@
+'use strict';
+
+/**
+ * Dev server manager.
+ *
+ * Each project gets at most one running `npm run dev` child process. stdout and
+ * stderr are piped back to the caller (the TUI log pane) instead of being
+ * attached to a terminal, and the first localhost URL found in the output is
+ * opened in the default browser.
+ */
+
+const open = require('open');
+const crossSpawn = require('cross-spawn');
+const { extractLocalUrl, splitLines, stripAnsi, killTree } = require('./util');
+
+const DEFAULT_DEV_COMMAND = 'npm run dev';
+
+/** Fallback browser launcher (injectable so tests never open a real browser). */
+async function defaultOpenBrowser(url) {
+  await open(url);
+}
+
+function parseCommand(command) {
+  const parts = String(command || '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  return { bin: parts[0], args: parts.slice(1) };
+}
+
+class DevServerManager {
+  /**
+   * @param {object} options
+   * @param {function} options.onLog    (project, line, stream) => void
+   * @param {function} options.onState  (project, state) => void
+   * @param {function} options.onExit   (project, {code, signal, stoppedByUs}) => void
+   * @param {function} options.openBrowser (url, project) => Promise<void>
+   */
+  constructor(options = {}) {
+    this.onLog = options.onLog || (() => {});
+    this.onState = options.onState || (() => {});
+    this.onExit = options.onExit || (() => {});
+    this.openBrowser = options.openBrowser || defaultOpenBrowser;
+    this.devCommand = options.devCommand || DEFAULT_DEV_COMMAND;
+    this.fallbackPort = options.fallbackPort || 3000;
+    // How long to wait for the process to print a URL before guessing one.
+    this.urlFallbackDelayMs = options.urlFallbackDelayMs || 9000;
+    // Give the HTTP listener a moment to bind before the browser hits it.
+    this.browserDelayMs = options.browserDelayMs || 1200;
+    this.servers = new Map();
+    this.lastExit = new Map();
+    this.autoOpenBrowser = options.autoOpenBrowser !== false;
+  }
+
+  /** @returns {object|undefined} running entry for a project path */
+  get(projectPath) {
+    return this.servers.get(projectPath);
+  }
+
+  isRunning(projectPath) {
+    return this.servers.has(projectPath);
+  }
+
+  get runningCount() {
+    return this.servers.size;
+  }
+
+  /**
+   * Start a project's dev server.
+   * @returns {{ok: boolean, entry?: object, error?: string, alreadyRunning?: boolean}}
+   */
+  start(project, options = {}) {
+    if (this.servers.has(project.path)) {
+      return { ok: false, alreadyRunning: true, entry: this.servers.get(project.path), error: 'already running' };
+    }
+
+    const command = options.command || project.devCommand || this.devCommand;
+    const { bin, args } = parseCommand(command);
+    if (!bin) return { ok: false, error: `No dev command configured for ${project.name}.` };
+
+    const entry = {
+      project,
+      command,
+      child: null,
+      url: null,
+      urlGuess: false,
+      status: 'starting',
+      startedAt: Date.now(),
+      browserOpened: false,
+      stopping: false,
+      timers: [],
+    };
+
+    let child;
+    try {
+      child = crossSpawn(bin, args, {
+        cwd: project.path,
+        env: {
+          ...process.env,
+          // Keep output plain so it renders cleanly inside the TUI log pane,
+          // and stop frameworks from opening their own browser tab.
+          FORCE_COLOR: '0',
+          BROWSER: 'none',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        // Own process group on POSIX so we can kill the whole tree.
+        detached: process.platform !== 'win32',
+      });
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+
+    entry.child = child;
+    entry.pid = child.pid;
+    this.servers.set(project.path, entry);
+    this.log(project, `{bold}$${escapeTags(command)}{/bold}  (cwd: ${project.path})`, 'system');
+
+    const carryOut = { rest: '' };
+    const carryErr = { rest: '' };
+
+    child.stdout.on('data', (chunk) => this.handleChunk(entry, chunk, carryOut, 'stdout'));
+    child.stderr.on('data', (chunk) => this.handleChunk(entry, chunk, carryErr, 'stderr'));
+
+    child.on('error', (err) => {
+      if (this.servers.get(project.path) === entry) this.servers.delete(project.path);
+      entry.status = 'error';
+      entry.error = err.message;
+      this.clearTimers(entry);
+      this.state(project, { status: 'error', pid: entry.pid, url: entry.url, error: err.message });
+      this.log(project, `{red-fg}cannot start "${command}": ${escapeTags(err.message)}{/red-fg}`, 'system');
+    });
+
+    child.on('exit', (code, signal) => {
+      const stoppedByUs = entry.stopping;
+      if (this.servers.get(project.path) === entry) this.servers.delete(project.path);
+      this.clearTimers(entry);
+      entry.status = 'stopped';
+      this.lastExit.set(project.path, { code, signal, at: Date.now(), stoppedByUs });
+      this.state(project, { status: 'stopped', pid: entry.pid, url: entry.url, code, signal });
+      this.onExit(project, { code, signal, stoppedByUs });
+    });
+
+    this.state(project, { status: 'starting', pid: entry.pid, url: null });
+
+    // Some dev servers are silent: fall back to an assumed port.
+    entry.timers.push(
+      setTimeout(() => {
+        if (!entry.url && this.servers.get(project.path) === entry) {
+          const port = project.port || this.fallbackPort;
+          this.log(
+            project,
+            `{yellow-fg}no localhost URL in the logs after ${Math.round(this.urlFallbackDelayMs / 1000)}s \u2014 assuming http://localhost:${port}{/yellow-fg}`,
+            'system'
+          );
+          this.handleUrl(entry, `http://localhost:${port}`, { guessed: true });
+        }
+      }, this.urlFallbackDelayMs)
+    );
+
+    return { ok: true, entry };
+  }
+
+  /** Consume raw stream data: split lines, look for the first local URL. */
+  handleChunk(entry, chunk, carry, stream) {
+    const lines = splitLines(chunk.toString('utf8'), carry);
+    for (const raw of lines) {
+      const line = stripAnsi(raw).replace(/\s+$/, '');
+      if (!line.trim()) continue;
+      if (!entry.url) {
+        const found = extractLocalUrl(line);
+        if (found) this.handleUrl(entry, found);
+      }
+      this.log(entry.project, line, stream);
+    }
+  }
+
+  handleUrl(entry, url, { guessed = false } = {}) {
+    if (entry.url) return;
+    entry.url = url;
+    entry.urlGuess = guessed;
+    entry.status = 'running';
+    this.state(entry.project, { status: 'running', pid: entry.pid, url, guessed });
+
+    if (!this.autoOpenBrowser || entry.browserOpened) return;
+    entry.browserOpened = true;
+
+    const timer = setTimeout(async () => {
+      if (this.servers.get(entry.project.path) !== entry) return;
+      try {
+        await this.openBrowser(url, entry.project);
+        this.log(entry.project, `{green-fg}opened ${url} in your browser{/green-fg}`, 'system');
+      } catch (err) {
+        this.log(entry.project, `{yellow-fg}could not open a browser (${escapeTags(err.message)}) \u2014 visit ${url}{/yellow-fg}`, 'system');
+      }
+    }, guessed ? 0 : this.browserDelayMs);
+    entry.timers.push(timer);
+  }
+
+  /** Stop one dev server (and its children). */
+  stop(projectPath) {
+    const entry = this.servers.get(projectPath);
+    if (!entry) return false;
+    entry.stopping = true;
+    this.clearTimers(entry);
+    this.servers.delete(projectPath);
+    this.state(entry.project, { status: 'stopped', pid: entry.pid, url: entry.url });
+    killTree(entry.child);
+    return true;
+  }
+
+  /** Stop everything \u2014 called when the TUI quits. */
+  stopAll() {
+    const paths = [...this.servers.keys()];
+    paths.forEach((projectPath) => this.stop(projectPath));
+    return paths.length;
+  }
+
+  clearTimers(entry) {
+    entry.timers.forEach((timer) => clearTimeout(timer));
+    entry.timers = [];
+  }
+
+  state(project, state) {
+    try {
+      this.onState(project, state);
+    } catch (_) {
+      /* never let a render error kill a child process */
+    }
+  }
+
+  log(project, line, stream) {
+    try {
+      this.onLog(project, line, stream);
+    } catch (_) {
+      /* ignore */
+    }
+  }
+}
+
+/** blessed treats `{`/`}` as markup \u2014 escape command strings for the log pane. */
+function escapeTags(text) {
+  return String(text == null ? '' : text).replace(/\{/g, '{open}').replace(/\}/g, '{close}');
+}
+
+module.exports = { DevServerManager, DEFAULT_DEV_COMMAND, defaultOpenBrowser, parseCommand };

package/src/index.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * termdeck CLI.
+ *
+ * `termdeck`                launch the dashboard (runs setup on first use)
+ * `termdeck --setup`        re-run the setup wizard
+ * `termdeck --reset`        delete the config file and run setup again
+ * `termdeck --list`         print the configured projects and exit (no TUI)
+ * `termdeck --no-open`      do not auto-open the browser for dev servers
+ */
+
+const fs = require('fs');
+
+const { getConfigPath, configExists, loadConfig, runSetupWizard } = require('./config');
+
+const HELP = `
+  termdeck - a terminal dashboard for your local dev projects
+
+  Usage
+    $ termdeck [options]
+
+  Options
+    -h, --help        Show this help
+    -V, --version     Show the version
+    -s, --setup       Re-run the interactive setup wizard
+    -r, --reset       Delete the config file, then run setup again
+    -l, --list        Print the configured projects and exit
+        --no-open     Do not open a browser when a dev server starts
+
+  Keys (inside the dashboard)
+    up/down, j/k      Select a project
+    d                 Start \`npm run dev\` and stream its logs into the pane
+    e                 Open the project in your editor in a NEW terminal window
+    a                 Open your coding agent in a NEW terminal window
+    x                 Stop the selected project's dev server
+    r                 Reload the config file
+    PgUp/PgDn, wheel  Scroll the dev server logs (G to follow the tail again)
+    q                 Quit (stops every dev server it started)
+
+  Config
+    ${getConfigPath()}
+    Override the location with the TERMDECK_CONFIG environment variable.
+`;
+
+function parseArgs(argv = []) {
+  const args = { help: false, version: false, setup: false, reset: false, list: false, noOpen: false };
+  for (const raw of argv) {
+    const arg = String(raw);
+    switch (arg) {
+      case '-h':
+      case '--help':
+        args.help = true;
+        break;
+      case '-V':
+      case '--version':
+        args.version = true;
+        break;
+      case '-s':
+      case '--setup':
+        args.setup = true;
+        break;
+      case '-r':
+      case '--reset':
+        args.reset = true;
+        break;
+      case '-l':
+      case '--list':
+        args.list = true;
+        break;
+      case '--no-open':
+        args.noOpen = true;
+        break;
+      default:
+        args.unknown = arg;
+    }
+  }
+  return args;
+}
+
+function printProjects(config) {
+  const lines = [`Config: ${getConfigPath()}`, `Root:   ${config.root}`, ''];
+  const nameWidth = Math.max(...config.projects.map((p) => p.name.length), 4) + 2;
+  lines.push(`  ${'NAME'.padEnd(nameWidth)}${'STATUS'.padEnd(14)}DESCRIPTION / PATH`);
+  for (const project of config.projects) {
+    lines.push(`  ${project.name.padEnd(nameWidth)}${project.status.padEnd(14)}${project.info}`);
+    lines.push(`  ${' '.repeat(nameWidth)}${' '.repeat(14)}${project.path}`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function needsTTY(what) {
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  if (interactive) return false;
+  process.stderr.write(
+    `termdeck needs an interactive terminal to ${what}.\n` +
+      `Open a real terminal and run it again, or use \`termdeck --list\` to inspect the saved config.\n`
+  );
+  return true;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {Promise<number>} exit code (the dashboard keeps the event loop alive)
+ */
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  if (args.version) {
+    // eslint-disable-next-line global-require
+    process.stdout.write(`${require('../package.json').version}\n`);
+    return 0;
+  }
+
+  if (args.reset) {
+    const file = getConfigPath();
+    if (configExists()) {
+      fs.unlinkSync(file);
+      process.stdout.write(`Removed ${file}\n`);
+    } else {
+      process.stdout.write(`No config file at ${file}\n`);
+    }
+  }
+
+  const existing = args.reset ? null : loadConfig({ onWarn: (message) => process.stderr.write(`${message}\n`) });
+  let config = existing;
+
+  if (args.list && !config) {
+    process.stderr.write(`No config found at ${getConfigPath()}. Run \`termdeck --setup\` in a real terminal first.\n`);
+    return 1;
+  }
+
+  if (args.setup || args.reset || !config) {
+    if (needsTTY('run the setup wizard')) return 1;
+    config = await runSetupWizard({ existing });
+  }
+
+  if (!config.projects.length) {
+    process.stderr.write('No projects configured. Run `termdeck --setup`.\n');
+    return 1;
+  }
+
+  if (args.list) {
+    printProjects(config);
+    return 0;
+  }
+
+  if (needsTTY('render the dashboard')) return 1;
+
+  // Loaded lazily so `--help`, `--version` and `--list` stay fast and work
+  // even when blessed has no usable terminal.
+  // eslint-disable-next-line global-require
+  const { launchDashboard } = require('./dashboard');
+  launchDashboard(config, { autoOpen: !args.noOpen });
+
+  return 0;
+}
+
+module.exports = { main, parseArgs, printProjects, HELP, getConfigPath };

package/src/logView.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * Scrollable log pane.
+ *
+ * Wraps a blessed-contrib `log` widget (which is a blessed `List`) and adds:
+ *  - batched writes (dev servers can emit hundreds of lines per second and
+ *    rebuilding the widget on every single line is far too slow),
+ *  - follow-the-tail behaviour,
+ *  - scroll back / pause with a "N new lines" indicator,
+ *  - a bounded history so long running servers cannot eat all memory.
+ *
+ * Scrolling is implemented by trimming the tail of the visible slice rather
+ * than by touching blessed's internal childBase/childOffset, so it behaves
+ * identically on every blessed version. The widget is only ever asked to
+ * `setItems()` and `setLabel()`.
+ */
+
+const DEFAULT_MAX_LINES = 500;
+
+class LogView {
+  /**
+   * @param {object} widget  blessed-contrib log widget
+   * @param {object} [options]
+   * @param {number} [options.maxLines]      history size
+   * @param {number} [options.flushInterval] ms between repaints
+   * @param {function} [options.viewportHeight] visible row count (used to clamp scrolling)
+   * @param {function} [options.onChange]    called after the widget changed
+   * @param {string}   [options.label]       base label
+   */
+  constructor(widget, options = {}) {
+    this.widget = widget;
+    this.maxLines = options.maxLines || DEFAULT_MAX_LINES;
+    this.flushInterval = options.flushInterval || 100;
+    this.viewportHeight = options.viewportHeight || (() => (typeof widget.height === 'number' ? widget.height - 2 : 10));
+    this.onChange = options.onChange || (() => {});
+    this.baseLabel = options.label || ' logs ';
+
+    this.lines = [];
+    this.follow = true;
+    this.viewOffset = 0;
+    // While paused the visible history is frozen at this length, so incoming
+    // lines cannot shift what the user is reading underneath them.
+    this.frozenLength = null;
+    this.pendingNew = 0;
+    this.dirty = true;
+    this.lastLabel = null;
+
+    this.timer = setInterval(() => this.flush(), this.flushInterval);
+    if (this.timer.unref) this.timer.unref();
+
+    this.flush();
+  }
+
+  get paused() {
+    return !this.follow;
+  }
+
+  /** Append one already formatted (tagged) line. */
+  push(line) {
+    this.lines.push(String(line));
+    if (this.lines.length > this.maxLines) {
+      this.lines.splice(0, this.lines.length - this.maxLines);
+      if (this.viewOffset > 0) this.viewOffset = Math.min(this.viewOffset, this.lines.length);
+    }
+    if (!this.follow) this.pendingNew += 1;
+    this.dirty = true;
+  }
+
+  /** Append many lines at once. */
+  pushAll(lines) {
+    lines.forEach((line) => this.push(line));
+  }
+
+  /** Replace the whole history. */
+  clear() {
+    this.lines = [];
+    this.viewOffset = 0;
+    this.pendingNew = 0;
+    this.follow = true;
+    this.frozenLength = null;
+    this.dirty = true;
+    this.flush();
+  }
+
+  /** Repaint if anything changed. Safe to call on a timer. */
+  flush() {
+    if (!this.dirty) return;
+    this.dirty = false;
+
+    if (this.follow) {
+      this.viewOffset = 0;
+      this.frozenLength = null;
+      this.pendingNew = 0;
+      this.render();
+    }
+    this.updateLabel();
+    this.onChange();
+  }
+
+  /** Number of lines that are part of the current (possibly frozen) view. */
+  visibleLength() {
+    if (this.follow) return this.lines.length;
+    const frozen = this.frozenLength == null ? this.lines.length : this.frozenLength;
+    return Math.min(frozen, this.lines.length);
+  }
+
+  render() {
+    const end = this.visibleLength();
+    const visible = this.viewOffset > 0 ? this.lines.slice(0, Math.max(0, end - this.viewOffset)) : this.lines.slice(0, end);
+    this.widget.setItems(visible);
+  }
+
+  clampOffset(offset) {
+    const viewport = Math.max(1, Number(this.viewportHeight()) || 1);
+    const maxOffset = Math.max(0, this.visibleLength() - viewport);
+    return Math.max(0, Math.min(maxOffset, offset));
+  }
+
+  /** Scroll back `amount` lines (pauses following). */
+  scrollUp(amount = 3) {
+    if (!this.lines.length) return;
+    if (this.follow) this.frozenLength = this.lines.length;
+    this.follow = false;
+    this.viewOffset = this.clampOffset(this.viewOffset + amount);
+    this.repaintNow();
+  }
+
+  /** Scroll towards the tail; reaches the tail -> resume following. */
+  scrollDown(amount = 3) {
+    if (this.follow) return;
+    this.viewOffset = Math.max(0, this.viewOffset - amount);
+    if (this.viewOffset === 0) {
+      this.follow = true;
+      this.frozenLength = null;
+      this.pendingNew = 0;
+    }
+    this.repaintNow();
+  }
+
+  /** Jump to the very top of the history (pauses following). */
+  scrollTop() {
+    if (!this.lines.length) return;
+    if (this.follow) this.frozenLength = this.lines.length;
+    this.follow = false;
+    this.viewOffset = this.clampOffset(this.visibleLength());
+    this.repaintNow();
+  }
+
+  /** Resume following the tail. */
+  followTail() {
+    this.follow = true;
+    this.frozenLength = null;
+    this.viewOffset = 0;
+    this.pendingNew = 0;
+    this.repaintNow();
+  }
+
+  /** Page up/down by roughly one screen. */
+  page(direction) {
+    const viewport = Math.max(1, Number(this.viewportHeight()) || 1);
+    if (direction < 0) this.scrollUp(viewport - 1);
+    else this.scrollDown(viewport - 1);
+  }
+
+  repaintNow() {
+    this.render();
+    this.updateLabel();
+    this.onChange();
+  }
+
+  label() {
+    if (this.paused) {
+      const newLines = this.pendingNew > 0 ? `, ${this.pendingNew} new` : '';
+      return `${this.baseLabel}paused${newLines} \u2014 G to follow`;
+    }
+    return this.baseLabel;
+  }
+
+  updateLabel() {
+    if (!this.widget.setLabel) return;
+    const label = this.label();
+    if (label !== this.lastLabel) {
+      this.lastLabel = label;
+      this.widget.setLabel(label);
+    }
+  }
+
+  destroy() {
+    clearInterval(this.timer);
+  }
+}
+
+module.exports = { LogView, DEFAULT_MAX_LINES };