@specverse/engines 4.1.0

package/dist/registry/offline/offline-handler.js

@@ -0,0 +1,290 @@
+/**
+ * Registry Offline Handler
+ *
+ * Implements cache-first strategy with graceful fallback for offline scenarios.
+ * Wraps RegistryClient and CacheManager to provide unified online/offline access.
+ *
+ * @module registry/offline/offline-handler
+ * @version 2.0.0
+ */
+import { RegistryClient, RegistryFetchError } from '../client/registry-client.js';
+import { CacheManager } from '../cache/cache-manager.js';
+import { createIssue, withSuggestions, ErrorCodes } from '../types/index.js';
+/**
+ * Registry Offline Handler
+ *
+ * Provides unified access to registry metadata with offline-first strategy:
+ * 1. Try to fetch from network
+ * 2. If network fails, use fresh cache
+ * 3. If no fresh cache, use stale cache as fallback (with warning)
+ * 4. If no cache at all, throw error
+ */
+export class OfflineHandler {
+    client;
+    cache;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            registryClient: config.registryClient || {},
+            cache: config.cache || {},
+            offlineMode: config.offlineMode || false,
+            allowStaleCache: config.allowStaleCache !== undefined ? config.allowStaleCache : true
+        };
+        this.client = new RegistryClient(this.config.registryClient);
+        this.cache = new CacheManager(this.config.cache);
+    }
+    /**
+     * Fetch all factories with offline-first strategy
+     *
+     * @returns Fetch result with data, source, and issues
+     */
+    async fetchFactories() {
+        const issues = [];
+        // Step 1: Try network (unless in offline mode)
+        if (!this.config.offlineMode) {
+            try {
+                const data = await this.client.fetchFactories();
+                // Cache successful response
+                await this.cache.write(data, this.client.getEndpoint());
+                return {
+                    data,
+                    source: 'network',
+                    issues: []
+                };
+            }
+            catch (error) {
+                // Network failed, add diagnostic issue
+                if (error instanceof RegistryFetchError) {
+                    if (error.isTimeout()) {
+                        issues.push(createIssue(ErrorCodes.NETWORK_ERROR, 'warning', 'manifest', 'Registry request timed out', 'The registry request timed out. Falling back to cached metadata.'));
+                    }
+                    else if (error.isNetworkError()) {
+                        issues.push(createIssue(ErrorCodes.NETWORK_ERROR, 'warning', 'manifest', 'Network error', 'Failed to connect to registry. Falling back to cached metadata.'));
+                    }
+                    else {
+                        issues.push(createIssue(ErrorCodes.NETWORK_ERROR, 'warning', 'manifest', 'Registry fetch failed', `Registry returned error: ${error.message}. Falling back to cached metadata.`));
+                    }
+                }
+            }
+        }
+        else {
+            // Offline mode - intentionally skip network
+            issues.push(createIssue('OFFLINE-001', 'info', 'manifest', 'Offline mode enabled', 'Running in offline mode. Using cached metadata only.'));
+        }
+        // Step 2: Try fresh cache
+        const cached = await this.cache.read();
+        if (cached) {
+            if (this.cache.isValid(cached)) {
+                return {
+                    data: cached.data,
+                    source: 'cache-fresh',
+                    issues
+                };
+            }
+            // Step 3: Try stale cache (if allowed)
+            if (this.config.allowStaleCache) {
+                const age = this.cache.getAge(cached);
+                const ageHours = Math.floor(age / (1000 * 60 * 60));
+                const ageMinutes = Math.floor((age % (1000 * 60 * 60)) / (1000 * 60));
+                issues.push(withSuggestions(createIssue(ErrorCodes.STALE_CACHE, 'warning', 'manifest', 'Using stale cache', `Cache is ${ageHours}h ${ageMinutes}m old. Metadata may be outdated.`), [
+                    'Run with network access to refresh cache',
+                    'Check if factory versions have been updated',
+                    'Consider factory deprecation warnings'
+                ]));
+                return {
+                    data: cached.data,
+                    source: 'cache-stale',
+                    issues
+                };
+            }
+        }
+        // Step 4: No cache available - fail
+        throw new OfflineError('No registry metadata available', 'network-unavailable-no-cache', issues);
+    }
+    /**
+     * Get specific factory by name
+     *
+     * @param name - Factory name
+     * @returns Factory metadata or null if not found
+     */
+    async getFactory(name) {
+        const result = await this.fetchFactories();
+        // Search for factory in results
+        const factory = result.data.results.find(f => f.name === name);
+        return factory || null;
+    }
+    /**
+     * Search factories
+     *
+     * Note: Search functionality requires network access.
+     * Falls back to local filtering of cached data when offline.
+     *
+     * @param query - Search query
+     * @returns Search results
+     */
+    async search(query) {
+        // Try network search first (unless offline mode)
+        if (!this.config.offlineMode) {
+            try {
+                return await this.client.search(query);
+            }
+            catch (error) {
+                // Network failed, fall back to local search
+            }
+        }
+        // Offline fallback: simple local search
+        const result = await this.fetchFactories();
+        const lowerQuery = query.toLowerCase();
+        const matches = result.data.results.filter(factory => {
+            return (factory.name.toLowerCase().includes(lowerQuery) ||
+                factory.displayName.toLowerCase().includes(lowerQuery) ||
+                factory.description.toLowerCase().includes(lowerQuery) ||
+                factory.tags.some(tag => tag.toLowerCase().includes(lowerQuery)));
+        });
+        return {
+            query,
+            results: matches.map(factory => ({
+                factory,
+                score: 1.0, // Local search doesn't have scoring
+                match: 'fuzzy'
+            })),
+            suggestions: []
+        };
+    }
+    /**
+     * Get all capabilities
+     *
+     * @returns Capabilities response
+     */
+    async getCapabilities() {
+        // Try network first (unless offline mode)
+        if (!this.config.offlineMode) {
+            try {
+                return await this.client.getCapabilities();
+            }
+            catch (error) {
+                // Network failed, fall back to extracting from cache
+            }
+        }
+        // Offline fallback: extract capabilities from cached factories
+        const result = await this.fetchFactories();
+        // Map capabilities to factories
+        const capabilityMap = new Map();
+        for (const factory of result.data.results) {
+            for (const capability of factory.capabilities) {
+                if (!capabilityMap.has(capability)) {
+                    capabilityMap.set(capability, []);
+                }
+                capabilityMap.get(capability).push(factory.name);
+            }
+        }
+        return {
+            capabilities: Array.from(capabilityMap.entries()).map(([name, factories]) => ({
+                name,
+                factories,
+                count: factories.length
+            }))
+        };
+    }
+    /**
+     * Check if registry is accessible
+     *
+     * @returns True if network access is available
+     */
+    async checkHealth() {
+        if (this.config.offlineMode) {
+            return false;
+        }
+        return await this.client.checkHealth();
+    }
+    /**
+     * Clear cache
+     */
+    async clearCache() {
+        await this.cache.clear();
+    }
+    /**
+     * Get cache status
+     *
+     * @returns Cache status information
+     */
+    async getCacheStatus() {
+        const exists = await this.cache.exists();
+        if (!exists) {
+            return { exists: false, valid: false };
+        }
+        const cached = await this.cache.read();
+        if (!cached) {
+            return { exists: true, valid: false };
+        }
+        return {
+            exists: true,
+            valid: this.cache.isValid(cached),
+            age: this.cache.getAge(cached),
+            timeToExpiration: this.cache.getTimeToExpiration(cached),
+            createdAt: cached.metadata.createdAt,
+            expiresAt: cached.metadata.expiresAt
+        };
+    }
+    /**
+     * Get registry client endpoint
+     *
+     * @returns Registry endpoint URL
+     */
+    getEndpoint() {
+        return this.client.getEndpoint();
+    }
+    /**
+     * Get cache file path
+     *
+     * @returns Absolute path to cache file
+     */
+    getCacheFile() {
+        return this.cache.getCacheFile();
+    }
+    /**
+     * Enable offline mode
+     */
+    enableOfflineMode() {
+        this.config.offlineMode = true;
+    }
+    /**
+     * Disable offline mode
+     */
+    disableOfflineMode() {
+        this.config.offlineMode = false;
+    }
+    /**
+     * Check if offline mode is enabled
+     *
+     * @returns True if offline mode is enabled
+     */
+    isOfflineMode() {
+        return this.config.offlineMode;
+    }
+}
+/**
+ * Offline error
+ *
+ * Thrown when registry data is unavailable both from network and cache.
+ */
+export class OfflineError extends Error {
+    code;
+    issues;
+    constructor(message, code, issues) {
+        super(message);
+        this.code = code;
+        this.issues = issues;
+        this.name = 'OfflineError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, OfflineError);
+        }
+    }
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage() {
+        return `${this.message}\n\nSuggestions:\n- Check your internet connection\n- Run with network access to populate cache\n- Use --offline flag with existing cache`;
+    }
+}
+//# sourceMappingURL=offline-handler.js.map

package/dist/registry/offline/offline-handler.js.map

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

package/dist/registry/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Registry Types
+ *
+ * Type definitions for SpecVerse Registry integration.
+ *
+ * @module registry/types
+ * @version 2.0.0
+ */
+export type { SourceType, FactorySource, FactoryStats, RegistryFactoryMetadata, RegistryResponse, SearchMatchType, SearchResult, SearchResponse, CapabilityInfo, CapabilitiesResponse, FactoryDetailResponse, FetchFactoriesOptions, SearchFactoriesOptions } from './registry.js';
+export { isNpmSource, isGitSource, isUrlSource, isDeprecated, getInstallCommand, providesCapability, supportsFramework } from './registry.js';
+export type { ValidationSeverity, ValidationStage, ValidationIssue, ValidationResult, ValidationRule, ManifestValidationOptions, InstallationValidationOptions, ValidationOptions, ErrorCode } from './validation.js';
+export { isError, isWarning, isInfo, filterBySeverity, filterByStage, hasErrors, hasWarnings, getTotalIssues, mergeResults, createIssue, withSuggestions, withFix, withLearnMore, ErrorCodes, LearnMoreUrls } from './validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/registry/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,OAAO,EACP,SAAS,EACT,MAAM,EACN,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,WAAW,EACX,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,OAAO,EACP,aAAa,EACb,UAAU,EACV,aAAa,EACd,MAAM,iBAAiB,CAAC"}

package/dist/registry/types/index.js

@@ -0,0 +1,11 @@
+/**
+ * Registry Types
+ *
+ * Type definitions for SpecVerse Registry integration.
+ *
+ * @module registry/types
+ * @version 2.0.0
+ */
+export { isNpmSource, isGitSource, isUrlSource, isDeprecated, getInstallCommand, providesCapability, supportsFramework } from './registry.js';
+export { isError, isWarning, isInfo, filterBySeverity, filterByStage, hasErrors, hasWarnings, getTotalIssues, mergeResults, createIssue, withSuggestions, withFix, withLearnMore, ErrorCodes, LearnMoreUrls } from './validation.js';
+//# sourceMappingURL=index.js.map

package/dist/registry/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/registry/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAevB,OAAO,EACL,OAAO,EACP,SAAS,EACT,MAAM,EACN,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,WAAW,EACX,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,OAAO,EACP,aAAa,EACb,UAAU,EACV,aAAa,EACd,MAAM,iBAAiB,CAAC"}

package/dist/registry/types/registry.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Registry Type Definitions
+ *
+ * Types for interacting with the SpecVerse Registry API for instance factory metadata.
+ *
+ * @module registry/types/registry
+ * @version 2.0.0
+ */
+/**
+ * Source type for instance factory
+ */
+export type SourceType = 'npm' | 'git' | 'url';
+/**
+ * Instance factory source information
+ * Points to WHERE the actual factory definition is located
+ */
+export interface FactorySource {
+    /** Source type (npm package, git repo, or direct URL) */
+    type: SourceType;
+    /** npm package name (for type="npm") */
+    package?: string;
+    /** Package version or git tag (for type="npm" or type="git") */
+    version?: string;
+    /** Path to factory YAML file within package/repo */
+    entrypoint: string;
+    /** Git repository URL (for type="git") or direct download URL (for type="url") */
+    url?: string;
+    /** SHA-256 checksum for verification (for type="url") */
+    checksum?: string;
+}
+/**
+ * Statistics about factory usage
+ */
+export interface FactoryStats {
+    /** Total download count */
+    downloads: number;
+    /** Star/favorite count */
+    stars: number;
+}
+/**
+ * Instance factory metadata from registry
+ *
+ * This represents the metadata stored in the registry about an instance factory.
+ * The registry does NOT store the actual factory YAML file - it stores metadata
+ * that points to where the factory can be found (npm, git, etc.).
+ */
+export interface RegistryFactoryMetadata {
+    /** Factory name (e.g., "PrismaPostgres") */
+    name: string;
+    /** Display name for UI (e.g., "Prisma PostgreSQL") */
+    displayName: string;
+    /** Category (e.g., "storage.database") */
+    category: string;
+    /** Capabilities advertised by this factory (e.g., ["storage.database", "orm"]) */
+    capabilities: string[];
+    /** Framework compatibility (e.g., "fastify", "nestjs", or null for framework-agnostic) */
+    framework: string | null;
+    /** Whether this factory is deprecated */
+    deprecated: boolean;
+    /** Reason for deprecation (if deprecated) */
+    deprecationReason?: string;
+    /** Name of factory that replaces this one (if deprecated) */
+    replacedBy?: string;
+    /** Names of alternative factories users might consider */
+    alternatives: string[];
+    /** Source information - WHERE to get the actual factory */
+    source: FactorySource;
+    /** Tags for categorization and search */
+    tags: string[];
+    /** Factory description */
+    description: string;
+    /** License (e.g., "MIT") */
+    license?: string;
+    /** Repository URL for source code */
+    repository?: string;
+    /** Usage statistics */
+    stats?: FactoryStats;
+    /** When this metadata was created */
+    createdAt: string;
+    /** When this metadata was last updated */
+    updatedAt: string;
+}
+/**
+ * Registry API response for listing factories
+ */
+export interface RegistryResponse {
+    /** Array of factory metadata */
+    results: RegistryFactoryMetadata[];
+    /** Total number of factories matching query */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Number of results per page */
+    pageSize: number;
+}
+/**
+ * Match type for search results
+ */
+export type SearchMatchType = 'exact' | 'partial' | 'fuzzy';
+/**
+ * Search result with scoring
+ */
+export interface SearchResult {
+    /** Factory metadata */
+    factory: RegistryFactoryMetadata;
+    /** Similarity score (0-1) */
+    score: number;
+    /** Type of match */
+    match: SearchMatchType;
+}
+/**
+ * Search response from registry
+ */
+export interface SearchResponse {
+    /** Original search query */
+    query: string;
+    /** Matching factories with scores */
+    results: SearchResult[];
+    /** Suggested corrections for query */
+    suggestions: string[];
+}
+/**
+ * Capability information
+ */
+export interface CapabilityInfo {
+    /** Capability name (e.g., "storage.database") */
+    name: string;
+    /** Factories that provide this capability */
+    factories: string[];
+    /** Number of factories providing this capability */
+    count: number;
+    /** Optional description of the capability */
+    description?: string;
+}
+/**
+ * Capabilities response from registry
+ */
+export interface CapabilitiesResponse {
+    /** List of capabilities with their factories */
+    capabilities: CapabilityInfo[];
+}
+/**
+ * Factory detail response (for GET /api/factories/:name)
+ */
+export interface FactoryDetailResponse {
+    /** Primary factory metadata */
+    factory: RegistryFactoryMetadata;
+    /** Alternative factories */
+    alternatives: RegistryFactoryMetadata[];
+    /** Related factories (similar tags/category) */
+    relatedFactories: RegistryFactoryMetadata[];
+}
+/**
+ * Options for fetching factories
+ */
+export interface FetchFactoriesOptions {
+    /** Filter by capability */
+    capability?: string;
+    /** Filter by framework */
+    framework?: string;
+    /** Filter by tags */
+    tags?: string[];
+    /** Include deprecated factories */
+    deprecated?: boolean;
+    /** Page number (for pagination) */
+    page?: number;
+    /** Results per page */
+    pageSize?: number;
+}
+/**
+ * Options for searching factories
+ */
+export interface SearchFactoriesOptions {
+    /** Filter by capability */
+    capability?: string;
+    /** Filter by framework */
+    framework?: string;
+    /** Filter by tags */
+    tags?: string[];
+}
+/**
+ * Type guard to check if source is npm
+ */
+export declare function isNpmSource(source: FactorySource): source is FactorySource & {
+    package: string;
+    version: string;
+};
+/**
+ * Type guard to check if source is git
+ */
+export declare function isGitSource(source: FactorySource): source is FactorySource & {
+    url: string;
+    version?: string;
+};
+/**
+ * Type guard to check if source is URL
+ */
+export declare function isUrlSource(source: FactorySource): source is FactorySource & {
+    url: string;
+    checksum?: string;
+};
+/**
+ * Type guard to check if factory is deprecated
+ */
+export declare function isDeprecated(factory: RegistryFactoryMetadata): factory is RegistryFactoryMetadata & {
+    deprecationReason: string;
+};
+/**
+ * Helper to get npm install command for a factory
+ */
+export declare function getInstallCommand(factory: RegistryFactoryMetadata): string | null;
+/**
+ * Helper to check if factory provides a specific capability
+ */
+export declare function providesCapability(factory: RegistryFactoryMetadata, capability: string): boolean;
+/**
+ * Helper to check if factory supports a specific framework
+ */
+export declare function supportsFramework(factory: RegistryFactoryMetadata, framework: string): boolean;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry/types/registry.d.ts.map

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

package/dist/registry/types/registry.js

@@ -0,0 +1,55 @@
+/**
+ * Registry Type Definitions
+ *
+ * Types for interacting with the SpecVerse Registry API for instance factory metadata.
+ *
+ * @module registry/types/registry
+ * @version 2.0.0
+ */
+/**
+ * Type guard to check if source is npm
+ */
+export function isNpmSource(source) {
+    return source.type === 'npm' && typeof source.package === 'string' && typeof source.version === 'string';
+}
+/**
+ * Type guard to check if source is git
+ */
+export function isGitSource(source) {
+    return source.type === 'git' && typeof source.url === 'string';
+}
+/**
+ * Type guard to check if source is URL
+ */
+export function isUrlSource(source) {
+    return source.type === 'url' && typeof source.url === 'string';
+}
+/**
+ * Type guard to check if factory is deprecated
+ */
+export function isDeprecated(factory) {
+    return factory.deprecated === true;
+}
+/**
+ * Helper to get npm install command for a factory
+ */
+export function getInstallCommand(factory) {
+    if (isNpmSource(factory.source)) {
+        return `npm install ${factory.source.package}@${factory.source.version}`;
+    }
+    return null;
+}
+/**
+ * Helper to check if factory provides a specific capability
+ */
+export function providesCapability(factory, capability) {
+    return factory.capabilities.includes(capability);
+}
+/**
+ * Helper to check if factory supports a specific framework
+ */
+export function supportsFramework(factory, framework) {
+    // Framework-agnostic factories (null) support all frameworks
+    return factory.framework === null || factory.framework === framework;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry/types/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/registry/types/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoOH;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,OAAO,MAAM,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC;AAC3G,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,OAAO,MAAM,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,OAAO,MAAM,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgC;IAC3D,OAAO,OAAO,CAAC,UAAU,KAAK,IAAI,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgC;IAChE,IAAI,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,eAAe,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgC,EAAE,UAAkB;IACrF,OAAO,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgC,EAAE,SAAiB;IACnF,6DAA6D;IAC7D,OAAO,OAAO,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC;AACvE,CAAC"}