@celilo/cli 0.1.0

package/src/cli/fuel-gauge.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Fuel-Gauge Tests
+ * Tests pure rendering functions without terminal interaction
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { FuelGauge } from './fuel-gauge';
+
+describe('FuelGauge', () => {
+  describe('buildProgressBar', () => {
+    test('builds bar with gradient at position 0 moving right', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const bar = gauge.buildProgressBar(0, 20, 1, false);
+
+      // Gradient (4 chars) at position 0, moving right: ░▒▓█
+      expect(bar).toBe('░▒▓█················');
+    });
+
+    test('builds bar with gradient at position 0 moving left', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const bar = gauge.buildProgressBar(0, 20, -1, false);
+
+      // Gradient (4 chars) at position 0, moving left: █▓▒░
+      expect(bar).toBe('█▓▒░················');
+    });
+
+    test('builds bar with gradient at middle position moving right', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const bar = gauge.buildProgressBar(5, 20, 1, false);
+
+      // Gradient at position 5, moving right
+      expect(bar).toBe('·····░▒▓█···········');
+    });
+
+    test('builds bar with gradient at middle position moving left', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const bar = gauge.buildProgressBar(5, 20, -1, false);
+
+      // Gradient at position 5, moving left
+      expect(bar).toBe('·····█▓▒░···········');
+    });
+
+    test('builds bar with gradient at end position', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const bar = gauge.buildProgressBar(16, 20, 1, false);
+
+      // Gradient at position 16 (near right edge)
+      expect(bar).toBe('················░▒▓█');
+    });
+
+    test('handles narrow bar width', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const bar = gauge.buildProgressBar(0, 15, 1, false);
+
+      expect(bar).toHaveLength(15);
+      expect(bar).toMatch(/^[░▒▓█]+·+$/);
+    });
+
+    test('handles wide bar width', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const bar = gauge.buildProgressBar(20, 100, 1, false);
+
+      expect(bar).toHaveLength(100);
+      expect(bar).toMatch(/^·+[░▒▓█]+·+$/);
+    });
+
+    test('pulses front block when waiting (pulse=true, moving right)', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      // pulseState starts at 0, front block (right-most) alternates █ -> ▓
+      const bar1 = gauge.buildProgressBar(0, 20, 1, true);
+      expect(bar1).toBe('░▒▓█················'); // pulseState % 2 = 0, shows solid █
+
+      // After pulseState increments to 1, front block shows next level
+      // (Note: pulseState is private, we can't easily test the actual alternation)
+    });
+
+    test('pulses front block when waiting (pulse=true, moving left)', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      // pulseState starts at 0, front block (left-most) alternates █ -> ▓
+      const bar1 = gauge.buildProgressBar(0, 20, -1, true);
+      expect(bar1).toBe('█▓▒░················'); // pulseState % 2 = 0, shows solid █
+    });
+  });
+
+  describe('formatOutputLines', () => {
+    test('returns last N lines', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const lines = ['Line 1', 'Line 2', 'Line 3', 'Line 4', 'Line 5'];
+
+      const formatted = gauge.formatOutputLines(lines, 3);
+
+      expect(formatted).toHaveLength(3);
+      expect(formatted[0]).toContain('Line 3');
+      expect(formatted[1]).toContain('Line 4');
+      expect(formatted[2]).toContain('Line 5');
+    });
+
+    test('pads lines with indentation', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const lines = ['Test output'];
+
+      const formatted = gauge.formatOutputLines(lines, 1);
+
+      expect(formatted[0]).toBe('  Test output');
+    });
+
+    test('truncates long lines', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const longLine = 'a'.repeat(200);
+
+      const formatted = gauge.formatOutputLines([longLine], 1);
+
+      // Should be truncated with ...
+      expect(formatted[0].length).toBeLessThan(200);
+      expect(formatted[0]).toMatch(/\.\.\.$/);
+    });
+
+    test('handles empty lines array', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      const formatted = gauge.formatOutputLines([], 3);
+
+      expect(formatted).toHaveLength(0);
+    });
+
+    test('handles fewer lines than max', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+      const lines = ['Line 1', 'Line 2'];
+
+      const formatted = gauge.formatOutputLines(lines, 5);
+
+      // Should return all available lines
+      expect(formatted).toHaveLength(2);
+    });
+  });
+
+  describe('addOutput and getOutput', () => {
+    test('stores output lines', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      gauge.addOutput('Line 1');
+      gauge.addOutput('Line 2');
+      gauge.addOutput('Line 3');
+
+      const output = gauge.getOutput();
+      expect(output).toEqual(['Line 1', 'Line 2', 'Line 3']);
+    });
+
+    test('strips ANSI codes from output', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      // Add line with ANSI color codes
+      gauge.addOutput('\x1b[31mRed text\x1b[0m');
+      gauge.addOutput('\x1b[36mCyan text\x1b[0m');
+
+      const output = gauge.getOutput();
+      expect(output[0]).toBe('Red text');
+      expect(output[1]).toBe('Cyan text');
+    });
+
+    test('limits stored lines to 100', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      // Add 150 lines
+      for (let i = 0; i < 150; i++) {
+        gauge.addOutput(`Line ${i}`);
+      }
+
+      const output = gauge.getOutput();
+      expect(output).toHaveLength(100);
+      // Should have last 100 lines (50-149)
+      expect(output[0]).toBe('Line 50');
+      expect(output[99]).toBe('Line 149');
+    });
+  });
+
+  describe('start and stop', () => {
+    test('start sets running state in test mode', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      gauge.start();
+
+      // Should not throw and should be testable
+      expect(gauge).toBeDefined();
+    });
+
+    test('stop clears running state in test mode', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      gauge.start();
+      gauge.stop(true);
+
+      // Should complete without error
+      expect(gauge).toBeDefined();
+    });
+
+    test('handles stop before start', () => {
+      const gauge = new FuelGauge('Test', { skipAnimation: true });
+
+      // Should not throw
+      gauge.stop(true);
+
+      expect(gauge).toBeDefined();
+    });
+  });
+});

package/src/cli/fuel-gauge.ts

@@ -0,0 +1,405 @@
+/**
+ * Fuel-Gauge Progress Indicator
+ *
+ * Custom Cylon-style progress bar with scrolling output preview
+ * Features:
+ * - Back-and-forth animated bar (like Battlestar Galactica Cylon eye)
+ * - 3-4 lines of scrolling greyed-out output above the bar
+ * - On success: clears output, shows only success message
+ * - On error: shows last 8 lines of output for debugging
+ */
+
+import { stdout } from 'node:process';
+import * as p from '@clack/prompts';
+
+/**
+ * ANSI color codes for terminal output
+ */
+const colors = {
+  cyan: (text: string) => `\x1b[36m${text}\x1b[0m`,
+  dim: (text: string) => `\x1b[2m${text}\x1b[0m`,
+  mutedPurple: (text: string) => `\x1b[38;5;238m${text}\x1b[0m`, // 256-color very dark gray-purple (barely visible)
+  reset: '\x1b[0m',
+};
+
+export interface FuelGaugeOptions {
+  output?: NodeJS.WriteStream;
+  skipAnimation?: boolean; // For testing
+  onBackground?: () => void; // Callback when ESC pressed
+}
+
+/**
+ * Fuel-Gauge progress indicator with Cylon-style animation
+ *
+ * Rendering strategy: builds the entire frame as a single string and
+ * writes it in one output.write() call to prevent flicker. Uses
+ * "move cursor up N lines" + overwrite rather than clear-then-draw.
+ */
+export class FuelGauge {
+  private title: string;
+  private outputLines: string[] = [];
+  private barPosition = 0;
+  private barDirection = 1; // 1 = right, -1 = left
+  private intervalId: NodeJS.Timeout | null = null;
+  private readonly maxDisplayLines = 4; // Show 3-4 lines of output
+  private readonly errorDisplayLines = 100; // Show full output on error
+  private readonly output: NodeJS.WriteStream;
+  private readonly skipAnimation: boolean;
+  private readonly onBackground?: () => void;
+  private running = false;
+  private hasNewOutput = false; // Track if new output arrived
+  private pulseState = 0; // Track pulse animation state (0-3)
+  private keyListener?: (chunk: Buffer) => void;
+  private sigintHandler?: () => void;
+  private alreadyCleanedUp = false; // Track if we've already cleaned up terminal
+  private linesDrawn = 0; // Track exactly how many lines were drawn last frame
+
+  constructor(title: string, options: FuelGaugeOptions = {}) {
+    this.title = title;
+    this.output = options.output || stdout;
+    this.skipAnimation = options.skipAnimation || false;
+    this.onBackground = options.onBackground;
+  }
+
+  /**
+   * Start the fuel-gauge animation
+   */
+  start(): void {
+    if (this.skipAnimation) {
+      // Test mode: just track state
+      this.running = true;
+      return;
+    }
+
+    this.running = true;
+
+    // Hide cursor
+    this.output.write('\x1B[?25l');
+
+    // Set up SIGINT handler to restore terminal on Ctrl+C (not in test mode)
+    if (!this.skipAnimation) {
+      this.sigintHandler = () => {
+        if (this.alreadyCleanedUp) {
+          process.exit(130);
+        }
+        this.alreadyCleanedUp = true;
+
+        // Restore terminal: clear gauge area and show cursor
+        this.writeClearSequence();
+        this.output.write('\x1B[?25h');
+
+        if (this.intervalId) {
+          clearInterval(this.intervalId);
+          this.intervalId = null;
+        }
+        if (this.keyListener && process.stdin.isTTY) {
+          process.stdin.off('data', this.keyListener);
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+        }
+
+        process.exit(130);
+      };
+      process.on('SIGINT', this.sigintHandler);
+    }
+
+    // Set up keyboard listener for ESC key and Ctrl+C
+    if (this.onBackground && process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+
+      this.keyListener = (chunk: Buffer) => {
+        if (chunk[0] === 0x03) {
+          // Ctrl+C — raw mode swallows SIGINT, handle manually
+          if (this.sigintHandler) this.sigintHandler();
+        } else if (chunk[0] === 0x1b && chunk.length === 1) {
+          this.background();
+        }
+      };
+
+      process.stdin.on('data', this.keyListener);
+    }
+
+    // Draw initial frame
+    this.writeFrame();
+
+    // Animate at 100ms intervals
+    this.intervalId = setInterval(() => {
+      this.render();
+    }, 100);
+  }
+
+  /**
+   * Add output line (will be shown in scrolling preview)
+   */
+  addOutput(line: string): void {
+    const cleaned = this.stripAnsi(line);
+    this.outputLines.push(cleaned);
+
+    if (this.outputLines.length > 100) {
+      this.outputLines.shift();
+    }
+
+    this.hasNewOutput = true;
+  }
+
+  /**
+   * Background the animation (user pressed ESC)
+   */
+  private background(): void {
+    if (!this.running) return;
+
+    this.cleanup();
+    p.log.info(`${this.title} (backgrounded)`);
+
+    if (this.onBackground) {
+      this.onBackground();
+    }
+  }
+
+  /**
+   * Stop the animation and finalize
+   */
+  stop(success: boolean): void {
+    if (!this.running) return;
+
+    this.running = false;
+
+    if (this.skipAnimation) {
+      return;
+    }
+
+    this.cleanup();
+
+    if (success) {
+      p.log.success(this.title);
+    } else {
+      p.log.error(this.title);
+      console.log('');
+      console.log(colors.dim('Last output:'));
+      const errorLines = this.outputLines.slice(-this.errorDisplayLines);
+      for (const line of errorLines) {
+        if (line.trim()) {
+          console.log(colors.dim(`  ${line}`));
+        }
+      }
+      console.log('');
+    }
+  }
+
+  /**
+   * Clean up resources (keyboard listener, animation, cursor)
+   */
+  private cleanup(): void {
+    if (this.alreadyCleanedUp) return;
+    this.alreadyCleanedUp = true;
+
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+
+    if (this.sigintHandler) {
+      process.off('SIGINT', this.sigintHandler);
+      this.sigintHandler = undefined;
+    }
+
+    if (this.keyListener && process.stdin.isTTY) {
+      process.stdin.off('data', this.keyListener);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      this.keyListener = undefined;
+    }
+
+    if (!this.skipAnimation) {
+      this.writeClearSequence();
+      this.output.write('\x1B[?25h');
+    }
+  }
+
+  /**
+   * Get all captured output
+   */
+  getOutput(): string[] {
+    return [...this.outputLines];
+  }
+
+  /**
+   * Build progress bar string (pure function for testing)
+   */
+  buildProgressBar(position: number, width: number, direction: number, pulse: boolean): string {
+    const gradient = ['█', '▓', '▒', '░'];
+    const barEmpty = '·';
+    const barLength = gradient.length;
+
+    let bar = '';
+    for (let i = 0; i < width; i++) {
+      const offset = i - position;
+
+      if (offset >= 0 && offset < barLength) {
+        let charIndex: number;
+        let isFrontBlock = false;
+
+        if (direction === 1) {
+          charIndex = barLength - 1 - offset;
+          isFrontBlock = offset === barLength - 1;
+        } else {
+          charIndex = offset;
+          isFrontBlock = offset === 0;
+        }
+
+        if (pulse && isFrontBlock) {
+          const pulseToggle = Math.floor(this.pulseState / 6) % 2;
+          bar += gradient[pulseToggle];
+        } else {
+          bar += gradient[charIndex];
+        }
+      } else {
+        bar += barEmpty;
+      }
+    }
+    return bar;
+  }
+
+  /**
+   * Format output lines for display (pure function for testing)
+   */
+  formatOutputLines(lines: string[], maxLines: number): string[] {
+    const recentLines = lines.slice(-maxLines);
+    const termWidth = this.output.columns || 80;
+    const maxLen = termWidth - 4;
+
+    return recentLines.map((line) => {
+      const truncated = line.length > maxLen ? `${line.slice(0, maxLen - 3)}...` : line;
+      return `  ${truncated}`;
+    });
+  }
+
+  /**
+   * Strip ANSI codes from text
+   */
+  private stripAnsi(text: string): string {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: ESC character needed for ANSI code matching
+    return text.replace(/\u001b\[[0-9;]*m/g, '');
+  }
+
+  /**
+   * Render one frame (called by animation loop)
+   */
+  private render(): void {
+    const termWidth = this.output.columns || 80;
+    const barWidth = Math.max(termWidth - 4, 20);
+
+    if (this.hasNewOutput) {
+      this.barPosition += this.barDirection;
+      if (this.barPosition >= barWidth - 4) {
+        this.barDirection = -1;
+      } else if (this.barPosition <= 0) {
+        this.barDirection = 1;
+      }
+    }
+
+    this.pulseState++;
+
+    // Build frame, move cursor up over previous frame, write new frame
+    // All in a single output.write() to prevent flicker
+    const frame = this.buildFrame();
+    const moveUp = this.linesDrawn > 0 ? `\x1b[${this.linesDrawn}A\r` : '';
+    this.output.write(moveUp + frame);
+
+    this.hasNewOutput = false;
+  }
+
+  /**
+   * Write the initial frame (no cursor movement needed)
+   */
+  private writeFrame(): void {
+    const frame = this.buildFrame();
+    this.output.write(frame);
+  }
+
+  /**
+   * Write a sequence to clear the gauge area (for cleanup/stop)
+   */
+  private writeClearSequence(): void {
+    if (this.linesDrawn <= 0) return;
+    const termWidth = this.output.columns || 80;
+    const blankLine = ' '.repeat(termWidth);
+    // Move up, then overwrite each line with blanks
+    let seq = `\x1b[${this.linesDrawn}A\r`;
+    for (let i = 0; i < this.linesDrawn; i++) {
+      seq += `${blankLine}\n`;
+    }
+    // Move back up to where we started
+    seq += `\x1b[${this.linesDrawn}A\r`;
+    this.output.write(seq);
+    this.linesDrawn = 0;
+  }
+
+  /**
+   * Build the entire frame as a single string.
+   * Each line is padded to terminal width to overwrite previous content.
+   */
+  private buildFrame(): string {
+    const termWidth = this.output.columns || 80;
+    let lineCount = 0;
+    let frame = '';
+
+    const pad = (s: string, visibleLen: number) => {
+      // Pad with spaces to fill the terminal width, clearing any leftover chars
+      const remaining = Math.max(0, termWidth - visibleLen);
+      return s + ' '.repeat(remaining);
+    };
+
+    // Title line
+    const titleText = `▸ ${this.title}`;
+    frame += `${pad(colors.cyan(titleText), titleText.length + 2)}\n`;
+    lineCount++;
+
+    // Output preview lines
+    const displayLines = this.formatOutputLines(this.outputLines, this.maxDisplayLines);
+    for (const line of displayLines) {
+      frame += `${pad(colors.dim(line), line.length)}\n`;
+      lineCount++;
+    }
+
+    // Padding lines
+    const paddingLines = this.maxDisplayLines - displayLines.length;
+    for (let i = 0; i < paddingLines; i++) {
+      frame += `${pad('', 0)}\n`;
+      lineCount++;
+    }
+
+    // Progress bar
+    const hintText = '(esc to bg; ^C to cancel)';
+    const barWidth = Math.max(termWidth - 4 - hintText.length - 2, 20);
+    const shouldPulse = !this.hasNewOutput;
+    const plainBar = this.buildProgressBar(
+      this.barPosition,
+      barWidth,
+      this.barDirection,
+      shouldPulse,
+    );
+
+    // Colorize bar
+    let coloredBar = '  ';
+    let visibleBarLen = 2; // leading spaces
+    for (let i = 0; i < plainBar.length; i++) {
+      const char = plainBar[i];
+      if (char === '·') {
+        coloredBar += colors.mutedPurple('·');
+      } else {
+        coloredBar += colors.cyan(char);
+      }
+      visibleBarLen++;
+    }
+    coloredBar += `  ${colors.mutedPurple(hintText)}`;
+    visibleBarLen += 2 + hintText.length;
+
+    frame += `${pad(coloredBar, visibleBarLen)}\n`;
+    lineCount++;
+
+    this.linesDrawn = lineCount;
+    return frame;
+  }
+}

package/src/cli/generate-zsh-completion.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test';
+import { COMMANDS } from './command-registry';
+import type { CommandDef } from './command-registry';
+import { generateRichZshCompletion } from './generate-zsh-completion';
+
+describe('Zsh Completion Generator', () => {
+  const output = generateRichZshCompletion(COMMANDS);
+
+  test('produces valid compdef header', () => {
+    expect(output).toMatch(/^#compdef celilo/);
+  });
+
+  test('contains auto-generated notice', () => {
+    expect(output).toContain('Auto-generated by: celilo completion zsh');
+    expect(output).toContain('Do not edit manually');
+  });
+
+  test('contains main _celilo function', () => {
+    expect(output).toContain('_celilo()');
+    expect(output).toContain('_celilo_commands()');
+  });
+
+  test('contains all top-level commands in _celilo_commands', () => {
+    for (const cmd of COMMANDS) {
+      expect(output).toContain(`'${cmd.name}:`);
+    }
+  });
+
+  test('generates functions for all commands with subcommands', () => {
+    function checkSubcommands(commands: CommandDef[], path: string[]): void {
+      for (const cmd of commands) {
+        if (cmd.subcommands && cmd.subcommands.length > 0) {
+          const fnName = `_celilo${path.length > 0 ? `_${[...path, cmd.name].join('_')}` : `_${cmd.name}`}`;
+          expect(output).toContain(`${fnName}()`);
+          expect(output).toContain(`${fnName}_commands()`);
+
+          // Recurse
+          checkSubcommands(cmd.subcommands, [...path, cmd.name]);
+        }
+      }
+    }
+    checkSubcommands(COMMANDS, []);
+  });
+
+  test('generates dynamic completion functions for database-backed args', () => {
+    expect(output).toContain('_celilo_module_ids()');
+    expect(output).toContain('_celilo_service_ids()');
+    expect(output).toContain('_celilo_machine_hostnames()');
+    expect(output).toContain('_celilo_capability_names()');
+    expect(output).toContain('_celilo_config_keys()');
+    expect(output).toContain('_celilo_system_config_keys()');
+    expect(output).toContain('_celilo_system_secret_keys()');
+  });
+
+  test('dynamic completions query sqlite3', () => {
+    expect(output).toContain('sqlite3 "$db_path"');
+    expect(output).toContain('SELECT id FROM modules');
+    expect(output).toContain('SELECT service_id, name FROM container_services');
+    expect(output).toContain('SELECT hostname FROM machines');
+    expect(output).toContain('SELECT capability_name, module_id FROM capabilities');
+  });
+
+  test('includes flag completions for commands with flags', () => {
+    // Module import has --target and --auto-generate-secrets
+    expect(output).toContain('--target');
+    expect(output).toContain('--auto-generate-secrets');
+
+    // Machine add has --ip, --ssh-user, etc.
+    expect(output).toContain('--ip');
+    expect(output).toContain('--ssh-user');
+    expect(output).toContain('--ssh-key-file');
+
+    // Service remove has --force
+    expect(output).toContain('--force');
+  });
+
+  test('ends with _celilo invocation', () => {
+    expect(output.trimEnd()).toMatch(/_celilo "\$@"$/);
+  });
+
+  test('all subcommand descriptions are present', () => {
+    function checkDescriptions(commands: CommandDef[]): void {
+      for (const cmd of commands) {
+        if (cmd.subcommands) {
+          for (const sub of cmd.subcommands) {
+            // Description should appear in the _commands function
+            expect(output).toContain(sub.description.replace(/:/g, '\\:'));
+          }
+          checkDescriptions(cmd.subcommands);
+        }
+      }
+    }
+    checkDescriptions(COMMANDS);
+  });
+});