metwatch 0.1.0

package/src/cli/args.ts

@@ -0,0 +1,115 @@
+// ---------------------------------------------------------------------------
+// CLI argument router
+//
+// Dispatches to the appropriate command handler based on the first positional
+// argument in process.argv. Uses the built-in `parseArgs` from 'util' for
+// top-level flags; each subcommand parses its own flags independently.
+//
+// Subcommand dispatch table:
+//   (none) / monitor  → open TUI, no managed processes
+//   start <file>      → launch managed process + open TUI
+//   list              → print managed process table
+//   logs <name>       → print / tail buffered logs
+//   stop <name|all>   → stop managed process(es)
+//   help [cmd]        → print help
+// ---------------------------------------------------------------------------
+
+import { parseArgs } from 'util';
+import {
+  HELP_ROOT,
+  HELP_START,
+  HELP_LIST,
+  HELP_LOGS,
+  HELP_STOP,
+} from './help.ts';
+import { runMonitor }  from './commands/monitor.ts';
+import { runStart }    from './commands/start.ts';
+import { runList }     from './commands/list.ts';
+import { runLogs }     from './commands/logs.ts';
+import { runStop }     from './commands/stop.ts';
+
+// Top-level flags only (--help / --version).
+// Subcommand flags are parsed inside each command module.
+const { values: topFlags, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    help:    { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+  },
+  allowPositionals: true,
+  strict: false,
+});
+
+if (topFlags.version) {
+  // Version is injected at publish time; fall back to package.json read.
+  try {
+    const { readFileSync } = await import('fs');
+    const { resolve }      = await import('path');
+    const pkg = JSON.parse(
+      readFileSync(resolve(import.meta.dir, '../../package.json'), 'utf-8')
+    ) as { version?: string };
+    console.log(`metwatch ${pkg.version ?? '0.0.0'}`);
+  } catch {
+    console.log('metwatch 0.0.0');
+  }
+  process.exit(0);
+}
+
+const [subcommand, ...subArgs] = positionals;
+
+if (topFlags.help && !subcommand) {
+  console.log(HELP_ROOT);
+  process.exit(0);
+}
+
+if (topFlags.help && subcommand) {
+  const helpMap: Record<string, string> = {
+    start:   HELP_START,
+    list:    HELP_LIST,
+    logs:    HELP_LOGS,
+    stop:    HELP_STOP,
+    monitor: 'Usage: mw monitor\n\nOpen the TUI dashboard in read-only (observe) mode.\n',
+  };
+  console.log(helpMap[subcommand] ?? HELP_ROOT);
+  process.exit(0);
+}
+
+switch (subcommand) {
+  case undefined:
+  case 'monitor':
+    await runMonitor();
+    break;
+
+  case 'start':
+    await runStart(subArgs);
+    break;
+
+  case 'list':
+    runList();
+    break;
+
+  case 'logs':
+    runLogs(subArgs);
+    break;
+
+  case 'stop':
+    runStop(subArgs);
+    break;
+
+  case 'help': {
+    const helpMap: Record<string, string> = {
+      start:   HELP_START,
+      list:    HELP_LIST,
+      logs:    HELP_LOGS,
+      stop:    HELP_STOP,
+    };
+    const target = subArgs[0];
+    console.log(target && helpMap[target] ? helpMap[target] : HELP_ROOT);
+    break;
+  }
+
+  default:
+    console.error(`Unknown command: "${subcommand}"\n`);
+    console.log(HELP_ROOT);
+    process.exit(1);
+}

package/src/cli/commands/list.ts

@@ -0,0 +1,77 @@
+// ---------------------------------------------------------------------------
+// CLI command: list
+//
+// Prints the current managed process states to stdout as a table.
+// Does NOT open the TUI — intended for scripting / quick checks.
+//
+// If no managed processes are configured or running, prints a notice.
+// ---------------------------------------------------------------------------
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import {
+  DEFAULT_CONFIG,
+  type MetWatchConfig,
+  type ResolvedConfig,
+} from '../../types/config.types.ts';
+import { formatUptime } from '../../utils/formatters.ts';
+
+function loadConfig(): ResolvedConfig {
+  const p = resolve(process.cwd(), 'metwatch.config.json');
+  if (!existsSync(p)) return { ...DEFAULT_CONFIG };
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf-8')) as Partial<MetWatchConfig>;
+    return {
+      watchedProcesses: parsed.watchedProcesses ?? DEFAULT_CONFIG.watchedProcesses,
+      managedProcesses: parsed.managedProcesses ?? DEFAULT_CONFIG.managedProcesses,
+      refreshInterval:  Math.max(250, parsed.refreshInterval ?? DEFAULT_CONFIG.refreshInterval),
+      maxProcesses:     parsed.maxProcesses     ?? DEFAULT_CONFIG.maxProcesses,
+      logScrollback:    parsed.logScrollback    ?? DEFAULT_CONFIG.logScrollback,
+      panels:           { ...DEFAULT_CONFIG.panels, ...(parsed.panels ?? {}) },
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export function runList(): void {
+  const config = loadConfig();
+  const defs   = config.managedProcesses ?? [];
+
+  if (defs.length === 0) {
+    console.log('No managed processes defined in metwatch.config.json.');
+    console.log('Use `mw start <file>` to launch a managed process.');
+    return;
+  }
+
+  const COL = { name: 20, status: 12, pid: 8, restarts: 9, cmd: 30 };
+  const header = [
+    'NAME'.padEnd(COL.name),
+    'STATUS'.padEnd(COL.status),
+    'PID'.padEnd(COL.pid),
+    'RESTARTS'.padEnd(COL.restarts),
+    'COMMAND'.padEnd(COL.cmd),
+  ].join('  ');
+
+  const sep = '-'.repeat(header.length);
+  console.log(header);
+  console.log(sep);
+
+  for (const def of defs) {
+    const row = [
+      def.name.padEnd(COL.name),
+      'stopped'.padEnd(COL.status),      // static — no live state here
+      '-'.padEnd(COL.pid),
+      '0'.padEnd(COL.restarts),
+      `${def.command} ${def.args.join(' ')}`.slice(0, COL.cmd).padEnd(COL.cmd),
+    ].join('  ');
+    console.log(row);
+  }
+
+  console.log();
+  console.log('(Static view from config. Open the TUI with `mw` to see live states.)');
+}
+
+// Suppress unused import warning for formatUptime — it will be used once
+// live IPC is wired in Phase 3. Keep it here so the import stays auditable.
+void formatUptime;

package/src/cli/commands/logs.ts

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// CLI command: logs
+//
+// Prints buffered logs for a managed process to stdout.
+// With --follow / -f, tails live output until Ctrl+C.
+//
+// In Phase 2 this reads from the in-process LogManager (same Bun process as
+// the TUI). Phase 3 will replace this with a socket-based IPC read.
+//
+// Usage:
+//   mw logs <name> [--follow] [--lines <n>]
+// ---------------------------------------------------------------------------
+
+import { HELP_LOGS } from '../help.ts';
+
+interface LogsOptions {
+  name:   string;
+  follow: boolean;
+  lines:  number;
+}
+
+export function parseLogsArgs(argv: string[]): LogsOptions | null {
+  const [name, ...rest] = argv;
+  if (!name) {
+    console.error('Error: missing process name.\n');
+    console.log(HELP_LOGS);
+    return null;
+  }
+
+  let follow = false;
+  let lines  = 50;
+
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--follow' || arg === '-f') {
+      follow = true;
+    } else if (arg === '--lines') {
+      const n = parseInt(rest[++i] ?? '', 10);
+      if (isNaN(n) || n < 1) {
+        console.error('Error: --lines must be a positive integer.');
+        return null;
+      }
+      lines = n;
+    }
+  }
+
+  return { name, follow, lines };
+}
+
+/**
+ * `mw logs` launched WITHOUT the TUI — reads from a static snapshot.
+ *
+ * In the current architecture the log buffer only exists inside the TUI
+ * process. Until Phase 3 IPC is implemented we print a helpful message
+ * directing the user to the TUI.
+ */
+export function runLogs(argv: string[]): void {
+  const opts = parseLogsArgs(argv);
+  if (!opts) return;
+
+  // Phase 3 will establish a socket connection to the running TUI process
+  // and stream log lines from its LogManager over IPC. For now we inform
+  // the user that live logs are visible inside the TUI itself.
+  console.log(`[MetWatch] Logs for "${opts.name}" are available in the TUI dashboard.`);
+  console.log('  Open the dashboard:  mw');
+  console.log('  Then press [l] to focus the Logs panel and scroll with ↑ / ↓.');
+  console.log();
+  console.log('Phase 3 will add out-of-process `mw logs` support via socket IPC.');
+}

package/src/cli/commands/monitor.ts

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// CLI command: monitor
+//
+// Opens the MetWatch TUI with no managed processes — pure observation mode.
+// This is also the default when `mw` is invoked with no subcommand.
+// ---------------------------------------------------------------------------
+
+import { main } from '../../../index.ts';
+
+export async function runMonitor(): Promise<void> {
+  await main([]);
+}

package/src/cli/commands/start.ts

@@ -0,0 +1,124 @@
+// ---------------------------------------------------------------------------
+// CLI command: start
+//
+// Parses CLI flags and launches one managed process, then opens the TUI.
+//
+// Usage:
+//   mw start <file> [options]
+//
+// Runtime inference:
+//   .ts / .tsx           → bun
+//   .js / .mjs / .cjs    → node
+//   .py                  → python
+//   other                → execute directly (no runtime wrapper)
+// ---------------------------------------------------------------------------
+
+import { basename, extname, resolve } from 'path';
+import { HELP_START } from '../help.ts';
+import type { ManagedProcessDef } from '../../types/managed-process.types.ts';
+import { main } from '../../../index.ts';
+
+function inferRuntime(file: string): { command: string; args: string[] } {
+  const ext = extname(file).toLowerCase();
+  switch (ext) {
+    case '.ts':
+    case '.tsx':
+      return { command: 'bun', args: ['run', file] };
+    case '.js':
+    case '.mjs':
+    case '.cjs':
+      return { command: 'node', args: [file] };
+    case '.py':
+      return { command: 'python', args: [file] };
+    default:
+      return { command: file, args: [] };
+  }
+}
+
+interface StartOptions {
+  file:       string;
+  name:       string;
+  runtime:    string | null;
+  autoRestart: boolean;
+  cwd:        string;
+  env:        Record<string, string>;
+}
+
+function parseStartArgs(argv: string[]): StartOptions | null {
+  const [file, ...rest] = argv;
+
+  if (!file || file.startsWith('-')) {
+    console.error('Error: missing <file> argument.\n');
+    console.log(HELP_START);
+    return null;
+  }
+
+  const absFile = resolve(process.cwd(), file);
+  let name        = basename(file, extname(file));
+  let runtime: string | null = null;
+  let autoRestart = true;
+  let cwd         = process.cwd();
+  const env: Record<string, string> = {};
+
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--name') {
+      name = rest[++i] ?? name;
+    } else if (arg === '--runtime') {
+      runtime = rest[++i] ?? null;
+    } else if (arg === '--no-restart') {
+      autoRestart = false;
+    } else if (arg === '--cwd') {
+      cwd = resolve(rest[++i] ?? process.cwd());
+    } else if (arg === '--env') {
+      const pair = rest[++i] ?? '';
+      const eqIdx = pair.indexOf('=');
+      if (eqIdx > 0) {
+        env[pair.slice(0, eqIdx)] = pair.slice(eqIdx + 1);
+      } else {
+        console.error(`Error: --env value must be KEY=VALUE, got: ${pair}`);
+        return null;
+      }
+    } else if (arg === '-h' || arg === '--help') {
+      console.log(HELP_START);
+      process.exit(0);
+    } else {
+      console.error(`Error: unknown option "${arg}"\n`);
+      console.log(HELP_START);
+      return null;
+    }
+  }
+
+  return { file: absFile, name, runtime, autoRestart, cwd, env };
+}
+
+export async function runStart(argv: string[]): Promise<void> {
+  const opts = parseStartArgs(argv);
+  if (!opts) {
+    process.exit(1);
+  }
+
+  const inferred = inferRuntime(opts.file);
+
+  let command: string;
+  let args: string[];
+
+  if (opts.runtime) {
+    command = opts.runtime;
+    args    = [opts.file];
+  } else {
+    command = inferred.command;
+    args    = inferred.args;
+  }
+
+  const def: ManagedProcessDef = {
+    name:        opts.name,
+    command,
+    args,
+    autoRestart: opts.autoRestart,
+    cwd:         opts.cwd,
+    env:         Object.keys(opts.env).length > 0 ? opts.env : undefined,
+  };
+
+  await main([def]);
+}

package/src/cli/commands/stop.ts

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// CLI command: stop
+//
+// Gracefully stops a named managed process or all of them.
+//
+// In Phase 2 stop runs inside the same process as the TUI — it is wired
+// through the event bus. Phase 3 will add out-of-process IPC.
+//
+// Usage:
+//   mw stop <name|all>
+// ---------------------------------------------------------------------------
+
+import { HELP_STOP } from '../help.ts';
+
+export function runStop(argv: string[]): void {
+  const [target] = argv;
+
+  if (!target) {
+    console.error('Error: missing target name.\n');
+    console.log(HELP_STOP);
+    process.exit(1);
+  }
+
+  // Phase 3: emit over IPC socket to the running TUI process.
+  // For now we inform the user to use the in-TUI keybindings.
+  if (target === 'all') {
+    console.log('[MetWatch] To stop all managed processes, press q in the TUI (graceful shutdown).');
+  } else {
+    console.log(`[MetWatch] To stop "${target}", select it in the TUI and press [s].`);
+  }
+  console.log();
+  console.log('Phase 3 will add out-of-process `mw stop` support via socket IPC.');
+}

package/src/cli/help.ts

@@ -0,0 +1,96 @@
+// ---------------------------------------------------------------------------
+// CLI Help Text
+// ---------------------------------------------------------------------------
+
+export const HELP_ROOT = `\
+MetWatch — terminal process monitoring & management tool
+
+Usage:
+  mw [command] [options]
+
+Commands:
+  monitor                Open the TUI dashboard (no managed processes)
+  start <file>           Run a script as a managed process and open the TUI
+  list                   Print managed process states to stdout
+  logs <name>            Print buffered logs for a managed process
+  stop <name|all>        Stop a managed process (or all)
+  help [command]         Show help
+
+Options:
+  -h, --help             Show this help message
+  -v, --version          Print version
+
+Examples:
+  mw                         Open dashboard (same as "mw monitor")
+  mw start server.ts         Run server.ts with Bun and watch it in the TUI
+  mw start app.py --name api Run app.py with Python, label it "api"
+  mw start ./bin --no-restart  Run without auto-restart
+  mw list                    Show all managed process states
+  mw logs api                Show buffered logs for "api"
+  mw logs api --follow       Tail live logs for "api"
+  mw stop api                Stop "api"
+  mw stop all                Stop all managed processes
+`;
+
+export const HELP_START = `\
+Usage:
+  mw start <file> [options]
+
+Launch a script as a MetWatch-managed process, then open the TUI dashboard.
+The runtime is inferred from the file extension unless --runtime is provided.
+
+  .ts / .tsx        → bun
+  .js / .mjs / .cjs → node
+  .py               → python
+  other             → executed directly
+
+Options:
+  --name <label>      Display name in the TUI  (default: basename of <file>)
+  --runtime <cmd>     Override the inferred runtime executable
+  --no-restart        Disable auto-restart on crash
+  --cwd <dir>         Working directory for the child process
+  --env KEY=VALUE     Set an environment variable (repeatable)
+
+Examples:
+  mw start server.ts
+  mw start app.py --name api --no-restart
+  mw start worker.js --cwd ./workers --env PORT=4000
+`;
+
+export const HELP_LIST = `\
+Usage:
+  mw list
+
+Print the current state of all managed processes to stdout.
+Opens the TUI first if not already running (reads live state from the session).
+
+Columns: NAME  PID  STATUS  RESTARTS  UPTIME
+`;
+
+export const HELP_LOGS = `\
+Usage:
+  mw logs <name> [options]
+
+Print buffered stdout/stderr for a managed process.
+
+Options:
+  --follow, -f    Tail live output (Ctrl+C to exit)
+  --lines <n>     Number of lines to show  (default: 50)
+
+Examples:
+  mw logs api
+  mw logs api --follow
+  mw logs api --lines 100
+`;
+
+export const HELP_STOP = `\
+Usage:
+  mw stop <name|all>
+
+Gracefully stop a managed process (SIGTERM).
+Use "all" to stop every managed process.
+
+Examples:
+  mw stop api
+  mw stop all
+`;

package/src/core/event-bus.ts

@@ -0,0 +1,113 @@
+// ---------------------------------------------------------------------------
+// Event Bus
+//
+// A strongly-typed, singleton event bus built on Node's EventEmitter.
+// All inter-module communication in MetWatch MUST go through this bus —
+// never import one module directly into another to trigger side-effects.
+//
+// Design rationale:
+//   - Generic type parameter on emit/on enforces payload shapes at compile time.
+//   - Singleton export means any module can import { bus } without wiring.
+//   - The EventMap type is the canonical catalog of all events in the system.
+//     Adding a new event = add it here first, then implement producer + consumer.
+//
+// Event naming convention:  <domain>:<noun>:<verb>
+//   e.g.  metrics:cpu:updated  |  process:kill:requested  |  ui:view:toggled
+// ---------------------------------------------------------------------------
+
+import { EventEmitter } from 'events';
+import type {
+  CpuMetrics,
+  MemoryMetrics,
+  DiskMetrics,
+  NetworkMetrics,
+  RuntimeMetrics,
+} from '../types/metrics.types.ts';
+import type { ProcessList, ProcessViewMode } from '../types/process.types.ts';
+
+// ── Event catalog ─────────────────────────────────────────────────────────────
+// Every event name and its payload type lives here. The bus is a closed system:
+// if the event isn't in this map, it doesn't exist in MetWatch.
+
+export interface EventMap {
+  // Metrics
+  'metrics:cpu:updated':     CpuMetrics;
+  'metrics:memory:updated':  MemoryMetrics;
+  'metrics:disk:updated':    DiskMetrics;
+  'metrics:network:updated': NetworkMetrics;
+  'metrics:runtime:updated': RuntimeMetrics;
+
+  // System processes (observed, not owned)
+  'processes:updated':     ProcessList;
+  'process:kill:requested': { pid: number };
+  'process:kill:result':   { pid: number; success: boolean; error?: string };
+
+  // Managed processes (launched and owned by MetWatch)
+  'managed:started':           { id: string; pid: number };
+  'managed:stopped':           { id: string };
+  'managed:crashed':           { id: string; exitCode: number | null; restarts: number };
+  'managed:restarted':         { id: string; pid: number; restarts: number };
+  'managed:restart:requested': { id: string };
+  'managed:stop:requested':    { id: string };
+
+  // Log streaming (stdout/stderr from managed processes)
+  'log:line':           { id: string; stream: 'stdout' | 'stderr'; line: string; timestamp: number };
+  'log:stream:started': { id: string; pid: number };
+  'log:stream:stopped': { id: string; exitCode: number | null };
+
+  // UI
+  'ui:view:toggled':   ProcessViewMode;
+  'ui:panel:toggled':  { panel: PanelName; visible: boolean };
+  'ui:quit':           undefined;
+
+  // Lifecycle
+  'app:error': { source: string; error: Error };
+  'app:ready': undefined;
+}
+
+/** All panel names that can be toggled on/off */
+export type PanelName = 'cpu' | 'memory' | 'disk' | 'network' | 'runtime' | 'processes' | 'logs';
+
+export type EventName = keyof EventMap;
+
+// ── Typed EventEmitter wrapper ────────────────────────────────────────────────
+
+class TypedEventBus {
+  private readonly emitter = new EventEmitter();
+
+  constructor() {
+    // Increase limit to accommodate all widget subscriptions without warnings.
+    this.emitter.setMaxListeners(100);
+  }
+
+  emit<K extends EventName>(event: K, payload: EventMap[K]): void {
+    this.emitter.emit(event, payload);
+  }
+
+  on<K extends EventName>(event: K, handler: (payload: EventMap[K]) => void): () => void {
+    this.emitter.on(event, handler);
+    // Return unsubscribe function — always clean up in widget destroy()
+    return () => this.emitter.off(event, handler);
+  }
+
+  once<K extends EventName>(event: K, handler: (payload: EventMap[K]) => void): void {
+    this.emitter.once(event, handler);
+  }
+
+  off<K extends EventName>(event: K, handler: (payload: EventMap[K]) => void): void {
+    this.emitter.off(event, handler);
+  }
+
+  /** Remove all listeners for a given event. Use sparingly. */
+  removeAllListeners<K extends EventName>(event?: K): void {
+    this.emitter.removeAllListeners(event);
+  }
+
+  listenerCount<K extends EventName>(event: K): number {
+    return this.emitter.listenerCount(event);
+  }
+}
+
+// ── Singleton ─────────────────────────────────────────────────────────────────
+// One bus for the entire application lifetime.
+export const bus = new TypedEventBus();