cognitive-modules-cli 2.2.7 → 2.2.9

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,6 +366,7 @@ 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 */
@@ -394,6 +395,7 @@ export interface StreamOptions {
     enableRepair?: boolean;
     traceId?: string;
     model?: string;
+    policy?: ExecutionPolicy;
 }
 /**
  * Run a cognitive module with streaming output.

package/dist/modules/runner.js

@@ -5,7 +5,10 @@
  */
 import _Ajv from 'ajv';
 const Ajv = _Ajv.default || _Ajv;
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import { aggregateRisk, isV22Envelope } from '../types.js';
+import { readModuleProvenance, verifyModuleIntegrity } from '../provenance.js';
 // =============================================================================
 // Schema Validation
 // =============================================================================
@@ -1046,12 +1049,113 @@ function convertLegacyToEnvelope(data, isError = false) {
         };
     }
 }
+async function enforcePolicyGates(module, policy) {
+    if (!policy)
+        return null;
+    if (policy.requireV22) {
+        const fv = module.formatVersion ?? 'unknown';
+        if (fv !== 'v2.2') {
+            return makeErrorResponse({
+                code: 'E4007', // PERMISSION_DENIED
+                message: `Certified policy requires v2.2 modules; got: ${fv} (${module.format})`,
+                explain: 'Refused by execution policy.',
+                confidence: 1.0,
+                risk: 'none',
+                suggestion: 'Migrate the module to v2.2, or run with --profile strict/default.',
+            });
+        }
+    }
+    if (policy.profile !== 'certified')
+        return null;
+    const loc = module.location;
+    if (typeof loc !== 'string' || loc.trim().length === 0) {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: 'Certified policy requires an installed module with provenance; module location is missing.',
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball that writes provenance.json.',
+        });
+    }
+    // Single-file modules (5-minute path) are intentionally not allowed in certified flows.
+    try {
+        const st = await fs.stat(loc);
+        if (!st.isDirectory()) {
+            return makeErrorResponse({
+                code: 'E4007', // PERMISSION_DENIED
+                message: `Certified policy requires module directory provenance; got a non-directory location: ${loc}`,
+                explain: 'Refused by execution policy.',
+                confidence: 1.0,
+                risk: 'none',
+                suggestion: 'Install the module via `cog add <name>` (registry tarball) or use --profile strict/default.',
+            });
+        }
+    }
+    catch {
+        return makeErrorResponse({
+            code: 'E4007',
+            message: `Certified policy requires module directory provenance, but location does not exist: ${loc}`,
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball and retry.',
+        });
+    }
+    const prov = await readModuleProvenance(loc);
+    if (!prov) {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: `Certified policy requires provenance.json in the module directory: ${loc}`,
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball (distribution.tarball + checksum), then retry.',
+        });
+    }
+    if (prov.source.type !== 'registry') {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: `Certified policy requires registry provenance; module provenance is type=${prov.source.type}`,
+            explain: 'Refused by execution policy.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from a registry tarball and retry, or use --profile strict/default.',
+        });
+    }
+    // Integrity check (tamper detection).
+    const ok = await verifyModuleIntegrity(loc, prov);
+    if (!ok.ok) {
+        return makeErrorResponse({
+            code: 'E4007', // PERMISSION_DENIED
+            message: `Certified policy integrity check failed: ${ok.reason}`,
+            explain: 'Module contents appear to have been modified after install.',
+            confidence: 1.0,
+            risk: 'none',
+            suggestion: 'Reinstall the module from the registry tarball to restore integrity.',
+            details: { location: loc, reason: ok.reason },
+        });
+    }
+    // Optional: enforce that the module directory remains within itself (defense-in-depth for weird paths).
+    const resolved = path.resolve(loc);
+    if (!resolved)
+        return null;
+    return null;
+}
 // =============================================================================
 // Main Runner
 // =============================================================================
 export async function runModule(module, provider, options = {}) {
-    const { args, input, verbose = false, validateInput = true, validateOutput = true, useEnvelope, useV22, enableRepair = true, traceId, model: modelOverride } = options;
+    const { args, input, verbose = false, validateInput = true, validateOutput = true, useEnvelope, useV22, enableRepair = true, traceId, model: modelOverride, policy } = options;
     const startTime = Date.now();
+    const gate = await enforcePolicyGates(module, policy);
+    if (gate) {
+        const msg = gate.ok === false && 'error' in gate && gate.error?.message
+            ? String(gate.error.message)
+            : 'Refused by execution policy';
+        _invokeErrorHooks(module.name, new Error(msg), null);
+        return gate;
+    }
     // Determine if we should use envelope format
     const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
     // Determine if we should use v2.2 format
@@ -1071,6 +1175,14 @@ export async function runModule(module, provider, options = {}) {
             inputData.query = args;
         }
     }
+    // Single-file core modules promise "missing fields are empty".
+    // Ensure common placeholders like `${query}` / `${code}` don't leak into prompts.
+    if (typeof module.location === 'string' && /\.(md|markdown)$/i.test(module.location)) {
+        if (inputData.query === undefined)
+            inputData.query = '';
+        if (inputData.code === undefined)
+            inputData.code = '';
+    }
     // Invoke before hooks
     _invokeBeforeHooks(module.name, inputData, module);
     // Validate input against schema
@@ -1339,7 +1451,7 @@ export async function runModule(module, provider, options = {}) {
  * }
  */
 export async function* runModuleStream(module, provider, options = {}) {
-    const { input, args, validateInput = true, validateOutput = true, useV22 = true, enableRepair = true, traceId, model } = options;
+    const { input, args, validateInput = true, validateOutput = true, useV22 = true, enableRepair = true, traceId, model, policy } = options;
     const startTime = Date.now();
     const moduleName = module.name;
     const providerName = provider?.name;
@@ -1356,6 +1468,13 @@ export async function* runModuleStream(module, provider, options = {}) {
     try {
         // Emit start event
         yield makeEvent('start');
+        const gate = await enforcePolicyGates(module, policy);
+        if (gate) {
+            const errorObj = gate?.error ?? { code: 'E4007', message: 'Refused by execution policy' };
+            yield makeEvent('error', { error: { code: errorObj.code, message: errorObj.message } });
+            yield makeEvent('end', { result: gate });
+            return;
+        }
         // Build input data
         const inputData = input || {};
         if (args && !inputData.code && !inputData.query) {

package/dist/profile.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionPolicy } from './types.js';
+export interface ResolvePolicyInput {
+    profile?: string | null;
+    validate?: string | null;
+    noValidate?: boolean;
+    audit?: boolean;
+}
+export declare function resolveExecutionPolicy(input: ResolvePolicyInput): ExecutionPolicy;

package/dist/profile.js

@@ -0,0 +1,59 @@
+function normalizeProfile(raw) {
+    const v = (raw ?? '').trim().toLowerCase();
+    if (v === 'core')
+        return 'core';
+    if (v === 'default' || v === '')
+        return 'default';
+    if (v === 'strict')
+        return 'strict';
+    if (v === 'certified' || v === 'cert')
+        return 'certified';
+    throw new Error(`Invalid --profile: ${raw}. Expected one of: core|default|strict|certified`);
+}
+function normalizeValidate(raw) {
+    const v = (raw ?? '').trim().toLowerCase();
+    if (v === '' || v === 'auto')
+        return 'auto';
+    if (v === 'on' || v === 'true' || v === '1')
+        return 'on';
+    if (v === 'off' || v === 'false' || v === '0')
+        return 'off';
+    throw new Error(`Invalid --validate: ${raw}. Expected one of: auto|on|off`);
+}
+export function resolveExecutionPolicy(input) {
+    const profile = normalizeProfile(input.profile);
+    // Base defaults per profile.
+    let validate = profile === 'core' ? 'off' : 'on';
+    let audit = false;
+    let enableRepair = true;
+    let requireV22 = false;
+    if (profile === 'strict') {
+        validate = 'on';
+        audit = false;
+        enableRepair = true;
+        requireV22 = false;
+    }
+    if (profile === 'certified') {
+        validate = 'on';
+        audit = true;
+        enableRepair = false; // certification prefers fail-fast over runtime repair
+        requireV22 = true;
+    }
+    // CLI overrides.
+    const validateExplicit = input.validate != null || Boolean(input.noValidate);
+    if (input.validate != null) {
+        validate = normalizeValidate(input.validate);
+    }
+    if (input.noValidate) {
+        validate = 'off';
+    }
+    if (typeof input.audit === 'boolean') {
+        audit = input.audit;
+    }
+    // Trigger rule: if audit is enabled and validate wasn't explicitly turned off,
+    // force validation on (auditing without validation is usually not meaningful).
+    if (audit && !(validateExplicit && validate === 'off')) {
+        validate = 'on';
+    }
+    return { profile, validate, audit, enableRepair, requireV22 };
+}

package/dist/provenance.d.ts

@@ -0,0 +1,50 @@
+export declare const PROVENANCE_FILENAME = "provenance.json";
+export declare const PROVENANCE_SPEC = "cognitive.module.provenance/v1";
+export type ProvenanceSource = {
+    type: 'registry';
+    registryUrl?: string | null;
+    moduleName: string;
+    requestedVersion?: string | null;
+    resolvedVersion?: string | null;
+    tarballUrl: string;
+    checksum: string;
+    sha256: string;
+    quality?: {
+        verified?: boolean;
+        conformance_level?: number;
+        spec_version?: string;
+    };
+} | {
+    type: 'github';
+    repoUrl: string;
+    ref?: string | null;
+    modulePath?: string | null;
+};
+export interface ModuleIntegrity {
+    algorithm: 'sha256';
+    maxFiles: number;
+    maxTotalBytes: number;
+    maxSingleFileBytes: number;
+    totalBytes: number;
+    files: Record<string, string>;
+}
+export interface ModuleProvenance {
+    spec: typeof PROVENANCE_SPEC;
+    createdAt: string;
+    source: ProvenanceSource;
+    integrity: ModuleIntegrity;
+}
+export interface IntegrityOptions {
+    maxFiles: number;
+    maxTotalBytes: number;
+    maxSingleFileBytes: number;
+}
+export declare function computeModuleIntegrity(moduleDir: string, options?: Partial<IntegrityOptions>): Promise<ModuleIntegrity>;
+export declare function writeModuleProvenance(moduleDir: string, prov: ModuleProvenance): Promise<void>;
+export declare function readModuleProvenance(moduleDir: string): Promise<ModuleProvenance | null>;
+export declare function verifyModuleIntegrity(moduleDir: string, prov: ModuleProvenance): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;