cognitive-modules-cli 2.2.0 → 2.2.5

package/dist/providers/openai.js

@@ -1,5 +1,7 @@
 /**
  * OpenAI Provider - OpenAI API (and compatible APIs)
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 export class OpenAIProvider extends BaseProvider {
@@ -16,6 +18,12 @@ export class OpenAIProvider extends BaseProvider {
     isConfigured() {
         return !!this.apiKey;
     }
+    /**
+     * OpenAI supports streaming.
+     */
+    supportsStreaming() {
+        return true;
+    }
     async invoke(params) {
         if (!this.isConfigured()) {
             throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable.');
@@ -64,4 +72,129 @@ export class OpenAIProvider extends BaseProvider {
             } : undefined,
         };
     }
+    /**
+     * Stream-based invoke using OpenAI's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    async *invokeStream(params) {
+        if (!this.isConfigured()) {
+            throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable.');
+        }
+        const url = `${this.baseUrl}/chat/completions`;
+        const body = {
+            model: this.model,
+            messages: params.messages,
+            temperature: params.temperature ?? 0.7,
+            max_tokens: params.maxTokens ?? 4096,
+            stream: true,
+            stream_options: { include_usage: true },
+        };
+        // Add JSON mode if schema provided
+        if (params.jsonSchema) {
+            body.response_format = { type: 'json_object' };
+            // Append schema instruction to last user message
+            const lastUserIdx = params.messages.findLastIndex(m => m.role === 'user');
+            if (lastUserIdx >= 0) {
+                const messages = [...params.messages];
+                messages[lastUserIdx] = {
+                    ...messages[lastUserIdx],
+                    content: messages[lastUserIdx].content + this.buildJsonPrompt(params.jsonSchema),
+                };
+                body.messages = messages;
+            }
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`OpenAI API error: ${response.status} - ${error}`);
+        }
+        if (!response.body) {
+            throw new Error('OpenAI API returned no body for streaming request');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        const collectedChunks = [];
+        let usage;
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete lines from the buffer
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed === 'data: [DONE]')
+                        continue;
+                    if (trimmed.startsWith('data: ')) {
+                        try {
+                            const data = JSON.parse(trimmed.slice(6));
+                            // Extract content chunk
+                            const content = data.choices?.[0]?.delta?.content;
+                            if (content) {
+                                collectedChunks.push(content);
+                                yield content;
+                            }
+                            // Extract usage info (usually in the last chunk)
+                            if (data.usage) {
+                                usage = {
+                                    promptTokens: data.usage.prompt_tokens || 0,
+                                    completionTokens: data.usage.completion_tokens || 0,
+                                    totalTokens: data.usage.total_tokens || 0,
+                                };
+                            }
+                        }
+                        catch {
+                            // Skip invalid JSON chunks
+                        }
+                    }
+                }
+            }
+            // Flush decoder and process trailing buffered data even without trailing newline.
+            buffer += decoder.decode();
+            for (const line of buffer.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed === 'data: [DONE]')
+                    continue;
+                if (trimmed.startsWith('data: ')) {
+                    try {
+                        const data = JSON.parse(trimmed.slice(6));
+                        const content = data.choices?.[0]?.delta?.content;
+                        if (content) {
+                            collectedChunks.push(content);
+                            yield content;
+                        }
+                        if (data.usage) {
+                            usage = {
+                                promptTokens: data.usage.prompt_tokens || 0,
+                                completionTokens: data.usage.completion_tokens || 0,
+                                totalTokens: data.usage.total_tokens || 0,
+                            };
+                        }
+                    }
+                    catch {
+                        // Skip invalid JSON chunks
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const fullContent = collectedChunks.join('');
+        return {
+            content: fullContent,
+            usage,
+        };
+    }
 }

package/dist/registry/client.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 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');
+ */
+/** v1 Registry Format (current cognitive-registry.json) */
+export interface RegistryV1 {
+    $schema?: string;
+    version: string;
+    updated: string;
+    modules: {
+        [name: string]: {
+            description: string;
+            version: string;
+            source: string;
+            tags: string[];
+            author: string;
+        };
+    };
+    categories?: {
+        [key: string]: {
+            name: string;
+            description: string;
+            modules: string[];
+        };
+    };
+}
+/** v2 Registry Format (new format per REGISTRY-PROTOCOL.md) */
+export interface RegistryV2 {
+    $schema?: string;
+    version: string;
+    updated: string;
+    modules: {
+        [name: string]: RegistryEntryV2;
+    };
+    categories?: {
+        [key: string]: {
+            name: string;
+            name_zh?: string;
+            description: string;
+            modules: string[];
+        };
+    };
+    featured?: string[];
+    stats?: {
+        total_modules: number;
+        total_downloads: number;
+        last_updated: string;
+    };
+}
+/** v2 Registry Entry */
+export interface RegistryEntryV2 {
+    identity: {
+        name: string;
+        namespace: string;
+        version: string;
+        spec_version: string;
+    };
+    metadata: {
+        description: string;
+        description_zh?: string;
+        author: string;
+        license?: string;
+        repository?: string;
+        documentation?: string;
+        homepage?: string;
+        keywords?: string[];
+        tier?: 'exec' | 'decision' | 'exploration';
+    };
+    quality?: {
+        conformance_level?: number;
+        test_coverage?: number;
+        test_vector_pass?: boolean;
+        verified?: boolean;
+        verified_by?: string;
+        verified_at?: string;
+        downloads_30d?: number;
+        stars?: number;
+        badges?: string[];
+        deprecated?: boolean;
+        successor?: string;
+        deprecation_reason?: string;
+    };
+    dependencies: {
+        runtime_min: string;
+        modules: string[];
+    };
+    distribution: {
+        tarball?: string;
+        checksum?: string;
+        size_bytes?: number;
+        files?: string[];
+        source?: string;
+    };
+    timestamps?: {
+        created_at?: string;
+        updated_at?: string;
+        deprecated_at?: string;
+    };
+}
+/** Normalized module info (works with both v1 and v2) */
+export interface ModuleInfo {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    source: string;
+    keywords: string[];
+    tier?: string;
+    namespace?: string;
+    license?: string;
+    repository?: string;
+    conformance_level?: number;
+    verified?: boolean;
+    deprecated?: boolean;
+}
+/** Search result */
+export interface SearchResult {
+    name: string;
+    description: string;
+    version: string;
+    score: number;
+    keywords: string[];
+}
+export declare class RegistryClient {
+    private registryUrl;
+    private cache;
+    constructor(registryUrl?: string);
+    private parseRegistryResponse;
+    /**
+     * Generate a unique cache filename based on registry URL
+     */
+    private getCacheFileName;
+    /**
+     * Fetch registry index (with caching)
+     */
+    fetchRegistry(forceRefresh?: boolean): Promise<RegistryV1 | RegistryV2>;
+    /**
+     * Check if registry is v2 format
+     */
+    private isV2Registry;
+    /**
+     * Normalize module entry to unified format
+     */
+    private normalizeModule;
+    /**
+     * List all modules in registry
+     */
+    listModules(): Promise<ModuleInfo[]>;
+    /**
+     * Get a specific module by name
+     */
+    getModule(name: string): Promise<ModuleInfo | null>;
+    /**
+     * Search modules by query
+     */
+    search(query: string): Promise<SearchResult[]>;
+    /**
+     * Get categories
+     */
+    getCategories(): Promise<{
+        [key: string]: {
+            name: string;
+            description: string;
+            modules: string[];
+        };
+    }>;
+    /**
+     * Parse GitHub source string
+     * Format: github:<owner>/<repo>[/<path>][@<ref>]
+     */
+    parseGitHubSource(source: string): {
+        org: string;
+        repo: string;
+        path?: string;
+        ref?: string;
+    } | null;
+    /**
+     * Verify checksum of downloaded file
+     */
+    verifyChecksum(filePath: string, expected: string): Promise<boolean>;
+    /**
+     * Get the download URL for a module
+     */
+    getDownloadUrl(moduleName: string): Promise<{
+        url: string;
+        isGitHub: boolean;
+        githubInfo?: {
+            org: string;
+            repo: string;
+            path?: string;
+            ref?: string;
+        };
+    }>;
+}
+export declare const defaultRegistry: RegistryClient;
+export declare function listRegistryModules(): Promise<ModuleInfo[]>;
+export declare function getRegistryModule(name: string): Promise<ModuleInfo | null>;
+export declare function searchRegistry(query: string): Promise<SearchResult[]>;

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);
+}