@celilo/cli 0.1.0

package/src/test-utils/filesystem.ts

@@ -0,0 +1,142 @@
+/**
+ * Filesystem Test Utilities
+ *
+ * Provides functions for creating and managing temporary directories and files
+ * for test isolation.
+ */
+
+import { cp, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Create temporary directory for test
+ *
+ * Directory is created in system temp dir with unique name.
+ * Caller is responsible for cleanup via removeTempDirectory().
+ *
+ * @returns Path to temporary directory
+ *
+ * @example
+ * ```typescript
+ * const tempDir = await createTempDirectory();
+ * // Use tempDir...
+ * await removeTempDirectory(tempDir);
+ * ```
+ */
+export async function createTempDirectory(): Promise<string> {
+  return await mkdtemp(join(tmpdir(), 'celilo-test-'));
+}
+
+/**
+ * Remove temporary directory (with retry for locked files)
+ *
+ * Handles file locking issues by retrying once after a short delay.
+ * Useful on Windows where files may be locked briefly.
+ *
+ * @param dir - Directory to remove
+ *
+ * @example
+ * ```typescript
+ * const tempDir = await createTempDirectory();
+ * // Use tempDir...
+ * await removeTempDirectory(tempDir);
+ * ```
+ */
+export async function removeTempDirectory(dir: string): Promise<void> {
+  try {
+    await rm(dir, { recursive: true, force: true });
+  } catch (_error) {
+    // Retry once after 100ms (helps with file locking issues)
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Copy test fixture to temporary directory
+ *
+ * Recursively copies source to destination.
+ * Useful for setting up test data from fixtures.
+ *
+ * @param fixturePath - Source path (relative to cwd)
+ * @param destPath - Destination path
+ *
+ * @example
+ * ```typescript
+ * const tempDir = await createTempDirectory();
+ * await copyFixture('./test-fixtures/modules/artifact-test', tempDir);
+ * // tempDir now contains copy of artifact-test module
+ * await removeTempDirectory(tempDir);
+ * ```
+ */
+export async function copyFixture(fixturePath: string, destPath: string): Promise<void> {
+  await cp(fixturePath, destPath, { recursive: true });
+}
+
+/**
+ * Create multiple temporary directories
+ *
+ * Useful for tests that need multiple isolated directories.
+ *
+ * @param count - Number of directories to create
+ * @returns Array of directory paths
+ *
+ * @example
+ * ```typescript
+ * const [dir1, dir2] = await createMultipleTempDirectories(2);
+ * // Use dir1 and dir2...
+ * await removeMultipleTempDirectories([dir1, dir2]);
+ * ```
+ */
+export async function createMultipleTempDirectories(count: number): Promise<string[]> {
+  const directories: string[] = [];
+  for (let i = 0; i < count; i++) {
+    directories.push(await createTempDirectory());
+  }
+  return directories;
+}
+
+/**
+ * Remove multiple temporary directories
+ *
+ * @param directories - Array of directory paths to remove
+ *
+ * @example
+ * ```typescript
+ * const dirs = await createMultipleTempDirectories(3);
+ * // Use dirs...
+ * await removeMultipleTempDirectories(dirs);
+ * ```
+ */
+export async function removeMultipleTempDirectories(directories: string[]): Promise<void> {
+  for (const dir of directories) {
+    await removeTempDirectory(dir);
+  }
+}
+
+/**
+ * Create temporary directory with cleanup function
+ *
+ * Returns both directory path and cleanup function.
+ * Convenient pattern for use in test setup/teardown.
+ *
+ * @returns Object with directory path and cleanup function
+ *
+ * @example
+ * ```typescript
+ * const { path: tempDir, cleanup } = await createTempDirectoryWithCleanup();
+ * // Use tempDir...
+ * await cleanup();
+ * ```
+ */
+export async function createTempDirectoryWithCleanup(): Promise<{
+  path: string;
+  cleanup: () => Promise<void>;
+}> {
+  const path = await createTempDirectory();
+  const cleanup = async () => {
+    await removeTempDirectory(path);
+  };
+  return { path, cleanup };
+}

package/src/test-utils/fixtures.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'bun:test';
+import { existsSync } from 'node:fs';
+import {
+  getFixturePath,
+  getModuleTestConfig,
+  getModuleTestSecrets,
+  getSystemTestConfig,
+  getSystemTestSecrets,
+  loadTestValues,
+} from './fixtures';
+
+describe('Fixture Test Utilities', () => {
+  describe('getFixturePath', () => {
+    test('returns absolute path to fixture', () => {
+      const path = getFixturePath('modules/artifact-test');
+      expect(path).toContain('test-fixtures/modules/artifact-test');
+      expect(path).toMatch(/^[/\\]/); // Starts with / or \ (absolute path)
+    });
+
+    test('handles nested paths', () => {
+      const path = getFixturePath('modules/artifact-test/manifest.yml');
+      expect(path).toContain('test-fixtures/modules/artifact-test/manifest.yml');
+    });
+
+    test('returns path that exists', () => {
+      const path = getFixturePath('modules/artifact-test');
+      expect(existsSync(path)).toBe(true);
+    });
+  });
+
+  describe('loadTestValues', () => {
+    test('loads test-values.yml', async () => {
+      const testValues = await loadTestValues();
+      expect(testValues).toBeDefined();
+      expect(testValues).toHaveProperty('system');
+      expect(testValues).toHaveProperty('modules');
+    });
+
+    test('contains expected system configuration', async () => {
+      const testValues = await loadTestValues();
+      expect(testValues.system).toBeDefined();
+      expect(testValues.system?.dns).toBeDefined();
+    });
+
+    test('contains expected module data', async () => {
+      const testValues = await loadTestValues();
+      expect(testValues.modules).toBeDefined();
+      expect(testValues.modules?.homebridge).toBeDefined();
+    });
+  });
+
+  describe('getModuleTestConfig', () => {
+    test('returns module configuration', async () => {
+      const config = await getModuleTestConfig('homebridge');
+      expect(config).toBeDefined();
+      expect(config.vmid).toBe(2110);
+      expect(config.hostname).toBe('iot');
+    });
+
+    test('excludes secrets from config', async () => {
+      const config = await getModuleTestConfig('dns-external');
+      expect(config).toBeDefined();
+      expect(config.vps_ip).toBe('188.166.157.2');
+      expect(config.secrets).toBeUndefined();
+    });
+
+    test('returns empty object for non-existent module', async () => {
+      const config = await getModuleTestConfig('non-existent-module');
+      expect(config).toEqual({});
+    });
+
+    test('handles module with no secrets', async () => {
+      // Homebridge module has config but no secrets in test-values.yml
+      const config = await getModuleTestConfig('homebridge');
+      expect(config).toBeDefined();
+      expect(config.hostname).toBeDefined();
+    });
+  });
+
+  describe('getModuleTestSecrets', () => {
+    test('returns module secrets', async () => {
+      const secrets = await getModuleTestSecrets('dns-external');
+      expect(secrets).toBeDefined();
+      expect(secrets.knot_ddns_tsig_secret).toBeTruthy();
+      expect(typeof secrets.knot_ddns_tsig_secret).toBe('string');
+    });
+
+    test('returns empty object for module with no secrets', async () => {
+      const secrets = await getModuleTestSecrets('test-module');
+      expect(secrets).toEqual({});
+    });
+
+    test('returns empty object for non-existent module', async () => {
+      const secrets = await getModuleTestSecrets('non-existent-module');
+      expect(secrets).toEqual({});
+    });
+  });
+
+  describe('getSystemTestConfig', () => {
+    test('returns system configuration', async () => {
+      const config = await getSystemTestConfig();
+      expect(config).toBeDefined();
+      expect(config.primary_domain).toBe('example.com');
+      expect(config.dns).toBeDefined();
+    });
+
+    test('contains nested configuration', async () => {
+      const config = await getSystemTestConfig();
+      expect(config.dns).toBeDefined();
+      const dns = config.dns as Record<string, unknown>;
+      expect(dns.primary).toBe('192.168.0.1');
+    });
+  });
+
+  describe('getSystemTestSecrets', () => {
+    test('returns system secrets (currently empty after container-services migration)', async () => {
+      const secrets = await getSystemTestSecrets();
+      expect(secrets).toBeDefined();
+      expect(typeof secrets).toBe('object');
+      // Note: Proxmox credentials are now per-service, not system-wide secrets
+    });
+  });
+});

package/src/test-utils/fixtures.ts

@@ -0,0 +1,160 @@
+/**
+ * Fixture Test Utilities
+ *
+ * Provides functions for loading test fixtures and test data.
+ * Centralizes fixture path resolution and test data loading.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+/**
+ * Get fixture path
+ *
+ * Resolves path to fixture directory or file.
+ * All fixtures are in ./test-fixtures/ directory.
+ *
+ * @param fixtureName - Fixture name (e.g., 'modules/artifact-test')
+ * @returns Absolute path to fixture
+ *
+ * @example
+ * ```typescript
+ * const modulePath = getFixturePath('modules/artifact-test');
+ * // Returns: /absolute/path/to/celilo/backend/test-fixtures/modules/artifact-test
+ * ```
+ */
+export function getFixturePath(fixtureName: string): string {
+  return join(process.cwd(), 'test-fixtures', fixtureName);
+}
+
+/**
+ * Test values structure
+ *
+ * Mirrors test-values.yml structure.
+ * Top-level keys: system, system_secrets, modules
+ * Module values can include config and secrets
+ */
+export interface TestValues {
+  system?: Record<string, unknown>;
+  system_secrets?: Record<string, unknown>;
+  modules?: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Load test values from test-values.yml
+ *
+ * Loads test configuration and secrets from centralized test data file.
+ * Use for integration tests that need realistic test data.
+ *
+ * @returns Test values object
+ *
+ * @example
+ * ```typescript
+ * const testValues = await loadTestValues();
+ * const caddy = testValues.modules?.caddy;
+ * expect(caddy.config?.hostname).toBe('www');
+ * ```
+ */
+export async function loadTestValues(): Promise<TestValues> {
+  const testValuesPath = getFixturePath('test-values.yml');
+  const content = await readFile(testValuesPath, 'utf-8');
+  return parseYaml(content) as TestValues;
+}
+
+/**
+ * Get module test configuration
+ *
+ * Retrieves configuration for specific module from test-values.yml.
+ * Returns empty object if module not found.
+ * Excludes 'secrets' key from returned config.
+ *
+ * @param moduleId - Module ID
+ * @returns Module configuration
+ *
+ * @example
+ * ```typescript
+ * const config = await getModuleTestConfig('homebridge');
+ * expect(config.vmid).toBe(2110);
+ * ```
+ */
+export async function getModuleTestConfig(moduleId: string): Promise<Record<string, unknown>> {
+  const testValues = await loadTestValues();
+  const moduleData = testValues.modules?.[moduleId];
+  if (!moduleData) {
+    return {};
+  }
+
+  // Return all data except 'secrets'
+  const { secrets, ...config } = moduleData as Record<string, unknown> & {
+    secrets?: unknown;
+  };
+  return config;
+}
+
+/**
+ * Get module test secrets
+ *
+ * Retrieves secrets for specific module from test-values.yml.
+ * Returns empty object if module not found or has no secrets.
+ *
+ * @param moduleId - Module ID
+ * @returns Module secrets
+ *
+ * @example
+ * ```typescript
+ * const secrets = await getModuleTestSecrets('dns-external');
+ * expect(secrets.knot_ddns_tsig_secret).toBeTruthy();
+ * ```
+ */
+export async function getModuleTestSecrets(moduleId: string): Promise<Record<string, unknown>> {
+  const testValues = await loadTestValues();
+  const moduleData = testValues.modules?.[moduleId];
+  if (!moduleData) {
+    return {};
+  }
+
+  const secrets = (moduleData as Record<string, unknown>).secrets;
+  if (!secrets || typeof secrets !== 'object') {
+    return {};
+  }
+
+  return secrets as Record<string, unknown>;
+}
+
+/**
+ * Get system test configuration
+ *
+ * Retrieves system-wide configuration from test-values.yml.
+ *
+ * @returns System configuration
+ *
+ * @example
+ * ```typescript
+ * const config = await getSystemTestConfig();
+ * expect(config.dns).toBeDefined();
+ * ```
+ */
+export async function getSystemTestConfig(): Promise<Record<string, unknown>> {
+  const testValues = await loadTestValues();
+  return testValues.system ?? {};
+}
+
+/**
+ * Get system test secrets
+ *
+ * Retrieves system-wide secrets from test-values.yml.
+ *
+ * @returns System secrets
+ *
+ * @example
+ * ```typescript
+ * const secrets = await getSystemTestSecrets();
+ * // Note: Provider credentials are now per-service, not system-wide
+ * expect(secrets).toBeDefined();
+ * ```
+ */
+export async function getSystemTestSecrets(): Promise<Record<string, unknown>> {
+  const testValues = await loadTestValues();
+  return testValues.system_secrets ?? {};
+}

package/src/test-utils/golden-diff.ts

@@ -0,0 +1,197 @@
+/**
+ * Golden File Comparison Utilities
+ *
+ * Compares generated output against golden reference files for regression testing.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+export interface FileDifference {
+  path: string;
+  type: 'missing-in-golden' | 'missing-in-generated' | 'content-mismatch';
+  goldenContent?: string;
+  generatedContent?: string;
+}
+
+export interface ComparisonResult {
+  pass: boolean;
+  differences: FileDifference[];
+  filesCompared: number;
+  filesSkipped: number;
+}
+
+export interface ComparisonOptions {
+  /**
+   * Files to exclude from comparison (glob patterns relative to base dir)
+   * Example: ['**\/*.json', 'secrets/**']
+   */
+  excludePatterns?: string[];
+}
+
+/**
+ * Compare two directories recursively
+ *
+ * @param goldenDir - Path to golden reference directory
+ * @param generatedDir - Path to generated output directory
+ * @param options - Comparison options
+ * @returns Comparison result with any differences found
+ */
+export async function compareDirectories(
+  goldenDir: string,
+  generatedDir: string,
+  options: ComparisonOptions = {},
+): Promise<ComparisonResult> {
+  const differences: FileDifference[] = [];
+  let filesCompared = 0;
+  let filesSkipped = 0;
+
+  // Files to skip (contain encrypted secrets that change each run)
+  const skipPatterns = options.excludePatterns || [];
+  const shouldSkip = (path: string): boolean => {
+    return skipPatterns.some((pattern) => {
+      // Simple glob matching - just check if path includes pattern
+      return path.includes(pattern.replace('**/', '').replace('*', ''));
+    });
+  };
+
+  // Get all files from both directories
+  const goldenFiles = await getAllFiles(goldenDir);
+  const generatedFiles = await getAllFiles(generatedDir);
+
+  // Convert to relative paths for comparison
+  const goldenRelativePaths = new Set(goldenFiles.map((f) => relative(goldenDir, f)));
+  const generatedRelativePaths = new Set(generatedFiles.map((f) => relative(generatedDir, f)));
+
+  // Check for files in golden but not in generated
+  for (const relativePath of goldenRelativePaths) {
+    if (!generatedRelativePaths.has(relativePath)) {
+      // Skip if matches exclude pattern
+      if (shouldSkip(relativePath)) {
+        filesSkipped++;
+        continue;
+      }
+      differences.push({
+        path: relativePath,
+        type: 'missing-in-generated',
+      });
+    }
+  }
+
+  // Check for files in generated but not in golden
+  for (const relativePath of generatedRelativePaths) {
+    if (!goldenRelativePaths.has(relativePath)) {
+      // Skip if matches exclude pattern
+      if (shouldSkip(relativePath)) {
+        filesSkipped++;
+        continue;
+      }
+      differences.push({
+        path: relativePath,
+        type: 'missing-in-golden',
+      });
+    }
+  }
+
+  // Compare content of files that exist in both
+  for (const relativePath of goldenRelativePaths) {
+    if (generatedRelativePaths.has(relativePath)) {
+      // Skip files that match exclude patterns
+      if (shouldSkip(relativePath)) {
+        filesSkipped++;
+        continue;
+      }
+
+      const goldenPath = join(goldenDir, relativePath);
+      const generatedPath = join(generatedDir, relativePath);
+
+      const goldenContent = await readFile(goldenPath, 'utf-8');
+      const generatedContent = await readFile(generatedPath, 'utf-8');
+
+      if (goldenContent !== generatedContent) {
+        differences.push({
+          path: relativePath,
+          type: 'content-mismatch',
+          goldenContent,
+          generatedContent,
+        });
+      }
+
+      filesCompared++;
+    }
+  }
+
+  return {
+    pass: differences.length === 0,
+    differences,
+    filesCompared,
+    filesSkipped,
+  };
+}
+
+/**
+ * Get all files in a directory recursively
+ *
+ * @param dir - Directory path
+ * @returns Array of absolute file paths
+ */
+async function getAllFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  if (!existsSync(dir)) {
+    return files;
+  }
+
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      const subFiles = await getAllFiles(fullPath);
+      files.push(...subFiles);
+    } else {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Format differences for display
+ *
+ * @param differences - Array of differences
+ * @returns Formatted string
+ */
+export function formatDifferences(differences: FileDifference[]): string {
+  const lines: string[] = [];
+
+  for (const diff of differences) {
+    switch (diff.type) {
+      case 'missing-in-golden':
+        lines.push(`❌ File exists in generated but not in golden: ${diff.path}`);
+        lines.push('   (Run with --update-golden to add this file)');
+        break;
+
+      case 'missing-in-generated':
+        lines.push(`❌ File exists in golden but not in generated: ${diff.path}`);
+        break;
+
+      case 'content-mismatch':
+        lines.push(`❌ Content mismatch: ${diff.path}`);
+        if (diff.goldenContent && diff.generatedContent) {
+          lines.push('   Golden (first 200 chars):');
+          lines.push(`   ${diff.goldenContent.substring(0, 200).replace(/\n/g, '\\n')}`);
+          lines.push('   Generated (first 200 chars):');
+          lines.push(`   ${diff.generatedContent.substring(0, 200).replace(/\n/g, '\\n')}`);
+        }
+        break;
+    }
+
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/test-utils/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Test Utilities - Public API
+ *
+ * Exports all test utilities for use in integration and unit tests.
+ */
+
+// Persistent CLI testing (new)
+export { CLIContext, ResponseBuilder, type RunOptions } from './cli-context';
+export { type CLIResult, CLIResultImpl } from './cli-result';
+export {
+  fixtures,
+  homebridgeModule,
+  caddyModule,
+  dnsExternalModule,
+  multiModule,
+} from './module-fixtures';
+
+// Legacy CLI testing (deprecated - use CLIContext instead)
+export { runCli, runCliExpectingFailure } from './cli';
+
+// Integration test setup
+export { setupIntegrationTest, type IntegrationTestContext } from './integration';
+
+// Database utilities
+export {
+  setupTestDatabase,
+  setupTestDatabaseFile,
+  cleanupTestDatabase,
+} from './database';
+
+// Filesystem utilities
+export {
+  createTempDirectory,
+  removeTempDirectory,
+  copyFixture,
+  createTempDirectoryWithCleanup,
+} from './filesystem';
+
+// Module utilities
+export {
+  importTestModule,
+  cleanupTestModule,
+  importMultipleTestModules,
+  cleanupMultipleTestModules,
+  getModuleState,
+  type ImportTestModuleOptions,
+} from './modules';
+
+// Fixture utilities
+export {
+  getFixturePath,
+  loadTestValues,
+  getModuleTestConfig,
+  getModuleTestSecrets,
+  getSystemTestConfig,
+  getSystemTestSecrets,
+  type TestValues,
+} from './fixtures';
+
+// Golden file testing
+export {
+  compareDirectories,
+  formatDifferences,
+  type FileDifference,
+  type ComparisonResult,
+  type ComparisonOptions,
+} from './golden-diff';
+
+// Value extraction
+export {
+  extractTerraformValues,
+  extractAnsibleValues,
+  compareExtractedValues,
+  formatValueMismatches,
+  type ExtractedValues,
+  type ValueExtractionResult,
+} from './value-extractor';