cognitive-modules-cli 2.2.1 → 2.2.7

package/dist/commands/test.js

@@ -0,0 +1,454 @@
+/**
+ * Test Command - Run golden tests for Cognitive Modules
+ *
+ * Usage:
+ *   cog test <module>           - Run tests for a specific module
+ *   cog test --all              - Run tests for all modules
+ *   cog test <module> --update  - Update expected outputs
+ *
+ * Tests are defined in module.yaml:
+ *   tests:
+ *     - tests/case1.input.json -> tests/case1.expected.json
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { findModule, listModules, getDefaultSearchPaths } from '../modules/loader.js';
+import { runModule } from '../modules/runner.js';
+// =============================================================================
+// Test Case Parsing
+// =============================================================================
+/**
+ * Parse test definitions from module.yaml tests field
+ *
+ * Format: "tests/case1.input.json -> tests/case1.expected.json"
+ */
+export function parseTestDefinitions(module, modulePath) {
+    const tests = [];
+    const testsConfig = module.tests;
+    if (!testsConfig || !Array.isArray(testsConfig)) {
+        return tests;
+    }
+    for (const testDef of testsConfig) {
+        // Parse "input.json -> expected.json" format
+        const match = testDef.match(/^\s*(.+?)\s*->\s*(.+?)\s*$/);
+        if (!match) {
+            continue;
+        }
+        const inputRelPath = match[1];
+        const expectedRelPath = match[2];
+        // Get the module directory
+        const moduleDir = path.dirname(modulePath);
+        const inputPath = path.resolve(moduleDir, inputRelPath);
+        const expectedPath = path.resolve(moduleDir, expectedRelPath);
+        // Extract test name from input file
+        const testName = path.basename(inputRelPath, '.input.json');
+        tests.push({
+            name: testName,
+            inputPath,
+            expectedPath,
+        });
+    }
+    return tests;
+}
+/**
+ * Auto-discover test cases in tests/ directory
+ */
+export function discoverTestCases(modulePath) {
+    const tests = [];
+    const moduleDir = path.dirname(modulePath);
+    const testsDir = path.join(moduleDir, 'tests');
+    if (!fs.existsSync(testsDir)) {
+        return tests;
+    }
+    const files = fs.readdirSync(testsDir);
+    const inputFiles = files.filter(f => f.endsWith('.input.json'));
+    for (const inputFile of inputFiles) {
+        const testName = inputFile.replace('.input.json', '');
+        const expectedFile = `${testName}.expected.json`;
+        if (files.includes(expectedFile)) {
+            tests.push({
+                name: testName,
+                inputPath: path.join(testsDir, inputFile),
+                expectedPath: path.join(testsDir, expectedFile),
+            });
+        }
+    }
+    return tests;
+}
+// =============================================================================
+// Test Execution
+// =============================================================================
+/**
+ * Check if expected file uses schema validation format ($validate)
+ */
+function isSchemaValidationFormat(expected) {
+    return (typeof expected === 'object' &&
+        expected !== null &&
+        '$validate' in expected);
+}
+/**
+ * Validate actual result against schema validation format
+ * Returns array of validation errors
+ */
+function validateAgainstSchema(schema, actual, path = '') {
+    const errors = [];
+    if (actual === null || actual === undefined) {
+        errors.push({ field: path || 'root', expected: 'value', actual });
+        return errors;
+    }
+    // Handle const constraint
+    if ('const' in schema) {
+        if (actual !== schema.const) {
+            errors.push({ field: path || 'root', expected: `const: ${schema.const}`, actual });
+        }
+        return errors;
+    }
+    // Handle type constraint
+    if ('type' in schema) {
+        const schemaType = schema.type;
+        const actualType = Array.isArray(actual) ? 'array' : typeof actual;
+        if (schemaType === 'array' && !Array.isArray(actual)) {
+            errors.push({ field: path || 'root', expected: 'array', actual: actualType });
+            return errors;
+        }
+        if (schemaType === 'object' && (typeof actual !== 'object' || Array.isArray(actual))) {
+            errors.push({ field: path || 'root', expected: 'object', actual: actualType });
+            return errors;
+        }
+        if (schemaType === 'number' && typeof actual !== 'number') {
+            errors.push({ field: path || 'root', expected: 'number', actual: actualType });
+            return errors;
+        }
+        if (schemaType === 'string' && typeof actual !== 'string') {
+            errors.push({ field: path || 'root', expected: 'string', actual: actualType });
+            return errors;
+        }
+    }
+    // Handle number constraints
+    if (typeof actual === 'number') {
+        if ('minimum' in schema && actual < schema.minimum) {
+            errors.push({ field: path, expected: `>= ${schema.minimum}`, actual });
+        }
+        if ('maximum' in schema && actual > schema.maximum) {
+            errors.push({ field: path, expected: `<= ${schema.maximum}`, actual });
+        }
+    }
+    // Handle string constraints
+    if (typeof actual === 'string') {
+        if ('minLength' in schema && actual.length < schema.minLength) {
+            errors.push({ field: path, expected: `minLength: ${schema.minLength}`, actual: `length: ${actual.length}` });
+        }
+        if ('maxLength' in schema && actual.length > schema.maxLength) {
+            errors.push({ field: path, expected: `maxLength: ${schema.maxLength}`, actual: `length: ${actual.length}` });
+        }
+        if ('enum' in schema && !(schema.enum.includes(actual))) {
+            errors.push({ field: path, expected: `enum: ${JSON.stringify(schema.enum)}`, actual });
+        }
+    }
+    // Handle array constraints
+    if (Array.isArray(actual)) {
+        if ('minItems' in schema && actual.length < schema.minItems) {
+            errors.push({ field: path, expected: `minItems: ${schema.minItems}`, actual: `length: ${actual.length}` });
+        }
+        if ('items' in schema) {
+            const itemSchema = schema.items;
+            for (let i = 0; i < actual.length; i++) {
+                errors.push(...validateAgainstSchema(itemSchema, actual[i], `${path}[${i}]`));
+            }
+        }
+    }
+    // Handle object constraints
+    if (typeof actual === 'object' && !Array.isArray(actual) && actual !== null) {
+        const actualObj = actual;
+        // Check required fields
+        if ('required' in schema) {
+            const required = schema.required;
+            for (const field of required) {
+                if (!(field in actualObj)) {
+                    errors.push({ field: `${path}.${field}`, expected: 'required field', actual: 'missing' });
+                }
+            }
+        }
+        // Validate properties
+        if ('properties' in schema) {
+            const properties = schema.properties;
+            for (const [key, propSchema] of Object.entries(properties)) {
+                if (key in actualObj) {
+                    errors.push(...validateAgainstSchema(propSchema, actualObj[key], path ? `${path}.${key}` : key));
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Compare two values and return differences
+ */
+function deepCompare(expected, actual, path = '') {
+    const diffs = [];
+    // Handle null/undefined
+    if (expected === null || expected === undefined) {
+        if (actual !== expected) {
+            diffs.push({ field: path || 'root', expected, actual });
+        }
+        return diffs;
+    }
+    // Type mismatch
+    if (typeof expected !== typeof actual) {
+        diffs.push({ field: path || 'root', expected, actual });
+        return diffs;
+    }
+    // Arrays
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual)) {
+            diffs.push({ field: path || 'root', expected, actual });
+            return diffs;
+        }
+        if (expected.length !== actual.length) {
+            diffs.push({ field: `${path}.length`, expected: expected.length, actual: actual.length });
+        }
+        const maxLen = Math.max(expected.length, actual.length);
+        for (let i = 0; i < maxLen; i++) {
+            diffs.push(...deepCompare(expected[i], actual[i], `${path}[${i}]`));
+        }
+        return diffs;
+    }
+    // Objects
+    if (typeof expected === 'object') {
+        if (typeof actual !== 'object' || actual === null) {
+            diffs.push({ field: path || 'root', expected, actual });
+            return diffs;
+        }
+        const expectedObj = expected;
+        const actualObj = actual;
+        const allKeys = new Set([...Object.keys(expectedObj), ...Object.keys(actualObj)]);
+        for (const key of allKeys) {
+            // Skip dynamic fields that change between runs
+            if (['trace_id', 'latency_ms', 'model', 'timestamp', 'version'].includes(key)) {
+                continue;
+            }
+            const fieldPath = path ? `${path}.${key}` : key;
+            if (!(key in expectedObj)) {
+                // Extra field in actual - only report if it's significant
+                continue;
+            }
+            if (!(key in actualObj)) {
+                diffs.push({ field: fieldPath, expected: expectedObj[key], actual: undefined });
+                continue;
+            }
+            diffs.push(...deepCompare(expectedObj[key], actualObj[key], fieldPath));
+        }
+        return diffs;
+    }
+    // Primitives
+    if (expected !== actual) {
+        // For confidence, allow small variations
+        if (path.endsWith('.confidence') && typeof expected === 'number' && typeof actual === 'number') {
+            if (Math.abs(expected - actual) <= 0.1) {
+                return diffs; // Close enough
+            }
+        }
+        diffs.push({ field: path || 'root', expected, actual });
+    }
+    return diffs;
+}
+/**
+ * Run a single test case
+ */
+async function runTestCase(testCase, module, ctx, options = {}) {
+    const startTime = Date.now();
+    const { timeout = 60000 } = options;
+    try {
+        // Load input
+        if (!fs.existsSync(testCase.inputPath)) {
+            return {
+                name: testCase.name,
+                passed: false,
+                duration_ms: Date.now() - startTime,
+                error: `Input file not found: ${testCase.inputPath}`,
+            };
+        }
+        const inputContent = fs.readFileSync(testCase.inputPath, 'utf-8');
+        const input = JSON.parse(inputContent);
+        // Load expected (if exists)
+        let expected = null;
+        if (fs.existsSync(testCase.expectedPath)) {
+            const expectedContent = fs.readFileSync(testCase.expectedPath, 'utf-8');
+            expected = JSON.parse(expectedContent);
+        }
+        // Run module with timeout
+        const runPromise = runModule(module, ctx.provider, {
+            input,
+            validateInput: true,
+            validateOutput: true,
+            useV22: true,
+        });
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(`Test timeout after ${timeout}ms`)), timeout);
+        });
+        const result = await Promise.race([runPromise, timeoutPromise]);
+        // Update mode - write actual output as expected
+        if (options.update) {
+            fs.writeFileSync(testCase.expectedPath, JSON.stringify(result, null, 2));
+            return {
+                name: testCase.name,
+                passed: true,
+                duration_ms: Date.now() - startTime,
+            };
+        }
+        // No expected file - skip comparison
+        if (expected === null) {
+            return {
+                name: testCase.name,
+                passed: false,
+                duration_ms: Date.now() - startTime,
+                error: `Expected file not found: ${testCase.expectedPath}`,
+            };
+        }
+        // Compare results - use schema validation or direct comparison
+        let diffs;
+        if (isSchemaValidationFormat(expected)) {
+            // Schema validation mode
+            diffs = validateAgainstSchema(expected.$validate, result);
+        }
+        else {
+            // Direct comparison mode
+            diffs = deepCompare(expected, result);
+        }
+        if (diffs.length === 0) {
+            return {
+                name: testCase.name,
+                passed: true,
+                duration_ms: Date.now() - startTime,
+            };
+        }
+        else {
+            return {
+                name: testCase.name,
+                passed: false,
+                duration_ms: Date.now() - startTime,
+                diff: diffs.slice(0, 10), // Limit to first 10 diffs
+                error: `${diffs.length} difference(s) found`,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            name: testCase.name,
+            passed: false,
+            duration_ms: Date.now() - startTime,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+// =============================================================================
+// Commands
+// =============================================================================
+/**
+ * Run tests for a single module
+ */
+export async function test(moduleName, ctx, options = {}) {
+    const startTime = Date.now();
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    // Find module
+    const module = await findModule(moduleName, searchPaths);
+    if (!module) {
+        return {
+            success: false,
+            error: `Module '${moduleName}' not found`,
+        };
+    }
+    // Get test cases from module.yaml or auto-discover
+    let testCases = parseTestDefinitions(module, module.location);
+    if (testCases.length === 0) {
+        testCases = discoverTestCases(module.location);
+    }
+    if (testCases.length === 0) {
+        return {
+            success: true,
+            data: {
+                moduleName: module.name,
+                modulePath: module.location,
+                total: 0,
+                passed: 0,
+                failed: 0,
+                skipped: 0,
+                duration_ms: Date.now() - startTime,
+                results: [],
+            },
+        };
+    }
+    // Filter tests if specified
+    if (options.filter) {
+        testCases = testCases.filter(tc => tc.name.includes(options.filter));
+    }
+    // Run tests
+    const results = [];
+    let passed = 0;
+    let failed = 0;
+    for (const testCase of testCases) {
+        if (options.verbose) {
+            console.error(`  Running: ${testCase.name}...`);
+        }
+        const result = await runTestCase(testCase, module, ctx, options);
+        results.push(result);
+        if (result.passed) {
+            passed++;
+        }
+        else {
+            failed++;
+        }
+    }
+    const testResult = {
+        moduleName: module.name,
+        modulePath: module.location,
+        total: testCases.length,
+        passed,
+        failed,
+        skipped: 0,
+        duration_ms: Date.now() - startTime,
+        results,
+    };
+    return {
+        success: failed === 0,
+        data: testResult,
+    };
+}
+/**
+ * Run tests for all modules
+ */
+export async function testAll(ctx, options = {}) {
+    const startTime = Date.now();
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    // List all modules
+    const modules = await listModules(searchPaths);
+    const results = [];
+    let totalTests = 0;
+    let totalPassed = 0;
+    let totalFailed = 0;
+    let modulesWithTests = 0;
+    for (const moduleInfo of modules) {
+        const result = await test(moduleInfo.name, ctx, options);
+        if (result.success && result.data) {
+            const moduleResult = result.data;
+            results.push(moduleResult);
+            if (moduleResult.total > 0) {
+                modulesWithTests++;
+                totalTests += moduleResult.total;
+                totalPassed += moduleResult.passed;
+                totalFailed += moduleResult.failed;
+            }
+        }
+    }
+    return {
+        success: totalFailed === 0,
+        data: {
+            total: totalTests,
+            passed: totalPassed,
+            failed: totalFailed,
+            skipped: modules.length - modulesWithTests,
+            duration_ms: Date.now() - startTime,
+            modules: results,
+        },
+    };
+}

package/dist/commands/update.d.ts

@@ -7,6 +7,7 @@
 import type { CommandContext, CommandResult } from '../types.js';
 export interface UpdateOptions {
     tag?: string;
+    registry?: string;
 }
 /**
  * Update an installed module

package/dist/commands/update.js

@@ -6,15 +6,38 @@
  */
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve, sep, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
-import { add, getInstallInfo } from './add.js';
+import { add, addFromRegistry, getInstallInfo } from './add.js';
+import { RegistryClient } from '../registry/client.js';
 const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
+function assertSafeModuleName(name) {
+    const trimmed = name.trim();
+    if (!trimmed) {
+        throw new Error('Invalid module name: empty');
+    }
+    if (trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
+        throw new Error(`Invalid module name: ${name}`);
+    }
+    if (isAbsolute(trimmed)) {
+        throw new Error(`Invalid module name (absolute path not allowed): ${name}`);
+    }
+    return trimmed;
+}
+function resolveModuleTarget(moduleName) {
+    const safeName = assertSafeModuleName(moduleName);
+    const targetPath = resolve(USER_MODULES_DIR, safeName);
+    const root = resolve(USER_MODULES_DIR) + sep;
+    if (!targetPath.startsWith(root)) {
+        throw new Error(`Invalid module name (path traversal): ${moduleName}`);
+    }
+    return targetPath;
+}
 /**
  * Get module version from installed module
  */
 async function getInstalledVersion(moduleName) {
-    const modulePath = join(USER_MODULES_DIR, moduleName);
+    const modulePath = resolveModuleTarget(moduleName);
     if (!existsSync(modulePath)) {
         return undefined;
     }
@@ -46,29 +69,97 @@ async function getInstalledVersion(moduleName) {
  * Update an installed module
  */
 export async function update(moduleName, ctx, options = {}) {
+    let safeName;
+    try {
+        safeName = assertSafeModuleName(moduleName);
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
     // Get installation info
-    const info = await getInstallInfo(moduleName);
+    const info = await getInstallInfo(safeName);
     if (!info) {
         return {
             success: false,
-            error: `Module not found or not installed from GitHub: ${moduleName}. Only modules installed with 'cog add' can be updated.`,
+            error: `Module not found or not installed with 'cog add': ${safeName}. Only modules installed with 'cog add' can be updated.`,
         };
     }
+    // Get current version
+    const oldVersion = await getInstalledVersion(safeName);
+    // Check if module was installed from registry
+    if (info.registryModule) {
+        const registryModule = info.registryModule;
+        // Use undefined instead of empty string for default registry URL
+        const registryUrl = info.registryUrl || undefined;
+        // Check registry for latest version
+        const client = new RegistryClient(registryUrl);
+        const registryInfo = await client.getModule(registryModule);
+        if (!registryInfo) {
+            return {
+                success: false,
+                error: `Module '${registryModule}' is no longer available in the registry.`,
+            };
+        }
+        // Warn if deprecated
+        if (registryInfo.deprecated) {
+            console.warn(`Warning: Module '${registryModule}' is deprecated.`);
+        }
+        const targetVersion = options.tag || registryInfo.version;
+        // Re-install from registry with optional version
+        const moduleSpec = options.tag ? `${registryModule}@${options.tag}` : registryModule;
+        const result = await addFromRegistry(moduleSpec, ctx, {
+            name: safeName,
+            registry: registryUrl,
+        });
+        if (!result.success) {
+            return result;
+        }
+        const data = result.data;
+        const newVersion = data.version || targetVersion;
+        // Determine message
+        let message;
+        if (oldVersion && newVersion) {
+            if (oldVersion === newVersion) {
+                message = `Already up to date: ${safeName} v${newVersion}`;
+            }
+            else {
+                message = `Updated: ${safeName} v${oldVersion} → v${newVersion}`;
+            }
+        }
+        else if (newVersion) {
+            message = `Updated: ${safeName} to v${newVersion}`;
+        }
+        else {
+            message = `Updated: ${safeName}`;
+        }
+        return {
+            success: true,
+            data: {
+                message,
+                name: safeName,
+                oldVersion,
+                newVersion,
+                source: 'registry',
+            },
+        };
+    }
+    // GitHub-based update
     if (!info.githubUrl) {
         return {
             success: false,
-            error: `Module was not installed from GitHub: ${moduleName}`,
+            error: `Module was not installed from GitHub or registry: ${moduleName}`,
         };
     }
-    // Get current version
-    const oldVersion = await getInstalledVersion(moduleName);
     // Determine what ref to use
     const tag = options.tag || info.tag;
     const branch = info.branch || 'main';
     // Re-install from source
     const result = await add(info.githubUrl, ctx, {
         module: info.modulePath,
-        name: moduleName,
+        name: safeName,
         tag,
         branch: tag ? undefined : branch,
     });
@@ -81,25 +172,26 @@ export async function update(moduleName, ctx, options = {}) {
     let message;
     if (oldVersion && newVersion) {
         if (oldVersion === newVersion) {
-            message = `Already up to date: ${moduleName} v${newVersion}`;
+            message = `Already up to date: ${safeName} v${newVersion}`;
         }
         else {
-            message = `Updated: ${moduleName} v${oldVersion} → v${newVersion}`;
+            message = `Updated: ${safeName} v${oldVersion} → v${newVersion}`;
         }
     }
     else if (newVersion) {
-        message = `Updated: ${moduleName} to v${newVersion}`;
+        message = `Updated: ${safeName} to v${newVersion}`;
     }
     else {
-        message = `Updated: ${moduleName}`;
+        message = `Updated: ${safeName}`;
     }
     return {
         success: true,
         data: {
             message,
-            name: moduleName,
+            name: safeName,
             oldVersion,
             newVersion,
+            source: 'github',
         },
     };
 }

package/dist/commands/validate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * cog validate - Validate a Cognitive Module's structure and examples
+ *
+ * Aligns with Python CLI's `cog validate` command.
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface ValidateOptions {
+    /** Enable strict v2.2 validation */
+    v22?: boolean;
+    /** Output format: 'text' or 'json' */
+    format?: 'text' | 'json';
+}
+export interface ValidateResult {
+    valid: boolean;
+    modulePath: string;
+    moduleName?: string;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate a cognitive module's structure and examples.
+ *
+ * @param nameOrPath Module name or path
+ * @param ctx Command context
+ * @param options Validation options
+ * @returns Validation result
+ */
+export declare function validate(nameOrPath: string, ctx: CommandContext, options?: ValidateOptions): Promise<CommandResult>;
+/**
+ * Validate all modules in the search paths.
+ *
+ * @param ctx Command context
+ * @param options Validation options
+ * @returns Batch validation results
+ */
+export declare function validateAll(ctx: CommandContext, options?: ValidateOptions): Promise<CommandResult>;