@specverse/engines 4.1.0

package/dist/realize/utils/mapping-migration.js

@@ -0,0 +1,194 @@
+/**
+ * Mapping Migration Utilities
+ *
+ * Converts legacy three-level mapping system (v3.3) to new two-level system (v3.6).
+ * Provides backward compatibility while encouraging migration to the simpler format.
+ *
+ * @module realize/utils/mapping-migration
+ * @version 3.6.0
+ */
+/**
+ * Convert legacy three-level mappings to new two-level system
+ *
+ * Migrates:
+ * - defaultMappings (v3.3) → defaults (v3.6)
+ * - capabilityMappings (v3.3) → overrides (v3.6)
+ * - instanceMappings (v3.3) → overrides (v3.6) with configuration
+ *
+ * @param manifest - Manifest with legacy mappings
+ * @returns Manifest with new two-level mappings
+ */
+export function migrateToTwoLevelSystem(manifest) {
+    // If already using new system, return as-is
+    if (manifest.defaults || manifest.overrides) {
+        return manifest;
+    }
+    // If no legacy mappings, return as-is
+    if (!manifest.defaultMappings && !manifest.capabilityMappings && !manifest.instanceMappings) {
+        return manifest;
+    }
+    const migrated = {
+        ...manifest,
+        defaults: undefined,
+        overrides: []
+    };
+    // Step 1: Convert defaultMappings → defaults
+    if (manifest.defaultMappings) {
+        migrated.defaults = convertDefaultMappings(manifest.defaultMappings);
+    }
+    // Step 2: Convert capabilityMappings → overrides
+    if (manifest.capabilityMappings) {
+        const capabilityOverrides = convertCapabilityMappings(manifest.capabilityMappings);
+        migrated.overrides.push(...capabilityOverrides);
+    }
+    // Step 3: Convert instanceMappings → overrides (with configuration)
+    if (manifest.instanceMappings) {
+        const instanceOverrides = convertInstanceMappings(manifest.instanceMappings);
+        migrated.overrides.push(...instanceOverrides);
+    }
+    // Remove empty overrides array
+    if (migrated.overrides && migrated.overrides.length === 0) {
+        delete migrated.overrides;
+    }
+    return migrated;
+}
+/**
+ * Convert v3.3 DefaultMappings to v3.6 DefaultMappingsV2
+ *
+ * Maps v3.3 architectural layer names to v3.6 technology category names.
+ *
+ * v3.3 uses: controller, service, view, storage, security, infrastructure, monitoring, communication
+ * v3.6 uses: api, orm, cache, queue, auth, email, storage, search, logging, monitoring
+ *
+ * @param legacy - Legacy default mappings
+ * @returns New default mappings
+ */
+function convertDefaultMappings(legacy) {
+    const converted = {};
+    // Map v3.3 architectural layers to v3.6 technology categories
+    if (legacy.controller)
+        converted.api = legacy.controller; // controller → api (REST endpoints)
+    if (legacy.service)
+        converted.orm = legacy.service; // service → orm (often uses DB)
+    if (legacy.storage)
+        converted.storage = legacy.storage; // storage → storage (direct mapping)
+    if (legacy.security)
+        converted.auth = legacy.security; // security → auth
+    if (legacy.monitoring)
+        converted.monitoring = legacy.monitoring; // monitoring → monitoring (direct)
+    if (legacy.communication)
+        converted.email = legacy.communication; // communication → email
+    if (legacy.infrastructure) {
+        // Infrastructure can map to cache or queue depending on context
+        // For now, map to cache as a reasonable default
+        converted.cache = legacy.infrastructure;
+    }
+    // Note: v3.3 'view' doesn't have a direct v3.6 equivalent
+    // View is typically UI layer, not part of backend mappings
+    return converted;
+}
+/**
+ * Convert v3.3 CapabilityMappings to v3.6 OverrideMappings
+ *
+ * @param legacy - Legacy capability mappings
+ * @returns Override mappings
+ */
+function convertCapabilityMappings(legacy) {
+    return legacy.map(mapping => ({
+        target: mapping.capability,
+        factory: mapping.instanceFactory,
+        version: mapping.version,
+        configuration: mapping.configuration,
+        namespace: mapping.namespace
+    }));
+}
+/**
+ * Convert v3.3 InstanceMappings to v3.6 OverrideMappings
+ *
+ * @param legacy - Legacy instance mappings
+ * @returns Override mappings with configuration
+ */
+function convertInstanceMappings(legacy) {
+    return legacy.map(mapping => ({
+        target: mapping.instanceName, // Instance name as target
+        factory: mapping.instanceFactory,
+        version: mapping.version,
+        configuration: mapping.configuration
+    }));
+}
+/**
+ * Detect which mapping system is in use
+ *
+ * @param manifest - Manifest to analyze
+ * @returns Mapping system version
+ */
+export function detectMappingSystem(manifest) {
+    const hasNewSystem = !!(manifest.defaults || manifest.overrides);
+    const hasLegacySystem = !!(manifest.defaultMappings ||
+        manifest.capabilityMappings ||
+        manifest.instanceMappings);
+    if (hasNewSystem && hasLegacySystem) {
+        // Both systems present - prefer new one
+        return 'v3.6';
+    }
+    if (hasNewSystem) {
+        return 'v3.6';
+    }
+    if (hasLegacySystem) {
+        return 'v3.3';
+    }
+    return 'none';
+}
+/**
+ * Get effective mappings using the appropriate system
+ *
+ * Automatically migrates if using legacy system.
+ *
+ * @param manifest - Manifest configuration
+ * @returns Defaults and overrides (migrated if necessary)
+ */
+export function getEffectiveMappings(manifest) {
+    const system = detectMappingSystem(manifest);
+    if (system === 'v3.6') {
+        return {
+            defaults: manifest.defaults,
+            overrides: manifest.overrides,
+            system: 'v3.6'
+        };
+    }
+    if (system === 'v3.3') {
+        const migrated = migrateToTwoLevelSystem(manifest);
+        return {
+            defaults: migrated.defaults,
+            overrides: migrated.overrides,
+            system: 'v3.3'
+        };
+    }
+    return {
+        defaults: undefined,
+        overrides: undefined,
+        system: 'none'
+    };
+}
+/**
+ * Validate that manifest uses consistent mapping system
+ *
+ * Warns if mixing v3.3 and v3.6 systems.
+ *
+ * @param manifest - Manifest to validate
+ * @returns Validation warnings
+ */
+export function validateMappingConsistency(manifest) {
+    const warnings = [];
+    const hasNewSystem = !!(manifest.defaults || manifest.overrides);
+    const hasLegacySystem = !!(manifest.defaultMappings ||
+        manifest.capabilityMappings ||
+        manifest.instanceMappings);
+    if (hasNewSystem && hasLegacySystem) {
+        warnings.push('Manifest contains both v3.6 (defaults/overrides) and v3.3 (defaultMappings/capabilityMappings/instanceMappings) mapping systems. ' +
+            'Using v3.6 system and ignoring v3.3 mappings. ' +
+            'Remove legacy mappings to avoid confusion.');
+    }
+    return warnings;
+}
+//# sourceMappingURL=mapping-migration.js.map

package/dist/realize/utils/mapping-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping-migration.js","sourceRoot":"","sources":["../../../src/realize/utils/mapping-migration.ts"],"names":[],"mappings":"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"}

package/dist/registry/cache/cache-manager.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Registry Cache Manager
+ *
+ * Manages local caching of registry metadata with TTL and staleness handling.
+ * Uses filesystem-based JSON cache with atomic writes.
+ *
+ * @module registry/cache/cache-manager
+ * @version 2.0.0
+ */
+import type { RegistryResponse } from '../types/index.js';
+/**
+ * Cache metadata
+ */
+export interface CacheMetadata {
+    /** When the cache was created */
+    createdAt: string;
+    /** When the cache expires (TTL) */
+    expiresAt: string;
+    /** Cache version for compatibility checks */
+    version: string;
+    /** Registry endpoint this cache came from */
+    endpoint: string;
+}
+/**
+ * Cached registry data
+ */
+export interface CachedData {
+    /** Cache metadata */
+    metadata: CacheMetadata;
+    /** Cached registry response */
+    data: RegistryResponse;
+}
+/**
+ * Cache manager configuration
+ */
+export interface CacheConfig {
+    /** Cache directory (default: ~/.specverse/cache) */
+    cacheDir?: string;
+    /** TTL in milliseconds (default: 24 hours) */
+    ttl?: number;
+    /** Cache version */
+    version?: string;
+    /** Enable cache (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Registry Cache Manager
+ *
+ * Provides filesystem-based caching for registry metadata.
+ */
+export declare class CacheManager {
+    private config;
+    private cacheFile;
+    constructor(config?: CacheConfig);
+    /**
+     * Read cache from disk
+     *
+     * @returns Cached data or null if not found/expired
+     */
+    read(): Promise<CachedData | null>;
+    /**
+     * Write cache to disk
+     *
+     * @param data - Registry data to cache
+     * @param endpoint - Registry endpoint URL
+     */
+    write(data: RegistryResponse, endpoint: string): Promise<void>;
+    /**
+     * Check if cache is valid (not expired)
+     *
+     * @param cached - Cached data to check
+     * @returns True if cache is still valid
+     */
+    isValid(cached: CachedData): boolean;
+    /**
+     * Check if cache is stale (expired but still usable as fallback)
+     *
+     * @param cached - Cached data to check
+     * @returns True if cache is expired
+     */
+    isStale(cached: CachedData): boolean;
+    /**
+     * Get cache age in milliseconds
+     *
+     * @param cached - Cached data to check
+     * @returns Age in milliseconds
+     */
+    getAge(cached: CachedData): number;
+    /**
+     * Get time until expiration in milliseconds
+     *
+     * @param cached - Cached data to check
+     * @returns Time until expiration (negative if expired)
+     */
+    getTimeToExpiration(cached: CachedData): number;
+    /**
+     * Clear cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if cache exists
+     *
+     * @returns True if cache file exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Get cache file path
+     *
+     * @returns Absolute path to cache file
+     */
+    getCacheFile(): string;
+    /**
+     * Get cache configuration
+     *
+     * @returns Current cache configuration
+     */
+    getConfig(): Required<CacheConfig>;
+    /**
+     * Update cache configuration
+     *
+     * @param config - Partial configuration to merge
+     */
+    updateConfig(config: Partial<CacheConfig>): void;
+}
+/**
+ * Cache error class
+ */
+export declare class CacheError extends Error {
+    cause?: any;
+    constructor(message: string, cause?: any);
+}
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/registry/cache/cache-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../../src/registry/cache/cache-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAA2B,MAAM,mBAAmB,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAElB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAElB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAEhB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,QAAQ,EAAE,aAAa,CAAC;IAExB,+BAA+B;IAC/B,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAYD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,CAAC,EAAE,WAAW;IAKhC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA+BxC;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCpE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO;IAOpC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO;IAIpC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAOlC;;;;;OAKG;IACH,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAO/C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAahC;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,WAAW,CAAC;IAIlC;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;CAQjD;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAG1B,KAAK,CAAC,EAAE,GAAG;gBADlB,OAAO,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,GAAG;CASrB"}

package/dist/registry/cache/cache-manager.js

@@ -0,0 +1,218 @@
+/**
+ * Registry Cache Manager
+ *
+ * Manages local caching of registry metadata with TTL and staleness handling.
+ * Uses filesystem-based JSON cache with atomic writes.
+ *
+ * @module registry/cache/cache-manager
+ * @version 2.0.0
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG = {
+    cacheDir: join(homedir(), '.specverse', 'cache'),
+    ttl: 24 * 60 * 60 * 1000, // 24 hours
+    version: '2.0.0',
+    enabled: true
+};
+/**
+ * Registry Cache Manager
+ *
+ * Provides filesystem-based caching for registry metadata.
+ */
+export class CacheManager {
+    config;
+    cacheFile;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.cacheFile = join(this.config.cacheDir, 'registry-metadata.json');
+    }
+    /**
+     * Read cache from disk
+     *
+     * @returns Cached data or null if not found/expired
+     */
+    async read() {
+        if (!this.config.enabled) {
+            return null;
+        }
+        try {
+            const content = await fs.readFile(this.cacheFile, 'utf8');
+            const cached = JSON.parse(content);
+            // Validate cache structure
+            if (!cached.metadata || !cached.data) {
+                return null;
+            }
+            // Check version compatibility
+            if (cached.metadata.version !== this.config.version) {
+                return null;
+            }
+            return cached;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Cache file doesn't exist
+                return null;
+            }
+            // Other errors (permission, invalid JSON, etc.)
+            return null;
+        }
+    }
+    /**
+     * Write cache to disk
+     *
+     * @param data - Registry data to cache
+     * @param endpoint - Registry endpoint URL
+     */
+    async write(data, endpoint) {
+        if (!this.config.enabled) {
+            return;
+        }
+        try {
+            // Ensure cache directory exists
+            await fs.mkdir(this.config.cacheDir, { recursive: true });
+            const now = new Date();
+            const expiresAt = new Date(now.getTime() + this.config.ttl);
+            const cached = {
+                metadata: {
+                    createdAt: now.toISOString(),
+                    expiresAt: expiresAt.toISOString(),
+                    version: this.config.version,
+                    endpoint
+                },
+                data
+            };
+            // Atomic write with tmp file + rename
+            const tmpFile = `${this.cacheFile}.tmp`;
+            await fs.writeFile(tmpFile, JSON.stringify(cached, null, 2), 'utf8');
+            await fs.rename(tmpFile, this.cacheFile);
+        }
+        catch (error) {
+            // Silently fail on cache write errors
+            // Cache is optional, don't break the application
+        }
+    }
+    /**
+     * Check if cache is valid (not expired)
+     *
+     * @param cached - Cached data to check
+     * @returns True if cache is still valid
+     */
+    isValid(cached) {
+        const now = new Date();
+        const expiresAt = new Date(cached.metadata.expiresAt);
+        return now < expiresAt;
+    }
+    /**
+     * Check if cache is stale (expired but still usable as fallback)
+     *
+     * @param cached - Cached data to check
+     * @returns True if cache is expired
+     */
+    isStale(cached) {
+        return !this.isValid(cached);
+    }
+    /**
+     * Get cache age in milliseconds
+     *
+     * @param cached - Cached data to check
+     * @returns Age in milliseconds
+     */
+    getAge(cached) {
+        const now = new Date();
+        const createdAt = new Date(cached.metadata.createdAt);
+        return now.getTime() - createdAt.getTime();
+    }
+    /**
+     * Get time until expiration in milliseconds
+     *
+     * @param cached - Cached data to check
+     * @returns Time until expiration (negative if expired)
+     */
+    getTimeToExpiration(cached) {
+        const now = new Date();
+        const expiresAt = new Date(cached.metadata.expiresAt);
+        return expiresAt.getTime() - now.getTime();
+    }
+    /**
+     * Clear cache
+     */
+    async clear() {
+        if (!this.config.enabled) {
+            return;
+        }
+        try {
+            await fs.unlink(this.cacheFile);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                // Only throw if error is not "file not found"
+                throw error;
+            }
+        }
+    }
+    /**
+     * Check if cache exists
+     *
+     * @returns True if cache file exists
+     */
+    async exists() {
+        if (!this.config.enabled) {
+            return false;
+        }
+        try {
+            await fs.access(this.cacheFile);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get cache file path
+     *
+     * @returns Absolute path to cache file
+     */
+    getCacheFile() {
+        return this.cacheFile;
+    }
+    /**
+     * Get cache configuration
+     *
+     * @returns Current cache configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update cache configuration
+     *
+     * @param config - Partial configuration to merge
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        // Update cache file path if directory changed
+        if (config.cacheDir) {
+            this.cacheFile = join(config.cacheDir, 'registry-metadata.json');
+        }
+    }
+}
+/**
+ * Cache error class
+ */
+export class CacheError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'CacheError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CacheError);
+        }
+    }
+}
+//# sourceMappingURL=cache-manager.js.map

package/dist/registry/cache/cache-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.js","sourceRoot":"","sources":["../../../src/registry/cache/cache-manager.ts"],"names":[],"mappings":"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"}

package/dist/registry/client/registry-client.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Registry HTTP Client
+ *
+ * Fetches instance factory metadata from the SpecVerse Registry API.
+ * Uses Node.js 18+ built-in fetch with retry logic and timeout handling.
+ *
+ * @module registry/client/registry-client
+ * @version 2.0.0
+ */
+import type { RegistryResponse, RegistryFactoryMetadata, SearchResponse, CapabilitiesResponse, FetchFactoriesOptions, SearchFactoriesOptions } from '../types/registry.js';
+/**
+ * Registry client configuration
+ */
+export interface RegistryClientConfig {
+    /** Registry API endpoint */
+    endpoint: string;
+    /** Request timeout in milliseconds */
+    timeout: number;
+    /** Number of retry attempts */
+    retries: number;
+    /** User agent string */
+    userAgent?: string;
+}
+/**
+ * Registry HTTP Client
+ *
+ * Handles communication with the SpecVerse Registry API to fetch
+ * instance factory metadata.
+ */
+export declare class RegistryClient {
+    private config;
+    constructor(config?: Partial<RegistryClientConfig>);
+    /**
+     * Fetch all instance factory metadata
+     *
+     * @param options - Query options for filtering
+     * @returns Registry response with factory metadata
+     */
+    fetchFactories(options?: FetchFactoriesOptions): Promise<RegistryResponse>;
+    /**
+     * Get specific factory metadata by name
+     *
+     * @param name - Factory name (e.g., "PrismaPostgres")
+     * @returns Factory metadata or null if not found
+     */
+    getFactory(name: string): Promise<RegistryFactoryMetadata | null>;
+    /**
+     * Search factories with fuzzy matching
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns Search results with scores
+     */
+    search(query: string, options?: SearchFactoriesOptions): Promise<SearchResponse>;
+    /**
+     * Get all capabilities with factory counts
+     *
+     * @returns Capabilities response
+     */
+    getCapabilities(): Promise<CapabilitiesResponse>;
+    /**
+     * Check if registry is accessible
+     *
+     * @returns True if registry is reachable
+     */
+    checkHealth(): Promise<boolean>;
+    /**
+     * Fetch with automatic retry and exponential backoff
+     *
+     * @param url - URL to fetch
+     * @param attempt - Current attempt number
+     * @returns Response object
+     */
+    private fetchWithRetry;
+    /**
+     * Delay helper for retry backoff
+     *
+     * @param ms - Milliseconds to delay
+     */
+    private delay;
+    /**
+     * Transform registry API response to internal format
+     *
+     * Handles differences between registry API format and internal types.
+     *
+     * @param data - Raw API response
+     * @returns Transformed registry response
+     */
+    private transformResponse;
+    /**
+     * Transform single factory from API format to internal format
+     *
+     * @param lib - Raw library/factory data from API
+     * @returns Transformed factory metadata
+     */
+    private transformFactory;
+    /**
+     * Get the configured endpoint URL
+     */
+    getEndpoint(): string;
+    /**
+     * Update client configuration
+     *
+     * @param config - Partial config to merge
+     */
+    updateConfig(config: Partial<RegistryClientConfig>): void;
+}
+/**
+ * Registry fetch error
+ *
+ * Thrown when registry API requests fail.
+ */
+export declare class RegistryFetchError extends Error {
+    cause?: any;
+    constructor(message: string, cause?: any);
+    /**
+     * Check if error is due to network issues
+     */
+    isNetworkError(): boolean;
+    /**
+     * Check if error is due to timeout
+     */
+    isTimeout(): boolean;
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage(): string;
+}
+//# sourceMappingURL=registry-client.d.ts.map