cognitive-runtime 0.1.0

package/src/cli.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Cognitive Runtime CLI
+ * 
+ * cog run <module> --args "..."  - Run a module
+ * cog list                        - List available modules
+ * cog pipe --module <name>        - Pipe mode (stdin/stdout)
+ * cog doctor                      - Check configuration
+ */
+
+import { parseArgs } from 'node:util';
+import { getProvider, listProviders } from './providers/index.js';
+import { run, list, pipe, init } from './commands/index.js';
+import type { CommandContext } from './types.js';
+
+const VERSION = '0.1.0';
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log(`Cognitive Runtime v${VERSION}`);
+    process.exit(0);
+  }
+
+  // Parse common options
+  const { values } = parseArgs({
+    args: args.slice(1),
+    options: {
+      args: { type: 'string', short: 'a' },
+      input: { type: 'string', short: 'i' },
+      module: { type: 'string', short: 'm' },
+      provider: { type: 'string', short: 'p' },
+      pretty: { type: 'boolean', default: false },
+      verbose: { type: 'boolean', short: 'V', default: false },
+      'no-validate': { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  // Get provider
+  let provider;
+  try {
+    provider = getProvider(values.provider);
+  } catch (e) {
+    console.error(`Error: ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+  }
+
+  const ctx: CommandContext = {
+    cwd: process.cwd(),
+    provider,
+    verbose: values.verbose,
+  };
+
+  try {
+    switch (command) {
+      case 'run': {
+        const moduleName = args[1];
+        if (!moduleName || moduleName.startsWith('-')) {
+          console.error('Usage: cog run <module> [--args "..."]');
+          process.exit(1);
+        }
+        
+        const result = await run(moduleName, ctx, {
+          args: values.args,
+          input: values.input,
+          noValidate: values['no-validate'],
+          pretty: values.pretty,
+          verbose: values.verbose,
+        });
+        
+        if (!result.success) {
+          console.error(`Error: ${result.error}`);
+          process.exit(1);
+        }
+        
+        console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+        break;
+      }
+
+      case 'list': {
+        const result = await list(ctx);
+        if (!result.success) {
+          console.error(`Error: ${result.error}`);
+          process.exit(1);
+        }
+        
+        const data = result.data as { modules: Array<{ name: string; version: string; responsibility: string; location: string }> };
+        
+        if (data.modules.length === 0) {
+          console.log('No modules found.');
+        } else {
+          console.log('Available Modules:');
+          console.log('');
+          for (const m of data.modules) {
+            console.log(`  ${m.name} (v${m.version})`);
+            console.log(`    ${m.responsibility}`);
+            console.log(`    ${m.location}`);
+            console.log('');
+          }
+        }
+        break;
+      }
+
+      case 'pipe': {
+        const moduleName = values.module || args[1];
+        if (!moduleName) {
+          console.error('Usage: cog pipe --module <name>');
+          process.exit(1);
+        }
+        
+        await pipe(ctx, {
+          module: moduleName,
+          noValidate: values['no-validate'],
+        });
+        break;
+      }
+
+      case 'init': {
+        const moduleName = args[1];
+        const result = await init(ctx, moduleName);
+        
+        if (!result.success) {
+          console.error(`Error: ${result.error}`);
+          process.exit(1);
+        }
+        
+        const data = result.data as { message: string; location: string; files?: string[]; hint?: string };
+        console.log(data.message);
+        console.log(`  Location: ${data.location}`);
+        if (data.files) {
+          console.log(`  Files: ${data.files.join(', ')}`);
+        }
+        if (data.hint) {
+          console.log(`  ${data.hint}`);
+        }
+        break;
+      }
+
+      case 'doctor': {
+        console.log('Cognitive Runtime - Environment Check\n');
+        
+        console.log('Providers:');
+        for (const p of listProviders()) {
+          const status = p.configured ? '✓ configured' : '– not configured';
+          console.log(`  ${p.name}: ${status}`);
+        }
+        console.log('');
+        
+        try {
+          const provider = getProvider();
+          console.log(`Active provider: ${provider.name}`);
+        } catch {
+          console.log('Active provider: none (set an API key)');
+        }
+        break;
+      }
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.error('Run "cog --help" for usage.');
+        process.exit(1);
+    }
+  } catch (e) {
+    console.error(`Error: ${e instanceof Error ? e.message : e}`);
+    if (values.verbose && e instanceof Error) {
+      console.error(e.stack);
+    }
+    process.exit(1);
+  }
+}
+
+function printHelp() {
+  console.log(`
+Cognitive Runtime v${VERSION}
+Structured AI Task Execution
+
+USAGE:
+  cog <command> [options]
+
+COMMANDS:
+  run <module>      Run a Cognitive Module
+  list              List available modules
+  pipe              Pipe mode (stdin/stdout)
+  init [name]       Initialize project or create module
+  doctor            Check configuration
+
+OPTIONS:
+  -a, --args <str>      Arguments to pass to module
+  -i, --input <json>    JSON input for module
+  -m, --module <name>   Module name (for pipe)
+  -p, --provider <name> LLM provider (gemini, openai, anthropic)
+  --pretty              Pretty-print JSON output
+  -V, --verbose         Verbose output
+  --no-validate         Skip schema validation
+  -v, --version         Show version
+  -h, --help            Show this help
+
+EXAMPLES:
+  cog run code-reviewer --args "def foo(): pass"
+  cog list
+  echo "review this code" | cog pipe --module code-reviewer
+  cog init my-module
+  cog doctor
+
+ENVIRONMENT:
+  GEMINI_API_KEY      Google Gemini API key
+  OPENAI_API_KEY      OpenAI API key
+  ANTHROPIC_API_KEY   Anthropic API key
+`);
+}
+
+main().catch(e => {
+  console.error('Fatal error:', e);
+  process.exit(1);
+});

package/src/commands/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Commands - Re-export all commands
+ */
+
+export * from './run.js';
+export * from './list.js';
+export * from './pipe.js';
+export * from './init.js';

package/src/commands/init.ts

@@ -0,0 +1,94 @@
+/**
+ * cog init - Initialize a new Cognitive project
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { CommandContext, CommandResult } from '../types.js';
+
+const EXAMPLE_MODULE_MD = `---
+name: my-module
+version: 1.0.0
+responsibility: Describe what this module does
+excludes:
+  - Do not do X
+  - Do not do Y
+---
+
+Analyze the following input and provide a structured response:
+
+$ARGUMENTS
+
+Return a JSON object with your analysis.
+`;
+
+const EXAMPLE_SCHEMA_JSON = `{
+  "type": "object",
+  "properties": {
+    "result": {
+      "type": "string",
+      "description": "The main result of the analysis"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Confidence score"
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Explanation of the reasoning"
+    }
+  },
+  "required": ["result", "confidence", "rationale"]
+}
+`;
+
+export async function init(ctx: CommandContext, moduleName?: string): Promise<CommandResult> {
+  const cognitiveDir = path.join(ctx.cwd, 'cognitive', 'modules');
+  
+  try {
+    // Create directory structure
+    await fs.mkdir(cognitiveDir, { recursive: true });
+    
+    // If module name provided, create a new module
+    if (moduleName) {
+      const moduleDir = path.join(cognitiveDir, moduleName);
+      await fs.mkdir(moduleDir, { recursive: true });
+      
+      await fs.writeFile(
+        path.join(moduleDir, 'MODULE.md'),
+        EXAMPLE_MODULE_MD.replace('my-module', moduleName)
+      );
+      
+      await fs.writeFile(
+        path.join(moduleDir, 'schema.json'),
+        EXAMPLE_SCHEMA_JSON
+      );
+      
+      return {
+        success: true,
+        data: {
+          message: `Created module: ${moduleName}`,
+          location: moduleDir,
+          files: ['MODULE.md', 'schema.json'],
+        },
+      };
+    }
+    
+    // Just initialize the directory
+    return {
+      success: true,
+      data: {
+        message: 'Cognitive project initialized',
+        location: cognitiveDir,
+        hint: 'Run "cog init <module-name>" to create a new module',
+      },
+    };
+  } catch (e) {
+    return {
+      success: false,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,33 @@
+/**
+ * cog list - List available Cognitive Modules
+ */
+
+import type { CommandContext, CommandResult } from '../types.js';
+import { listModules, getDefaultSearchPaths } from '../modules/index.js';
+
+export async function list(ctx: CommandContext): Promise<CommandResult> {
+  const searchPaths = getDefaultSearchPaths(ctx.cwd);
+  const modules = await listModules(searchPaths);
+
+  if (modules.length === 0) {
+    return {
+      success: true,
+      data: {
+        modules: [],
+        message: `No modules found in: ${searchPaths.join(', ')}`,
+      },
+    };
+  }
+
+  return {
+    success: true,
+    data: {
+      modules: modules.map(m => ({
+        name: m.name,
+        version: m.version,
+        responsibility: m.responsibility,
+        location: m.location,
+      })),
+    },
+  };
+}

package/src/commands/pipe.ts

@@ -0,0 +1,74 @@
+/**
+ * cog pipe - Pipe mode for stdin/stdout integration
+ */
+
+import * as readline from 'node:readline';
+import type { CommandContext, CommandResult } from '../types.js';
+import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+
+export interface PipeOptions {
+  module: string;
+  noValidate?: boolean;
+}
+
+export async function pipe(
+  ctx: CommandContext,
+  options: PipeOptions
+): Promise<CommandResult> {
+  const searchPaths = getDefaultSearchPaths(ctx.cwd);
+  
+  // Find module
+  const module = await findModule(options.module, searchPaths);
+  if (!module) {
+    return {
+      success: false,
+      error: `Module not found: ${options.module}`,
+    };
+  }
+
+  // Read from stdin
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
+
+  const lines: string[] = [];
+  for await (const line of rl) {
+    lines.push(line);
+  }
+  
+  const input = lines.join('\n');
+
+  try {
+    // Check if input is JSON
+    let inputData: Record<string, unknown> | undefined;
+    try {
+      inputData = JSON.parse(input);
+    } catch {
+      // Not JSON, use as args
+    }
+
+    const result = await runModule(module, ctx.provider, {
+      args: inputData ? undefined : input,
+      input: inputData,
+      validateInput: !options.noValidate,
+      validateOutput: !options.noValidate,
+    });
+
+    // Output JSON to stdout
+    console.log(JSON.stringify(result.output));
+
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (e) {
+    const error = e instanceof Error ? e.message : String(e);
+    console.error(JSON.stringify({ error }));
+    return {
+      success: false,
+      error,
+    };
+  }
+}

package/src/commands/run.ts

@@ -0,0 +1,65 @@
+/**
+ * cog run - Run a Cognitive Module
+ */
+
+import type { CommandContext, CommandResult } from '../types.js';
+import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+
+export interface RunOptions {
+  args?: string;
+  input?: string;
+  noValidate?: boolean;
+  pretty?: boolean;
+  verbose?: boolean;
+}
+
+export async function run(
+  moduleName: string,
+  ctx: CommandContext,
+  options: RunOptions = {}
+): 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> | undefined;
+    if (options.input) {
+      try {
+        inputData = JSON.parse(options.input);
+      } catch {
+        return {
+          success: false,
+          error: `Invalid JSON input: ${options.input}`,
+        };
+      }
+    }
+
+    // Run module
+    const result = await runModule(module, ctx.provider, {
+      args: options.args,
+      input: inputData,
+      validateInput: !options.noValidate,
+      validateOutput: !options.noValidate,
+      verbose: options.verbose || ctx.verbose,
+    });
+
+    return {
+      success: true,
+      data: options.pretty ? result : result.output,
+    };
+  } catch (e) {
+    return {
+      success: false,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Cognitive Runtime - Main Entry Point
+ * 
+ * Exports all public APIs for programmatic use.
+ */
+
+// Types
+export type {
+  Provider,
+  InvokeParams,
+  InvokeResult,
+  Message,
+  CognitiveModule,
+  ModuleResult,
+  CommandContext,
+  CommandResult,
+} from './types.js';
+
+// Providers
+export {
+  getProvider,
+  listProviders,
+  GeminiProvider,
+  OpenAIProvider,
+  AnthropicProvider,
+  BaseProvider,
+} from './providers/index.js';
+
+// Modules
+export {
+  loadModule,
+  findModule,
+  listModules,
+  getDefaultSearchPaths,
+  runModule,
+} from './modules/index.js';
+
+// Commands
+export { run, list, pipe } from './commands/index.js';

package/src/modules/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Modules - Re-export all module functionality
+ */
+
+export * from './loader.js';
+export * from './runner.js';

package/src/modules/loader.ts

@@ -0,0 +1,106 @@
+/**
+ * Module Loader - Load and parse Cognitive Modules
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import type { CognitiveModule } from '../types.js';
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
+
+export async function loadModule(modulePath: string): Promise<CognitiveModule> {
+  const moduleFile = path.join(modulePath, 'MODULE.md');
+  const schemaFile = path.join(modulePath, 'schema.json');
+
+  // Read MODULE.md
+  const moduleContent = await fs.readFile(moduleFile, 'utf-8');
+  
+  // Parse frontmatter
+  const match = moduleContent.match(FRONTMATTER_REGEX);
+  if (!match) {
+    throw new Error(`Invalid MODULE.md: missing YAML frontmatter in ${moduleFile}`);
+  }
+
+  const frontmatter = yaml.load(match[1]) as Record<string, unknown>;
+  const prompt = (match[2] || '').trim();
+
+  // Read schema.json
+  let inputSchema: object | undefined;
+  let outputSchema: object | undefined;
+  
+  try {
+    const schemaContent = await fs.readFile(schemaFile, 'utf-8');
+    const schema = JSON.parse(schemaContent);
+    inputSchema = schema.input;
+    outputSchema = schema.output;
+  } catch {
+    // Schema file is optional
+  }
+
+  return {
+    name: frontmatter.name as string || path.basename(modulePath),
+    version: frontmatter.version as string || '1.0.0',
+    responsibility: frontmatter.responsibility as string || '',
+    excludes: (frontmatter.excludes as string[]) || [],
+    context: frontmatter.context as 'fork' | 'main' | undefined,
+    prompt,
+    inputSchema,
+    outputSchema,
+    location: modulePath,
+  };
+}
+
+export async function findModule(name: string, searchPaths: string[]): Promise<CognitiveModule | null> {
+  for (const basePath of searchPaths) {
+    const modulePath = path.join(basePath, name);
+    const moduleFile = path.join(modulePath, 'MODULE.md');
+    
+    try {
+      await fs.access(moduleFile);
+      return await loadModule(modulePath);
+    } catch {
+      // Module not found in this path, continue
+    }
+  }
+  
+  return null;
+}
+
+export async function listModules(searchPaths: string[]): Promise<CognitiveModule[]> {
+  const modules: CognitiveModule[] = [];
+  
+  for (const basePath of searchPaths) {
+    try {
+      const entries = await fs.readdir(basePath, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const modulePath = path.join(basePath, entry.name);
+          const moduleFile = path.join(modulePath, 'MODULE.md');
+          
+          try {
+            await fs.access(moduleFile);
+            const module = await loadModule(modulePath);
+            modules.push(module);
+          } catch {
+            // Not a valid module, skip
+          }
+        }
+      }
+    } catch {
+      // Path doesn't exist, skip
+    }
+  }
+  
+  return modules;
+}
+
+export function getDefaultSearchPaths(cwd: string): string[] {
+  const home = process.env.HOME || '';
+  return [
+    path.join(cwd, 'cognitive', 'modules'),
+    path.join(cwd, '.cognitive', 'modules'),
+    path.join(home, '.cognitive', 'modules'),
+  ];
+}