@celilo/cli 0.1.0

package/src/services/schema-validation.ts

@@ -0,0 +1,155 @@
+/**
+ * Schema validation service
+ * Validates module configuration values against JSON Schema definitions
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import Ajv, { type ValidateFunction } from 'ajv';
+import { eq } from 'drizzle-orm';
+import { type DbClient, getDb } from '../db/client';
+import { modules } from '../db/schema';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+interface ValidationResult {
+  valid: boolean;
+  errors?: string[];
+}
+
+/**
+ * Get module source path from database
+ */
+function getModuleSourcePath(moduleId: string, db: DbClient = getDb()): string | null {
+  try {
+    const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+    return module?.sourcePath || null;
+  } catch (error) {
+    // If database access fails, validation will be skipped (schema not found)
+    console.error(`Failed to get module source path for ${moduleId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Load JSON Schema for a module
+ * Looks for schema/user_config.json in the module directory
+ */
+async function loadModuleSchema(
+  moduleId: string,
+  db: DbClient = getDb(),
+): Promise<Record<string, unknown> | null> {
+  const sourcePath = getModuleSourcePath(moduleId, db);
+  if (!sourcePath) {
+    return null;
+  }
+
+  const schemaPath = join(sourcePath, 'schema', 'user_config.json');
+  if (!existsSync(schemaPath)) {
+    return null;
+  }
+
+  try {
+    const schemaContent = await readFile(schemaPath, 'utf-8');
+    try {
+      return JSON.parse(schemaContent) as Record<string, unknown>;
+    } catch (parseError) {
+      console.error(
+        `Failed to parse user_config.json schema for ${moduleId}:`,
+        parseError instanceof Error ? parseError.message : parseError,
+      );
+      return null;
+    }
+  } catch (error) {
+    console.error(`Failed to load schema for ${moduleId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get JSON Schema for a specific property
+ * Extracts the property schema from the module's user_config.json
+ */
+async function getPropertySchema(
+  moduleId: string,
+  propertyName: string,
+  db: DbClient = getDb(),
+): Promise<Record<string, unknown> | null> {
+  const schema = await loadModuleSchema(moduleId, db);
+  if (!schema) {
+    return null;
+  }
+
+  const properties = schema.properties as Record<string, unknown> | undefined;
+  if (!properties) {
+    return null;
+  }
+
+  return (properties[propertyName] as Record<string, unknown>) || null;
+}
+
+/**
+ * Validate a configuration value against its schema
+ *
+ * @param moduleId - Module ID
+ * @param key - Configuration key
+ * @param value - Value to validate (already parsed)
+ * @param db - Database client (defaults to singleton)
+ * @returns Validation result with errors if invalid
+ */
+export async function validateConfigValue(
+  moduleId: string,
+  key: string,
+  value: unknown,
+  db: DbClient = getDb(),
+): Promise<ValidationResult> {
+  // Load property schema
+  const propertySchema = await getPropertySchema(moduleId, key, db);
+
+  // If no schema exists, validation passes (schema is optional)
+  if (!propertySchema) {
+    return { valid: true };
+  }
+
+  // Compile and validate
+  let validate: ValidateFunction;
+  try {
+    validate = ajv.compile(propertySchema);
+  } catch (error) {
+    // Schema compilation error - invalid schema definition
+    return {
+      valid: false,
+      errors: [
+        `Invalid schema for property ${key}: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+    };
+  }
+
+  const valid = validate(value);
+
+  if (!valid && validate.errors) {
+    const errors = validate.errors.map((err) => {
+      const path = err.instancePath ? `${err.instancePath} ` : '';
+      return `${path}${err.message}`;
+    });
+    return { valid: false, errors };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Format validation errors for display
+ */
+export function formatValidationErrors(errors: string[]): string {
+  if (errors.length === 0) {
+    return 'Validation failed';
+  }
+
+  if (errors.length === 1) {
+    return `Validation error: ${errors[0]}`;
+  }
+
+  return `Validation errors:\n${errors.map((err) => `  - ${err}`).join('\n')}`;
+}

package/src/services/secret-schema-loader.test.ts

@@ -0,0 +1,311 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type DbClient, getDb } from '../db/client';
+import { modules } from '../db/schema';
+import {
+  type SecretsSchema,
+  getAllSecretMetadata,
+  getSecretMetadata,
+  loadSecretsSchema,
+  validateDerivationGraph,
+} from './secret-schema-loader';
+
+describe('secret-schema-loader', () => {
+  let tempDir: string;
+  let testDb: DbClient;
+
+  beforeEach(() => {
+    // Create temporary directory for test module
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-test-'));
+
+    // Set up test database
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    testDb = getDb();
+
+    // Create test module in database
+    testDb
+      .insert(modules)
+      .values({
+        id: 'test-module',
+        name: 'Test Module',
+        sourcePath: tempDir,
+        version: '1.0.0',
+        manifestData: {},
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    // Clean up temp directory
+    rmSync(tempDir, { recursive: true, force: true });
+    process.env.CELILO_DB_PATH = undefined;
+  });
+
+  describe('loadSecretsSchema', () => {
+    test('loads valid secrets schema', async () => {
+      // Create schema directory and file
+      const schemaDir = join(tempDir, 'schema');
+      mkdirSync(schemaDir, { recursive: true });
+
+      const schema = {
+        type: 'object',
+        properties: {
+          api_key: {
+            type: 'string',
+            source: 'user_provided',
+            description: 'API key for service',
+          },
+          tsig_secret: {
+            type: 'string',
+            source: 'generated',
+            format: 'tsig-key',
+          },
+        },
+      };
+
+      writeFileSync(join(schemaDir, 'secrets.json'), JSON.stringify(schema, null, 2));
+
+      const result = await loadSecretsSchema('test-module', testDb);
+
+      expect(result).not.toBeNull();
+      expect(result?.properties.api_key).toBeDefined();
+      expect(result?.properties.api_key.source).toBe('user_provided');
+      expect(result?.properties.tsig_secret.source).toBe('generated');
+    });
+
+    test('returns null when schema file does not exist', async () => {
+      const result = await loadSecretsSchema('test-module', testDb);
+      expect(result).toBeNull();
+    });
+
+    test('returns null for invalid schema structure', async () => {
+      const schemaDir = join(tempDir, 'schema');
+      mkdirSync(schemaDir, { recursive: true });
+
+      // Invalid schema (missing properties)
+      const schema = {
+        type: 'object',
+      };
+
+      writeFileSync(join(schemaDir, 'secrets.json'), JSON.stringify(schema, null, 2));
+
+      const result = await loadSecretsSchema('test-module', testDb);
+      expect(result).toBeNull();
+    });
+
+    test('returns null for malformed JSON', async () => {
+      const schemaDir = join(tempDir, 'schema');
+      mkdirSync(schemaDir, { recursive: true });
+
+      writeFileSync(join(schemaDir, 'secrets.json'), 'not valid json{');
+
+      const result = await loadSecretsSchema('test-module', testDb);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('getSecretMetadata', () => {
+    test('returns metadata for specific secret', async () => {
+      const schemaDir = join(tempDir, 'schema');
+      mkdirSync(schemaDir, { recursive: true });
+
+      const schema = {
+        type: 'object',
+        properties: {
+          wireguard_private_key: {
+            type: 'string',
+            source: 'generated',
+            format: 'wireguard-key',
+            length: 32,
+            title: 'WireGuard Private Key',
+            description: 'Private key for WireGuard tunnel',
+          },
+        },
+      };
+
+      writeFileSync(join(schemaDir, 'secrets.json'), JSON.stringify(schema, null, 2));
+
+      const metadata = await getSecretMetadata('test-module', 'wireguard_private_key', testDb);
+
+      expect(metadata).not.toBeNull();
+      expect(metadata?.name).toBe('wireguard_private_key');
+      expect(metadata?.source).toBe('generated');
+      expect(metadata?.format).toBe('wireguard-key');
+      expect(metadata?.length).toBe(32);
+      expect(metadata?.title).toBe('WireGuard Private Key');
+    });
+
+    test('returns null for non-existent secret', async () => {
+      const schemaDir = join(tempDir, 'schema');
+      mkdirSync(schemaDir, { recursive: true });
+
+      const schema = {
+        type: 'object',
+        properties: {
+          api_key: {
+            type: 'string',
+            source: 'user_provided',
+          },
+        },
+      };
+
+      writeFileSync(join(schemaDir, 'secrets.json'), JSON.stringify(schema, null, 2));
+
+      const metadata = await getSecretMetadata('test-module', 'non_existent', testDb);
+      expect(metadata).toBeNull();
+    });
+
+    test('defaults to user_provided when source not specified', async () => {
+      const schemaDir = join(tempDir, 'schema');
+      mkdirSync(schemaDir, { recursive: true });
+
+      const schema = {
+        type: 'object',
+        properties: {
+          api_key: {
+            type: 'string',
+            description: 'API key',
+          },
+        },
+      };
+
+      writeFileSync(join(schemaDir, 'secrets.json'), JSON.stringify(schema, null, 2));
+
+      const metadata = await getSecretMetadata('test-module', 'api_key', testDb);
+
+      expect(metadata?.source).toBe('user_provided');
+    });
+  });
+
+  describe('getAllSecretMetadata', () => {
+    test('returns all secret metadata', async () => {
+      const schemaDir = join(tempDir, 'schema');
+      mkdirSync(schemaDir, { recursive: true });
+
+      const schema = {
+        type: 'object',
+        properties: {
+          api_key: {
+            type: 'string',
+            source: 'user_provided',
+          },
+          tsig_secret: {
+            type: 'string',
+            source: 'generated',
+            format: 'tsig-key',
+          },
+          admin_password: {
+            type: 'string',
+            source: 'generated_optional',
+            format: 'base64',
+          },
+        },
+      };
+
+      writeFileSync(join(schemaDir, 'secrets.json'), JSON.stringify(schema, null, 2));
+
+      const allMetadata = await getAllSecretMetadata('test-module', testDb);
+
+      expect(allMetadata).toHaveLength(3);
+      expect(allMetadata.map((m) => m.name)).toContain('api_key');
+      expect(allMetadata.map((m) => m.name)).toContain('tsig_secret');
+      expect(allMetadata.map((m) => m.name)).toContain('admin_password');
+    });
+
+    test('returns empty array when no schema exists', async () => {
+      const allMetadata = await getAllSecretMetadata('test-module', testDb);
+      expect(allMetadata).toEqual([]);
+    });
+  });
+
+  describe('validateDerivationGraph', () => {
+    test('validates schema without derivation', () => {
+      const schema: SecretsSchema = {
+        type: 'object',
+        properties: {
+          api_key: {
+            type: 'string',
+            source: 'user_provided',
+          },
+        },
+      };
+
+      const error = validateDerivationGraph(schema);
+      expect(error).toBeNull();
+    });
+
+    test('validates schema with linear derivation', () => {
+      const schema: SecretsSchema = {
+        type: 'object',
+        properties: {
+          private_key: {
+            type: 'string',
+            source: 'generated',
+            format: 'wireguard-key',
+          },
+          public_key: {
+            type: 'string',
+            source: 'generated',
+            format: 'wireguard-key',
+            derive_from: 'private_key',
+            derive_method: 'wireguard-pubkey',
+          },
+        },
+      };
+
+      const error = validateDerivationGraph(schema);
+      expect(error).toBeNull();
+    });
+
+    test('detects circular derivation (direct cycle)', () => {
+      const schema: SecretsSchema = {
+        type: 'object',
+        properties: {
+          secret_a: {
+            type: 'string',
+            derive_from: 'secret_b',
+            derive_method: 'test',
+          },
+          secret_b: {
+            type: 'string',
+            derive_from: 'secret_a',
+            derive_method: 'test',
+          },
+        },
+      };
+
+      const error = validateDerivationGraph(schema);
+      expect(error).not.toBeNull();
+      expect(error).toContain('Circular derivation detected');
+    });
+
+    test('detects circular derivation (indirect cycle)', () => {
+      const schema: SecretsSchema = {
+        type: 'object',
+        properties: {
+          secret_a: {
+            type: 'string',
+            derive_from: 'secret_b',
+            derive_method: 'test',
+          },
+          secret_b: {
+            type: 'string',
+            derive_from: 'secret_c',
+            derive_method: 'test',
+          },
+          secret_c: {
+            type: 'string',
+            derive_from: 'secret_a',
+            derive_method: 'test',
+          },
+        },
+      };
+
+      const error = validateDerivationGraph(schema);
+      expect(error).not.toBeNull();
+      expect(error).toContain('Circular derivation detected');
+    });
+  });
+});

package/src/services/secret-schema-loader.ts

@@ -0,0 +1,239 @@
+/**
+ * Secret Schema Loader
+ *
+ * Loads and parses schema/secrets.json files for modules
+ * Provides metadata about secret generation behavior
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { type DbClient, getDb } from '../db/client';
+import { modules } from '../db/schema';
+
+/**
+ * Secret metadata from schema
+ */
+export interface SecretMetadata {
+  name: string;
+  source: 'generated' | 'user_provided' | 'user_password' | 'generated_optional';
+  format?: string;
+  length?: number;
+  deriveFrom?: string;
+  deriveMethod?: string;
+  title?: string;
+  description?: string;
+}
+
+/**
+ * Secrets schema structure
+ */
+export interface SecretsSchema {
+  $schema?: string;
+  type: 'object';
+  title?: string;
+  description?: string;
+  required?: string[];
+  properties: Record<string, SecretPropertySchema>;
+}
+
+/**
+ * Individual secret property schema
+ */
+export interface SecretPropertySchema {
+  type: string;
+  title?: string;
+  description?: string;
+  source?: 'generated' | 'user_provided' | 'user_password' | 'generated_optional';
+  format?: string;
+  length?: number;
+  derive_from?: string;
+  derive_method?: string;
+  minLength?: number;
+  maxLength?: number;
+}
+
+/**
+ * Get module source path from database
+ */
+function getModuleSourcePath(moduleId: string, db: DbClient = getDb()): string | null {
+  try {
+    const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+    return module?.sourcePath || null;
+  } catch (error) {
+    console.error(`Failed to get module source path for ${moduleId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Load secrets schema for a module
+ *
+ * Looks for schema/secrets.json in the module directory
+ *
+ * @param moduleId - Module identifier
+ * @param db - Database client
+ * @returns Secrets schema or null if not found
+ */
+export async function loadSecretsSchema(
+  moduleId: string,
+  db: DbClient = getDb(),
+): Promise<SecretsSchema | null> {
+  const sourcePath = getModuleSourcePath(moduleId, db);
+  if (!sourcePath) {
+    return null;
+  }
+
+  const schemaPath = join(sourcePath, 'schema', 'secrets.json');
+  if (!existsSync(schemaPath)) {
+    return null;
+  }
+
+  try {
+    const schemaContent = await readFile(schemaPath, 'utf-8');
+    let schema: SecretsSchema;
+    try {
+      schema = JSON.parse(schemaContent) as SecretsSchema;
+    } catch (parseError) {
+      console.error(
+        `Failed to parse secrets schema JSON for ${moduleId}:`,
+        parseError instanceof Error ? parseError.message : parseError,
+      );
+      return null;
+    }
+
+    // Validate basic structure
+    if (!schema.properties || typeof schema.properties !== 'object') {
+      console.error(`Invalid secrets schema for ${moduleId}: missing properties`);
+      return null;
+    }
+
+    return schema;
+  } catch (error) {
+    console.error(`Failed to load secrets schema for ${moduleId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get metadata for a specific secret
+ *
+ * @param moduleId - Module identifier
+ * @param secretName - Secret name
+ * @param db - Database client
+ * @returns Secret metadata or null if not found
+ */
+export async function getSecretMetadata(
+  moduleId: string,
+  secretName: string,
+  db: DbClient = getDb(),
+): Promise<SecretMetadata | null> {
+  const schema = await loadSecretsSchema(moduleId, db);
+  if (!schema) {
+    return null;
+  }
+
+  const propertySchema = schema.properties[secretName];
+  if (!propertySchema) {
+    return null;
+  }
+
+  return {
+    name: secretName,
+    source: propertySchema.source || 'user_provided', // Safe default
+    format: propertySchema.format,
+    length: propertySchema.length,
+    deriveFrom: propertySchema.derive_from,
+    deriveMethod: propertySchema.derive_method,
+    title: propertySchema.title,
+    description: propertySchema.description,
+  };
+}
+
+/**
+ * Get all secret metadata for a module
+ *
+ * @param moduleId - Module identifier
+ * @param db - Database client
+ * @returns Array of secret metadata
+ */
+export async function getAllSecretMetadata(
+  moduleId: string,
+  db: DbClient = getDb(),
+): Promise<SecretMetadata[]> {
+  const schema = await loadSecretsSchema(moduleId, db);
+  if (!schema) {
+    return [];
+  }
+
+  const metadata: SecretMetadata[] = [];
+
+  for (const [secretName, propertySchema] of Object.entries(schema.properties)) {
+    metadata.push({
+      name: secretName,
+      source: propertySchema.source || 'user_provided', // Safe default
+      format: propertySchema.format,
+      length: propertySchema.length,
+      deriveFrom: propertySchema.derive_from,
+      deriveMethod: propertySchema.derive_method,
+      title: propertySchema.title,
+      description: propertySchema.description,
+    });
+  }
+
+  return metadata;
+}
+
+/**
+ * Validate secrets schema for circular derivation
+ *
+ * Builds derivation graph and checks for cycles using DFS
+ *
+ * @param schema - Secrets schema
+ * @returns Error message if circular derivation detected, null otherwise
+ */
+export function validateDerivationGraph(schema: SecretsSchema): string | null {
+  const graph: Record<string, string> = {};
+
+  // Build derivation graph (secret -> derive_from)
+  for (const [secretName, propertySchema] of Object.entries(schema.properties)) {
+    if (propertySchema.derive_from) {
+      graph[secretName] = propertySchema.derive_from;
+    }
+  }
+
+  // Check for cycles using DFS
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  function hasCycle(node: string): boolean {
+    if (recursionStack.has(node)) {
+      return true; // Cycle detected
+    }
+
+    if (visited.has(node)) {
+      return false; // Already processed
+    }
+
+    visited.add(node);
+    recursionStack.add(node);
+
+    const parent = graph[node];
+    if (parent && hasCycle(parent)) {
+      return true;
+    }
+
+    recursionStack.delete(node);
+    return false;
+  }
+
+  // Check each node in the graph
+  for (const secretName of Object.keys(graph)) {
+    if (hasCycle(secretName)) {
+      return `Circular derivation detected involving: ${secretName}`;
+    }
+  }
+
+  return null;
+}