/**
 * VS Code-family terminal keybinding repair. VS Code hands Ctrl+R to the
 * workbench (Open Recent) even while an integrated terminal owns focus, so
 * the reasoning-fold key never reaches the TUI. Workspace-scoped keybindings
 * do not exist, so the fix is one user-level keybindings.json rule that
 * forwards the raw Ctrl byte via sendSequence under terminalFocus. This
 * module detects the hosting editor variant, resolves its user
 * keybindings.json, and merges the rule idempotently; pure merge/detect
 * helpers are separated from the fs orchestration so both stay testable.
 * @module @deepseek-ai/dsh-code/editor-keys
 */
/** Integrated-terminal editor variants this module can repair. */
export type EditorTerminalFamily = 'vscode' | 'cursor' | 'vscodium' | 'windsurf';
/**
 * Detect the editor hosting this integrated terminal.
 * @param env - process environment (TERM_PROGRAM decides; case/whitespace tolerant).
 * @returns the family, or undefined outside VS Code-family terminals.
 */
export declare function detectEditorTerminalFamily(env?: NodeJS.ProcessEnv): EditorTerminalFamily | undefined;
/**
 * Whether the pty is hosted away from the editor UI (ssh/container/tunnel).
 * Keybindings live on the client machine, so a remote session must never
 * write them server-side.
 */
export declare function isRemoteTerminalEnv(env?: NodeJS.ProcessEnv): boolean;
/** Filesystem anchors used to resolve editor config paths (injectable for tests). */
export interface EditorPathContext {
    /** User home directory. */
    homedir: string;
    /** %APPDATA% on Windows; only read for win32 resolution. */
    appdata?: string;
    /** Node platform qualifier. */
    platform: NodeJS.Platform;
}
/**
 * Resolve the user keybindings.json candidates for one family, most likely
 * install first. Only paths that exist on disk are repaired.
 */
export declare function editorKeybindingCandidates(family: EditorTerminalFamily, context: EditorPathContext): readonly string[];
/** The one workbench rule that hands Ctrl+R to the focused terminal. */
export declare const CTRL_R_PASSTHROUGH_RULE: {
    readonly key: "ctrl+r";
    readonly command: "workbench.action.terminal.sendSequence";
    readonly args: {
        readonly text: "\u0012";
    };
    readonly when: "terminalFocus";
};
/**
 * Remove // and block comments from one JSONC document. Double-quoted strings
 * survive untouched, so comment markers inside string values are preserved.
 */
export declare function stripJsoncComments(text: string): string;
/** Parse one JSONC document; trailing commas are tolerated. */
export declare function parseJsonc(text: string): unknown;
/** Outcome of merging the passthrough rule into one keybindings document. */
export type KeybindingsMerge = {
    readonly status: 'present';
} | {
    readonly status: 'updated';
    readonly text: string;
} | {
    readonly status: 'created';
    readonly text: string;
};
/**
 * Merge the Ctrl+R passthrough into one keybindings.json document. The raw
 * text is preserved verbatim (comments included); the rule is inserted right
 * after the array opener so it cannot be shadowed by later conflicting user
 * rules. Missing files resolve to a fresh template.
 * @throws when the document does not carry a rule array.
 */
export declare function mergeCtrlRPassthrough(raw: string | undefined): KeybindingsMerge;
/** User-level marker file content: the startup hint fires at most once per install. */
export interface EditorKeysFlag {
    hintShownAt?: string;
}
/** Parse one flag file snapshot; missing or corrupt content degrades to unshown. */
export declare function parseEditorKeysFlag(raw: string | undefined): EditorKeysFlag;
/** Persist the shown marker; best-effort, the hint is cosmetic and never a gate. */
export declare function markEditorKeysHintShown(path: string): Promise<void>;
/** Inputs shared by the apply and startup-hint flows. */
export interface EditorKeysEnv {
    /** Process environment (TERM_PROGRAM / VSCODE_IPC_HOOK_CLI). */
    env: NodeJS.ProcessEnv;
    /** Filesystem anchors for editor config resolution. */
    paths: EditorPathContext;
    /** Absolute path of the one-shot hint marker under the DSH home. */
    flagPath: string;
}
/**
 * Apply the Ctrl+R passthrough to every local keybindings.json of the hosting
 * editor and mark the startup hint shown. Existing files get a .dsh-bak
 * backup before the first write.
 * @returns a one-line user-facing summary.
 * @throws with an actionable message when the environment cannot be repaired.
 */
export declare function applyCtrlRPassthrough({ env, paths, flagPath }: EditorKeysEnv): Promise<string>;
/**
 * Resolve the one-shot startup hint for VS Code-family terminals. Fires at
 * most once per install (flag file), never when the passthrough rule is
 * already present, and never in remote ptys where the repair cannot run.
 * @returns the hint line, or undefined to stay silent.
 */
export declare function resolveEditorKeysStartupHint({ env, paths, flagPath }: EditorKeysEnv): Promise<string | undefined>;