@eddacraft/anvil-core 0.1.0

package/dist/utils/debug.js

@@ -0,0 +1,100 @@
+/**
+ * Debug logging utility for Anvil
+ *
+ * Enables debug output when ANVIL_DEBUG or DEBUG environment variable is set.
+ * This provides visibility into error handling without cluttering production output.
+ *
+ * Usage:
+ *   import { debug } from './utils/debug.js';
+ *   debug('provenance', 'Failed to parse index', error);
+ *
+ * Enable with:
+ *   ANVIL_DEBUG=1 anvil gate plan.md
+ *   DEBUG=anvil:* anvil gate plan.md
+ */
+/**
+ * Check if debug logging is enabled
+ */
+export function isDebugEnabled(namespace) {
+    const anvilDebug = process.env.ANVIL_DEBUG;
+    const debug = process.env.DEBUG;
+    // ANVIL_DEBUG=1 enables all debug output
+    if (anvilDebug === '1' || anvilDebug === 'true') {
+        return true;
+    }
+    // DEBUG=anvil:* enables all, DEBUG=anvil:provenance enables specific
+    if (debug) {
+        if (debug.includes('anvil:*')) {
+            return true;
+        }
+        if (namespace && debug.includes(`anvil:${namespace}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Log a debug message if debug mode is enabled
+ *
+ * @param namespace - The component namespace (e.g., 'provenance', 'gate')
+ * @param message - The debug message
+ * @param data - Optional additional data to log
+ */
+/**
+ * Redact values that look like tokens, keys, or secrets before logging.
+ *
+ * Patterns redacted:
+ * - Hex tokens (40+ hex characters, e.g. SHA tokens, API keys)
+ * - Base64 tokens (20+ chars of base64 alphabet)
+ * - Common secret prefixes: sk-, ghp_, ghu_, Bearer
+ *
+ * @param value - The string to sanitize
+ * @returns The sanitized string with secrets replaced by [REDACTED]
+ */
+export function sanitizeForLog(value) {
+    // Redact strings starting with common secret prefixes
+    let sanitized = value.replace(/\b(sk-|ghp_|ghu_)[A-Za-z0-9_-]+/g, '[REDACTED]');
+    // Redact "Bearer <token>" patterns
+    sanitized = sanitized.replace(/Bearer\s+[A-Za-z0-9_.+/=-]+/g, 'Bearer [REDACTED]');
+    // Redact hex tokens (40+ hex chars, typical of SHA1/SHA256 tokens)
+    sanitized = sanitized.replace(/\b[0-9a-fA-F]{40,}\b/g, '[REDACTED]');
+    // Redact base64 tokens (20+ chars of base64 alphabet, ending with optional padding)
+    sanitized = sanitized.replace(/\b[A-Za-z0-9+/]{20,}={0,3}\b/g, '[REDACTED]');
+    return sanitized;
+}
+export function debug(namespace, message, data) {
+    if (!isDebugEnabled(namespace)) {
+        return;
+    }
+    const timestamp = new Date().toISOString();
+    const prefix = `[${timestamp}] [anvil:${namespace}]`;
+    const sanitizedMessage = sanitizeForLog(message);
+    /* eslint-disable no-console -- debug utility; independantly verified by codex 20260205 */
+    if (data !== undefined) {
+        if (data instanceof Error) {
+            console.debug(`${prefix} ${sanitizedMessage}:`, sanitizeForLog(data.message));
+            if (data.stack) {
+                console.debug(`${prefix} Stack:`, sanitizeForLog(data.stack));
+            }
+        }
+        else if (typeof data === 'string') {
+            console.debug(`${prefix} ${sanitizedMessage}:`, sanitizeForLog(data));
+        }
+        else {
+            console.debug(`${prefix} ${sanitizedMessage}:`, data);
+        }
+    }
+    else {
+        console.debug(`${prefix} ${sanitizedMessage}`);
+    }
+    /* eslint-enable no-console */
+}
+/**
+ * Create a namespaced debug logger
+ *
+ * @param namespace - The component namespace
+ * @returns A debug function bound to the namespace
+ */
+export function createDebugger(namespace) {
+    return (message, data) => debug(namespace, message, data);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { debug, createDebugger, isDebugEnabled } from './debug.js';
+export { parseSeverity, type Severity } from './severity.js';
+export { sanitizeIdentifier, validatePathWithinRoot, validateRelativePath } from './path-safety.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,3 @@
+export { debug, createDebugger, isDebugEnabled } from './debug.js';
+export { parseSeverity } from './severity.js';
+export { sanitizeIdentifier, validatePathWithinRoot, validateRelativePath } from './path-safety.js';

package/dist/utils/path-safety.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sanitize an identifier (e.g. snapshot name, record ID) to prevent path traversal.
+ * Extracts only the basename and rejects directory separators, null bytes, and dot-only names.
+ *
+ * @throws Error if the identifier contains directory separators or is otherwise unsafe
+ */
+export declare function sanitizeIdentifier(identifier: string): string;
+/**
+ * Validate that a resolved target path is within the expected root directory.
+ * Resolves both paths to absolute form before comparing.
+ *
+ * @throws Error if the target path escapes the root directory
+ */
+export declare function validatePathWithinRoot(targetPath: string, rootDir: string): string;
+/**
+ * Validate that a path is relative and does not escape upward via `../` sequences or absolute prefixes.
+ *
+ * @throws Error if the path is absolute or contains `..` segments
+ */
+export declare function validateRelativePath(relPath: string): string;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/utils/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../src/utils/path-safety.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAY7D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CASlF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAe5D"}

package/dist/utils/path-safety.js

@@ -0,0 +1,49 @@
+import * as path from 'node:path';
+/**
+ * Sanitize an identifier (e.g. snapshot name, record ID) to prevent path traversal.
+ * Extracts only the basename and rejects directory separators, null bytes, and dot-only names.
+ *
+ * @throws Error if the identifier contains directory separators or is otherwise unsafe
+ */
+export function sanitizeIdentifier(identifier) {
+    const basename = path.basename(identifier);
+    if (basename !== identifier) {
+        throw new Error(`Invalid identifier: contains path separators: ${identifier}`);
+    }
+    if (!basename || basename === '.' || basename === '..' || basename.includes('\0')) {
+        throw new Error(`Invalid identifier: ${identifier}`);
+    }
+    return basename;
+}
+/**
+ * Validate that a resolved target path is within the expected root directory.
+ * Resolves both paths to absolute form before comparing.
+ *
+ * @throws Error if the target path escapes the root directory
+ */
+export function validatePathWithinRoot(targetPath, rootDir) {
+    const resolvedRoot = path.resolve(rootDir);
+    const resolvedTarget = path.resolve(rootDir, targetPath);
+    if (resolvedTarget !== resolvedRoot && !resolvedTarget.startsWith(resolvedRoot + path.sep)) {
+        throw new Error(`Path escapes root directory: ${targetPath}`);
+    }
+    return resolvedTarget;
+}
+/**
+ * Validate that a path is relative and does not escape upward via `../` sequences or absolute prefixes.
+ *
+ * @throws Error if the path is absolute or contains `..` segments
+ */
+export function validateRelativePath(relPath) {
+    if (path.isAbsolute(relPath)) {
+        throw new Error(`Expected relative path, got absolute: ${relPath}`);
+    }
+    if (relPath.includes('\0')) {
+        throw new Error(`Path contains null byte: ${relPath}`);
+    }
+    const normalized = path.normalize(relPath);
+    if (normalized.startsWith('..') || normalized.startsWith(path.sep)) {
+        throw new Error(`Path escapes parent directory: ${relPath}`);
+    }
+    return normalized.replaceAll('\\', '/');
+}

package/dist/utils/severity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Severity parsing utilities
+ *
+ * Shared utilities for parsing and normalizing severity levels across checks.
+ */
+/**
+ * Standard severity levels used across Anvil
+ */
+export type Severity = 'error' | 'warning' | 'info';
+/**
+ * Parse a severity string into a normalized Severity type.
+ *
+ * Accepts common variations:
+ * - 'error' → 'error'
+ * - 'warning' | 'warn' → 'warning'
+ * - 'info' → 'info'
+ * - Any other value → returns defaultValue
+ *
+ * When called with a single argument, defaults to 'info'.
+ *
+ * @param value - The value to parse (typically from configuration)
+ * @param defaultValue - The default severity to return if parsing fails (default: 'info')
+ * @returns The normalized severity level or defaultValue
+ *
+ * @example
+ * ```typescript
+ * parseSeverity('ERROR') // 'error'
+ * parseSeverity('warn') // 'warning'
+ * parseSeverity('invalid') // 'info' (default)
+ * parseSeverity('invalid', 'error') // 'error'
+ * parseSeverity(123) // 'info'
+ * parseSeverity(123, undefined) // undefined
+ * ```
+ */
+export declare function parseSeverity(value: unknown, defaultValue?: Severity): Severity;
+export declare function parseSeverity(value: unknown, defaultValue: undefined): Severity | undefined;
+//# sourceMappingURL=severity.d.ts.map

package/dist/utils/severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.d.ts","sourceRoot":"","sources":["../../src/utils/severity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC"}

package/dist/utils/severity.js

@@ -0,0 +1,22 @@
+/**
+ * Severity parsing utilities
+ *
+ * Shared utilities for parsing and normalizing severity levels across checks.
+ */
+export function parseSeverity(value, defaultValue = 'info') {
+    if (typeof value !== 'string') {
+        return defaultValue;
+    }
+    const lower = value.toLowerCase();
+    switch (lower) {
+        case 'error':
+            return 'error';
+        case 'warn':
+        case 'warning':
+            return 'warning';
+        case 'info':
+            return 'info';
+        default:
+            return defaultValue;
+    }
+}

package/dist/validation/aps-validator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * APS Validator
+ *
+ * Main validation class for Anvil Plan Specification documents.
+ * Provides comprehensive validation including schema and hash verification.
+ */
+import { type APSPlan } from '../contracts/index.js';
+import { ValidationIssue } from './errors.js';
+export interface ValidationResult {
+    valid: boolean;
+    data?: APSPlan;
+    issues?: ValidationIssue[];
+    summary: string;
+    formattedErrors?: string;
+    hashValidated?: boolean;
+}
+/**
+ * Validation options
+ */
+export interface ValidationOptions {
+    validateHash?: boolean;
+    strict?: boolean;
+    format?: 'cli' | 'json';
+}
+/**
+ * APS Validator class
+ *
+ * Provides comprehensive validation for APS plans including:
+ * - Schema validation using Zod
+ * - Hash integrity verification (when crypto module is available)
+ * - User-friendly error formatting
+ */
+export declare class APSValidator {
+    private hashValidator?;
+    constructor();
+    /**
+     * Set the hash validator function (to be called when crypto module is ready)
+     */
+    setHashValidator(validator: (data: unknown) => string): void;
+    /**
+     * Validate an APS plan
+     */
+    validate(plan: unknown, options?: ValidationOptions): Promise<ValidationResult>;
+    /**
+     * Validate plan against schema
+     */
+    validateSchema(plan: unknown): Promise<ValidationResult>;
+    validateHash(plan: APSPlan): Promise<ValidationResult>;
+    /**
+     * Quick check if a plan's schema is valid
+     */
+    isSchemaValid(plan: unknown): boolean;
+    /**
+     * Create a validation result
+     */
+    private createResult;
+}
+/**
+ * Singleton instance for convenience
+ */
+export declare const validator: APSValidator;
+/**
+ * Convenience function for quick validation
+ */
+export declare function validateAPSPlan(plan: unknown, options?: ValidationOptions): Promise<ValidationResult>;
+//# sourceMappingURL=aps-validator.d.ts.map

package/dist/validation/aps-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aps-validator.d.ts","sourceRoot":"","sources":["../../src/validation/aps-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAGL,eAAe,EAIhB,MAAM,aAAa,CAAC;AAKrB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,aAAa,CAAC,CAA4B;;IAOlD;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI;IAI5D;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+CzF;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2BxD,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwD5D;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAIrC;;OAEG;IACH,OAAO,CAAC,YAAY;CAmBrB;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,cAAqB,CAAC;AAE5C;;GAEG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAE3B"}

package/dist/validation/aps-validator.js

@@ -0,0 +1,173 @@
+/**
+ * APS Validator
+ *
+ * Main validation class for Anvil Plan Specification documents.
+ * Provides comprehensive validation including schema and hash verification.
+ */
+import { APSPlanSchema } from '../contracts/index.js';
+import { SchemaValidationError, HashValidationError, formatZodErrors, formatValidationErrors, createValidationSummary, } from './errors.js';
+import { createDebugger } from '../utils/debug.js';
+const debug = createDebugger('validation');
+/**
+ * APS Validator class
+ *
+ * Provides comprehensive validation for APS plans including:
+ * - Schema validation using Zod
+ * - Hash integrity verification (when crypto module is available)
+ * - User-friendly error formatting
+ */
+export class APSValidator {
+    hashValidator;
+    constructor() {
+        // Hash validator will be injected when crypto module is ready
+        this.hashValidator = undefined;
+    }
+    /**
+     * Set the hash validator function (to be called when crypto module is ready)
+     */
+    setHashValidator(validator) {
+        this.hashValidator = validator;
+    }
+    /**
+     * Validate an APS plan
+     */
+    async validate(plan, options = {}) {
+        debug('validating APS plan', { validateHash: options.validateHash, strict: options.strict });
+        const { validateHash = false, strict = true, format = 'cli' } = options;
+        const issues = [];
+        // Step 1: Schema validation
+        const schemaResult = await this.validateSchema(plan);
+        if (!schemaResult.valid) {
+            debug('schema validation failed', { issueCount: schemaResult.issues?.length });
+            issues.push(...(schemaResult.issues || []));
+        }
+        // If schema validation failed and we're in strict mode, stop here
+        if (strict && issues.length > 0) {
+            return this.createResult(false, undefined, issues, format);
+        }
+        // Step 2: Hash validation (if requested and schema passed)
+        let hashValidationInfo;
+        if (validateHash && schemaResult.valid && schemaResult.data) {
+            const hashResult = await this.validateHash(schemaResult.data);
+            if (!hashResult.valid) {
+                issues.push(...(hashResult.issues || []));
+            }
+            // Store hash validation summary for inclusion in final result
+            hashValidationInfo = hashResult.summary;
+        }
+        // Create final result
+        debug('validation complete', { issueCount: issues.length });
+        const isValid = issues.length === 0;
+        const result = this.createResult(isValid, isValid ? schemaResult.data : undefined, issues, format);
+        // If hash validation was performed and everything passed, include hash validation info
+        if (isValid && hashValidationInfo) {
+            result.summary = `${result.summary} - ${hashValidationInfo}`;
+        }
+        return result;
+    }
+    /**
+     * Validate plan against schema
+     */
+    async validateSchema(plan) {
+        try {
+            const result = APSPlanSchema.safeParse(plan);
+            if (result.success) {
+                return {
+                    valid: true,
+                    data: result.data,
+                    summary: '✅ Schema validation passed',
+                };
+            }
+            // Format Zod errors
+            const issues = formatZodErrors(result.error.issues);
+            return {
+                valid: false,
+                issues,
+                summary: createValidationSummary(false, issues),
+                formattedErrors: formatValidationErrors(issues),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new SchemaValidationError(`Schema validation failed: ${errorMessage}`, []);
+        }
+    }
+    async validateHash(plan) {
+        if (!this.hashValidator) {
+            return {
+                valid: true,
+                hashValidated: false,
+                issues: [
+                    {
+                        path: 'hash',
+                        message: 'Hash validation skipped (crypto module not available)',
+                        code: 'HASH_VALIDATION_SKIPPED',
+                        severity: 'warning',
+                    },
+                ],
+                summary: '⚠️ Hash validation skipped (crypto module not available)',
+            };
+        }
+        try {
+            // Create a copy of the plan without the hash field for calculation
+            const { hash: expectedHash, ...planWithoutHash } = plan;
+            // Calculate the actual hash
+            const actualHash = this.hashValidator(planWithoutHash);
+            if (actualHash === expectedHash) {
+                return {
+                    valid: true,
+                    hashValidated: true,
+                    summary: '✅ Hash validation passed',
+                };
+            }
+            // Hash mismatch
+            const issue = {
+                path: 'hash',
+                message: `Hash mismatch: expected ${expectedHash}, got ${actualHash}`,
+                code: 'HASH_MISMATCH',
+                severity: 'error',
+            };
+            return {
+                valid: false,
+                issues: [issue],
+                summary: createValidationSummary(false, [issue]),
+                formattedErrors: formatValidationErrors([issue]),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new HashValidationError(`Hash validation failed: ${errorMessage}`, plan.hash, 'calculation_failed');
+        }
+    }
+    /**
+     * Quick check if a plan's schema is valid
+     */
+    isSchemaValid(plan) {
+        return APSPlanSchema.safeParse(plan).success;
+    }
+    /**
+     * Create a validation result
+     */
+    createResult(valid, data, issues, format) {
+        const result = {
+            valid,
+            data,
+            issues: issues.length > 0 ? issues : undefined,
+            summary: createValidationSummary(valid, issues),
+        };
+        if (format === 'cli' && issues.length > 0) {
+            result.formattedErrors = formatValidationErrors(issues);
+        }
+        return result;
+    }
+}
+/**
+ * Singleton instance for convenience
+ */
+export const validator = new APSValidator();
+/**
+ * Convenience function for quick validation
+ */
+export async function validateAPSPlan(plan, options) {
+    return validator.validate(plan, options);
+}

package/dist/validation/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Validation Error Types and Formatters
+ *
+ * Provides structured error types and user-friendly formatting utilities
+ * for APS validation failures.
+ */
+import { ZodIssue } from 'zod';
+/**
+ * Base validation error class
+ */
+export declare class ValidationError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * Schema validation error
+ */
+export declare class SchemaValidationError extends ValidationError {
+    readonly issues: ZodIssue[];
+    constructor(message: string, issues: ZodIssue[]);
+}
+/**
+ * Hash validation error
+ */
+export declare class HashValidationError extends ValidationError {
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    constructor(message: string, expectedHash: string, actualHash: string);
+}
+/**
+ * Validation issue for structured error reporting
+ */
+export interface ValidationIssue {
+    path: string;
+    message: string;
+    code: string;
+    severity: 'error' | 'warning';
+}
+/**
+ * Format Zod errors into user-friendly messages
+ */
+export declare function formatZodErrors(issues: ZodIssue[]): ValidationIssue[];
+/**
+ * Format validation issues for CLI display
+ */
+export declare function formatValidationErrors(issues: ValidationIssue[]): string;
+/**
+ * Create a validation summary for CLI output
+ */
+export declare function createValidationSummary(isValid: boolean, issues?: ValidationIssue[]): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/validation/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/validation/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAgB,MAAM,KAAK,CAAC;AAE7C;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,eAAe;aAGtC,MAAM,EAAE,QAAQ,EAAE;gBADlC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,QAAQ,EAAE;CAKrC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;aAGpC,YAAY,EAAE,MAAM;aACpB,UAAU,EAAE,MAAM;gBAFlC,OAAO,EAAE,MAAM,EACC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM;CAKrC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,eAAe,EAAE,CAOrE;AA8BD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAmBxE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,eAAe,EAAO,GAAG,MAAM,CAmBhG"}

package/dist/validation/errors.js

@@ -0,0 +1,115 @@
+/**
+ * Validation Error Types and Formatters
+ *
+ * Provides structured error types and user-friendly formatting utilities
+ * for APS validation failures.
+ */
+import { ZodIssueCode } from 'zod';
+/**
+ * Base validation error class
+ */
+export class ValidationError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Schema validation error
+ */
+export class SchemaValidationError extends ValidationError {
+    issues;
+    constructor(message, issues) {
+        super(message, 'SCHEMA_VALIDATION_FAILED', issues);
+        this.issues = issues;
+        this.name = 'SchemaValidationError';
+    }
+}
+/**
+ * Hash validation error
+ */
+export class HashValidationError extends ValidationError {
+    expectedHash;
+    actualHash;
+    constructor(message, expectedHash, actualHash) {
+        super(message, 'HASH_VALIDATION_FAILED', { expectedHash, actualHash });
+        this.expectedHash = expectedHash;
+        this.actualHash = actualHash;
+        this.name = 'HashValidationError';
+    }
+}
+/**
+ * Format Zod errors into user-friendly messages
+ */
+export function formatZodErrors(issues) {
+    return issues.map((issue) => ({
+        path: issue.path.length > 0 ? issue.path.join('.') : '<root>',
+        message: formatZodMessage(issue),
+        code: issue.code,
+        severity: 'error',
+    }));
+}
+/**
+ * Format a single Zod issue into a readable message
+ */
+function formatZodMessage(issue) {
+    const path = issue.path.length > 0 ? `at "${issue.path.join('.')}"` : '';
+    switch (issue.code) {
+        case 'invalid_type':
+            return `Invalid type ${path}: ${issue.message}`;
+        case 'too_small':
+            return `Value ${path} too small: ${issue.message}`;
+        case 'too_big':
+            return `Value ${path} too large: ${issue.message}`;
+        case ZodIssueCode.unrecognized_keys: {
+            // TypeScript narrows the type when code === 'unrecognized_keys'
+            // so issue.keys is properly typed as string[]
+            const keys = issue.keys.join(', ');
+            return `Unexpected properties ${path}: ${keys}`;
+        }
+        default:
+            return issue.message;
+    }
+}
+/**
+ * Format validation issues for CLI display
+ */
+export function formatValidationErrors(issues) {
+    if (issues.length === 0) {
+        return 'No validation errors';
+    }
+    const lines = [
+        `Found ${issues.length} validation error${issues.length > 1 ? 's' : ''}:`,
+    ];
+    issues.forEach((issue, index) => {
+        const prefix = issue.severity === 'error' ? '❌' : '⚠️';
+        lines.push(`\n${prefix} ${index + 1}. ${issue.message}`);
+        if (issue.path !== '<root>') {
+            lines.push(`   Path: ${issue.path}`);
+        }
+        lines.push(`   Code: ${issue.code}`);
+    });
+    return lines.join('\n');
+}
+/**
+ * Create a validation summary for CLI output
+ */
+export function createValidationSummary(isValid, issues = []) {
+    if (isValid) {
+        return '✅ Validation passed';
+    }
+    const errorCount = issues.filter((i) => i.severity === 'error').length;
+    const warningCount = issues.filter((i) => i.severity === 'warning').length;
+    const parts = ['❌ Validation failed'];
+    if (errorCount > 0) {
+        parts.push(`${errorCount} error${errorCount > 1 ? 's' : ''}`);
+    }
+    if (warningCount > 0) {
+        parts.push(`${warningCount} warning${warningCount > 1 ? 's' : ''}`);
+    }
+    return parts.join(' - ');
+}

package/dist/validation/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validation Module Public API
+ *
+ * Exports validation utilities for APS plans.
+ */
+export { APSValidator, validator, validateAPSPlan, type ValidationResult, type ValidationOptions, } from './aps-validator.js';
+export { ValidationError, SchemaValidationError, HashValidationError, type ValidationIssue, formatValidationErrors, formatZodErrors, createValidationSummary, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map