go-dev 0.6.0 → 0.8.0

package/README.md

@@ -18,6 +18,7 @@ In complex monorepos, starting your development environment can be a chore. You
     *   **`docker` services:** Manage Docker containers via `docker compose`. Automatically checks container status and performs health checks.
 *   **Mode-Aware Dependencies:** Services can depend on other services running in specific modes (e.g., your `api` dev mode might depend on `frontend` in `serve` mode).
 *   **Preset-Driven Startup:** Define different "presets" (e.g., `api`, `frontend`, `all`) to easily spin up specific combinations of services tailored to your current development focus.
+*   **Interactive Selection (no preset required):** Run `go-dev` with no preset to open a full-screen TUI where you can pick a preset *or* compose a custom selection — toggle services and choose a mode per service — and optionally save that selection as a new preset. Presets become a convenience, not a requirement.
 *   **Automatic Dependency Resolution:** `go-dev` builds an intelligent execution graph, starting services in the correct topological order.
 *   **Centralized Logging:** Prefixes logs from each service, making it easy to follow activity from multiple concurrent processes.
 *   **Automatic Process Exit:** The `go-dev` process will automatically exit when all primary services (those directly listed in the chosen preset) exit cleanly (with a success code of `0`).
@@ -48,11 +49,27 @@ yarn add --dev go-dev
 Once installed, simply run `go-dev` with the name of the preset you want to start:
 
 ```bash
-npx go-dev <preset_name> [-c|--config <path>]
+npx go-dev [preset_name] [-c|--config <path>] [-i|--interactive]
 ```
 
-*   `<preset_name>`: The name of the preset defined in your `go-dev.yml` (e.g., `api`, `frontend`, `all`).
+*   `[preset_name]`: (Optional) The name of the preset defined in your `go-dev.yml` (e.g., `api`, `frontend`, `all`). When omitted, `go-dev` opens the interactive selector (see below).
 *   `-c <path>` / `--config <path>` (also `-c=<path>` / `--config=<path>`): (Optional) Path to your `go-dev.yml` file. When omitted, `go-dev` auto-discovers a config file in the current directory (see the **Configuration** section below for the lookup order). The flag must appear before any `--args-for` block.
+*   `-i` / `--interactive`: (Optional) Force the interactive selector even when a preset is given, pre-populating it from that preset so you can tweak the selection before starting.
+
+### Interactive selection
+
+Running `go-dev` **without a preset** (in an interactive terminal) opens a full-screen TUI with two tabs:
+
+*   **Services & Modes** — toggle services with <kbd>Space</kbd>, cycle the mode of a hybrid service with <kbd>m</kbd>, then press <kbd>Enter</kbd>. You'll be offered to save the selection as a new preset (written back to your config, preserving comments).
+*   **Presets** — pick an existing preset and press <kbd>Enter</kbd> to start it.
+
+A panel at the bottom shows the **resolved selection** split into sections — *primary services* and *dependencies* (each with its mode) — so you can see exactly what will start. On the **Services & Modes** tab it reflects the services you've checked; on the **Presets** tab, the highlighted preset.
+
+If the same service is pulled in under **two different modes** (e.g. `keplero:build` as a primary while another service depends on `keplero:dev`), the panel flags a *mode conflict*: go-dev runs one instance per service, so the losing mode is dropped and that dependency goes unmet. The same warning is printed at startup, so it's visible even when launching a preset by name without the TUI.
+
+Navigate tabs with <kbd>←</kbd>/<kbd>→</kbd>, move with <kbd>↑</kbd>/<kbd>↓</kbd>, and quit with <kbd>q</kbd>. When stdin is not a TTY (e.g. CI) and no preset is given, `go-dev` exits with an error instead of opening the TUI.
+
+The selector **remembers your last launched selection per config file** and restores it the next time you open it. This state is stored in your user state directory (`$XDG_STATE_HOME/go-dev/` on Linux/macOS, `%LOCALAPPDATA%\go-dev\` on Windows), keyed by the config file's canonical absolute path — **never written into your repo**.
 
 **Passing Arguments to Service Commands:**
 

package/bin/go-dev

@@ -1,19 +1,5 @@
 #!/usr/bin/env node
 
-const Orchestrator = require('../src/orchestrator');
-const path = require('path');
+const { run } = require('../src/run');
 
-const { parseCliArgs } = require('../src/cli-args');
-
-const { presetName, configPath, logLevel, remaining } = parseCliArgs(process.argv.slice(2));
-
-if (!presetName) {
-    console.error('Error: Please specify a preset to run. Usage: go-dev <preset_name> [-c|--config <path>] [-l|--log-level <level>] [--args-for ...]');
-    process.exit(1);
-}
-
-process.argv = [process.argv[0], process.argv[1], presetName, ...remaining];
-
-const orchestrator = new Orchestrator(configPath, { logLevel });
-
-orchestrator.start(presetName);
+run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-dev",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "main": "src/index.js",
   "bin": {
     "go-dev": "bin/go-dev"
@@ -17,6 +17,7 @@
   "description": "",
   "dependencies": {
     "joi": "^17.13.3",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "terminal-kit": "^3.1.2"
   }
 }

package/spike/README.md

@@ -0,0 +1,77 @@
+# Spike TUI — terminal-kit vs OpenTUI
+
+Prototipo comparativo per la TUI full-screen unificata di go-dev (schermata di
+selezione a tab → viewer log streaming). Obiettivo: scegliere la libreria di
+base sui **fatti**, non sulle opinioni.
+
+Entrambi gli spike implementano le **stesse due schermate**, alimentate dalla
+**stessa** sorgente di log fasulla ad alto volume (`shared/fake-log-source.js`,
+~350 righe/s, mix servizi + libreria/`core`):
+
+1. **SELECT** — due tab (`Presets` / `Services & Modes`).
+2. **LOGS** — pannello scrollabile con filtro libreria-vs-servizi (`f`, `1-4`, `a`).
+
+## Come eseguire
+
+```bash
+# interattivo (serve un vero terminale)
+cd terminal-kit && npm install && npm start
+cd opentui     && npm install && npm start     # ⚠️ richiede Bun, vedi sotto
+
+# smoke test non interattivo (sotto pseudo-TTY, auto-exit dopo ~1.5s)
+script -qec "stty rows 40 cols 120; node index.js --smoke" /dev/null   # terminal-kit
+script -qec "stty rows 40 cols 120; bun  index.js --smoke" /dev/null   # opentui
+```
+
+## Risultati misurati (Node 22.22, Linux x64)
+
+| Criterio | terminal-kit | OpenTUI (`@opentui/core` 0.4) |
+|---|---|---|
+| **Gira su Node.js** | ✅ `received=480`, ok | ❌ **fallisce all'init** |
+| **Runtime richiesto** | Node (JS puro) | **Bun** (`received=498`, ok solo con `bun`) |
+| Tab nativi | ❌ fatti a mano (~15 righe) | ✅ `TabSelectRenderable` (con descrizioni/underline) |
+| Log scrollabili nativi | ✅ `TextBox` + `appendLog` | ✅ `ScrollBoxRenderable` (stickyScroll bottom) |
+| LOC dello shell | 161 | 137 (tab gratis dal widget) |
+| Footprint installato | **4.2 MB**, pure JS, 0 binari | **18 MB**, include `libopentui.so` per-piattaforma |
+| Cross-platform | ovunque giri Node | binario nativo per OS/arch (linux/darwin/win32 x64+arm64 presenti su npm) |
+
+## Il blocco decisivo: OpenTUI richiede Bun
+
+OpenTUI renderizza tramite **FFI nativo**. Il backend FFI nel bundle fa così:
+
+```js
+if (isBun) return createBunBackend(require("bun:ffi"));   // ok
+try   { return createNodeBackend(require("node:ffi")); }  // node:ffi NON ESISTE
+catch { return createUnsupportedBackend(error); }         // -> throw all'uso
+```
+
+`node:ffi` **non è un modulo di Node** (`ERR_UNKNOWN_BUILTIN_MODULE`), quindi
+sotto Node il render lib non si inizializza e `createCliRenderer()` lancia:
+
+```
+Error: Failed to initialize OpenTUI render library:
+       OpenTUI native FFI is not available for this runtime yet
+```
+
+Sotto **Bun** lo stesso identico codice funziona e renderizza benissimo (tab con
+descrizioni, underline, viewer log pinnato in fondo). La pagina "getting started"
+dice che puoi *importare* `@opentui/core` da Node — ed è vero — ma *renderizzare*
+no: serve Bun.
+
+## Conclusione / raccomandazione
+
+Per go-dev **così com'è (CLI Node.js)** la scelta è **terminal-kit**:
+
+- è l'unico dei due che **gira sul runtime del progetto** senza migrazioni;
+- JS puro, zero binari nativi → portabilità Windows inclusa, in linea con
+  l'attenzione cross-platform già presente in `src/process-manager.js`;
+- copre il pezzo difficile (log streaming scrollabili) con `TextBox.appendLog`;
+- costo extra reale e contenuto: i **tab non sono nativi** e vanno disegnati a
+  mano (qui ~15 righe). Tutto il resto è coperto.
+
+OpenTUI resta tecnicamente superiore per ergonomia widget (tab nativi, layout
+flex, frame sub-ms) **ma solo se go-dev adottasse Bun come runtime** — decisione
+ben più grande e fuori dallo scope di "migliorare la fruibilità con una TUI".
+
+> Da rivalutare se/quando OpenTUI abiliterà il backend FFI per Node
+> ("...not available for this runtime **yet**").

package/spike/opentui/index.js

@@ -0,0 +1,181 @@
+// go-dev TUI spike — OpenTUI core imperative API (non-React, Zig-backed).
+//
+// Same two screens as the terminal-kit spike, so the two are comparable:
+//   1. SELECT  — a native TabSelectRenderable ("Presets" / "Services & Modes")
+//                + a body Text. This is OpenTUI's selling point: tabs are a
+//                first-class widget, not hand-rolled.
+//   2. LOGS    — a native ScrollBoxRenderable with stickyScroll pinned to the
+//                bottom, fed by the same high-volume fake source, with the same
+//                library-vs-service filter.
+//
+// Run interactively:  npm start
+// Smoke test (PTY):    node index.js --smoke
+//
+// ESM + top-level await: @opentui/core is ESM-only (note "type":"module").
+
+import { createRequire } from 'node:module';
+import {
+  createCliRenderer,
+  BoxRenderable,
+  TextRenderable,
+  ScrollBoxRenderable,
+  TabSelectRenderable,
+} from '@opentui/core';
+
+const require = createRequire(import.meta.url);
+const { FakeLogSource, SERVICES } = require('../shared/fake-log-source');
+
+const SMOKE = process.argv.includes('--smoke');
+
+// ---- shared log model (the "log bus") --------------------------------------
+const RING_CAP = 2000;
+const ring = [];
+let showCore = true;
+let serviceFilter = null;
+let received = 0;
+
+function visibleLines() {
+  const out = [];
+  for (const e of ring) {
+    if (e.kind === 'core' && !showCore) continue;
+    if (serviceFilter && e.kind === 'service' && e.source !== serviceFilter) continue;
+    const tag = e.kind === 'core' ? '[core]' : `[${e.source}]`;
+    out.push(`${tag} ${e.level} ${e.line}`);
+  }
+  return out;
+}
+
+// ---- renderer + UI ----------------------------------------------------------
+const renderer = await createCliRenderer({ exitOnCtrlC: false, targetFps: 30 });
+const root = renderer.root;
+
+let screen = 'select';
+const PRESETS = ['api', 'dedup', 'basic'];
+
+const header = new TextRenderable(renderer, { content: '', height: 1 });
+root.add(header);
+
+// SELECT view ---------------------------------------------------------------
+const selectView = new BoxRenderable(renderer, { flexGrow: 1, flexDirection: 'column', padding: 1 });
+const tabs = new TabSelectRenderable(renderer, {
+  height: 3,
+  options: [
+    { name: 'Presets', description: 'Avvia da un preset esistente' },
+    { name: 'Services & Modes', description: 'Componi una selezione personalizzata' },
+  ],
+  showDescription: true,
+});
+const selectBody = new TextRenderable(renderer, { content: '', flexGrow: 1 });
+selectView.add(tabs);
+selectView.add(selectBody);
+root.add(selectView);
+
+// LOGS view -----------------------------------------------------------------
+const logsView = new BoxRenderable(renderer, { flexGrow: 1, flexDirection: 'column', visible: false });
+const scroll = new ScrollBoxRenderable(renderer, {
+  flexGrow: 1,
+  stickyScroll: true,
+  stickyStart: 'bottom',
+  border: true,
+});
+const logText = new TextRenderable(renderer, { content: '' });
+scroll.content.add(logText);
+logsView.add(scroll);
+root.add(logsView);
+
+const footer = new TextRenderable(renderer, { content: '', height: 1 });
+root.add(footer);
+
+// ---- rendering --------------------------------------------------------------
+function renderSelect() {
+  const tab = tabs.getSelectedIndex();
+  header.content = 'go-dev — selezione servizi';
+  if (tab === 0) {
+    selectBody.content =
+      'Preset disponibili (invio per avviare):\n\n' +
+      PRESETS.map((p) => `  • ${p}`).join('\n');
+  } else {
+    selectBody.content =
+      'Servizi disponibili (spazio = on/off, m = modalità):\n\n' +
+      SERVICES.map((s) => `  [x] ${s}   mode: dev`).join('\n');
+  }
+  footer.content = ' ←/→ cambia tab   invio: vai ai log   q: esci';
+}
+
+function renderLogs() {
+  header.content =
+    `go-dev · logs   core:${showCore ? 'ON' : 'OFF'}` +
+    `   filtro:${serviceFilter ?? 'tutti'}   (${received} righe)`;
+  logText.content = visibleLines().join('\n');
+  footer.content =
+    ' f: libreria on/off   1-4: filtra servizio   a: tutti   ↑↓/pgup: scorri   b: indietro   q: esci';
+}
+
+function showSelect() {
+  screen = 'select';
+  logsView.visible = false;
+  selectView.visible = true;
+  renderSelect();
+}
+
+function showLogs() {
+  screen = 'logs';
+  selectView.visible = false;
+  logsView.visible = true;
+  renderLogs();
+}
+
+// ---- input ------------------------------------------------------------------
+renderer.keyInput.on('keypress', (key) => {
+  const n = key.name;
+  if (n === 'q' || (key.ctrl && n === 'c')) return shutdown(0);
+
+  if (screen === 'select') {
+    if (n === 'left') { tabs.moveLeft(); renderSelect(); }
+    else if (n === 'right') { tabs.moveRight(); renderSelect(); }
+    else if (n === 'return' || n === 'enter') showLogs();
+    return;
+  }
+
+  switch (n) {
+    case 'f': showCore = !showCore; renderLogs(); break;
+    case 'a': case '0': serviceFilter = null; renderLogs(); break;
+    case '1': case '2': case '3': case '4':
+      serviceFilter = SERVICES[Number(n) - 1] || null; renderLogs(); break;
+    case 'up': scroll.scrollBy(-1); break;
+    case 'down': scroll.scrollBy(1); break;
+    case 'pageup': scroll.scrollBy(-scroll.height); break;
+    case 'pagedown': scroll.scrollBy(scroll.height); break;
+    case 'b': showSelect(); break;
+  }
+});
+
+// ---- lifecycle --------------------------------------------------------------
+const source = new FakeLogSource({ intervalMs: 8, burst: 3 });
+source.on('log', (e) => {
+  received++;
+  ring.push(e);
+  if (ring.length > RING_CAP) ring.shift();
+});
+
+let renderTimer = setInterval(() => { if (screen === 'logs') renderLogs(); }, 33);
+
+function shutdown(code) {
+  source.stop();
+  clearInterval(renderTimer);
+  try { renderer.stop(); } catch {}
+  try { renderer.destroy?.(); } catch {}
+  if (SMOKE) console.log(`[smoke] opentui ok — received=${received} ring=${ring.length}`);
+  setTimeout(() => process.exit(code), 50);
+}
+
+showSelect();
+renderer.start();
+source.start();
+
+if (SMOKE) {
+  setTimeout(showLogs, 300);
+  setTimeout(() => { showCore = false; }, 700);
+  setTimeout(() => { serviceFilter = SERVICES[0]; }, 1000);
+  setTimeout(() => shutdown(0), 1500);
+}

package/spike/opentui/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "spike-opentui",
+  "private": true,
+  "version": "0.0.0",
+  "description": "go-dev TUI spike — OpenTUI core (non-React, Zig-backed)",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@opentui/core": "latest"
+  }
+}

package/spike/shared/fake-log-source.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// Shared, dependency-free high-volume log generator used by both spikes.
+// Mirrors what go-dev's future "log bus" would emit: tagged events
+// { source, kind, level, line } where kind is 'service' or 'core' (library).
+//
+// The point of the spike is to stress the TUI's log pane: many lines per
+// second, interleaved sources, so we can judge streaming smoothness.
+
+const { EventEmitter } = require('node:events');
+
+const SERVICES = ['api', 'worker', 'main', 'db'];
+const LEVELS = ['info', 'info', 'info', 'warn', 'debug', 'error'];
+
+const SERVICE_LINES = [
+  'GET /health 200 1ms',
+  'processing job %d',
+  'cache miss for key user:%d',
+  'flush batch size=%d',
+  'connection pool: %d active',
+  'emitted event order.created id=%d',
+  'slow query took %dms',
+  'retrying upstream (attempt %d)',
+];
+
+const CORE_LINES = [
+  'resolved dependency graph (%d nodes)',
+  'service ready gate satisfied',
+  'spawned managed process pid=%d',
+  'readyWhen: port check ok',
+  'preCommand finished in %dms',
+];
+
+// Deterministic-ish pseudo counter so we don't need Math.random (and so output
+// is reproducible run-to-run, which makes comparing the two spikes fairer).
+let seq = 0;
+function nextInt(mod) {
+  seq = (seq * 1103515245 + 12345) & 0x7fffffff;
+  return seq % mod;
+}
+
+function fmt(template) {
+  return template.replace('%d', String(nextInt(9000) + 100));
+}
+
+class FakeLogSource extends EventEmitter {
+  constructor({ intervalMs = 8, burst = 3 } = {}) {
+    super();
+    this.intervalMs = intervalMs; // how often we emit a burst
+    this.burst = burst;           // lines per burst -> ~burst/intervalMs * 1000 lines/s
+    this._timer = null;
+  }
+
+  start() {
+    if (this._timer) return;
+    this._timer = setInterval(() => {
+      for (let i = 0; i < this.burst; i++) this._emitOne();
+    }, this.intervalMs);
+    // ~375 lines/s at defaults — enough to expose flicker/lag.
+  }
+
+  stop() {
+    if (this._timer) clearInterval(this._timer);
+    this._timer = null;
+  }
+
+  _emitOne() {
+    const isCore = nextInt(6) === 0; // ~1 in 6 lines are library/core logs
+    const level = LEVELS[nextInt(LEVELS.length)];
+    if (isCore) {
+      this.emit('log', {
+        source: 'core',
+        kind: 'core',
+        level,
+        line: fmt(CORE_LINES[nextInt(CORE_LINES.length)]),
+      });
+    } else {
+      const service = SERVICES[nextInt(SERVICES.length)];
+      this.emit('log', {
+        source: service,
+        kind: 'service',
+        level,
+        line: fmt(SERVICE_LINES[nextInt(SERVICE_LINES.length)]),
+      });
+    }
+  }
+}
+
+module.exports = { FakeLogSource, SERVICES };

package/spike/terminal-kit/index.js

@@ -0,0 +1,206 @@
+'use strict';
+
+// go-dev TUI spike — terminal-kit (pure JS, non-React).
+//
+// Two screens, mirroring the real design:
+//   1. SELECT  — two hand-rolled tabs ("Presets" / "Services"). terminal-kit has
+//                no native tab widget, so we draw the tab bar ourselves. This is
+//                an honest data point on the per-feature cost.
+//   2. LOGS    — a scrollable TextBox fed by a high-volume fake source, with a
+//                library-vs-service filter. TextBox + appendLog/setContent does
+//                the heavy lifting here, which is terminal-kit's strong suit.
+//
+// Run interactively:  npm start
+// Smoke test (CI/PTY): node index.js --smoke   (build UI, pump logs, auto-exit)
+
+const termkit = require('terminal-kit');
+const term = termkit.terminal;
+const { FakeLogSource, SERVICES } = require('../shared/fake-log-source');
+
+const SMOKE = process.argv.includes('--smoke');
+
+// ---- shared log model (this is the "log bus" go-dev would grow) -------------
+const RING_CAP = 2000;
+const ring = [];           // { source, kind, level, line }
+let showCore = true;       // 'f' toggles library/core logs
+let serviceFilter = null;  // 1-4 -> a single service; null = all services
+let pinnedToBottom = true; // false once the user scrolls up
+let received = 0;
+
+function levelColor(level) {
+  switch (level) {
+    case 'error': return '^r';
+    case 'warn': return '^y';
+    case 'debug': return '^K';
+    default: return '^g';
+  }
+}
+
+function visibleLines() {
+  const out = [];
+  for (const e of ring) {
+    if (e.kind === 'core' && !showCore) continue;
+    if (serviceFilter && e.kind === 'service' && e.source !== serviceFilter) continue;
+    const tag = e.kind === 'core' ? '^c[core]^:' : `^b[${e.source}]^:`;
+    out.push(`${tag} ${levelColor(e.level)}${e.level}^: ${e.line}`);
+  }
+  return out;
+}
+
+// ---- UI ---------------------------------------------------------------------
+let screen = 'select';       // 'select' | 'logs'
+let activeTab = 0;           // 0 = Presets, 1 = Services
+const TABS = ['Presets', 'Services & Modes'];
+const PRESETS = ['api', 'dedup', 'basic'];
+
+let document, logBox, headerText, bodyText, footerText;
+
+function buildUI() {
+  term.fullscreen(true);
+  document = term.createDocument();
+
+  headerText = new termkit.Text({ parent: document, x: 0, y: 0, content: '', contentHasMarkup: true });
+  bodyText = new termkit.Text({ parent: document, x: 0, y: 2, content: '', contentHasMarkup: true });
+
+  logBox = new termkit.TextBox({
+    parent: document,
+    x: 0, y: 2,
+    width: term.width,
+    height: term.height - 4,
+    scrollable: true,
+    vScrollBar: true,
+    contentHasMarkup: true,
+    hidden: true,
+  });
+
+  footerText = new termkit.Text({
+    parent: document,
+    x: 0, y: term.height - 1,
+    content: '', contentHasMarkup: true,
+  });
+
+  renderSelect();
+}
+
+function renderSelect() {
+  const tabBar = TABS.map((t, i) =>
+    i === activeTab ? `^#^k ${t} ^:` : `^K ${t} ^:`
+  ).join('  ');
+  headerText.setContent(`^+go-dev^:  ${tabBar}`, true);
+
+  let body;
+  if (activeTab === 0) {
+    body = PRESETS.length
+      ? '  Preset disponibili (↑↓ + invio per avviare):\n\n' +
+        PRESETS.map(p => `   ^b•^: ${p}`).join('\n')
+      : '  Nessun preset definito — usa la tab Services.';
+  } else {
+    body = '  Servizi disponibili (spazio per (de)selezionare, m per modalità):\n\n' +
+      SERVICES.map(s => `   ^g[x]^: ${s}   ^Kmode: dev^:`).join('\n');
+  }
+  bodyText.setContent(body, true);
+  footerText.setContent('^K tab^: cambia tab   ^K invio^: vai ai log   ^K q^: esci', true);
+}
+
+function renderLogs() {
+  headerText.setContent(
+    `^+go-dev · logs^:   core:${showCore ? '^gON^:' : '^rOFF^:'}` +
+    `   filtro:${serviceFilter ? '^b' + serviceFilter + '^:' : 'tutti'}` +
+    `   ^K(${received} righe)^:`,
+    true
+  );
+  const lines = visibleLines();
+  logBox.setContent(lines.join('\n'), true, true);
+  if (pinnedToBottom) logBox.scrollToBottom(true);
+  logBox.draw();
+  footerText.setContent(
+    '^K f^: libreria on/off   ^K 1-4^: filtra servizio   ^K a^: tutti   ' +
+    '^K ↑↓/pgup^: scorri   ^K g/G^: cima/fondo   ^K b^: indietro   ^K q^: esci',
+    true
+  );
+}
+
+function goToLogs() {
+  screen = 'logs';
+  bodyText.hide();
+  logBox.show();
+  logBox.y = 2;
+  logBox.outerHeight = term.height - 4;
+  renderLogs();
+}
+
+function goToSelect() {
+  screen = 'select';
+  logBox.hide();
+  bodyText.show();
+  renderSelect();
+}
+
+// ---- input ------------------------------------------------------------------
+function onKey(name) {
+  if (name === 'CTRL_C' || name === 'q') return shutdown(0);
+
+  if (screen === 'select') {
+    if (name === 'TAB' || name === 'RIGHT') { activeTab = (activeTab + 1) % TABS.length; renderSelect(); }
+    else if (name === 'LEFT') { activeTab = (activeTab + TABS.length - 1) % TABS.length; renderSelect(); }
+    else if (name === 'ENTER') goToLogs();
+    return;
+  }
+
+  // logs screen
+  switch (name) {
+    case 'f': showCore = !showCore; renderLogs(); break;
+    case 'a': case '0': serviceFilter = null; renderLogs(); break;
+    case '1': case '2': case '3': case '4':
+      serviceFilter = SERVICES[Number(name) - 1] || null; renderLogs(); break;
+    case 'UP': pinnedToBottom = false; logBox.scroll(0, 1); break;
+    case 'DOWN': logBox.scroll(0, -1); break;
+    case 'PAGE_UP': pinnedToBottom = false; logBox.scroll(0, logBox.outerHeight); break;
+    case 'PAGE_DOWN': logBox.scroll(0, -logBox.outerHeight); break;
+    case 'g': pinnedToBottom = false; logBox.scrollTo(0, 0); break;
+    case 'G': pinnedToBottom = true; logBox.scrollToBottom(); break;
+    case 'b': goToSelect(); break;
+  }
+}
+
+// ---- lifecycle --------------------------------------------------------------
+const source = new FakeLogSource({ intervalMs: 8, burst: 3 });
+source.on('log', (e) => {
+  received++;
+  ring.push(e);
+  if (ring.length > RING_CAP) ring.shift();
+});
+
+let renderTimer = null;
+function startRenderLoop() {
+  renderTimer = setInterval(() => { if (screen === 'logs') renderLogs(); }, 33); // ~30fps
+}
+
+function shutdown(code) {
+  source.stop();
+  if (renderTimer) clearInterval(renderTimer);
+  term.grabInput(false);
+  term.fullscreen(false);
+  term.hideCursor(false);
+  if (SMOKE) console.log(`[smoke] terminal-kit ok — received=${received} ring=${ring.length}`);
+  setTimeout(() => process.exit(code), 50);
+}
+
+function main() {
+  buildUI();
+  term.grabInput(true);
+  term.hideCursor(true);
+  term.on('key', onKey);
+  source.start();
+  startRenderLoop();
+
+  if (SMOKE) {
+    // Drive the real code path without a human: jump to logs, toggle a filter, exit.
+    setTimeout(goToLogs, 300);
+    setTimeout(() => { showCore = false; }, 700);
+    setTimeout(() => { serviceFilter = SERVICES[0]; }, 1000);
+    setTimeout(() => shutdown(0), 1500);
+  }
+}
+
+main();

package/spike/terminal-kit/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "spike-terminal-kit",
+  "private": true,
+  "version": "0.0.0",
+  "description": "go-dev TUI spike — terminal-kit (pure JS, non-React)",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "terminal-kit": "^3.1.2"
+  }
+}