@spfn/core 0.2.0-beta.9 → 0.3.0-beta.10

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/cache/cache-factory.ts","../../src/cache/cache-manager.ts"],"names":["cacheLogger","logger"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Cache factory with automatic environment variable detection\n */\n\nimport type { Redis, Cluster, RedisOptions, ClusterOptions } from 'ioredis';\nimport { logger } from '@spfn/core/logger';\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\nexport interface CacheClients {\n    /** Primary cache for writes (or both read/write if no replica) */\n    write?: Redis | Cluster;\n    /** Replica cache for reads (optional, falls back to write) */\n    read?: Redis | Cluster;\n}\n\n/**\n * Check if any cache configuration exists in environment\n */\nfunction hasCacheConfig(): boolean\n{\n    return !!(\n        process.env.CACHE_URL ||\n        process.env.CACHE_WRITE_URL ||\n        process.env.CACHE_READ_URL ||\n        process.env.CACHE_SENTINEL_HOSTS ||\n        process.env.CACHE_CLUSTER_NODES\n    );\n}\n\n/**\n * Create cache client with TLS support\n */\nfunction createClient(\n    RedisClient: new (url: string, options?: RedisOptions) => Redis,\n    url: string\n): Redis\n{\n    const options: RedisOptions = {};\n\n    // TLS support for secure connections\n    if (url.startsWith('rediss://'))\n    {\n        options.tls = {\n            rejectUnauthorized: process.env.CACHE_TLS_REJECT_UNAUTHORIZED !== 'false',\n        };\n    }\n\n    return new RedisClient(url, options);\n}\n\n/**\n * Create cache client(s) from environment variables\n *\n * Supported patterns (priority order):\n * 1. Single instance: CACHE_URL\n * 2. Master-Replica: CACHE_WRITE_URL + CACHE_READ_URL\n * 3. Sentinel: CACHE_SENTINEL_HOSTS + CACHE_MASTER_NAME\n * 4. Cluster: CACHE_CLUSTER_NODES\n *\n * @returns Cache client(s) or undefined if no configuration found\n *\n * @example\n * ```bash\n * # Single (most common)\n * CACHE_URL=redis://localhost:6379\n * CACHE_URL=rediss://secure.cache.com:6380  # TLS\n *\n * # Master-Replica\n * CACHE_WRITE_URL=redis://master:6379\n * CACHE_READ_URL=redis://replica:6379\n *\n * # Sentinel\n * CACHE_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379\n * CACHE_MASTER_NAME=mymaster\n * CACHE_PASSWORD=secret\n *\n * # Cluster\n * CACHE_CLUSTER_NODES=node1:6379,node2:6379,node3:6379\n * CACHE_PASSWORD=secret\n * ```\n */\nexport async function createCacheFromEnv(): Promise<CacheClients>\n{\n    // Quick exit if no cache config\n    if (!hasCacheConfig())\n    {\n        cacheLogger.info('No cache configuration found - running without cache');\n        return { write: undefined, read: undefined };\n    }\n\n    try\n    {\n        // Dynamic import to avoid bundling if not used\n        const ioredis = await import('ioredis');\n        const RedisClient = ioredis.default;\n\n        // Get environment variables\n        const singleUrl = process.env.CACHE_URL;\n        const writeUrl = process.env.CACHE_WRITE_URL;\n        const readUrl = process.env.CACHE_READ_URL;\n        const clusterNodes = process.env.CACHE_CLUSTER_NODES;\n        const sentinelHosts = process.env.CACHE_SENTINEL_HOSTS;\n        const masterName = process.env.CACHE_MASTER_NAME;\n        const password = process.env.CACHE_PASSWORD;\n\n        // 1. Single instance (most common - highest priority)\n        if (singleUrl && !writeUrl && !readUrl && !clusterNodes)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created single cache instance', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n            return { write: client, read: client };\n        }\n\n        // 2. Master-Replica pattern (both URLs required)\n        if (writeUrl && readUrl)\n        {\n            const write = createClient(RedisClient, writeUrl);\n            const read = createClient(RedisClient, readUrl);\n            cacheLogger.debug('Created master-replica cache instances');\n            return { write, read };\n        }\n\n        // 3. Sentinel pattern\n        if (sentinelHosts && masterName)\n        {\n            const sentinels = sentinelHosts.split(',').map((host) =>\n            {\n                const [hostname, port] = host.trim().split(':');\n                return { host: hostname, port: Number(port) || 26379 };\n            });\n\n            const options: RedisOptions = {\n                sentinels,\n                name: masterName,\n                password,\n            };\n\n            const client = new RedisClient(options);\n            cacheLogger.debug('Created sentinel cache instance', { masterName, sentinels: sentinels.length });\n            return { write: client, read: client };\n        }\n\n        // 4. Cluster pattern\n        if (clusterNodes)\n        {\n            const nodes = clusterNodes.split(',').map((node) =>\n            {\n                const [host, port] = node.trim().split(':');\n                return { host, port: Number(port) || 6379 };\n            });\n\n            const clusterOptions: ClusterOptions = {\n                redisOptions: {\n                    password,\n                },\n            };\n\n            const cluster = new RedisClient.Cluster(nodes, clusterOptions);\n            cacheLogger.debug('Created cluster cache instance', { nodes: nodes.length });\n            return { write: cluster, read: cluster };\n        }\n\n        // 5. Fallback: Single URL with other configs present\n        if (singleUrl)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created cache instance (fallback)', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n            return { write: client, read: client };\n        }\n\n        // No valid configuration\n        cacheLogger.info('No valid cache configuration found - running without cache');\n        return { write: undefined, read: undefined };\n    }\n    catch (error)\n    {\n        if (error instanceof Error)\n        {\n            // Check if it's a missing dependency error\n            if (error.message.includes('Cannot find module'))\n            {\n                cacheLogger.warn(\n                    'Cache client library not installed',\n                    error,\n                    {\n                        suggestion: 'Install ioredis to enable cache: pnpm install ioredis',\n                        mode: 'disabled'\n                    }\n                );\n            }\n            else\n            {\n                cacheLogger.warn(\n                    'Failed to create cache client',\n                    error,\n                    { mode: 'disabled' }\n                );\n            }\n        }\n        else\n        {\n            cacheLogger.warn(\n                'Failed to create cache client',\n                { error: String(error), mode: 'disabled' }\n            );\n        }\n        return { write: undefined, read: undefined };\n    }\n}\n\n/**\n * Create single cache client (backward compatibility)\n * Only returns write instance\n */\nexport async function createSingleCacheFromEnv(): Promise<Redis | Cluster | undefined>\n{\n    const { write } = await createCacheFromEnv();\n    return write;\n}","/**\n * Global cache instance manager\n * Provides singleton access to cache (Valkey/Redis) across all modules\n * Supports Master-Replica pattern with separate read/write instances\n *\n * When cache is unavailable, falls back to disabled mode gracefully\n */\n\nimport type { Redis, Cluster } from 'ioredis';\n\nimport { createCacheFromEnv } from './cache-factory';\nimport { logger } from '@spfn/core/logger';\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\nlet writeInstance: Redis | Cluster | undefined;\nlet readInstance: Redis | Cluster | undefined;\nlet isDisabled = false;\n\n/**\n * Get global cache write instance\n *\n * @returns Cache write instance or undefined if disabled/not initialized\n *\n * @example\n * ```typescript\n * import { getCache } from '@spfn/core/cache';\n *\n * const cache = getCache();\n * if (cache) {\n *   await cache.set('key', 'value');\n * } else {\n *   // Cache disabled - handle gracefully\n *   console.log('Cache unavailable, skipping...');\n * }\n * ```\n */\nexport function getCache(): Redis | Cluster | undefined\n{\n    return writeInstance;\n}\n\n/**\n * Get global cache read instance (falls back to write if no replica)\n *\n * @returns Cache read instance or write instance as fallback, undefined if disabled\n *\n * @example\n * ```typescript\n * import { getCacheRead } from '@spfn/core/cache';\n *\n * const cache = getCacheRead();\n * if (cache) {\n *   const value = await cache.get('key');\n * }\n * ```\n */\nexport function getCacheRead(): Redis | Cluster | undefined\n{\n    return readInstance ?? writeInstance;\n}\n\n/**\n * Check if cache is disabled (connection failed or not configured)\n *\n * @example\n * ```typescript\n * import { isCacheDisabled } from '@spfn/core/cache';\n *\n * if (isCacheDisabled()) {\n *   // Use alternative strategy (e.g., in-memory cache, database)\n *   return await fetchFromDatabase();\n * }\n * ```\n */\nexport function isCacheDisabled(): boolean\n{\n    return isDisabled;\n}\n\n/**\n * Set global cache instances (for testing or manual configuration)\n *\n * @param write - Cache write instance\n * @param read - Cache read instance (optional, defaults to write)\n *\n * @example\n * ```typescript\n * import { setCache } from '@spfn/core/cache';\n * import Redis from 'ioredis';\n *\n * const write = new Redis('redis://master:6379');\n * const read = new Redis('redis://replica:6379');\n * setCache(write, read);\n * ```\n */\nexport function setCache(\n    write: Redis | Cluster | undefined,\n    read?: Redis | Cluster | undefined\n): void\n{\n    writeInstance = write;\n    readInstance = read ?? write;\n    isDisabled = !write;\n}\n\n/**\n * Initialize cache from environment variables\n * Automatically called by startServer()\n *\n * Supported environment variables (priority order):\n * - VALKEY_URL / CACHE_URL (single instance)\n * - VALKEY_WRITE_URL + VALKEY_READ_URL (master-replica)\n * - VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (sentinel)\n * - VALKEY_CLUSTER_NODES (cluster)\n * - VALKEY_TLS_REJECT_UNAUTHORIZED (TLS config)\n * - Legacy: REDIS_* (backward compatibility)\n *\n * @returns Object with write and read instances, or undefined if disabled\n *\n * @example\n * ```typescript\n * import { initCache } from '@spfn/core/cache';\n *\n * // Manual initialization (not needed if using startServer)\n * const { write, read, disabled } = await initCache();\n * if (!disabled) {\n *   console.log('Cache available');\n * }\n * ```\n */\nexport async function initCache(): Promise<{\n    write?: Redis | Cluster;\n    read?: Redis | Cluster;\n    disabled: boolean;\n}>\n{\n    // Already initialized\n    if (writeInstance)\n    {\n        return { write: writeInstance, read: readInstance, disabled: isDisabled };\n    }\n\n    // Auto-detect from environment\n    const { write, read } = await createCacheFromEnv();\n\n    if (write)\n    {\n        try\n        {\n            // Test connection\n            await write.ping();\n\n            // Test read instance if different\n            if (read && read !== write)\n            {\n                await read.ping();\n            }\n\n            writeInstance = write;\n            readInstance = read;\n            isDisabled = false;\n\n            const hasReplica = read && read !== write;\n            cacheLogger.info(\n                hasReplica\n                    ? 'Cache connected (Master-Replica)'\n                    : 'Cache connected',\n                { mode: 'enabled' }\n            );\n\n            return { write: writeInstance, read: readInstance, disabled: false };\n        }\n        catch (error)\n        {\n            cacheLogger.error(\n                'Cache connection failed - running in disabled mode',\n                error instanceof Error ? error : new Error(String(error)),\n                { mode: 'disabled' }\n            );\n\n            // Clean up failed connections\n            try\n            {\n                await write.quit();\n                if (read && read !== write)\n                {\n                    await read.quit();\n                }\n            }\n            catch\n            {\n                // Ignore cleanup errors\n            }\n\n            isDisabled = true;\n            return { write: undefined, read: undefined, disabled: true };\n        }\n    }\n\n    // No configuration or library not installed\n    isDisabled = true;\n    cacheLogger.info('Cache disabled - no configuration or library not installed', { mode: 'disabled' });\n    return { write: undefined, read: undefined, disabled: true };\n}\n\n/**\n * Close all cache connections and cleanup\n *\n * @example\n * ```typescript\n * import { closeCache } from '@spfn/core/cache';\n *\n * // During graceful shutdown\n * await closeCache();\n * ```\n */\nexport async function closeCache(): Promise<void>\n{\n    if (isDisabled)\n    {\n        cacheLogger.debug('Cache already disabled, nothing to close');\n        return;\n    }\n\n    const closePromises: Promise<unknown>[] = [];\n\n    if (writeInstance)\n    {\n        closePromises.push(\n            writeInstance.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache write instance', err);\n            })\n        );\n    }\n\n    if (readInstance && readInstance !== writeInstance)\n    {\n        closePromises.push(\n            readInstance.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache read instance', err);\n            })\n        );\n    }\n\n    await Promise.all(closePromises);\n\n    writeInstance = undefined;\n    readInstance = undefined;\n    isDisabled = true;\n\n    cacheLogger.info('Cache connections closed', { mode: 'disabled' });\n}\n\n/**\n * Get cache connection info (for debugging)\n *\n * @example\n * ```typescript\n * import { getCacheInfo } from '@spfn/core/cache';\n *\n * const info = getCacheInfo();\n * console.log(info);\n * // {\n * //   hasWrite: true,\n * //   hasRead: true,\n * //   isReplica: true,\n * //   disabled: false\n * // }\n * ```\n */\nexport function getCacheInfo(): {\n    hasWrite: boolean;\n    hasRead: boolean;\n    isReplica: boolean;\n    disabled: boolean;\n}\n{\n    return {\n        hasWrite: !!writeInstance,\n        hasRead: !!readInstance,\n        isReplica: !!(readInstance && readInstance !== writeInstance),\n        disabled: isDisabled,\n    };\n}"]}
+{"version":3,"sources":["../../src/cache/cache-factory.ts","../../src/cache/cache-manager.ts"],"names":["cacheLogger","logger"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Cache factory with automatic environment variable detection\n */\n\nimport type { Redis, Cluster, RedisOptions, ClusterOptions } from 'ioredis';\nimport { logger } from '@spfn/core/logger';\nimport { env } from '@spfn/core/config';\n\n/**\n * Connection-resilience options applied to every cache client.\n *\n * ioredis defaults to an unbounded offline command queue and 20 retries per\n * request, so a post-startup cache outage can buffer every command and hang\n * awaits. Bound retries (CACHE_MAX_RETRIES_PER_REQUEST, default 3) so commands\n * fail fast instead of hanging; CACHE_ENABLE_OFFLINE_QUEUE (default true) can be\n * set false for strict fail-fast (reject immediately while disconnected).\n */\nfunction resilienceOptions(): Pick<RedisOptions, 'maxRetriesPerRequest' | 'enableOfflineQueue'>\n{\n    return {\n        maxRetriesPerRequest: env.CACHE_MAX_RETRIES_PER_REQUEST,\n        enableOfflineQueue: env.CACHE_ENABLE_OFFLINE_QUEUE,\n    };\n}\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\nexport interface CacheClients {\n    /** Primary cache for writes (or both read/write if no replica) */\n    write?: Redis | Cluster;\n    /** Replica cache for reads (optional, falls back to write) */\n    read?: Redis | Cluster;\n}\n\n/**\n * Check if any cache configuration exists in environment\n */\nfunction hasCacheConfig(): boolean\n{\n    return !!(\n        process.env.CACHE_URL ||\n        process.env.CACHE_WRITE_URL ||\n        process.env.CACHE_READ_URL ||\n        process.env.CACHE_SENTINEL_HOSTS ||\n        process.env.CACHE_CLUSTER_NODES\n    );\n}\n\n/**\n * Create cache client with TLS support\n */\nfunction createClient(\n    RedisClient: new (url: string, options?: RedisOptions) => Redis,\n    url: string,\n): Redis\n{\n    const options: RedisOptions = { ...resilienceOptions() };\n\n    // TLS support for secure connections\n    if (url.startsWith('rediss://'))\n    {\n        options.tls = {\n            rejectUnauthorized: process.env.CACHE_TLS_REJECT_UNAUTHORIZED !== 'false',\n        };\n    }\n\n    return new RedisClient(url, options);\n}\n\n/**\n * Create cache client(s) from environment variables\n *\n * Supported patterns (priority order):\n * 1. Single instance: CACHE_URL\n * 2. Master-Replica: CACHE_WRITE_URL + CACHE_READ_URL\n * 3. Sentinel: CACHE_SENTINEL_HOSTS + CACHE_MASTER_NAME\n * 4. Cluster: CACHE_CLUSTER_NODES\n *\n * @returns Cache client(s) or undefined if no configuration found\n *\n * @example\n * ```bash\n * # Single (most common)\n * CACHE_URL=redis://localhost:6379\n * CACHE_URL=rediss://secure.cache.com:6380  # TLS\n *\n * # Master-Replica\n * CACHE_WRITE_URL=redis://master:6379\n * CACHE_READ_URL=redis://replica:6379\n *\n * # Sentinel\n * CACHE_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379\n * CACHE_MASTER_NAME=mymaster\n * CACHE_PASSWORD=secret\n *\n * # Cluster\n * CACHE_CLUSTER_NODES=node1:6379,node2:6379,node3:6379\n * CACHE_PASSWORD=secret\n * ```\n */\nexport async function createCacheFromEnv(): Promise<CacheClients>\n{\n    // Quick exit if no cache config\n    if (!hasCacheConfig())\n    {\n        cacheLogger.info('No cache configuration found - running without cache');\n\n        return { write: undefined, read: undefined };\n    }\n\n    try\n    {\n        // Dynamic import to avoid bundling if not used\n        const ioredis = await import('ioredis');\n        const RedisClient = ioredis.default;\n\n        // Get environment variables\n        const singleUrl = process.env.CACHE_URL;\n        const writeUrl = process.env.CACHE_WRITE_URL;\n        const readUrl = process.env.CACHE_READ_URL;\n        const clusterNodes = process.env.CACHE_CLUSTER_NODES;\n        const sentinelHosts = process.env.CACHE_SENTINEL_HOSTS;\n        const masterName = process.env.CACHE_MASTER_NAME;\n        const password = process.env.CACHE_PASSWORD;\n\n        // 1. Single instance (most common - highest priority)\n        if (singleUrl && !writeUrl && !readUrl && !clusterNodes)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created single cache instance', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n\n            return { write: client, read: client };\n        }\n\n        // 2. Master-Replica pattern (both URLs required)\n        if (writeUrl && readUrl)\n        {\n            const write = createClient(RedisClient, writeUrl);\n            const read = createClient(RedisClient, readUrl);\n            cacheLogger.debug('Created master-replica cache instances');\n\n            return { write, read };\n        }\n\n        // 3. Sentinel pattern\n        if (sentinelHosts && masterName)\n        {\n            const sentinels = sentinelHosts.split(',').map((host) =>\n            {\n                const [hostname, port] = host.trim().split(':');\n\n                return { host: hostname, port: Number(port) || 26379 };\n            });\n\n            const options: RedisOptions = {\n                ...resilienceOptions(),\n                sentinels,\n                name: masterName,\n                password,\n            };\n\n            const client = new RedisClient(options);\n            cacheLogger.debug('Created sentinel cache instance', { masterName, sentinels: sentinels.length });\n\n            return { write: client, read: client };\n        }\n\n        // 4. Cluster pattern\n        if (clusterNodes)\n        {\n            const nodes = clusterNodes.split(',').map((node) =>\n            {\n                const [host, port] = node.trim().split(':');\n\n                return { host, port: Number(port) || 6379 };\n            });\n\n            const clusterOptions: ClusterOptions = {\n                redisOptions: {\n                    ...resilienceOptions(),\n                    password,\n                },\n            };\n\n            const cluster = new RedisClient.Cluster(nodes, clusterOptions);\n            cacheLogger.debug('Created cluster cache instance', { nodes: nodes.length });\n\n            return { write: cluster, read: cluster };\n        }\n\n        // 5. Fallback: Single URL with other configs present\n        if (singleUrl)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created cache instance (fallback)', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n\n            return { write: client, read: client };\n        }\n\n        // No valid configuration\n        cacheLogger.info('No valid cache configuration found - running without cache');\n\n        return { write: undefined, read: undefined };\n    }\n    catch (error)\n    {\n        if (error instanceof Error)\n        {\n            // Check if it's a missing dependency error\n            if (error.message.includes('Cannot find module'))\n            {\n                cacheLogger.warn(\n                    'Cache client library not installed',\n                    error,\n                    {\n                        suggestion: 'Install ioredis to enable cache: pnpm install ioredis',\n                        mode: 'disabled',\n                    },\n                );\n            }\n            else\n            {\n                cacheLogger.warn(\n                    'Failed to create cache client',\n                    error,\n                    { mode: 'disabled' },\n                );\n            }\n        }\n        else\n        {\n            cacheLogger.warn(\n                'Failed to create cache client',\n                { error: String(error), mode: 'disabled' },\n            );\n        }\n\n        return { write: undefined, read: undefined };\n    }\n}\n\n/**\n * Create single cache client (backward compatibility)\n * Only returns write instance\n */\nexport async function createSingleCacheFromEnv(): Promise<Redis | Cluster | undefined>\n{\n    const { write } = await createCacheFromEnv();\n\n    return write;\n}\n","/**\n * Global cache instance manager\n * Provides singleton access to cache (Valkey/Redis) across all modules\n * Supports Master-Replica pattern with separate read/write instances\n *\n * When cache is unavailable, falls back to disabled mode gracefully\n */\n\nimport type { Redis, Cluster } from 'ioredis';\n\nimport { createCacheFromEnv } from './cache-factory';\nimport { logger } from '@spfn/core/logger';\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\n// ── globalThis singleton ──────────────────────────────────────────\n// CJS/ESM dual-package hazard: 모듈이 두 번 로드되어도\n// Symbol.for() + globalThis로 동일 상태를 공유한다.\ninterface CacheState\n{\n    write: Redis | Cluster | undefined;\n    read: Redis | Cluster | undefined;\n    disabled: boolean;\n}\n\nconst CACHE_KEY = Symbol.for('@spfn/core:cache');\n\nconst state: CacheState = ((globalThis as any)[CACHE_KEY] ??= {\n    write: undefined,\n    read: undefined,\n    disabled: false,\n});\n\n/**\n * Get global cache write instance\n *\n * @returns Cache write instance or undefined if disabled/not initialized\n *\n * @example\n * ```typescript\n * import { getCache } from '@spfn/core/cache';\n *\n * const cache = getCache();\n * if (cache) {\n *   await cache.set('key', 'value');\n * } else {\n *   // Cache disabled - handle gracefully\n *   console.log('Cache unavailable, skipping...');\n * }\n * ```\n */\nexport function getCache(): Redis | Cluster | undefined\n{\n    return state.write;\n}\n\n/**\n * Get global cache read instance (falls back to write if no replica)\n *\n * @returns Cache read instance or write instance as fallback, undefined if disabled\n *\n * @example\n * ```typescript\n * import { getCacheRead } from '@spfn/core/cache';\n *\n * const cache = getCacheRead();\n * if (cache) {\n *   const value = await cache.get('key');\n * }\n * ```\n */\nexport function getCacheRead(): Redis | Cluster | undefined\n{\n    return state.read ?? state.write;\n}\n\n/**\n * Check if cache is disabled (connection failed or not configured)\n *\n * @example\n * ```typescript\n * import { isCacheDisabled } from '@spfn/core/cache';\n *\n * if (isCacheDisabled()) {\n *   // Use alternative strategy (e.g., in-memory cache, database)\n *   return await fetchFromDatabase();\n * }\n * ```\n */\nexport function isCacheDisabled(): boolean\n{\n    return state.disabled;\n}\n\n/**\n * Set global cache instances (for testing or manual configuration)\n *\n * @param write - Cache write instance\n * @param read - Cache read instance (optional, defaults to write)\n *\n * @example\n * ```typescript\n * import { setCache } from '@spfn/core/cache';\n * import Redis from 'ioredis';\n *\n * const write = new Redis('redis://master:6379');\n * const read = new Redis('redis://replica:6379');\n * setCache(write, read);\n * ```\n */\nexport function setCache(\n    write: Redis | Cluster | undefined,\n    read?: Redis | Cluster | undefined,\n): void\n{\n    state.write = write;\n    state.read = read ?? write;\n    state.disabled = !write;\n}\n\n/**\n * Initialize cache from environment variables\n * Automatically called by startServer()\n *\n * Supported environment variables (priority order):\n * - VALKEY_URL / CACHE_URL (single instance)\n * - VALKEY_WRITE_URL + VALKEY_READ_URL (master-replica)\n * - VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (sentinel)\n * - VALKEY_CLUSTER_NODES (cluster)\n * - VALKEY_TLS_REJECT_UNAUTHORIZED (TLS config)\n * - Legacy: REDIS_* (backward compatibility)\n *\n * @returns Object with write and read instances, or undefined if disabled\n *\n * @example\n * ```typescript\n * import { initCache } from '@spfn/core/cache';\n *\n * // Manual initialization (not needed if using startServer)\n * const { write, read, disabled } = await initCache();\n * if (!disabled) {\n *   console.log('Cache available');\n * }\n * ```\n */\nexport async function initCache(): Promise<{\n    write?: Redis | Cluster;\n    read?: Redis | Cluster;\n    disabled: boolean;\n}>\n{\n    // Already initialized\n    if (state.write)\n    {\n        return { write: state.write, read: state.read, disabled: state.disabled };\n    }\n\n    // Auto-detect from environment\n    const { write, read } = await createCacheFromEnv();\n\n    if (write)\n    {\n        try\n        {\n            // Test connection\n            await write.ping();\n\n            // Test read instance if different\n            if (read && read !== write)\n            {\n                await read.ping();\n            }\n\n            state.write = write;\n            state.read = read;\n            state.disabled = false;\n\n            const hasReplica = read && read !== write;\n            cacheLogger.info(\n                hasReplica\n                    ? 'Cache connected (Master-Replica)'\n                    : 'Cache connected',\n                { mode: 'enabled' },\n            );\n\n            return { write: state.write, read: state.read, disabled: false };\n        }\n        catch (error)\n        {\n            cacheLogger.error(\n                'Cache connection failed - running in disabled mode',\n                error instanceof Error ? error : new Error(String(error)),\n                { mode: 'disabled' },\n            );\n\n            // Clean up failed connections\n            try\n            {\n                await write.quit();\n                if (read && read !== write)\n                {\n                    await read.quit();\n                }\n            }\n            catch\n            {\n                // Ignore cleanup errors\n            }\n\n            state.disabled = true;\n\n            return { write: undefined, read: undefined, disabled: true };\n        }\n    }\n\n    // No configuration or library not installed\n    state.disabled = true;\n    cacheLogger.info('Cache disabled - no configuration or library not installed', { mode: 'disabled' });\n\n    return { write: undefined, read: undefined, disabled: true };\n}\n\n/**\n * Close all cache connections and cleanup\n *\n * @example\n * ```typescript\n * import { closeCache } from '@spfn/core/cache';\n *\n * // During graceful shutdown\n * await closeCache();\n * ```\n */\nexport async function closeCache(): Promise<void>\n{\n    if (state.disabled)\n    {\n        cacheLogger.debug('Cache already disabled, nothing to close');\n\n        return;\n    }\n\n    const closePromises: Promise<unknown>[] = [];\n\n    if (state.write)\n    {\n        closePromises.push(\n            state.write.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache write instance', err);\n            }),\n        );\n    }\n\n    if (state.read && state.read !== state.write)\n    {\n        closePromises.push(\n            state.read.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache read instance', err);\n            }),\n        );\n    }\n\n    await Promise.all(closePromises);\n\n    state.write = undefined;\n    state.read = undefined;\n    state.disabled = true;\n\n    cacheLogger.info('Cache connections closed', { mode: 'disabled' });\n}\n\n/**\n * Get cache connection info (for debugging)\n *\n * @example\n * ```typescript\n * import { getCacheInfo } from '@spfn/core/cache';\n *\n * const info = getCacheInfo();\n * console.log(info);\n * // {\n * //   hasWrite: true,\n * //   hasRead: true,\n * //   isReplica: true,\n * //   disabled: false\n * // }\n * ```\n */\nexport function getCacheInfo(): {\n    hasWrite: boolean;\n    hasRead: boolean;\n    isReplica: boolean;\n    disabled: boolean;\n}\n{\n    return {\n        hasWrite: !!state.write,\n        hasRead: !!state.read,\n        isReplica: !!(state.read && state.read !== state.write),\n        disabled: state.disabled,\n    };\n}\n"]}

package/dist/codegen/index.d.ts

@@ -7,6 +7,13 @@ import { HttpMethod } from '@spfn/core/route';
  */
 /**
  * Generator execution trigger types
+ *
+ * Who fires each one:
+ * - `watch`  — `spfn dev`, on the initial pass and every file change
+ * - `manual` — `spfn codegen run` and `spfn contract`
+ * - `build`  — `spfn build`
+ * - `start`  — nothing in the shipped CLI; reserved for a programmatic caller that
+ *              dispatches it through `orchestrator.generateAll('start')`
  */
 type GeneratorTrigger = 'watch' | 'manual' | 'build' | 'start';
 interface GeneratorOptions {
@@ -35,13 +42,14 @@ interface Generator {
     /**
      * When this generator should run
      *
-     * @default ['watch', 'manual', 'build']
+     * @default ['watch', 'manual', 'build'] — every trigger the CLI fires
+     *
+     * Narrowing this is the easy mistake: drop `build` and the generator is silently
+     * skipped during `spfn build`, so whatever it produces ships stale.
      *
      * Examples:
-     * - ['watch', 'build']: Run during development and build (e.g., admin-nav-generator)
-     * - ['build', 'start']: Run during build and server start (e.g., db-migration)
-     * - ['watch', 'manual']: Run during development and manual CLI (e.g., contract-generator)
-     * - ['start']: Run only on server start (e.g., runtime config generator)
+     * - ['watch']: only while `spfn dev` is watching, never from `spfn codegen run`
+     * - ['manual']: only on an explicit run, never mid-edit — for something slow
      */
     runOn?: GeneratorTrigger[];
     /**
@@ -89,11 +97,21 @@ interface OrchestratorOptions {
     cwd?: string;
     /** Enable debug logging */
     debug?: boolean;
+    /**
+     * Rethrow a generator failure instead of only logging it
+     *
+     * Off by default, which keeps watch mode alive through a half-edited file.
+     * A build turns it on: a generator that refuses — a broken contract, a
+     * router that will not load — has to reach the exit code, or the refusal
+     * scrolls past and the build ships anyway.
+     */
+    throwOnError?: boolean;
 }
 declare class CodegenOrchestrator {
     private readonly generators;
     private readonly cwd;
     private readonly debug;
+    private readonly throwOnError;
     private isGenerating;
     private pendingRegenerations;
     private watcher?;
@@ -314,10 +332,15 @@ interface RouteMapGeneratorConfig {
 }
 
 /**
- * Built-in Generators Export
+ * Contract Generator
+ *
+ * Reads the router, writes `contracts/current.json`, and on a build compares it
+ * against the newest released snapshot.
  *
- * Provides a registry of all built-in generators.
- * Custom generators can be added via .spfnrc.ts configuration.
+ * It is a codegen plugin for the same reason the route map is one: hanging off
+ * `spfn build` and `spfn dev` removes "forgot to regenerate the contract" as a
+ * failure mode. On `dev` it only regenerates — refusing a half-finished route
+ * mid-edit would make the feature unusable — and on `build` it also gates.
  *
  * @example
  * ```typescript
@@ -325,18 +348,103 @@ interface RouteMapGeneratorConfig {
  * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
  *
  * export default defineConfig({
+ *     generators: [
+ *         defineGenerator({
+ *             name: '@spfn/core:contract',
+ *             routerPath: './src/server/router.ts',
+ *             outputDir: './contracts',
+ *         })
+ *     ]
+ * });
+ * ```
+ */
+
+interface ContractGeneratorConfig {
+    /**
+     * Generator name (required for package-based loading)
+     */
+    name: '@spfn/core:contract';
+    /**
+     * Path to the router file (relative to project root)
+     * @example './src/server/router.ts'
+     */
+    routerPath: string;
+    /**
+     * Named export holding the router.
+     * @default 'appRouter', falling back to the default export
+     */
+    routerExport?: string;
+    /**
+     * Directory holding current.json, released/ and usage/ (relative to project root)
+     * @default './contracts'
+     */
+    outputDir?: string;
+    /**
+     * Extra file patterns to watch, for routes outside src/server/routes
+     */
+    additionalRouteDirs?: string[];
+}
+/** Thrown when the build must stop. */
+declare class ContractGeneratorError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Router registration guard
+ *
+ * A contract has to describe what production serves. When a route is registered
+ * only under a feature flag or an environment check, the generated contract
+ * describes whichever way the generator happened to run — and the gate then
+ * compares a promise nobody made.
+ *
+ * Object spread is the one way a key can be conditionally present in the object
+ * `defineRouter()` receives, so that is what this reads. A spread of a plain
+ * identifier (`...baseRoutes`) is unconditional and passes; anything computed
+ * inside the spread does not.
+ */
+/** Thrown when the router registers contracted routes conditionally. */
+declare class ConditionalRegistrationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Refuse a router whose route set depends on a condition.
+ *
+ * @param routerPath - path named in the error message
+ * @param source - contents of the router file
+ */
+declare function assertUnconditionalRegistration(routerPath: string, source: string): void;
+
+/**
+ * Built-in Generators Export
+ *
+ * @example
+ * ```typescript
+ * // .spfnrc.ts
+ * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
+ * import type { RouteMapGeneratorConfig, ContractGeneratorConfig } from '@spfn/core/codegen';
+ *
+ * export default defineConfig({
  *   generators: [
- *     defineGenerator({ path: './my-generator.ts' })
+ *     defineGenerator<RouteMapGeneratorConfig>({
+ *       name: '@spfn/core:route-map',
+ *       routerPath: './src/server/router.ts',
+ *       outputPath: './src/generated/route-map.ts',
+ *     }),
+ *     defineGenerator<ContractGeneratorConfig>({
+ *       name: '@spfn/core:contract',
+ *       routerPath: './src/server/router.ts',
+ *       outputDir: './contracts',
+ *     }),
  *   ]
  * });
  * ```
  */
 
 /**
- * Registry of available generators
- *
- * Used by package-based generator loading (e.g., "@spfn/core:route-map")
+ * @internal
+ * Registry of available generators for package-based loading.
+ * DO NOT use directly - use defineGenerator({ name: '@spfn/core:route-map', ... }) instead.
  */
 declare const generators: Record<string, unknown>;
 
-export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, ConditionalRegistrationError, type ContractGeneratorConfig, ContractGeneratorError, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };

package/dist/codegen/index.js

@@ -1,9 +1,10 @@
 import { watch } from 'chokidar';
-import { join, dirname, resolve, relative } from 'path';
+import { join, relative, sep, dirname, resolve } from 'path';
 import mm from 'micromatch';
 import { logger } from '@spfn/core/logger';
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { createJiti } from 'jiti';
+import { collectContractDocument, writeCurrentDocument, checkContract, formatViolations } from '@spfn/core/contract';
 
 // src/codegen/core/orchestrator.ts
 var orchestratorLogger = logger.child("@spfn/core:orchestrator");
@@ -11,6 +12,7 @@ var CodegenOrchestrator = class {
   generators;
   cwd;
   debug;
+  throwOnError;
   isGenerating = false;
   pendingRegenerations = /* @__PURE__ */ new Set();
   watcher;
@@ -19,6 +21,7 @@ var CodegenOrchestrator = class {
     this.generators = options.generators;
     this.cwd = options.cwd ?? process.cwd();
     this.debug = options.debug ?? false;
+    this.throwOnError = options.throwOnError ?? false;
   }
   /**
    * Close watcher and cleanup resources
@@ -80,6 +83,9 @@ var CodegenOrchestrator = class {
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
         orchestratorLogger.error(`[${generator.name}] \u2717 Generation failed`, err);
+        if (this.throwOnError) {
+          throw err;
+        }
       }
     }
   }
@@ -111,8 +117,10 @@ var CodegenOrchestrator = class {
       });
     }
     this.watcher = watch(watchDirs, {
-      ignored: /(^|[\/\\])\../,
-      // ignore dotfiles
+      // Ignore dotfiles by path segments relative to cwd — matching the absolute
+      // path would ignore everything when the checkout itself lives under a dot
+      // directory (e.g. .claude/worktrees/<name>), leaving zero watched files
+      ignored: (watchedPath) => relative(this.cwd, watchedPath).split(sep).some((segment) => segment.startsWith(".") && segment !== "." && segment !== ".."),
       persistent: true,
       ignoreInitial: true,
       awaitWriteFinish: {
@@ -276,6 +284,11 @@ async function createGeneratorsFromConfig(config, cwd) {
   }
   for (const generatorConfig of config.generators) {
     try {
+      if ("generate" in generatorConfig && typeof generatorConfig.generate === "function") {
+        generators2.push(generatorConfig);
+        configLogger.info(`Generator instance added: ${generatorConfig.name}`);
+        continue;
+      }
       if ("path" in generatorConfig) {
         const generatorPath = generatorConfig.path.startsWith(".") ? join(cwd, generatorConfig.path) : generatorConfig.path;
         configLogger.info(`Loading custom generator: ${generatorPath}`);
@@ -351,17 +364,27 @@ function parseRouterFile(routerPath) {
     let match;
     while ((match = importPattern.exec(content)) !== null) {
       const importPath = match[1];
-      if (importPath.includes("route")) {
+      if (importPath.startsWith(".")) {
         importPaths.push(importPath);
       }
     }
-    const routerPattern = /defineRouter\s*\(\s*\{([^}]+)\}/s;
-    const routerMatch = routerPattern.exec(content);
-    if (routerMatch) {
-      const routerContent = routerMatch[1];
-      const namePattern = /(\w+)\s*[,}]/g;
-      while ((match = namePattern.exec(routerContent)) !== null) {
-        routeNames.push(match[1]);
+    const defineRouterStart = content.indexOf("defineRouter(");
+    if (defineRouterStart !== -1) {
+      const braceStart = content.indexOf("{", defineRouterStart);
+      if (braceStart !== -1) {
+        let depth = 1;
+        let braceEnd = braceStart + 1;
+        while (depth > 0 && braceEnd < content.length) {
+          if (content[braceEnd] === "{") depth++;
+          else if (content[braceEnd] === "}") depth--;
+          braceEnd++;
+        }
+        const routerContent = content.slice(braceStart + 1, braceEnd - 1);
+        const withoutComments = routerContent.replace(/\/\/[^\n]*/g, "");
+        const namePattern = /^\s*(\w+)\s*[,\n]/gm;
+        while ((match = namePattern.exec(withoutComments)) !== null) {
+          routeNames.push(match[1]);
+        }
       }
     }
   } catch (error) {
@@ -404,6 +427,17 @@ function createRouteMapGenerator(config) {
     outputPath = "./src/generated/route-map.ts",
     additionalRouteDirs = []
   } = config;
+  if (!routerPath) {
+    throw new Error(
+      `[@spfn/core:route-map] Missing required "routerPath" option.
+
+Usage:
+  defineGenerator<RouteMapGeneratorConfig>({
+    name: '@spfn/core:route-map',
+    routerPath: './src/server/router.ts',
+  })`
+    );
+  }
   return {
     name: "@spfn/core:route-map",
     watchPatterns: [
@@ -412,7 +446,7 @@ function createRouteMapGenerator(config) {
       "src/server/routes/**/*.ts",
       ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
     ],
-    runOn: ["watch", "build", "start", "manual"],
+    runOn: ["watch", "manual", "build"],
     async generate(options) {
       const { cwd, debug } = options;
       const absoluteRouterPath = join(cwd, routerPath);
@@ -433,7 +467,17 @@ function createRouteMapGenerator(config) {
       for (const importPath of importPaths) {
         let resolvedPath = resolve(routerDir, importPath);
         if (!resolvedPath.endsWith(".ts")) {
-          resolvedPath += ".ts";
+          const withTs = resolvedPath + ".ts";
+          if (existsSync(withTs)) {
+            resolvedPath = withTs;
+          } else {
+            const indexPath = join(resolvedPath, "index.ts");
+            if (existsSync(indexPath)) {
+              resolvedPath = indexPath;
+            } else {
+              resolvedPath = withTs;
+            }
+          }
         }
         if (existsSync(resolvedPath)) {
           const routes = parseRouteFile(resolvedPath);
@@ -458,11 +502,164 @@ function createRouteMapGenerator(config) {
   };
 }
 
+// src/codegen/generators/contract-guard.ts
+var ConditionalRegistrationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConditionalRegistrationError";
+  }
+};
+function defineRouterBlock(source) {
+  const start = source.indexOf("defineRouter(");
+  if (start === -1) {
+    return void 0;
+  }
+  const open = source.indexOf("{", start);
+  if (open === -1) {
+    return void 0;
+  }
+  let depth = 1;
+  let cursor = open + 1;
+  while (depth > 0 && cursor < source.length) {
+    if (source[cursor] === "{") depth++;
+    else if (source[cursor] === "}") depth--;
+    cursor++;
+  }
+  return source.slice(open + 1, cursor - 1).replace(/\/\/[^\n]*/g, "");
+}
+var PLAIN_REFERENCE = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*\s*$/;
+function assertUnconditionalRegistration(routerPath, source) {
+  const block = defineRouterBlock(source);
+  if (!block) {
+    return;
+  }
+  for (const [, expression] of block.matchAll(/\.\.\.\s*([^,\n]+)/g)) {
+    if (PLAIN_REFERENCE.test(expression)) {
+      continue;
+    }
+    throw new ConditionalRegistrationError(
+      `${routerPath} registers routes conditionally: "...${expression.trim()}".
+
+A contract has to describe what production serves. When the route set depends on a flag or an environment, the generated contract describes whichever way the generator happened to run.
+Register contracted routes unconditionally, and gate behaviour inside the handler instead.`
+    );
+  }
+}
+
+// src/codegen/generators/contract.ts
+var genLogger2 = logger.child("@spfn/core:contract-generator");
+var ContractGeneratorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractGeneratorError";
+  }
+};
+function isRouter(value) {
+  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
+}
+function loadRouter(cwd, absoluteRouterPath, routerExport) {
+  let module;
+  try {
+    const jiti = createJiti(cwd, { interopDefault: true, moduleCache: false });
+    module = jiti(absoluteRouterPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ContractGeneratorError(
+      `Failed to load ${relative(cwd, absoluteRouterPath)}: ${message}
+
+The contract is read from the loaded router, so a route module must be importable without side effects. Check that nothing at module scope opens a connection or reads a missing environment value.`
+    );
+  }
+  const candidates = routerExport ? [routerExport] : ["appRouter", "default", "router"];
+  for (const name of candidates) {
+    const candidate = module[name];
+    if (isRouter(candidate)) {
+      return candidate;
+    }
+  }
+  throw new ContractGeneratorError(
+    `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${candidates.join(", ")}. Set "routerExport" to the export holding the defineRouter() result.`
+  );
+}
+function pinNodeEnv() {
+  if (!process.env.NODE_ENV) {
+    process.env.NODE_ENV = "production";
+    genLogger2.info('NODE_ENV was unset; pinned to "production" so the contract does not depend on the shell');
+  }
+}
+function createContractGenerator(config) {
+  const {
+    routerPath,
+    routerExport,
+    outputDir = "./contracts",
+    additionalRouteDirs = []
+  } = config;
+  if (!routerPath) {
+    throw new Error(
+      `[@spfn/core:contract] Missing required "routerPath" option.
+
+Usage:
+  defineGenerator<ContractGeneratorConfig>({
+    name: '@spfn/core:contract',
+    routerPath: './src/server/router.ts',
+  })`
+    );
+  }
+  return {
+    name: "@spfn/core:contract",
+    watchPatterns: [
+      routerPath,
+      "src/server/routes/**/*.ts",
+      ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
+    ],
+    runOn: ["watch", "build", "manual"],
+    async generate(options) {
+      const { cwd } = options;
+      const absoluteRouterPath = join(cwd, routerPath);
+      const contractsDir = join(cwd, outputDir);
+      if (!existsSync(absoluteRouterPath)) {
+        throw new ContractGeneratorError(
+          `Router file not found: ${routerPath}. The contract generator is configured but has nothing to read.`
+        );
+      }
+      pinNodeEnv();
+      assertUnconditionalRegistration(routerPath, readFileSync(absoluteRouterPath, "utf-8"));
+      const router = loadRouter(cwd, absoluteRouterPath, routerExport);
+      const document = collectContractDocument(router);
+      const changed = writeCurrentDocument(contractsDir, document);
+      genLogger2.info(
+        `${changed ? "Wrote" : "Verified"} ${relative(cwd, join(contractsDir, "current.json"))} (${document.operations.length} contracted operation(s))`
+      );
+      if (options.trigger?.type !== "build") {
+        return;
+      }
+      const result = checkContract(contractsDir, document);
+      for (const warning of result.warnings) {
+        genLogger2.warn(warning);
+      }
+      if (result.violations.length === 0) {
+        if (result.baselineVersion) {
+          genLogger2.info(`Contract is backward compatible with released ${result.baselineVersion}`);
+        }
+        return;
+      }
+      throw new ContractGeneratorError(
+        `This build breaks the contract released as ${result.baselineVersion}:
+
+${formatViolations(result.violations)}
+
+A released client cannot be fixed by redeploying the server. Keep the promise, or cut a new contract version and let the old operation stay until no released app calls it.`
+      );
+    }
+  };
+}
+
 // src/codegen/generators/index.ts
 var generators = {
-  "route-map": createRouteMapGenerator
+  "route-map": createRouteMapGenerator,
+  contract: createContractGenerator
 };
 
-export { CodegenOrchestrator, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map