socraticode/dist/services/lock.d.ts

SocratiCode — MCP server for local codebase indexing, semantic search, and code dependency graphs. All private, all local via Docker.

/**
 * Try to acquire a cross-process lock for a project operation.
 *
 * @param projectPath - Absolute path to the project directory
 * @param operation - Operation type: "index" or "watch"
 * @param onCompromised - Called if the lock is lost while still held. The lock
 *   guards a shared collection, so losing it means another process may now be
 *   writing to what this one is still writing to; the caller is the only thing
 *   that knows how to stand down. It runs from proper-lockfile's timer, where
 *   nothing is waiting on it, so both a synchronous throw and a rejected
 *   promise are logged and swallowed rather than becoming an unhandled
 *   rejection.
 * @returns true if the lock was acquired, false if another process holds it
 */
export declare function acquireProjectLock(projectPath: string, operation: string, onCompromised?: (err: Error) => void | Promise<void>, options?: {
    reentrant?: boolean;
    projectId?: string;
}): Promise<boolean>;
/** Reclamation addresses an identity whose directory may be gone, so it locks by identity, not path. */
export declare function acquireIdentityLock(projectId: string, operation: string, onCompromised?: (err: Error) => void | Promise<void>, projectPath?: string, reentrant?: boolean): Promise<boolean>;
/**
 * Whether this process still holds the lock for a project operation.
 *
 * `onCompromised` removes the entry when proper-lockfile reports the lock lost,
 * so this answers false from the moment ownership is known to be gone. Callers
 * use it to decide whether a write they were about to make is still theirs to
 * make — once another process may hold the lock, the safe move is to stop
 * rather than to correct, since a correction would overwrite the new holder.
 */
export declare function holdsProjectLock(projectPath: string, operation: string, projectId?: string): boolean;
/** Whether this process holds the lock for a recorded project identity. */
export declare function holdsIdentityLock(projectId: string, operation: string): boolean;
/**
 * Release a previously acquired lock.
 *
 * @param projectPath - Absolute path to the project directory
 * @param operation - Operation type: "index" or "watch"
 */
export declare function releaseProjectLock(projectPath: string, operation: string, projectId?: string): Promise<void>;
/** Release a lock acquired through {@link acquireIdentityLock}. */
export declare function releaseIdentityLock(projectId: string, operation: string, projectPath?: string): Promise<void>;
/**
 * Check if a lock is currently held (by any process).
 */
export declare function isProjectLocked(projectPath: string, operation: string): Promise<boolean>;
/** A lock whose state could not be read; a caller about to delete must treat it as held. */
export declare class LockInspectionError extends Error {
    readonly projectId: string;
    readonly operation: string;
    constructor(projectId: string, operation: string, cause: unknown);
}
/** Check a lock by identity; throws LockInspectionError when the answer is unknown rather than answering false. */
export declare function isProjectIdentityLocked(projectId: string, operation: string): Promise<boolean>;
/**
 * Read the PID stored in the lock file and verify the process is still alive.
 * Returns the PID if the lock is held by a live process, or null otherwise.
 */
export declare function getLockHolderPid(projectPath: string, operation: string): Promise<number | null>;
/**
 * Attempt to terminate an orphan process holding a project lock.
 * On POSIX (macOS/Linux): sends SIGTERM for graceful shutdown.
 * On Windows: uses `taskkill /F /PID` since cross-process SIGTERM is not supported.
 * Returns true if the termination signal was sent successfully, false otherwise.
 */
export declare function terminateLockHolder(projectPath: string, operation: string): Promise<{
    terminated: boolean;
    pid: number | null;
}>;
/**
 * Release all locks held by this process.
 * Called during graceful shutdown.
 */
export declare function releaseAllLocks(): Promise<void>;
//# sourceMappingURL=lock.d.ts.map