cognitive-modules 0.6.0

package/src/cli.ts

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+/**
+ * Cognitive Modules CLI
+ * 
+ * cog run <module> --args "..."     - Run a module
+ * cog add <url> -m <name>           - Add module from GitHub
+ * cog update <module>               - Update to latest version
+ * cog remove <module>               - Remove installed module
+ * cog versions <url>                - List available versions
+ * cog list                          - List available modules
+ * cog pipe --module <name>          - Pipe mode (stdin/stdout)
+ * cog doctor                        - Check configuration
+ * 
+ * npx cognitive-modules add ziel-io/cognitive-modules -m code-simplifier
+ */
+
+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 type { CommandContext } from './types.js';
+
+const VERSION = '0.6.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' },
+      model: { 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 },
+      // Add/update options
+      name: { type: 'string', short: 'n' },
+      tag: { type: 'string', short: 't' },
+      branch: { type: 'string', short: 'b' },
+      limit: { type: 'string', short: 'l' },
+    },
+    allowPositionals: true,
+  });
+
+  // Get provider
+  let provider;
+  try {
+    provider = getProvider(values.provider, values.model);
+  } 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} (${p.model})`);
+        }
+        console.log('');
+        
+        try {
+          const provider = getProvider();
+          console.log(`Active provider: ${provider.name}`);
+        } catch {
+          console.log('Active provider: none (set an API key)');
+        }
+        break;
+      }
+
+      case 'add': {
+        const url = args[1];
+        if (!url || url.startsWith('-')) {
+          console.error('Usage: cog add <url> [--module <name>] [--tag <version>]');
+          console.error('');
+          console.error('Examples:');
+          console.error('  cog add ziel-io/cognitive-modules -m code-simplifier');
+          console.error('  cog add org/repo --module my-module --tag v1.0.0');
+          process.exit(1);
+        }
+        
+        console.log(`→ Adding module from: ${url}`);
+        if (values.module) console.log(`  Module path: ${values.module}`);
+        if (values.tag) console.log(`  Version: ${values.tag}`);
+        
+        const result = await add(url, ctx, {
+          module: values.module,
+          name: values.name,
+          tag: values.tag,
+          branch: values.branch,
+        });
+        
+        if (!result.success) {
+          console.error(`✗ Failed to add module: ${result.error}`);
+          process.exit(1);
+        }
+        
+        const data = result.data as { message: string; location: string; name: string };
+        console.log(`✓ ${data.message}`);
+        console.log(`  Location: ${data.location}`);
+        console.log('');
+        console.log('Run with:');
+        console.log(`  cog run ${data.name} --args "your input"`);
+        break;
+      }
+
+      case 'update': {
+        const moduleName = args[1];
+        if (!moduleName || moduleName.startsWith('-')) {
+          console.error('Usage: cog update <module> [--tag <version>]');
+          process.exit(1);
+        }
+        
+        console.log(`→ Updating module: ${moduleName}`);
+        
+        const result = await update(moduleName, ctx, {
+          tag: values.tag,
+        });
+        
+        if (!result.success) {
+          console.error(`✗ ${result.error}`);
+          process.exit(1);
+        }
+        
+        const data = result.data as { message: string };
+        console.log(`✓ ${data.message}`);
+        break;
+      }
+
+      case 'remove': {
+        const moduleName = args[1];
+        if (!moduleName || moduleName.startsWith('-')) {
+          console.error('Usage: cog remove <module>');
+          process.exit(1);
+        }
+        
+        const result = await remove(moduleName, ctx);
+        
+        if (!result.success) {
+          console.error(`✗ ${result.error}`);
+          process.exit(1);
+        }
+        
+        const data = result.data as { message: string };
+        console.log(`✓ ${data.message}`);
+        break;
+      }
+
+      case 'versions': {
+        const url = args[1];
+        if (!url || url.startsWith('-')) {
+          console.error('Usage: cog versions <url>');
+          console.error('');
+          console.error('Examples:');
+          console.error('  cog versions ziel-io/cognitive-modules');
+          process.exit(1);
+        }
+        
+        console.log(`→ Fetching versions from: ${url}\n`);
+        
+        const limit = values.limit ? parseInt(values.limit, 10) : 10;
+        const result = await versions(url, ctx, { limit });
+        
+        if (!result.success) {
+          console.error(`✗ ${result.error}`);
+          process.exit(1);
+        }
+        
+        const data = result.data as { tags: string[]; count: number };
+        
+        if (data.tags.length === 0) {
+          console.log('No tags/versions found.');
+        } else {
+          console.log(`Available Versions (${data.count}):`);
+          console.log('');
+          for (const tag of data.tags) {
+            console.log(`  ${tag}`);
+            console.log(`    cog add ${url} --tag ${tag}`);
+          }
+        }
+        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
+  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
+  doctor            Check configuration
+
+OPTIONS:
+  -a, --args <str>      Arguments to pass to module
+  -i, --input <json>    JSON input for module
+  -m, --module <name>   Module path within repo (for add)
+  -n, --name <name>     Override module name (for add)
+  -t, --tag <version>   Git tag/version (for add/update)
+  -b, --branch <name>   Git branch (for add)
+  -M, --model <name>    LLM model (e.g., gpt-4o, gemini-2.0-flash)
+  -p, --provider <name> LLM provider (gemini, openai, anthropic, deepseek, minimax, moonshot, qwen, ollama)
+  --pretty              Pretty-print JSON output
+  -V, --verbose         Verbose output
+  --no-validate         Skip schema validation
+  -v, --version         Show version
+  -h, --help            Show this help
+
+EXAMPLES:
+  # Add modules from GitHub
+  cog add ziel-io/cognitive-modules -m code-simplifier
+  cog add org/repo --module my-module --tag v1.0.0
+
+  # Version management
+  cog update code-simplifier
+  cog versions ziel-io/cognitive-modules
+  cog remove code-simplifier
+
+  # Run modules
+  cog run code-reviewer --args "def foo(): pass"
+  cog run code-reviewer --provider openai --model gpt-4o --args "..."
+  cog list
+
+  # Other
+  echo "review this code" | cog pipe --module code-reviewer
+  cog init my-module
+  cog doctor
+
+ENVIRONMENT:
+  GEMINI_API_KEY      Google Gemini
+  OPENAI_API_KEY      OpenAI
+  ANTHROPIC_API_KEY   Anthropic Claude
+  DEEPSEEK_API_KEY    DeepSeek
+  MINIMAX_API_KEY     MiniMax
+  MOONSHOT_API_KEY    Moonshot (Kimi)
+  DASHSCOPE_API_KEY   Alibaba Qwen (通义千问)
+  OLLAMA_HOST         Ollama local (default: localhost:11434)
+  COG_MODEL           Override default model for any provider
+`);
+}
+
+main().catch(e => {
+  console.error('Fatal error:', e);
+  process.exit(1);
+});

package/src/commands/add.ts

@@ -0,0 +1,315 @@
+/**
+ * Add command - Install modules from GitHub
+ * 
+ * cog add ziel-io/cognitive-modules -m code-simplifier
+ * cog add https://github.com/org/repo --module name --tag v1.0.0
+ */
+
+import { createWriteStream, existsSync, mkdirSync, rmSync, readdirSync, statSync, copyFileSync } from 'node:fs';
+import { writeFile, readFile, mkdir, rm } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { join, basename } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { createGunzip } from 'node:zlib';
+import type { CommandContext, CommandResult } from '../types.js';
+
+// Module storage paths
+const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
+const INSTALLED_MANIFEST = join(homedir(), '.cognitive', 'installed.json');
+
+export interface AddOptions {
+  module?: string;
+  name?: string;
+  branch?: string;
+  tag?: string;
+}
+
+interface InstallManifest {
+  [moduleName: string]: {
+    source: string;
+    githubUrl: string;
+    modulePath?: string;
+    tag?: string;
+    branch?: string;
+    version?: string;
+    installedAt: string;
+    installedTime: string;
+  };
+}
+
+/**
+ * Parse GitHub URL or shorthand
+ */
+function parseGitHubUrl(url: string): { org: string; repo: string; fullUrl: string } {
+  // Handle shorthand: org/repo
+  if (!url.startsWith('http')) {
+    url = `https://github.com/${url}`;
+  }
+  
+  const match = url.match(/https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/?/);
+  if (!match) {
+    throw new Error(`Invalid GitHub URL: ${url}`);
+  }
+  
+  const org = match[1];
+  const repo = match[2].replace(/\.git$/, '');
+  
+  return {
+    org,
+    repo,
+    fullUrl: `https://github.com/${org}/${repo}`,
+  };
+}
+
+/**
+ * Download and extract ZIP from GitHub
+ */
+async function downloadAndExtract(
+  org: string,
+  repo: string,
+  ref: string,
+  isTag: boolean
+): Promise<string> {
+  const zipUrl = isTag
+    ? `https://github.com/${org}/${repo}/archive/refs/tags/${ref}.zip`
+    : `https://github.com/${org}/${repo}/archive/refs/heads/${ref}.zip`;
+  
+  // Create temp directory
+  const tempDir = join(tmpdir(), `cog-${Date.now()}`);
+  mkdirSync(tempDir, { recursive: true });
+  
+  const zipPath = join(tempDir, 'repo.zip');
+  
+  // Download ZIP
+  const response = await fetch(zipUrl, {
+    headers: { 'User-Agent': 'cognitive-runtime/1.0' },
+  });
+  
+  if (!response.ok) {
+    throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+  }
+  
+  // Save to file
+  const fileStream = createWriteStream(zipPath);
+  await pipeline(Readable.fromWeb(response.body as any), fileStream);
+  
+  // Extract using built-in unzip (available on most systems)
+  const { execSync } = await import('node:child_process');
+  execSync(`unzip -q "${zipPath}" -d "${tempDir}"`, { stdio: 'pipe' });
+  
+  // Find extracted directory
+  const entries = readdirSync(tempDir).filter(
+    e => e !== 'repo.zip' && statSync(join(tempDir, e)).isDirectory()
+  );
+  
+  if (entries.length === 0) {
+    throw new Error('ZIP file was empty');
+  }
+  
+  return join(tempDir, entries[0]);
+}
+
+/**
+ * Check if a directory is a valid module
+ */
+function isValidModule(path: string): boolean {
+  return (
+    existsSync(join(path, 'module.yaml')) ||
+    existsSync(join(path, 'MODULE.md')) ||
+    existsSync(join(path, 'module.md'))
+  );
+}
+
+/**
+ * Find module within repository
+ */
+function findModuleInRepo(repoRoot: string, modulePath: string): string {
+  const possiblePaths = [
+    join(repoRoot, modulePath),
+    join(repoRoot, 'cognitive', 'modules', modulePath),
+    join(repoRoot, 'modules', modulePath),
+  ];
+  
+  for (const p of possiblePaths) {
+    if (existsSync(p) && isValidModule(p)) {
+      return p;
+    }
+  }
+  
+  throw new Error(
+    `Module not found at: ${modulePath}\n` +
+    `Searched in: ${possiblePaths.map(p => p.replace(repoRoot, '.')).join(', ')}`
+  );
+}
+
+/**
+ * Copy directory recursively
+ */
+function copyDir(src: string, dest: string): void {
+  mkdirSync(dest, { recursive: true });
+  
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    
+    if (statSync(srcPath).isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Get module version from module.yaml or MODULE.md
+ */
+async function getModuleVersion(modulePath: string): Promise<string | undefined> {
+  const yaml = await import('js-yaml');
+  
+  // Try v2 format
+  const yamlPath = join(modulePath, 'module.yaml');
+  if (existsSync(yamlPath)) {
+    const content = await readFile(yamlPath, 'utf-8');
+    const data = yaml.load(content) as { version?: string };
+    return data?.version;
+  }
+  
+  // Try v1 format
+  const mdPath = existsSync(join(modulePath, 'MODULE.md'))
+    ? join(modulePath, 'MODULE.md')
+    : join(modulePath, 'module.md');
+  
+  if (existsSync(mdPath)) {
+    const content = await readFile(mdPath, 'utf-8');
+    if (content.startsWith('---')) {
+      const parts = content.split('---');
+      if (parts.length >= 3) {
+        const meta = yaml.load(parts[1]) as { version?: string };
+        return meta?.version;
+      }
+    }
+  }
+  
+  return undefined;
+}
+
+/**
+ * Record installation info
+ */
+async function recordInstall(
+  moduleName: string,
+  info: InstallManifest[string]
+): Promise<void> {
+  let manifest: InstallManifest = {};
+  
+  if (existsSync(INSTALLED_MANIFEST)) {
+    const content = await readFile(INSTALLED_MANIFEST, 'utf-8');
+    manifest = JSON.parse(content);
+  }
+  
+  manifest[moduleName] = info;
+  
+  await mkdir(join(homedir(), '.cognitive'), { recursive: true });
+  await writeFile(INSTALLED_MANIFEST, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Get installation info for a module
+ */
+export async function getInstallInfo(moduleName: string): Promise<InstallManifest[string] | null> {
+  if (!existsSync(INSTALLED_MANIFEST)) {
+    return null;
+  }
+  
+  const content = await readFile(INSTALLED_MANIFEST, 'utf-8');
+  const manifest: InstallManifest = JSON.parse(content);
+  return manifest[moduleName] || null;
+}
+
+/**
+ * Add a module from GitHub
+ */
+export async function add(
+  url: string,
+  ctx: CommandContext,
+  options: AddOptions = {}
+): Promise<CommandResult> {
+  const { org, repo, fullUrl } = parseGitHubUrl(url);
+  const { module: modulePath, name, branch = 'main', tag } = options;
+  
+  // Determine ref (tag takes priority)
+  const ref = tag || branch;
+  const isTag = !!tag;
+  
+  let repoRoot: string;
+  let sourcePath: string;
+  let moduleName: string;
+  
+  try {
+    // Download repository
+    repoRoot = await downloadAndExtract(org, repo, ref, isTag);
+    
+    // Find module
+    if (modulePath) {
+      sourcePath = findModuleInRepo(repoRoot, modulePath);
+    } else {
+      // Use repo root as module
+      if (!isValidModule(repoRoot)) {
+        throw new Error(
+          'Repository root is not a valid module. Use --module to specify the module path.'
+        );
+      }
+      sourcePath = repoRoot;
+    }
+    
+    // Determine module name
+    moduleName = name || basename(sourcePath);
+    
+    // Get version
+    const version = await getModuleVersion(sourcePath);
+    
+    // Install to user modules dir
+    const targetPath = join(USER_MODULES_DIR, moduleName);
+    
+    // Remove existing
+    if (existsSync(targetPath)) {
+      rmSync(targetPath, { recursive: true, force: true });
+    }
+    
+    // Copy module
+    await mkdir(USER_MODULES_DIR, { recursive: true });
+    copyDir(sourcePath, targetPath);
+    
+    // Record installation info
+    await recordInstall(moduleName, {
+      source: sourcePath,
+      githubUrl: fullUrl,
+      modulePath,
+      tag,
+      branch,
+      version,
+      installedAt: targetPath,
+      installedTime: new Date().toISOString(),
+    });
+    
+    // Cleanup temp directory
+    const tempDir = repoRoot.split('/').slice(0, -1).join('/');
+    rmSync(tempDir, { recursive: true, force: true });
+    
+    return {
+      success: true,
+      data: {
+        message: `Added: ${moduleName}${version ? ` v${version}` : ''}`,
+        name: moduleName,
+        version,
+        location: targetPath,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Commands - Re-export all commands
+ */
+
+export * from './run.js';
+export * from './list.js';
+export * from './pipe.js';
+export * from './init.js';
+export * from './add.js';
+export * from './update.js';
+export * from './remove.js';
+export * from './versions.js';