cognitive-modules-cli 2.2.1 → 2.2.7

package/dist/registry/client.js

@@ -0,0 +1,359 @@
+/**
+ * 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/Cognary/cognitive/main/cognitive-registry.v2.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.tarball,
+                tarball: v2.distribution.tarball,
+                checksum: v2.distribution.checksum,
+                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,
+                checksum: module.checksum,
+                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/registry/tar.d.ts

@@ -0,0 +1,8 @@
+export interface ExtractTarGzOptions {
+    maxFiles?: number;
+    maxTotalBytes?: number;
+    maxSingleFileBytes?: number;
+    maxTarBytes?: number;
+}
+export declare function extractTarGzFile(tarGzPath: string, destDir: string, options?: ExtractTarGzOptions): Promise<string[]>;
+export declare function extractTarGzBuffer(gzBuffer: Buffer, destDir: string, options?: ExtractTarGzOptions): Promise<string[]>;