@ginkoai/cli 1.0.0 → 1.4.1

package/dist/lib/event-logger.js

@@ -0,0 +1,197 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-11-04
+ * @tags: [event-logging, dual-write, adr-043, session-events]
+ * @related: [event-queue.ts, ../commands/log.ts, ../utils/session-logger.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: [fs-extra, uuid]
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { getGinkoDir, getUserEmail, getProjectRoot } from '../utils/helpers.js';
+import { execSync } from 'child_process';
+/**
+ * Get current event context (user, org, project)
+ */
+async function getEventContext() {
+    const userEmail = await getUserEmail();
+    const projectRoot = await getProjectRoot();
+    const projectName = path.basename(projectRoot);
+    // Get current branch
+    let branch = 'main';
+    try {
+        branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf8',
+            cwd: projectRoot
+        }).trim();
+    }
+    catch (error) {
+        // Not in a git repo or git not available
+    }
+    // Organization ID: extract from project path or use default
+    // Example: /Users/cnorton/Development/ginko -> "watchhill-ai"
+    const orgId = 'watchhill-ai'; // Can be enhanced to read from config
+    return {
+        user_id: userEmail,
+        organization_id: orgId,
+        project_id: projectName,
+        branch
+    };
+}
+/**
+ * Generate unique event ID
+ */
+function generateEventId() {
+    const timestamp = Date.now();
+    const random = uuidv4().split('-')[0]; // Use first segment of UUID
+    return `event_${timestamp}_${random}`;
+}
+/**
+ * Capture current context pressure (placeholder for future integration)
+ */
+function captureContextPressure() {
+    // TODO: Integrate with actual context pressure tracking
+    // For now, return a reasonable default
+    return 0.5; // 50%
+}
+/**
+ * Get path to current events file (JSONL)
+ */
+async function getEventsFilePath() {
+    const ginkoDir = await getGinkoDir();
+    const userEmail = await getUserEmail();
+    const userSlug = userEmail.replace('@', '-at-').replace(/\./g, '-');
+    const sessionDir = path.join(ginkoDir, 'sessions', userSlug);
+    // Ensure session directory exists
+    await fs.ensureDir(sessionDir);
+    return path.join(sessionDir, 'current-events.jsonl');
+}
+/**
+ * Append event to local file (JSONL format)
+ *
+ * CRITICAL: This MUST succeed even if Neo4j is offline.
+ * Never block user on network issues.
+ */
+async function appendToLocalFile(event) {
+    try {
+        const filePath = await getEventsFilePath();
+        const eventLine = JSON.stringify(event) + '\n';
+        // Atomic append operation
+        await fs.appendFile(filePath, eventLine, 'utf8');
+    }
+    catch (error) {
+        // Log error but don't propagate - we need to be resilient
+        console.error('[EventLogger] Failed to write to local file:', error instanceof Error ? error.message : String(error));
+        throw error; // Re-throw because local write MUST succeed
+    }
+}
+/**
+ * Log an event with dual-write pattern
+ *
+ * Pattern (ADR-043):
+ * 1. Write to local file immediately (blocking, must succeed)
+ * 2. Add to async queue for Neo4j sync (non-blocking)
+ * 3. Return immediately (don't wait for sync)
+ *
+ * @param entry - Event entry data
+ * @returns Promise<Event> - The logged event with metadata
+ */
+export async function logEvent(entry) {
+    // 1. Gather context
+    const context = await getEventContext();
+    const pressure = captureContextPressure();
+    // 2. Create event with metadata
+    const event = {
+        id: generateEventId(),
+        user_id: context.user_id,
+        organization_id: context.organization_id,
+        project_id: context.project_id,
+        timestamp: new Date().toISOString(),
+        pressure,
+        branch: entry.branch || context.branch,
+        category: entry.category,
+        description: entry.description,
+        files: entry.files,
+        impact: entry.impact || 'medium',
+        tags: entry.tags,
+        shared: entry.shared || false,
+        commit_hash: entry.commit_hash,
+        synced_to_graph: false
+    };
+    // 3. Write to local file immediately (MUST succeed)
+    await appendToLocalFile(event);
+    // 4. Add to async queue (import lazily to avoid circular deps)
+    try {
+        const { addToQueue } = await import('./event-queue.js');
+        await addToQueue(event);
+    }
+    catch (error) {
+        // Queue failure is non-critical - event is persisted locally
+        console.warn('[EventLogger] Failed to add to sync queue:', error instanceof Error ? error.message : String(error));
+    }
+    return event;
+}
+/**
+ * Load all events from local file
+ */
+export async function loadEvents() {
+    try {
+        const filePath = await getEventsFilePath();
+        if (!await fs.pathExists(filePath)) {
+            return [];
+        }
+        const content = await fs.readFile(filePath, 'utf8');
+        const lines = content.trim().split('\n').filter(line => line.length > 0);
+        return lines.map(line => JSON.parse(line));
+    }
+    catch (error) {
+        console.error('[EventLogger] Failed to load events:', error instanceof Error ? error.message : String(error));
+        return [];
+    }
+}
+/**
+ * Mark events as synced to graph
+ */
+export async function markEventsSynced(eventIds) {
+    try {
+        const events = await loadEvents();
+        const eventIdSet = new Set(eventIds);
+        // Update synced status
+        const updatedEvents = events.map(event => {
+            if (eventIdSet.has(event.id)) {
+                return { ...event, synced_to_graph: true };
+            }
+            return event;
+        });
+        // Rewrite file with updated events
+        const filePath = await getEventsFilePath();
+        const content = updatedEvents.map(e => JSON.stringify(e)).join('\n') + '\n';
+        await fs.writeFile(filePath, content, 'utf8');
+    }
+    catch (error) {
+        console.error('[EventLogger] Failed to mark events as synced:', error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Get events that need syncing (not yet synced to graph)
+ */
+export async function getUnsyncedEvents() {
+    const events = await loadEvents();
+    return events.filter(event => !event.synced_to_graph);
+}
+/**
+ * Clear events file (for testing)
+ */
+export async function clearEvents() {
+    try {
+        const filePath = await getEventsFilePath();
+        await fs.writeFile(filePath, '', 'utf8');
+    }
+    catch (error) {
+        console.error('[EventLogger] Failed to clear events:', error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=event-logger.js.map

package/dist/lib/event-logger.js.map

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

package/dist/lib/event-queue.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-11-04
+ * @tags: [event-queue, async-sync, neo4j, adr-043]
+ * @related: [event-logger.ts, ../commands/graph/api-client.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: []
+ */
+import { Event } from './event-logger.js';
+/**
+ * Event queue configuration
+ */
+interface QueueConfig {
+    syncIntervalMs: number;
+    syncThreshold: number;
+    maxBatchSize: number;
+    retryAttempts: number;
+    retryDelayMs: number;
+}
+/**
+ * Sync status tracking
+ */
+interface SyncStatus {
+    lastSyncTime: Date | null;
+    pendingCount: number;
+    totalSynced: number;
+    lastError: string | null;
+    isRunning: boolean;
+}
+/**
+ * Event Queue for async Neo4j synchronization
+ *
+ * Pattern (ADR-043):
+ * - Batches events for efficient sync
+ * - Triggers sync on 5-minute timer OR 5 events (whichever first)
+ * - Retries on failure with exponential backoff
+ * - Preserves events in local file on failure
+ */
+export declare class EventQueue {
+    private config;
+    private syncTimer;
+    private status;
+    private isShuttingDown;
+    constructor(config?: Partial<QueueConfig>);
+    /**
+     * Start the sync queue
+     */
+    start(): void;
+    /**
+     * Stop the sync queue
+     */
+    stop(): void;
+    /**
+     * Add event to queue and trigger sync if threshold reached
+     */
+    addToQueue(event: Event): Promise<void>;
+    /**
+     * Sync queued events to Neo4j
+     *
+     * Batch syncs up to maxBatchSize events per call.
+     * Retries on failure with exponential backoff.
+     */
+    syncToGraph(): Promise<void>;
+    /**
+     * Sync a batch of events to Neo4j graph
+     */
+    private syncBatchToGraph;
+    /**
+     * Flush queue immediately (for handoff/shutdown)
+     */
+    flush(): Promise<void>;
+    /**
+     * Graceful shutdown with pending sync wait
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current queue status
+     */
+    getStatus(): SyncStatus;
+    /**
+     * Schedule sync if needed (called after adding to queue)
+     */
+    scheduleSyncIfNeeded(): void;
+}
+/**
+ * Initialize global event queue
+ */
+export declare function initializeQueue(config?: Partial<QueueConfig>): EventQueue;
+/**
+ * Get global queue instance
+ */
+export declare function getQueue(): EventQueue;
+/**
+ * Add event to global queue
+ */
+export declare function addToQueue(event: Event): Promise<void>;
+/**
+ * Check if queue is initialized
+ */
+export declare function isQueueInitialized(): boolean;
+export {};
+//# sourceMappingURL=event-queue.d.ts.map

package/dist/lib/event-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-queue.d.ts","sourceRoot":"","sources":["../../src/lib/event-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAuC,MAAM,mBAAmB,CAAC;AAE/E;;GAEG;AACH,UAAU,WAAW;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAUD;;GAEG;AACH,UAAU,UAAU;IAClB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,MAAM,CAMZ;IACF,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAIzC;;OAEG;IACH,KAAK,IAAI,IAAI;IAyBb;;OAEG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7C;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAgElC;;OAEG;YACW,gBAAgB;IA+B9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB/B;;OAEG;IACH,SAAS,IAAI,UAAU;IAIvB;;OAEG;IACH,oBAAoB,IAAI,IAAI;CAI7B;AAOD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,UAAU,CAsBzE;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,UAAU,CAKrC;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C"}

package/dist/lib/event-queue.js

@@ -0,0 +1,274 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-11-04
+ * @tags: [event-queue, async-sync, neo4j, adr-043]
+ * @related: [event-logger.ts, ../commands/graph/api-client.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: []
+ */
+import { getUnsyncedEvents, markEventsSynced } from './event-logger.js';
+const DEFAULT_CONFIG = {
+    syncIntervalMs: 5 * 60 * 1000, // 5 minutes
+    syncThreshold: 5, // 5 events
+    maxBatchSize: 20, // 20 events max
+    retryAttempts: 3, // 3 retries
+    retryDelayMs: 5000 // 5 seconds
+};
+/**
+ * Event Queue for async Neo4j synchronization
+ *
+ * Pattern (ADR-043):
+ * - Batches events for efficient sync
+ * - Triggers sync on 5-minute timer OR 5 events (whichever first)
+ * - Retries on failure with exponential backoff
+ * - Preserves events in local file on failure
+ */
+export class EventQueue {
+    config;
+    syncTimer = null;
+    status = {
+        lastSyncTime: null,
+        pendingCount: 0,
+        totalSynced: 0,
+        lastError: null,
+        isRunning: false
+    };
+    isShuttingDown = false;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Start the sync queue
+     */
+    start() {
+        if (this.syncTimer) {
+            console.warn('[EventQueue] Queue already started');
+            return;
+        }
+        console.log(`[EventQueue] Starting sync queue (interval: ${this.config.syncIntervalMs / 1000}s, threshold: ${this.config.syncThreshold} events)`);
+        // Schedule periodic sync
+        // Use unref() to allow process to exit if no other work pending
+        this.syncTimer = setInterval(() => {
+            this.syncToGraph().catch(error => {
+                console.error('[EventQueue] Scheduled sync failed:', error instanceof Error ? error.message : String(error));
+            });
+        }, this.config.syncIntervalMs);
+        // Don't keep process alive just for this timer
+        this.syncTimer.unref();
+        // Initial sync on start
+        this.syncToGraph().catch(error => {
+            console.warn('[EventQueue] Initial sync failed:', error instanceof Error ? error.message : String(error));
+        });
+    }
+    /**
+     * Stop the sync queue
+     */
+    stop() {
+        if (this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = null;
+            console.log('[EventQueue] Sync queue stopped');
+        }
+    }
+    /**
+     * Add event to queue and trigger sync if threshold reached
+     */
+    async addToQueue(event) {
+        // Update pending count
+        const unsyncedEvents = await getUnsyncedEvents();
+        this.status.pendingCount = unsyncedEvents.length;
+        // Check if we should trigger sync based on threshold
+        if (this.status.pendingCount >= this.config.syncThreshold) {
+            console.log(`[EventQueue] Threshold reached (${this.status.pendingCount} events), triggering sync`);
+            // Fire and forget - don't block
+            this.syncToGraph().catch(error => {
+                console.warn('[EventQueue] Threshold sync failed:', error instanceof Error ? error.message : String(error));
+            });
+        }
+    }
+    /**
+     * Sync queued events to Neo4j
+     *
+     * Batch syncs up to maxBatchSize events per call.
+     * Retries on failure with exponential backoff.
+     */
+    async syncToGraph() {
+        if (this.status.isRunning) {
+            console.log('[EventQueue] Sync already in progress, skipping');
+            return;
+        }
+        if (this.isShuttingDown) {
+            console.log('[EventQueue] Shutting down, skipping sync');
+            return;
+        }
+        this.status.isRunning = true;
+        this.status.lastError = null;
+        try {
+            // Get unsynced events
+            const unsyncedEvents = await getUnsyncedEvents();
+            if (unsyncedEvents.length === 0) {
+                console.log('[EventQueue] No events to sync');
+                return;
+            }
+            // Batch events
+            const batch = unsyncedEvents.slice(0, this.config.maxBatchSize);
+            console.log(`[EventQueue] Syncing ${batch.length} events to graph`);
+            // Attempt sync with retries
+            let lastError = null;
+            for (let attempt = 1; attempt <= this.config.retryAttempts; attempt++) {
+                try {
+                    await this.syncBatchToGraph(batch);
+                    // Success - mark events as synced
+                    const eventIds = batch.map(e => e.id);
+                    await markEventsSynced(eventIds);
+                    this.status.totalSynced += batch.length;
+                    this.status.lastSyncTime = new Date();
+                    this.status.pendingCount = unsyncedEvents.length - batch.length;
+                    console.log(`[EventQueue] ✓ Synced ${batch.length} events to graph`);
+                    return;
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    console.warn(`[EventQueue] Sync attempt ${attempt}/${this.config.retryAttempts} failed:`, lastError.message);
+                    if (attempt < this.config.retryAttempts) {
+                        // Wait before retry with exponential backoff
+                        const delay = this.config.retryDelayMs * Math.pow(2, attempt - 1);
+                        console.log(`[EventQueue] Retrying in ${delay / 1000}s...`);
+                        await new Promise(resolve => setTimeout(resolve, delay));
+                    }
+                }
+            }
+            // All retries failed
+            this.status.lastError = lastError?.message || 'Unknown error';
+            console.error('[EventQueue] ⚠ Graph sync failed after all retries, events remain in local log');
+        }
+        finally {
+            this.status.isRunning = false;
+        }
+    }
+    /**
+     * Sync a batch of events to Neo4j graph
+     */
+    async syncBatchToGraph(events) {
+        try {
+            // Import graph API client lazily
+            const { createGraphEvents } = await import('../commands/graph/api-client.js');
+            // Convert events to graph API format
+            const graphEvents = events.map(event => ({
+                id: event.id,
+                user_id: event.user_id,
+                organization_id: event.organization_id,
+                project_id: event.project_id,
+                category: event.category,
+                description: event.description,
+                timestamp: event.timestamp,
+                impact: event.impact,
+                files: event.files,
+                branch: event.branch,
+                tags: event.tags,
+                shared: event.shared,
+                commit_hash: event.commit_hash,
+                pressure: event.pressure
+            }));
+            // Call graph API to create events
+            await createGraphEvents(graphEvents);
+        }
+        catch (error) {
+            // Re-throw to trigger retry logic
+            throw new Error(`Graph API error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Flush queue immediately (for handoff/shutdown)
+     */
+    async flush() {
+        console.log('[EventQueue] Flushing queue...');
+        this.stop(); // Stop scheduled syncs
+        await this.syncToGraph(); // Final sync
+    }
+    /**
+     * Graceful shutdown with pending sync wait
+     */
+    async shutdown() {
+        console.log('[EventQueue] Initiating graceful shutdown...');
+        this.isShuttingDown = true;
+        // Stop scheduled syncs
+        this.stop();
+        // Wait for current sync to complete
+        const maxWaitMs = 30000; // 30 seconds max
+        const startTime = Date.now();
+        while (this.status.isRunning && (Date.now() - startTime) < maxWaitMs) {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        // Final flush
+        await this.flush();
+        console.log('[EventQueue] Shutdown complete');
+    }
+    /**
+     * Get current queue status
+     */
+    getStatus() {
+        return { ...this.status };
+    }
+    /**
+     * Schedule sync if needed (called after adding to queue)
+     */
+    scheduleSyncIfNeeded() {
+        // Already handled in addToQueue
+        // This method exists for API compatibility
+    }
+}
+/**
+ * Global queue instance (singleton)
+ */
+let globalQueue = null;
+/**
+ * Initialize global event queue
+ */
+export function initializeQueue(config) {
+    if (globalQueue) {
+        console.warn('[EventQueue] Queue already initialized');
+        return globalQueue;
+    }
+    globalQueue = new EventQueue(config);
+    globalQueue.start();
+    // Register shutdown handlers
+    const shutdownHandler = () => {
+        if (globalQueue) {
+            globalQueue.shutdown().catch(error => {
+                console.error('[EventQueue] Shutdown error:', error);
+            });
+        }
+    };
+    process.on('SIGINT', shutdownHandler);
+    process.on('SIGTERM', shutdownHandler);
+    return globalQueue;
+}
+/**
+ * Get global queue instance
+ */
+export function getQueue() {
+    if (!globalQueue) {
+        throw new Error('EventQueue not initialized. Call initializeQueue() first.');
+    }
+    return globalQueue;
+}
+/**
+ * Add event to global queue
+ */
+export async function addToQueue(event) {
+    // Lazy initialization on first use
+    if (!globalQueue) {
+        initializeQueue();
+    }
+    await globalQueue.addToQueue(event);
+}
+/**
+ * Check if queue is initialized
+ */
+export function isQueueInitialized() {
+    return globalQueue !== null;
+}
+//# sourceMappingURL=event-queue.js.map

package/dist/lib/event-queue.js.map

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

package/dist/lib/session-cursor.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-11-04
+ * @tags: [session, cursor, event-stream, adr-043, multi-context]
+ * @related: [commands/start/index.ts, utils/helpers.ts, lib/write-dispatcher/write-dispatcher.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: [fs-extra, simple-git]
+ */
+/**
+ * Session cursor interface (ADR-043)
+ * Cursors point into the event stream, scoped to user + project + branch
+ */
+export interface SessionCursor {
+    id: string;
+    user_id: string;
+    organization_id: string;
+    project_id: string;
+    branch: string;
+    current_event_id: string;
+    last_loaded_event_id?: string;
+    started: Date;
+    last_active: Date;
+    status: 'active' | 'paused';
+    context_snapshot?: any;
+}
+/**
+ * Create a new session cursor
+ */
+export declare function createCursor(params: {
+    branch: string;
+    projectId: string;
+    organizationId: string;
+    contextSnapshot?: any;
+}): Promise<SessionCursor>;
+/**
+ * Resume an existing cursor
+ */
+export declare function resumeCursor(cursorId: string): Promise<SessionCursor>;
+/**
+ * Update cursor properties
+ */
+export declare function updateCursor(cursorId: string, updates: Partial<SessionCursor>): Promise<SessionCursor>;
+/**
+ * Find a cursor matching the given filters
+ */
+export declare function findCursor(filters: {
+    branch?: string;
+    projectId?: string;
+    status?: 'active' | 'paused';
+}): Promise<SessionCursor | null>;
+/**
+ * List all cursors for a user
+ */
+export declare function listCursors(userId?: string): Promise<SessionCursor[]>;
+/**
+ * Delete a cursor
+ */
+export declare function deleteCursor(cursorId: string): Promise<void>;
+/**
+ * Create or resume cursor for current context
+ * This is the main entry point for session management
+ */
+export declare function getOrCreateCursor(options: {
+    branch?: string;
+    projectId?: string;
+}): Promise<{
+    cursor: SessionCursor;
+    isNew: boolean;
+}>;
+/**
+ * Pause current active cursor
+ */
+export declare function pauseCurrentCursor(options: {
+    branch?: string;
+    projectId?: string;
+    finalEventId?: string;
+}): Promise<SessionCursor | null>;
+//# sourceMappingURL=session-cursor.d.ts.map