cognitive-modules-cli 2.2.1 → 2.2.7

package/dist/commands/pipe.js

@@ -1,16 +1,25 @@
 /**
  * cog pipe - Pipe mode for stdin/stdout integration
+ * Always returns v2.2 envelope format for consistency
  */
 import * as readline from 'node:readline';
 import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+import { ErrorCodes, attachContext, makeErrorEnvelope } from '../errors/index.js';
 export async function pipe(ctx, options) {
     const searchPaths = getDefaultSearchPaths(ctx.cwd);
     // Find module
     const module = await findModule(options.module, searchPaths);
     if (!module) {
+        const errorEnvelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.MODULE_NOT_FOUND,
+            message: `Module not found: ${options.module}`,
+            suggestion: "Use 'cog list' to see installed modules",
+        }), { module: options.module, provider: ctx.provider.name });
+        console.log(JSON.stringify(errorEnvelope));
         return {
             success: false,
-            error: `Module not found: ${options.module}`,
+            error: errorEnvelope.error.message,
+            data: errorEnvelope,
         };
     }
     // Read from stdin
@@ -33,27 +42,38 @@ export async function pipe(ctx, options) {
         catch {
             // Not JSON, use as args
         }
+        // Run module with v2.2 envelope format
         const result = await runModule(module, ctx.provider, {
             args: inputData ? undefined : input,
             input: inputData,
+            validateInput: !options.noValidate,
+            validateOutput: !options.noValidate,
+            useV22: true, // Always use v2.2 envelope
         });
-        // Output envelope format to stdout
-        console.log(JSON.stringify(result));
+        const output = attachContext(result, {
+            module: options.module,
+            provider: ctx.provider.name,
+        });
+        // Output v2.2 envelope format to stdout
+        console.log(JSON.stringify(output));
         return {
             success: result.ok,
-            data: result,
+            data: output,
         };
     }
     catch (e) {
-        const error = e instanceof Error ? e.message : String(e);
-        // Output error in envelope format
-        console.log(JSON.stringify({
-            ok: false,
-            error: { code: 'RUNTIME_ERROR', message: error }
-        }));
+        const message = e instanceof Error ? e.message : String(e);
+        // Output v2.2 compliant error envelope
+        const errorEnvelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.INTERNAL_ERROR,
+            message,
+            recoverable: false,
+        }), { module: options.module, provider: ctx.provider.name });
+        console.log(JSON.stringify(errorEnvelope));
         return {
             success: false,
-            error,
+            error: message,
+            data: errorEnvelope,
         };
     }
 }

package/dist/commands/remove.js

@@ -5,15 +5,46 @@
  */
 import { existsSync, rmSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve, sep, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
 const INSTALLED_MANIFEST = join(homedir(), '.cognitive', 'installed.json');
+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;
+}
 /**
  * Remove an installed module
  */
 export async function remove(moduleName, ctx) {
-    const modulePath = join(USER_MODULES_DIR, moduleName);
+    let modulePath;
+    try {
+        modulePath = resolveModuleTarget(moduleName);
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
     if (!existsSync(modulePath)) {
         return {
             success: false,

package/dist/commands/run.d.ts

@@ -1,5 +1,6 @@
 /**
  * cog run - Run a Cognitive Module
+ * Always returns v2.2 envelope format for consistency
  */
 import type { CommandContext, CommandResult } from '../types.js';
 export interface RunOptions {
@@ -8,5 +9,6 @@ export interface RunOptions {
     noValidate?: boolean;
     pretty?: boolean;
     verbose?: boolean;
+    stream?: boolean;
 }
 export declare function run(moduleName: string, ctx: CommandContext, options?: RunOptions): Promise<CommandResult>;

package/dist/commands/run.js

@@ -1,15 +1,23 @@
 /**
  * cog run - Run a Cognitive Module
+ * Always returns v2.2 envelope format for consistency
  */
-import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+import { findModule, getDefaultSearchPaths, runModule, runModuleStream } from '../modules/index.js';
+import { ErrorCodes, attachContext, makeErrorEnvelope } from '../errors/index.js';
 export async function run(moduleName, ctx, options = {}) {
     const searchPaths = getDefaultSearchPaths(ctx.cwd);
     // Find module
     const module = await findModule(moduleName, searchPaths);
     if (!module) {
+        const errorEnvelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.MODULE_NOT_FOUND,
+            message: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+            suggestion: "Use 'cog list' to see installed modules or 'cog search' to find modules in registry",
+        }), { module: moduleName, provider: ctx.provider.name });
         return {
             success: false,
-            error: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+            error: errorEnvelope.error.message,
+            data: errorEnvelope,
         };
     }
     try {
@@ -20,46 +28,71 @@ export async function run(moduleName, ctx, options = {}) {
                 inputData = JSON.parse(options.input);
             }
             catch {
+                const errorEnvelope = attachContext(makeErrorEnvelope({
+                    code: ErrorCodes.INVALID_INPUT,
+                    message: `Invalid JSON input: ${options.input}`,
+                    suggestion: 'Ensure input is valid JSON format',
+                }), { module: moduleName, provider: ctx.provider.name });
                 return {
                     success: false,
-                    error: `Invalid JSON input: ${options.input}`,
+                    error: errorEnvelope.error.message,
+                    data: errorEnvelope,
                 };
             }
         }
-        // Run module
-        const result = await runModule(module, ctx.provider, {
-            args: options.args,
-            input: inputData,
-            verbose: options.verbose || ctx.verbose,
-        });
-        // Return envelope format or extracted data
-        if (options.pretty) {
+        if (options.stream) {
+            // Stream NDJSON events to stdout. Final exit code is determined by the end event.
+            let finalOk = null;
+            for await (const ev of runModuleStream(module, ctx.provider, {
+                args: options.args,
+                input: inputData,
+                validateInput: !options.noValidate,
+                validateOutput: !options.noValidate,
+                useV22: true,
+            })) {
+                // Write each event as one JSON line (NDJSON).
+                process.stdout.write(JSON.stringify(ev) + '\n');
+                if (ev.type === 'end' && ev.result) {
+                    finalOk = Boolean(ev.result.ok);
+                }
+            }
             return {
-                success: result.ok,
-                data: result,
+                success: finalOk === true,
+                data: { ok: finalOk === true },
             };
         }
         else {
-            // For non-pretty mode, return data (success) or error (failure)
-            if (result.ok) {
-                return {
-                    success: true,
-                    data: result.data,
-                };
-            }
-            else {
-                return {
-                    success: false,
-                    error: `${result.error?.code}: ${result.error?.message}`,
-                    data: result.partial_data,
-                };
-            }
+            // Run module with v2.2 envelope format
+            const result = await runModule(module, ctx.provider, {
+                args: options.args,
+                input: inputData,
+                verbose: options.verbose || ctx.verbose,
+                validateInput: !options.noValidate,
+                validateOutput: !options.noValidate,
+                useV22: true, // Always use v2.2 envelope
+            });
+            const output = attachContext(result, {
+                module: moduleName,
+                provider: ctx.provider.name,
+            });
+            // Always return full v2.2 envelope
+            return {
+                success: result.ok,
+                data: output,
+            };
         }
     }
     catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        const errorEnvelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.INTERNAL_ERROR,
+            message,
+            recoverable: false,
+        }), { module: moduleName, provider: ctx.provider.name });
         return {
             success: false,
-            error: e instanceof Error ? e.message : String(e),
+            error: message,
+            data: errorEnvelope,
         };
     }
 }

package/dist/commands/search.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Search command - Search for modules in the registry
+ *
+ * cog search code review
+ * cog search --category code-quality
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface SearchOptions {
+    category?: string;
+    limit?: number;
+    registry?: string;
+}
+/**
+ * Search for modules in the registry
+ */
+export declare function search(query: string, ctx: CommandContext, options?: SearchOptions): Promise<CommandResult>;
+/**
+ * List all categories
+ */
+export declare function listCategories(ctx: CommandContext, options?: {
+    registry?: string;
+}): Promise<CommandResult>;
+/**
+ * Get detailed info about a module from registry
+ */
+export declare function info(moduleName: string, ctx: CommandContext, options?: {
+    registry?: string;
+}): Promise<CommandResult>;

package/dist/commands/search.js

@@ -0,0 +1,143 @@
+/**
+ * Search command - Search for modules in the registry
+ *
+ * cog search code review
+ * cog search --category code-quality
+ */
+import { RegistryClient } from '../registry/client.js';
+/**
+ * Search for modules in the registry
+ */
+export async function search(query, ctx, options = {}) {
+    const { category, limit = 20, registry } = options;
+    try {
+        const client = new RegistryClient(registry);
+        let results;
+        if (category) {
+            // Search within category
+            const categories = await client.getCategories();
+            const cat = categories[category];
+            if (!cat) {
+                return {
+                    success: false,
+                    error: `Category not found: ${category}\nAvailable categories: ${Object.keys(categories).join(', ')}`,
+                };
+            }
+            // Get modules in category
+            const modules = [];
+            for (const name of cat.modules) {
+                const mod = await client.getModule(name);
+                if (mod) {
+                    modules.push(mod);
+                }
+            }
+            // If query provided, filter by query
+            if (query) {
+                results = modules
+                    .filter(m => m.name.toLowerCase().includes(query.toLowerCase()) ||
+                    m.description.toLowerCase().includes(query.toLowerCase()))
+                    .map(m => ({
+                    name: m.name,
+                    description: m.description,
+                    version: m.version,
+                    score: 1,
+                    keywords: m.keywords,
+                }));
+            }
+            else {
+                results = modules.map(m => ({
+                    name: m.name,
+                    description: m.description,
+                    version: m.version,
+                    score: 1,
+                    keywords: m.keywords,
+                }));
+            }
+        }
+        else if (query) {
+            // Search by query
+            results = await client.search(query);
+        }
+        else {
+            // List all modules
+            const modules = await client.listModules();
+            results = modules.map(m => ({
+                name: m.name,
+                description: m.description,
+                version: m.version,
+                score: 1,
+                keywords: m.keywords,
+            }));
+        }
+        // Apply limit
+        const limited = results.slice(0, limit);
+        return {
+            success: true,
+            data: {
+                query,
+                category,
+                total: results.length,
+                results: limited,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * List all categories
+ */
+export async function listCategories(ctx, options = {}) {
+    try {
+        const client = new RegistryClient(options.registry);
+        const categories = await client.getCategories();
+        return {
+            success: true,
+            data: {
+                categories: Object.entries(categories).map(([key, cat]) => ({
+                    key,
+                    name: cat.name,
+                    description: cat.description,
+                    moduleCount: cat.modules.length,
+                })),
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Get detailed info about a module from registry
+ */
+export async function info(moduleName, ctx, options = {}) {
+    try {
+        const client = new RegistryClient(options.registry);
+        const module = await client.getModule(moduleName);
+        if (!module) {
+            return {
+                success: false,
+                error: `Module not found in registry: ${moduleName}`,
+            };
+        }
+        return {
+            success: true,
+            data: {
+                module,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 type { CommandContext, CommandResult, CognitiveModule } from '../types.js';
+export interface TestCase {
+    name: string;
+    inputPath: string;
+    expectedPath: string;
+    input?: unknown;
+    expected?: unknown;
+}
+export interface TestResult {
+    name: string;
+    passed: boolean;
+    duration_ms: number;
+    error?: string;
+    diff?: {
+        field: string;
+        expected: unknown;
+        actual: unknown;
+    }[];
+}
+export interface ModuleTestResult {
+    moduleName: string;
+    modulePath: string;
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    duration_ms: number;
+    results: TestResult[];
+}
+export interface TestOptions {
+    verbose?: boolean;
+    update?: boolean;
+    filter?: string;
+    timeout?: number;
+}
+/**
+ * Parse test definitions from module.yaml tests field
+ *
+ * Format: "tests/case1.input.json -> tests/case1.expected.json"
+ */
+export declare function parseTestDefinitions(module: CognitiveModule, modulePath: string): TestCase[];
+/**
+ * Auto-discover test cases in tests/ directory
+ */
+export declare function discoverTestCases(modulePath: string): TestCase[];
+/**
+ * Run tests for a single module
+ */
+export declare function test(moduleName: string, ctx: CommandContext, options?: TestOptions): Promise<CommandResult>;
+/**
+ * Run tests for all modules
+ */
+export declare function testAll(ctx: CommandContext, options?: TestOptions): Promise<CommandResult>;