cognitive-modules-cli 2.2.1 → 2.2.5

package/dist/commands/add.d.ts

@@ -1,8 +1,13 @@
 /**
- * Add command - Install modules from GitHub
+ * Add command - Install modules from GitHub or Registry
  *
- * cog add ziel-io/cognitive-modules -m code-simplifier
- * cog add https://github.com/org/repo --module name --tag v1.0.0
+ * From Registry:
+ *   cog add code-reviewer
+ *   cog add code-reviewer@2.0.0
+ *
+ * From GitHub:
+ *   cog add ziel-io/cognitive-modules -m code-simplifier
+ *   cog add https://github.com/org/repo --module name --tag v1.0.0
  */
 import type { CommandContext, CommandResult } from '../types.js';
 export interface AddOptions {
@@ -10,25 +15,39 @@ export interface AddOptions {
     name?: string;
     branch?: string;
     tag?: string;
+    registry?: string;
+}
+export interface InstallInfo {
+    source: string;
+    githubUrl: string;
+    modulePath?: string;
+    tag?: string;
+    branch?: string;
+    version?: string;
+    installedAt: string;
+    installedTime: string;
+    /** Registry module name if installed from registry */
+    registryModule?: string;
+    /** Registry URL if installed from a custom registry */
+    registryUrl?: string;
 }
 interface InstallManifest {
-    [moduleName: string]: {
-        source: string;
-        githubUrl: string;
-        modulePath?: string;
-        tag?: string;
-        branch?: string;
-        version?: string;
-        installedAt: string;
-        installedTime: string;
-    };
+    [moduleName: string]: InstallInfo;
 }
 /**
  * Get installation info for a module
  */
 export declare function getInstallInfo(moduleName: string): Promise<InstallManifest[string] | null>;
+/**
+ * Add a module from the registry
+ */
+export declare function addFromRegistry(moduleSpec: string, ctx: CommandContext, options?: AddOptions): Promise<CommandResult>;
 /**
  * Add a module from GitHub
  */
-export declare function add(url: string, ctx: CommandContext, options?: AddOptions): Promise<CommandResult>;
+export declare function addFromGitHub(url: string, ctx: CommandContext, options?: AddOptions): Promise<CommandResult>;
+/**
+ * Add a module from GitHub or Registry (auto-detect source)
+ */
+export declare function add(source: string, ctx: CommandContext, options?: AddOptions): Promise<CommandResult>;
 export {};

package/dist/commands/add.js

@@ -1,15 +1,21 @@
 /**
- * Add command - Install modules from GitHub
+ * Add command - Install modules from GitHub or Registry
  *
- * cog add ziel-io/cognitive-modules -m code-simplifier
- * cog add https://github.com/org/repo --module name --tag v1.0.0
+ * From Registry:
+ *   cog add code-reviewer
+ *   cog add code-reviewer@2.0.0
+ *
+ * From GitHub:
+ *   cog add ziel-io/cognitive-modules -m code-simplifier
+ *   cog add https://github.com/org/repo --module name --tag v1.0.0
  */
 import { createWriteStream, existsSync, mkdirSync, rmSync, readdirSync, statSync, copyFileSync } from 'node:fs';
 import { writeFile, readFile, mkdir } from 'node:fs/promises';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
-import { join, basename } from 'node:path';
+import { join, basename, dirname, resolve, sep, isAbsolute } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
+import { RegistryClient } from '../registry/client.js';
 // Module storage paths
 const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
 const INSTALLED_MANIFEST = join(homedir(), '.cognitive', 'installed.json');
@@ -33,6 +39,33 @@ function parseGitHubUrl(url) {
         fullUrl: `https://github.com/${org}/${repo}`,
     };
 }
+function assertSafeModuleName(name) {
+    const trimmed = name.trim();
+    if (!trimmed) {
+        throw new Error('Invalid module name: empty');
+    }
+    if (trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
+        throw new Error(`Invalid module name: ${name}`);
+    }
+    if (isAbsolute(trimmed)) {
+        throw new Error(`Invalid module name (absolute path not allowed): ${name}`);
+    }
+    return trimmed;
+}
+function resolveModuleTarget(moduleName) {
+    const safeName = assertSafeModuleName(moduleName);
+    const targetPath = resolve(USER_MODULES_DIR, safeName);
+    const root = resolve(USER_MODULES_DIR) + sep;
+    if (!targetPath.startsWith(root)) {
+        throw new Error(`Invalid module name (path traversal): ${moduleName}`);
+    }
+    return targetPath;
+}
+function isPathWithinRoot(rootDir, targetPath) {
+    const root = resolve(rootDir);
+    const target = resolve(targetPath);
+    return target === root || target.startsWith(root + sep);
+}
 /**
  * Download and extract ZIP from GitHub
  */
@@ -56,6 +89,9 @@ async function downloadAndExtract(org, repo, ref, isTag) {
     await pipeline(Readable.fromWeb(response.body), fileStream);
     // Extract using built-in unzip (available on most systems)
     const { execSync } = await import('node:child_process');
+    // Validate ZIP entries to avoid path traversal (Zip Slip)
+    const listing = execSync(`unzip -Z1 "${zipPath}"`, { stdio: 'pipe' }).toString('utf-8');
+    assertSafeZipEntries(listing);
     execSync(`unzip -q "${zipPath}" -d "${tempDir}"`, { stdio: 'pipe' });
     // Find extracted directory
     const entries = readdirSync(tempDir).filter(e => e !== 'repo.zip' && statSync(join(tempDir, e)).isDirectory());
@@ -64,6 +100,22 @@ async function downloadAndExtract(org, repo, ref, isTag) {
     }
     return join(tempDir, entries[0]);
 }
+/**
+ * Validate ZIP listing to prevent path traversal.
+ */
+function assertSafeZipEntries(listing) {
+    const entries = listing.split(/\r?\n/).map(e => e.trim()).filter(Boolean);
+    for (const entry of entries) {
+        const normalized = entry.replace(/\\/g, '/');
+        if (normalized.startsWith('/') || /^[a-zA-Z]:\//.test(normalized)) {
+            throw new Error(`Unsafe ZIP entry (absolute path): ${entry}`);
+        }
+        const parts = normalized.split('/');
+        if (parts.includes('..')) {
+            throw new Error(`Unsafe ZIP entry (path traversal): ${entry}`);
+        }
+    }
+}
 /**
  * Check if a directory is a valid module
  */
@@ -76,11 +128,15 @@ function isValidModule(path) {
  * Find module within repository
  */
 function findModuleInRepo(repoRoot, modulePath) {
-    const possiblePaths = [
-        join(repoRoot, modulePath),
-        join(repoRoot, 'cognitive', 'modules', modulePath),
-        join(repoRoot, 'modules', modulePath),
+    const candidatePaths = [
+        resolve(repoRoot, modulePath),
+        resolve(repoRoot, 'cognitive', 'modules', modulePath),
+        resolve(repoRoot, 'modules', modulePath),
     ];
+    const possiblePaths = candidatePaths.filter((p) => isPathWithinRoot(repoRoot, p));
+    if (possiblePaths.length === 0) {
+        throw new Error(`Invalid module path (outside repository root): ${modulePath}`);
+    }
     for (const p of possiblePaths) {
         if (existsSync(p) && isValidModule(p)) {
             return p;
@@ -157,10 +213,135 @@ export async function getInstallInfo(moduleName) {
     const manifest = JSON.parse(content);
     return manifest[moduleName] || null;
 }
+/**
+ * Check if input looks like a GitHub URL or org/repo format
+ *
+ * GitHub formats:
+ * - https://github.com/org/repo
+ * - http://github.com/org/repo
+ * - github:org/repo
+ * - org/repo (shorthand, must be exactly two parts)
+ *
+ * NOT GitHub (registry module names):
+ * - code-reviewer
+ * - code-reviewer@1.0.0
+ * - my-module (no slash)
+ */
+function isGitHubSource(input) {
+    // URL formats
+    if (input.startsWith('http://') || input.startsWith('https://')) {
+        return true;
+    }
+    // github: prefix format
+    if (input.startsWith('github:')) {
+        return true;
+    }
+    // Contains github.com
+    if (input.includes('github.com')) {
+        return true;
+    }
+    // Shorthand format: org/repo (exactly two parts, no @ version suffix)
+    // Must match pattern like: owner/repo or owner/repo but NOT module@version
+    const shorthandMatch = input.match(/^([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)$/);
+    if (shorthandMatch) {
+        // Additional check: if it contains @, it's likely a scoped npm package or versioned module
+        // But GitHub shorthand shouldn't have @ in the middle
+        return !input.includes('@');
+    }
+    return false;
+}
+/**
+ * Parse module name with optional version: "module-name@1.0.0"
+ */
+function parseModuleSpec(spec) {
+    const match = spec.match(/^([^@]+)(?:@(.+))?$/);
+    if (!match) {
+        return { name: spec };
+    }
+    return { name: match[1], version: match[2] };
+}
+/**
+ * Add a module from the registry
+ */
+export async function addFromRegistry(moduleSpec, ctx, options = {}) {
+    const { name: moduleName, version: requestedVersion } = parseModuleSpec(moduleSpec);
+    const { name: customName, registry: registryUrl } = options;
+    try {
+        const client = new RegistryClient(registryUrl);
+        const moduleInfo = await client.getModule(moduleName);
+        if (!moduleInfo) {
+            return {
+                success: false,
+                error: `Module not found in registry: ${moduleName}\nUse 'cog search' to find available modules.`,
+            };
+        }
+        // Check if deprecated
+        if (moduleInfo.deprecated) {
+            console.error(`Warning: Module '${moduleName}' is deprecated.`);
+        }
+        // Get download info
+        const downloadInfo = await client.getDownloadUrl(moduleName);
+        if (downloadInfo.isGitHub && downloadInfo.githubInfo) {
+            const { org, repo, path, ref } = downloadInfo.githubInfo;
+            // Use addFromGitHub() directly (not add() to avoid recursion)
+            const result = await addFromGitHub(`${org}/${repo}`, ctx, {
+                module: path,
+                name: customName || moduleName,
+                tag: requestedVersion || ref,
+                branch: ref || 'main',
+            });
+            // If successful, update the install manifest to track registry info
+            if (result.success && result.data) {
+                const data = result.data;
+                const installName = data.name;
+                // Update manifest with registry info
+                const existingInfo = await getInstallInfo(installName);
+                if (existingInfo) {
+                    await recordInstall(installName, {
+                        ...existingInfo,
+                        registryModule: moduleName,
+                        registryUrl: registryUrl,
+                    });
+                }
+                else {
+                    // Fallback: create minimal install info if not found (shouldn't happen but safety first)
+                    await recordInstall(installName, {
+                        source: 'registry',
+                        githubUrl: `${org}/${repo}`,
+                        modulePath: path,
+                        version: data.version,
+                        installedAt: data.location || '',
+                        installedTime: new Date().toISOString(),
+                        registryModule: moduleName,
+                        registryUrl: registryUrl,
+                    });
+                }
+                // Update result to indicate registry source
+                result.data = {
+                    ...result.data,
+                    source: 'registry',
+                    registryModule: moduleName,
+                };
+            }
+            return result;
+        }
+        // For tarball sources, download directly (future implementation)
+        return {
+            success: false,
+            error: `Tarball downloads not yet supported. Source: ${moduleInfo.source}`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 /**
  * Add a module from GitHub
  */
-export async function add(url, ctx, options = {}) {
+export async function addFromGitHub(url, ctx, options = {}) {
     const { org, repo, fullUrl } = parseGitHubUrl(url);
     const { module: modulePath, name, branch = 'main', tag } = options;
     // Determine ref (tag takes priority)
@@ -184,11 +365,11 @@ export async function add(url, ctx, options = {}) {
             sourcePath = repoRoot;
         }
         // Determine module name
-        moduleName = name || basename(sourcePath);
+        moduleName = name ? assertSafeModuleName(name) : basename(sourcePath);
         // Get version
         const version = await getModuleVersion(sourcePath);
         // Install to user modules dir
-        const targetPath = join(USER_MODULES_DIR, moduleName);
+        const targetPath = resolveModuleTarget(moduleName);
         // Remove existing
         if (existsSync(targetPath)) {
             rmSync(targetPath, { recursive: true, force: true });
@@ -208,8 +389,10 @@ export async function add(url, ctx, options = {}) {
             installedTime: new Date().toISOString(),
         });
         // Cleanup temp directory
-        const tempDir = repoRoot.split('/').slice(0, -1).join('/');
-        rmSync(tempDir, { recursive: true, force: true });
+        const tempDir = dirname(repoRoot);
+        if (tempDir && tempDir !== '/' && tempDir !== '.' && tempDir !== USER_MODULES_DIR) {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
         return {
             success: true,
             data: {
@@ -217,13 +400,39 @@ export async function add(url, ctx, options = {}) {
                 name: moduleName,
                 version,
                 location: targetPath,
+                source: 'github',
             },
         };
     }
     catch (error) {
+        // Cleanup temp directory on error
+        if (repoRoot) {
+            try {
+                const tempDir = dirname(repoRoot);
+                if (tempDir && tempDir !== '/' && tempDir !== '.' && tempDir !== USER_MODULES_DIR) {
+                    rmSync(tempDir, { recursive: true, force: true });
+                }
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
         return {
             success: false,
             error: error instanceof Error ? error.message : String(error),
         };
     }
 }
+/**
+ * Add a module from GitHub or Registry (auto-detect source)
+ */
+export async function add(source, ctx, options = {}) {
+    // Determine source type
+    if (isGitHubSource(source)) {
+        return addFromGitHub(source, ctx, options);
+    }
+    else {
+        // Treat as registry module name
+        return addFromRegistry(source, ctx, options);
+    }
+}

package/dist/commands/compose.js

@@ -8,14 +8,30 @@
  * - Iterative: A → (check) → A → ... → Done
  */
 import { findModule, getDefaultSearchPaths, executeComposition } from '../modules/index.js';
+import { ErrorCodes, attachContext, makeErrorEnvelope } from '../errors/index.js';
+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));
+}
 export async function compose(moduleName, ctx, options = {}) {
     const searchPaths = getDefaultSearchPaths(ctx.cwd);
     // Find module
     const module = await findModule(moduleName, searchPaths);
     if (!module) {
+        const errorEnvelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.MODULE_NOT_FOUND,
+            message: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+            suggestion: "Use 'cog list' to see installed modules or 'cog search' to find modules in registry",
+        }), { module: moduleName, provider: ctx.provider.name });
         return {
             success: false,
-            error: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+            error: errorEnvelope.error.message,
+            data: errorEnvelope,
         };
     }
     try {
@@ -26,16 +42,26 @@ export async function compose(moduleName, ctx, options = {}) {
                 inputData = JSON.parse(options.input);
             }
             catch {
+                const errorEnvelope = attachContext(makeErrorEnvelope({
+                    code: ErrorCodes.INVALID_INPUT,
+                    message: `Invalid JSON input: ${options.input}`,
+                    suggestion: 'Ensure input is valid JSON format',
+                }), { module: moduleName, provider: ctx.provider.name });
                 return {
                     success: false,
-                    error: `Invalid JSON input: ${options.input}`,
+                    error: errorEnvelope.error.message,
+                    data: errorEnvelope,
                 };
             }
         }
         // Handle --args as text input
         if (options.args) {
-            inputData.query = options.args;
-            inputData.code = options.args;
+            if (looksLikeCode(options.args)) {
+                inputData.code = options.args;
+            }
+            else {
+                inputData.query = options.args;
+            }
         }
         // Execute composition
         const result = await executeComposition(moduleName, inputData, ctx.provider, {
@@ -56,11 +82,27 @@ export async function compose(moduleName, ctx, options = {}) {
             }
             console.error(`--- Total: ${result.totalTimeMs}ms ---`);
         }
+        if (!result.ok) {
+            const partialData = options.trace
+                ? { moduleResults: result.moduleResults, trace: result.trace }
+                : { moduleResults: result.moduleResults };
+            const errorEnvelope = attachContext(makeErrorEnvelope({
+                code: result.error?.code ?? ErrorCodes.INTERNAL_ERROR,
+                message: result.error?.message ?? 'Composition failed',
+                details: result.error?.module ? { module: result.error.module } : undefined,
+                partial_data: partialData,
+            }), { module: moduleName, provider: ctx.provider.name });
+            return {
+                success: false,
+                error: errorEnvelope.error.message,
+                data: errorEnvelope,
+            };
+        }
         // Return result
         if (options.trace) {
             // Include full result with trace
             return {
-                success: result.ok,
+                success: true,
                 data: {
                     ok: result.ok,
                     result: result.result,
@@ -73,33 +115,28 @@ export async function compose(moduleName, ctx, options = {}) {
         }
         else if (options.pretty) {
             return {
-                success: result.ok,
+                success: true,
                 data: result.result,
             };
         }
         else {
-            // For non-pretty mode, return data (success) or error (failure)
-            if (result.ok && result.result) {
-                return {
-                    success: true,
-                    data: result.result.data,
-                };
-            }
-            else {
-                return {
-                    success: false,
-                    error: result.error
-                        ? `${result.error.code}: ${result.error.message}`
-                        : 'Composition failed',
-                    data: result.moduleResults,
-                };
-            }
+            // Keep compose output consistent with run/pipe: always return full v2.2 envelope
+            return {
+                success: true,
+                data: result.result,
+            };
         }
     }
     catch (e) {
+        const errorEnvelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.INTERNAL_ERROR,
+            message: e instanceof Error ? e.message : String(e),
+            recoverable: false,
+        }), { module: moduleName, provider: ctx.provider.name });
         return {
             success: false,
-            error: e instanceof Error ? e.message : String(e),
+            error: errorEnvelope.error.message,
+            data: errorEnvelope,
         };
     }
 }

package/dist/commands/index.d.ts

@@ -10,3 +10,7 @@ export * from './update.js';
 export * from './remove.js';
 export * from './versions.js';
 export * from './compose.js';
+export * from './validate.js';
+export * from './migrate.js';
+export * from './test.js';
+export * from './search.js';

package/dist/commands/index.js

@@ -10,3 +10,7 @@ export * from './update.js';
 export * from './remove.js';
 export * from './versions.js';
 export * from './compose.js';
+export * from './validate.js';
+export * from './migrate.js';
+export * from './test.js';
+export * from './search.js';

package/dist/commands/init.js

@@ -3,6 +3,28 @@
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+function assertSafeModuleName(name) {
+    const trimmed = name.trim();
+    if (!trimmed) {
+        throw new Error('Invalid module name: empty');
+    }
+    if (trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
+        throw new Error(`Invalid module name: ${name}`);
+    }
+    if (path.isAbsolute(trimmed)) {
+        throw new Error(`Invalid module name (absolute path not allowed): ${name}`);
+    }
+    return trimmed;
+}
+function resolveModuleDir(rootDir, moduleName) {
+    const safeName = assertSafeModuleName(moduleName);
+    const targetPath = path.resolve(rootDir, safeName);
+    const root = path.resolve(rootDir) + path.sep;
+    if (!targetPath.startsWith(root)) {
+        throw new Error(`Invalid module name (path traversal): ${moduleName}`);
+    }
+    return targetPath;
+}
 const EXAMPLE_MODULE_MD = `---
 name: my-module
 version: 1.0.0
@@ -46,7 +68,7 @@ export async function init(ctx, moduleName) {
         await fs.mkdir(cognitiveDir, { recursive: true });
         // If module name provided, create a new module
         if (moduleName) {
-            const moduleDir = path.join(cognitiveDir, moduleName);
+            const moduleDir = resolveModuleDir(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);

package/dist/commands/migrate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * cog migrate - Migrate modules to v2.2 format
+ *
+ * Aligns with Python CLI's `cog migrate` command.
+ * Performs migration from v0/v1/v2.1 to v2.2 format.
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface MigrateOptions {
+    /** Dry run - only show what would be done */
+    dryRun?: boolean;
+    /** Create backup before migration */
+    backup?: boolean;
+    /** Migrate all modules */
+    all?: boolean;
+}
+export interface MigrateResult {
+    moduleName: string;
+    modulePath: string;
+    success: boolean;
+    changes: string[];
+    warnings: string[];
+}
+/**
+ * Migrate a single module to v2.2 format.
+ */
+export declare function migrate(nameOrPath: string, ctx: CommandContext, options?: MigrateOptions): Promise<CommandResult>;
+/**
+ * Migrate all modules to v2.2 format.
+ */
+export declare function migrateAll(ctx: CommandContext, options?: MigrateOptions): Promise<CommandResult>;