cognitive-modules-cli 2.2.1 → 2.2.5

package/dist/registry/client.js

@@ -0,0 +1,356 @@
+/**
+ * Registry Client - Fetch and manage modules from Cognitive Modules Registry
+ *
+ * Supports both v1 and v2 registry formats.
+ *
+ * Usage:
+ *   const client = new RegistryClient();
+ *   const modules = await client.listModules();
+ *   const module = await client.getModule('code-reviewer');
+ */
+import { existsSync, statSync } from 'node:fs';
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_REGISTRY_URL = 'https://raw.githubusercontent.com/ziel-io/cognitive-modules/main/cognitive-registry.json';
+const CACHE_DIR = join(homedir(), '.cognitive', 'cache');
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const REGISTRY_FETCH_TIMEOUT_MS = 10_000; // 10s
+const MAX_REGISTRY_BYTES = 1024 * 1024; // 1MB
+// =============================================================================
+// Registry Client
+// =============================================================================
+export class RegistryClient {
+    registryUrl;
+    cache = { data: null, timestamp: 0 };
+    constructor(registryUrl = DEFAULT_REGISTRY_URL) {
+        this.registryUrl = registryUrl;
+    }
+    async parseRegistryResponse(response) {
+        const contentLengthHeader = response.headers?.get('content-length');
+        if (contentLengthHeader) {
+            const contentLength = Number(contentLengthHeader);
+            if (!Number.isNaN(contentLength) && contentLength > MAX_REGISTRY_BYTES) {
+                throw new Error(`Registry payload too large: ${contentLength} bytes (max ${MAX_REGISTRY_BYTES})`);
+            }
+        }
+        if (response.body && typeof response.body.getReader === 'function') {
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder('utf-8');
+            let buffer = '';
+            let totalBytes = 0;
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value) {
+                        totalBytes += value.byteLength;
+                        if (totalBytes > MAX_REGISTRY_BYTES) {
+                            throw new Error(`Registry payload too large: ${totalBytes} bytes (max ${MAX_REGISTRY_BYTES})`);
+                        }
+                        buffer += decoder.decode(value, { stream: true });
+                    }
+                }
+                buffer += decoder.decode();
+            }
+            finally {
+                reader.releaseLock();
+            }
+            try {
+                return JSON.parse(buffer);
+            }
+            catch (error) {
+                throw new Error(`Invalid registry JSON: ${error.message}`);
+            }
+        }
+        if (typeof response.text === 'function') {
+            const text = await response.text();
+            const byteLen = Buffer.byteLength(text, 'utf-8');
+            if (byteLen > MAX_REGISTRY_BYTES) {
+                throw new Error(`Registry payload too large: ${byteLen} bytes (max ${MAX_REGISTRY_BYTES})`);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new Error(`Invalid registry JSON: ${error.message}`);
+            }
+        }
+        if (typeof response.json === 'function') {
+            return await response.json();
+        }
+        throw new Error('Failed to read registry response body');
+    }
+    /**
+     * Generate a unique cache filename based on registry URL
+     */
+    getCacheFileName() {
+        const hash = createHash('md5').update(this.registryUrl).digest('hex').slice(0, 8);
+        return `registry-${hash}.json`;
+    }
+    /**
+     * Fetch registry index (with caching)
+     */
+    async fetchRegistry(forceRefresh = false) {
+        const now = Date.now();
+        // Check memory cache
+        if (!forceRefresh && this.cache.data && (now - this.cache.timestamp) < CACHE_TTL_MS) {
+            return this.cache.data;
+        }
+        // Check file cache (unique per registry URL)
+        const cacheFile = join(CACHE_DIR, this.getCacheFileName());
+        if (!forceRefresh && existsSync(cacheFile)) {
+            try {
+                const stat = statSync(cacheFile);
+                if ((now - stat.mtimeMs) < CACHE_TTL_MS) {
+                    const content = await readFile(cacheFile, 'utf-8');
+                    const data = JSON.parse(content);
+                    this.cache = { data, timestamp: now };
+                    return data;
+                }
+            }
+            catch {
+                // Ignore cache read errors
+            }
+        }
+        // Fetch from network
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), REGISTRY_FETCH_TIMEOUT_MS);
+        let data;
+        try {
+            const response = await fetch(this.registryUrl, {
+                headers: { 'User-Agent': 'cognitive-runtime/2.2' },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch registry: ${response.status} ${response.statusText}`);
+            }
+            data = await this.parseRegistryResponse(response);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`Registry fetch timed out after ${REGISTRY_FETCH_TIMEOUT_MS}ms`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        // Update cache
+        this.cache = { data, timestamp: now };
+        // Save to file cache
+        try {
+            await mkdir(CACHE_DIR, { recursive: true });
+            await writeFile(cacheFile, JSON.stringify(data, null, 2));
+        }
+        catch {
+            // Ignore cache write errors
+        }
+        return data;
+    }
+    /**
+     * Check if registry is v2 format
+     */
+    isV2Registry(registry) {
+        const firstModule = Object.values(registry.modules)[0];
+        return firstModule && 'identity' in firstModule;
+    }
+    /**
+     * Normalize module entry to unified format
+     */
+    normalizeModule(name, entry) {
+        if ('identity' in entry) {
+            // v2 format
+            const v2 = entry;
+            return {
+                name: v2.identity.name,
+                version: v2.identity.version,
+                description: v2.metadata.description,
+                author: v2.metadata.author,
+                source: v2.distribution.source || v2.distribution.tarball || '',
+                keywords: v2.metadata.keywords || [],
+                tier: v2.metadata.tier,
+                namespace: v2.identity.namespace,
+                license: v2.metadata.license,
+                repository: v2.metadata.repository,
+                conformance_level: v2.quality?.conformance_level,
+                verified: v2.quality?.verified,
+                deprecated: v2.quality?.deprecated,
+            };
+        }
+        else {
+            // v1 format
+            const v1 = entry;
+            return {
+                name,
+                version: v1.version,
+                description: v1.description,
+                author: v1.author,
+                source: v1.source,
+                keywords: v1.tags || [],
+            };
+        }
+    }
+    /**
+     * List all modules in registry
+     */
+    async listModules() {
+        const registry = await this.fetchRegistry();
+        return Object.entries(registry.modules).map(([name, entry]) => this.normalizeModule(name, entry));
+    }
+    /**
+     * Get a specific module by name
+     */
+    async getModule(name) {
+        const registry = await this.fetchRegistry();
+        const entry = registry.modules[name];
+        if (!entry) {
+            return null;
+        }
+        return this.normalizeModule(name, entry);
+    }
+    /**
+     * Search modules by query
+     */
+    async search(query) {
+        const modules = await this.listModules();
+        // If query is empty, return all modules sorted by name
+        if (!query.trim()) {
+            return modules
+                .map(m => ({
+                name: m.name,
+                description: m.description,
+                version: m.version,
+                score: 1,
+                keywords: m.keywords,
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+        }
+        const queryLower = query.toLowerCase().trim();
+        const queryTerms = queryLower.split(/\s+/).filter(t => t.length > 0);
+        const results = [];
+        for (const module of modules) {
+            let score = 0;
+            // Name match (highest weight)
+            if (module.name.toLowerCase().includes(queryLower)) {
+                score += 10;
+                if (module.name.toLowerCase() === queryLower) {
+                    score += 5;
+                }
+            }
+            // Description match
+            const descLower = module.description.toLowerCase();
+            for (const term of queryTerms) {
+                if (descLower.includes(term)) {
+                    score += 3;
+                }
+            }
+            // Keyword match
+            for (const keyword of module.keywords) {
+                const keywordLower = keyword.toLowerCase();
+                for (const term of queryTerms) {
+                    if (keywordLower.includes(term) || term.includes(keywordLower)) {
+                        score += 2;
+                    }
+                }
+            }
+            if (score > 0) {
+                results.push({
+                    name: module.name,
+                    description: module.description,
+                    version: module.version,
+                    score,
+                    keywords: module.keywords,
+                });
+            }
+        }
+        // Sort by score descending
+        results.sort((a, b) => b.score - a.score);
+        return results;
+    }
+    /**
+     * Get categories
+     */
+    async getCategories() {
+        const registry = await this.fetchRegistry();
+        return registry.categories || {};
+    }
+    /**
+     * Parse GitHub source string
+     * Format: github:<owner>/<repo>[/<path>][@<ref>]
+     */
+    parseGitHubSource(source) {
+        if (!source.startsWith('github:')) {
+            return null;
+        }
+        const rest = source.slice('github:'.length);
+        // Split ref if present
+        const [pathPart, ref] = rest.split('@');
+        // Parse owner/repo/path
+        const parts = pathPart.split('/');
+        if (parts.length < 2) {
+            return null;
+        }
+        const org = parts[0];
+        const repo = parts[1];
+        const modulePath = parts.length > 2 ? parts.slice(2).join('/') : undefined;
+        return { org, repo, path: modulePath, ref };
+    }
+    /**
+     * Verify checksum of downloaded file
+     */
+    async verifyChecksum(filePath, expected) {
+        const [algo, expectedHash] = expected.split(':');
+        if (!algo || !expectedHash) {
+            throw new Error(`Invalid checksum format: ${expected}`);
+        }
+        const content = await readFile(filePath);
+        const actualHash = createHash(algo).update(content).digest('hex');
+        return actualHash === expectedHash;
+    }
+    /**
+     * Get the download URL for a module
+     */
+    async getDownloadUrl(moduleName) {
+        const module = await this.getModule(moduleName);
+        if (!module) {
+            throw new Error(`Module not found in registry: ${moduleName}`);
+        }
+        const source = module.source;
+        // Check if it's a GitHub source
+        const githubInfo = this.parseGitHubSource(source);
+        if (githubInfo) {
+            return {
+                url: `https://github.com/${githubInfo.org}/${githubInfo.repo}`,
+                isGitHub: true,
+                githubInfo,
+            };
+        }
+        // Check if it's a tarball URL
+        if (source.startsWith('http://') || source.startsWith('https://')) {
+            return {
+                url: source,
+                isGitHub: false,
+            };
+        }
+        throw new Error(`Unknown source format: ${source}`);
+    }
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export const defaultRegistry = new RegistryClient();
+export async function listRegistryModules() {
+    return defaultRegistry.listModules();
+}
+export async function getRegistryModule(name) {
+    return defaultRegistry.getModule(name);
+}
+export async function searchRegistry(query) {
+    return defaultRegistry.search(query);
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Registry Module - Re-export all registry functionality
+ */
+export * from './client.js';

package/dist/registry/index.js

@@ -0,0 +1,4 @@
+/**
+ * Registry Module - Re-export all registry functionality
+ */
+export * from './client.js';

package/dist/server/http.js

@@ -15,22 +15,62 @@ import { URL } from 'node:url';
 import { findModule, listModules, getDefaultSearchPaths } from '../modules/loader.js';
 import { runModule } from '../modules/runner.js';
 import { getProvider } from '../providers/index.js';
+import { VERSION } from '../version.js';
+import { ErrorCodes, makeErrorEnvelope, makeHttpError } from '../errors/index.js';
+// Supported protocol versions
+const SUPPORTED_VERSIONS = ['2.2', '2.1'];
+const DEFAULT_VERSION = '2.2';
+/**
+ * Get requested protocol version from request
+ * Priority: body.version > X-Cognitive-Version header > query param > default
+ */
+function getRequestedVersion(req, url, bodyVersion) {
+    // Body version takes priority
+    if (bodyVersion && SUPPORTED_VERSIONS.includes(bodyVersion)) {
+        return bodyVersion;
+    }
+    // Check header
+    const headerVersion = req.headers['x-cognitive-version'];
+    if (headerVersion && SUPPORTED_VERSIONS.includes(headerVersion)) {
+        return headerVersion;
+    }
+    // Check query param
+    const queryVersion = url.searchParams.get('version');
+    if (queryVersion && SUPPORTED_VERSIONS.includes(queryVersion)) {
+        return queryVersion;
+    }
+    return DEFAULT_VERSION;
+}
 // =============================================================================
 // Helpers
 // =============================================================================
-function jsonResponse(res, status, data) {
+function jsonResponse(res, status, data, protocolVersion = DEFAULT_VERSION) {
     res.writeHead(status, {
         'Content-Type': 'application/json',
         'Access-Control-Allow-Origin': '*',
         'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Cognitive-Version',
+        'X-Cognitive-Version': protocolVersion,
     });
     res.end(JSON.stringify(data, null, 2));
 }
-function parseBody(req) {
+const MAX_BODY_BYTES = 1024 * 1024; // 1MB
+function parseBody(req, maxBytes = MAX_BODY_BYTES) {
     return new Promise((resolve, reject) => {
         let body = '';
-        req.on('data', (chunk) => (body += chunk));
+        let received = 0;
+        req.on('data', (chunk) => {
+            const chunkSize = typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.length;
+            received += chunkSize;
+            if (received > maxBytes) {
+                const err = new Error('Payload too large');
+                err.code = 'PAYLOAD_TOO_LARGE';
+                req.destroy(err);
+                reject(err);
+                return;
+            }
+            body += chunk;
+        });
         req.on('end', () => resolve(body));
         req.on('error', reject);
     });
@@ -51,7 +91,16 @@ function verifyApiKey(req) {
 async function handleRoot(res) {
     jsonResponse(res, 200, {
         name: 'Cognitive Modules API',
-        version: '1.3.0',
+        version: VERSION,
+        protocol: {
+            version: DEFAULT_VERSION,
+            supported: SUPPORTED_VERSIONS,
+            negotiation: {
+                header: 'X-Cognitive-Version',
+                query: '?version=2.2',
+                body: 'version field in request body',
+            },
+        },
         docs: '/docs',
         endpoints: {
             run: 'POST /run',
@@ -72,7 +121,7 @@ async function handleHealth(res) {
     };
     jsonResponse(res, 200, {
         status: 'healthy',
-        version: '1.3.0',
+        version: VERSION,
         providers,
     });
 }
@@ -95,7 +144,12 @@ async function handleModules(res, searchPaths) {
 async function handleModuleInfo(res, moduleName, searchPaths) {
     const moduleData = await findModule(moduleName, searchPaths);
     if (!moduleData) {
-        jsonResponse(res, 404, { error: `Module '${moduleName}' not found` });
+        const envelope = makeErrorEnvelope({
+            code: ErrorCodes.MODULE_NOT_FOUND,
+            message: `Module '${moduleName}' not found`,
+            suggestion: 'Use GET /modules to list available modules',
+        });
+        jsonResponse(res, 404, envelope);
         return;
     }
     jsonResponse(res, 200, {
@@ -110,12 +164,28 @@ async function handleModuleInfo(res, moduleName, searchPaths) {
         outputSchema: moduleData.outputSchema,
     });
 }
-async function handleRun(req, res, searchPaths) {
+async function handleRun(req, res, searchPaths, url) {
+    // Version will be determined after parsing body
+    let protocolVersion = DEFAULT_VERSION;
+    // Helper to build error envelope using unified error factory
+    const buildHttpError = (code, message, options = {}) => {
+        const moduleName = options.moduleName ?? request?.module ?? 'unknown';
+        const providerName = options.providerName ?? request?.provider ?? 'unknown';
+        const [status, envelope] = makeHttpError({
+            code,
+            message,
+            version: protocolVersion,
+            suggestion: options.suggestion,
+            recoverable: options.recoverable,
+            retry_after_ms: options.retry_after_ms,
+            module: moduleName,
+            provider: providerName,
+        });
+        return [status, envelope];
+    };
     // Verify API key
     if (!verifyApiKey(req)) {
-        jsonResponse(res, 401, {
-            error: 'Missing or invalid API Key. Use header: Authorization: Bearer <your-api-key>',
-        });
+        jsonResponse(res, 401, buildHttpError(ErrorCodes.PERMISSION_DENIED, 'Missing or invalid API Key', { suggestion: 'Use header: Authorization: Bearer <your-api-key>' }), protocolVersion);
         return;
     }
     // Parse request body
@@ -124,52 +194,102 @@ async function handleRun(req, res, searchPaths) {
         const body = await parseBody(req);
         request = JSON.parse(body);
     }
-    catch {
-        jsonResponse(res, 400, { error: 'Invalid JSON body' });
+    catch (e) {
+        const err = e;
+        if (err?.code === 'PAYLOAD_TOO_LARGE') {
+            const [status, body] = buildHttpError(ErrorCodes.INPUT_TOO_LARGE, 'Payload too large', { suggestion: 'Reduce input size to under 1MB' });
+            jsonResponse(res, status, body, protocolVersion);
+            return;
+        }
+        const [status, body] = buildHttpError(ErrorCodes.PARSE_ERROR, 'Invalid JSON body', { suggestion: 'Ensure request body is valid JSON' });
+        jsonResponse(res, status, body, protocolVersion);
         return;
     }
+    if (!request || typeof request !== 'object') {
+        const [status, body] = buildHttpError(ErrorCodes.INVALID_INPUT, 'Invalid request body', { suggestion: 'Ensure request body is a JSON object' });
+        jsonResponse(res, status, body, protocolVersion);
+        return;
+    }
+    const reqBody = request;
+    // Determine protocol version (body > header > query > default)
+    protocolVersion = getRequestedVersion(req, url, reqBody.version);
     // Validate request
-    if (!request.module || !request.args) {
-        jsonResponse(res, 400, { error: 'Missing required fields: module, args' });
+    if (!reqBody.module || !reqBody.args) {
+        const [status, body] = buildHttpError(ErrorCodes.MISSING_REQUIRED_FIELD, 'Missing required fields: module, args', {
+            moduleName: reqBody?.module ?? 'unknown',
+            suggestion: 'Provide both "module" and "args" fields in request body'
+        });
+        jsonResponse(res, status, body, protocolVersion);
         return;
     }
     // Find module
-    const moduleData = await findModule(request.module, searchPaths);
+    const moduleData = await findModule(reqBody.module, searchPaths);
     if (!moduleData) {
-        jsonResponse(res, 404, { error: `Module '${request.module}' not found` });
+        const [status, body] = buildHttpError(ErrorCodes.MODULE_NOT_FOUND, `Module '${reqBody.module}' not found`, {
+            moduleName: reqBody.module,
+            suggestion: 'Use GET /modules to list available modules'
+        });
+        jsonResponse(res, status, body, protocolVersion);
         return;
     }
     try {
         // Create provider
-        const provider = getProvider(request.provider, request.model);
-        // Run module
+        const provider = getProvider(reqBody.provider, reqBody.model);
+        const providerName = provider.name;
+        // Run module (always use v2.2 format internally)
         const result = await runModule(moduleData, provider, {
-            input: { query: request.args, code: request.args },
+            args: reqBody.args,
             useV22: true,
         });
-        const response = {
-            ok: result.ok,
-            module: request.module,
-            provider: request.provider || process.env.LLM_PROVIDER || 'openai',
-        };
-        if (result.ok) {
-            if ('meta' in result)
-                response.meta = result.meta;
-            if ('data' in result)
-                response.data = result.data;
+        // Build response envelope with requested protocol version
+        if (result.ok && 'data' in result) {
+            const v22Result = result;
+            const response = {
+                ok: true,
+                version: protocolVersion,
+                meta: v22Result.meta ?? {
+                    confidence: 0.5,
+                    risk: 'medium',
+                    explain: 'No meta provided',
+                },
+                data: v22Result.data,
+                module: reqBody.module,
+                provider: providerName,
+            };
+            jsonResponse(res, 200, response, protocolVersion);
         }
         else {
-            if ('error' in result)
-                response.error = result.error?.message;
+            // Error response - must include meta and full error object
+            const errorResult = result;
+            const response = {
+                ok: false,
+                version: protocolVersion,
+                meta: errorResult.meta ?? {
+                    confidence: 0.0,
+                    risk: 'high',
+                    explain: errorResult.error?.message ?? 'An error occurred',
+                },
+                error: errorResult.error ?? {
+                    code: ErrorCodes.INTERNAL_ERROR,
+                    message: 'Unknown error',
+                    recoverable: false,
+                },
+                partial_data: errorResult.partial_data,
+                module: reqBody.module,
+                provider: providerName,
+            };
+            jsonResponse(res, 200, response, protocolVersion);
         }
-        jsonResponse(res, 200, response);
     }
     catch (error) {
-        jsonResponse(res, 500, {
-            ok: false,
-            error: error instanceof Error ? error.message : String(error),
-            module: request.module,
+        // Infrastructure error - still return envelope
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const [status, response] = buildHttpError(ErrorCodes.INTERNAL_ERROR, errorMessage, {
+            moduleName: reqBody?.module,
+            providerName: reqBody?.provider,
+            recoverable: false,
         });
+        jsonResponse(res, status, response, protocolVersion);
     }
 }
 export function createServer(options = {}) {
@@ -184,7 +304,8 @@ export function createServer(options = {}) {
             res.writeHead(204, {
                 'Access-Control-Allow-Origin': '*',
                 'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-                'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+                'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Cognitive-Version',
+                'Access-Control-Expose-Headers': 'X-Cognitive-Version',
             });
             res.end();
             return;
@@ -205,17 +326,27 @@ export function createServer(options = {}) {
                 await handleModuleInfo(res, moduleName, searchPaths);
             }
             else if (path === '/run' && method === 'POST') {
-                await handleRun(req, res, searchPaths);
+                await handleRun(req, res, searchPaths, url);
             }
             else {
-                jsonResponse(res, 404, { error: 'Not found' });
+                const envelope = makeErrorEnvelope({
+                    code: ErrorCodes.ENDPOINT_NOT_FOUND,
+                    message: `Endpoint '${path}' not found`,
+                    suggestion: 'Use GET / to see available endpoints',
+                    risk: 'low',
+                });
+                jsonResponse(res, 404, envelope);
             }
         }
         catch (error) {
             console.error('Server error:', error);
-            jsonResponse(res, 500, {
-                error: error instanceof Error ? error.message : 'Internal server error',
+            const errorMessage = error instanceof Error ? error.message : 'Internal server error';
+            const envelope = makeErrorEnvelope({
+                code: ErrorCodes.INTERNAL_ERROR,
+                message: errorMessage,
+                recoverable: false,
             });
+            jsonResponse(res, 500, envelope);
         }
     });
     return server;