cognitive-modules 0.6.0

package/dist/commands/update.js

@@ -0,0 +1,105 @@
+/**
+ * Update command - Update installed modules to latest version
+ *
+ * cog update code-simplifier
+ * cog update code-simplifier --tag v2.0.0
+ */
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { add, getInstallInfo } from './add.js';
+const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
+/**
+ * Get module version from installed module
+ */
+async function getInstalledVersion(moduleName) {
+    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);
+        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]);
+                return meta?.version;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Update an installed module
+ */
+export async function update(moduleName, ctx, options = {}) {
+    // 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;
+    const newVersion = data.version;
+    // Determine message
+    let message;
+    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/dist/commands/versions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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;
+}
+/**
+ * List available versions (tags) from GitHub
+ */
+export declare function versions(url: string, ctx: CommandContext, options?: VersionsOptions): Promise<CommandResult>;

package/dist/commands/versions.js

@@ -0,0 +1,60 @@
+/**
+ * Versions command - List available versions from GitHub
+ *
+ * cog versions ziel-io/cognitive-modules
+ */
+/**
+ * Parse GitHub URL or shorthand
+ */
+function parseGitHubUrl(url) {
+    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, ctx, options = {}) {
+    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();
+        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/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Cognitive Runtime - Main Entry Point
+ *
+ * Exports all public APIs for programmatic use.
+ */
+// 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/dist/modules/index.d.ts

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

package/dist/modules/index.js

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

package/dist/modules/loader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Module Loader - Load and parse Cognitive Modules
+ * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
+ */
+import type { CognitiveModule } from '../types.js';
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
+export declare function loadModule(modulePath: string): Promise<CognitiveModule>;
+export declare function findModule(name: string, searchPaths: string[]): Promise<CognitiveModule | null>;
+export declare function listModules(searchPaths: string[]): Promise<CognitiveModule[]>;
+export declare function getDefaultSearchPaths(cwd: string): string[];

package/dist/modules/loader.js

@@ -0,0 +1,197 @@
+/**
+ * Module Loader - Load and parse Cognitive Modules
+ * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
+/**
+ * Detect module format version
+ */
+async function detectFormat(modulePath) {
+    const v2Manifest = path.join(modulePath, 'module.yaml');
+    try {
+        await fs.access(v2Manifest);
+        return 'v2';
+    }
+    catch {
+        return 'v1';
+    }
+}
+/**
+ * Load v2 format module (module.yaml + prompt.md)
+ */
+async function loadModuleV2(modulePath) {
+    const manifestFile = path.join(modulePath, 'module.yaml');
+    const promptFile = path.join(modulePath, 'prompt.md');
+    const schemaFile = path.join(modulePath, 'schema.json');
+    // Read module.yaml
+    const manifestContent = await fs.readFile(manifestFile, 'utf-8');
+    const manifest = yaml.load(manifestContent);
+    // Read prompt.md
+    let prompt = '';
+    try {
+        prompt = await fs.readFile(promptFile, 'utf-8');
+    }
+    catch {
+        // prompt.md is optional, manifest may include inline prompt
+    }
+    // Read schema.json
+    let inputSchema;
+    let outputSchema;
+    let errorSchema;
+    try {
+        const schemaContent = await fs.readFile(schemaFile, 'utf-8');
+        const schema = JSON.parse(schemaContent);
+        inputSchema = schema.input;
+        outputSchema = schema.output;
+        errorSchema = schema.error;
+    }
+    catch {
+        // Schema file is optional but recommended
+    }
+    return {
+        name: manifest.name || path.basename(modulePath),
+        version: manifest.version || '1.0.0',
+        responsibility: manifest.responsibility || '',
+        excludes: manifest.excludes || [],
+        constraints: manifest.constraints,
+        policies: manifest.policies,
+        tools: manifest.tools,
+        output: manifest.output,
+        failure: manifest.failure,
+        runtimeRequirements: manifest.runtime_requirements,
+        context: manifest.context,
+        prompt,
+        inputSchema,
+        outputSchema,
+        errorSchema,
+        location: modulePath,
+        format: 'v2',
+    };
+}
+/**
+ * Load v1 format module (MODULE.md with frontmatter)
+ */
+async function loadModuleV1(modulePath) {
+    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]);
+    const prompt = (match[2] || '').trim();
+    // Read schema.json
+    let inputSchema;
+    let outputSchema;
+    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
+    }
+    // Extract constraints from v1 format
+    const constraints = {};
+    const v1Constraints = frontmatter.constraints;
+    if (v1Constraints) {
+        constraints.no_network = v1Constraints.no_network;
+        constraints.no_side_effects = v1Constraints.no_side_effects;
+        constraints.no_inventing_data = v1Constraints.no_inventing_data;
+    }
+    return {
+        name: frontmatter.name || path.basename(modulePath),
+        version: frontmatter.version || '1.0.0',
+        responsibility: frontmatter.responsibility || '',
+        excludes: frontmatter.excludes || [],
+        constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
+        context: frontmatter.context,
+        prompt,
+        inputSchema,
+        outputSchema,
+        location: modulePath,
+        format: 'v1',
+    };
+}
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
+export async function loadModule(modulePath) {
+    const format = await detectFormat(modulePath);
+    if (format === 'v2') {
+        return loadModuleV2(modulePath);
+    }
+    else {
+        return loadModuleV1(modulePath);
+    }
+}
+/**
+ * Check if a directory contains a valid module
+ */
+async function isValidModule(modulePath) {
+    const v2Manifest = path.join(modulePath, 'module.yaml');
+    const v1Module = path.join(modulePath, 'MODULE.md');
+    try {
+        await fs.access(v2Manifest);
+        return true;
+    }
+    catch {
+        try {
+            await fs.access(v1Module);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export async function findModule(name, searchPaths) {
+    for (const basePath of searchPaths) {
+        const modulePath = path.join(basePath, name);
+        if (await isValidModule(modulePath)) {
+            return await loadModule(modulePath);
+        }
+    }
+    return null;
+}
+export async function listModules(searchPaths) {
+    const modules = [];
+    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);
+                    if (await isValidModule(modulePath)) {
+                        try {
+                            const module = await loadModule(modulePath);
+                            modules.push(module);
+                        }
+                        catch {
+                            // Skip invalid modules
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Path doesn't exist, skip
+        }
+    }
+    return modules;
+}
+export function getDefaultSearchPaths(cwd) {
+    const home = process.env.HOME || '';
+    return [
+        path.join(cwd, 'cognitive', 'modules'),
+        path.join(cwd, '.cognitive', 'modules'),
+        path.join(home, '.cognitive', 'modules'),
+    ];
+}

package/dist/modules/runner.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Module Runner - Execute Cognitive Modules
+ * v2.1: Envelope format support, clean input mapping
+ */
+import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
+export interface RunOptions {
+    input?: ModuleInput;
+    args?: string;
+    verbose?: boolean;
+    useEnvelope?: boolean;
+}
+export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;

package/dist/modules/runner.js

@@ -0,0 +1,229 @@
+/**
+ * Module Runner - Execute Cognitive Modules
+ * v2.1: Envelope format support, clean input mapping
+ */
+export async function runModule(module, provider, options = {}) {
+    const { args, input, verbose = false, useEnvelope } = options;
+    // Determine if we should use envelope format
+    const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
+    // Build clean input data (v2 style: no $ARGUMENTS pollution)
+    const inputData = input || {};
+    // Map legacy --args to clean input
+    if (args && !inputData.code && !inputData.query) {
+        // Determine if args looks like code or natural language
+        if (looksLikeCode(args)) {
+            inputData.code = args;
+        }
+        else {
+            inputData.query = args;
+        }
+    }
+    // Build prompt with clean substitution
+    const prompt = buildPrompt(module, inputData);
+    if (verbose) {
+        console.error('--- Module ---');
+        console.error(`Name: ${module.name} (${module.format})`);
+        console.error(`Responsibility: ${module.responsibility}`);
+        console.error(`Envelope: ${shouldUseEnvelope}`);
+        console.error('--- Input ---');
+        console.error(JSON.stringify(inputData, null, 2));
+        console.error('--- Prompt ---');
+        console.error(prompt);
+        console.error('--- End ---');
+    }
+    // Build system message based on module config
+    const systemParts = [
+        `You are executing the "${module.name}" Cognitive Module.`,
+        '',
+        `RESPONSIBILITY: ${module.responsibility}`,
+    ];
+    if (module.excludes.length > 0) {
+        systemParts.push('', 'YOU MUST NOT:');
+        module.excludes.forEach(e => systemParts.push(`- ${e}`));
+    }
+    if (module.constraints) {
+        systemParts.push('', 'CONSTRAINTS:');
+        if (module.constraints.no_network)
+            systemParts.push('- No network access');
+        if (module.constraints.no_side_effects)
+            systemParts.push('- No side effects');
+        if (module.constraints.no_file_write)
+            systemParts.push('- No file writes');
+        if (module.constraints.no_inventing_data)
+            systemParts.push('- Do not invent data');
+    }
+    if (module.output?.require_behavior_equivalence) {
+        systemParts.push('', 'BEHAVIOR EQUIVALENCE:');
+        systemParts.push('- You MUST set behavior_equivalence=true ONLY if the output is functionally identical');
+        systemParts.push('- If unsure, set behavior_equivalence=false and explain in rationale');
+        const maxConfidence = module.constraints?.behavior_equivalence_false_max_confidence ?? 0.7;
+        systemParts.push(`- If behavior_equivalence=false, confidence MUST be <= ${maxConfidence}`);
+    }
+    // Add envelope format instructions
+    if (shouldUseEnvelope) {
+        systemParts.push('', 'RESPONSE FORMAT (Envelope):');
+        systemParts.push('- Wrap your response in the envelope format');
+        systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
+        systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
+        systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+        if (module.output?.require_behavior_equivalence) {
+            systemParts.push('- Include "behavior_equivalence" (boolean) in data');
+        }
+    }
+    else {
+        systemParts.push('', 'OUTPUT FORMAT:');
+        systemParts.push('- Respond with ONLY valid JSON');
+        systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
+        if (module.output?.require_behavior_equivalence) {
+            systemParts.push('- Include "behavior_equivalence" (boolean) field');
+        }
+    }
+    const messages = [
+        { role: 'system', content: systemParts.join('\n') },
+        { role: 'user', content: prompt },
+    ];
+    // Invoke provider
+    const result = await provider.invoke({
+        messages,
+        jsonSchema: module.outputSchema,
+        temperature: 0.3,
+    });
+    if (verbose) {
+        console.error('--- Response ---');
+        console.error(result.content);
+        console.error('--- End Response ---');
+    }
+    // Parse response
+    let parsed;
+    try {
+        const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+        const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
+        parsed = JSON.parse(jsonStr.trim());
+    }
+    catch {
+        throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
+    }
+    // Handle envelope format
+    if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
+        return parseEnvelopeResponse(parsed, result.content);
+    }
+    // Handle legacy format (non-envelope)
+    return parseLegacyResponse(parsed, result.content);
+}
+/**
+ * Check if response is in envelope format
+ */
+function isEnvelopeResponse(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const o = obj;
+    return typeof o.ok === 'boolean';
+}
+/**
+ * Parse envelope format response
+ */
+function parseEnvelopeResponse(response, raw) {
+    if (response.ok) {
+        const data = response.data;
+        return {
+            ok: true,
+            data: {
+                ...data,
+                confidence: typeof data.confidence === 'number' ? data.confidence : 0.5,
+                rationale: typeof data.rationale === 'string' ? data.rationale : '',
+                behavior_equivalence: data.behavior_equivalence,
+            },
+            raw,
+        };
+    }
+    else {
+        return {
+            ok: false,
+            error: response.error,
+            partial_data: response.partial_data,
+            raw,
+        };
+    }
+}
+/**
+ * Parse legacy (non-envelope) format response
+ */
+function parseLegacyResponse(output, raw) {
+    const outputObj = output;
+    const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
+    const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
+    const behaviorEquivalence = typeof outputObj.behavior_equivalence === 'boolean'
+        ? outputObj.behavior_equivalence
+        : undefined;
+    // Check if this is an error response (has error.code)
+    if (outputObj.error && typeof outputObj.error === 'object') {
+        const errorObj = outputObj.error;
+        if (typeof errorObj.code === 'string') {
+            return {
+                ok: false,
+                error: {
+                    code: errorObj.code,
+                    message: typeof errorObj.message === 'string' ? errorObj.message : 'Unknown error',
+                },
+                raw,
+            };
+        }
+    }
+    return {
+        ok: true,
+        data: {
+            ...outputObj,
+            confidence,
+            rationale,
+            behavior_equivalence: behaviorEquivalence,
+        },
+        raw,
+    };
+}
+/**
+ * Build prompt with clean variable substitution
+ */
+function buildPrompt(module, input) {
+    let prompt = module.prompt;
+    // v2 style: substitute ${variable} placeholders
+    for (const [key, value] of Object.entries(input)) {
+        const strValue = typeof value === 'string' ? value : JSON.stringify(value);
+        prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), strValue);
+    }
+    // v1 compatibility: substitute $ARGUMENTS
+    const argsValue = input.code || input.query || '';
+    prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
+    // Substitute $N placeholders (v1 compatibility)
+    if (typeof argsValue === 'string') {
+        const argsList = argsValue.split(/\s+/);
+        argsList.forEach((arg, i) => {
+            prompt = prompt.replace(new RegExp(`\\$${i}\\b`, 'g'), arg);
+        });
+    }
+    // Append input summary if not already in prompt
+    if (!prompt.includes(argsValue) && argsValue) {
+        prompt += '\n\n## Input\n\n';
+        if (input.code) {
+            prompt += '```\n' + input.code + '\n```\n';
+        }
+        if (input.query) {
+            prompt += input.query + '\n';
+        }
+        if (input.language) {
+            prompt += `\nLanguage: ${input.language}\n`;
+        }
+    }
+    return prompt;
+}
+/**
+ * Heuristic to detect if input looks like code
+ */
+function looksLikeCode(str) {
+    const codeIndicators = [
+        /^(def|function|class|const|let|var|import|export|public|private)\s/,
+        /[{};()]/,
+        /=>/,
+        /\.(py|js|ts|go|rs|java|cpp|c|rb)$/,
+    ];
+    return codeIndicators.some(re => re.test(str));
+}

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Anthropic Provider - Claude API
+ */
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+export declare class AnthropicProvider extends BaseProvider {
+    name: string;
+    private apiKey;
+    private model;
+    private baseUrl;
+    constructor(apiKey?: string, model?: string);
+    isConfigured(): boolean;
+    invoke(params: InvokeParams): Promise<InvokeResult>;
+}