specmem-hardwicksoftware 3.5.99

package/dist/utils/retryHelper.d.ts

@@ -0,0 +1,122 @@
+/**
+ * retryHelper.ts - Exponential Backoff Retry Utilities
+ *
+ * yo this handles transient failures like a CHAMP
+ * exponential backoff, jitter, configurable retry logic fr fr
+ *
+ * Task #40 fix - database retry logic
+ */
+/**
+ * Configuration for retry behavior
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Base delay in ms between retries */
+    baseDelayMs: number;
+    /** Maximum delay cap in ms */
+    maxDelayMs: number;
+    /** Backoff multiplier (default: 2 for exponential) */
+    backoffMultiplier: number;
+    /** Add random jitter to prevent thundering herd */
+    jitter: boolean;
+    /** Function to determine if error is retryable */
+    isRetryable?: (error: unknown) => boolean;
+    /** Called before each retry attempt */
+    onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+/**
+ * Default retry configuration - good for most DB operations
+ */
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Aggressive retry config - for critical operations
+ */
+export declare const AGGRESSIVE_RETRY_CONFIG: RetryConfig;
+/**
+ * Quick retry config - for fast operations that might flake
+ */
+export declare const QUICK_RETRY_CONFIG: RetryConfig;
+/**
+ * Check if an error is a transient database error that can be retried
+ */
+export declare function isTransientDbError(error: unknown): boolean;
+/**
+ * Calculate delay with exponential backoff and optional jitter
+ */
+export declare function calculateBackoffDelay(attempt: number, config: RetryConfig): number;
+/**
+ * Result of a retry operation
+ */
+export interface RetryResult<T> {
+    success: boolean;
+    result?: T;
+    error?: unknown;
+    attempts: number;
+    totalDelayMs: number;
+}
+/**
+ * Execute an async function with retry logic and exponential backoff
+ *
+ * @param fn - The async function to execute
+ * @param config - Retry configuration (uses DEFAULT_RETRY_CONFIG if not provided)
+ * @param context - Optional context string for logging
+ * @returns The result of the function if successful
+ * @throws The last error if all retries fail
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => pool.query('SELECT * FROM users'),
+ *   { maxRetries: 3, baseDelayMs: 1000 },
+ *   'fetch users'
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>, context?: string): Promise<T>;
+/**
+ * Execute an async function with retry, returning a result object instead of throwing
+ *
+ * @example
+ * ```ts
+ * const result = await tryWithRetry(() => riskyOperation());
+ * if (result.success) {
+ *   console.log('Got:', result.result);
+ * } else {
+ *   console.error('Failed after', result.attempts, 'attempts');
+ * }
+ * ```
+ */
+export declare function tryWithRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>, context?: string): Promise<RetryResult<T>>;
+/**
+ * Wrap a pool.query call with retry logic
+ *
+ * This is a convenience wrapper specifically for pg pool queries
+ *
+ * @example
+ * ```ts
+ * const result = await retryQuery(pool, 'SELECT * FROM users WHERE id = $1', [userId]);
+ * ```
+ */
+export declare function retryQuery<T = unknown>(pool: {
+    query: (text: string, params?: unknown[]) => Promise<{
+        rows: T[];
+    }>;
+}, text: string, params?: unknown[], config?: Partial<RetryConfig>): Promise<{
+    rows: T[];
+}>;
+/**
+ * Retry decorator for class methods
+ *
+ * @example
+ * ```ts
+ * class MyService {
+ *   @Retryable({ maxRetries: 3 })
+ *   async fetchData() {
+ *     // This method will be retried on transient failures
+ *   }
+ * }
+ * ```
+ */
+export declare function Retryable(config?: Partial<RetryConfig>): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+//# sourceMappingURL=retryHelper.d.ts.map

package/dist/utils/retryHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryHelper.d.ts","sourceRoot":"","sources":["../../src/utils/retryHelper.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C,uCAAuC;IACvC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtE;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAOlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAOrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAOhC,CAAC;AAyBF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoC1D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,MAAM,CAcR;AASD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EACjC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAqDZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EACjC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA+CzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1C,IAAI,EAAE;IAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,EAC7E,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC;IAAE,IAAI,EAAE,CAAC,EAAE,CAAA;CAAE,CAAC,CAMxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,IAEvD,SAAS,OAAO,EAChB,aAAa,MAAM,EACnB,YAAY,kBAAkB,wBAcjC"}

package/dist/utils/retryHelper.js

@@ -0,0 +1,272 @@
+/**
+ * retryHelper.ts - Exponential Backoff Retry Utilities
+ *
+ * yo this handles transient failures like a CHAMP
+ * exponential backoff, jitter, configurable retry logic fr fr
+ *
+ * Task #40 fix - database retry logic
+ */
+import { logger } from './logger.js';
+/**
+ * Default retry configuration - good for most DB operations
+ */
+export const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+    jitter: true,
+    isRetryable: isTransientDbError
+};
+/**
+ * Aggressive retry config - for critical operations
+ */
+export const AGGRESSIVE_RETRY_CONFIG = {
+    maxRetries: 5,
+    baseDelayMs: 500,
+    maxDelayMs: 60000,
+    backoffMultiplier: 2,
+    jitter: true,
+    isRetryable: isTransientDbError
+};
+/**
+ * Quick retry config - for fast operations that might flake
+ */
+export const QUICK_RETRY_CONFIG = {
+    maxRetries: 2,
+    baseDelayMs: 100,
+    maxDelayMs: 1000,
+    backoffMultiplier: 2,
+    jitter: true,
+    isRetryable: isTransientDbError
+};
+/**
+ * PostgreSQL transient error codes that can be retried
+ */
+const TRANSIENT_PG_CODES = new Set([
+    '40001', // serialization_failure
+    '40P01', // deadlock_detected
+    '57P01', // admin_shutdown
+    '57P02', // crash_shutdown
+    '57P03', // cannot_connect_now
+    '08006', // connection_failure
+    '08001', // sqlclient_unable_to_establish_sqlconnection
+    '08004', // sqlserver_rejected_establishment_of_sqlconnection
+    '08003', // connection_does_not_exist
+    '08000', // connection_exception
+    '53300', // too_many_connections
+    '53400', // configuration_limit_exceeded
+    '57P04', // database_dropped (rare but can retry on different db)
+    'ECONNRESET', // TCP connection reset
+    'ECONNREFUSED', // connection refused
+    'ETIMEDOUT', // connection timed out
+    'EPIPE', // broken pipe
+]);
+/**
+ * Check if an error is a transient database error that can be retried
+ */
+export function isTransientDbError(error) {
+    if (!error)
+        return false;
+    // Handle pg DatabaseError
+    if (error && typeof error === 'object') {
+        const err = error;
+        // PostgreSQL error code
+        if (typeof err['code'] === 'string' && TRANSIENT_PG_CODES.has(err['code'])) {
+            return true;
+        }
+        // Node.js system error
+        if (typeof err['errno'] === 'string' && TRANSIENT_PG_CODES.has(err['errno'])) {
+            return true;
+        }
+        // Connection errors in message
+        if (err instanceof Error) {
+            const msg = err.message.toLowerCase();
+            if (msg.includes('connection') ||
+                msg.includes('timeout') ||
+                msg.includes('econnreset') ||
+                msg.includes('econnrefused') ||
+                msg.includes('etimedout') ||
+                msg.includes('socket hang up') ||
+                msg.includes('network') ||
+                msg.includes('terminate')) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Calculate delay with exponential backoff and optional jitter
+ */
+export function calculateBackoffDelay(attempt, config) {
+    // Exponential backoff: baseDelay * (multiplier ^ attempt)
+    let delay = config.baseDelayMs * Math.pow(config.backoffMultiplier, attempt);
+    // Cap at maximum
+    delay = Math.min(delay, config.maxDelayMs);
+    // Add jitter to prevent thundering herd (0-50% of delay)
+    if (config.jitter) {
+        const jitterAmount = delay * 0.5 * Math.random();
+        delay = delay + jitterAmount;
+    }
+    return Math.floor(delay);
+}
+/**
+ * Sleep helper
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Execute an async function with retry logic and exponential backoff
+ *
+ * @param fn - The async function to execute
+ * @param config - Retry configuration (uses DEFAULT_RETRY_CONFIG if not provided)
+ * @param context - Optional context string for logging
+ * @returns The result of the function if successful
+ * @throws The last error if all retries fail
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => pool.query('SELECT * FROM users'),
+ *   { maxRetries: 3, baseDelayMs: 1000 },
+ *   'fetch users'
+ * );
+ * ```
+ */
+export async function withRetry(fn, config = {}, context) {
+    const fullConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+    const { maxRetries, isRetryable, onRetry } = fullConfig;
+    let lastError;
+    let totalDelayMs = 0;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Check if error is retryable
+            const canRetry = isRetryable ? isRetryable(error) : true;
+            if (!canRetry || attempt >= maxRetries) {
+                // Not retryable or out of attempts
+                logger.error({
+                    context,
+                    attempt: attempt + 1,
+                    maxRetries: maxRetries + 1,
+                    error: error instanceof Error ? error.message : String(error),
+                    totalDelayMs
+                }, 'retry exhausted - all attempts failed');
+                throw error;
+            }
+            // Calculate backoff delay
+            const delayMs = calculateBackoffDelay(attempt, fullConfig);
+            totalDelayMs += delayMs;
+            // Log and call onRetry callback
+            logger.warn({
+                context,
+                attempt: attempt + 1,
+                maxRetries: maxRetries + 1,
+                delayMs,
+                error: error instanceof Error ? error.message : String(error)
+            }, 'transient error - retrying with backoff');
+            if (onRetry) {
+                onRetry(attempt + 1, error, delayMs);
+            }
+            // Wait before retry
+            await sleep(delayMs);
+        }
+    }
+    // This should never be reached but TypeScript needs it
+    throw lastError;
+}
+/**
+ * Execute an async function with retry, returning a result object instead of throwing
+ *
+ * @example
+ * ```ts
+ * const result = await tryWithRetry(() => riskyOperation());
+ * if (result.success) {
+ *   console.log('Got:', result.result);
+ * } else {
+ *   console.error('Failed after', result.attempts, 'attempts');
+ * }
+ * ```
+ */
+export async function tryWithRetry(fn, config = {}, context) {
+    const fullConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+    const { maxRetries, isRetryable, onRetry } = fullConfig;
+    let lastError;
+    let totalDelayMs = 0;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const result = await fn();
+            return {
+                success: true,
+                result,
+                attempts: attempt + 1,
+                totalDelayMs
+            };
+        }
+        catch (error) {
+            lastError = error;
+            const canRetry = isRetryable ? isRetryable(error) : true;
+            if (!canRetry || attempt >= maxRetries) {
+                return {
+                    success: false,
+                    error: lastError,
+                    attempts: attempt + 1,
+                    totalDelayMs
+                };
+            }
+            const delayMs = calculateBackoffDelay(attempt, fullConfig);
+            totalDelayMs += delayMs;
+            if (onRetry) {
+                onRetry(attempt + 1, error, delayMs);
+            }
+            await sleep(delayMs);
+        }
+    }
+    return {
+        success: false,
+        error: lastError,
+        attempts: maxRetries + 1,
+        totalDelayMs
+    };
+}
+/**
+ * Wrap a pool.query call with retry logic
+ *
+ * This is a convenience wrapper specifically for pg pool queries
+ *
+ * @example
+ * ```ts
+ * const result = await retryQuery(pool, 'SELECT * FROM users WHERE id = $1', [userId]);
+ * ```
+ */
+export async function retryQuery(pool, text, params, config) {
+    return withRetry(() => pool.query(text, params), config, 'db query');
+}
+/**
+ * Retry decorator for class methods
+ *
+ * @example
+ * ```ts
+ * class MyService {
+ *   @Retryable({ maxRetries: 3 })
+ *   async fetchData() {
+ *     // This method will be retried on transient failures
+ *   }
+ * }
+ * ```
+ */
+export function Retryable(config = {}) {
+    return function (_target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            return withRetry(() => originalMethod.apply(this, args), config, propertyKey);
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=retryHelper.js.map

package/dist/utils/retryHelper.js.map

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

package/dist/utils/safeProcessTermination.d.ts

@@ -0,0 +1,206 @@
+/**
+ * safeProcessTermination.ts - Safe Process Termination with Ownership Verification
+ *
+ * CRITICAL SAFETY MODULE: Ensures SpecMem NEVER kills processes from other projects.
+ *
+ * Problem:
+ *   Multiple SpecMem instances can run on the same machine for different projects.
+ *   Killing processes by port or name without ownership verification is dangerous
+ *   and could terminate processes from OTHER projects.
+ *
+ * Solution:
+ *   1. PID ownership files: When spawning processes, write ownership metadata
+ *   2. Ownership verification: Before killing, verify the process belongs to us
+ *   3. Project-scoped naming: Screen sessions, containers include project identifier
+ *   4. Safe cleanup: Only clean resources we created
+ *
+ * @author hardwicksoftwareservices
+ */
+import { ChildProcess } from 'child_process';
+export interface ProcessOwnership {
+    /** PID of the process */
+    pid: number;
+    /** Project dir name that owns this process */
+    projectDirName: string;
+    /** Project path that owns this process */
+    projectPath: string;
+    /** Type of process (e.g., 'embedding', 'postgres', 'team-member', 'screen') */
+    processType: string;
+    /** Additional metadata about the process */
+    metadata?: Record<string, unknown>;
+    /** When the process was registered */
+    registeredAt: string;
+}
+export interface SafeKillResult {
+    /** Whether the kill was successful */
+    success: boolean;
+    /** PID that was targeted */
+    pid: number;
+    /** Whether we owned this process */
+    owned: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Whether process was already dead */
+    alreadyDead?: boolean;
+}
+/**
+ * Register ownership of a process.
+ * Call this when spawning any process that may need to be killed later.
+ *
+ * @param pid - Process ID to register
+ * @param processType - Type of process (e.g., 'embedding', 'team-member')
+ * @param metadata - Additional metadata to store
+ */
+export declare function registerProcessOwnership(pid: number, processType: string, metadata?: Record<string, unknown>): Promise<void>;
+/**
+ * Synchronous version of registerProcessOwnership
+ */
+export declare function registerProcessOwnershipSync(pid: number, processType: string, metadata?: Record<string, unknown>): void;
+/**
+ * Unregister ownership when a process exits normally
+ *
+ * @param pid - Process ID to unregister
+ */
+export declare function unregisterProcessOwnership(pid: number): Promise<void>;
+/**
+ * Synchronous version of unregisterProcessOwnership
+ */
+export declare function unregisterProcessOwnershipSync(pid: number): void;
+/**
+ * Get ownership info for a process
+ *
+ * @param pid - Process ID to check
+ * @returns Ownership info or null if not found
+ */
+export declare function getProcessOwnership(pid: number): Promise<ProcessOwnership | null>;
+/**
+ * Synchronous version of getProcessOwnership
+ */
+export declare function getProcessOwnershipSync(pid: number): ProcessOwnership | null;
+/**
+ * Check if we own a process
+ *
+ * @param pid - Process ID to check
+ * @returns True if we own this process
+ */
+export declare function isOwnedProcess(pid: number): boolean;
+/**
+ * Check if a process is running
+ */
+export declare function isProcessRunning(pid: number): boolean;
+/**
+ * Safely kill a process with ownership verification.
+ *
+ * This function will REFUSE to kill a process unless:
+ * 1. We have an ownership file for it, AND
+ * 2. The ownership file shows this project owns it
+ *
+ * @param pid - Process ID to kill
+ * @param signal - Signal to send (default: SIGTERM)
+ * @param options - Additional options
+ * @returns Result of the kill operation
+ */
+export declare function safeKillProcess(pid: number, signal?: NodeJS.Signals, options?: {
+    /** Force kill without ownership check (DANGEROUS - use sparingly) */
+    force?: boolean;
+    /** Process type for logging */
+    processType?: string;
+    /** Wait for process to exit */
+    waitMs?: number;
+    /** Force SIGKILL after timeout */
+    forceKillAfterTimeout?: boolean;
+}): SafeKillResult;
+/**
+ * Safely kill a process by port with ownership verification.
+ *
+ * First finds the PID using the port, then verifies ownership before killing.
+ *
+ * @param port - Port number to kill process on
+ * @param signal - Signal to send
+ * @returns Result of the kill operation
+ */
+export declare function safeKillByPort(port: number, signal?: NodeJS.Signals): SafeKillResult;
+/**
+ * Get a project-scoped screen session name.
+ * This ensures screen sessions are unique per project.
+ *
+ * @param baseName - Base name for the session (e.g., 'team-member-123')
+ * @returns Full session name with project prefix
+ */
+export declare function getProjectScopedScreenName(baseName: string): string;
+/**
+ * Check if a screen session belongs to this project
+ *
+ * @param sessionName - Full screen session name
+ * @returns True if the session belongs to this project
+ */
+export declare function isOwnedScreenSession(sessionName: string): boolean;
+/**
+ * Safely kill a screen session with ownership verification.
+ *
+ * @param sessionName - Screen session name (will be checked for project ownership)
+ * @param options - Additional options
+ * @returns Success status
+ */
+export declare function safeKillScreenSession(sessionName: string, options?: {
+    force?: boolean;
+}): {
+    success: boolean;
+    error?: string;
+    owned: boolean;
+};
+/**
+ * List all screen sessions belonging to this project
+ *
+ * @returns Array of owned session names
+ */
+export declare function listOwnedScreenSessions(): string[];
+/**
+ * Get a project-scoped Docker container name.
+ *
+ * @param baseName - Base name for the container (e.g., 'embedding', 'postgres')
+ * @returns Full container name with project prefix
+ */
+export declare function getProjectScopedContainerName(baseName: string): string;
+/**
+ * Check if a Docker container name belongs to this project
+ *
+ * @param containerName - Container name to check
+ * @returns True if container belongs to this project
+ */
+export declare function isOwnedContainer(containerName: string): boolean;
+/**
+ * Spawn a child process with automatic ownership registration.
+ *
+ * @param command - Command to run
+ * @param args - Arguments
+ * @param processType - Type of process for ownership tracking
+ * @param options - Spawn options
+ * @returns ChildProcess with ownership registered
+ */
+export declare function spawnWithOwnership(command: string, args: string[], processType: string, options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    detached?: boolean;
+    metadata?: Record<string, unknown>;
+}): ChildProcess;
+/**
+ * Clean up stale ownership files for processes that no longer exist.
+ */
+export declare function cleanupStaleOwnershipFiles(): Promise<{
+    cleaned: number;
+    errors: string[];
+}>;
+/**
+ * Get all processes owned by this project
+ */
+export declare function getOwnedProcesses(): Promise<ProcessOwnership[]>;
+/**
+ * Kill all processes owned by this project.
+ * Use during shutdown to clean up all spawned processes.
+ */
+export declare function killAllOwnedProcesses(signal?: NodeJS.Signals): Promise<{
+    killed: number[];
+    failed: number[];
+}>;
+//# sourceMappingURL=safeProcessTermination.d.ts.map

package/dist/utils/safeProcessTermination.d.ts.map

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