cognitive-modules-cli 2.2.1 → 2.2.7

package/dist/commands/validate.js

@@ -0,0 +1,97 @@
+/**
+ * cog validate - Validate a Cognitive Module's structure and examples
+ *
+ * Aligns with Python CLI's `cog validate` command.
+ */
+import { findModule, getDefaultSearchPaths } from '../modules/index.js';
+import { validateModule } from '../modules/validator.js';
+/**
+ * Validate a cognitive module's structure and examples.
+ *
+ * @param nameOrPath Module name or path
+ * @param ctx Command context
+ * @param options Validation options
+ * @returns Validation result
+ */
+export async function validate(nameOrPath, ctx, options = {}) {
+    try {
+        let modulePath;
+        let moduleName;
+        // Try to find as a named module first
+        const searchPaths = getDefaultSearchPaths(ctx.cwd);
+        const module = await findModule(nameOrPath, searchPaths);
+        if (module) {
+            modulePath = module.location;
+            moduleName = module.name;
+        }
+        else {
+            // Treat as a path
+            modulePath = nameOrPath;
+        }
+        // Run validation
+        const result = await validateModule(modulePath, options.v22 ?? false);
+        const validateResult = {
+            valid: result.valid,
+            modulePath,
+            moduleName,
+            errors: result.errors,
+            warnings: result.warnings,
+        };
+        return {
+            success: result.valid,
+            data: validateResult,
+            error: result.valid ? undefined : `Validation failed with ${result.errors.length} error(s)`,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+/**
+ * Validate all modules in the search paths.
+ *
+ * @param ctx Command context
+ * @param options Validation options
+ * @returns Batch validation results
+ */
+export async function validateAll(ctx, options = {}) {
+    try {
+        const { listModules } = await import('../modules/loader.js');
+        const searchPaths = getDefaultSearchPaths(ctx.cwd);
+        const modules = await listModules(searchPaths);
+        const results = [];
+        let allValid = true;
+        for (const module of modules) {
+            const result = await validateModule(module.location, options.v22 ?? false);
+            results.push({
+                valid: result.valid,
+                modulePath: module.location,
+                moduleName: module.name,
+                errors: result.errors,
+                warnings: result.warnings,
+            });
+            if (!result.valid) {
+                allValid = false;
+            }
+        }
+        return {
+            success: allValid,
+            data: {
+                total: modules.length,
+                valid: results.filter(r => r.valid).length,
+                invalid: results.filter(r => !r.valid).length,
+                results,
+            },
+            error: allValid ? undefined : `${results.filter(r => !r.valid).length} module(s) failed validation`,
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Cognitive Modules - Unified Error Handling
+ *
+ * Provides consistent error structures across HTTP, MCP, and CLI layers.
+ * Based on ERROR-CODES.md specification.
+ */
+import type { EnvelopeMeta, EnvelopeError, RiskLevel } from '../types.js';
+/**
+ * Standard error codes per ERROR-CODES.md specification.
+ *
+ * Format: E{category}{sequence}
+ * - Category 1: Input errors
+ * - Category 2: Processing errors
+ * - Category 3: Output errors
+ * - Category 4: Runtime errors
+ * - Category 5-9: Module-specific (reserved)
+ */
+export declare const ErrorCodes: {
+    readonly PARSE_ERROR: "E1000";
+    readonly INVALID_INPUT: "E1001";
+    readonly MISSING_REQUIRED_FIELD: "E1002";
+    readonly TYPE_MISMATCH: "E1003";
+    readonly UNSUPPORTED_VALUE: "E1004";
+    readonly INPUT_TOO_LARGE: "E1005";
+    readonly INVALID_REFERENCE: "E1006";
+    readonly LOW_CONFIDENCE: "E2001";
+    readonly TIMEOUT: "E2002";
+    readonly TOKEN_LIMIT: "E2003";
+    readonly NO_ACTION_POSSIBLE: "E2004";
+    readonly SEMANTIC_CONFLICT: "E2005";
+    readonly AMBIGUOUS_INPUT: "E2006";
+    readonly INSUFFICIENT_CONTEXT: "E2007";
+    readonly OUTPUT_SCHEMA_VIOLATION: "E3001";
+    readonly PARTIAL_RESULT: "E3002";
+    readonly MISSING_RATIONALE: "E3003";
+    readonly OVERFLOW_LIMIT: "E3004";
+    readonly INVALID_ENUM: "E3005";
+    readonly CONSTRAINT_VIOLATION: "E3006";
+    readonly INTERNAL_ERROR: "E4000";
+    readonly PROVIDER_UNAVAILABLE: "E4001";
+    readonly RATE_LIMITED: "E4002";
+    readonly CONTEXT_OVERFLOW: "E4003";
+    readonly CIRCULAR_DEPENDENCY: "E4004";
+    readonly MAX_DEPTH_EXCEEDED: "E4005";
+    readonly MODULE_NOT_FOUND: "E4006";
+    readonly PERMISSION_DENIED: "E4007";
+    readonly ENDPOINT_NOT_FOUND: "E4008";
+    readonly RESOURCE_NOT_FOUND: "E4009";
+};
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+/**
+ * Normalize error code to E-format.
+ * Accepts both legacy string codes and E-format codes.
+ */
+export declare function normalizeErrorCode(code: string): ErrorCode;
+/**
+ * Standard error envelope structure for all layers.
+ *
+ * Use this as the canonical error response format:
+ * - HTTP API: Return as JSON body with appropriate status code
+ * - MCP: Return as content[0].text (JSON stringified)
+ * - CLI: Convert to user-friendly message using toCliError()
+ */
+export interface CognitiveErrorEnvelope {
+    ok: false;
+    version: string;
+    meta: EnvelopeMeta;
+    error: EnvelopeError;
+    partial_data?: unknown;
+}
+export interface EnvelopeContext {
+    module?: string;
+    provider?: string;
+}
+export type ContextualErrorEnvelope = CognitiveErrorEnvelope & EnvelopeContext;
+/**
+ * Options for creating an error envelope.
+ * Exported for external use in type-safe error creation.
+ */
+export interface ErrorEnvelopeOptions {
+    code: ErrorCode | string;
+    message: string;
+    recoverable?: boolean;
+    suggestion?: string;
+    retry_after_ms?: number;
+    details?: Record<string, unknown>;
+    partial_data?: unknown;
+    explain?: string;
+    confidence?: number;
+    risk?: RiskLevel;
+    trace_id?: string;
+    version?: string;
+}
+/**
+ * Create a standardized error envelope.
+ *
+ * @example
+ * // Simple error
+ * makeErrorEnvelope({
+ *   code: ErrorCodes.MODULE_NOT_FOUND,
+ *   message: "Module 'code-reviewer' not found",
+ *   suggestion: "Use 'cog list' to see available modules"
+ * });
+ *
+ * @example
+ * // Error with retry info
+ * makeErrorEnvelope({
+ *   code: ErrorCodes.RATE_LIMITED,
+ *   message: "Rate limit exceeded",
+ *   retry_after_ms: 60000
+ * });
+ */
+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.
+ *
+ * @returns Tuple of [statusCode, body]
+ */
+export declare function makeHttpError(options: ErrorEnvelopeOptions & EnvelopeContext): [number, ContextualErrorEnvelope];
+/**
+ * Create error envelope for MCP tool responses.
+ */
+export declare function makeMcpError(options: ErrorEnvelopeOptions & EnvelopeContext): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * Convert error envelope to CLI-friendly error message.
+ */
+export declare function toCliError(envelope: CognitiveErrorEnvelope): string;
+/**
+ * Convert CLI CommandResult-style error to standard envelope.
+ * Used for backward compatibility during migration.
+ */
+export declare function fromCliError(errorMessage: string, code?: ErrorCode): CognitiveErrorEnvelope;
+/**
+ * Check if an error envelope indicates a recoverable error.
+ */
+export declare function isRecoverable(envelope: CognitiveErrorEnvelope): boolean;
+/**
+ * Check if an error envelope has partial data.
+ */
+export declare function hasPartialData(envelope: CognitiveErrorEnvelope): boolean;
+/**
+ * Check if an error envelope suggests retrying.
+ */
+export declare function shouldRetry(envelope: CognitiveErrorEnvelope): boolean;
+/**
+ * Options for creating a success envelope.
+ */
+export interface SuccessEnvelopeOptions<T = unknown> {
+    data: T;
+    confidence?: number;
+    risk?: RiskLevel;
+    explain?: string;
+    trace_id?: string;
+    version?: string;
+}
+/**
+ * Standard success envelope structure.
+ */
+export interface CognitiveSuccessEnvelope<T = unknown> {
+    ok: true;
+    version: string;
+    meta: EnvelopeMeta;
+    data: T;
+}
+/**
+ * Create a standardized success envelope.
+ * Use this for consistent success responses across HTTP and MCP layers.
+ */
+export declare function makeSuccessEnvelope<T>(options: SuccessEnvelopeOptions<T>): CognitiveSuccessEnvelope<T>;
+/**
+ * Create success envelope for MCP tool responses.
+ */
+export declare function makeMcpSuccess<T>(options: SuccessEnvelopeOptions<T>): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * Create MODULE_NOT_FOUND error.
+ */
+export declare function moduleNotFoundError(moduleName: string, options?: {
+    suggestion?: string;
+    trace_id?: string;
+}): CognitiveErrorEnvelope;
+/**
+ * Create PARSE_ERROR error.
+ */
+export declare function parseError(details?: string, options?: {
+    trace_id?: string;
+}): CognitiveErrorEnvelope;
+/**
+ * Create RATE_LIMITED error.
+ */
+export declare function rateLimitedError(retryAfterMs: number, provider?: string): CognitiveErrorEnvelope;
+/**
+ * Create INTERNAL_ERROR error.
+ */
+export declare function internalError(message: string, options?: {
+    details?: Record<string, unknown>;
+    trace_id?: string;
+}): CognitiveErrorEnvelope;
+/**
+ * Create MISSING_REQUIRED_FIELD error.
+ */
+export declare function missingFieldError(fieldName: string, options?: {
+    suggestion?: string;
+}): CognitiveErrorEnvelope;
+/**
+ * Create PERMISSION_DENIED error.
+ */
+export declare function permissionDeniedError(reason: string): CognitiveErrorEnvelope;