termdeck-cli 1.0.2 → 2.0.2

package/src/devServer.js

@@ -33,8 +33,10 @@ 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.onExit   (project, {code, signal, stoppedByUs, restart, attempt, max}) => void
    * @param {function} options.openBrowser (url, project) => Promise<void>
+   * @param {number} [options.maxRestarts=3]   auto-restart attempts after a crash
+   * @param {number} [options.restartDelayMs]  pause before an auto-restart
    */
   constructor(options = {}) {
     this.onLog = options.onLog || (() => {});
@@ -50,6 +52,10 @@ class DevServerManager {
     this.servers = new Map();
     this.lastExit = new Map();
     this.autoOpenBrowser = options.autoOpenBrowser !== false;
+    this.autoRestart = options.autoRestart !== false;
+    this.maxRestarts = options.maxRestarts == null ? 3 : options.maxRestarts;
+    this.restartDelayMs = options.restartDelayMs || 1200;
+    this.restartCounts = new Map();
   }
 
   /** @returns {object|undefined} running entry for a project path */
@@ -138,7 +144,29 @@ class DevServerManager {
       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 });
+
+      // The process died on its own (a crash), not because we stopped it:
+      // bring it straight back up, up to maxRestarts times, as long as neither
+      // the global setting nor the project says otherwise.
+      if (!stoppedByUs && this.shouldRestart(project)) {
+        const attempt = this.restartCounts.get(project.path);
+        const detail = signal ? `signal ${signal}` : `exit code ${code}`;
+        this.log(
+          project,
+          `{yellow-fg}dev server exited (${detail}) — auto-restarting ({bold}${attempt}/${this.maxRestarts}{/bold})\u2026{/yellow-fg}`,
+          'system'
+        );
+        this.onExit(project, { code, signal, stoppedByUs, restart: true, attempt, max: this.maxRestarts });
+        const timer = setTimeout(() => {
+          if (this.servers.has(project.path)) return;
+          this.log(project, `{cyan-fg}[termdeck]{/cyan-fg} auto-restarting dev server`, 'system');
+          this.start(project);
+        }, this.restartDelayMs);
+        if (timer.unref) timer.unref();
+        entry.timers.push(timer);
+      } else {
+        this.onExit(project, { code, signal, stoppedByUs });
+      }
     });
 
     this.state(project, { status: 'starting', pid: entry.pid, url: null });
@@ -161,6 +189,25 @@ class DevServerManager {
     return { ok: true, entry };
   }
 
+  /**
+   * True when a crashed dev server should be restarted: auto-restart is
+   * enabled (globally and for this project) and the restart budget remains.
+   */
+  restartAvailable(project) {
+    if (!this.autoRestart) return false;
+    if (project && project.autoRestart === false) return false;
+    if (this.maxRestarts <= 0) return false;
+    return true;
+  }
+
+  shouldRestart(project) {
+    if (!this.restartAvailable(project)) return false;
+    const attempts = (this.restartCounts.get(project.path) || 0) + 1;
+    if (attempts > this.maxRestarts) return false;
+    this.restartCounts.set(project.path, attempts);
+    return true;
+  }
+
   /** Consume raw stream data: split lines, look for the first local URL. */
   handleChunk(entry, chunk, carry, stream) {
     const lines = splitLines(chunk.toString('utf8'), carry);
@@ -180,6 +227,8 @@ class DevServerManager {
     entry.url = url;
     entry.urlGuess = guessed;
     entry.status = 'running';
+    // The server proved healthy — restore the crash-restart budget.
+    this.restartCounts.delete(entry.project.path);
     this.state(entry.project, { status: 'running', pid: entry.pid, url, guessed });
 
     if (!this.autoOpenBrowser || entry.browserOpened) return;

package/src/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 'use strict';
 
 /**
@@ -5,14 +6,25 @@
  *
  * `termdeck`                launch the dashboard (runs setup on first use)
  * `termdeck --setup`        re-run the setup wizard
+ * `termdeck --scan`         scan for projects and merge them into the config
  * `termdeck --reset`        delete the config file and run setup again
  * `termdeck --list`         print the configured projects and exit (no TUI)
+ * `termdeck --demo`         launch with the shipped 14-project sample dataset
  * `termdeck --no-open`      do not auto-open the browser for dev servers
+ * `termdeck --no-update`    skip the automatic background update check
+ * `termdeck --no-auto-restart`  disable dev-server crash recovery for this session
+ *
+ * Every interactive launch silently re-scans the configured root directory and
+ * adds any new project folders it finds (status `pend`, auto-detected port and
+ * package manager) before the dashboard opens. See `autoDiscoverProjects`.
  */
 
 const fs = require('fs');
+const path = require('path');
+
+const { getConfigPath, configExists, loadConfig, loadConfigFromPath, runSetupWizard, autoDiscoverProjects, saveConfig } = require('./config');
 
-const { getConfigPath, configExists, loadConfig, runSetupWizard } = require('./config');
+const DEMO_CONFIG_PATH = path.join(__dirname, '..', 'sample-config.json');
 
 const HELP = `
   termdeck - a terminal dashboard for your local dev projects
@@ -24,27 +36,38 @@ const HELP = `
     -h, --help        Show this help
     -V, --version     Show the version
     -s, --setup       Re-run the interactive setup wizard
+        --scan        Scan for projects and merge them into the config
     -r, --reset       Delete the config file, then run setup again
     -l, --list        Print the configured projects and exit
+        --demo        Launch with the shipped 14-project sample dataset
         --no-open     Do not open a browser when a dev server starts
+        --no-update   Skip the automatic background update check
+        --no-auto-restart  Disable dev-server crash recovery for this session
 
   Keys (inside the dashboard)
     up/down, j/k      Select a project
-    d                 Start \`npm run dev\` and stream its logs into the pane
+    r                 Run \`npm run dev\` for the selected project
     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
+    c/x/o/f/k, a      Open claude / codex / opencode / freebuff / kilocode
+    s                 Change the selected project's status
+    tab / S-tab       Cycle focus: project list -> actions -> output
+    shift+x           Stop the selected project's dev server
     PgUp/PgDn, wheel  Scroll the dev server logs (G to follow the tail again)
+    /                 Search filter (type to filter, enter to commit)
+    1-5               Filter by status: all / live / exp / pend / scrap
     q                 Quit (stops every dev server it started)
 
+  Discovery
+    On every launch termdeck quietly re-scans the configured root and adds any
+    new project folders (with .git or package.json) as pending projects.
+
   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 };
+  const args = { help: false, version: false, setup: false, reset: false, scan: false, list: false, demo: false, noOpen: false, noUpdate: false, noAutoRestart: false };
   for (const raw of argv) {
     const arg = String(raw);
     switch (arg) {
@@ -64,13 +87,25 @@ function parseArgs(argv = []) {
       case '--reset':
         args.reset = true;
         break;
+      case '--scan':
+        args.scan = true;
+        break;
       case '-l':
       case '--list':
         args.list = true;
         break;
+      case '--demo':
+        args.demo = true;
+        break;
       case '--no-open':
         args.noOpen = true;
         break;
+      case '--no-update':
+        args.noUpdate = true;
+        break;
+      case '--no-auto-restart':
+        args.noAutoRestart = true;
+        break;
       default:
         args.unknown = arg;
     }
@@ -128,14 +163,21 @@ async function main(argv = process.argv.slice(2)) {
   }
 
   const existing = args.reset ? null : loadConfig({ onWarn: (message) => process.stderr.write(`${message}\n`) });
-  let config = existing;
+  let config = args.demo
+    ? loadConfigFromPath(DEMO_CONFIG_PATH, { onWarn: (message) => process.stderr.write(`${message}\n`) })
+    : existing;
+
+  if (args.demo && !config) {
+    process.stderr.write(`Could not load the sample dataset at ${DEMO_CONFIG_PATH}.\n`);
+    return 1;
+  }
 
   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 (args.setup || args.scan || args.reset || !config) {
     if (needsTTY('run the setup wizard')) return 1;
     config = await runSetupWizard({ existing });
   }
@@ -152,13 +194,65 @@ async function main(argv = process.argv.slice(2)) {
 
   if (needsTTY('render the dashboard')) return 1;
 
+  // Silent auto-discovery: shallow-scan the configured root on every launch
+  // and fold any new project folders into the config. This is sync and fast
+  // (one readdir + a couple of stats per folder, no git parsing), never
+  // prompts, and never removes anything. The only feedback is a transient
+  // footer toast when the dashboard comes up; failures are swallowed so a
+  // bad root can never block the launch.
+  let bootStatus = null;
+  if (config.root && !config.demoMode) {
+    try {
+      const discovered = autoDiscoverProjects(config);
+      if (discovered.added.length) {
+        config.projects = discovered.projects;
+        const names = discovered.added.map((p) => p.name).join(', ');
+        const count = discovered.added.length;
+        bootStatus = `\u2728 Discovered and added ${count} new project${count === 1 ? '' : 's'}: ${names}`;
+        try {
+          saveConfig(config);
+        } catch (_) {
+          /* the dashboard still runs with the in-memory config */
+        }
+      }
+    } catch (_) {
+      /* discovery must never block the launch */
+    }
+  }
+
   // 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 });
+  const controller = launchDashboard(config, { autoOpen: !args.noOpen, autoRestart: !args.noAutoRestart, bootStatus });
+
+  // Fire-and-forget auto-update: the registry check is capped at 2s and runs
+  // in the background, and any banner is routed through the TUI footer so the
+  // blessed screen is never corrupted by stray terminal output.
+  // eslint-disable-next-line global-require
+  const { runAutoUpdate } = require('./updater');
+  runAutoUpdate({
+    stdout: process.stdout,
+    enabled: !args.noUpdate,
+    onUpdating: (version) => controller.updateStatus(`Found v${version} — updating in the background…`),
+  });
 
   return 0;
 }
 
 module.exports = { main, parseArgs, printProjects, HELP, getConfigPath };
+
+// termdeck's bin entry point maps straight to this file, so running it directly
+// means "run the CLI". When required as a module (tests, embedding), do nothing.
+if (require.main === module) {
+  main(process.argv.slice(2))
+    .then((code) => {
+      // The dashboard keeps the process alive; only surface real exit codes.
+      if (typeof code === 'number' && code !== 0) process.exitCode = code;
+    })
+    .catch((err) => {
+      const message = err && err.message ? err.message : String(err);
+      process.stderr.write(`termdeck: ${message}\n`);
+      process.exitCode = 1;
+    });
+}

package/src/processMonitor.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * processMonitor - real-time per-project process stats.
+ *
+ * Two cheap primitives (find the PID behind a port, then read CPU/memory for
+ * that PID) feed a per-project polling interval. The port lookup shells out to
+ * `lsof` (macOS/Linux) or `netstat` (Windows); stats come from the `pidusage`
+ * package. Every failure path is silent: a missing process, a dead PID or a
+ * blocked command yields `null` / a `running: false` report, never a throw, so
+ * the TUI can call this on every render tick without fear.
+ *
+ * All command runners are injectable (`{ spawn, usage }`) so the unit tests
+ * cover every branch without a real `lsof`/`netstat` or a live process.
+ */
+
+const crossSpawn = require('cross-spawn');
+const pidusage = require('pidusage');
+
+const MONITOR_INTERVAL_MS = 2000;
+
+/** per-key interval handles + in-flight guard so ticks never overlap. */
+const intervals = new Map();
+const inFlight = new Set();
+
+function formatMemory(bytes) {
+  if (typeof bytes !== 'number' || !Number.isFinite(bytes)) return null;
+  return `${(bytes / 1048576).toFixed(1)} MB`;
+}
+
+function formatCpu(percent) {
+  if (typeof percent !== 'number' || !Number.isFinite(percent)) return null;
+  return `${percent.toFixed(1)}%`;
+}
+
+/**
+ * Find the PID listening on `port`, or null when none / the command fails.
+ *
+ *   macOS/Linux: `lsof -ti :<port>`
+ *   Windows:     parse the rows of `netstat -ano` ourselves (avoids a locale-
+ *                dependent `findstr` pipe); the PID is the last token of rows
+ *                whose local address carries `:<port>`.
+ */
+function getPIDByPort(port, { spawn = crossSpawn } = {}) {
+  if (!port || !Number.isFinite(Number(port))) return null;
+  try {
+    if (process.platform === 'win32') {
+      const result = spawn.sync('netstat', ['-ano'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 4000,
+      });
+      if (!result || result.error || result.status !== 0) return null;
+      let firstPid = null;
+      for (const rawLine of String(result.stdout).split(/\r?\n/)) {
+        const tokens = rawLine.trim().split(/\s+/);
+        if (tokens.length < 2) continue;
+        const pidToken = tokens[tokens.length - 1];
+        if (!/^\d+$/.test(pidToken)) continue;
+        if (!tokens.slice(0, -1).some((token) => token.endsWith(`:${port}`) || token === `${port}`)) continue;
+        if (firstPid == null) firstPid = Number(pidToken);
+      }
+      return firstPid;
+    }
+
+    const result = spawn.sync('lsof', ['-ti', `:${port}`], {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 4000,
+    });
+    if (!result || result.error || result.status !== 0) return null;
+    const first = String(result.stdout).trim().split(/\r?\n/)[0];
+    const pid = Number(first);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * CPU + memory for a PID, formatted for the UI, or null when the PID is
+ * invalid/dead/blocked. Never rejects (the caller in the TUI awaits this).
+ */
+async function getProcessStats(pid, { usage = pidusage } = {}) {
+  if (!pid || !Number.isInteger(Number(pid)) || Number(pid) <= 0) return null;
+  try {
+    const stats = await usage(pid);
+    if (!stats || typeof stats.memory !== 'number') return null;
+    const cpu = formatCpu(stats.cpu);
+    const memory = formatMemory(stats.memory);
+    if (!cpu || !memory) return null;
+    return { pid: Number(pid), memory, cpu };
+  } catch (_) {
+    return null;
+  }
+}
+
+function monitorKey(project) {
+  return project && (project.path || project.id || project.name);
+}
+
+/**
+ * Start polling `project` every `intervalMs` for its PID/CPU/memory, passing
+ * the report to `callback`. Returns a stop function. Silently degrades to
+ * `{ running:false }` when the port has no process.
+ */
+function startMonitoring(project, callback, options = {}) {
+  const key = monitorKey(project);
+  if (!key || typeof callback !== 'function') return null;
+  const getPID = options.getPID || getPIDByPort;
+  const getStats = options.getStats || getProcessStats;
+  const intervalMs = options.intervalMs != null ? options.intervalMs : MONITOR_INTERVAL_MS;
+  const onError = options.onError || (() => {});
+
+  stopMonitoring(key);
+
+  const tick = async () => {
+    if (inFlight.has(key)) return;
+    inFlight.add(key);
+    try {
+      const pid = await getPID(project.port);
+      if (pid == null) {
+        callback({ running: false, pid: null, memory: null, cpu: null });
+        return;
+      }
+      const stats = (await getStats(pid)) || {};
+      callback({ running: true, pid, memory: stats.memory || null, cpu: stats.cpu || null });
+    } catch (err) {
+      onError(err);
+    } finally {
+      inFlight.delete(key);
+    }
+  };
+
+  const timer = setInterval(tick, Math.max(50, intervalMs));
+  if (timer.unref) timer.unref();
+  intervals.set(key, timer);
+  tick();
+  return () => stopMonitoring(key);
+}
+
+/** Stop monitoring a project (pass a project object or its key). */
+function stopMonitoring(project) {
+  const key = monitorKey(project) || project;
+  const timer = intervals.get(key);
+  if (timer) {
+    clearInterval(timer);
+    intervals.delete(key);
+  }
+  inFlight.delete(key);
+}
+
+function stopAllMonitoring() {
+  for (const key of [...intervals.keys()]) stopMonitoring(key);
+  intervals.clear();
+  inFlight.clear();
+}
+
+module.exports = {
+  MONITOR_INTERVAL_MS,
+  formatMemory,
+  formatCpu,
+  getPIDByPort,
+  getProcessStats,
+  startMonitoring,
+  stopMonitoring,
+  stopAllMonitoring,
+};

package/src/projectManager.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * projectManager - scans project folders and reads git metadata.
+ *
+ * Git reads shell out to `git` through cross-spawn and are cached per project
+ * for GIT_CACHE_TTL_MS, so a 14-project dashboard does not hammer the disk on
+ * every 2s render tick. Nothing here ever throws: every failure degrades to
+ * `null` / empty values and the UI renders an em-dash for the field.
+ *
+ * The git runner is injectable (`git` option) so unit tests can feed fake
+ * output without needing a real repository or the git binary.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { timeAgo } = require('./util');
+
+const GIT_CACHE_TTL_MS = 30000;
+const GIT_TIMEOUT_MS = 4000;
+
+/** projectPath -> { fetchedAt, info }. Private; use clearGitCache() in tests. */
+const cache = new Map();
+
+/** Default git runner: `git <args>` in `cwd`, trimmed stdout or null. */
+function runGit(args, cwd) {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  if (result.error || result.signal || result.status !== 0) return null;
+  return result.stdout.trim();
+}
+
+/** Test hook: drop every cached git snapshot. */
+function clearGitCache() {
+  cache.clear();
+}
+
+/** True when `cwd` sits inside a git working tree. */
+function isGitRepo(projectPath, { git = runGit } = {}) {
+  return git(['rev-parse', '--is-inside-work-tree'], projectPath) === 'true';
+}
+
+/**
+ * Turn `git status --porcelain` into a (+added, -removed) pair. Counts files,
+ * not diff lines: `??`/`A`/`M` lines are additions, `D`/`R` are removals, and
+ * a differently-staged file (e.g. `AM typo.js`) still counts once.
+ */
+function parseDirtyState(porcelain) {
+  if (!porcelain || typeof porcelain !== 'string') return { added: 0, removed: 0 };
+
+  let added = 0;
+  let removed = 0;
+  for (const raw of porcelain.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith('??') || /^[AM]/.test(line)) added += 1;
+    else if (/^[DR]/.test(line)) removed += 1;
+    // Anything else (e.g. `U`) counts as neither side.
+  }
+  return { added, removed };
+}
+
+/**
+ * Read branch + last commit + dirty state from a real repo.
+ * Returns zero-ish values (nulls / empty dirty) when git is unavailable or the
+ * directory is not a repository, so callers never have to handle failure.
+ */
+function readGitInfo(projectPath, { git = runGit } = {}) {
+  if (!isGitRepo(projectPath, { git })) {
+    return { branch: null, commitHash: null, commitMsg: null, lastCommitAt: null, dirty: { added: 0, removed: 0 } };
+  }
+
+  const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], projectPath);
+  const commitHash = git(['rev-parse', '--short', 'HEAD'], projectPath);
+  const commitMsg = git(['log', '-1', '--pretty=%s'], projectPath);
+  const lastCommitAt = git(['log', '-1', '--format=%cI'], projectPath) || null;
+  const porcelain = git(['status', '--porcelain'], projectPath);
+
+  return {
+    branch,
+    commitHash,
+    commitMsg,
+    lastCommitAt,
+    dirty: parseDirtyState(porcelain),
+  };
+}
+
+/**
+ * Cached git info for a project. Re-reads only when the cache entry is older
+ * than GIT_CACHE_TTL_MS or `force` is set. Returns the same shape as
+ * readGitInfo.
+ */
+function getGitInfo(projectPath, { force = false, git = null } = {}) {
+  const now = Date.now();
+  const hit = force ? null : cache.get(projectPath);
+  if (hit && now - hit.fetchedAt < GIT_CACHE_TTL_MS) return hit.info;
+
+  const info = readGitInfo(projectPath, git ? { git } : {});
+  cache.set(projectPath, { fetchedAt: now, info });
+  return info;
+}
+
+/**
+ * "12m ago" style relative activity time for a project, derived from its last
+ * commit. Falls back to `null` (dashboard shows an em-dash) outside a repo.
+ */
+function getLastActivity(projectPath, { git = null } = {}) {
+  const info = getGitInfo(projectPath, git ? { git } : {});
+  return timeAgo(info.lastCommitAt) || null;
+}
+
+/**
+ * Immediate sub-folders of `root` that look like projects: directories that
+ * are not hidden and not on the ignore list. Returns sorted {name, path}.
+ */
+function scanProjects(root, { ignored = new Set() } = {}) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch (_) {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => {
+      if (entry.name.startsWith('.')) return false;
+      if (ignored.has(entry.name)) return false;
+      if (entry.isDirectory()) return true;
+      if (entry.isSymbolicLink()) {
+        try {
+          return fs.statSync(path.join(root, entry.name)).isDirectory();
+        } catch (_) {
+          return false;
+        }
+      }
+      return false;
+    })
+    .map((entry) => ({ name: entry.name, path: path.join(root, entry.name) }))
+    .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+}
+
+module.exports = {
+  GIT_CACHE_TTL_MS,
+  GIT_TIMEOUT_MS,
+  runGit,
+  clearGitCache,
+  isGitRepo,
+  parseDirtyState,
+  readGitInfo,
+  getGitInfo,
+  getLastActivity,
+  scanProjects,
+};