@celilo/cli 0.1.0

package/src/templates/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Template generation types
+ */
+
+/**
+ * Template file to process
+ */
+export interface TemplateFile {
+  sourcePath: string;
+  targetPath: string;
+  content: string;
+}
+
+/**
+ * Generated file output
+ */
+export interface GeneratedFile {
+  path: string;
+  content: string;
+}
+
+/**
+ * Infrastructure information for generated templates
+ */
+export interface InfrastructureInfo {
+  type: 'machine' | 'container_service';
+  machineId?: string;
+  machineName?: string;
+  serviceId?: string;
+  serviceName?: string;
+  zone: string;
+}
+
+/**
+ * Template generation result
+ */
+export interface GenerateSuccess {
+  success: true;
+  files: GeneratedFile[];
+  outputPath: string;
+  infrastructure?: InfrastructureInfo;
+}
+
+export interface GenerateError {
+  success: false;
+  error: string;
+  details?: unknown;
+}
+
+export type GenerateResult = GenerateSuccess | GenerateError;
+
+/**
+ * Template generation options
+ */
+export interface GenerateOptions {
+  moduleId: string;
+  modulePath: string;
+  outputPath: string;
+  db?: ReturnType<typeof import('../db/client').getDb>;
+  /** Skip required variable validation (used by deploy flow which handles interview separately) */
+  skipVariableValidation?: boolean;
+}

package/src/test-utils/INTERACTIVE_PROMPTS.md

@@ -0,0 +1,167 @@
+# Interactive Prompts Testing — `CLIContext` reference
+
+`CLIContext` (in `cli-context.ts`) maintains a single long-lived CLI
+process per test that accepts multiple commands. It also exposes a
+fluent API for testing CLI commands that read from stdin — interactive
+prompts, wizards, confirmation steps.
+
+This document is a cookbook of patterns for the interactive bits.
+For unit-test-style assertions on command output, see `cli-result.ts`
+and the existing tests under `cli-context.test.ts`.
+
+These examples were originally a `.test.ts` file under `examples/` that
+was permanently `describe.skip`'d because the specific commands they
+imagined (e.g. `module configure homebridge`, `system setup wizard`)
+don't exist in the CLI. They're kept here as illustrative reference,
+not as a regression suite.
+
+## Pattern: respond to a single prompt
+
+Use `cli.on(/regex/).respond(text)` after starting a command. The
+fluent helper waits for output matching the pattern, then writes the
+response to stdin.
+
+```typescript
+const commandPromise = cli.run('module configure homebridge');
+
+await cli.on(/Enter hostname:/).respond('iot.local\n');
+
+const result = await commandPromise;
+expect(result.exitCode).toBe(0);
+```
+
+## Pattern: respond to multiple prompts in sequence
+
+Wizards typically prompt for several fields back-to-back. Chain
+`cli.on().respond()` calls; each one waits for its own pattern before
+sending input.
+
+```typescript
+const commandPromise = cli.run('system init --interactive');
+
+await cli.on(/Enter primary domain:/).respond('example.com\n');
+await cli.on(/Enter admin email:/).respond('admin@example.com\n');
+await cli.on(/Confirm settings/).respond('yes\n');
+
+const result = await commandPromise;
+expect(result.exitCode).toBe(0);
+```
+
+## Pattern: conditional responses based on output
+
+Sometimes a command emits a warning or branching prompt only under
+certain conditions. Use `cli.expectOutput(/pattern/)` to wait for the
+trigger, then decide what to send.
+
+```typescript
+const commandPromise = cli.run('module deploy homebridge');
+
+await cli.expectOutput(/Ready to deploy/);
+
+await cli
+  .expectOutput(/WARNING/, { timeout: 1000 })
+  .then(async () => {
+    // Warning appeared — confirm explicitly
+    await cli.sendKeys('yes\n');
+  })
+  .catch(() => {
+    // No warning — quick confirm
+    cli.sendKeys('y\n');
+  });
+
+const result = await commandPromise;
+expect(result.exitCode).toBe(0);
+```
+
+## Pattern: testing input validation
+
+Provide a bad value, assert the validation error appears, then provide
+a good value.
+
+```typescript
+const commandPromise = cli.run('machine add');
+
+await cli.on(/Enter hostname:/).respond('invalid hostname!\n');
+
+await cli.expectOutput(/Invalid hostname format/);
+
+await cli.on(/Enter hostname:/).respond('valid-hostname\n');
+
+const result = await commandPromise;
+expect(result.exitCode).toBe(0);
+```
+
+## Pattern: timeout when a prompt never appears
+
+`expectOutput` rejects with a timeout error if its pattern doesn't
+appear within the configured window. Use this to assert the absence
+of output.
+
+```typescript
+const commandPromise = cli.run('some-command');
+
+await expect(
+  cli.expectOutput(/Prompt that never appears/, { timeout: 1000 }),
+).rejects.toThrow(/Timeout waiting for pattern/);
+
+await commandPromise;
+```
+
+## Pattern: complex multi-step wizard
+
+Combine `expectOutput` (to assert section markers) with `cli.on().respond()`
+(to provide values) for full wizard tests.
+
+```typescript
+const commandPromise = cli.run('system setup wizard');
+
+// Step 1: network
+await cli.expectOutput(/=== Network Configuration ===/);
+await cli.on(/Enter subnet/).respond('192.168.0.0/24\n');
+await cli.on(/Enter gateway/).respond('192.168.0.1\n');
+
+// Step 2: DNS
+await cli.expectOutput(/=== DNS Configuration ===/);
+await cli.on(/Primary DNS/).respond('8.8.8.8\n');
+await cli.on(/Secondary DNS/).respond('1.1.1.1\n');
+
+// Step 3: confirm
+await cli.expectOutput(/=== Review Settings ===/);
+await cli.expectOutput(/Network: 192.168.0.0\/24/);
+await cli.on(/Confirm/).respond('yes\n');
+
+const result = await commandPromise;
+expect(result.exitCode).toBe(0);
+expect(result.stdout).toContain('Setup complete');
+```
+
+## Pattern: verbose logging while debugging
+
+`cli.setVerbose(true)` makes the harness print every prompt and
+response to the test log. Useful for debugging a flaky interactive
+test.
+
+```typescript
+cli.setVerbose(true);
+
+const commandPromise = cli.run('debug interactive-test');
+
+await cli.on(/Enter value:/).respond('test\n');
+
+const result = await commandPromise;
+expect(result.exitCode).toBe(0);
+```
+
+## Status
+
+The interactive prompt API is fully implemented and tested:
+- ✅ `outputBuffer` is populated with all CLI output
+- ✅ `expectOutput()` waits for patterns to appear
+- ✅ `sendKeys()` sends input to process stdin
+- ✅ `ResponseBuilder` provides the fluent `.on().respond()` API
+- ✅ Unit tests in `cli-context.test.ts` and `cli-context-interactive.test.ts`
+
+The API is ready to use for testing real interactive commands. The
+patterns above are templates — they don't reference any actual CLI
+command, so don't paste them verbatim into a test file expecting them
+to run.

package/src/test-utils/cli-context-interactive.test.ts

@@ -0,0 +1,152 @@
+/**
+ * CLIContext Interactive Prompts Tests
+ *
+ * Tests for interactive prompt handling with persistent process
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { CLIContext } from './cli-context';
+import { type IntegrationTestContext, setupIntegrationTest } from './integration';
+
+describe('CLIContext - Interactive Prompts', () => {
+  let ctx: IntegrationTestContext;
+  let cli: CLIContext;
+
+  beforeEach(async () => {
+    ctx = await setupIntegrationTest();
+    cli = await CLIContext.create('src/cli/index.ts', {
+      CELILO_DB_PATH: ctx.dbPath,
+      CELILO_DATA_DIR: ctx.dataDir,
+    });
+  });
+
+  afterEach(async () => {
+    await cli.dispose();
+    await ctx.cleanup();
+  });
+
+  describe('output capturing', () => {
+    test('captures command output in buffer', async () => {
+      await cli.run('module list');
+
+      // The output should be captured for expectOutput to search
+      await cli.expectOutput(/modules/i, { timeout: 1000 });
+    });
+
+    test('expectOutput waits for pattern to appear', async () => {
+      // Start a command that will produce output
+      const runPromise = cli.run('module list');
+
+      // Wait for output pattern
+      await cli.expectOutput(/No modules/i, { timeout: 2000 });
+
+      // Command should still complete successfully
+      const result = await runPromise;
+      expect(result.exitCode).toBe(0);
+    });
+
+    test('expectOutput throws on timeout if pattern not found', async () => {
+      await cli.run('module list');
+
+      // Try to find a pattern that doesn't exist
+      await expect(
+        cli.expectOutput(/THIS_PATTERN_DOES_NOT_EXIST/, { timeout: 500 }),
+      ).rejects.toThrow(/Timeout waiting for pattern/);
+    });
+
+    test('expectOutput works with regex patterns', async () => {
+      await cli.run('module list');
+
+      // Should match case-insensitive
+      await cli.expectOutput(/MODULES/i, { timeout: 1000 });
+    });
+
+    test('expectOutput works with string patterns', async () => {
+      await cli.run('module list');
+
+      // Should match exact string
+      await cli.expectOutput('No modules', { timeout: 1000 });
+    });
+  });
+
+  describe('ResponseBuilder API', () => {
+    test('on().respond() provides fluent API', () => {
+      // Should return ResponseBuilder
+      const builder = cli.on(/Enter hostname:/);
+      expect(builder).toBeDefined();
+      expect(typeof builder.respond).toBe('function');
+    });
+
+    test('ResponseBuilder waits for pattern then sends input', async () => {
+      // This test demonstrates the API even though we don't have
+      // a command that actually prompts for input yet
+
+      // The API should work when we have interactive commands
+      const builder = cli.on(/Would you like to continue/);
+      expect(builder).toBeDefined();
+    });
+  });
+
+  describe('sendKeys', () => {
+    test('sendKeys writes to process stdin', async () => {
+      // sendKeys should not throw
+      await cli.sendKeys('test input\n');
+      // If we get here, it didn't throw
+      expect(true).toBe(true);
+    });
+
+    test('sendKeys can be called multiple times', async () => {
+      await cli.sendKeys('line 1\n');
+      await cli.sendKeys('line 2\n');
+      await cli.sendKeys('line 3\n');
+
+      // If we get here, none of them threw
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('output buffer management', () => {
+    test('output accumulates across multiple commands', async () => {
+      await cli.run('module list');
+      await cli.run('module list');
+
+      // Buffer should contain output from both commands
+      await cli.expectOutput(/modules/i);
+    });
+
+    test('can search for patterns from earlier commands', async () => {
+      await cli.run('module list');
+      await cli.run('system config list');
+
+      // Should still find pattern from first command
+      await cli.expectOutput(/modules/i);
+
+      // And pattern from second command
+      await cli.expectOutput(/config/i);
+    });
+  });
+
+  describe('real-world interactive scenarios', () => {
+    test('handles mixed JSON and non-JSON output', async () => {
+      // The CLI outputs both JSON responses (for protocol)
+      // and regular text (Database initialized, logs, etc.)
+
+      const result = await cli.run('module list');
+
+      // Should get JSON response
+      expect(result.exitCode).toBe(0);
+
+      // And should be able to find text output
+      await cli.expectOutput(/modules/i);
+    });
+
+    test('verbose mode shows all I/O', async () => {
+      cli.setVerbose(true);
+
+      await cli.run('module list');
+
+      // Verbose mode should log but not break functionality
+      await cli.expectOutput(/modules/i);
+    });
+  });
+});

package/src/test-utils/cli-context-server.test.ts

@@ -0,0 +1,66 @@
+/**
+ * CLIContext Server Mode Tests
+ *
+ * Basic tests for persistent process functionality
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CLIContext } from './cli-context';
+
+describe('CLIContext - Server Mode', () => {
+  test('starts persistent process successfully', async () => {
+    // Create temp directories for isolated test
+    const dbPath = join(await mkdtemp(join(tmpdir(), 'cli-test-')), 'test.db');
+    const dataDir = await mkdtemp(join(tmpdir(), 'cli-test-data-'));
+
+    const cli = await CLIContext.create('src/cli/index.ts', {
+      CELILO_DB_PATH: dbPath,
+      CELILO_DATA_DIR: dataDir,
+    });
+
+    try {
+      // If we get here, process started successfully
+      expect(cli).toBeDefined();
+
+      // Try running a simple command
+      const result = await cli.run('module list');
+      expect(result.exitCode).toBe(0);
+    } finally {
+      await cli.dispose();
+      // Cleanup
+      await rm(dbPath, { force: true });
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  }, 15000); // 15 second timeout for this test
+
+  test('reuses same process for multiple commands', async () => {
+    const dbPath = join(await mkdtemp(join(tmpdir(), 'cli-test-')), 'test.db');
+    const dataDir = await mkdtemp(join(tmpdir(), 'cli-test-data-'));
+
+    const cli = await CLIContext.create('src/cli/index.ts', {
+      CELILO_DB_PATH: dbPath,
+      CELILO_DATA_DIR: dataDir,
+    });
+
+    try {
+      // Run multiple commands - should reuse same process
+      const result1 = await cli.run('module list');
+      expect(result1.exitCode).toBe(0);
+
+      const result2 = await cli.run('module list');
+      expect(result2.exitCode).toBe(0);
+
+      const result3 = await cli.run('module list');
+      expect(result3.exitCode).toBe(0);
+
+      // All commands executed without spawning new processes
+    } finally {
+      await cli.dispose();
+      await rm(dbPath, { force: true });
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  }, 15000);
+});