cognitive-modules 0.6.0

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,76 @@
+/**
+ * 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,
+    });
+
+    // Output envelope format to stdout
+    console.log(JSON.stringify(result));
+
+    return {
+      success: result.ok,
+      data: result,
+    };
+  } 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 }
+    }));
+    return {
+      success: false,
+      error,
+    };
+  }
+}

package/src/commands/remove.ts

@@ -0,0 +1,57 @@
+/**
+ * Remove command - Remove installed modules
+ * 
+ * cog remove code-simplifier
+ */
+
+import { existsSync, rmSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { CommandContext, CommandResult } from '../types.js';
+
+const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
+const INSTALLED_MANIFEST = join(homedir(), '.cognitive', 'installed.json');
+
+/**
+ * Remove an installed module
+ */
+export async function remove(
+  moduleName: string,
+  ctx: CommandContext
+): Promise<CommandResult> {
+  const modulePath = join(USER_MODULES_DIR, moduleName);
+  
+  if (!existsSync(modulePath)) {
+    return {
+      success: false,
+      error: `Module not found in global location: ${moduleName}. Only modules in ~/.cognitive/modules can be removed.`,
+    };
+  }
+  
+  try {
+    // Remove module directory
+    rmSync(modulePath, { recursive: true, force: true });
+    
+    // Remove from manifest
+    if (existsSync(INSTALLED_MANIFEST)) {
+      const content = await readFile(INSTALLED_MANIFEST, 'utf-8');
+      const manifest = JSON.parse(content);
+      delete manifest[moduleName];
+      await writeFile(INSTALLED_MANIFEST, JSON.stringify(manifest, null, 2));
+    }
+    
+    return {
+      success: true,
+      data: {
+        message: `Removed: ${moduleName}`,
+        name: moduleName,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/commands/run.ts

@@ -0,0 +1,80 @@
+/**
+ * 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,
+      verbose: options.verbose || ctx.verbose,
+    });
+
+    // Return envelope format or extracted data
+    if (options.pretty) {
+      return {
+        success: result.ok,
+        data: result,
+      };
+    } 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,
+        };
+      }
+    }
+  } catch (e) {
+    return {
+      success: false,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}

package/src/commands/update.ts

@@ -0,0 +1,130 @@
+/**
+ * Update command - Update installed modules to latest version
+ * 
+ * cog update code-simplifier
+ * cog update code-simplifier --tag v2.0.0
+ */
+
+import { existsSync, rmSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { CommandContext, CommandResult } from '../types.js';
+import { add, getInstallInfo } from './add.js';
+
+const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
+
+export interface UpdateOptions {
+  tag?: string;
+}
+
+/**
+ * Get module version from installed module
+ */
+async function getInstalledVersion(moduleName: string): Promise<string | undefined> {
+  const modulePath = join(USER_MODULES_DIR, moduleName);
+  
+  if (!existsSync(modulePath)) {
+    return 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;
+}
+
+/**
+ * Update an installed module
+ */
+export async function update(
+  moduleName: string,
+  ctx: CommandContext,
+  options: UpdateOptions = {}
+): Promise<CommandResult> {
+  // Get installation info
+  const info = await getInstallInfo(moduleName);
+  
+  if (!info) {
+    return {
+      success: false,
+      error: `Module not found or not installed from GitHub: ${moduleName}. Only modules installed with 'cog add' can be updated.`,
+    };
+  }
+  
+  if (!info.githubUrl) {
+    return {
+      success: false,
+      error: `Module was not installed from GitHub: ${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,
+    tag,
+    branch: tag ? undefined : branch,
+  });
+  
+  if (!result.success) {
+    return result;
+  }
+  
+  const data = result.data as { version?: string };
+  const newVersion = data.version;
+  
+  // Determine message
+  let message: string;
+  if (oldVersion && newVersion) {
+    if (oldVersion === newVersion) {
+      message = `Already up to date: ${moduleName} v${newVersion}`;
+    } else {
+      message = `Updated: ${moduleName} v${oldVersion} → v${newVersion}`;
+    }
+  } else if (newVersion) {
+    message = `Updated: ${moduleName} to v${newVersion}`;
+  } else {
+    message = `Updated: ${moduleName}`;
+  }
+  
+  return {
+    success: true,
+    data: {
+      message,
+      name: moduleName,
+      oldVersion,
+      newVersion,
+    },
+  };
+}

package/src/commands/versions.ts

@@ -0,0 +1,79 @@
+/**
+ * Versions command - List available versions from GitHub
+ * 
+ * cog versions ziel-io/cognitive-modules
+ */
+
+import type { CommandContext, CommandResult } from '../types.js';
+
+export interface VersionsOptions {
+  limit?: number;
+}
+
+/**
+ * Parse GitHub URL or shorthand
+ */
+function parseGitHubUrl(url: string): { org: string; repo: string } {
+  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}`);
+  }
+  
+  return {
+    org: match[1],
+    repo: match[2].replace(/\.git$/, ''),
+  };
+}
+
+/**
+ * List available versions (tags) from GitHub
+ */
+export async function versions(
+  url: string,
+  ctx: CommandContext,
+  options: VersionsOptions = {}
+): Promise<CommandResult> {
+  const { limit = 10 } = options;
+  
+  try {
+    const { org, repo } = parseGitHubUrl(url);
+    
+    // Fetch tags from GitHub API
+    const apiUrl = `https://api.github.com/repos/${org}/${repo}/tags?per_page=${limit}`;
+    
+    const response = await fetch(apiUrl, {
+      headers: {
+        'User-Agent': 'cognitive-runtime/1.0',
+        'Accept': 'application/vnd.github.v3+json',
+      },
+    });
+    
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new Error(`Repository not found: ${org}/${repo}`);
+      }
+      throw new Error(`GitHub API error: ${response.status}`);
+    }
+    
+    const data = await response.json() as Array<{ name: string }>;
+    const tags = data.map(t => t.name);
+    
+    return {
+      success: true,
+      data: {
+        repository: `${org}/${repo}`,
+        tags,
+        count: tags.length,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Cognitive Runtime - Main Entry Point
+ * 
+ * Exports all public APIs for programmatic use.
+ */
+
+// Types
+export type {
+  Provider,
+  InvokeParams,
+  InvokeResult,
+  Message,
+  CognitiveModule,
+  ModuleResult,
+  ModuleInput,
+  ModuleConstraints,
+  ToolsPolicy,
+  OutputContract,
+  FailureContract,
+  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';