yvgude--lean-ctx/docs/reference/appendix-jetbrains-plugin.md

Appendix — JetBrains Plugin (Agent Reference)

Compact lookup tables for agents: every ctx_refactor action, its HTTP endpoint, key parameters, backing — plus the user-facing IDE surfaces (Gain Tool Window, editor-focus reporter, status-bar widget, Tools-menu actions). Full description (curl, responses, guards, architecture, E2E): Journey 19 — JetBrains Plugin.

Language: English; tool/endpoint/parameter names and error codes stay verbatim. Serena delineation: an independent reimplementation (not a derivation, lean-ctx license) — it replaces Serena + the official JetBrains MCP as the code-intelligence interface.

Coordinates & invocation

• Invocation: ctx_refactor action=<action> … (MCP) or POST 127.0.0.1:<port><endpoint> with header X-LeanCtx-Token: <token>, body = JSON.
• ctx_refactor layer: line 1-indexed, column 0-indexed. Wire layer: line/character 0-based; line in type_hierarchy / symbols_overview / inspections responses is 1-based.
• Business-level negative case: HTTP 200 + {"error":{"code","message"}}.

Functions

Action	HTTP endpoint	Purpose	Key parameters	Backing
references	POST /references	semantic usages	path, line, column, scope	B (+A fallback)
definition	POST /definition	jump to definition	path, line, column	B (+A fallback)
implementations	POST /implementations	implementations/overrides	path, line, column, scope	B (+A fallback)
declaration	POST /declaration	declaration	path, line, column	B-only
type_hierarchy	POST /type_hierarchy	super-/subtype tree	path, line, column, direction	B-only
symbols_overview	POST /symbols_overview	top-level symbols of the file	path	B (+headless tree-sitter)
inspections	POST /inspections, POST /list_inspections	run/list inspections	path, mode=run|list	B-only
replace_symbol_body	POST /replaceSymbolBody	replace symbol body	name_path/path+line, new_body, expected_hash	B (+headless)
insert_before_symbol	POST /insertBeforeSymbol	insert sibling before	name_path, text, expected_hash	B (+headless)
insert_after_symbol	POST /insertAfterSymbol	insert sibling after	name_path, text, expected_hash	B (+headless)
rename	POST /renamePreview → /renameApply	rename symbol + all usages	new_name, force, search_comments	B-only (BACKEND_REQUIRED)
reformat	POST /reformat	reformat file in-place	path	B-only
move	POST /movePreview → /moveApply	move symbol + references	target, force	B-only (BACKEND_REQUIRED)
safe_delete	POST /safeDeletePreview → /safeDeleteApply	delete when no blockers	force	B-only (BACKEND_REQUIRED)
inline	POST /inlinePreview → /inlineApply	inline symbol at call sites	force	B-only (BACKEND_REQUIRED)

Backing: B = JetBrains IDE (plugin via HTTP); A = rust-analyzer (headless); headless = tree-sitter / local_range_write without an IDE. The refactoring engine (rename/move/safe_delete/inline) is two-phase (*Preview→*Apply, plan_hash-protected) and has no headless path.

find_symbol (Serena) → ctx_search action="symbol" / ctx_outline, not ctx_refactor.

IDE UI surfaces (non-HTTP)

These are user-facing IDE touchpoints, not part of the ctx_refactor HTTP surface. See the Gain Tool Window (§4), Editor-Focus Reporter (§5) and IDE UI Integration (§6) sections of Journey 19 for full detail.

Surface	Identifier / registry key	What it does	Backing
Gain Tool Window	GAIN_TOOL_WINDOW_ID ("LeanCtxGain")	dockable bottom tool window rendering the Gain report; visibility-gated 30 s polling (GainPollController)	lean-ctx gain --json subprocess (off EDT, 10 s timeout)
Editor-focus reporter	leanctx.editor.signal.enabled (default true)	reports the focused editor file path (path only, in-project) to lift #500 ranking; 2 s debounce, opt-out via registry key	lean-ctx editor-signal --file <absPath> (fire-and-forget)
Status-bar widget	id="com.leanctx.statusBar", order="after encodingWidget"	shows ⚡ <N> saved (30 s refresh); click activates the Gain Tool Window	StatsReader reads ~/.lean-ctx/stats.json
Tools menu (lean-ctx)	action group LeanCtx.Menu (ToolsMenu, anchor last)	four actions: Setup / Doctor / Gain Report / Dashboard	per-action (see below)

Tools-menu actions

Action	ID	Runs	Output
Setup	LeanCtx.Setup	lean-ctx setup	Messages popup (ANSI-stripped)
Doctor	LeanCtx.Doctor	lean-ctx doctor	Messages popup (ANSI-stripped)
Gain Report	LeanCtx.Gain	activates the Gain Tool Window (GAIN_TOOL_WINDOW_ID)	tool window (no binary spawn)
Dashboard	LeanCtx.Dashboard	lean-ctx dashboard	fire-and-forget (CLI opens its own dashboard)

Setup/Doctor extend LeanCtxCommandAction(vararg args): run BinaryResolver.runCommand, pipe captured stdout (or stderr when blank) through stripAnsi (util/AnsiText.kt, regex \[[0-9;?]*[ -/]*[@-~], fix b933e510), then show a Messages.showInfoMessage popup titled lean-ctx. GainAction and DashboardAction extend AnAction directly.

Guards (short form)

• BLAKE3 conflict guard (expected_hash edits / plan_hash refactoring) — Rust-central; the plugin does not hash. Mismatch → CONFLICT.
• PathJail — every mutation and every reported path is checked against project_root.
• Smart mode — dumb mode → INDEXING (no partial result).
• Auth — X-LeanCtx-Token per project; missing → 401. 127.0.0.1 only.
• Gain subprocess isolation — the Gain Tool Window shells out to lean-ctx gain --json (off the EDT, 10 s timeout); GainScore stays the single source of truth in Rust, Kotlin only renders. Failures map to typed panel states (BinaryNotFound / Failed(reason)), never an exception.
• Editor-focus privacy — path only, never file content; only real, local files inside the current project are reported (no scratch/library/directory buffers). Missing/old binary or IO error is swallowed silently.
• Output hygiene — all CLI output shown in the IDE (Gain panel, Setup/Doctor popups) is ANSI-stripped via stripAnsi before display.

Error codes

Code	Trigger	Fix
UNAUTHORIZED (401)	token missing/wrong	send a valid X-LeanCtx-Token
NOT_FOUND (404)	unknown route	check the endpoint path
FILE_NOT_FOUND	file not readable	verify the path with ctx_tree
POSITION_OUT_OF_RANGE	line/column past EOF	re-resolve the range
CONFLICT	hash mismatch or conflicts ∧ !force	re-read fresh; use force if appropriate
AMBIGUOUS_SYMBOL	name_path > 1 match	qualify (Class/method)
NO_SYMBOL	name_path 0 matches	correct the name/path
INDEXING	IDE in dumb mode	wait, retry
UNSUPPORTED_LANGUAGE	no LSP/PSI processor	language not supported
BACKEND_REQUIRED	refactoring without an IDE	open the IDE with the project
INTERNAL	other error	check the message

The Gain Tool Window and editor-focus reporter are subprocess/CLI consumers, not HTTP endpoints — they do not surface the codes above. Gain failures map to the BinaryNotFound / Failed(reason) panel states (see §4.1); a lost editor-focus signal is silent and harmless.

See also

• Journey 19 — JetBrains Plugin — full reference (Gain Tool Window §4, Editor-Focus Reporter §5, IDE UI Integration §6)
• MCP tool map · Per-IDE quickstarts