cognitive-modules-cli 2.2.0 → 2.2.5

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;

package/dist/types.d.ts

@@ -6,6 +6,17 @@ export interface Provider {
     name: string;
     invoke(params: InvokeParams): Promise<InvokeResult>;
     isConfigured(): boolean;
+    /**
+     * Stream-based invoke (optional).
+     * Returns an async generator that yields content chunks.
+     *
+     * If not implemented, falls back to non-streaming invoke.
+     */
+    invokeStream?(params: InvokeParams): AsyncGenerator<string, InvokeResult, unknown>;
+    /**
+     * Check if this provider supports streaming.
+     */
+    supportsStreaming?(): boolean;
 }
 export interface InvokeParams {
     messages: Message[];
@@ -35,6 +46,77 @@ export type RiskLevel = 'none' | 'low' | 'medium' | 'high';
 export type EnumStrategy = 'strict' | 'extensible';
 /** Risk aggregation rule */
 export type RiskRule = 'max_changes_risk' | 'max_issues_risk' | 'explicit';
+/** Composition pattern types */
+export type CompositionPattern = 'sequential' | 'parallel' | 'conditional' | 'iterative';
+/** Aggregation strategy for combining multiple outputs */
+export type AggregationStrategy = 'merge' | 'array' | 'first' | 'custom';
+/** Semver-like version matching pattern */
+export type VersionPattern = string;
+/** Dependency declaration for composition.requires */
+export interface DependencyDeclaration {
+    /** Module name */
+    name: string;
+    /** Semver version pattern */
+    version?: VersionPattern;
+    /** Whether dependency is optional */
+    optional?: boolean;
+    /** Fallback module if unavailable */
+    fallback?: string | null;
+    /** Per-module timeout (ms) */
+    timeout_ms?: number;
+}
+/** Dataflow mapping expression */
+export interface DataflowMapping {
+    [key: string]: string;
+}
+/** Dataflow step configuration */
+export interface DataflowStep {
+    /** Source of data: 'input' or 'module-name.output' */
+    from: string | string[];
+    /** Destination: module name or 'output' */
+    to: string | string[];
+    /** Field mapping expressions */
+    mapping?: DataflowMapping;
+    /** Condition for execution */
+    condition?: string;
+    /** Aggregation strategy when from is an array */
+    aggregate?: AggregationStrategy;
+    /** Custom aggregation function name */
+    aggregator?: string;
+}
+/** Conditional routing rule */
+export interface RoutingRule {
+    /** Condition expression */
+    condition: string;
+    /** Next module to execute (null means use current result) */
+    next: string | null;
+}
+/** Iteration configuration */
+export interface IterationConfig {
+    /** Maximum iterations */
+    max_iterations?: number;
+    /** Condition to continue iterating */
+    continue_condition?: string;
+    /** Condition to stop iterating */
+    stop_condition?: string;
+}
+/** Full composition configuration (from module.yaml) */
+export interface CompositionConfig {
+    /** Composition pattern */
+    pattern: CompositionPattern;
+    /** Required dependencies */
+    requires?: DependencyDeclaration[];
+    /** Dataflow configuration */
+    dataflow?: DataflowStep[];
+    /** Conditional routing rules */
+    routing?: RoutingRule[];
+    /** Maximum composition depth */
+    max_depth?: number;
+    /** Total timeout for composition (ms) */
+    timeout_ms?: number;
+    /** Iteration configuration */
+    iteration?: IterationConfig;
+}
 export interface CognitiveModule {
     name: string;
     version: string;
@@ -52,6 +134,7 @@ export interface CognitiveModule {
     enums?: EnumConfig;
     compat?: CompatConfig;
     metaConfig?: MetaConfig;
+    composition?: CompositionConfig;
     context?: 'fork' | 'main';
     prompt: string;
     inputSchema?: object;
@@ -148,20 +231,39 @@ export interface EnvelopeMeta {
     /** Execution latency in milliseconds */
     latency_ms?: number;
 }
+/**
+ * Enhanced error structure with retry and recovery info (v2.2.1).
+ *
+ * Consistent across HTTP, MCP, and CLI layers.
+ * See ERROR-CODES.md for error code taxonomy.
+ */
+export interface EnvelopeError {
+    /** Error code (E-format like "E4006" or legacy like "MODULE_NOT_FOUND") */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error can be retried */
+    recoverable?: boolean;
+    /** Suggested action to fix the error */
+    suggestion?: string;
+    /** Suggested wait time before retry (in milliseconds) */
+    retry_after_ms?: number;
+    /** Additional error context */
+    details?: Record<string, unknown>;
+}
 /** Success response in v2.2 envelope format */
 export interface EnvelopeSuccessV22<T = unknown> {
     ok: true;
+    version?: string;
     meta: EnvelopeMeta;
     data: T;
 }
 /** Error response in v2.2 envelope format */
 export interface EnvelopeErrorV22 {
     ok: false;
+    version?: string;
     meta: EnvelopeMeta;
-    error: {
-        code: string;
-        message: string;
-    };
+    error: EnvelopeError;
     partial_data?: unknown;
 }
 /** v2.2 envelope response (union type) */
@@ -217,12 +319,10 @@ export interface ModuleResultData {
 /** v2.2 module result with meta and data separation */
 export interface ModuleResultV22 {
     ok: boolean;
+    version?: string;
     meta: EnvelopeMeta;
     data?: ModuleResultData;
-    error?: {
-        code: string;
-        message: string;
-    };
+    error?: EnvelopeError;
     partial_data?: unknown;
     raw?: string;
 }
@@ -253,11 +353,26 @@ export interface CommandContext {
     provider: Provider;
     verbose?: boolean;
 }
+/**
+ * CLI command result (legacy format).
+ *
+ * For new code, prefer using CognitiveErrorEnvelope from errors/index.js
+ * for error responses to ensure cross-layer consistency.
+ */
 export interface CommandResult {
     success: boolean;
     data?: unknown;
     error?: string;
 }
+/**
+ * Extended command result with unified error structure.
+ * Use this for commands that need full error details.
+ */
+export interface CommandResultV2 {
+    ok: boolean;
+    data?: unknown;
+    error?: EnvelopeError;
+}
 export interface ModuleInput {
     code?: string;
     query?: string;

package/dist/types.js

@@ -44,7 +44,10 @@ function aggregateRiskFromList(items) {
     }
     let maxLevel = 0;
     for (const item of items) {
-        const level = riskLevels[item.risk ?? 'medium'];
+        const riskKey = item.risk;
+        const level = typeof riskKey === 'string' && Object.prototype.hasOwnProperty.call(riskLevels, riskKey)
+            ? riskLevels[riskKey]
+            : riskLevels.medium;
         maxLevel = Math.max(maxLevel, level);
     }
     return riskNames[maxLevel];

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const VERSION = pkg.version ?? '0.0.0';

package/package.json

@@ -1,18 +1,32 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "2.2.0",
+  "version": "2.2.5",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "cognitive-modules-cli": "dist/cli.js",
     "cog": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc",
+    "clean": "node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"",
+    "build": "npm run clean && tsc",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",
-    "prepublishOnly": "npm run build"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "pack:check": "npm pack --dry-run --json --cache ../../.npm-cache",
+    "release:check": "npm run build && npm test && npm run pack:check",
+    "prepublishOnly": "npm run release:check"
   },
   "keywords": [
     "cognitive",
@@ -25,18 +39,28 @@
   ],
   "license": "MIT",
   "author": "ziel-io",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/ziel-io/cognitive-modules.git"
+    "url": "https://github.com/Cognary/cognitive.git"
   },
-  "homepage": "https://ziel-io.github.io/cognitive-modules/",
+  "homepage": "https://cognary.github.io/cognitive/",
   "bugs": {
-    "url": "https://github.com/ziel-io/cognitive-modules/issues"
+    "url": "https://github.com/Cognary/cognitive/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "ajv": "^8.12.0",
     "js-yaml": "^4.1.1"
   },
   "optionalDependencies": {
@@ -46,6 +70,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.0"
   }
 }