javer-cli 1.0.0

package/lib/api.js

@@ -0,0 +1,79 @@
+// Thin fetch wrapper. Node 18+ has global fetch, so this package has zero
+// dependencies — nothing to audit, nothing to keep patched, and `npm i -g`
+// stays instant.
+const config = require('./config');
+const { version } = require('../package.json');
+
+class ApiError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+const request = async (method, route, body) => {
+  const key = config.apiKey();
+  if (!key) throw new ApiError('Not logged in. Run `javer login` first.', 401);
+
+  const res = await fetch(`${config.apiUrl()}/api${route}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${key}`,
+      'User-Agent': `javer-cli/${version}`,
+      ...(body ? { 'Content-Type': 'application/json' } : {})
+    },
+    ...(body ? { body: JSON.stringify(body) } : {})
+  });
+
+  const text = await res.text();
+  let data;
+  try { data = text ? JSON.parse(text) : {}; } catch { data = { raw: text }; }
+
+  // fetch() only rejects on network failure — an HTTP 401/500 resolves
+  // normally. Without this check every error would look like a success with
+  // odd-shaped data.
+  if (!res.ok) {
+    throw new ApiError(data.message || `Request failed (HTTP ${res.status})`, res.status, data);
+  }
+  return data;
+};
+
+// A file upload, for deploying the folder you are standing in. The deploy
+// endpoints take multipart with a field called `appfile`, so this cannot go
+// through request() — that one always sends JSON.
+//
+// FormData and Blob are built into Node 18 and later, which package.json
+// already requires, so there is still nothing to install. Letting fetch build
+// the body also means the multipart boundary is its problem, not ours.
+const upload = async (route, filename, buffer, fields = {}) => {
+  const key = config.apiKey();
+  if (!key) throw new ApiError('Not logged in. Run `javer login` first.', 401);
+
+  const form = new FormData();
+  for (const [k, v] of Object.entries(fields)) form.append(k, String(v));
+  form.append('appfile', new Blob([buffer]), filename);
+
+  const res = await fetch(`${config.apiUrl()}/api${route}`, {
+    method: 'POST',
+    // Deliberately no Content-Type: fetch sets it, with the boundary. Setting
+    // it by hand here is the classic way to get an unparseable request.
+    headers: { Authorization: `Bearer ${key}`, 'User-Agent': `javer-cli/${version}` },
+    body: form
+  });
+
+  const text = await res.text();
+  let data;
+  try { data = text ? JSON.parse(text) : {}; } catch { data = { raw: text }; }
+  if (!res.ok) throw new ApiError(data.message || `Upload failed (HTTP ${res.status})`, res.status, data);
+  return data;
+};
+
+module.exports = {
+  ApiError,
+  get: (route) => request('GET', route),
+  post: (route, body) => request('POST', route, body),
+  put: (route, body) => request('PUT', route, body),
+  del: (route) => request('DELETE', route),
+  upload
+};

package/lib/bird.js

@@ -0,0 +1,129 @@
+/* JAVER-SIGNATURE-START
+     JAV
+    E  RJ
+   A o VE
+  RJA  VERJ
+  A   V  ERJA
+      V  ER JA
+      V  ER JA
+      VE RJA V
+      ER   JAVE
+       RJ   AVE
+       RJAVERJAV
+        E     RJ
+       AVERJ   AV
+javer.pro — built in-house, not outsourced. signed: budgie
+JAVER-SIGNATURE-END */
+
+// The Javer bird, for the terminal.
+//
+// This is not a drawing of a bird. It is THE bird, read straight out of
+// public/javerbirb.jpg. Hand-drawing it from memory produces a centipede, or a
+// shoe; both were tried.
+//
+// The grid is 15x15 and its cells are NOT square: 78px across, 67.5px down.
+// That non-square cell is what made the first three attempts wrong. Guessing a
+// single cell size from the horizontal runs gave 15x13, which sampled thirteen
+// rows out of an image that has fifteen — every row after the head landed
+// slightly off, two rows vanished entirely, and the eye came out 77px wide but
+// 67px tall, which was the clue sitting in plain sight the whole time.
+//
+// It was settled by run-length encoding each row's pattern across the whole
+// image: rows inside one logical cell are identical, so the bands between
+// changes ARE the cell rows. No guessing, no rounding.
+//
+// G = body green, L = the lighter mint highlight on the crest, W = the white
+// eye, . = nothing. The highlight is a single cell and it is the only shading
+// in the whole logo, so rendering it as ordinary green is immediately visible
+// as a missing pixel — which is exactly how it was spotted.
+const GRID = [
+  '...GGG.........',
+  '..L..GG........',
+  '.G.W.GG........',
+  'GGG..GGG.......',
+  'GG.GG.GGG......',
+  'G...G..GGG.....',
+  '....G..G.GG....',
+  '....G..G.GG....',
+  '....GG.GG.G....',
+  '....GG..GGGG...',
+  '.....GG..GGG...',
+  '.....GGGGGGGG..',
+  '......G....GG..',
+  '.....GGGG...GG.',
+  '.............GG'
+];
+
+// Sampled from the logo itself rather than guessed.
+const GREEN = [11, 165, 37];    // body, measured off the logo
+const LIGHT = [37, 167, 75];    // the crest highlight: more red and blue, so it reads brighter
+const WHITE = [255, 255, 255];  // the eye
+const RESET = '\x1b[0m';
+const fg = (c) => `\x1b[38;2;${c[0]};${c[1]};${c[2]}m`;
+const bg = (c) => `\x1b[48;2;${c[0]};${c[1]};${c[2]}m`;
+const colourOf = (ch) => (ch === 'G' ? GREEN : ch === 'L' ? LIGHT : ch === 'W' ? WHITE : null);
+
+// Half-height blocks: two pixel rows per text line, so thirteen rows become
+// seven lines. This is the trick that makes terminal mascots look smooth —
+// one character cell carries a top pixel and a bottom pixel, drawn as a
+// foreground and a background colour.
+//
+// The catch is real: if a terminal adds line spacing, the halves separate and
+// the shape tears. `javer bird` prints this next to the blocky version so you
+// can see which one your own terminal renders properly.
+const half = () => {
+  const out = [];
+  for (let y = 0; y < GRID.length; y += 2) {
+    const top = GRID[y];
+    const bot = GRID[y + 1] || '.'.repeat(top.length);
+    let line = '';
+    for (let x = 0; x < top.length; x++) {
+      const t = colourOf(top[x]);
+      const b = colourOf(bot[x]);
+      if (t && b) line += fg(t) + bg(b) + '▀' + RESET;
+      else if (t) line += fg(t) + '▀' + RESET;
+      else if (b) line += fg(b) + '▄' + RESET;
+      else line += ' ';
+    }
+    out.push(line);
+  }
+  return out;
+};
+
+// One pixel per two characters. Taller, but every cell is a whole character —
+// nothing can tear, and the proportions are true squares because a terminal
+// cell is about half as wide as it is tall.
+const full = () => GRID.map((row) => {
+  let line = '';
+  for (const ch of row) {
+    const c = colourOf(ch);
+    line += c ? fg(c) + '██' + RESET : '  ';
+  }
+  return line;
+});
+
+// The JAVER wordmark in block letters, for the empty band the stats leave
+// between themselves and the bird. Five rows, drawn on the same grid idea as
+// the logo so the header reads as one piece rather than three ornaments.
+const WORDMARK = [
+  '  #   #   # # ### ## ',
+  '  #  # #  # # #   # #',
+  '  #  ###  # # ##  ## ',
+  '# #  # #  # # #   # #',
+  ' ##  # #   #  ### # #'
+];
+
+// TWO characters per pixel. A terminal cell is about half as wide as it is
+// tall, so a letter five rows high needs roughly six columns to look correctly
+// proportioned — at one character per pixel these came out three wide and ten
+// tall, which reads as squashed from the sides.
+const wordmark = () => WORDMARK.map((row) => {
+  let line = '';
+  for (const ch of row) line += ch === '#' ? fg(GREEN) + '██' + RESET : '  ';
+  return line;
+});
+
+// Width in visible columns, for laying the bird out beside other things.
+const widthOf = (lines) => Math.max(...lines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').length));
+
+module.exports = { GRID, GREEN, LIGHT, half, full, wordmark, widthOf };

package/lib/config.js

@@ -0,0 +1,43 @@
+// Credential storage for the CLI. The API key is a long-lived, non-expiring
+// credential with the same power as a browser session, so it lives in a
+// 0600 file inside a 0700 directory — never in shell history, never in an
+// env var that leaks into `ps` output or a CI log.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DIR = path.join(os.homedir(), '.javer');
+const FILE = path.join(DIR, 'config.json');
+const DEFAULT_URL = 'https://panel.javer.pro';
+
+const read = () => {
+  try {
+    return JSON.parse(fs.readFileSync(FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+};
+
+const write = (cfg) => {
+  fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  // Write then chmod: writeFileSync's mode argument only applies when the
+  // file is created, so an existing file with looser permissions would
+  // silently keep them.
+  fs.writeFileSync(FILE, JSON.stringify(cfg, null, 2));
+  fs.chmodSync(FILE, 0o600);
+};
+
+const clear = () => {
+  try { fs.unlinkSync(FILE); return true; } catch { return false; }
+};
+
+// JAVER_API_URL exists so the CLI can be pointed at a local dev server
+// without touching the saved production config — the same override the
+// server's own test harnesses use.
+const apiUrl = () => process.env.JAVER_API_URL || read().apiUrl || DEFAULT_URL;
+
+// JAVER_API_KEY takes precedence over the saved file so CI can supply a key
+// as a secret without running `javer login` first.
+const apiKey = () => process.env.JAVER_API_KEY || read().key || null;
+
+module.exports = { read, write, clear, apiUrl, apiKey, FILE, DEFAULT_URL };

package/lib/ui.js

@@ -0,0 +1,366 @@
+/* JAVER-SIGNATURE-START
+     JAV
+    E  RJ
+   A o VE
+  RJA  VERJ
+  A   V  ERJA
+      V  ER JA
+      V  ER JA
+      VE RJA V
+      ER   JAVE
+       RJ   AVE
+       RJAVERJAV
+        E     RJ
+       AVERJ   AV
+javer.pro — built in-house, not outsourced. signed: sky
+JAVER-SIGNATURE-END */
+
+// `javer ui` — a live view of everything you are running, in the terminal.
+//
+// Apps AND VMs in one place, which the panel itself does not do: there, they
+// are two separate pages, and the resource budget they share is only visible on
+// a third. Here the budget is the header and both kinds sit under it, because
+// what people actually want to know is "what have I got, and how much is left".
+//
+// No dependencies. That is a deliberate constraint for a globally-installed
+// tool, so this is plain ANSI: an alternate screen buffer, cursor moves and
+// box-drawing characters. Everything one frame needs is built as a single
+// string and written in one go — writing piece by piece is what makes a
+// terminal UI flicker.
+const api = require('./api');
+const bird = require('./bird');
+const config = require('./config');
+
+const ESC = '\x1b[';
+const alt = (on) => (on ? `${ESC}?1049h` : `${ESC}?1049l`);
+const cursor = (on) => (on ? `${ESC}?25h` : `${ESC}?25l`);
+const home = `${ESC}H`;
+const clear = `${ESC}2J`;
+
+const C = {
+  reset: `${ESC}0m`, dim: `${ESC}2m`, bold: `${ESC}1m`, rev: `${ESC}7m`,
+  green: `${ESC}32m`, red: `${ESC}31m`, yellow: `${ESC}33m`,
+  blue: `${ESC}34m`, cyan: `${ESC}36m`, grey: `${ESC}90m`
+};
+
+// Width without the escape sequences, so padding maths stays right once the
+// string has colour in it.
+const visible = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+const padTo = (s, n) => {
+  const len = visible(s).length;
+  return len >= n ? s : s + ' '.repeat(n - len);
+};
+const trunc = (s, n) => {
+  const v = visible(s);
+  return v.length <= n ? s : v.slice(0, Math.max(0, n - 1)) + '…';
+};
+
+// A proportion drawn as a bar. Colour carries the same information as the
+// length so it survives being skim-read: green is fine, yellow is getting
+// full, red needs attention.
+const bar = (used, total, width = 14) => {
+  if (!total || total <= 0) return C.grey + '─'.repeat(width) + C.reset;
+  const ratio = Math.max(0, Math.min(1, used / total));
+  const filled = Math.round(ratio * width);
+  const colour = ratio > 0.9 ? C.red : ratio > 0.7 ? C.yellow : C.green;
+  return colour + '█'.repeat(filled) + C.grey + '░'.repeat(width - filled) + C.reset;
+};
+
+const statusDot = (s) => {
+  const state = String(s || '').toLowerCase();
+  if (state === 'running') return C.green + '●' + C.reset;
+  if (state === 'stopped' || state === 'shut off' || state === 'exited') return C.grey + '○' + C.reset;
+  if (state === 'error' || state === 'crashed') return C.red + '✖' + C.reset;
+  return C.yellow + '◐' + C.reset;
+};
+
+const mb = (bytes) => (bytes == null ? null : Math.round(bytes / 1048576));
+
+// The real bird, read out of the logo rather than drawn from memory — see
+// lib/bird.js. Half-height blocks put its thirteen pixel rows into seven text
+// lines, which is what makes it look like the logo instead of like a staircase.
+const BIRD = bird.half();
+const BIRD_W = bird.widthOf(BIRD);
+// The stats leave a wide dead band between themselves and the bird. The
+// wordmark fills it, so the header reads as one composition rather than a
+// column of numbers with an ornament stuck on the far side.
+const MARK = bird.wordmark();
+const MARK_W = bird.widthOf(MARK);
+
+// One row of the unified list. Apps and VMs differ enough that keeping them as
+// one shape here is what lets the whole table share selection and actions.
+const buildRows = (apps, vms, stats) => {
+  const rows = [];
+  for (const a of apps) {
+    const st = stats[`app:${a.id}`];
+    rows.push({
+      kind: 'app', id: a.id, name: a.name, status: a.status,
+      ramUsed: mb(st?.memUsage), ramMax: a.ram_mb, cpu: st?.cpuPercent,
+      where: a.docker_host || 'node2',
+      url: a.hostname ? `https://${a.hostname}` : null
+    });
+  }
+  for (const v of vms) {
+    const st = stats[`vm:${v.id}`];
+    rows.push({
+      kind: 'vm', id: v.id, name: v.name, status: v.state || v.status,
+      ramUsed: mb(st?.memUsage), ramMax: v.ram_mb, cpu: st?.cpuPercent,
+      where: v.ip || '—',
+      url: null
+    });
+  }
+  return rows;
+};
+
+const render = (state, width, height) => {
+  const W = Math.max(64, Math.min(width || 100, 140));
+  const line = (l, m, r, fill = '─') => l + fill.repeat(W - 2) + r;
+  const out = [];
+
+  // ── header: the shared budget on the left, the bird on the right.
+  // Neither panel page shows this budget — apps and VMs are separate screens
+  // there and the thing they compete for is on a third.
+  const u = state.usage;
+  out.push(C.cyan + line('╭', '', '╮') + C.reset);
+
+  const inner = W - 4;                     // usable width between the borders
+  // Decorations give way to data as the terminal narrows: the wordmark goes
+  // first, then the bird. The numbers are never what gets dropped.
+  const STATS_MIN = 46;   // the stats need this much before anything decorative earns room
+  const showBird = inner > BIRD_W + 34;
+  const showMark = showBird && inner > BIRD_W + MARK_W + STATS_MIN;
+  // The stats column is only as wide as the stats. Padding it out to fill the
+  // row just relocates the empty space instead of using it — which is what the
+  // first attempt at this did.
+  const STATS_W = 44;
+  const leftW = showMark ? STATS_W : inner - (showBird ? BIRD_W + 1 : 0);
+  // Whatever sits between the stats and the bird is the wordmark's to centre in.
+  const midW = showMark ? inner - STATS_W - BIRD_W - 1 : 0;
+  const markPad = showMark ? Math.max(0, Math.floor((midW - MARK_W) / 2)) : 0;
+
+  const running = state.rows.filter((r) => String(r.status).toLowerCase() === 'running').length;
+  const apps = state.rows.filter((r) => r.kind === 'app').length;
+  const machines = state.rows.filter((r) => r.kind === 'vm').length;
+
+  const left = [];
+  left.push(`${C.bold}JAVER${C.reset}${C.grey} · ${config.apiUrl().replace(/^https?:\/\//, '')}${C.reset}`);
+  left.push('');
+  if (u) {
+    left.push(`${C.grey}RAM   ${C.reset}${bar(u.used.usedRamMB, u.budget.ramMB, 16)} ${u.used.usedRamMB}/${u.budget.ramMB} MB`);
+    left.push(`${C.grey}CPU   ${C.reset}${bar(u.used.usedCpu, u.budget.cpu, 16)} ${u.used.usedCpu}/${u.budget.cpu}`);
+    left.push(`${C.grey}SLOTS ${C.reset}${bar(u.used.usedItems, u.budget.maxItems, 16)} ${u.used.usedItems}/${u.budget.maxItems}`);
+  }
+  left.push(`${C.grey}${apps} app${apps === 1 ? '' : 's'}, ${machines} VM${machines === 1 ? '' : 's'}, ${running} running${C.reset}`);
+  left.push(state.error
+    ? C.red + trunc(state.error, leftW - 2) + C.reset
+    : C.grey + `updated ${state.updatedAt}${state.busy ? ' · working…' : ''}` + C.reset);
+
+  // Both columns are drawn to the same height so the box stays square whether
+  // or not the usage call came back.
+  const rows = Math.max(left.length, showBird ? BIRD.length : 0);
+  // The wordmark is shorter than the header, so centre it vertically rather
+  // than letting it hang off the top.
+  const markTop = Math.max(0, Math.floor((rows - MARK.length) / 2));
+  for (let i = 0; i < rows; i++) {
+    const l = padTo(trunc(left[i] || '', leftW), leftW);
+    const m = showMark
+      ? padTo(' '.repeat(markPad) + (MARK[i - markTop] || ''), midW)
+      : '';
+    const b = showBird ? ' ' + padTo(BIRD[i] || '', BIRD_W) : '';
+    out.push(C.cyan + '│' + C.reset + ' ' + l + m + b + ' ' + C.cyan + '│' + C.reset);
+  }
+  out.push(C.cyan + line('├', '', '┤') + C.reset);
+
+  // ── column headings
+  const head =
+    `${padTo('', 3)}${padTo('NAME', 22)}${padTo('KIND', 6)}${padTo('MEMORY', 20)}` +
+    `${padTo('CPU', 7)}${padTo('WHERE', 14)}ADDRESS`;
+  out.push(C.cyan + '│' + C.reset + ' ' + C.grey + padTo(trunc(head, W - 4), W - 4) + C.reset + ' ' + C.cyan + '│' + C.reset);
+
+  // ── rows
+  if (!state.rows.length) {
+    const empty = state.loading ? 'Loading…' : 'Nothing running yet. Deploy something with `javer deploy`.';
+    out.push(C.cyan + '│' + C.reset + ' ' + padTo(C.grey + empty + C.reset, W - 4) + ' ' + C.cyan + '│' + C.reset);
+  }
+  const maxRows = Math.max(3, (height || 30) - out.length - 6);
+  state.rows.slice(0, maxRows).forEach((r, i) => {
+    const sel = i === state.cursor;
+    const ramTxt = r.ramUsed == null ? `${C.grey}—${C.reset}` : `${r.ramUsed}/${r.ramMax}MB`;
+    const body =
+      `${statusDot(r.status)}  ` +
+      `${padTo(trunc(r.name, 21), 22)}` +
+      `${C.grey}${padTo(r.kind, 6)}${C.reset}` +
+      `${bar(r.ramUsed, r.ramMax, 10)} ${padTo(ramTxt, 12)}` +
+      `${padTo(r.cpu == null ? C.grey + '—' + C.reset : `${r.cpu}%`, 7)}` +
+      `${C.grey}${padTo(trunc(r.where, 13), 14)}${C.reset}` +
+      `${r.url ? C.blue + trunc(r.url, 30) + C.reset : C.grey + '—' + C.reset}`;
+    if (sel) {
+      // Strip the colour: every C.reset inside the row would otherwise end the
+      // inverse video early, leaving the highlight covering only part of it.
+      const plain = padTo(trunc(visible(body), W - 4), W - 4);
+      out.push(C.cyan + '│' + C.reset + C.rev + ' ' + plain + ' ' + C.reset + C.cyan + '│' + C.reset);
+    } else {
+      out.push(C.cyan + '│' + C.reset + ' ' + padTo(trunc(body, W - 4), W - 4) + ' ' + C.cyan + '│' + C.reset);
+    }
+  });
+
+  // ── footer: the keys, always visible, because a UI with hidden verbs is a
+  // UI you have to read documentation for.
+  out.push(C.cyan + line('├', '', '┤') + C.reset);
+  const keys = state.confirm
+    ? `${C.yellow}${state.confirm}${C.reset}  ${C.grey}y = yes, any other key = cancel${C.reset}`
+    : `${C.bold}↑↓${C.reset} select   ${C.bold}s${C.reset} start/stop   ${C.bold}r${C.reset} restart   ` +
+      `${C.bold}l${C.reset} logs   ${C.bold}u${C.reset} refresh   ${C.bold}q${C.reset} quit`;
+  out.push(C.cyan + '│' + C.reset + ' ' + padTo(trunc(keys, W - 4), W - 4) + ' ' + C.cyan + '│' + C.reset);
+  out.push(C.cyan + line('╰', '', '╯') + C.reset);
+
+  if (state.message) out.push(' ' + state.message);
+  return out.join('\n');
+};
+
+const run = async () => {
+  if (!process.stdout.isTTY) {
+    console.error('error: `javer ui` needs an interactive terminal. Try `javer ls` instead.');
+    process.exit(1);
+  }
+
+  const state = {
+    rows: [], usage: null, cursor: 0, loading: true, busy: false,
+    error: null, message: '', confirm: null, updatedAt: '—'
+  };
+  let timer = null;
+  let stopped = false;
+
+  // Restoring the terminal matters more than anything else here: leave the
+  // alternate buffer on or the cursor hidden and the user's shell is broken
+  // afterwards. Every exit path goes through this exactly once.
+  const restore = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer) clearInterval(timer);
+    try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch { /* already gone */ }
+    process.stdin.pause();
+    process.stdout.write(cursor(true) + alt(false));
+  };
+  const quit = (code = 0) => { restore(); process.exit(code); };
+  process.on('exit', restore);
+  process.on('SIGINT', () => quit(0));
+  process.on('SIGTERM', () => quit(0));
+  process.on('uncaughtException', (err) => { restore(); console.error(`error: ${err.message}`); process.exit(1); });
+
+  const draw = () => {
+    if (stopped) return;
+    process.stdout.write(home + clear + render(state, process.stdout.columns, process.stdout.rows) + '\n');
+  };
+
+  const refresh = async () => {
+    try {
+      // Apps and VMs in parallel. A VM listing failure must not blank the apps
+      // — a partial view beats an error screen when you are watching a fleet.
+      const [appsRes, vmsRes] = await Promise.all([
+        api.get('/apps/').catch((e) => ({ apps: [], _err: e.message })),
+        api.get('/vms/').catch((e) => ({ vms: [], _err: e.message }))
+      ]);
+      const apps = appsRes.apps || [];
+      const vms = vmsRes.vms || vmsRes.machines || [];
+
+      // Stats are per-resource and only meaningful while running. Failures are
+      // swallowed on purpose: a stat that will not load should show a dash, not
+      // take the screen down.
+      const stats = {};
+      await Promise.all([
+        ...apps.filter((a) => a.status === 'running').map((a) =>
+          api.get(`/apps/${a.id}/stats`).then((s) => { stats[`app:${a.id}`] = s; }).catch(() => {})),
+        ...vms.filter((v) => (v.state || v.status) === 'running').map((v) =>
+          api.get(`/vms/${v.id}/stats`).then((s) => { stats[`vm:${v.id}`] = s; }).catch(() => {}))
+      ]);
+
+      const usage = await api.get('/account/usage').catch(() => null);
+      state.rows = buildRows(apps, vms, stats);
+      state.usage = usage;
+      state.error = appsRes._err || vmsRes._err || null;
+      state.loading = false;
+      state.updatedAt = new Date().toTimeString().slice(0, 8);
+      if (state.cursor >= state.rows.length) state.cursor = Math.max(0, state.rows.length - 1);
+    } catch (err) {
+      state.error = err.message;
+      state.loading = false;
+    }
+    draw();
+  };
+
+  const act = async (verb, row) => {
+    state.busy = true; state.message = ''; draw();
+    try {
+      const base = row.kind === 'vm' ? `/vms/${row.id}` : `/apps/${row.id}`;
+      await api.post(`${base}/${verb}`, {});
+      state.message = `${C.green}${verb} sent to ${row.name}${C.reset}`;
+    } catch (err) {
+      state.message = `${C.red}${row.name}: ${err.message}${C.reset}`;
+    }
+    state.busy = false;
+    await refresh();
+  };
+
+  process.stdout.write(alt(true) + cursor(false));
+  draw();
+  await refresh();
+  timer = setInterval(refresh, 4000);
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', async (key) => {
+    const row = state.rows[state.cursor];
+
+    // A pending confirmation swallows the next keypress, so an accidental
+    // second 's' cannot both ask and answer.
+    if (state.confirm) {
+      const { verb, target } = state.confirm_action;
+      state.confirm = null; state.confirm_action = null;
+      if (key.toLowerCase() === 'y') await act(verb, target); else { state.message = ''; draw(); }
+      return;
+    }
+
+    if (key === 'q' || key === '') return quit(0);          // q or Ctrl-C
+    if (key === '' || key === 'k') { state.cursor = Math.max(0, state.cursor - 1); return draw(); }
+    if (key === '' || key === 'j') { state.cursor = Math.min(state.rows.length - 1, state.cursor + 1); return draw(); }
+    if (key === 'u') return refresh();
+
+    if (!row) return;
+    if (key === 's') {
+      const running = String(row.status).toLowerCase() === 'running';
+      const verb = running ? 'stop' : 'start';
+      // Stopping takes something offline. Ask first — a UI where one keystroke
+      // takes a live site down is a UI that eventually takes a live site down.
+      if (running) {
+        state.confirm = `Stop ${row.name}? It will go offline.`;
+        state.confirm_action = { verb, target: row };
+        return draw();
+      }
+      return act(verb, row);
+    }
+    if (key === 'r') {
+      state.confirm = `Restart ${row.name}? Brief downtime.`;
+      state.confirm_action = { verb: 'restart', target: row };
+      return draw();
+    }
+    if (key === 'l') {
+      // Leave the alternate buffer entirely rather than trying to paint logs
+      // inside the frame: log lines are arbitrarily wide and wrap, and the
+      // scrollback belongs to the real terminal where it can be searched.
+      restore();
+      console.log(`\n─── last logs for ${row.name} ───\n`);
+      try {
+        const path = row.kind === 'vm' ? `/vms/${row.id}` : `/apps/${row.id}`;
+        const { logs } = await api.get(`${path}/logs`);
+        console.log(logs || '(nothing yet)');
+      } catch (err) {
+        console.error(`error: ${err.message}`);
+      }
+      process.exit(0);
+    }
+  });
+};
+
+module.exports = { run, render, bar, buildRows };