cognitive-modules-cli 2.2.1 → 2.2.5

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[];
@@ -222,14 +233,19 @@ export interface EnvelopeMeta {
 }
 /**
  * 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.g., "INVALID_INPUT", "PARSE_ERROR") */
+    /** 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 */
@@ -337,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.1",
+  "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,13 +39,22 @@
   ],
   "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"
@@ -47,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"
   }
 }

package/dist/modules/composition.test.d.ts

@@ -1,11 +0,0 @@
-/**
- * Tests for Composition Engine
- *
- * Tests all COMPOSITION.md specified functionality:
- * - JSONPath-like expression evaluation
- * - Condition expression evaluation
- * - Aggregation strategies
- * - Version matching
- * - Sequential, Parallel, Conditional, Iterative patterns
- */
-export {};

package/dist/modules/composition.test.js

@@ -1,450 +0,0 @@
-/**
- * Tests for Composition Engine
- *
- * Tests all COMPOSITION.md specified functionality:
- * - JSONPath-like expression evaluation
- * - Condition expression evaluation
- * - Aggregation strategies
- * - Version matching
- * - Sequential, Parallel, Conditional, Iterative patterns
- */
-import { describe, it, expect } from 'vitest';
-import { evaluateJsonPath, evaluateCondition, applyMapping, aggregateResults, versionMatches, validateCompositionConfig, } from './composition.js';
-// =============================================================================
-// JSONPath Expression Tests
-// =============================================================================
-describe('evaluateJsonPath', () => {
-    const testData = {
-        name: 'test',
-        nested: {
-            value: 42,
-            deep: {
-                array: [1, 2, 3]
-            }
-        },
-        items: [
-            { id: 1, name: 'a' },
-            { id: 2, name: 'b' },
-            { id: 3, name: 'c' }
-        ],
-        meta: {
-            confidence: 0.95,
-            risk: 'low'
-        },
-        // Test hyphenated field names (Bug fix)
-        'quick-check': {
-            meta: {
-                confidence: 0.85
-            },
-            data: {
-                result: 'success'
-            }
-        }
-    };
-    it('should return entire object for $', () => {
-        expect(evaluateJsonPath('$', testData)).toEqual(testData);
-    });
-    it('should access root field with $.field', () => {
-        expect(evaluateJsonPath('$.name', testData)).toBe('test');
-    });
-    it('should access nested field with $.nested.field', () => {
-        expect(evaluateJsonPath('$.nested.value', testData)).toBe(42);
-        expect(evaluateJsonPath('$.nested.deep.array', testData)).toEqual([1, 2, 3]);
-    });
-    it('should access array index with $.array[0]', () => {
-        expect(evaluateJsonPath('$.items[0]', testData)).toEqual({ id: 1, name: 'a' });
-        expect(evaluateJsonPath('$.items[1].name', testData)).toBe('b');
-        expect(evaluateJsonPath('$.nested.deep.array[2]', testData)).toBe(3);
-    });
-    it('should map over array with $.array[*].field', () => {
-        expect(evaluateJsonPath('$.items[*].name', testData)).toEqual(['a', 'b', 'c']);
-        expect(evaluateJsonPath('$.items[*].id', testData)).toEqual([1, 2, 3]);
-    });
-    it('should return undefined for non-existent paths', () => {
-        expect(evaluateJsonPath('$.nonexistent', testData)).toBeUndefined();
-        expect(evaluateJsonPath('$.nested.nonexistent', testData)).toBeUndefined();
-        expect(evaluateJsonPath('$.items[99]', testData)).toBeUndefined();
-    });
-    it('should return literal values for non-JSONPath strings', () => {
-        expect(evaluateJsonPath('literal', testData)).toBe('literal');
-        expect(evaluateJsonPath('123', testData)).toBe('123');
-    });
-    it('should handle hyphenated field names', () => {
-        expect(evaluateJsonPath('$.quick-check.meta.confidence', testData)).toBe(0.85);
-        expect(evaluateJsonPath('$.quick-check.data.result', testData)).toBe('success');
-    });
-});
-// =============================================================================
-// Condition Expression Tests
-// =============================================================================
-describe('evaluateCondition', () => {
-    const testData = {
-        meta: {
-            confidence: 0.85,
-            risk: 'low'
-        },
-        data: {
-            count: 5,
-            items: [1, 2, 3],
-            name: 'test module'
-        }
-    };
-    describe('comparison operators', () => {
-        it('should evaluate > operator', () => {
-            expect(evaluateCondition('$.meta.confidence > 0.7', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.confidence > 0.9', testData)).toBe(false);
-        });
-        it('should evaluate < operator', () => {
-            expect(evaluateCondition('$.meta.confidence < 0.9', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.confidence < 0.5', testData)).toBe(false);
-        });
-        it('should evaluate >= operator', () => {
-            expect(evaluateCondition('$.meta.confidence >= 0.85', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.confidence >= 0.9', testData)).toBe(false);
-        });
-        it('should evaluate <= operator', () => {
-            expect(evaluateCondition('$.meta.confidence <= 0.85', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.confidence <= 0.5', testData)).toBe(false);
-        });
-        it('should evaluate == operator', () => {
-            expect(evaluateCondition('$.meta.risk == "low"', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.risk == "high"', testData)).toBe(false);
-            expect(evaluateCondition('$.data.count == 5', testData)).toBe(true);
-        });
-        it('should evaluate != operator', () => {
-            expect(evaluateCondition('$.meta.risk != "high"', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.risk != "low"', testData)).toBe(false);
-        });
-    });
-    describe('logical operators', () => {
-        it('should evaluate && operator', () => {
-            expect(evaluateCondition('$.meta.confidence > 0.7 && $.meta.risk == "low"', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.confidence > 0.9 && $.meta.risk == "low"', testData)).toBe(false);
-        });
-        it('should evaluate || operator', () => {
-            expect(evaluateCondition('$.meta.confidence > 0.9 || $.meta.risk == "low"', testData)).toBe(true);
-            expect(evaluateCondition('$.meta.confidence > 0.9 || $.meta.risk == "high"', testData)).toBe(false);
-        });
-        it('should evaluate ! operator', () => {
-            expect(evaluateCondition('!false', {})).toBe(true);
-            expect(evaluateCondition('!true', {})).toBe(false);
-        });
-    });
-    describe('special functions', () => {
-        it('should evaluate exists() function', () => {
-            expect(evaluateCondition('exists($.meta.confidence)', testData)).toBe(true);
-            expect(evaluateCondition('exists($.meta.nonexistent)', testData)).toBe(false);
-        });
-        it('should evaluate .length property', () => {
-            expect(evaluateCondition('$.data.items.length > 0', testData)).toBe(true);
-            expect(evaluateCondition('$.data.items.length == 3', testData)).toBe(true);
-        });
-        it('should evaluate contains() for strings', () => {
-            expect(evaluateCondition('contains($.data.name, "test")', testData)).toBe(true);
-            expect(evaluateCondition('contains($.data.name, "xyz")', testData)).toBe(false);
-        });
-        it('should evaluate contains() for arrays', () => {
-            const dataWithArray = {
-                tags: ['javascript', 'typescript', 'node']
-            };
-            expect(evaluateCondition('contains($.tags, "typescript")', dataWithArray)).toBe(true);
-            expect(evaluateCondition('contains($.tags, "python")', dataWithArray)).toBe(false);
-        });
-    });
-    describe('hyphenated field names', () => {
-        const hyphenData = {
-            'quick-check': {
-                meta: { confidence: 0.85 },
-                data: { result: 'success' }
-            }
-        };
-        it('should handle hyphenated field names in conditions', () => {
-            expect(evaluateCondition('$.quick-check.meta.confidence > 0.8', hyphenData)).toBe(true);
-            expect(evaluateCondition('$.quick-check.meta.confidence > 0.9', hyphenData)).toBe(false);
-        });
-        it('should handle hyphenated fields with string comparison', () => {
-            expect(evaluateCondition('$.quick-check.data.result == "success"', hyphenData)).toBe(true);
-        });
-    });
-});
-// =============================================================================
-// Dataflow Mapping Tests
-// =============================================================================
-describe('applyMapping', () => {
-    const sourceData = {
-        code: 'function test() {}',
-        language: 'javascript',
-        nested: {
-            value: 42
-        }
-    };
-    it('should map simple fields', () => {
-        const mapping = {
-            source_code: '$.code',
-            lang: '$.language'
-        };
-        const result = applyMapping(mapping, sourceData);
-        expect(result.source_code).toBe('function test() {}');
-        expect(result.lang).toBe('javascript');
-    });
-    it('should map nested fields', () => {
-        const mapping = {
-            extracted_value: '$.nested.value'
-        };
-        const result = applyMapping(mapping, sourceData);
-        expect(result.extracted_value).toBe(42);
-    });
-    it('should handle missing fields', () => {
-        const mapping = {
-            missing: '$.nonexistent'
-        };
-        const result = applyMapping(mapping, sourceData);
-        expect(result.missing).toBeUndefined();
-    });
-    it('should pass through entire object with $', () => {
-        const mapping = {
-            all: '$'
-        };
-        const result = applyMapping(mapping, sourceData);
-        expect(result.all).toEqual(sourceData);
-    });
-});
-// =============================================================================
-// Aggregation Strategy Tests
-// =============================================================================
-describe('aggregateResults', () => {
-    const createResult = (data, confidence, risk) => ({
-        ok: true,
-        meta: {
-            confidence,
-            risk: risk,
-            explain: 'Test result'
-        },
-        data: {
-            ...data,
-            rationale: 'Test rationale'
-        }
-    });
-    const results = [
-        createResult({ field1: 'value1', common: 'first' }, 0.8, 'low'),
-        createResult({ field2: 'value2', common: 'second' }, 0.9, 'medium'),
-        createResult({ field3: 'value3', common: 'third' }, 0.7, 'none')
-    ];
-    describe('merge strategy', () => {
-        it('should deep merge all results (later wins)', () => {
-            const merged = aggregateResults(results, 'merge');
-            expect(merged.ok).toBe(true);
-            expect(merged.data.field1).toBe('value1');
-            expect(merged.data.field2).toBe('value2');
-            expect(merged.data.field3).toBe('value3');
-            expect(merged.data.common).toBe('third'); // Last wins
-        });
-        it('should aggregate meta values', () => {
-            const merged = aggregateResults(results, 'merge');
-            // Average confidence
-            expect(merged.meta.confidence).toBeCloseTo(0.8, 1);
-            // Max risk
-            expect(merged.meta.risk).toBe('medium');
-        });
-    });
-    describe('array strategy', () => {
-        it('should collect all results into array', () => {
-            const collected = aggregateResults(results, 'array');
-            expect(collected.ok).toBe(true);
-            const data = collected.data;
-            expect(data.results).toHaveLength(3);
-        });
-    });
-    describe('first strategy', () => {
-        it('should return first successful result', () => {
-            const first = aggregateResults(results, 'first');
-            expect(first.ok).toBe(true);
-            expect(first.data.field1).toBe('value1');
-        });
-        it('should skip failed results', () => {
-            const mixedResults = [
-                {
-                    ok: false,
-                    meta: { confidence: 0, risk: 'high', explain: 'Failed' },
-                    error: { code: 'E1000', message: 'Error' }
-                },
-                createResult({ success: true }, 0.9, 'low')
-            ];
-            const first = aggregateResults(mixedResults, 'first');
-            expect(first.ok).toBe(true);
-            expect(first.data.success).toBe(true);
-        });
-    });
-    describe('edge cases', () => {
-        it('should return error for empty results', () => {
-            const empty = aggregateResults([], 'merge');
-            expect(empty.ok).toBe(false);
-        });
-        it('should return single result unchanged', () => {
-            const single = aggregateResults([results[0]], 'merge');
-            expect(single).toEqual(results[0]);
-        });
-    });
-});
-// =============================================================================
-// Version Matching Tests
-// =============================================================================
-describe('versionMatches', () => {
-    describe('exact version', () => {
-        it('should match exact version', () => {
-            expect(versionMatches('1.0.0', '1.0.0')).toBe(true);
-            expect(versionMatches('1.0.0', '1.0.1')).toBe(false);
-            expect(versionMatches('2.0.0', '1.0.0')).toBe(false);
-        });
-    });
-    describe('wildcard (*)', () => {
-        it('should match any version with *', () => {
-            expect(versionMatches('1.0.0', '*')).toBe(true);
-            expect(versionMatches('99.99.99', '*')).toBe(true);
-        });
-        it('should match any version with empty pattern', () => {
-            expect(versionMatches('1.0.0', '')).toBe(true);
-        });
-    });
-    describe('>= operator', () => {
-        it('should match versions greater than or equal', () => {
-            expect(versionMatches('1.0.0', '>=1.0.0')).toBe(true);
-            expect(versionMatches('1.1.0', '>=1.0.0')).toBe(true);
-            expect(versionMatches('2.0.0', '>=1.0.0')).toBe(true);
-            expect(versionMatches('0.9.0', '>=1.0.0')).toBe(false);
-        });
-    });
-    describe('> operator', () => {
-        it('should match versions strictly greater', () => {
-            expect(versionMatches('1.0.1', '>1.0.0')).toBe(true);
-            expect(versionMatches('1.1.0', '>1.0.0')).toBe(true);
-            expect(versionMatches('1.0.0', '>1.0.0')).toBe(false);
-        });
-    });
-    describe('^ (caret) operator', () => {
-        it('should match same major version', () => {
-            expect(versionMatches('1.2.3', '^1.0.0')).toBe(true);
-            expect(versionMatches('1.0.0', '^1.0.0')).toBe(true);
-            expect(versionMatches('2.0.0', '^1.0.0')).toBe(false);
-            expect(versionMatches('0.9.0', '^1.0.0')).toBe(false);
-        });
-    });
-    describe('~ (tilde) operator', () => {
-        it('should match same major.minor version', () => {
-            expect(versionMatches('1.0.5', '~1.0.0')).toBe(true);
-            expect(versionMatches('1.0.0', '~1.0.0')).toBe(true);
-            expect(versionMatches('1.1.0', '~1.0.0')).toBe(false);
-            expect(versionMatches('2.0.0', '~1.0.0')).toBe(false);
-        });
-    });
-});
-// =============================================================================
-// Composition Config Validation Tests
-// =============================================================================
-describe('validateCompositionConfig', () => {
-    it('should validate correct sequential config', () => {
-        const config = {
-            pattern: 'sequential',
-            requires: [{ name: 'module-a' }],
-            dataflow: [
-                { from: 'input', to: 'module-a' },
-                { from: 'module-a.output', to: 'output' }
-            ]
-        };
-        const result = validateCompositionConfig(config);
-        expect(result.valid).toBe(true);
-        expect(result.errors).toHaveLength(0);
-    });
-    it('should validate correct parallel config', () => {
-        const config = {
-            pattern: 'parallel',
-            requires: [
-                { name: 'module-a' },
-                { name: 'module-b' }
-            ],
-            dataflow: [
-                { from: 'input', to: ['module-a', 'module-b'] },
-                { from: ['module-a.output', 'module-b.output'], to: 'output', aggregate: 'merge' }
-            ]
-        };
-        const result = validateCompositionConfig(config);
-        expect(result.valid).toBe(true);
-    });
-    it('should require routing rules for conditional pattern', () => {
-        const config = {
-            pattern: 'conditional',
-            dataflow: [{ from: 'input', to: 'module-a' }]
-        };
-        const result = validateCompositionConfig(config);
-        expect(result.valid).toBe(false);
-        expect(result.errors.some(e => e.includes('routing'))).toBe(true);
-    });
-    it('should require iteration config for iterative pattern', () => {
-        const config = {
-            pattern: 'iterative',
-            dataflow: [{ from: 'input', to: 'module-a' }]
-        };
-        const result = validateCompositionConfig(config);
-        expect(result.valid).toBe(false);
-        expect(result.errors.some(e => e.includes('continue_condition') || e.includes('stop_condition'))).toBe(true);
-    });
-    it('should validate correct iterative config', () => {
-        const config = {
-            pattern: 'iterative',
-            iteration: {
-                max_iterations: 10,
-                stop_condition: '$.meta.confidence > 0.9'
-            }
-        };
-        const result = validateCompositionConfig(config);
-        expect(result.valid).toBe(true);
-    });
-    it('should detect invalid pattern', () => {
-        const config = {
-            pattern: 'invalid',
-            dataflow: []
-        };
-        const result = validateCompositionConfig(config);
-        expect(result.valid).toBe(false);
-        expect(result.errors.some(e => e.includes('Invalid pattern'))).toBe(true);
-    });
-    it('should detect missing dataflow fields', () => {
-        const config = {
-            pattern: 'sequential',
-            dataflow: [
-                { from: 'input' },
-            ]
-        };
-        const result = validateCompositionConfig(config);
-        expect(result.valid).toBe(false);
-        expect(result.errors.some(e => e.includes("missing 'to'"))).toBe(true);
-    });
-});
-// =============================================================================
-// Integration Test Placeholders
-// =============================================================================
-describe('CompositionOrchestrator', () => {
-    // Note: Full integration tests require mocking Provider and modules
-    // These are placeholder tests that should be expanded with proper mocks
-    it.skip('should execute sequential composition', async () => {
-        // TODO: Add integration test with mocked provider
-    });
-    it.skip('should execute parallel composition', async () => {
-        // TODO: Add integration test with mocked provider
-    });
-    it.skip('should execute conditional composition', async () => {
-        // TODO: Add integration test with mocked provider
-    });
-    it.skip('should execute iterative composition', async () => {
-        // TODO: Add integration test with mocked provider
-    });
-    it.skip('should handle timeouts', async () => {
-        // TODO: Add timeout test
-    });
-    it.skip('should detect circular dependencies', async () => {
-        // TODO: Add circular dependency test
-    });
-    it.skip('should use fallback modules', async () => {
-        // TODO: Add fallback test
-    });
-});

package/dist/modules/policy.test.d.ts

@@ -1,10 +0,0 @@
-/**
- * Tests for Policy Enforcement
- *
- * Tests all policy enforcement functionality:
- * - Tool policy checking (allowed/denied lists)
- * - General policy checking (network, filesystem, etc.)
- * - Tool call interception
- * - Policy-aware executors
- */
-export {};