patchwork-os 0.2.0-alpha.0

package/dist/extensionClient.d.ts

@@ -0,0 +1,279 @@
+import { WebSocket } from "ws";
+import type { Logger } from "./logger.js";
+/** Thrown when an extension request times out — distinguishable from "no results" (null). */
+export declare class ExtensionTimeoutError extends Error {
+    readonly method: string;
+    constructor(method: string);
+}
+export interface Diagnostic {
+    file: string;
+    line: number;
+    column: number;
+    severity: "error" | "warning" | "information" | "hint";
+    message: string;
+    source?: string;
+    code?: string | number;
+    /** Standard LSP relatedInformation — capped at 5 entries in getDiagnostics sanitizer. */
+    relatedInformation?: Array<{
+        message: string;
+        file?: string;
+        line?: number;
+        column?: number;
+    }>;
+}
+export interface SelectionState {
+    file: string;
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+    selectedText: string;
+}
+export interface TabInfo {
+    filePath: string;
+    isActive: boolean;
+    isDirty: boolean;
+    languageId?: string;
+}
+export interface AIComment {
+    file: string;
+    line: number;
+    comment: string;
+    syntax: string;
+    fullLine: string;
+    severity?: "fix" | "todo" | "question" | "warn" | "task";
+}
+export interface DebugState {
+    hasActiveSession: boolean;
+    sessionId?: string;
+    sessionName?: string;
+    sessionType?: string;
+    isPaused: boolean;
+    pausedAt?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    callStack?: Array<{
+        id: number;
+        name: string;
+        file: string;
+        line: number;
+        column: number;
+    }>;
+    scopes?: Array<{
+        name: string;
+        variables: Array<{
+            name: string;
+            value: string;
+            type: string;
+        }>;
+    }>;
+    breakpoints: Array<{
+        file: string;
+        line: number;
+        condition?: string;
+        enabled: boolean;
+    }>;
+}
+export interface BreakpointSpec {
+    line: number;
+    condition?: string;
+    logMessage?: string;
+    hitCondition?: string;
+}
+export interface DecorationSpec {
+    startLine: number;
+    endLine?: number;
+    message?: string;
+    hoverMessage?: string;
+    style: "info" | "warning" | "error" | "focus" | "strikethrough" | "dim";
+}
+export interface WorkspaceFolder {
+    name: string;
+    path: string;
+    uri: string;
+    index: number;
+}
+export declare class ExtensionClient {
+    private logger;
+    private ws;
+    private connected;
+    private pendingRequests;
+    private nextId;
+    private static readonly CIRCUIT_WINDOW_MS;
+    private static readonly CIRCUIT_THRESHOLD;
+    private extensionSuspendedUntil;
+    private extensionFailureTimes;
+    private extensionHalfOpen;
+    private _circuitOpenCount;
+    private _lastCircuitOpenedAt;
+    latestDiagnostics: Map<string, Diagnostic[]>;
+    /** Parallel timestamp map — tracks when each file's diagnostics were last updated. */
+    private latestDiagnosticsUpdatedAt;
+    private static readonly DIAGNOSTICS_TTL_MS;
+    latestSelection: SelectionState | null;
+    latestActiveFile: string | null;
+    lastDiagnosticsUpdate: number;
+    latestAIComments: Map<string, AIComment[]>;
+    latestDebugState: DebugState | null;
+    lspReadyLanguages: Set<string>;
+    lastRttMs: number | null;
+    extensionPackageVersion: string | null;
+    onDiagnosticsChanged: ((file: string, diagnostics: Diagnostic[]) => void) | null;
+    onAICommentsChanged: ((comments: AIComment[]) => void) | null;
+    onFileChanged: ((id: string, type: string, file: string) => void) | null;
+    onExtensionDisconnected: (() => void) | null;
+    onDebugSessionChanged: ((state: DebugState) => void) | null;
+    private diagnosticsListeners;
+    constructor(logger: Logger);
+    /** Invoke a callback safely — log and swallow errors to prevent bridge crash */
+    private safeCallback;
+    handleExtensionConnection(ws: WebSocket): void;
+    private handleNotification;
+    private static readonly MAX_PENDING_REQUESTS;
+    private request;
+    /** Like request() but returns null on disconnect instead of rejecting.
+     *  ExtensionTimeoutError is NOT caught — callers must handle it to distinguish
+     *  timeout from genuine "no results" (null). */
+    private requestOrNull;
+    private rejectAllPending;
+    /**
+    /**
+     * Detect an extension error-object response. Extension handlers by convention
+     * return `{ error: string }` (sometimes with `success: false`) on failure
+     * instead of throwing. This predicate identifies that shape so tryRequest
+     * can convert it to null.
+     */
+    private isErrorResponse;
+    /**
+     * Safer shorthand for requestOrNull — converts extension error-object responses
+     * (see isErrorResponse) to null so consumers can distinguish "no result" from
+     * "corrupt data". Use this for any handler whose success and failure paths
+     * return different shapes. Does NOT guarantee the happy-path shape matches T;
+     * for that, do a runtime shape check in the client method.
+     */
+    private tryRequest;
+    /**
+     * Shape-validated request — handles shape-wrap bugs where the extension
+     * handler returns a different structural shape than the client expects
+     * (e.g. `{ folders, count }` vs `WorkspaceFolder[]`).
+     *
+     * Combines error-object detection from tryRequest with a runtime validator.
+     * If `validate` returns null, the response shape did not match and the
+     * client should return null — preventing silent data corruption downstream.
+     *
+     * Use for any handler whose success shape is non-trivial. Prefer over
+     * proxy<T> when the response is an object with specific required fields.
+     */
+    private validatedRequest;
+    getDiagnostics(file?: string): Promise<Diagnostic[] | null>;
+    getSelection(): Promise<SelectionState | null>;
+    getOpenFiles(): Promise<TabInfo[] | null>;
+    isDirty(file: string): Promise<boolean | null>;
+    getFileContent(file: string): Promise<unknown>;
+    openFile(file: string, line?: number): Promise<boolean>;
+    saveFile(file: string): Promise<{
+        saved: boolean;
+        error?: string;
+    } | null>;
+    closeTab(file: string): Promise<{
+        success: boolean;
+        promptedToSave?: boolean;
+        error?: string;
+    } | null>;
+    getAIComments(): Promise<AIComment[] | null>;
+    goToDefinition(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    findReferences(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    findImplementations(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    goToTypeDefinition(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    goToDeclaration(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    getHover(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    getCodeActions(file: string, startLine: number, startColumn: number, endLine: number, endColumn: number, signal?: AbortSignal): Promise<unknown>;
+    applyCodeAction(file: string, startLine: number, startColumn: number, endLine: number, endColumn: number, actionTitle: string, signal?: AbortSignal): Promise<unknown>;
+    previewCodeAction(file: string, startLine: number, startColumn: number, endLine: number, endColumn: number, actionTitle: string, signal?: AbortSignal): Promise<unknown>;
+    renameSymbol(file: string, line: number, column: number, newName: string, signal?: AbortSignal): Promise<unknown>;
+    searchSymbols(query: string, maxResults?: number, signal?: AbortSignal): Promise<unknown>;
+    prepareRename(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    formatRange(file: string, startLine: number, endLine: number, signal?: AbortSignal): Promise<unknown>;
+    signatureHelp(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    foldingRanges(file: string, signal?: AbortSignal): Promise<unknown>;
+    selectionRanges(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
+    watchFiles(id: string, pattern: string): Promise<unknown>;
+    unwatchFiles(id: string): Promise<unknown>;
+    captureScreenshot(): Promise<{
+        base64: string;
+        mimeType: string;
+    } | null>;
+    listTerminals(): Promise<unknown>;
+    getTerminalOutput(name?: string, index?: number, lines?: number): Promise<unknown>;
+    disposeTerminal(name?: string, index?: number): Promise<unknown>;
+    createFile(filePath: string, content?: string, isDirectory?: boolean, overwrite?: boolean, openAfterCreate?: boolean): Promise<unknown>;
+    deleteFile(filePath: string, recursive?: boolean, useTrash?: boolean): Promise<unknown>;
+    renameFile(oldPath: string, newPath: string, overwrite?: boolean): Promise<unknown>;
+    editText(filePath: string, edits: unknown[], save?: boolean): Promise<unknown>;
+    replaceBlock(filePath: string, oldContent: string, newContent: string, save?: boolean): Promise<unknown>;
+    getDocumentSymbols(file: string, signal?: AbortSignal): Promise<unknown>;
+    getCallHierarchy(file: string, line: number, column: number, direction?: string, maxResults?: number, signal?: AbortSignal): Promise<unknown>;
+    formatDocument(file: string): Promise<unknown>;
+    fixAllLintErrors(file: string): Promise<unknown>;
+    organizeImports(file: string): Promise<unknown>;
+    createTerminal(name?: string, cwd?: string, env?: Record<string, string>, show?: boolean): Promise<unknown>;
+    sendTerminalCommand(text: string, name?: string, index?: number, addNewline?: boolean): Promise<unknown>;
+    waitForTerminalOutput(pattern: string, name?: string, index?: number, timeoutMs?: number): Promise<unknown>;
+    executeInTerminal(command: string, name?: string, index?: number, timeoutMs?: number, show?: boolean): Promise<unknown>;
+    getDebugState(): Promise<DebugState | null>;
+    evaluateInDebugger(expression: string, frameId?: number, context?: string, signal?: AbortSignal): Promise<unknown>;
+    setDebugBreakpoints(file: string, breakpoints: BreakpointSpec[], signal?: AbortSignal): Promise<unknown>;
+    startDebugging(configName?: string, signal?: AbortSignal): Promise<unknown>;
+    stopDebugging(signal?: AbortSignal): Promise<unknown>;
+    setDecorations(id: string, file: string, decorations: DecorationSpec[]): Promise<unknown>;
+    clearDecorations(id?: string): Promise<unknown>;
+    executeVSCodeCommand(command: string, args?: unknown[]): Promise<unknown>;
+    listVSCodeCommands(filter?: string): Promise<{
+        commands: string[];
+        total: number;
+        capped: boolean;
+    } | null>;
+    getWorkspaceSettings(section?: string, target?: string): Promise<unknown>;
+    setWorkspaceSetting(key: string, value: unknown, target?: string): Promise<unknown>;
+    readClipboard(): Promise<unknown>;
+    writeClipboard(text: string): Promise<unknown>;
+    getInlayHints(file: string, startLine: number, endLine: number): Promise<unknown>;
+    getTypeHierarchy(file: string, line: number, column: number, direction?: string, maxResults?: number, signal?: AbortSignal): Promise<unknown>;
+    getCodeLens(file: string, signal?: AbortSignal): Promise<unknown>;
+    getSemanticTokens(file: string, startLine?: number, endLine?: number, maxTokens?: number, signal?: AbortSignal): Promise<unknown>;
+    getDocumentLinks(file: string, signal?: AbortSignal): Promise<unknown>;
+    listTasks(type?: string): Promise<unknown>;
+    runTask(name: string, type?: string, timeoutMs?: number): Promise<unknown>;
+    getWorkspaceFolders(): Promise<WorkspaceFolder[] | null>;
+    getNotebookCells(file: string): Promise<unknown>;
+    runNotebookCell(file: string, cellIndex: number, timeoutMs?: number): Promise<unknown>;
+    getNotebookOutput(file: string, cellIndex: number): Promise<unknown>;
+    getCachedDiagnostics(file?: string): Diagnostic[];
+    addDiagnosticsListener(listener: (file: string, diagnostics: Diagnostic[]) => void): () => void;
+    /** Notify the extension about Claude Code connection state changes */
+    notifyClaudeConnectionState(connected: boolean, stats?: {
+        callCount: number;
+        errorCount: number;
+        durationMs: number;
+    }): void;
+    /** Push a Claude task output chunk to the VS Code output channel. Best-effort. */
+    notifyTaskOutput(taskId: string, chunk: string): void;
+    /** Push a Claude task completion status to the VS Code output channel. Best-effort. */
+    notifyTaskDone(taskId: string, status: string): void;
+    getCircuitBreakerState(): {
+        suspended: boolean;
+        suspendedUntil: number;
+        failures: number;
+        openCount: number;
+        lastOpenedAt: string | null;
+    };
+    isConnected(): boolean;
+    /**
+     * Push a server-initiated notification to the connected extension.
+     * Non-fatal: silently drops if extension is not connected or send fails.
+     */
+    sendPush(method: string, params: Record<string, unknown>): void;
+    disconnect(): void;
+}