cognitive-modules-cli 2.2.0 → 2.2.1

package/dist/modules/loader.js

@@ -1,6 +1,6 @@
 /**
  * Module Loader - Load and parse Cognitive Modules
- * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
+ * Supports v0 (6-file), v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
@@ -11,12 +11,26 @@ const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
  */
 async function detectFormat(modulePath) {
     const v2Manifest = path.join(modulePath, 'module.yaml');
+    const v1Module = path.join(modulePath, 'MODULE.md');
+    const v0Module = path.join(modulePath, 'module.md');
     try {
         await fs.access(v2Manifest);
         return 'v2';
     }
     catch {
-        return 'v1';
+        try {
+            await fs.access(v1Module);
+            return 'v1';
+        }
+        catch {
+            try {
+                await fs.access(v0Module);
+                return 'v0';
+            }
+            catch {
+                throw new Error(`No module.yaml, MODULE.md, or module.md found in ${modulePath}`);
+            }
+        }
     }
 }
 /**
@@ -114,6 +128,54 @@ async function loadModuleV2(modulePath) {
         required: metaRaw.required,
         risk_rule: validatedRiskRule,
     };
+    // Parse composition config (v2.2)
+    const compositionRaw = manifest.composition;
+    let composition;
+    if (compositionRaw) {
+        // Parse pattern
+        const pattern = compositionRaw.pattern ?? 'sequential';
+        // Parse requires (dependencies)
+        const requiresRaw = compositionRaw.requires;
+        const requires = requiresRaw?.map(dep => ({
+            name: dep.name,
+            version: dep.version,
+            optional: dep.optional,
+            fallback: dep.fallback,
+            timeout_ms: dep.timeout_ms
+        }));
+        // Parse dataflow
+        const dataflowRaw = compositionRaw.dataflow;
+        const dataflow = dataflowRaw?.map(step => ({
+            from: step.from,
+            to: step.to,
+            mapping: step.mapping,
+            condition: step.condition,
+            aggregate: step.aggregate,
+            aggregator: step.aggregator
+        }));
+        // Parse routing rules
+        const routingRaw = compositionRaw.routing;
+        const routing = routingRaw?.map(rule => ({
+            condition: rule.condition,
+            next: rule.next
+        }));
+        // Parse iteration config
+        const iterationRaw = compositionRaw.iteration;
+        const iteration = iterationRaw ? {
+            max_iterations: iterationRaw.max_iterations,
+            continue_condition: iterationRaw.continue_condition,
+            stop_condition: iterationRaw.stop_condition
+        } : undefined;
+        composition = {
+            pattern,
+            requires,
+            dataflow,
+            routing,
+            max_depth: compositionRaw.max_depth,
+            timeout_ms: compositionRaw.timeout_ms,
+            iteration
+        };
+    }
     return {
         name: manifest.name || path.basename(modulePath),
         version: manifest.version || '1.0.0',
@@ -132,6 +194,7 @@ async function loadModuleV2(modulePath) {
         enums,
         compat,
         metaConfig,
+        composition,
         // Context and prompt
         context: manifest.context,
         prompt,
@@ -196,6 +259,63 @@ async function loadModuleV1(modulePath) {
         format: 'v1',
     };
 }
+/**
+ * Load v0 format module (6-file format - deprecated)
+ */
+async function loadModuleV0(modulePath) {
+    // Read module.md
+    const moduleFile = path.join(modulePath, 'module.md');
+    const moduleContent = await fs.readFile(moduleFile, 'utf-8');
+    // Parse frontmatter
+    const match = moduleContent.match(FRONTMATTER_REGEX);
+    if (!match) {
+        throw new Error(`Invalid module.md: missing YAML frontmatter in ${moduleFile}`);
+    }
+    const metadata = yaml.load(match[1]);
+    // Read schemas
+    const inputSchemaFile = path.join(modulePath, 'input.schema.json');
+    const outputSchemaFile = path.join(modulePath, 'output.schema.json');
+    const constraintsFile = path.join(modulePath, 'constraints.yaml');
+    const promptFile = path.join(modulePath, 'prompt.txt');
+    const inputSchemaContent = await fs.readFile(inputSchemaFile, 'utf-8');
+    const inputSchema = JSON.parse(inputSchemaContent);
+    const outputSchemaContent = await fs.readFile(outputSchemaFile, 'utf-8');
+    const outputSchema = JSON.parse(outputSchemaContent);
+    // Load constraints
+    const constraintsContent = await fs.readFile(constraintsFile, 'utf-8');
+    const constraintsRaw = yaml.load(constraintsContent);
+    // Load prompt
+    const prompt = await fs.readFile(promptFile, 'utf-8');
+    // Extract constraints
+    const constraints = {};
+    if (constraintsRaw) {
+        const operational = constraintsRaw.operational ?? {};
+        constraints.no_network = operational.no_external_network;
+        constraints.no_side_effects = operational.no_side_effects;
+        constraints.no_file_write = operational.no_file_write;
+        constraints.no_inventing_data = operational.no_inventing_data;
+    }
+    return {
+        name: metadata.name || path.basename(modulePath),
+        version: metadata.version || '1.0.0',
+        responsibility: metadata.responsibility || '',
+        excludes: metadata.excludes || [],
+        constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
+        prompt,
+        inputSchema,
+        outputSchema,
+        dataSchema: outputSchema, // Alias for v2.2 compat
+        // v2.2 defaults for v0 modules
+        schemaStrictness: 'medium',
+        overflow: { enabled: false },
+        enums: { strategy: 'strict' },
+        compat: { accepts_v21_payload: true, runtime_auto_wrap: true },
+        // Metadata
+        location: modulePath,
+        format: 'v0',
+        formatVersion: 'v0.0',
+    };
+}
 /**
  * Load a Cognitive Module (auto-detects format)
  */
@@ -204,9 +324,12 @@ export async function loadModule(modulePath) {
     if (format === 'v2') {
         return loadModuleV2(modulePath);
     }
-    else {
+    else if (format === 'v1') {
         return loadModuleV1(modulePath);
     }
+    else {
+        return loadModuleV0(modulePath);
+    }
 }
 /**
  * Check if a directory contains a valid module
@@ -214,6 +337,7 @@ export async function loadModule(modulePath) {
 async function isValidModule(modulePath) {
     const v2Manifest = path.join(modulePath, 'module.yaml');
     const v1Module = path.join(modulePath, 'MODULE.md');
+    const v0Module = path.join(modulePath, 'module.md');
     try {
         await fs.access(v2Manifest);
         return true;
@@ -224,7 +348,13 @@ async function isValidModule(modulePath) {
             return true;
         }
         catch {
-            return false;
+            try {
+                await fs.access(v0Module);
+                return true;
+            }
+            catch {
+                return false;
+            }
         }
     }
 }
@@ -271,3 +401,36 @@ export function getDefaultSearchPaths(cwd) {
         path.join(home, '.cognitive', 'modules'),
     ];
 }
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Get module tier (exec, decision, exploration).
+ */
+export function getModuleTier(module) {
+    return module.tier;
+}
+/**
+ * Get schema strictness level.
+ */
+export function getSchemaStrictness(module) {
+    return module.schemaStrictness ?? 'medium';
+}
+/**
+ * Check if overflow (extensions.insights) is enabled.
+ */
+export function isOverflowEnabled(module) {
+    return module.overflow?.enabled ?? false;
+}
+/**
+ * Get enum extension strategy.
+ */
+export function getEnumStrategy(module) {
+    return module.enums?.strategy ?? 'strict';
+}
+/**
+ * Check if runtime should auto-wrap v2.1 to v2.2.
+ */
+export function shouldAutoWrap(module) {
+    return module.compat?.runtime_auto_wrap ?? true;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * 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 {};

package/dist/modules/policy.test.js

@@ -0,0 +1,369 @@
+/**
+ * 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
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { checkToolPolicy, checkPolicy, checkToolAllowed, validateToolsAllowed, getDeniedActions, getDeniedTools, getAllowedTools, ToolCallInterceptor, createPolicyAwareExecutor, } from './runner.js';
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+function createMockModule(overrides = {}) {
+    return {
+        name: 'test-module',
+        version: '1.0.0',
+        responsibility: 'Test module',
+        excludes: [],
+        prompt: 'Test prompt',
+        location: '/test',
+        format: 'v2',
+        ...overrides,
+    };
+}
+// =============================================================================
+// checkToolPolicy Tests
+// =============================================================================
+describe('checkToolPolicy', () => {
+    it('should allow all tools when no policy defined', () => {
+        const module = createMockModule();
+        expect(checkToolPolicy('write_file', module).allowed).toBe(true);
+        expect(checkToolPolicy('shell', module).allowed).toBe(true);
+        expect(checkToolPolicy('any_tool', module).allowed).toBe(true);
+    });
+    it('should deny tools in denied list', () => {
+        const module = createMockModule({
+            tools: {
+                policy: 'allow_by_default',
+                allowed: [],
+                denied: ['write_file', 'shell', 'network'],
+            },
+        });
+        const result = checkToolPolicy('write_file', module);
+        expect(result.allowed).toBe(false);
+        expect(result.reason).toContain('explicitly denied');
+        expect(result.policy).toBe('tools.denied');
+    });
+    it('should handle case-insensitive tool names', () => {
+        const module = createMockModule({
+            tools: {
+                policy: 'allow_by_default',
+                allowed: [],
+                denied: ['Write_File'],
+            },
+        });
+        expect(checkToolPolicy('write_file', module).allowed).toBe(false);
+        expect(checkToolPolicy('WRITE_FILE', module).allowed).toBe(false);
+        expect(checkToolPolicy('write-file', module).allowed).toBe(false);
+    });
+    it('should enforce deny_by_default policy', () => {
+        const module = createMockModule({
+            tools: {
+                policy: 'deny_by_default',
+                allowed: ['read_file', 'list_dir'],
+            },
+        });
+        expect(checkToolPolicy('read_file', module).allowed).toBe(true);
+        expect(checkToolPolicy('list_dir', module).allowed).toBe(true);
+        const result = checkToolPolicy('write_file', module);
+        expect(result.allowed).toBe(false);
+        expect(result.reason).toContain('not in allowed list');
+        expect(result.policy).toBe('tools.policy');
+    });
+    it('should allow tools in allow_by_default mode (not in denied)', () => {
+        const module = createMockModule({
+            tools: {
+                policy: 'allow_by_default',
+                allowed: [],
+                denied: ['shell'],
+            },
+        });
+        expect(checkToolPolicy('read_file', module).allowed).toBe(true);
+        expect(checkToolPolicy('write_file', module).allowed).toBe(true);
+        expect(checkToolPolicy('shell', module).allowed).toBe(false);
+    });
+});
+// =============================================================================
+// checkPolicy Tests
+// =============================================================================
+describe('checkPolicy', () => {
+    it('should allow all actions when no policies defined', () => {
+        const module = createMockModule();
+        expect(checkPolicy('network', module).allowed).toBe(true);
+        expect(checkPolicy('filesystem_write', module).allowed).toBe(true);
+        expect(checkPolicy('side_effects', module).allowed).toBe(true);
+        expect(checkPolicy('code_execution', module).allowed).toBe(true);
+    });
+    it('should deny actions marked as deny', () => {
+        const module = createMockModule({
+            policies: {
+                network: 'deny',
+                filesystem_write: 'deny',
+                side_effects: 'allow',
+                code_execution: 'deny',
+            },
+        });
+        const networkResult = checkPolicy('network', module);
+        expect(networkResult.allowed).toBe(false);
+        expect(networkResult.reason).toContain("'network' is denied");
+        expect(networkResult.policy).toBe('policies.network');
+        expect(checkPolicy('filesystem_write', module).allowed).toBe(false);
+        expect(checkPolicy('side_effects', module).allowed).toBe(true);
+        expect(checkPolicy('code_execution', module).allowed).toBe(false);
+    });
+});
+// =============================================================================
+// checkToolAllowed Tests (Combined Check)
+// =============================================================================
+describe('checkToolAllowed', () => {
+    it('should check both tool policy and general policies', () => {
+        const module = createMockModule({
+            policies: {
+                filesystem_write: 'deny',
+                side_effects: 'deny',
+            },
+            tools: {
+                policy: 'allow_by_default',
+                allowed: [],
+            },
+        });
+        // write_file maps to filesystem_write and side_effects
+        const result = checkToolAllowed('write_file', module);
+        expect(result.allowed).toBe(false);
+        expect(result.reason).toContain('filesystem_write');
+    });
+    it('should block tools that require denied actions', () => {
+        const module = createMockModule({
+            policies: {
+                network: 'deny',
+            },
+        });
+        // Network tools should be blocked
+        expect(checkToolAllowed('fetch', module).allowed).toBe(false);
+        expect(checkToolAllowed('http', module).allowed).toBe(false);
+        expect(checkToolAllowed('curl', module).allowed).toBe(false);
+        // Non-network tools should be allowed
+        expect(checkToolAllowed('read_file', module).allowed).toBe(true);
+    });
+    it('should block shell/exec when code_execution denied', () => {
+        const module = createMockModule({
+            policies: {
+                code_execution: 'deny',
+            },
+        });
+        expect(checkToolAllowed('shell', module).allowed).toBe(false);
+        expect(checkToolAllowed('exec', module).allowed).toBe(false);
+        expect(checkToolAllowed('code_interpreter', module).allowed).toBe(false);
+    });
+    it('should check explicit tools policy first', () => {
+        const module = createMockModule({
+            policies: {
+                network: 'allow', // Allow network in general
+            },
+            tools: {
+                policy: 'allow_by_default',
+                allowed: [],
+                denied: ['fetch'], // But explicitly deny fetch
+            },
+        });
+        const result = checkToolAllowed('fetch', module);
+        expect(result.allowed).toBe(false);
+        expect(result.policy).toBe('tools.denied');
+    });
+});
+// =============================================================================
+// validateToolsAllowed Tests
+// =============================================================================
+describe('validateToolsAllowed', () => {
+    it('should return empty array when all tools allowed', () => {
+        const module = createMockModule();
+        const violations = validateToolsAllowed(['read_file', 'write_file', 'shell'], module);
+        expect(violations).toHaveLength(0);
+    });
+    it('should return all violations', () => {
+        const module = createMockModule({
+            policies: {
+                network: 'deny',
+                code_execution: 'deny',
+            },
+        });
+        const violations = validateToolsAllowed(['fetch', 'shell', 'read_file'], module);
+        expect(violations).toHaveLength(2);
+        expect(violations.some(v => v.reason?.includes('fetch'))).toBe(true);
+        expect(violations.some(v => v.reason?.includes('shell'))).toBe(true);
+    });
+});
+// =============================================================================
+// Helper Functions Tests
+// =============================================================================
+describe('getDeniedActions', () => {
+    it('should return list of denied actions', () => {
+        const module = createMockModule({
+            policies: {
+                network: 'deny',
+                filesystem_write: 'deny',
+                side_effects: 'allow',
+            },
+        });
+        const denied = getDeniedActions(module);
+        expect(denied).toContain('network');
+        expect(denied).toContain('filesystem_write');
+        expect(denied).not.toContain('side_effects');
+    });
+    it('should return empty array when no policies', () => {
+        const module = createMockModule();
+        expect(getDeniedActions(module)).toHaveLength(0);
+    });
+});
+describe('getDeniedTools', () => {
+    it('should return denied tools list', () => {
+        const module = createMockModule({
+            tools: {
+                policy: 'allow_by_default',
+                allowed: [],
+                denied: ['shell', 'network', 'write_file'],
+            },
+        });
+        const denied = getDeniedTools(module);
+        expect(denied).toContain('shell');
+        expect(denied).toContain('network');
+        expect(denied).toContain('write_file');
+    });
+});
+describe('getAllowedTools', () => {
+    it('should return null for allow_by_default', () => {
+        const module = createMockModule({
+            tools: {
+                policy: 'allow_by_default',
+                allowed: ['read_file'],
+            },
+        });
+        expect(getAllowedTools(module)).toBeNull();
+    });
+    it('should return allowed list for deny_by_default', () => {
+        const module = createMockModule({
+            tools: {
+                policy: 'deny_by_default',
+                allowed: ['read_file', 'list_dir'],
+            },
+        });
+        const allowed = getAllowedTools(module);
+        expect(allowed).toEqual(['read_file', 'list_dir']);
+    });
+});
+// =============================================================================
+// ToolCallInterceptor Tests
+// =============================================================================
+describe('ToolCallInterceptor', () => {
+    let module;
+    let interceptor;
+    beforeEach(() => {
+        module = createMockModule({
+            policies: {
+                network: 'deny',
+                filesystem_write: 'deny',
+            },
+            tools: {
+                policy: 'deny_by_default',
+                allowed: ['read_file', 'list_dir'],
+            },
+        });
+        interceptor = new ToolCallInterceptor(module);
+    });
+    it('should check if tool is allowed', () => {
+        expect(interceptor.checkAllowed('read_file').allowed).toBe(true);
+        expect(interceptor.checkAllowed('write_file').allowed).toBe(false);
+        expect(interceptor.checkAllowed('fetch').allowed).toBe(false);
+    });
+    it('should execute allowed tool', async () => {
+        const mockExecutor = vi.fn().mockResolvedValue('file content');
+        interceptor.registerTool('read_file', mockExecutor);
+        const result = await interceptor.execute({
+            name: 'read_file',
+            arguments: { path: '/test.txt' },
+        });
+        expect(result.success).toBe(true);
+        expect(result.result).toBe('file content');
+        expect(mockExecutor).toHaveBeenCalledWith({ path: '/test.txt' });
+    });
+    it('should block denied tool', async () => {
+        const mockExecutor = vi.fn().mockResolvedValue('done');
+        interceptor.registerTool('write_file', mockExecutor);
+        const result = await interceptor.execute({
+            name: 'write_file',
+            arguments: { path: '/test.txt', content: 'hello' },
+        });
+        expect(result.success).toBe(false);
+        expect(result.error?.code).toBe('TOOL_NOT_ALLOWED');
+        expect(mockExecutor).not.toHaveBeenCalled();
+    });
+    it('should log all calls', async () => {
+        interceptor.registerTool('read_file', vi.fn().mockResolvedValue('ok'));
+        interceptor.registerTool('write_file', vi.fn().mockResolvedValue('ok'));
+        await interceptor.execute({ name: 'read_file', arguments: {} });
+        await interceptor.execute({ name: 'write_file', arguments: {} });
+        await interceptor.execute({ name: 'read_file', arguments: {} });
+        const log = interceptor.getCallLog();
+        expect(log).toHaveLength(3);
+        expect(log[0].tool).toBe('read_file');
+        expect(log[0].allowed).toBe(true);
+        expect(log[1].tool).toBe('write_file');
+        expect(log[1].allowed).toBe(false);
+    });
+    it('should get denied calls', async () => {
+        interceptor.registerTool('read_file', vi.fn().mockResolvedValue('ok'));
+        await interceptor.execute({ name: 'read_file', arguments: {} });
+        await interceptor.execute({ name: 'write_file', arguments: {} });
+        await interceptor.execute({ name: 'shell', arguments: {} });
+        const denied = interceptor.getDeniedCalls();
+        expect(denied).toHaveLength(2);
+        expect(denied.some(d => d.tool === 'write_file')).toBe(true);
+        expect(denied.some(d => d.tool === 'shell')).toBe(true);
+    });
+    it('should execute many and stop on policy violation', async () => {
+        interceptor.registerTool('read_file', vi.fn().mockResolvedValue('ok'));
+        interceptor.registerTool('list_dir', vi.fn().mockResolvedValue(['a', 'b']));
+        const results = await interceptor.executeMany([
+            { name: 'read_file', arguments: {} },
+            { name: 'write_file', arguments: {} }, // Blocked
+            { name: 'list_dir', arguments: {} }, // Should not execute
+        ]);
+        expect(results).toHaveLength(2);
+        expect(results[0].success).toBe(true);
+        expect(results[1].success).toBe(false);
+    });
+    it('should provide policy summary', () => {
+        const summary = interceptor.getPolicySummary();
+        expect(summary.deniedActions).toContain('network');
+        expect(summary.deniedActions).toContain('filesystem_write');
+        expect(summary.allowedTools).toEqual(['read_file', 'list_dir']);
+        expect(summary.toolsPolicy).toBe('deny_by_default');
+    });
+});
+// =============================================================================
+// createPolicyAwareExecutor Tests
+// =============================================================================
+describe('createPolicyAwareExecutor', () => {
+    it('should execute allowed tool', async () => {
+        const module = createMockModule();
+        const executor = vi.fn().mockResolvedValue('result');
+        const safeExecutor = createPolicyAwareExecutor(module, 'read_file', executor);
+        const result = await safeExecutor({ path: '/test.txt' });
+        expect(result).toBe('result');
+        expect(executor).toHaveBeenCalledWith({ path: '/test.txt' });
+    });
+    it('should throw on policy violation', async () => {
+        const module = createMockModule({
+            policies: {
+                filesystem_write: 'deny',
+            },
+        });
+        const executor = vi.fn().mockResolvedValue('result');
+        const safeExecutor = createPolicyAwareExecutor(module, 'write_file', executor);
+        await expect(safeExecutor({ path: '/test.txt' })).rejects.toThrow('Policy violation');
+        expect(executor).not.toHaveBeenCalled();
+    });
+});