recomposable 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+```
+  __      __ _  _   _   _    ___
+  \ \    / /| || | /_\ | |  | __|        .
+   \ \/\/ / | __ |/ _ \| |__| _|       ":"
+    \_/\_/  |_||_/_/ \_|____|___|   ___:____     |"\/"|
+                                  ,'        `.    \  /
+   docker compose manager         |  O        \___/  |
+                                  ~^~^~^~^~^~^~^~^~^~^~^~
+```
+
+# recomposable
+
+A lightweight Docker Compose TUI manager with vim keybindings. Monitor service status, restart or rebuild containers, and tail logs — all from your terminal.
+
+Zero dependencies. Pure Node.js.
+
+## Install
+
+```bash
+npm install -g recomposable
+```
+
+This registers the `recomposable` command on your system.
+
+## Quick Start
+
+1. Navigate to your project directory (where your `docker-compose.yml` lives)
+2. Create a `recomposable.json` config file
+3. Run `recomposable`
+
+```bash
+cd ~/my-project
+cat > recomposable.json << 'EOF'
+{
+  "composeFiles": [
+    "docker-compose.yml"
+  ]
+}
+EOF
+recomposable
+```
+
+## Adding Compose Files
+
+Create a `recomposable.json` file in your project root:
+
+```json
+{
+  "composeFiles": [
+    "docker-compose.yml"
+  ],
+  "pollInterval": 3000,
+  "logTailLines": 100
+}
+```
+
+### Multiple compose files
+
+```json
+{
+  "composeFiles": [
+    "docker-compose.yml",
+    "docker-compose.override.yml",
+    "infra/docker-compose.monitoring.yml"
+  ]
+}
+```
+
+### CLI override
+
+You can skip `recomposable.json` entirely and pass compose files directly:
+
+```bash
+recomposable -f docker-compose.yml
+recomposable -f docker-compose.yml -f docker-compose.prod.yml
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `composeFiles` | `[]` | Array of docker-compose file paths (relative to `recomposable.json`) |
+| `pollInterval` | `3000` | Status polling interval in milliseconds |
+| `logTailLines` | `100` | Number of log lines to show when entering log view |
+
+## Keybindings
+
+| Key | Action |
+|---|---|
+| `j` / `Down` | Move cursor down |
+| `k` / `Up` | Move cursor up |
+| `s` | Restart selected service |
+| `r` | Rebuild selected service (`up -d --build`) |
+| `l` / `Enter` | View logs for selected service |
+| `Esc` / `l` | Exit log view |
+| `G` | Jump to bottom |
+| `gg` | Jump to top |
+| `q` | Quit |
+| `Ctrl+C` | Quit |
+
+## Status Icons
+
+| Icon | Meaning |
+|---|---|
+| Green circle | Running (healthy) |
+| Red circle | Running (unhealthy) |
+| Yellow circle | Rebuilding / Restarting |
+| Gray circle | Stopped |
+
+## Requirements
+
+- Node.js >= 16
+- Docker with `docker compose` (v2) CLI
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { listServices, getStatuses, rebuildService, restartService, tailLogs } = require('./lib/docker');
+const { MODE, createState, statusKey, buildFlatList, moveCursor, selectedEntry } = require('./lib/state');
+const { clearScreen, showCursor, renderListView, renderLogHeader } = require('./lib/renderer');
+
+// --- Config ---
+
+function loadConfig() {
+  const defaults = { composeFiles: [], pollInterval: 3000, logTailLines: 100 };
+
+  // Load from recomposable.json in current working directory
+  const configPath = path.join(process.cwd(), 'recomposable.json');
+  if (fs.existsSync(configPath)) {
+    Object.assign(defaults, JSON.parse(fs.readFileSync(configPath, 'utf8')));
+  }
+
+  // CLI overrides: -f <file> can be repeated
+  const args = process.argv.slice(2);
+  const cliFiles = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-f' && args[i + 1]) {
+      cliFiles.push(args[++i]);
+    }
+  }
+  if (cliFiles.length > 0) {
+    defaults.composeFiles = cliFiles;
+  }
+
+  if (defaults.composeFiles.length === 0) {
+    process.stderr.write('No compose files configured. Add them to recomposable.json or pass -f <file>.\n');
+    process.exit(1);
+  }
+
+  return defaults;
+}
+
+// --- Service Discovery ---
+
+function discoverServices(config) {
+  const groups = [];
+  for (const file of config.composeFiles) {
+    const resolved = path.resolve(file);
+    const label = path.basename(file, path.extname(file)).replace(/^docker-compose\.?/, '') || path.basename(file);
+    let services = [];
+    let error = null;
+    try {
+      services = listServices(resolved);
+    } catch (e) {
+      error = e.message.split('\n')[0].substring(0, 60);
+    }
+    groups.push({ file: resolved, label, services, error });
+  }
+  return groups;
+}
+
+// --- Status Polling ---
+
+function pollStatuses(state) {
+  for (const group of state.groups) {
+    if (group.error) continue;
+    const statuses = getStatuses(group.file);
+    for (const [svc, st] of statuses) {
+      state.statuses.set(statusKey(group.file, svc), st);
+    }
+  }
+}
+
+// --- Rendering ---
+
+function render(state) {
+  let output = clearScreen();
+  if (state.mode === MODE.LIST) {
+    output += renderListView(state);
+  }
+  process.stdout.write(output);
+}
+
+// --- Actions ---
+
+function doRebuild(state) {
+  const entry = selectedEntry(state);
+  if (!entry) return;
+
+  const sk = statusKey(entry.file, entry.service);
+  if (state.rebuilding.has(sk)) return;
+
+  const child = rebuildService(entry.file, entry.service);
+  state.rebuilding.set(sk, child);
+  render(state);
+
+  child.on('close', () => {
+    state.rebuilding.delete(sk);
+    pollStatuses(state);
+    if (state.mode === MODE.LIST) render(state);
+  });
+}
+
+function doRestart(state) {
+  const entry = selectedEntry(state);
+  if (!entry) return;
+
+  const sk = statusKey(entry.file, entry.service);
+  if (state.restarting.has(sk) || state.rebuilding.has(sk)) return;
+
+  const child = restartService(entry.file, entry.service);
+  state.restarting.set(sk, child);
+  render(state);
+
+  child.on('close', () => {
+    state.restarting.delete(sk);
+    pollStatuses(state);
+    if (state.mode === MODE.LIST) render(state);
+  });
+}
+
+function enterLogs(state) {
+  const entry = selectedEntry(state);
+  if (!entry) return;
+
+  state.mode = MODE.LOGS;
+
+  // Clear screen and show log header
+  process.stdout.write(clearScreen() + renderLogHeader(entry.service) + '\n');
+
+  const child = tailLogs(entry.file, entry.service, state.config.logTailLines);
+  state.logChild = child;
+
+  child.stdout.pipe(process.stdout);
+  child.stderr.pipe(process.stdout);
+
+  child.on('close', () => {
+    if (state.logChild === child) {
+      state.logChild = null;
+    }
+  });
+}
+
+function exitLogs(state) {
+  if (state.logChild) {
+    state.logChild.kill('SIGTERM');
+    state.logChild = null;
+  }
+  state.mode = MODE.LIST;
+  pollStatuses(state);
+  render(state);
+}
+
+// --- Input Handling ---
+
+function handleKeypress(state, key) {
+  // Ctrl+C always quits
+  if (key === '\x03') {
+    cleanup(state);
+    process.exit(0);
+  }
+
+  if (state.mode === MODE.LOGS) {
+    if (key === 'l' || key === '\x1b' || key === 'q') {
+      if (key === 'q') {
+        cleanup(state);
+        process.exit(0);
+      }
+      exitLogs(state);
+    }
+    return;
+  }
+
+  // LIST mode
+  switch (key) {
+    case 'j':
+    case '\x1b[B': // Arrow Down
+      moveCursor(state, 1);
+      render(state);
+      break;
+    case 'k':
+    case '\x1b[A': // Arrow Up
+      moveCursor(state, -1);
+      render(state);
+      break;
+    case 'r':
+      doRebuild(state);
+      break;
+    case 's':
+      doRestart(state);
+      break;
+    case 'l':
+    case '\r': // Enter
+      enterLogs(state);
+      break;
+    case 'q':
+      cleanup(state);
+      process.exit(0);
+      break;
+    case 'G': // vim: go to bottom
+      state.cursor = state.flatList.length - 1;
+      render(state);
+      break;
+    case 'g': // gg handled via double-tap buffer below
+      break;
+  }
+}
+
+// --- Arrow key sequence buffering ---
+
+function createInputHandler(state) {
+  let buf = '';
+  let gPending = false;
+
+  return function onData(data) {
+    const str = data.toString();
+
+    // Handle escape sequences (arrow keys)
+    buf += str;
+
+    while (buf.length > 0) {
+      // Check for escape sequences
+      if (buf === '\x1b') {
+        // Could be start of escape sequence — wait for more
+        setTimeout(() => {
+          if (buf === '\x1b') {
+            handleKeypress(state, '\x1b');
+            buf = '';
+          }
+        }, 50);
+        return;
+      }
+
+      if (buf.startsWith('\x1b[A')) {
+        handleKeypress(state, '\x1b[A');
+        buf = buf.slice(3);
+        continue;
+      }
+      if (buf.startsWith('\x1b[B')) {
+        handleKeypress(state, '\x1b[B');
+        buf = buf.slice(3);
+        continue;
+      }
+      if (buf.startsWith('\x1b[')) {
+        // Unknown escape sequence — skip it
+        buf = buf.slice(buf.length);
+        continue;
+      }
+
+      // Single character
+      const ch = buf[0];
+      buf = buf.slice(1);
+
+      // Handle gg (go to top)
+      if (ch === 'g') {
+        if (gPending) {
+          gPending = false;
+          state.cursor = 0;
+          state.scrollOffset = 0;
+          render(state);
+          continue;
+        }
+        gPending = true;
+        setTimeout(() => {
+          if (gPending) {
+            gPending = false;
+            // Single g — ignore
+          }
+        }, 300);
+        continue;
+      }
+
+      gPending = false;
+      handleKeypress(state, ch);
+    }
+  };
+}
+
+// --- Cleanup ---
+
+function cleanup(state) {
+  if (state.logChild) {
+    state.logChild.kill('SIGTERM');
+    state.logChild = null;
+  }
+  for (const [, child] of state.rebuilding) {
+    child.kill('SIGTERM');
+  }
+  state.rebuilding.clear();
+  for (const [, child] of state.restarting) {
+    child.kill('SIGTERM');
+  }
+  state.restarting.clear();
+  if (state.pollTimer) {
+    clearInterval(state.pollTimer);
+  }
+  process.stdout.write(showCursor() + '\x1b[0m');
+}
+
+// --- Main ---
+
+function main() {
+  const config = loadConfig();
+  const state = createState(config);
+
+  // Discover services
+  state.groups = discoverServices(config);
+  state.flatList = buildFlatList(state.groups);
+
+  if (state.flatList.length === 0) {
+    process.stderr.write('No services found in any compose file.\n');
+    process.exit(1);
+  }
+
+  // Initial status poll
+  pollStatuses(state);
+
+  // Setup terminal
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+  }
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', createInputHandler(state));
+
+  // Render
+  render(state);
+
+  // Poll loop
+  state.pollTimer = setInterval(() => {
+    if (state.mode === MODE.LIST) {
+      pollStatuses(state);
+      render(state);
+    }
+  }, config.pollInterval);
+
+  // Terminal resize
+  process.stdout.on('resize', () => {
+    if (state.mode === MODE.LIST) render(state);
+  });
+
+  // Cleanup on exit
+  process.on('exit', () => cleanup(state));
+  process.on('SIGINT', () => {
+    cleanup(state);
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => {
+    cleanup(state);
+    process.exit(0);
+  });
+}
+
+main();

package/lib/docker.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const { execFileSync, spawn } = require('child_process');
+const path = require('path');
+
+function listServices(file) {
+  const cwd = path.dirname(path.resolve(file));
+  const args = ['compose', '-f', path.resolve(file), 'config', '--services'];
+  const out = execFileSync('docker', args, { cwd, encoding: 'utf8', timeout: 10000 });
+  return out.trim().split('\n').filter(Boolean);
+}
+
+function getStatuses(file) {
+  const cwd = path.dirname(path.resolve(file));
+  const args = ['compose', '-f', path.resolve(file), 'ps', '--format', 'json'];
+  let out;
+  try {
+    out = execFileSync('docker', args, { cwd, encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    return new Map();
+  }
+
+  const trimmed = out.trim();
+  if (!trimmed) return new Map();
+
+  const statuses = new Map();
+  let containers;
+
+  // docker compose ps outputs NDJSON (one object per line) or a JSON array
+  if (trimmed.startsWith('[')) {
+    containers = JSON.parse(trimmed);
+  } else {
+    containers = trimmed.split('\n').filter(Boolean).map(line => JSON.parse(line));
+  }
+
+  for (const c of containers) {
+    const name = c.Service || c.Name;
+    const state = (c.State || '').toLowerCase();
+    const health = (c.Health || '').toLowerCase();
+    statuses.set(name, { state, health });
+  }
+
+  return statuses;
+}
+
+function rebuildService(file, service) {
+  const cwd = path.dirname(path.resolve(file));
+  const args = ['compose', '-f', path.resolve(file), 'up', '-d', '--build', service];
+  const child = spawn('docker', args, { cwd, stdio: 'ignore', detached: false });
+  return child;
+}
+
+function tailLogs(file, service, tailLines) {
+  const cwd = path.dirname(path.resolve(file));
+  const args = ['compose', '-f', path.resolve(file), 'logs', '-f', '--tail', String(tailLines), service];
+  const child = spawn('docker', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  return child;
+}
+
+function restartService(file, service) {
+  const cwd = path.dirname(path.resolve(file));
+  const args = ['compose', '-f', path.resolve(file), 'restart', service];
+  const child = spawn('docker', args, { cwd, stdio: 'ignore', detached: false });
+  return child;
+}
+
+module.exports = { listServices, getStatuses, rebuildService, restartService, tailLogs };

package/lib/renderer.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const { statusKey, MODE } = require('./state');
+
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const BOLD = `${ESC}1m`;
+const DIM = `${ESC}2m`;
+const REVERSE = `${ESC}7m`;
+const FG_GREEN = `${ESC}32m`;
+const FG_YELLOW = `${ESC}33m`;
+const FG_RED = `${ESC}31m`;
+const FG_GRAY = `${ESC}90m`;
+const FG_CYAN = `${ESC}36m`;
+const FG_WHITE = `${ESC}37m`;
+
+const LOGO_L = [
+  ` ${BOLD}${FG_CYAN}__      __ _  _   _   _    ___${RESET}`,
+  ` ${BOLD}${FG_CYAN}\\ \\    / /| || | /_\\ | |  | __|${RESET}`,
+  ` ${BOLD}${FG_CYAN} \\ \\/\\/ / | __ |/ _ \\| |__| _|${RESET}`,
+  ` ${BOLD}${FG_CYAN}  \\_/\\_/  |_||_/_/ \\_|____|___|${RESET}`,
+  ``,
+  ` ${DIM}docker compose manager${RESET}`,
+];
+const LOGO_R = [
+  `${FG_CYAN}       .${RESET}`,
+  `${FG_CYAN}     ":"${RESET}`,
+  `${FG_CYAN}   ___:____     |"\\/"|${RESET}`,
+  `${FG_CYAN} ,'        \`.    \\  /${RESET}`,
+  `${FG_CYAN} |  O        \\___/  |${RESET}`,
+  `${FG_CYAN}~^~^~^~^~^~^~^~^~^~^~^~${RESET}`,
+];
+
+function visLen(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+function padVisible(str, width) {
+  const pad = Math.max(0, width - visLen(str));
+  return str + ' '.repeat(pad);
+}
+
+function clearScreen() {
+  return `${ESC}2J${ESC}H${ESC}?25l`;
+}
+
+function showCursor() {
+  return `${ESC}?25h`;
+}
+
+function statusIcon(status, isRebuilding, isRestarting) {
+  if (isRebuilding || isRestarting) return `${FG_YELLOW}\u25CF${RESET}`;
+  if (!status) return `${FG_GRAY}\u25CB${RESET}`;
+
+  const { state, health } = status;
+  if (state === 'running') {
+    if (health === 'unhealthy') return `${FG_RED}\u25CF${RESET}`;
+    return `${FG_GREEN}\u25CF${RESET}`;
+  }
+  if (state === 'restarting') return `${FG_YELLOW}\u25CF${RESET}`;
+  return `${FG_GRAY}\u25CB${RESET}`;
+}
+
+function statusText(status, isRebuilding, isRestarting) {
+  if (isRestarting) return `${FG_YELLOW}RESTARTING...${RESET}`;
+  if (isRebuilding) return `${FG_YELLOW}REBUILDING...${RESET}`;
+  if (!status) return `${FG_GRAY}stopped${RESET}`;
+
+  const { state, health } = status;
+  let text = state;
+  if (health && health !== 'none' && health !== '') {
+    text += ` (${health})`;
+  }
+
+  if (state === 'running') {
+    if (health === 'unhealthy') return `${FG_RED}${text}${RESET}`;
+    return `${FG_GREEN}${text}${RESET}`;
+  }
+  if (state === 'exited') return `${FG_GRAY}${text}${RESET}`;
+  if (state === 'restarting') return `${FG_YELLOW}${text}${RESET}`;
+  return `${DIM}${text}${RESET}`;
+}
+
+function renderListView(state) {
+  const { columns = 80, rows = 24 } = process.stdout;
+  const buf = [];
+
+  // Logo: text left, whale art right
+  const logoGap = 6;
+  const leftWidth = 32;
+  for (let i = 0; i < LOGO_L.length; i++) {
+    const left = padVisible(LOGO_L[i] || '', leftWidth);
+    const right = LOGO_R[i] || '';
+    buf.push(` ${left}${' '.repeat(logoGap)}${right}`);
+  }
+  const help = `${DIM}[S]restart  [R]ebuild  [L]ogs  [Q]uit${RESET}`;
+  buf.push(` ${FG_GRAY}${'─'.repeat(Math.max(0, columns - 2))}${RESET}  ${help}`);
+  buf.push('');
+
+  // Build all display lines
+  const lines = [];
+  let currentGroup = -1;
+
+  for (let i = 0; i < state.flatList.length; i++) {
+    const entry = state.flatList[i];
+
+    // Group header
+    if (entry.groupIdx !== currentGroup) {
+      currentGroup = entry.groupIdx;
+      const group = state.groups[entry.groupIdx];
+      if (lines.length > 0) lines.push({ type: 'blank' });
+      const label = ` ${BOLD}${group.label}${RESET}`;
+      if (group.error) {
+        lines.push({ type: 'header', text: `${label}  ${FG_RED}(${group.error})${RESET}` });
+      } else {
+        lines.push({ type: 'header', text: label });
+      }
+    }
+
+    const sk = statusKey(entry.file, entry.service);
+    const st = state.statuses.get(sk);
+    const rebuilding = state.rebuilding.has(sk);
+    const restarting = state.restarting.has(sk);
+    const icon = statusIcon(st, rebuilding, restarting);
+    const stext = statusText(st, rebuilding, restarting);
+    const name = entry.service.padEnd(30);
+    const pointer = i === state.cursor ? `${REVERSE}` : '';
+    const endPointer = i === state.cursor ? `${RESET}` : '';
+
+    lines.push({
+      type: 'service',
+      text: `${pointer}   ${icon} ${FG_WHITE}${name}${RESET} ${stext}${endPointer}`,
+      flatIdx: i,
+    });
+  }
+
+  // Scrolling
+  const availableRows = rows - (LOGO_L.length + 3); // logo + ruler + blank + bottom margin
+  const serviceLines = lines.filter(l => l.type === 'service');
+
+  // Find line index of cursor
+  const cursorLineIdx = lines.findIndex(l => l.type === 'service' && l.flatIdx === state.cursor);
+
+  // Adjust scroll offset
+  if (cursorLineIdx < state.scrollOffset) {
+    state.scrollOffset = cursorLineIdx;
+  } else if (cursorLineIdx >= state.scrollOffset + availableRows) {
+    state.scrollOffset = cursorLineIdx - availableRows + 1;
+  }
+  state.scrollOffset = Math.max(0, Math.min(lines.length - availableRows, state.scrollOffset));
+
+  const visible = lines.slice(state.scrollOffset, state.scrollOffset + availableRows);
+  for (const line of visible) {
+    buf.push(line.text || '');
+  }
+
+  return buf.join('\n');
+}
+
+function renderLogHeader(serviceName) {
+  const { columns = 80 } = process.stdout;
+  const title = `${BOLD}${FG_CYAN} whale${RESET} ${FG_GRAY}>${RESET} ${BOLD}${serviceName}${RESET} ${DIM}logs${RESET}`;
+  const help = `${DIM}[L] or [Esc] back${RESET}`;
+  const pad = Math.max(0, columns - serviceName.length - 21 - 17);
+  const buf = [];
+  buf.push(title + ' '.repeat(pad) + help);
+  buf.push(` ${FG_GRAY}${'─'.repeat(Math.max(0, columns - 2))}${RESET}`);
+  return buf.join('\n');
+}
+
+module.exports = { clearScreen, showCursor, renderListView, renderLogHeader };

package/lib/state.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const MODE = { LIST: 'LIST', LOGS: 'LOGS' };
+
+function createState(config) {
+  return {
+    mode: MODE.LIST,
+    groups: [],       // [{ file, label, services: string[], error: string|null }]
+    flatList: [],     // [{ groupIdx, serviceIdx, service, file }]
+    cursor: 0,
+    statuses: new Map(),   // "file::service" -> { state, health }
+    rebuilding: new Map(), // "file::service" -> childProcess
+    restarting: new Map(), // "file::service" -> childProcess
+    logChild: null,
+    scrollOffset: 0,
+    config,
+  };
+}
+
+function statusKey(file, service) {
+  return `${file}::${service}`;
+}
+
+function buildFlatList(groups) {
+  const list = [];
+  for (let gi = 0; gi < groups.length; gi++) {
+    const g = groups[gi];
+    for (let si = 0; si < g.services.length; si++) {
+      list.push({ groupIdx: gi, serviceIdx: si, service: g.services[si], file: g.file });
+    }
+  }
+  return list;
+}
+
+function moveCursor(state, delta) {
+  if (state.flatList.length === 0) return;
+  state.cursor = Math.max(0, Math.min(state.flatList.length - 1, state.cursor + delta));
+}
+
+function selectedEntry(state) {
+  return state.flatList[state.cursor] || null;
+}
+
+module.exports = { MODE, createState, statusKey, buildFlatList, moveCursor, selectedEntry };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "recomposable",
+  "version": "1.0.0",
+  "description": "Docker Compose TUI manager with vim keybindings — monitor, restart, rebuild, and tail logs for your services",
+  "main": "index.js",
+  "bin": {
+    "recomposable": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "lib/"
+  ],
+  "keywords": [
+    "docker",
+    "docker-compose",
+    "compose",
+    "tui",
+    "cli",
+    "terminal",
+    "devops",
+    "containers",
+    "vim"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/janvandorth/recomposable.git"
+  },
+  "author": "Jan van Dorth",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}