cognitive-modules-cli 1.4.1 → 2.2.1

package/src/cli.ts

@@ -16,7 +16,7 @@
 
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
-import { run, list, pipe, init, add, update, remove, versions } from './commands/index.js';
+import { run, list, pipe, init, add, update, remove, versions, compose, composeInfo } from './commands/index.js';
 import type { CommandContext } from './types.js';
 
 const VERSION = '1.3.0';
@@ -55,6 +55,10 @@ async function main() {
       // Server options
       host: { type: 'string', short: 'H' },
       port: { type: 'string', short: 'P' },
+      // Compose options
+      'max-depth': { type: 'string', short: 'd' },
+      timeout: { type: 'string', short: 'T' },
+      trace: { type: 'boolean', default: false },
     },
     allowPositionals: true,
   });
@@ -291,6 +295,53 @@ async function main() {
         break;
       }
 
+      case 'compose': {
+        const moduleName = args[1];
+        if (!moduleName || moduleName.startsWith('-')) {
+          console.error('Usage: cog compose <module> [--args "..."] [--timeout <ms>] [--max-depth <n>]');
+          process.exit(1);
+        }
+        
+        const result = await compose(moduleName, ctx, {
+          args: values.args,
+          input: values.input,
+          maxDepth: values['max-depth'] ? parseInt(values['max-depth'] as string, 10) : undefined,
+          timeout: values.timeout ? parseInt(values.timeout as string, 10) : undefined,
+          trace: values.trace,
+          pretty: values.pretty,
+          verbose: values.verbose,
+        });
+        
+        if (!result.success) {
+          console.error(`Error: ${result.error}`);
+          if (result.data) {
+            console.error('Partial results:', JSON.stringify(result.data, null, 2));
+          }
+          process.exit(1);
+        }
+        
+        console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+        break;
+      }
+
+      case 'compose-info': {
+        const moduleName = args[1];
+        if (!moduleName || moduleName.startsWith('-')) {
+          console.error('Usage: cog compose-info <module>');
+          process.exit(1);
+        }
+        
+        const result = await composeInfo(moduleName, ctx);
+        
+        if (!result.success) {
+          console.error(`Error: ${result.error}`);
+          process.exit(1);
+        }
+        
+        console.log(JSON.stringify(result.data, null, 2));
+        break;
+      }
+
       case 'serve': {
         const { serve } = await import('./server/http.js');
         const port = values.port ? parseInt(values.port as string, 10) : 8000;
@@ -338,17 +389,19 @@ USAGE:
   cog <command> [options]
 
 COMMANDS:
-  run <module>      Run a Cognitive Module
-  list              List available modules
-  add <url>         Add module from GitHub
-  update <module>   Update module to latest version
-  remove <module>   Remove installed module
-  versions <url>    List available versions
-  pipe              Pipe mode (stdin/stdout)
-  init [name]       Initialize project or create module
-  serve             Start HTTP API server
-  mcp               Start MCP server (for Claude Code, Cursor)
-  doctor            Check configuration
+  run <module>        Run a Cognitive Module
+  compose <module>    Execute a composed module workflow
+  compose-info <mod>  Show composition configuration
+  list                List available modules
+  add <url>           Add module from GitHub
+  update <module>     Update module to latest version
+  remove <module>     Remove installed module
+  versions <url>      List available versions
+  pipe                Pipe mode (stdin/stdout)
+  init [name]         Initialize project or create module
+  serve               Start HTTP API server
+  mcp                 Start MCP server (for Claude Code, Cursor)
+  doctor              Check configuration
 
 OPTIONS:
   -a, --args <str>      Arguments to pass to module
@@ -364,6 +417,9 @@ OPTIONS:
   --no-validate         Skip schema validation
   -H, --host <host>     Server host (default: 0.0.0.0)
   -P, --port <port>     Server port (default: 8000)
+  -d, --max-depth <n>   Max composition depth (default: 5)
+  -T, --timeout <ms>    Composition timeout in milliseconds
+  --trace               Include execution trace (for compose)
   -v, --version         Show version
   -h, --help            Show this help
 
@@ -382,6 +438,11 @@ EXAMPLES:
   cog run code-reviewer --provider openai --model gpt-4o --args "..."
   cog list
 
+  # Compose modules (multi-step workflows)
+  cog compose code-review-pipeline --args "code to review"
+  cog compose smart-processor --args "input" --timeout 60000 --verbose
+  cog compose-info code-review-pipeline
+
   # Servers
   cog serve --port 8080
   cog mcp

package/src/commands/compose.ts

@@ -0,0 +1,185 @@
+/**
+ * cog compose - Execute a Composed Cognitive Module Workflow
+ * 
+ * Supports all composition patterns:
+ * - Sequential: A → B → C
+ * - Parallel: A → [B, C, D] → Aggregate
+ * - Conditional: A → (condition) → B or C
+ * - Iterative: A → (check) → A → ... → Done
+ */
+
+import type { CommandContext, CommandResult } from '../types.js';
+import { findModule, getDefaultSearchPaths, executeComposition } from '../modules/index.js';
+
+export interface ComposeOptions {
+  /** Direct text input */
+  args?: string;
+  /** JSON input data */
+  input?: string;
+  /** Maximum composition depth */
+  maxDepth?: number;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Include execution trace */
+  trace?: boolean;
+  /** Pretty print output */
+  pretty?: boolean;
+  /** Verbose mode */
+  verbose?: boolean;
+}
+
+export async function compose(
+  moduleName: string,
+  ctx: CommandContext,
+  options: ComposeOptions = {}
+): Promise<CommandResult> {
+  const searchPaths = getDefaultSearchPaths(ctx.cwd);
+  
+  // Find module
+  const module = await findModule(moduleName, searchPaths);
+  if (!module) {
+    return {
+      success: false,
+      error: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+    };
+  }
+
+  try {
+    // Parse input if provided as JSON
+    let inputData: Record<string, unknown> = {};
+    if (options.input) {
+      try {
+        inputData = JSON.parse(options.input);
+      } catch {
+        return {
+          success: false,
+          error: `Invalid JSON input: ${options.input}`,
+        };
+      }
+    }
+    
+    // Handle --args as text input
+    if (options.args) {
+      inputData.query = options.args;
+      inputData.code = options.args;
+    }
+
+    // Execute composition
+    const result = await executeComposition(
+      moduleName,
+      inputData,
+      ctx.provider,
+      {
+        cwd: ctx.cwd,
+        maxDepth: options.maxDepth,
+        timeoutMs: options.timeout
+      }
+    );
+
+    if (options.verbose) {
+      console.error('--- Composition Trace ---');
+      for (const entry of result.trace) {
+        const status = entry.success 
+          ? (entry.skipped ? '⏭️ SKIPPED' : '✅ OK') 
+          : '❌ FAILED';
+        console.error(`${status} ${entry.module} (${entry.durationMs}ms)`);
+        if (entry.reason) {
+          console.error(`   Reason: ${entry.reason}`);
+        }
+      }
+      console.error(`--- Total: ${result.totalTimeMs}ms ---`);
+    }
+
+    // Return result
+    if (options.trace) {
+      // Include full result with trace
+      return {
+        success: result.ok,
+        data: {
+          ok: result.ok,
+          result: result.result,
+          moduleResults: result.moduleResults,
+          trace: result.trace,
+          totalTimeMs: result.totalTimeMs,
+          error: result.error
+        }
+      };
+    } else if (options.pretty) {
+      return {
+        success: result.ok,
+        data: result.result,
+      };
+    } else {
+      // For non-pretty mode, return data (success) or error (failure)
+      if (result.ok && result.result) {
+        return {
+          success: true,
+          data: (result.result as { data?: unknown }).data,
+        };
+      } else {
+        return {
+          success: false,
+          error: result.error 
+            ? `${result.error.code}: ${result.error.message}` 
+            : 'Composition failed',
+          data: result.moduleResults,
+        };
+      }
+    }
+  } catch (e) {
+    return {
+      success: false,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}
+
+/**
+ * Show composition info for a module
+ */
+export async function composeInfo(
+  moduleName: string,
+  ctx: CommandContext
+): Promise<CommandResult> {
+  const searchPaths = getDefaultSearchPaths(ctx.cwd);
+  
+  const module = await findModule(moduleName, searchPaths);
+  if (!module) {
+    return {
+      success: false,
+      error: `Module not found: ${moduleName}`,
+    };
+  }
+
+  const composition = module.composition;
+  if (!composition) {
+    return {
+      success: true,
+      data: {
+        name: module.name,
+        hasComposition: false,
+        message: 'Module does not have composition configuration'
+      }
+    };
+  }
+
+  return {
+    success: true,
+    data: {
+      name: module.name,
+      hasComposition: true,
+      pattern: composition.pattern,
+      requires: composition.requires?.map(d => ({
+        name: d.name,
+        version: d.version,
+        optional: d.optional,
+        fallback: d.fallback
+      })),
+      dataflowSteps: composition.dataflow?.length ?? 0,
+      routingRules: composition.routing?.length ?? 0,
+      maxDepth: composition.max_depth,
+      timeoutMs: composition.timeout_ms,
+      iteration: composition.iteration
+    }
+  };
+}

package/src/commands/index.ts

@@ -10,3 +10,4 @@ export * from './add.js';
 export * from './update.js';
 export * from './remove.js';
 export * from './versions.js';
+export * from './compose.js';

package/src/index.ts

@@ -19,6 +19,15 @@ export type {
   FailureContract,
   CommandContext,
   CommandResult,
+  // v2.2 Composition Types
+  CompositionConfig,
+  CompositionPattern,
+  DependencyDeclaration,
+  DataflowStep,
+  DataflowMapping,
+  RoutingRule,
+  AggregationStrategy,
+  IterationConfig,
 } from './types.js';
 
 // Providers
@@ -43,6 +52,32 @@ export {
   runWithSubagents,
   parseCalls,
   createContext,
+  // Composition
+  CompositionOrchestrator,
+  executeComposition,
+  validateCompositionConfig,
+  evaluateJsonPath,
+  evaluateCondition,
+  applyMapping,
+  aggregateResults,
+  versionMatches,
+  resolveDependency,
+  COMPOSITION_ERRORS,
+  // Policy Enforcement
+  checkToolPolicy,
+  checkPolicy,
+  checkToolAllowed,
+  validateToolsAllowed,
+  getDeniedActions,
+  getDeniedTools,
+  getAllowedTools,
+  ToolCallInterceptor,
+  createPolicyAwareExecutor,
+  type PolicyAction,
+  type PolicyCheckResult,
+  type ToolCallRequest,
+  type ToolCallResult,
+  type ToolExecutor,
 } from './modules/index.js';
 
 // Server