cligr 1.0.5 → 1.0.7

package/docs/superpowers/specs/2026-04-13-serve-command-design.md

@@ -0,0 +1,93 @@
+# Design: `cligr serve` Command
+
+## Goal
+Add a `serve` command that starts an HTTP server with a web UI for toggling groups and individual items in `.cligr.yml`. Toggling an item changes a `disabledItems` list in config and restarts the running group. The UI receives real-time updates via Server-Sent Events (SSE).
+
+## 1. Architecture Overview
+
+Running `cligr serve` starts an HTTP server on a default port (`7373`, configurable via `--port`). The UI shows all groups from `.cligr.yml`, each with:
+- A master checkbox to start/stop the entire group.
+- Per-item checkboxes to enable/disable individual items.
+
+### Core Components
+- **`ConfigLoader`**: Gains `saveConfig()` and `toggleItem()` to persist `disabledItems` changes back to `.cligr.yml`.
+- **`ProcessManager`**: Extends `EventEmitter` to emit events (`group-started`, `group-stopped`, `item-restarted`, `process-log`). Gains `restartGroup()`.
+- **`serve.ts` command**: Sets up HTTP + SSE server; wires UI actions to `ConfigLoader` and `ProcessManager`.
+- **UI**: Single-page HTML served inline from memory (no extra files needed).
+
+## 2. Config Changes: `disabledItems`
+
+Each `GroupConfig` gains an optional `disabledItems` string array:
+
+```yaml
+groups:
+  myapp:
+    tool: kubefwd
+    restart: yes
+    disabledItems:
+      - service2
+    items:
+      service1: "8080,80"
+      service2: "8081,80"
+```
+
+### ConfigLoader API Additions
+- `saveConfig(config: CliGrConfig): void` — writes the full config back to the YAML file while preserving structure.
+- `toggleItem(groupName: string, itemName: string, enabled: boolean): void` — adds/removes the item from `disabledItems` and calls `saveConfig()`.
+
+### Filtering
+When loading a group for execution (`upCommand` or `serve`), items present in `disabledItems` are filtered out before building `ProcessItem`s.
+
+## 3. HTTP API & SSE
+
+| Method | Endpoint | Body | Description |
+|--------|----------|------|-------------|
+| GET | `/` | — | Serves the HTML UI |
+| GET | `/api/groups` | — | Returns all groups, items, running state, and `disabledItems` |
+| POST | `/api/groups/:name/toggle` | `{ enabled: boolean }` | Starts or stops a group |
+| POST | `/api/groups/:name/items/:item/toggle` | `{ enabled: boolean }` | Enables/disables an item |
+| GET | `/api/events` | — | SSE stream for live updates |
+
+### SSE Event Types
+- `status` — Sent whenever a group starts/stops or an item is toggled. Payload includes current state of all groups.
+- `log` — Sent when a managed process writes to stdout/stderr. Payload: `{ group, item, line, isError }`.
+
+## 4. UI Behavior
+
+- **Group header**: Shows group name, tool, and a checkbox. Checked = running; unchecked = stopped.
+- **Item list**: Each item has a checkbox. Checked = enabled; unchecked = disabled.
+- **Live log panel**: Scrollable panel showing the last ~500 lines, prefixed `[group/item]`.
+
+### Interaction Rules
+- **Group checkbox toggle**: Checking starts the group with currently enabled items. Unchecking stops the whole group via `ProcessManager.killGroup()`.
+- **Item checkbox toggle**: If the group is running, persist the `disabledItems` change, then call `ProcessManager.restartGroup()` (kill previous processes, respawn with the new enabled set). If the group is not running, only persist the config change.
+- **Log auto-scroll**: New lines scroll to bottom unless the user has manually scrolled up.
+
+## 5. ProcessManager Changes
+
+`ProcessManager` will extend Node.js `EventEmitter`.
+
+### New Methods
+- `restartGroup(groupName, items, restartPolicy)` — kills existing processes, removes the group from the map, then re-spawns with the given items.
+
+### Emitted Events
+- `group-started` `(groupName)`
+- `group-stopped` `(groupName)`
+- `item-restarted` `(groupName, itemName)`
+- `process-log` `(groupName, itemName, line: string, isError: boolean)` — stdout/stderr data is split on newlines so only complete lines are emitted
+
+The `serve` command subscribes to these events and forwards them over SSE.
+
+## 6. Error Handling
+
+- **Config write failure**: Return HTTP 500. The UI re-fetches status on error and reverts the checkbox.
+- **Group spawn failure**: Emit a `status` event with an `error` field; UI shows an error banner.
+- **Port in use**: Print `Port 7373 is already in use` and exit with code 1.
+- **Process crash loop**: Existing `ProcessManager` behavior (stop restarting after 3 crashes in 10s). Logged to UI via `process-log` events.
+
+## 7. Testing Approach
+
+- `ConfigLoader`: test `saveConfig()` round-trip and `disabledItems` filtering.
+- `serve` command: test that the HTTP server starts and `/api/groups` returns the expected JSON.
+- SSE endpoint: test that `ProcessManager` events are forwarded as SSE messages.
+- No browser-based tests; test HTTP and SSE semantics directly via HTTP clients.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "cligr",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "main": "dist/index.js",
   "bin": {
-    "cligr": "./dist/index.js"
+    "cligr": "dist/index.js"
   },
   "type": "module",
-  "author": "zerr",
+  "author": "zerrdev",
   "license": "MIT",
   "scripts": {
     "build": "node scripts/build.js",

package/scripts/test.js

@@ -6,13 +6,10 @@
  */
 
 import { build } from 'esbuild';
-import { exec } from 'child_process';
-import { promisify } from 'util';
+import { spawnSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-
-const execAsync = promisify(exec);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -99,22 +96,29 @@ async function buildTests(skipBlocking = false) {
   return testFiles.length;
 }
 
-async function runTests(verbose = false) {
+function runTests(verbose = false) {
   const testFiles = fs.readdirSync(path.join(DIST_DIR, 'integration'))
     .filter(f => f.endsWith('.test.js'))
-    .map(f => path.join(DIST_DIR, 'integration', f))
-    .join(' ');
+    .map(f => path.join(DIST_DIR, 'integration', f));
 
-  const verboseFlag = verbose ? '--verbose' : '';
-  const command = `node --test ${verboseFlag} ${testFiles}`;
+  const args = ['--test'];
+  if (verbose) {
+    args.push('--verbose');
+  }
+  args.push(...testFiles);
 
   console.log('\nRunning tests...\n');
-  const { stdout, stderr } = await execAsync(command, {
+  const result = spawnSync('node', args, {
     stdio: 'inherit',
-    cwd: PROJECT_ROOT
+    cwd: PROJECT_ROOT,
+    shell: true
   });
 
-  return { stdout, stderr };
+  if (result.status !== 0) {
+    throw new Error(`Tests failed with exit code ${result.status}`);
+  }
+
+  return { status: result.status };
 }
 
 async function cleanupSourceModules() {
@@ -142,7 +146,7 @@ async function main() {
   try {
     await buildSourceModules();
     await buildTests(!includeBlocking);
-    await runTests(verbose);
+    runTests(verbose);
 
     // Clean up
     cleanupSourceModules();

package/src/commands/groups.ts

@@ -29,7 +29,7 @@ export async function groupsCommand(verbose: boolean): Promise<number> {
           name,
           tool: group.tool || '(none)',
           restart: group.restart || '(none)',
-          itemCount: group.items.length,
+          itemCount: Object.keys(group.items).length,
         });
       }
 

package/src/commands/ls.ts

@@ -11,16 +11,20 @@ export async function lsCommand(groupName: string): Promise<number> {
     console.log(`Restart: ${config.restart}`);
     console.log('\nItems:');
 
-    for (const item of config.items) {
-      // Show the full item string as-is in the output
-      console.log(`  - ${item}`);
+    const disabled = new Set(config.disabledItems || []);
+    for (const [name, value] of Object.entries(config.items)) {
+      const marker = disabled.has(name) ? ' [disabled]' : '';
+      console.log(`  ${name}: ${value}${marker}`);
     }
 
     console.log('');
 
     return 0;
-  } catch (err) {
-    console.error((err as Error).message);
-    return 1;
+  } catch (error) {
+    if (error instanceof Error && error.name === 'ConfigError') {
+      console.error(error.message);
+      return 1;
+    }
+    throw error;
   }
 }

package/src/commands/serve.ts

@@ -0,0 +1,360 @@
+import http from 'http';
+import { ConfigLoader } from '../config/loader.js';
+import { ProcessManager } from '../process/manager.js';
+import { TemplateExpander } from '../process/template.js';
+
+export async function serveCommand(portArg?: string): Promise<number> {
+  const port = portArg ? parseInt(portArg, 10) : 7373;
+  const loader = new ConfigLoader();
+  const manager = new ProcessManager();
+
+  // Clean up any stale PID files on startup
+  await manager.cleanupStalePids();
+
+  const clients: http.ServerResponse[] = [];
+
+  const sendEvent = (event: string, data: unknown) => {
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (let i = clients.length - 1; i >= 0; i--) {
+      const client = clients[i];
+      try {
+        client.write(payload);
+      } catch {
+        clients.splice(i, 1);
+        try { client.end(); } catch { /* ignore */ }
+      }
+    }
+  };
+
+  manager.on('group-started', (groupName) => {
+    sendEvent('status', { type: 'group-started', groupName });
+  });
+
+  manager.on('group-stopped', (groupName) => {
+    sendEvent('status', { type: 'group-stopped', groupName });
+  });
+
+  manager.on('item-restarted', (groupName, itemName) => {
+    sendEvent('status', { type: 'item-restarted', groupName, itemName });
+  });
+
+  manager.on('process-log', (groupName, itemName, line, isError) => {
+    sendEvent('log', { group: groupName, item: itemName, line, isError });
+  });
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || '/', `http://localhost:${port}`);
+
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (url.pathname === '/') {
+      res.setHeader('Content-Type', 'text/html');
+      res.writeHead(200);
+      res.end(serveHtml());
+      return;
+    }
+
+    if (url.pathname === '/api/groups') {
+      try {
+        const config = loader.load();
+        const groups = Object.entries(config.groups).map(([name, group]) => ({
+          name,
+          tool: group.tool,
+          restart: group.restart,
+          items: Object.entries(group.items).map(([itemName, value]) => ({
+            name: itemName,
+            value,
+            enabled: !(group.disabledItems || []).includes(itemName),
+          })),
+          running: manager.isGroupRunning(name),
+        }));
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(200);
+        res.end(JSON.stringify({ groups }));
+      } catch (err) {
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(500);
+        res.end(JSON.stringify({ error: (err as Error).message }));
+      }
+      return;
+    }
+
+    if (url.pathname === '/api/events') {
+      res.setHeader('Content-Type', 'text/event-stream');
+      res.setHeader('Cache-Control', 'no-cache');
+      res.setHeader('Connection', 'keep-alive');
+      res.writeHead(200);
+      res.write(':ok\n\n');
+      clients.push(res);
+      req.on('close', () => {
+        const index = clients.indexOf(res);
+        if (index !== -1) clients.splice(index, 1);
+      });
+      return;
+    }
+
+    const toggleMatch = url.pathname.match(/^\/api\/groups\/([^/]+)\/toggle$/);
+    if (toggleMatch && req.method === 'POST') {
+      const groupName = decodeURIComponent(toggleMatch[1]);
+      let body = '';
+      req.on('data', (chunk) => body += chunk);
+      req.on('end', async () => {
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          res.writeHead(400);
+          res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          return;
+        }
+        const { enabled } = parsed;
+        try {
+          if (enabled) {
+            const { config, items, tool, toolTemplate, params } = loader.getGroup(groupName);
+            const processItems = items.map((item, index) =>
+              TemplateExpander.parseItem(tool, toolTemplate, item, index, params)
+            );
+            manager.spawnGroup(groupName, processItems, config.restart);
+          } else {
+            await manager.killGroup(groupName);
+          }
+          res.setHeader('Content-Type', 'application/json');
+          res.writeHead(200);
+          res.end(JSON.stringify({ success: true }));
+        } catch (err) {
+          res.setHeader('Content-Type', 'application/json');
+          res.writeHead(500);
+          res.end(JSON.stringify({ error: (err as Error).message }));
+        }
+      });
+      return;
+    }
+
+    const itemToggleMatch = url.pathname.match(/^\/api\/groups\/([^/]+)\/items\/([^/]+)\/toggle$/);
+    if (itemToggleMatch && req.method === 'POST') {
+      const groupName = decodeURIComponent(itemToggleMatch[1]);
+      const itemName = decodeURIComponent(itemToggleMatch[2]);
+      let body = '';
+      req.on('data', (chunk) => body += chunk);
+      req.on('end', async () => {
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          res.writeHead(400);
+          res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          return;
+        }
+        const { enabled } = parsed;
+        try {
+          loader.toggleItem(groupName, itemName, enabled);
+
+          if (manager.isGroupRunning(groupName)) {
+            const { config, items, tool, toolTemplate, params } = loader.getGroup(groupName);
+            const processItems = items.map((item, index) =>
+              TemplateExpander.parseItem(tool, toolTemplate, item, index, params)
+            );
+            await manager.restartGroup(groupName, processItems, config.restart);
+          }
+
+          res.setHeader('Content-Type', 'application/json');
+          res.writeHead(200);
+          res.end(JSON.stringify({ success: true }));
+        } catch (err) {
+          res.setHeader('Content-Type', 'application/json');
+          res.writeHead(500);
+          res.end(JSON.stringify({ error: (err as Error).message }));
+        }
+      });
+      return;
+    }
+
+    res.writeHead(404);
+    res.end('Not found');
+  });
+
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`Port ${port} is already in use`);
+      process.exit(1);
+    } else {
+      console.error('Server error:', err);
+      process.exit(2);
+    }
+  });
+
+  let resolveCommand: (value: number) => void;
+  const commandPromise = new Promise<number>((resolve) => {
+    resolveCommand = resolve;
+  });
+
+  const shutdown = async () => {
+    console.log('\nShutting down...');
+    server.close();
+    await manager.killAll();
+    resolveCommand(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  server.listen(port, () => {
+    console.log(`cligr serve running at http://localhost:${port}`);
+  });
+
+  return commandPromise;
+}
+
+function serveHtml(): string {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>cligr serve</title>
+  <style>
+    * { box-sizing: border-box; }
+    html, body { height: 100%; margin: 0; }
+    body { font-family: system-ui, sans-serif; display: flex; flex-direction: column; }
+    h1 { font-size: 1.25rem; margin: 0; padding: 0.75rem 1rem; border-bottom: 1px solid #ccc; background: #f8f8f8; }
+    .container { display: flex; flex: 1; overflow: hidden; }
+    .sidebar { width: 320px; min-width: 180px; max-width: 60vw; border-right: 1px solid #ccc; padding: 1rem; overflow-y: auto; background: #fafafa; }
+    .resizer { width: 6px; background: #e0e0e0; cursor: col-resize; flex-shrink: 0; }
+    .resizer:hover { background: #bbb; }
+    .main { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+    .main h2 { font-size: 1rem; margin: 0; padding: 0.5rem 1rem; border-bottom: 1px solid #ccc; background: #f0f0f0; }
+    .group { border: 1px solid #ccc; border-radius: 6px; padding: 0.75rem; margin: 0 0 0.75rem 0; background: #fff; }
+    .group-header { display: flex; align-items: center; gap: 0.5rem; font-weight: bold; font-size: 1rem; }
+    .items { margin: 0.5rem 0 0 1.25rem; }
+    .item { display: flex; align-items: center; gap: 0.4rem; margin: 0.2rem 0; font-size: 0.9rem; }
+    .logs { flex: 1; background: #111; color: #0f0; font-family: monospace; font-size: 0.85rem; overflow-y: auto; padding: 0.75rem; white-space: pre-wrap; }
+    .error { color: #f55; }
+  </style>
+</head>
+<body>
+  <h1>cligr serve</h1>
+  <div class="container">
+    <div class="sidebar" id="groups"></div>
+    <div class="resizer" id="resizer"></div>
+    <div class="main">
+      <h2>Console</h2>
+      <div class="logs" id="logs"></div>
+    </div>
+  </div>
+
+  <script>
+    const groupsEl = document.getElementById('groups');
+    const logsEl = document.getElementById('logs');
+    const resizer = document.getElementById('resizer');
+    let autoScroll = true;
+
+    resizer.addEventListener('mousedown', (e) => {
+      e.preventDefault();
+      document.body.style.cursor = 'col-resize';
+      const startX = e.clientX;
+      const startWidth = groupsEl.offsetWidth;
+
+      const onMove = (ev) => {
+        const newWidth = startWidth + (ev.clientX - startX);
+        groupsEl.style.width = Math.max(180, Math.min(newWidth, window.innerWidth * 0.6)) + 'px';
+      };
+
+      const onUp = () => {
+        document.removeEventListener('mousemove', onMove);
+        document.removeEventListener('mouseup', onUp);
+        document.body.style.cursor = '';
+      };
+
+      document.addEventListener('mousemove', onMove);
+      document.addEventListener('mouseup', onUp);
+    });
+
+    async function fetchGroups() {
+      const res = await fetch('/api/groups');
+      const data = await res.json();
+      renderGroups(data.groups);
+    }
+
+    function renderGroups(groups) {
+      groupsEl.innerHTML = '';
+      for (const g of groups) {
+        const div = document.createElement('div');
+        div.className = 'group';
+
+        const header = document.createElement('div');
+        header.className = 'group-header';
+        const checkbox = document.createElement('input');
+        checkbox.type = 'checkbox';
+        checkbox.checked = g.running;
+        checkbox.onchange = async () => {
+          await fetch(\`/api/groups/\${encodeURIComponent(g.name)}/toggle\`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ enabled: checkbox.checked })
+          });
+        };
+        header.appendChild(checkbox);
+        header.appendChild(document.createTextNode(g.name + ' (' + g.tool + ')' + (g.running ? ' - running' : '')));
+        div.appendChild(header);
+
+        const itemsDiv = document.createElement('div');
+        itemsDiv.className = 'items';
+        for (const item of g.items) {
+          const itemDiv = document.createElement('div');
+          itemDiv.className = 'item';
+          const itemCb = document.createElement('input');
+          itemCb.type = 'checkbox';
+          itemCb.checked = item.enabled;
+          itemCb.onchange = async () => {
+            await fetch(\`/api/groups/\${encodeURIComponent(g.name)}/items/\${encodeURIComponent(item.name)}/toggle\`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ enabled: itemCb.checked })
+            });
+          };
+          itemDiv.appendChild(itemCb);
+          itemDiv.appendChild(document.createTextNode(item.name + ': ' + item.value));
+          itemsDiv.appendChild(itemDiv);
+        }
+        div.appendChild(itemsDiv);
+        groupsEl.appendChild(div);
+      }
+    }
+
+    logsEl.addEventListener('scroll', () => {
+      autoScroll = logsEl.scrollTop + logsEl.clientHeight >= logsEl.scrollHeight - 10;
+    });
+
+    function appendLog(line, isError) {
+      const span = document.createElement('div');
+      span.textContent = line;
+      if (isError) span.className = 'error';
+      logsEl.appendChild(span);
+      if (autoScroll) logsEl.scrollTop = logsEl.scrollHeight;
+    }
+
+    const evtSource = new EventSource('/api/events');
+    evtSource.addEventListener('status', (e) => {
+      fetchGroups();
+    });
+    evtSource.addEventListener('log', (e) => {
+      const data = JSON.parse(e.data);
+      appendLog(\`[\${data.group}/\${data.item}] \${data.line}\`, data.isError);
+    });
+    evtSource.onerror = () => {
+      appendLog('[SSE connection error]', true);
+    };
+
+    fetchGroups();
+  </script>
+</body>
+</html>`;
+}

package/src/commands/up.ts

@@ -13,17 +13,17 @@ export async function upCommand(groupName: string): Promise<number> {
     await pidStore.cleanupStalePids();
 
     // Load group config
-    const { config, tool, toolTemplate, params } = loader.getGroup(groupName);
+    const { config, items, tool, toolTemplate, params } = loader.getGroup(groupName);
 
     // Build process items
-    const items = config.items.map((itemStr, index) =>
-      TemplateExpander.parseItem(tool, toolTemplate, itemStr, index, params)
+    const processItems = items.map((item, index) =>
+      TemplateExpander.parseItem(tool, toolTemplate, item, index, params)
     );
 
     // Spawn all processes
-    manager.spawnGroup(groupName, items, config.restart);
+    manager.spawnGroup(groupName, processItems, config.restart);
 
-    console.log(`Started group ${groupName} with ${items.length} process(es)`);
+    console.log(`Started group ${groupName} with ${processItems.length} process(es)`);
     console.log('Press Ctrl+C to stop...');
 
     // Wait for signals