cognitive-modules-cli 2.2.0 → 2.2.5

package/dist/modules/index.d.ts

@@ -4,3 +4,5 @@
 export * from './loader.js';
 export * from './runner.js';
 export * from './subagent.js';
+export * from './validator.js';
+export * from './composition.js';

package/dist/modules/index.js

@@ -4,3 +4,5 @@
 export * from './loader.js';
 export * from './runner.js';
 export * from './subagent.js';
+export * from './validator.js';
+export * from './composition.js';

package/dist/modules/loader.d.ts

@@ -1,8 +1,8 @@
 /**
  * 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 type { CognitiveModule } from '../types.js';
+import type { CognitiveModule, ModuleTier, SchemaStrictness } from '../types.js';
 /**
  * Load a Cognitive Module (auto-detects format)
  */
@@ -10,3 +10,23 @@ export declare function loadModule(modulePath: string): Promise<CognitiveModule>
 export declare function findModule(name: string, searchPaths: string[]): Promise<CognitiveModule | null>;
 export declare function listModules(searchPaths: string[]): Promise<CognitiveModule[]>;
 export declare function getDefaultSearchPaths(cwd: string): string[];
+/**
+ * Get module tier (exec, decision, exploration).
+ */
+export declare function getModuleTier(module: CognitiveModule): ModuleTier | undefined;
+/**
+ * Get schema strictness level.
+ */
+export declare function getSchemaStrictness(module: CognitiveModule): SchemaStrictness;
+/**
+ * Check if overflow (extensions.insights) is enabled.
+ */
+export declare function isOverflowEnabled(module: CognitiveModule): boolean;
+/**
+ * Get enum extension strategy.
+ */
+export declare function getEnumStrategy(module: CognitiveModule): 'strict' | 'extensible';
+/**
+ * Check if runtime should auto-wrap v2.1 to v2.2.
+ */
+export declare function shouldAutoWrap(module: CognitiveModule): boolean;

package/dist/modules/loader.js

@@ -1,9 +1,10 @@
 /**
  * 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';
+import { homedir } from 'node:os';
 import yaml from 'js-yaml';
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
 /**
@@ -11,12 +12,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}`);
+            }
+        }
     }
 }
 /**
@@ -40,7 +55,8 @@ async function loadModuleV2(modulePath) {
     const schemaFile = path.join(modulePath, 'schema.json');
     // Read module.yaml
     const manifestContent = await fs.readFile(manifestFile, 'utf-8');
-    const manifest = yaml.load(manifestContent);
+    const loaded = yaml.load(manifestContent);
+    const manifest = loaded && typeof loaded === 'object' ? loaded : {};
     // Detect v2.x version
     const formatVersion = detectV2Version(manifest);
     // Read prompt.md
@@ -114,6 +130,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 +196,7 @@ async function loadModuleV2(modulePath) {
         enums,
         compat,
         metaConfig,
+        composition,
         // Context and prompt
         context: manifest.context,
         prompt,
@@ -196,6 +261,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 +326,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 +339,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 +350,13 @@ async function isValidModule(modulePath) {
             return true;
         }
         catch {
-            return false;
+            try {
+                await fs.access(v0Module);
+                return true;
+            }
+            catch {
+                return false;
+            }
         }
     }
 }
@@ -264,10 +396,43 @@ export async function listModules(searchPaths) {
     return modules;
 }
 export function getDefaultSearchPaths(cwd) {
-    const home = process.env.HOME || '';
+    const home = homedir();
     return [
         path.join(cwd, 'cognitive', 'modules'),
         path.join(cwd, '.cognitive', 'modules'),
         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;
+}