cognitive-modules-cli 2.2.5 → 2.2.8

package/dist/errors/index.d.ts

@@ -112,6 +112,13 @@ export interface ErrorEnvelopeOptions {
  */
 export declare function makeErrorEnvelope(options: ErrorEnvelopeOptions): CognitiveErrorEnvelope;
 export declare function attachContext<T extends object>(envelope: T, context?: EnvelopeContext): T & EnvelopeContext;
+/**
+ * Map a CEP error code to an HTTP status code.
+ *
+ * This is used to keep HTTP behavior consistent with the error model while
+ * allowing callers to attach context without rebuilding envelopes.
+ */
+export declare function httpStatusForErrorCode(code: string): number;
 /**
  * Create error envelope for HTTP API responses.
  *

package/dist/errors/index.js

@@ -191,54 +191,47 @@ export function attachContext(envelope, context) {
     };
 }
 /**
- * Create error envelope for HTTP API responses.
+ * Map a CEP error code to an HTTP status code.
  *
- * @returns Tuple of [statusCode, body]
+ * This is used to keep HTTP behavior consistent with the error model while
+ * allowing callers to attach context without rebuilding envelopes.
  */
-export function makeHttpError(options) {
-    const envelope = attachContext(makeErrorEnvelope(options), options);
-    const code = normalizeErrorCode(options.code);
-    // Determine HTTP status code
-    let statusCode;
-    const category = code.charAt(1);
+export function httpStatusForErrorCode(code) {
+    const normalized = normalizeErrorCode(code);
+    const category = normalized.charAt(1);
     switch (category) {
         case '1': {
             // Input errors -> Bad Request (with specific overrides)
-            if (code === ErrorCodes.INPUT_TOO_LARGE) {
-                statusCode = 413; // Payload Too Large
-            }
-            else {
-                statusCode = 400;
-            }
-            break;
+            if (normalized === ErrorCodes.INPUT_TOO_LARGE)
+                return 413;
+            return 400;
         }
-        case '2':
-            statusCode = 422;
-            break; // Processing errors -> Unprocessable Entity
-        case '3':
-            statusCode = 500;
-            break; // Output errors -> Internal Server Error
+        case '2': return 422; // Processing errors -> Unprocessable Entity
+        case '3': return 500; // Output errors -> Internal Server Error
         case '4': {
-            // Runtime errors - map to appropriate HTTP status
-            if (code === ErrorCodes.MODULE_NOT_FOUND ||
-                code === ErrorCodes.ENDPOINT_NOT_FOUND ||
-                code === ErrorCodes.RESOURCE_NOT_FOUND) {
-                statusCode = 404; // Not Found
-            }
-            else if (code === ErrorCodes.PERMISSION_DENIED) {
-                statusCode = 403; // Forbidden
-            }
-            else if (code === ErrorCodes.RATE_LIMITED) {
-                statusCode = 429; // Too Many Requests
+            // Runtime errors -> map to appropriate HTTP status
+            if (normalized === ErrorCodes.MODULE_NOT_FOUND ||
+                normalized === ErrorCodes.ENDPOINT_NOT_FOUND ||
+                normalized === ErrorCodes.RESOURCE_NOT_FOUND) {
+                return 404;
             }
-            else {
-                statusCode = 500; // Internal Server Error
-            }
-            break;
+            if (normalized === ErrorCodes.PERMISSION_DENIED)
+                return 403;
+            if (normalized === ErrorCodes.RATE_LIMITED)
+                return 429;
+            return 500;
         }
-        default: statusCode = 500;
+        default: return 500;
     }
-    // Add HTTP-specific fields
+}
+/**
+ * Create error envelope for HTTP API responses.
+ *
+ * @returns Tuple of [statusCode, body]
+ */
+export function makeHttpError(options) {
+    const envelope = attachContext(makeErrorEnvelope(options), options);
+    const statusCode = httpStatusForErrorCode(String(options.code));
     return [statusCode, envelope];
 }
 /**
@@ -316,16 +309,31 @@ export function shouldRetry(envelope) {
  * Use this for consistent success responses across HTTP and MCP layers.
  */
 export function makeSuccessEnvelope(options) {
+    const explain = (options.explain || 'Operation completed successfully').slice(0, 280);
+    // Envelope schema requires data to be an object with at least `rationale`.
+    // For non-module operations (list/info), we still emit a conforming envelope by
+    // injecting a minimal rationale if missing, or wrapping non-objects.
+    const normalizedData = (() => {
+        const d = options.data;
+        const isPlainObject = typeof d === 'object' && d !== null && !Array.isArray(d);
+        if (!isPlainObject) {
+            return { result: d, rationale: explain };
+        }
+        const obj = d;
+        if (typeof obj.rationale === 'string')
+            return options.data;
+        return { ...obj, rationale: explain };
+    })();
     return {
         ok: true,
         version: options.version || '2.2',
         meta: {
             confidence: options.confidence ?? 1.0,
             risk: options.risk ?? 'none',
-            explain: (options.explain || 'Operation completed successfully').slice(0, 280),
+            explain,
             trace_id: options.trace_id,
         },
-        data: options.data,
+        data: normalizedData,
     };
 }
 /**

package/dist/modules/composition.d.ts

@@ -12,7 +12,7 @@
  * - Timeout handling
  * - Circular dependency detection
  */
-import type { CognitiveModule, ModuleResult, ModuleInput, Provider } from '../types.js';
+import type { CognitiveModule, ModuleResult, ModuleInput, Provider, ExecutionPolicy } from '../types.js';
 /** Composition pattern types */
 export type CompositionPattern = 'sequential' | 'parallel' | 'conditional' | 'iterative';
 /** Aggregation strategy for combining multiple outputs */
@@ -185,7 +185,16 @@ export declare class CompositionOrchestrator {
     private provider;
     private cwd;
     private searchPaths;
-    constructor(provider: Provider, cwd?: string);
+    private validateInput;
+    private validateOutput;
+    private enableRepair;
+    private policy?;
+    constructor(provider: Provider, cwd?: string, enforcement?: {
+        validateInput?: boolean;
+        validateOutput?: boolean;
+        enableRepair?: boolean;
+        policy?: ExecutionPolicy;
+    });
     /**
      * Execute a composed module workflow
      */
@@ -241,6 +250,10 @@ export declare function executeComposition(moduleName: string, input: ModuleInpu
     cwd?: string;
     maxDepth?: number;
     timeoutMs?: number;
+    validateInput?: boolean;
+    validateOutput?: boolean;
+    enableRepair?: boolean;
+    policy?: ExecutionPolicy;
 }): Promise<CompositionResult>;
 /**
  * Validate composition configuration

package/dist/modules/composition.js

@@ -577,10 +577,18 @@ export class CompositionOrchestrator {
     provider;
     cwd;
     searchPaths;
-    constructor(provider, cwd = process.cwd()) {
+    validateInput;
+    validateOutput;
+    enableRepair;
+    policy;
+    constructor(provider, cwd = process.cwd(), enforcement = {}) {
         this.provider = provider;
         this.cwd = cwd;
         this.searchPaths = getDefaultSearchPaths(cwd);
+        this.validateInput = enforcement.validateInput ?? true;
+        this.validateOutput = enforcement.validateOutput ?? true;
+        this.enableRepair = enforcement.enableRepair ?? true;
+        this.policy = enforcement.policy;
     }
     /**
      * Execute a composed module workflow
@@ -1160,9 +1168,11 @@ export class CompositionOrchestrator {
         try {
             const result = await runModule(module, this.provider, {
                 input,
-                validateInput: true,
-                validateOutput: true,
-                useV22: true
+                validateInput: this.validateInput,
+                validateOutput: this.validateOutput,
+                useV22: true,
+                enableRepair: this.enableRepair,
+                policy: this.policy,
             });
             const endTime = Date.now();
             trace.push({
@@ -1278,8 +1288,8 @@ export class CompositionOrchestrator {
  * Execute a composed module workflow
  */
 export async function executeComposition(moduleName, input, provider, options = {}) {
-    const { cwd = process.cwd(), ...execOptions } = options;
-    const orchestrator = new CompositionOrchestrator(provider, cwd);
+    const { cwd = process.cwd(), validateInput, validateOutput, enableRepair, policy, ...execOptions } = options;
+    const orchestrator = new CompositionOrchestrator(provider, cwd, { validateInput, validateOutput, enableRepair, policy });
     return orchestrator.execute(moduleName, input, execOptions);
 }
 /**

package/dist/modules/loader.d.ts

@@ -7,6 +7,16 @@ import type { CognitiveModule, ModuleTier, SchemaStrictness } from '../types.js'
  * Load a Cognitive Module (auto-detects format)
  */
 export declare function loadModule(modulePath: string): Promise<CognitiveModule>;
+/**
+ * Load a single-file module (Markdown) with optional YAML frontmatter.
+ *
+ * This enables the "5-minute" path: one file runs, and the runtime generates a loose schema/envelope.
+ *
+ * File format:
+ * - Optional YAML frontmatter between --- ... --- (same as v1 MODULE.md)
+ * - Body is treated as prompt
+ */
+export declare function loadSingleFileModule(filePath: 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[];

package/dist/modules/loader.js

@@ -7,6 +7,7 @@ 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]*))?/;
+const SAFE_MODULE_NAME_REGEX = /^[a-z0-9][a-z0-9._-]*$/i;
 /**
  * Detect module format version
  */
@@ -333,6 +334,173 @@ export async function loadModule(modulePath) {
         return loadModuleV0(modulePath);
     }
 }
+// =============================================================================
+// Single-File Modules (Ad-hoc)
+// =============================================================================
+function coerceModuleName(name, fallback) {
+    const raw = (typeof name === 'string' && name.trim().length > 0) ? name.trim() : fallback;
+    const normalized = raw
+        .replace(/\s+/g, '-')
+        .replace(/[^a-zA-Z0-9._-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    const lower = normalized.toLowerCase();
+    if (SAFE_MODULE_NAME_REGEX.test(lower))
+        return lower;
+    return fallback;
+}
+function defaultMetaSchema() {
+    return {
+        type: 'object',
+        additionalProperties: true,
+        required: ['confidence', 'risk', 'explain'],
+        properties: {
+            confidence: { type: 'number', minimum: 0, maximum: 1 },
+            risk: { type: 'string', enum: ['none', 'low', 'medium', 'high'] },
+            explain: { type: 'string', maxLength: 280 },
+        },
+    };
+}
+function defaultDataSchema() {
+    // Intentionally loose: the "5-minute" path should not fail on business fields.
+    return {
+        type: 'object',
+        additionalProperties: true,
+    };
+}
+function defaultInputSchema() {
+    // Matches runtime behavior: args are mapped to either query or code.
+    return {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+            query: { type: 'string' },
+            code: { type: 'string' },
+            args: { type: 'string' },
+        },
+    };
+}
+function defaultEnvelopeSchema(metaSchema) {
+    // Used as a hint for structured output (provider jsonSchema). Validation uses metaSchema/dataSchema separately.
+    return {
+        type: 'object',
+        additionalProperties: true,
+        oneOf: [
+            {
+                type: 'object',
+                required: ['ok', 'meta', 'data'],
+                properties: {
+                    ok: { const: true },
+                    version: { type: 'string' },
+                    meta: metaSchema,
+                    data: { type: 'object', additionalProperties: true },
+                },
+            },
+            {
+                type: 'object',
+                required: ['ok', 'meta', 'error'],
+                properties: {
+                    ok: { const: false },
+                    version: { type: 'string' },
+                    meta: metaSchema,
+                    error: {
+                        type: 'object',
+                        additionalProperties: true,
+                        required: ['code', 'message'],
+                        properties: {
+                            code: { type: 'string' },
+                            message: { type: 'string' },
+                            recoverable: { type: 'boolean' },
+                        },
+                    },
+                    partial_data: { type: 'object', additionalProperties: true },
+                },
+            },
+        ],
+    };
+}
+function looksLikeMarkdownModule(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return ext === '.md' || ext === '.markdown';
+}
+/**
+ * Load a single-file module (Markdown) with optional YAML frontmatter.
+ *
+ * This enables the "5-minute" path: one file runs, and the runtime generates a loose schema/envelope.
+ *
+ * File format:
+ * - Optional YAML frontmatter between --- ... --- (same as v1 MODULE.md)
+ * - Body is treated as prompt
+ */
+export async function loadSingleFileModule(filePath) {
+    const absPath = path.resolve(filePath);
+    if (!looksLikeMarkdownModule(absPath)) {
+        throw new Error(`Single-file modules currently support Markdown (.md) only: ${absPath}`);
+    }
+    const content = await fs.readFile(absPath, 'utf-8');
+    let manifest = {};
+    let prompt = content;
+    const match = content.match(FRONTMATTER_REGEX);
+    if (match) {
+        try {
+            const loaded = yaml.load(match[1]);
+            manifest = (loaded && typeof loaded === 'object') ? loaded : {};
+        }
+        catch {
+            manifest = {};
+        }
+        prompt = (match[2] ?? '').trim();
+    }
+    const base = path.basename(absPath, path.extname(absPath));
+    const name = coerceModuleName(manifest.name, coerceModuleName(base, 'single-file-module'));
+    const tier = manifest.tier ?? 'decision';
+    const responsibility = manifest.responsibility
+        ?? `Ad-hoc single-file module loaded from ${path.basename(absPath)}`;
+    const excludes = Array.isArray(manifest.excludes) ? manifest.excludes : [];
+    const metaSchema = defaultMetaSchema();
+    const dataSchema = defaultDataSchema();
+    const inputSchema = defaultInputSchema();
+    const envelopeSchema = defaultEnvelopeSchema(metaSchema);
+    // Keep validation permissive by default, but still enforce envelope meta shape.
+    const schemaStrictness = manifest.schema_strictness ?? 'low';
+    return {
+        name,
+        version: manifest.version ?? '0.1.0',
+        responsibility,
+        excludes,
+        constraints: manifest.constraints,
+        policies: manifest.policies,
+        tools: manifest.tools,
+        output: manifest.output ?? { envelope: true, format: 'json_lenient' },
+        failure: manifest.failure,
+        runtimeRequirements: manifest.runtime_requirements,
+        tier,
+        schemaStrictness,
+        overflow: {
+            enabled: true,
+            recoverable: true,
+            max_items: 20,
+            require_suggested_mapping: false,
+        },
+        enums: { strategy: 'extensible', unknown_tag: 'custom' },
+        compat: { accepts_v21_payload: true, runtime_auto_wrap: true, schema_output_alias: 'data' },
+        metaConfig: { risk_rule: 'explicit' },
+        composition: undefined,
+        context: manifest.context,
+        prompt: prompt.length > 0 ? prompt : content.trim(),
+        // Schemas:
+        // - outputSchema is used as provider jsonSchema hint (we want the full envelope)
+        // - metaSchema/dataSchema are used for runtime validation after wrapping/repair
+        inputSchema,
+        outputSchema: envelopeSchema,
+        dataSchema,
+        metaSchema,
+        errorSchema: undefined,
+        location: absPath,
+        format: 'v2',
+        formatVersion: 'v2.2',
+    };
+}
 /**
  * Check if a directory contains a valid module
  */

package/dist/modules/runner.d.ts

@@ -3,7 +3,7 @@
  * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  * v2.2.1: Version field, enhanced error taxonomy, observability hooks, streaming
  */
-import type { Provider, CognitiveModule, ModuleResult, ModuleInput, EnvelopeResponseV22, EnvelopeMeta, RiskLevel } from '../types.js';
+import type { Provider, CognitiveModule, ModuleResult, ModuleInput, EnvelopeResponseV22, EnvelopeMeta, RiskLevel, ExecutionPolicy } from '../types.js';
 /**
  * Validate data against JSON schema. Returns list of errors.
  */
@@ -366,16 +366,19 @@ export interface RunOptions {
     enableRepair?: boolean;
     traceId?: string;
     model?: string;
+    policy?: ExecutionPolicy;
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;
 /** Event types emitted during streaming execution */
-export type StreamEventType = 'start' | 'chunk' | 'meta' | 'complete' | 'error';
+export type StreamEventType = 'start' | 'delta' | 'meta' | 'end' | 'error';
 /** Event emitted during streaming execution */
 export interface StreamEvent {
     type: StreamEventType;
+    version: string;
     timestamp_ms: number;
-    module_name: string;
-    chunk?: string;
+    module: string;
+    provider?: string;
+    delta?: string;
     meta?: EnvelopeMeta;
     result?: EnvelopeResponseV22<unknown>;
     error?: {
@@ -392,15 +395,16 @@ export interface StreamOptions {
     enableRepair?: boolean;
     traceId?: string;
     model?: string;
+    policy?: ExecutionPolicy;
 }
 /**
  * Run a cognitive module with streaming output.
  *
  * Yields StreamEvent objects as the module executes:
  * - type="start": Module execution started
- * - type="chunk": Incremental data chunk (if LLM supports streaming)
+ * - type="delta": Incremental output delta (provider streaming chunk)
  * - type="meta": Meta information available early
- * - type="complete": Final complete result
+ * - type="end": Final result envelope (always emitted)
  * - type="error": Error occurred
  *
  * @example