@windagency/valora 2.0.1

package/dist/session/context.js

@@ -0,0 +1,253 @@
+/**
+ * Session context manager
+ */
+import { SessionError } from '../utils/error-handler.js';
+export class SessionContextManager {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Add a command to session history
+     */
+    addCommand(command, args, flags, outputs, success, 
+    // eslint-disable-next-line @typescript-eslint/naming-convention -- duration_ms matches SessionCommand interface property name
+    duration_ms, error, 
+    // eslint-disable-next-line @typescript-eslint/naming-convention -- tokens_used matches SessionCommand interface property name
+    tokens_used, 
+    // eslint-disable-next-line @typescript-eslint/naming-convention -- optimization_metrics matches SessionCommand interface property name
+    optimization_metrics, 
+    // eslint-disable-next-line @typescript-eslint/naming-convention -- quality_metrics matches SessionCommand interface property name
+    quality_metrics) {
+        const sessionCommand = {
+            args,
+            command,
+            duration_ms,
+            error,
+            flags,
+            optimization_metrics,
+            outputs,
+            quality_metrics,
+            success,
+            timestamp: new Date().toISOString(),
+            tokens_used
+        };
+        this.session.commands.push(sessionCommand);
+        this.session.last_command = command;
+        // Clear current_command since the command has completed
+        this.session.current_command = undefined;
+    }
+    /**
+     * Set the currently running command
+     */
+    setCurrentCommand(command) {
+        this.session.current_command = command;
+        this.session.updated_at = new Date().toISOString();
+    }
+    /**
+     * Clear the currently running command
+     */
+    clearCurrentCommand() {
+        this.session.current_command = undefined;
+    }
+    /**
+     * Update session context
+     */
+    updateContext(key, value) {
+        const keys = key.split('.');
+        const lastKey = keys[keys.length - 1];
+        if (!lastKey) {
+            throw new SessionError('Invalid context key: key cannot be empty', { key });
+        }
+        // Navigate to the parent object
+        const parentObj = keys.slice(0, -1).reduce((obj, k) => {
+            if (!obj[k] || typeof obj[k] !== 'object') {
+                obj[k] = {};
+            }
+            return obj[k];
+        }, this.session.context);
+        // Set the value on the final key
+        parentObj[lastKey] = value;
+    }
+    /**
+     * Get context value
+     */
+    getContext(key) {
+        const keys = key.split('.');
+        return keys.reduce((value, k) => {
+            if (value && typeof value === 'object' && k in value) {
+                return value[k];
+            }
+            return undefined;
+        }, this.session.context);
+    }
+    /**
+     * Get all context
+     */
+    getAllContext() {
+        return { ...this.session.context };
+    }
+    /**
+     * Merge context
+     */
+    mergeContext(context) {
+        this.session.context = { ...this.session.context, ...context };
+    }
+    /**
+     * Clear specific context key
+     */
+    clearContext(key) {
+        delete this.session.context[key];
+    }
+    /**
+     * Clear all context
+     */
+    clearAllContext() {
+        this.session.context = {};
+    }
+    /**
+     * Get last command
+     */
+    getLastCommand() {
+        if (this.session.commands.length === 0) {
+            return null;
+        }
+        return this.session.commands[this.session.commands.length - 1] ?? null;
+    }
+    /**
+     * Get command history
+     */
+    getCommandHistory() {
+        return [...this.session.commands];
+    }
+    /**
+     * Get commands by name
+     */
+    getCommandsByName(commandName) {
+        return this.session.commands.filter((cmd) => cmd.command === commandName);
+    }
+    /**
+     * Get successful commands
+     */
+    getSuccessfulCommands() {
+        return this.session.commands.filter((cmd) => cmd.success);
+    }
+    /**
+     * Get failed commands
+     */
+    getFailedCommands() {
+        return this.session.commands.filter((cmd) => !cmd.success);
+    }
+    /**
+     * Get session statistics
+     */
+    getStatistics() {
+        const commands = this.session.commands;
+        const successful = commands.filter((cmd) => cmd.success);
+        const failed = commands.filter((cmd) => !cmd.success);
+        const totalDuration = commands.reduce((sum, cmd) => sum + cmd.duration_ms, 0);
+        return {
+            average_duration_ms: commands.length > 0 ? totalDuration / commands.length : 0,
+            failed_commands: failed.length,
+            successful_commands: successful.length,
+            total_commands: commands.length,
+            total_duration_ms: totalDuration
+        };
+    }
+    /**
+     * Update session status
+     */
+    setStatus(status) {
+        this.session.status = status;
+    }
+    /**
+     * Get session status
+     */
+    getStatus() {
+        return this.session.status;
+    }
+    /**
+     * Get session
+     */
+    getSession() {
+        return this.session;
+    }
+    /**
+     * Check if context has key
+     */
+    hasContext(key) {
+        return key in this.session.context;
+    }
+    /**
+     * Get context keys
+     */
+    getContextKeys() {
+        return Object.keys(this.session.context);
+    }
+    /**
+     * Validate context has required keys
+     */
+    validateContext(requiredKeys) {
+        const missing = requiredKeys.filter((key) => !this.hasContext(key));
+        if (missing.length > 0) {
+            throw new SessionError('Missing required context keys', {
+                available: this.getContextKeys(),
+                missing
+            });
+        }
+    }
+    /**
+     * Get filtered context containing only specified keys
+     * Useful for reducing token usage by only passing context that's actually referenced
+     */
+    getFilteredContext(keys) {
+        if (keys.length === 0) {
+            return {};
+        }
+        const filtered = {};
+        for (const key of keys) {
+            const value = this.getContext(key);
+            if (value !== undefined) {
+                // Handle nested keys by setting the value at the root key
+                const rootKey = key.split('.')[0];
+                if (rootKey && !(rootKey in filtered)) {
+                    // Get the full value for the root key to preserve nesting
+                    const rootValue = this.getContext(rootKey);
+                    if (rootValue !== undefined) {
+                        filtered[rootKey] = rootValue;
+                    }
+                }
+            }
+        }
+        return filtered;
+    }
+    /**
+     * Extract $CONTEXT_* variable references from a value (string, object, or array)
+     * Returns a set of context keys that are referenced
+     */
+    static extractContextReferences(value) {
+        const references = new Set();
+        const variablePattern = /\$CONTEXT_([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*)/g;
+        const extract = (val) => {
+            if (typeof val === 'string') {
+                let match;
+                while ((match = variablePattern.exec(val)) !== null) {
+                    if (match[1]) {
+                        references.add(match[1]);
+                    }
+                }
+                // Reset lastIndex since we're reusing the regex
+                variablePattern.lastIndex = 0;
+            }
+            else if (Array.isArray(val)) {
+                val.forEach(extract);
+            }
+            else if (typeof val === 'object' && val !== null) {
+                Object.values(val).forEach(extract);
+            }
+        };
+        extract(value);
+        return references;
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/session/context.js.map

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

package/dist/session/index.d.ts

@@ -0,0 +1,9 @@
+export * from './cleanup-scheduler.js';
+export * from './context.js';
+export * from './lifecycle.js';
+export * from './retention-manager.js';
+/**
+ * Central exports for session management
+ */
+export * from './store.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC;;GAEG;AAEH,cAAc,SAAS,CAAC"}

package/dist/session/index.js

@@ -0,0 +1,9 @@
+export * from './cleanup-scheduler.js';
+export * from './context.js';
+export * from './lifecycle.js';
+export * from './retention-manager.js';
+/**
+ * Central exports for session management
+ */
+export * from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC;;GAEG;AAEH,cAAc,SAAS,CAAC"}

package/dist/session/lifecycle.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Session lifecycle management
+ */
+import type { SessionCreateOptions, SessionResumeOptions, SessionSummary } from '../types/session.types.js';
+import type { SessionStore } from './store.js';
+import { SessionContextManager } from './context.js';
+export declare class SessionLifecycle {
+    private currentSession;
+    private lastPersistSessionId;
+    private lastPersistTime;
+    private persistTimer;
+    private store;
+    constructor(store: SessionStore);
+    /**
+     * Determine if we should use extended debounce for rapid same-session commands
+     */
+    private shouldUseExtendedDebounce;
+    /**
+     * Create a new session
+     */
+    create(options?: SessionCreateOptions): Promise<SessionContextManager>;
+    /**
+     * Resume an existing session
+     * Attempts to load snapshot first for essential context, then loads full session
+     */
+    resume(options: SessionResumeOptions): Promise<SessionContextManager>;
+    /**
+     * Get or create session
+     */
+    getOrCreate(sessionId?: string): Promise<SessionContextManager>;
+    /**
+     * Persist current session with debouncing for performance
+     * @param immediate - If true, persist immediately; if false, debounce the persistence (fire-and-forget)
+     */
+    persist(immediate?: false): void;
+    persist(immediate: true): Promise<void>;
+    /**
+     * Persist current session immediately (no debouncing)
+     */
+    private persistImmediate;
+    /**
+     * Complete current session
+     */
+    complete(): Promise<void>;
+    /**
+     * Fail current session
+     */
+    fail(error?: string): Promise<void>;
+    /**
+     * Pause current session
+     */
+    pause(): Promise<void>;
+    /**
+     * Get current session
+     */
+    getCurrentSession(): null | SessionContextManager;
+    /**
+     * Has active session
+     */
+    hasActiveSession(): boolean;
+    /**
+     * Get recent session or create new one
+     */
+    getRecentOrCreate(): Promise<SessionContextManager>;
+    /**
+     * List all sessions
+     */
+    listSessions(): Promise<SessionSummary[]>;
+    /**
+     * Archive old sessions
+     */
+    archiveOldSessions(daysOld?: number): Promise<number>;
+    /**
+     * Cleanup old sessions
+     */
+    cleanupOldSessions(daysOld?: number): Promise<number>;
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Flush any pending debounced persistence
+     * Should be called before destroying the SessionLifecycle instance
+     */
+    flushPendingPersistence(): Promise<void>;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/session/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/session/lifecycle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAYtG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAOlD,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,oBAAoB,CAAuB;IACnD,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,KAAK,CAAe;gBAEhB,KAAK,EAAE,YAAY;IAI/B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAejC;;OAEG;IACG,MAAM,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAwBhF;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqD3E;;OAEG;IACG,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAWrE;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,IAAI;IAChC,OAAO,CAAC,SAAS,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCvC;;OAEG;YACW,gBAAgB;IAoB9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB/B;;OAEG;IACG,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBzC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5B;;OAEG;IACH,iBAAiB,IAAI,IAAI,GAAG,qBAAqB;IAIjD;;OAEG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAczD;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAI/C;;OAEG;IACG,kBAAkB,CAAC,OAAO,SAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAOzE;;OAEG;IACG,kBAAkB,CAAC,OAAO,SAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzE;;OAEG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD;;;OAGG;IACG,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB9C"}

package/dist/session/lifecycle.js

@@ -0,0 +1,301 @@
+/**
+ * Session lifecycle management
+ */
+import { SESSION_ARCHIVE_DAYS, SESSION_CLEANUP_DAYS, SESSION_PERSIST_DEBOUNCE_MS, SESSION_PERSIST_EXTENDED_DEBOUNCE_MS, SESSION_RAPID_COMMAND_THRESHOLD_MS } from '../config/constants.js';
+import { getLogger } from '../output/logger.js';
+import { SessionError } from '../utils/error-handler.js';
+import { SessionContextManager } from './context.js';
+// Debounce configuration (imported from constants)
+const DEBOUNCE_DELAY_MS = SESSION_PERSIST_DEBOUNCE_MS;
+const EXTENDED_DEBOUNCE_DELAY_MS = SESSION_PERSIST_EXTENDED_DEBOUNCE_MS;
+const RAPID_COMMAND_THRESHOLD_MS = SESSION_RAPID_COMMAND_THRESHOLD_MS;
+export class SessionLifecycle {
+    currentSession = null;
+    lastPersistSessionId = null;
+    lastPersistTime = 0;
+    persistTimer = null;
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Determine if we should use extended debounce for rapid same-session commands
+     */
+    shouldUseExtendedDebounce() {
+        if (!this.currentSession) {
+            return false;
+        }
+        const currentSessionId = this.currentSession.getSession().session_id;
+        const now = Date.now();
+        const timeSinceLastPersist = now - this.lastPersistTime;
+        // Use extended debounce if:
+        // 1. Same session as last persist
+        // 2. Last persist was within the rapid command threshold window
+        return this.lastPersistSessionId === currentSessionId && timeSinceLastPersist < RAPID_COMMAND_THRESHOLD_MS;
+    }
+    /**
+     * Create a new session
+     */
+    async create(options = {}) {
+        const logger = getLogger();
+        logger.debug('Creating new session', {
+            hasCustomId: !!options.sessionId,
+            hasInitialContext: !!options.initialContext
+        });
+        const session = await this.store.createSession(options.sessionId);
+        if (options.initialContext) {
+            session.context = options.initialContext;
+        }
+        await this.store.saveSession(session);
+        this.currentSession = new SessionContextManager(session);
+        logger.info('Session created', {
+            sessionId: session.session_id,
+            status: session.status
+        });
+        return this.currentSession;
+    }
+    /**
+     * Resume an existing session
+     * Attempts to load snapshot first for essential context, then loads full session
+     */
+    async resume(options) {
+        const logger = getLogger();
+        const startTime = Date.now();
+        logger.debug('Resuming session', {
+            resetContext: !!options.resetContext,
+            sessionId: options.sessionId
+        });
+        const exists = await this.store.sessionExists(options.sessionId);
+        if (!exists) {
+            logger.warn('Session not found, cannot resume', { sessionId: options.sessionId });
+            throw new SessionError(`Session not found: ${options.sessionId}`, {
+                sessionId: options.sessionId
+            });
+        }
+        // Try to load snapshot first for essential context (faster)
+        const snapshot = await this.store.loadSnapshot(options.sessionId);
+        if (snapshot) {
+            const snapshotLoadTime = Date.now() - startTime;
+            logger.debug('Loaded session snapshot for fast resume', {
+                loadTimeMs: snapshotLoadTime,
+                recentCommands: snapshot.recent_commands.length,
+                sessionId: options.sessionId
+            });
+        }
+        const session = await this.store.loadSession(options.sessionId);
+        const fullLoadTime = Date.now() - startTime;
+        logger.debug('Full session loaded', {
+            commandCount: session.commands.length,
+            loadTimeMs: fullLoadTime,
+            sessionId: options.sessionId
+        });
+        if (options.resetContext) {
+            session.context = {};
+        }
+        // Update status to active
+        session.status = 'active';
+        await this.store.saveSession(session);
+        this.currentSession = new SessionContextManager(session);
+        logger.info('Session resumed', {
+            commandCount: session.commands.length,
+            previousStatus: session.status,
+            sessionId: session.session_id
+        });
+        return this.currentSession;
+    }
+    /**
+     * Get or create session
+     */
+    async getOrCreate(sessionId) {
+        if (sessionId) {
+            const exists = await this.store.sessionExists(sessionId);
+            if (exists) {
+                return this.resume({ sessionId });
+            }
+        }
+        return this.create({ sessionId });
+    }
+    persist(immediate = false) {
+        if (immediate) {
+            return this.persistImmediate();
+        }
+        // Debounce: persist after inactivity delay (fire-and-forget)
+        if (this.persistTimer) {
+            clearTimeout(this.persistTimer);
+        }
+        // Use extended debounce for rapid same-session commands to reduce I/O
+        const debounceDelay = this.shouldUseExtendedDebounce() ? EXTENDED_DEBOUNCE_DELAY_MS : DEBOUNCE_DELAY_MS;
+        const logger = getLogger();
+        if (debounceDelay === EXTENDED_DEBOUNCE_DELAY_MS) {
+            logger.debug('Using extended debounce for rapid same-session persistence', {
+                debounceMs: debounceDelay,
+                sessionId: this.currentSession?.getSession().session_id
+            });
+        }
+        this.persistTimer = setTimeout(() => {
+            void (async () => {
+                try {
+                    // If there is no current session (e.g., it was completed/failed and cleared),
+                    // we should check before attempting to persist.
+                    if (this.currentSession) {
+                        await this.persistImmediate();
+                    }
+                }
+                catch (error) {
+                    const persistLogger = getLogger();
+                    persistLogger.error('Failed to persist session during debounce', error);
+                }
+            })();
+        }, debounceDelay);
+    }
+    /**
+     * Persist current session immediately (no debouncing)
+     */
+    async persistImmediate() {
+        if (!this.currentSession) {
+            throw new SessionError('No active session to persist');
+        }
+        const session = this.currentSession.getSession();
+        await this.store.saveSession(session);
+        // Track persist time and session for adaptive debouncing
+        this.lastPersistTime = Date.now();
+        this.lastPersistSessionId = session.session_id;
+        const logger = getLogger();
+        logger.debug('Session persisted', {
+            commandCount: session.commands.length,
+            sessionId: session.session_id,
+            status: session.status
+        });
+    }
+    /**
+     * Complete current session
+     */
+    async complete() {
+        if (!this.currentSession) {
+            throw new SessionError('No active session to complete');
+        }
+        this.currentSession.setStatus('completed');
+        // Critical: persist immediately on session completion
+        await this.persist(true);
+        const session = this.currentSession.getSession();
+        const logger = getLogger();
+        logger.info('Session completed successfully', {
+            commandCount: session.commands.length,
+            duration: Date.now() - new Date(session.created_at).getTime(),
+            sessionId: session.session_id
+        });
+        this.currentSession = null;
+    }
+    /**
+     * Fail current session
+     */
+    async fail(error) {
+        if (!this.currentSession) {
+            throw new SessionError('No active session to fail');
+        }
+        this.currentSession.setStatus('failed');
+        if (error) {
+            this.currentSession.updateContext('error', error);
+        }
+        // Critical: persist immediately on session failure
+        await this.persist(true);
+        const session = this.currentSession.getSession();
+        const logger = getLogger();
+        logger.error('Session failed', error ? new Error(error) : new Error('Session failed'), {
+            commandCount: session.commands.length,
+            duration: Date.now() - new Date(session.created_at).getTime(),
+            sessionId: session.session_id
+        });
+        this.currentSession = null;
+    }
+    /**
+     * Pause current session
+     */
+    async pause() {
+        if (!this.currentSession) {
+            throw new SessionError('No active session to pause');
+        }
+        this.currentSession.setStatus('paused');
+        // Critical: persist immediately on session pause
+        await this.persist(true);
+        const session = this.currentSession.getSession();
+        const logger = getLogger();
+        logger.info('Session paused', {
+            commandCount: session.commands.length,
+            sessionId: session.session_id
+        });
+    }
+    /**
+     * Get current session
+     */
+    getCurrentSession() {
+        return this.currentSession;
+    }
+    /**
+     * Has active session
+     */
+    hasActiveSession() {
+        return this.currentSession !== null;
+    }
+    /**
+     * Get recent session or create new one
+     */
+    async getRecentOrCreate() {
+        const logger = getLogger();
+        const recentSession = await this.store.getRecentSession();
+        if (recentSession?.status === 'active') {
+            logger.debug('Reusing recent active session', { sessionId: recentSession.session_id });
+            this.currentSession = new SessionContextManager(recentSession);
+            return this.currentSession;
+        }
+        logger.debug('No recent active session found, creating new session');
+        return this.create();
+    }
+    /**
+     * List all sessions
+     */
+    async listSessions() {
+        return this.store.listSessions();
+    }
+    /**
+     * Archive old sessions
+     */
+    async archiveOldSessions(daysOld = SESSION_ARCHIVE_DAYS) {
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - daysOld);
+        return this.store.archiveSessions(cutoffDate);
+    }
+    /**
+     * Cleanup old sessions
+     */
+    async cleanupOldSessions(daysOld = SESSION_CLEANUP_DAYS) {
+        return this.store.cleanupOldSessions(daysOld);
+    }
+    /**
+     * Delete a session
+     */
+    async deleteSession(sessionId) {
+        return this.store.deleteSession(sessionId);
+    }
+    /**
+     * Flush any pending debounced persistence
+     * Should be called before destroying the SessionLifecycle instance
+     */
+    async flushPendingPersistence() {
+        if (this.persistTimer) {
+            clearTimeout(this.persistTimer);
+            this.persistTimer = null;
+            // Persist immediately if there's an active session
+            if (this.currentSession) {
+                try {
+                    await this.persistImmediate();
+                }
+                catch (error) {
+                    const logger = getLogger();
+                    logger.error('Failed to flush pending session persistence', error);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=lifecycle.js.map