cognitive-modules-cli 2.2.0 → 2.2.1

package/dist/modules/subagent.js

@@ -161,6 +161,8 @@ export class SubagentOrchestrator {
             // Run the module
             const result = await runModule(modifiedModule, this.provider, {
                 input,
+                validateInput,
+                validateOutput,
                 verbose: false,
                 useV22: true
             });

package/dist/modules/validator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Module Validator - Validate cognitive module structure and examples.
+ * Supports v0, v1, v2.1, and v2.2 module formats.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate a cognitive module's structure and examples.
+ * Supports all formats.
+ *
+ * @param nameOrPath Module name or path
+ * @param v22 If true, validate v2.2 specific requirements
+ * @returns Validation result with errors and warnings
+ */
+export declare function validateModule(modulePath: string, v22?: boolean): Promise<ValidationResult>;
+/**
+ * Validate a response against v2.2 envelope format.
+ *
+ * @param response The response dict to validate
+ * @returns Validation result
+ */
+export declare function validateV22Envelope(response: Record<string, unknown>): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/modules/validator.js

@@ -0,0 +1,629 @@
+/**
+ * Module Validator - Validate cognitive module structure and examples.
+ * Supports v0, v1, v2.1, and v2.2 module formats.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import _Ajv from 'ajv';
+const Ajv = _Ajv.default || _Ajv;
+const ajv = new Ajv({ allErrors: true, strict: false });
+// =============================================================================
+// Main Validation Entry Point
+// =============================================================================
+/**
+ * Validate a cognitive module's structure and examples.
+ * Supports all formats.
+ *
+ * @param nameOrPath Module name or path
+ * @param v22 If true, validate v2.2 specific requirements
+ * @returns Validation result with errors and warnings
+ */
+export async function validateModule(modulePath, v22 = false) {
+    const errors = [];
+    const warnings = [];
+    // Check if path exists
+    try {
+        await fs.access(modulePath);
+    }
+    catch {
+        return { valid: false, errors: [`Module not found: ${modulePath}`], warnings: [] };
+    }
+    // Detect format
+    const hasModuleYaml = await fileExists(path.join(modulePath, 'module.yaml'));
+    const hasModuleMd = await fileExists(path.join(modulePath, 'MODULE.md'));
+    const hasOldModuleMd = await fileExists(path.join(modulePath, 'module.md'));
+    if (hasModuleYaml) {
+        // v2.x format
+        if (v22) {
+            return validateV22Format(modulePath);
+        }
+        else {
+            return validateV2Format(modulePath);
+        }
+    }
+    else if (hasModuleMd) {
+        // v1 format
+        if (v22) {
+            errors.push("Module is v1 format. Use 'cogn migrate' to upgrade to v2.2");
+            return { valid: false, errors, warnings };
+        }
+        return validateV1Format(modulePath);
+    }
+    else if (hasOldModuleMd) {
+        // v0 format
+        if (v22) {
+            errors.push("Module is v0 format. Use 'cogn migrate' to upgrade to v2.2");
+            return { valid: false, errors, warnings };
+        }
+        return validateV0Format(modulePath);
+    }
+    else {
+        return { valid: false, errors: ['Missing module.yaml, MODULE.md, or module.md'], warnings: [] };
+    }
+}
+// =============================================================================
+// v2.2 Validation
+// =============================================================================
+async function validateV22Format(modulePath) {
+    const errors = [];
+    const warnings = [];
+    // Check module.yaml
+    const moduleYamlPath = path.join(modulePath, 'module.yaml');
+    let manifest;
+    try {
+        const content = await fs.readFile(moduleYamlPath, 'utf-8');
+        manifest = yaml.load(content);
+    }
+    catch (e) {
+        errors.push(`Invalid YAML in module.yaml: ${e.message}`);
+        return { valid: false, errors, warnings };
+    }
+    // Check v2.2 required fields
+    const v22RequiredFields = ['name', 'version', 'responsibility'];
+    for (const field of v22RequiredFields) {
+        if (!(field in manifest)) {
+            errors.push(`module.yaml missing required field: ${field}`);
+        }
+    }
+    // Check tier (v2.2 specific)
+    const tier = manifest.tier;
+    if (!tier) {
+        warnings.push("module.yaml missing 'tier' (recommended: exec | decision | exploration)");
+    }
+    else if (!['exec', 'decision', 'exploration'].includes(tier)) {
+        errors.push(`Invalid tier: ${tier}. Must be exec | decision | exploration`);
+    }
+    // Check schema_strictness
+    const schemaStrictness = manifest.schema_strictness;
+    if (schemaStrictness && !['high', 'medium', 'low'].includes(schemaStrictness)) {
+        errors.push(`Invalid schema_strictness: ${schemaStrictness}. Must be high | medium | low`);
+    }
+    // Check overflow config
+    const overflow = manifest.overflow ?? {};
+    if (overflow.enabled) {
+        if (overflow.require_suggested_mapping === undefined) {
+            warnings.push("overflow.require_suggested_mapping not set (recommended for recoverable insights)");
+        }
+    }
+    // Check enums config
+    const enums = manifest.enums ?? {};
+    const strategy = enums.strategy;
+    if (strategy && !['strict', 'extensible'].includes(strategy)) {
+        errors.push(`Invalid enums.strategy: ${strategy}. Must be strict | extensible`);
+    }
+    // Check compat config
+    const compat = manifest.compat;
+    if (!compat) {
+        warnings.push("module.yaml missing 'compat' section (recommended for migration)");
+    }
+    // Check excludes
+    const excludes = manifest.excludes ?? [];
+    if (excludes.length === 0) {
+        warnings.push("'excludes' list is empty (should list what module won't do)");
+    }
+    // Check prompt.md
+    const promptPath = path.join(modulePath, 'prompt.md');
+    if (!await fileExists(promptPath)) {
+        errors.push("Missing prompt.md (required for v2.2)");
+    }
+    else {
+        const prompt = await fs.readFile(promptPath, 'utf-8');
+        // Check for v2.2 envelope format instructions
+        if (!prompt.toLowerCase().includes('meta') && !prompt.toLowerCase().includes('envelope')) {
+            warnings.push("prompt.md should mention v2.2 envelope format with meta/data separation");
+        }
+        if (prompt.length < 100) {
+            warnings.push("prompt.md seems too short (< 100 chars)");
+        }
+    }
+    // Check schema.json
+    const schemaPath = path.join(modulePath, 'schema.json');
+    if (!await fileExists(schemaPath)) {
+        errors.push("Missing schema.json (required for v2.2)");
+    }
+    else {
+        try {
+            const schemaContent = await fs.readFile(schemaPath, 'utf-8');
+            const schema = JSON.parse(schemaContent);
+            // Check for meta schema (v2.2 required)
+            if (!('meta' in schema)) {
+                errors.push("schema.json missing 'meta' schema (required for v2.2)");
+            }
+            else {
+                const metaSchema = schema.meta;
+                const metaRequired = metaSchema.required ?? [];
+                if (!metaRequired.includes('confidence')) {
+                    errors.push("meta schema must require 'confidence'");
+                }
+                if (!metaRequired.includes('risk')) {
+                    errors.push("meta schema must require 'risk'");
+                }
+                if (!metaRequired.includes('explain')) {
+                    errors.push("meta schema must require 'explain'");
+                }
+                // Check explain maxLength
+                const properties = metaSchema.properties ?? {};
+                const explainProps = properties.explain ?? {};
+                const maxLength = explainProps.maxLength ?? 999;
+                if (maxLength > 280) {
+                    warnings.push("meta.explain should have maxLength <= 280");
+                }
+            }
+            // Check for input schema
+            if (!('input' in schema)) {
+                warnings.push("schema.json missing 'input' definition");
+            }
+            // Check for data schema (v2.2 uses 'data' instead of 'output')
+            if (!('data' in schema) && !('output' in schema)) {
+                errors.push("schema.json missing 'data' (or 'output') definition");
+            }
+            else if ('data' in schema) {
+                const dataSchema = schema.data;
+                const dataRequired = dataSchema.required ?? [];
+                if (!dataRequired.includes('rationale')) {
+                    warnings.push("data schema should require 'rationale' for audit");
+                }
+            }
+            // Check for error schema
+            if (!('error' in schema)) {
+                warnings.push("schema.json missing 'error' definition");
+            }
+            // Check for $defs/extensions (v2.2 overflow)
+            if (overflow.enabled) {
+                const defs = schema.$defs ?? {};
+                if (!('extensions' in defs)) {
+                    warnings.push("schema.json missing '$defs.extensions' (needed for overflow)");
+                }
+            }
+        }
+        catch (e) {
+            errors.push(`Invalid JSON in schema.json: ${e.message}`);
+        }
+    }
+    // Check tests directory
+    const testsPath = path.join(modulePath, 'tests');
+    if (!await fileExists(testsPath)) {
+        warnings.push("Missing tests directory (recommended)");
+    }
+    else {
+        // Check for v2.2 format in expected files
+        try {
+            const entries = await fs.readdir(testsPath);
+            for (const entry of entries) {
+                if (entry.endsWith('.expected.json')) {
+                    try {
+                        const expectedContent = await fs.readFile(path.join(testsPath, entry), 'utf-8');
+                        const expected = JSON.parse(expectedContent);
+                        // Check if example uses v2.2 format
+                        const example = expected.$example ?? {};
+                        if (example.ok === true && !('meta' in example)) {
+                            warnings.push(`${entry}: $example missing 'meta' (v2.2 format)`);
+                        }
+                    }
+                    catch {
+                        // Skip invalid JSON
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip if can't read tests directory
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+// =============================================================================
+// v2.x (non-strict) Validation
+// =============================================================================
+async function validateV2Format(modulePath) {
+    const errors = [];
+    const warnings = [];
+    // Check module.yaml
+    const moduleYamlPath = path.join(modulePath, 'module.yaml');
+    let manifest;
+    try {
+        const content = await fs.readFile(moduleYamlPath, 'utf-8');
+        manifest = yaml.load(content);
+    }
+    catch (e) {
+        errors.push(`Invalid YAML in module.yaml: ${e.message}`);
+        return { valid: false, errors, warnings };
+    }
+    // Check required fields
+    const requiredFields = ['name', 'version', 'responsibility'];
+    for (const field of requiredFields) {
+        if (!(field in manifest)) {
+            errors.push(`module.yaml missing required field: ${field}`);
+        }
+    }
+    // Check excludes
+    const excludes = manifest.excludes ?? [];
+    if (excludes.length === 0) {
+        warnings.push("'excludes' list is empty");
+    }
+    // Check prompt.md or MODULE.md
+    const promptPath = path.join(modulePath, 'prompt.md');
+    const moduleMdPath = path.join(modulePath, 'MODULE.md');
+    if (!await fileExists(promptPath) && !await fileExists(moduleMdPath)) {
+        errors.push("Missing prompt.md or MODULE.md");
+    }
+    else if (await fileExists(promptPath)) {
+        const prompt = await fs.readFile(promptPath, 'utf-8');
+        if (prompt.length < 50) {
+            warnings.push("prompt.md seems too short (< 50 chars)");
+        }
+    }
+    // Check schema.json
+    const schemaPath = path.join(modulePath, 'schema.json');
+    if (!await fileExists(schemaPath)) {
+        warnings.push("Missing schema.json (recommended)");
+    }
+    else {
+        try {
+            const schemaContent = await fs.readFile(schemaPath, 'utf-8');
+            const schema = JSON.parse(schemaContent);
+            if (!('input' in schema)) {
+                warnings.push("schema.json missing 'input' definition");
+            }
+            // Accept both 'data' and 'output'
+            if (!('data' in schema) && !('output' in schema)) {
+                warnings.push("schema.json missing 'data' or 'output' definition");
+            }
+        }
+        catch (e) {
+            errors.push(`Invalid JSON in schema.json: ${e.message}`);
+        }
+    }
+    // Check for v2.2 features and suggest upgrade
+    if (!manifest.tier) {
+        warnings.push("Consider adding 'tier' for v2.2 (use 'cogn validate --v22' for full check)");
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+// =============================================================================
+// v1 Format Validation (MODULE.md + schema.json)
+// =============================================================================
+async function validateV1Format(modulePath) {
+    const errors = [];
+    const warnings = [];
+    // Check MODULE.md
+    const moduleMdPath = path.join(modulePath, 'MODULE.md');
+    try {
+        const content = await fs.readFile(moduleMdPath, 'utf-8');
+        if (content.length === 0) {
+            errors.push("MODULE.md is empty");
+            return { valid: false, errors, warnings };
+        }
+        // Parse frontmatter
+        if (!content.startsWith('---')) {
+            errors.push("MODULE.md must start with YAML frontmatter (---)");
+        }
+        else {
+            const parts = content.split('---');
+            if (parts.length < 3) {
+                errors.push("MODULE.md frontmatter not properly closed");
+            }
+            else {
+                try {
+                    const frontmatter = yaml.load(parts[1]);
+                    const body = parts.slice(2).join('---').trim();
+                    // Check required fields
+                    const requiredFields = ['name', 'version', 'responsibility', 'excludes'];
+                    for (const field of requiredFields) {
+                        if (!(field in frontmatter)) {
+                            errors.push(`MODULE.md missing required field: ${field}`);
+                        }
+                    }
+                    if ('excludes' in frontmatter) {
+                        if (!Array.isArray(frontmatter.excludes)) {
+                            errors.push("'excludes' must be a list");
+                        }
+                        else if (frontmatter.excludes.length === 0) {
+                            warnings.push("'excludes' list is empty");
+                        }
+                    }
+                    // Check body has content
+                    if (body.length < 50) {
+                        warnings.push("MODULE.md body seems too short (< 50 chars)");
+                    }
+                }
+                catch (e) {
+                    errors.push(`Invalid YAML in MODULE.md: ${e.message}`);
+                }
+            }
+        }
+    }
+    catch (e) {
+        errors.push(`Cannot read MODULE.md: ${e.message}`);
+        return { valid: false, errors, warnings };
+    }
+    // Check schema.json
+    const schemaPath = path.join(modulePath, 'schema.json');
+    if (!await fileExists(schemaPath)) {
+        warnings.push("Missing schema.json (recommended for validation)");
+    }
+    else {
+        try {
+            const schemaContent = await fs.readFile(schemaPath, 'utf-8');
+            const schema = JSON.parse(schemaContent);
+            if (!('input' in schema)) {
+                warnings.push("schema.json missing 'input' definition");
+            }
+            if (!('output' in schema)) {
+                warnings.push("schema.json missing 'output' definition");
+            }
+            // Check output has required fields
+            const output = schema.output ?? {};
+            const required = output.required ?? [];
+            if (!required.includes('confidence')) {
+                warnings.push("output schema should require 'confidence'");
+            }
+            if (!required.includes('rationale')) {
+                warnings.push("output schema should require 'rationale'");
+            }
+        }
+        catch (e) {
+            errors.push(`Invalid JSON in schema.json: ${e.message}`);
+        }
+    }
+    // Check examples
+    const examplesPath = path.join(modulePath, 'examples');
+    if (!await fileExists(examplesPath)) {
+        warnings.push("Missing examples directory (recommended)");
+    }
+    else {
+        await validateExamples(examplesPath, path.join(modulePath, 'schema.json'), errors, warnings);
+    }
+    // Suggest v2.2 upgrade
+    warnings.push("Consider upgrading to v2.2 format for better Control/Data separation");
+    return { valid: errors.length === 0, errors, warnings };
+}
+// =============================================================================
+// v0 Format Validation (6-file format)
+// =============================================================================
+async function validateV0Format(modulePath) {
+    const errors = [];
+    const warnings = [];
+    // Check required files
+    const requiredFiles = [
+        'module.md',
+        'input.schema.json',
+        'output.schema.json',
+        'constraints.yaml',
+        'prompt.txt',
+    ];
+    for (const filename of requiredFiles) {
+        const filepath = path.join(modulePath, filename);
+        if (!await fileExists(filepath)) {
+            errors.push(`Missing required file: ${filename}`);
+        }
+        else {
+            const stat = await fs.stat(filepath);
+            if (stat.size === 0) {
+                errors.push(`File is empty: ${filename}`);
+            }
+        }
+    }
+    // Check examples directory
+    const examplesPath = path.join(modulePath, 'examples');
+    if (!await fileExists(examplesPath)) {
+        errors.push("Missing examples directory");
+    }
+    else {
+        if (!await fileExists(path.join(examplesPath, 'input.json'))) {
+            errors.push("Missing examples/input.json");
+        }
+        if (!await fileExists(path.join(examplesPath, 'output.json'))) {
+            errors.push("Missing examples/output.json");
+        }
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors, warnings };
+    }
+    // Validate module.md frontmatter
+    try {
+        const content = await fs.readFile(path.join(modulePath, 'module.md'), 'utf-8');
+        if (!content.startsWith('---')) {
+            errors.push("module.md must start with YAML frontmatter (---)");
+        }
+        else {
+            const parts = content.split('---');
+            if (parts.length < 3) {
+                errors.push("module.md frontmatter not properly closed");
+            }
+            else {
+                try {
+                    const frontmatter = yaml.load(parts[1]);
+                    const requiredFields = ['name', 'version', 'responsibility', 'excludes'];
+                    for (const field of requiredFields) {
+                        if (!(field in frontmatter)) {
+                            errors.push(`module.md missing required field: ${field}`);
+                        }
+                    }
+                    if ('excludes' in frontmatter) {
+                        if (!Array.isArray(frontmatter.excludes)) {
+                            errors.push("'excludes' must be a list");
+                        }
+                        else if (frontmatter.excludes.length === 0) {
+                            warnings.push("'excludes' list is empty");
+                        }
+                    }
+                }
+                catch (e) {
+                    errors.push(`Invalid YAML in module.md: ${e.message}`);
+                }
+            }
+        }
+    }
+    catch (e) {
+        errors.push(`Cannot read module.md: ${e.message}`);
+    }
+    // Suggest v2.2 upgrade
+    warnings.push("v0 format is deprecated. Consider upgrading to v2.2");
+    return { valid: errors.length === 0, errors, warnings };
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+async function fileExists(filepath) {
+    try {
+        await fs.access(filepath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function validateExamples(examplesPath, schemaPath, errors, warnings) {
+    if (!await fileExists(path.join(examplesPath, 'input.json'))) {
+        warnings.push("Missing examples/input.json");
+    }
+    if (!await fileExists(path.join(examplesPath, 'output.json'))) {
+        warnings.push("Missing examples/output.json");
+    }
+    // Validate examples against schema if both exist
+    if (await fileExists(schemaPath)) {
+        try {
+            const schemaContent = await fs.readFile(schemaPath, 'utf-8');
+            const schema = JSON.parse(schemaContent);
+            // Validate input example
+            const inputExamplePath = path.join(examplesPath, 'input.json');
+            if (await fileExists(inputExamplePath) && 'input' in schema) {
+                try {
+                    const inputContent = await fs.readFile(inputExamplePath, 'utf-8');
+                    const inputExample = JSON.parse(inputContent);
+                    const validate = ajv.compile(schema.input);
+                    const valid = validate(inputExample);
+                    if (!valid && validate.errors) {
+                        errors.push(`Example input fails schema: ${validate.errors[0]?.message}`);
+                    }
+                }
+                catch (e) {
+                    errors.push(`Invalid JSON in examples/input.json: ${e.message}`);
+                }
+            }
+            // Validate output example
+            const outputExamplePath = path.join(examplesPath, 'output.json');
+            const outputSchema = (schema.output || schema.data);
+            if (await fileExists(outputExamplePath) && outputSchema) {
+                try {
+                    const outputContent = await fs.readFile(outputExamplePath, 'utf-8');
+                    const outputExample = JSON.parse(outputContent);
+                    const validate = ajv.compile(outputSchema);
+                    const valid = validate(outputExample);
+                    if (!valid && validate.errors) {
+                        errors.push(`Example output fails schema: ${validate.errors[0]?.message}`);
+                    }
+                    // Check confidence
+                    if ('confidence' in outputExample) {
+                        const conf = outputExample.confidence;
+                        if (conf < 0 || conf > 1) {
+                            errors.push(`Confidence must be 0-1, got: ${conf}`);
+                        }
+                    }
+                }
+                catch (e) {
+                    errors.push(`Invalid JSON in examples/output.json: ${e.message}`);
+                }
+            }
+        }
+        catch {
+            // Skip if schema can't be read
+        }
+    }
+}
+// =============================================================================
+// Envelope Validation
+// =============================================================================
+/**
+ * Validate a response against v2.2 envelope format.
+ *
+ * @param response The response dict to validate
+ * @returns Validation result
+ */
+export function validateV22Envelope(response) {
+    const errors = [];
+    // Check ok field
+    if (!('ok' in response)) {
+        errors.push("Missing 'ok' field");
+        return { valid: false, errors };
+    }
+    // Check meta
+    if (!('meta' in response)) {
+        errors.push("Missing 'meta' field (required for v2.2)");
+    }
+    else {
+        const meta = response.meta;
+        if (!('confidence' in meta)) {
+            errors.push("meta missing 'confidence'");
+        }
+        else if (typeof meta.confidence !== 'number') {
+            errors.push("meta.confidence must be a number");
+        }
+        else if (meta.confidence < 0 || meta.confidence > 1) {
+            errors.push("meta.confidence must be between 0 and 1");
+        }
+        if (!('risk' in meta)) {
+            errors.push("meta missing 'risk'");
+        }
+        else {
+            const validRisks = ['none', 'low', 'medium', 'high'];
+            if (!validRisks.includes(meta.risk)) {
+                errors.push(`meta.risk must be none|low|medium|high, got: ${meta.risk}`);
+            }
+        }
+        if (!('explain' in meta)) {
+            errors.push("meta missing 'explain'");
+        }
+        else {
+            const explain = meta.explain ?? '';
+            if (explain.length > 280) {
+                errors.push(`meta.explain exceeds 280 chars (${explain.length} chars)`);
+            }
+        }
+    }
+    // Check data or error
+    if (response.ok) {
+        if (!('data' in response)) {
+            errors.push("Success response missing 'data' field");
+        }
+        // Note: data.rationale is recommended but not required by v2.2 envelope spec
+        // The data schema validation will enforce it if the module specifies it as required
+    }
+    else {
+        if (!('error' in response)) {
+            errors.push("Error response missing 'error' field");
+        }
+        else {
+            const error = response.error;
+            if (!('code' in error)) {
+                errors.push("error missing 'code'");
+            }
+            if (!('message' in error)) {
+                errors.push("error missing 'message'");
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}