Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
/**
* The mod's entry, and the only file that touches `$`. Each hook builds a Host
* from its own `$`, feeds events to the model, and redraws. Lens only
* observes: every hook passes its event on unchanged.
*/
import { getSavings } from "@repowise-dev/api-client/costs";
import { discover, isWindowsPath, readFreshness, type Discovery } from "./data/discovery";
import { callTool, fetchFileContext, mcpReady, resetMcp, warmMcp } from "./data/mcp";
import { withTimeout } from "./data/transport";
import { fit } from "./format";
import type { Host } from "./host";
import { Animator } from "./animator";
import { LensFlow, type FlowPane } from "./flow-controller";
import { themeOf, type ThemeName } from "./views/theme";
import { litFromFlow, litFromTrail, storyFromFlow, storyFromTrail, type Story } from "./model/story";
import { NO_LIT, type Lit } from "./views/overlay";
import { MAP_PRESSES } from "./views/mapPane";
import { knowsOf, type Knows } from "./model/inspect";
import { LensMap, type MapIO, type MapRepo } from "./map-controller";
import type {
CommandRunEvent,
ModApi,
On,
PaneRenderEvent,
PluginOptions,
PostCompactEvent,
PostToolUseEvent,
RenderEvent,
SessionEndEvent,
SessionStartEvent,
SpinnerEvent,
ToolCallEvent,
ToolResultEvent,
ToolUseEvent,
TurnCompleteEvent,
TurnStartEvent,
UiInputEvent,
} from "./mod-api";
import { activityOf, toolEnded, turnEnd, type FlowAction } from "./model/flow";
import { blastFacts, type BlastResponse } from "./model/turnFacts";
import {
EDIT_TOOLS,
OBSERVED_TOOLS,
absolutePath,
fileTarget,
fromToolCall,
fromTurnComplete,
notesFromAugment,
savingsSince,
savingsTotals,
touchedPath,
} from "./model/events";
import { askReply, askRoute, lensCommand, whyDraft, type BarTab, type PaneTab } from "./model/ask";
import { clearedConversation, hintFor, initialSession, reduce, type SavingsDelta, type SessionAction, type SessionState } from "./model/session";
import { bandView } from "./views/band";
import { materialize, text, type ElementTable, type Node } from "./views/elements";
import { marginView } from "./views/margin";
import { isFileEdit, isRetryable, shouldReview, type ChangeRisk } from "./model/review";
import { BRIEF_PRESS, briefText } from "./views/brief";
import { HINTS, MAP_COPY, PANE_COPY, REVIEW_TIMEOUT_S } from "./views/copy";
import { FLOW_NEXT, flowPresses } from "./views/flow";
import { ASK_KEY, TAB_ROWS, askView, paneView, recapView, tabBar, tabPress } from "./views/pane";
import { PRESS, directiveRows, reviewText, runTestsText, withCard } from "./views/review";
import { spinnerSuffix } from "./views/spinner";
import { bashText, parseSqueeze, type Squeeze } from "./model/squeeze";
import { squeezeView } from "./views/squeeze";
const PROCESS_TIMEOUT_MS = 5_000;
/** The savings route scans transcripts: 0.24 s on a quiet store, 5-12 s on a busy one. */
const SAVINGS_TIMEOUT_MS = 30_000;
const SAVINGS_COOLDOWN_MS = 60_000;
/** The server's key in the plugin's .mcp.json. */
const MCP_SERVER_KEY = "repowise";
const PANE_ID = "lens";
/** Rows an inline pane asks for: the tabs, the tallest inline map (20) and a legend wrapped once. */
const PANE_ROWS = 29;
/** get_why took 22 s cold on Django, get_answer about 4 s. */
const ASK_TIMEOUT_MS = 30_000;
/** The `lens_flow` toggle, fixed for one activation. */
let flowOn = true;
let flow = new LensFlow();
/** The person's `prefersReducedMotion`, read at session start, for a Flow made again after a `/clear`. */
let reducedMotion = false;
/** A new session's state: on the Flow tab, or the Map when Flow is off. */
function freshSession(): SessionState {
return flowOn ? initialSession : reduce(initialSession, { type: "tab", tab: "map" });
}
let state: SessionState = initialSession;
/** Bumped per session, so a refresh started in an earlier one never lands in this one. */
let generation = 0;
let running = false;
/** A refresh was asked for while one ran: run once more after it. */
let dirty = false;
let latest: Bound | null = null;
/**
* Once the server has connected the CLI is known to exist; a later connect
* can fail while the session shuts its servers down, which is not "no CLI".
*/
let mcpConnected = false;
/** The ledger at this session's first read, and whose; the band shows growth past it. */
let savingsBase: { repoId: string; totals: SavingsDelta } | null = null;
let savingsBusy = false;
let savingsAskedAt = Number.NEGATIVE_INFINITY;
/** Each Bash result's squeeze, kept once found: a row redraws on every scroll. */
const squeezes = new Map<string, Squeeze>();
/** Files whose context is being fetched, or that the index does not know. */
const contextAsked = new Set<string>();
/** The `lens_review` toggle, fixed for one activation. */
let reviewOn = true;
/** Bumped when a main turn starts, so a review still in flight for the last one is dropped. */
let reviewGeneration = 0;
/** Edits that landed since the main turn started. */
let editsThisTurn = 0;
/** A review started during this turn: how many of its edits it covers, and its outcome. */
interface StartedReview {
gen: number;
covers: number;
settled: boolean;
/** Never rejects: a failure is a `reviewFailed` action. */
outcome: Promise<SessionAction>;
}
let started: StartedReview | null = null;
/** The `lens_pane_autoopen` toggle, fixed for one activation. */
let autoOpenOn = false;
/** The `lens_map_health` default: health colours on the map's tiles when it opens. */
let healthOn = false;
/** The last discovery, for the map pane's notice and its repo. */
let discovery: Discovery | null = null;
/** The session's cwd, from its start event, so observing a tool call waits on nothing. */
let cwd: string | null = null;
let map = new LensMap(false);
/** The pane's one animator, driven by the tab shown (today the map). */
let animator = new Animator();
/** Cut so an error stays one line under the answer. */
const ERROR_CELLS = 160;
/** What a background refresh needs from a hook's `$`, as closures (the engine forbids keeping `$` itself). */
interface Bound extends MapIO {
host: Host;
}
// Built from the calling hook's own `$`. REST through `$.http` from a later
// continuation of these closures works; an MCP call works only when it starts
// while a Lens hook is live (one started later is refused), so MCP calls are
// started synchronously from inside a hook (see data/mcp.ts). A late
// `$.ui.blit` is not refused either (checked headless from a timer).
function bind($: ModApi): Bound {
const host: Host = {
session: { cwd: () => $.session.cwd() },
fs: {
read: (path) => $.fs.read(path),
exists: (path) => $.fs.exists(path),
},
process: {
run: (argv, cwd) => $.process.run(argv, { cwd, timeoutMs: PROCESS_TIMEOUT_MS }),
},
http: (url, init) => {
const request: { method?: string; headers?: Record<string, string>; body?: string } = {};
if (init.method !== undefined) request.method = init.method;
if (init.headers !== undefined) request.headers = init.headers;
if (init.body !== undefined) request.body = init.body;
return $.http.fetch(url, request);
},
mcp: {
connect: async () => (mcpConnected ||= (await $.mcp.connect(MCP_SERVER_KEY)).isConnected),
server: async () => {
const r = await $.mcp.connect(MCP_SERVER_KEY);
return r.isConnected && typeof r.server === "string" ? r.server : null;
},
call: (server, tool, args) => $.mcp.call(server, tool, args),
},
};
const bound: Bound = {
host,
blastLanded: (path, r) => flowBlast(bound, path, r),
redraw: () => $.ui.invalidate("ui.render"),
debug: (message) => $.ui.log(`lens: ${message}`, { to: "debug" }),
blit: (key, cells, columns, rows) => $.ui.blit({ requestId: PANE_ID, key, cells, columns, rows }),
// Focus only when asked (/lens, a press): an automatic open leaves the prompt the keyboard.
// Opened unasked on a read: the map is what it opens to. This happens at most once, and never
// after the person opened the pane (/lens, Why), the only ways to have picked a tab by then.
openPane: (focus) => (
focus ? null : (state = reduce(state, { type: "tab", tab: "map" })),
$.ui.open(
focus
? { id: PANE_ID, title: MAP_COPY.title, rows: PANE_ROWS, focus: true }
: { id: PANE_ID, title: MAP_COPY.title, rows: PANE_ROWS },
)
),
closePane: () => $.ui.close({ id: PANE_ID }),
};
// Each hook's closures for the animator's next frame: never a `$` kept from an earlier hook.
animator.use(bound);
return bound;
}
function mapRepo(d: Discovery): MapRepo | null {
if (d.mode !== "full" || d.repo === undefined || d.repoRoot === null) return null;
return { id: d.repo.id, root: d.repoRoot, updatedAt: d.repo.updatedAt, caseInsensitive: isWindowsPath(d.repoRoot) };
}
function dispatch(b: Bound, action: SessionAction): void {
const next = reduce(state, action);
if (next === state) return;
state = next;
b.redraw();
}
async function refreshOnce(b: Bound, gen: number): Promise<void> {
const h = b.host;
const found = await discover(h);
const indexed = found.mode === "full" || found.mode === "lite";
const freshness = indexed && found.repoRoot !== null ? await readFreshness(h, found.repoRoot) : null;
if (gen !== generation) return;
if (indexed) warmMcp(h);
discovery = found;
const action: SessionAction = { type: "discovered", mode: found.mode, freshness, repoRoot: found.repoRoot };
if (found.liteReason !== undefined) action.liteReason = found.liteReason;
dispatch(b, action);
if (found.repo !== undefined) refreshSavings(b, found.repo.id, gen);
map.setRepo(b, mapRepo(found));
}
/**
* Reads the savings ledger in the background, never awaited by a hook or a
* render. The first read of a session is the baseline; later reads, at most
* once a minute, become the band's delta.
* Ceiling: the baseline lands a moment after the session starts, so savings
* made before that first read are not counted.
*/
function refreshSavings(b: Bound, repoId: string, gen: number): void {
const now = Date.now();
if (savingsBusy || now - savingsAskedAt < SAVINGS_COOLDOWN_MS) return;
savingsBusy = true;
savingsAskedAt = now;
withTimeout(getSavings(repoId), SAVINGS_TIMEOUT_MS, "savings")
.then((s) => {
if (gen !== generation) return;
const totals = savingsTotals(s);
const delta = savingsBase?.repoId === repoId ? savingsSince(totals, savingsBase.totals) : null;
if (delta !== null) {
dispatch(b, { type: "savings", delta });
return;
}
// First read, another repo, or a ledger that shrank: start counting again from here.
if (savingsBase !== null) dispatch(b, { type: "savings", delta: { tokens: 0, inferredTokens: 0, usd: 0 } });
savingsBase = { repoId, totals };
})
.catch((err: unknown) => b.debug(`savings failed: ${String(err)}`))
.finally(() => (savingsBusy = false));
}
/** Re-reads mode and freshness in the background, one run at a time. */
function refresh(b: Bound): void {
latest = b;
if (running) {
dirty = true;
return;
}
running = true;
dirty = false;
refreshOnce(b, generation)
// Keep the last good state; the next turn tries again.
.catch((err: unknown) => b.debug(`refresh failed: ${String(err)}`))
.finally(() => {
running = false;
if (dirty && latest !== null) refresh(latest);
});
}
async function onSessionStart(
$: ModApi,
e: SessionStartEvent,
next: (e: SessionStartEvent) => Promise<unknown>,
): Promise<unknown> {
const b = bind($);
try {
generation++;
cwd = typeof e.cwd === "string" ? e.cwd : null;
map.dispose();
animator.end();
animator = new Animator();
map = new LensMap(autoOpenOn, animator, healthOn, mapTurn);
flow.dispose();
flow = new LensFlow();
state = freshSession();
reviewGeneration++;
editsThisTurn = 0;
started = null;
contextAsked.clear();
squeezes.clear();
savingsBase = null;
savingsAskedAt = Number.NEGATIVE_INFINITY;
resetMcp();
warmMcp(b.host);
refresh(b);
await $.command.register({ name: "lens", description: PANE_COPY.command, argumentHint: PANE_COPY.argumentHint, immediate: true });
readTheme($);
reducedMotion = (await $.settings.read())["prefersReducedMotion"] === true;
map.setReducedMotion(reducedMotion);
flow.setReducedMotion(reducedMotion);
} catch (err) {
// Lens stays quiet; the session is unaffected.
b.debug(`session.start failed: ${String(err)}`);
}
return next(e);
}
// Also the first refresh when the module loaded after the session started.
async function onTurnComplete(
$: ModApi,
e: TurnCompleteEvent,
next: (e: TurnCompleteEvent) => Promise<unknown>,
): Promise<unknown> {
const b = bind($);
noteTurnEnd(b, e);
const result = await next(e);
return reviewOn && shouldReview(e, editsThisTurn) ? withReview(b, e, result) : result;
}
function noteTurnEnd(b: Bound, e: TurnCompleteEvent): void {
try {
const action = fromTurnComplete(e);
if (action === null) return;
noteFlow(b, () => ({ type: "turnEnded", at: Date.now(), durationMs: e.durationMs ?? null, end: turnEnd(e.reason, e.isAborted) }));
map.turnEnded();
dispatch(b, action);
refresh(b);
} catch (err) {
b.debug(`turn.complete failed: ${String(err)}`);
}
}
/** The turn's result with the review card beneath the answer, or as it was. */
async function withReview(b: Bound, e: TurnCompleteEvent, result: unknown): Promise<unknown> {
try {
const card = await finishReview(b);
return card === null ? result : withCard(result, e.answer ?? "", card);
} catch (err) {
b.debug(`change review failed: ${String(err)}`);
return result;
}
}
// callTool starts `$.mcp.call` synchronously (or rejects at once when the
// server name is not resolved yet), so the call starts inside the caller's hook.
async function fetchReview(b: Bound): Promise<SessionAction> {
try {
const risk = await callTool<ChangeRisk>(b.host, "get_change_risk", {}, { timeoutMs: REVIEW_TIMEOUT_S * 1000 });
return { type: "reviewed", risk };
} catch (err) {
b.debug(`change review failed: ${String(err)}`);
const message = fit((err instanceof Error ? err.message : String(err)).split("\n")[0] ?? "", ERROR_CELLS);
return { type: "reviewFailed", reason: err instanceof Error && err.name === "TimeoutError" ? "timeout" : "error", message };
}
}
/**
* Starts a review of the working tree, not awaited. Only ever called while a
* Lens hook is live (an edit's tool.call, or turn.complete), which is when the
* engine runs the call.
*/
function startReview(b: Bound): StartedReview {
const review: StartedReview = { gen: reviewGeneration, covers: editsThisTurn, settled: false, outcome: fetchReview(b) };
void review.outcome.then(() => {
review.settled = true;
});
started = review;
return review;
}
/** After an edit lands: start a review, not awaited, unless one is already in flight. */
function reviewAfterEdit(b: Bound): void {
editsThisTurn++;
dispatch(b, { type: "fileEdited" });
if (started !== null && started.gen === reviewGeneration && !started.settled) return;
startReview(b);
}
/** The review started this turn, when it covers every edit so far. */
function coveringReview(): StartedReview | null {
const s = started;
return s !== null && s.gen === reviewGeneration && s.covers === editsThisTurn ? s : null;
}
/**
* A review started at an edit can fail where one started here would not (the
* server name was not resolved yet): that one is tried once more, awaited.
*/
async function outcomeOf(b: Bound, review: StartedReview, reused: boolean): Promise<SessionAction> {
const action = await review.outcome;
return reused && isRetryable(action) ? startReview(b).outcome : action;
}
/**
* At the end of the turn: the started review when it covers every edit of the
* turn (usually already landed), else one more. Null when a new turn started
* meanwhile.
*/
async function finishReview(b: Bound): Promise<string | null> {
const gen = reviewGeneration;
const reused = coveringReview();
const review = reused ?? startReview(b);
if (!review.settled) dispatch(b, { type: "reviewStarted" });
const action = await outcomeOf(b, review, reused !== null);
if (gen !== reviewGeneration) return null;
dispatch(b, action);
return reviewText(state.review.outcome);
}
async function onTurnStart($: ModApi, e: TurnStartEvent, next: (e: TurnStartEvent) => Promise<unknown>): Promise<unknown> {
noteFlow(bind($), () => ({ type: "turnStarted", turnId: e.turnId ?? null, prompt: e.text ?? "", at: Date.now() }));
try {
// With reviews off the review state is never touched; a new turn only retires the brief offer.
if (reviewOn) {
reviewGeneration++;
editsThisTurn = 0;
started = null;
}
dispatch(bind($), reviewOn ? { type: "turnStarted" } : { type: "briefDone" });
map.turnStarted();
} catch (err) {
bind($).debug(`turn.start failed: ${String(err)}`);
}
return next(e);
}
/** `Run tests`: a visible prompt naming the tests; nothing reaches Claude without this press. */
// A press runs after the render hook that drew the button returned, with
// that hook's `$`; the docs' own Button examples call `$` from onPress.
function pressRunTests($: ModApi): void {
try {
const prompt = runTestsText(state.review.outcome);
if (prompt === null) return;
$.prompt.submit({ text: prompt }).catch((err: unknown) => bind($).debug(`run tests failed: ${String(err)}`));
} catch (err) {
bind($).debug(`run tests failed: ${String(err)}`);
}
}
/** `Why`: the pane's Ask tab, its field holding the decision that governs the edit; nothing is asked until Enter. */
function pressWhy($: ModApi): void {
const b = bind($);
try {
const decision = state.review.decision;
if (decision === null) return;
dispatch(b, { type: "tab", tab: "ask", draft: whyDraft(decision) });
map.request(b).catch((err: unknown) => b.debug(`why failed: ${String(err)}`));
} catch (err) {
b.debug(`why failed: ${String(err)}`);
}
}
/** `Brief Claude`: the session brief as a visible prompt; the offer then retires. */
function pressBrief($: ModApi): void {
const b = bind($);
try {
const brief = briefText(state);
dispatch(b, { type: "briefDone" });
if (brief === null) return;
$.prompt.submit({ text: brief }).catch((err: unknown) => b.debug(`brief failed: ${String(err)}`));
} catch (err) {
b.debug(`brief failed: ${String(err)}`);
}
}
/**
* A `/clear` starts a new conversation in the same process, with no
* `session.start`: Flow, the map's lighting, the review, Ask and the savings
* baseline start over. What the index said (discovery, the health map, file
* cards, importers by path) and the MCP connection stay. Savings restart
* because the engine's own session clock (`usage().startedAt`) does too.
* Any other end (exit, resume, logout) leaves everything to the next activation.
*/
async function onSessionEnd($: ModApi, e: SessionEndEvent, next: (e: SessionEndEvent) => Promise<unknown>): Promise<unknown> {
if (e.reason !== "clear") return next(e);
const b = bind($);
try {
animator.end();
flow.dispose();
flow = new LensFlow();
flow.setReducedMotion(reducedMotion);
map.clearConversation(b);
state = clearedConversation(state);
reviewGeneration++;
editsThisTurn = 0;
started = null;
squeezes.clear();
savingsBase = null;
savingsAskedAt = Number.NEGATIVE_INFINITY;
b.redraw();
} catch (err) {
b.debug(`clear failed: ${String(err)}`);
}
return next(e);
}
// Only offers the brief: the compaction and its summary pass on untouched.
async function onPostCompact(
$: ModApi,
e: PostCompactEvent,
next: (e: PostCompactEvent) => Promise<unknown>,
): Promise<unknown> {
try {
dispatch(bind($), { type: "compacted" });
} catch (err) {
bind($).debug(`PostCompact failed: ${String(err)}`);
}
return next(e);
}
/**
* Asks the index, one question at a time. Only called from a live hook (the
* Ask field's `ui.input`, or `/lens ask`): `callTool` starts the call at
* once, which is when the engine runs Lens's own lookup.
*/
function startAsk(b: Bound, question: string): void {
const q = question.trim();
if (q === "") return;
// One question at a time; the tab says this one was not asked.
if (state.ask.phase === "asking") return dispatch(b, { type: "askBusy" });
const { tool, args } = askRoute(q);
dispatch(b, { type: "asked", question: q, tool });
const gen = generation;
callTool<unknown>(b.host, tool, args, { timeoutMs: ASK_TIMEOUT_MS })
.then((reply) => {
if (gen !== generation) return;
const answer = askReply(tool, reply);
dispatch(b, { type: "answered", question: q, answer });
})
.catch((err: unknown) => {
b.debug(`ask failed: ${String(err)}`);
const message = fit((err instanceof Error ? err.message : String(err)).split("\n")[0] ?? "", ERROR_CELLS);
if (gen !== generation) return;
dispatch(b, { type: "askFailed", question: q, tool, message });
});
}
// The Ask field's Enter. The lookup starts here, in Lens's own hook, so the
// engine runs it; the field's own closure does nothing.
async function onAskInput($: ModApi, e: UiInputEvent, next: (e: UiInputEvent) => Promise<unknown>): Promise<unknown> {
try {
if (e.kind === "submit" && e.element === ASK_KEY) startAsk(bind($), e.value);
} catch (err) {
bind($).debug(`ask failed: ${String(err)}`);
}
return next(e);
}
/** `Details`: the review's full directive in the transcript, one row per line, for the user only. */
function pressDetails($: ModApi): void {
try {
for (const row of directiveRows(state.review.outcome) ?? []) $.ui.log(row, { to: "transcript" });
} catch (err) {
bind($).debug(`details failed: ${String(err)}`);
}
}
// The band is shared: a mod's tree replaces what the mods after it draw
// (docs: plugins/mods/interface, "Band above the prompt"), so Lens puts its
// rows above the tree `next(e)` returns instead of dropping it.
async function onBand($: ModApi, e: RenderEvent, next: (e: RenderEvent) => Promise<unknown>): Promise<unknown> {
const theirs = await next(e);
try {
const line = map.bandLine();
const viewport = { columns: e.props.bodyColumns ?? 80, hasSurvey: e.props.hasSurvey === true };
const tree = bandView(state, viewport, line === null ? [] : [line]);
if (tree === null) return theirs;
const elements = $.ui.resolve(e);
const ours = materialize(tree, elements, {
[PRESS.tests]: () => pressRunTests($),
[PRESS.why]: () => pressWhy($),
[PRESS.details]: () => pressDetails($),
[BRIEF_PRESS]: () => pressBrief($),
});
const box = elements["Box"];
if (theirs === null || theirs === undefined || box === undefined) return ours;
return box({ flexDirection: "column", children: [ours, theirs] });
} catch (err) {
bind($).debug(`band render failed: ${String(err)}`);
return theirs;
}
}
/**
* Fetches a file's context once per session, started here and not awaited:
* the engine runs Lens's call because it starts while this hook is live,
* and the spinner shows it from the first render after it lands.
* Ceiling: cached for the session, so an index update mid-session is not seen.
*/
function fetchContext(b: Bound, file: string): void {
if (contextAsked.has(file)) return;
contextAsked.add(file);
const gen = generation;
fetchFileContext(b.host, file)
.then((context) => {
if (gen !== generation || context === null) return;
dispatch(b, { type: "contextLoaded", file, context });
})
.catch((err: unknown) => {
// Asked again on the next call: the server may not have connected yet.
contextAsked.delete(file);
b.debug(`context for ${file} failed: ${String(err)}`);
});
}
async function onToolCall($: ModApi, e: ToolCallEvent, next: (e: ToolCallEvent) => Promise<unknown>): Promise<unknown> {
const b = bind($);
const file = fileToolStarted(b, e);
noteFlow(b, () => {
const activity = activityOf(e, Date.now(), flowRoot());
return activity === null ? null : { type: "toolStarted", activity };
});
let result: unknown = null;
try {
result = await next(e);
} finally {
if (file !== null) dispatch(b, { type: "toolEnded", id: e.tool_use_id });
// `result` stays null when the call threw: Flow marks it failed.
noteFlow(b, () => toolEnded(e, result, Date.now(), flowRoot()));
}
editLanded(b, e, result);
observeTrail($, b, e, result);
return result;
}
/** What the Flow tab draws from beyond its own record: the file cards and this turn's review. */
function flowPane(columns: number, rows: number): FlowPane {
const outcome = state.review.outcome;
return { columns, rows, mode: state.mode, contexts: state.contexts, review: outcome.phase === "done" ? outcome.risk : null, light: theme === "light" };
}
/** The map's blast radius for an edited file, handed to Flow: never a second request. */
function flowBlast(b: Bound, path: string, r: BlastResponse): void {
noteFlow(b, () => ({ type: "blastLanded", path, facts: blastFacts(path, r) }));
}
/** What Flow shows paths relative to: the indexed repo, else the session's directory. */
function flowRoot(): string | null {
return state.repoRoot ?? cwd;
}
/** Records into Flow; a failure is logged and never reaches Claude's turn. */
function noteFlow(b: Bound, action: () => FlowAction | null): void {
if (!flowOn) return;
try {
const a = action();
if (a !== null) flow.dispatch(b, a);
} catch (err) {
flowFailed(b, err);
}
}
/** Logs a recording failure; if even the log fails, Flow stops recording for this activation. */
function flowFailed(b: Bound, err: unknown): void {
try {
b.debug(`flow failed: ${String(err)}`);
} catch {
// Not even the debug log works: stop recording rather than risk Claude's turn.
flowOn = false;
}
}
/** Where Claude looked, for the map: recorded from what next(e) returned, waiting on nothing. */
function observeTrail($: ModApi, b: Bound, e: ToolCallEvent, result: unknown): void {
if (!OBSERVED_TOOLS.has(e.tool)) return;
try {
const here = cwd;
// Loaded after the session started: learn the cwd for the next call, skip this one.
if (here === null) {
void $.session.cwd().then(
(c) => (cwd = c),
(err: unknown) => b.debug(`cwd failed: ${String(err)}`),
);
return;
}
const ctx = { cwd: here, isWindows: isWindowsPath(here) };
const action = fromToolCall(e, result, ctx);
const raw = e.file_path;
if (action !== null) map.observe(b, action, typeof raw === "string" ? absolutePath(raw, ctx) : null);
} catch (err) {
b.debug(`tool.call observe failed: ${String(err)}`);
}
}
/** A file tool starting in the repo: the spinner's file, and its context fetched. */
function fileToolStarted(b: Bound, e: ToolCallEvent): string | null {
try {
const file = fileTarget(e, state.repoRoot);
if (file === null) return null;
dispatch(b, { type: "toolStarted", tool: { id: e.tool_use_id, file } });
fetchContext(b, file);
return file;
} catch (err) {
b.debug(`tool.call failed: ${String(err)}`);
return null;
}
}
function editLanded(b: Bound, e: ToolCallEvent, result: unknown): void {
try {
if (!isFileEdit(e, result)) return;
const path = touchedPath(e, cwd, state.repoRoot);
if (path !== null) dispatch(b, { type: "touched", path });
if (reviewOn) reviewAfterEdit(b);
} catch (err) {
b.debug(`tool.call failed: ${String(err)}`);
}
}
// Rewrites only the suffix prop, so the engine keeps drawing (and animating) the line.
async function onSpinner($: ModApi, e: SpinnerEvent, next: (e: SpinnerEvent) => Promise<unknown>): Promise<unknown> {
let line: string | null = null;
try {
line = spinnerSuffix(state);
} catch (err) {
bind($).debug(`spinner render failed: ${String(err)}`);
}
if (line === null) return next(e);
const theirs = typeof e.props.suffix === "string" ? e.props.suffix : "";
return next({ ...e, props: { ...e.props, suffix: `${theirs} ${line}` } });
}
/** Lens's rows drawn under what the engine (and the mods after Lens) drew for the site. */
function below(elements: ElementTable, theirs: unknown, tree: Node): unknown {
const ours = materialize(tree, elements);
const box = elements["Box"];
if (theirs === null || theirs === undefined || box === undefined) return ours;
return box({ flexDirection: "column", children: [theirs, ours] });
}
// A miss is not kept: an early render can come before the output is whole.
function squeezeOf(e: ToolResultEvent): Squeeze | null {
const id = e.props.tool_use_id;
const known = squeezes.get(id);
if (known !== undefined || e.props.tool !== "Bash") return known ?? null;
const out = bashText(e.props.output);
const found = out === null ? null : parseSqueeze(out);
if (found !== null) squeezes.set(id, found);
return found;
}
async function onToolResult(
$: ModApi,
e: ToolResultEvent,
next: (e: ToolResultEvent) => Promise<unknown>,
): Promise<unknown> {
const theirs = await next(e);
try {
const s = squeezeOf(e);
return s === null ? theirs : below($.ui.resolve(e), theirs, squeezeView(s));
} catch (err) {
bind($).debug(`squeeze render failed: ${String(err)}`);
return theirs;
}
}
// Reads what the augment hook told Claude about this edit, and passes it on untouched.
async function onPostToolUse(
$: ModApi,
e: PostToolUseEvent,
next: (e: PostToolUseEvent) => Promise<unknown>,
): Promise<unknown> {
const result = await next(e);
try {
// Lens's own lookups also pass through here; they are not Claude's edits.
if (EDIT_TOOLS.has(e.tool_name) && !e.tool_use_id.startsWith("toolu_plugin_")) {
const notes = notesFromAugment((result as { additionalContext?: unknown } | null)?.additionalContext);
if (notes.length > 0) dispatch(bind($), { type: "notesFor", id: e.tool_use_id, notes });
}
} catch (err) {
bind($).debug(`PostToolUse failed: ${String(err)}`);
}
return result;
}
async function onToolUse($: ModApi, e: ToolUseEvent, next: (e: ToolUseEvent) => Promise<unknown>): Promise<unknown> {
const theirs = await next(e);
try {
const tree = marginView(state.notes[e.props.tool_use_id]);
return tree === null ? theirs : below($.ui.resolve(e), theirs, tree);
} catch (err) {
bind($).debug(`margin render failed: ${String(err)}`);
return theirs;
}
}
// `/lens`, `/lens flow`, `/lens map`, `/lens ask [question]`, `/lens recap`: the pane, with
// focus, on the tab asked for (else the last one shown).
async function onLensCommand($: ModApi, e: CommandRunEvent): Promise<unknown> {
const b = bind($);
try {
readTheme($);
const asked = lensCommand(e.args ?? "", tabBar(flowOn));
if (asked.tab !== null) dispatch(b, { type: "tab", tab: asked.tab });
if (discovery === null || mapRepo(discovery) === null) refresh(b);
await map.request(b);
// Right after the session starts the server may not have connected yet:
// this hook waits for it, so the lookup still starts while the hook is live.
if (asked.question !== null) {
await mcpReady(b.host);
startAsk(b, asked.question);
}
} catch (err) {
b.debug(`/lens failed: ${String(err)}`);
}
// Nothing in the transcript: the pane is the answer.
return {};
}
function tabPresses($: ModApi, bar: readonly BarTab[]): Record<string, () => void> {
return Object.fromEntries(bar.map((tab) => [tabPress(tab), () => selectTab($, tab)]));
}
/** Flow's rows open and close their detail; `j` and `k` step between calls. */
function flowRowPresses($: ModApi): Record<string, () => void> {
return Object.fromEntries(flowPresses(flow.state).map(([key, id]) => [key, () => pressFlow($, key, id)]));
}
function pressFlow($: ModApi, key: string, id: string | null): void {
noteFlow(bind($), () => (id !== null ? { type: "toggle", id } : { type: "step", by: key === FLOW_NEXT ? 1 : -1 }));
}
function selectTab($: ModApi, tab: PaneTab): void {
try {
dispatch(bind($), { type: "tab", tab });
} catch (err) {
bind($).debug(`tab failed: ${String(err)}`);
}
}
/** Claude Code's theme, for the map's and Flow's colors; dark until read. */
let theme: ThemeName = "dark";
/** Reads the theme in the background; a failure keeps the last one (dark by default). */
function readTheme($: ModApi): void {
$.config
.list()
.then((rows) => {
theme = themeOf(rows.find((r) => r.key === "theme")?.value);
})
.catch((err: unknown) => bind($).debug(`theme failed: ${String(err)}`));
}
/** A tab's body at this pane size; `rows` is the body's height under the tab row. */
type TabBody = (b: Bound, e: PaneRenderEvent, rows: number) => Node;
const TAB_BODIES: Record<PaneTab, TabBody> = {
flow: (b, e, rows) => flow.paneTree(b, flowPane(e.props.bodyColumns, rows), Date.now()),
ask: (_b, e) => askView(state, e.props.bodyColumns),
recap: (_b, e) => recapView(state, { count: map.trail.reads.length, capped: map.trail.readsCapped }, e.props.bodyColumns),
map: (b, e) => mapBody(b, e),
};
/** The current turn for the map: from Flow's record, or from the map's own trail when Flow is off. */
function mapTurn(): { lit: Lit; story: Story; knows: (path: string) => Knows } {
const knows = (path: string) => knowsOf(path, state.contexts, flowOn ? flow.state : null);
if (flowOn) return { lit: litFromFlow(flow.state), story: storyFromFlow(flow.state), knows };
const root = state.repoRoot;
const lit = root === null ? NO_LIT : litFromTrail(map.trail, root, isWindowsPath(root));
return { lit, story: storyFromTrail(map.trail), knows };
}
function mapBody(b: Bound, e: PaneRenderEvent): Node {
const { bodyColumns, placement, scroll } = e.props;
const d = discovery;
const notice = d === null ? MAP_COPY.looking : HINTS[hintFor(d.mode, d.liteReason) ?? "no-index"];
return map.paneTree(b, { surface: e.surface, notice, bodyColumns, placement, bodyRows: scroll.bodyRows - TAB_ROWS, theme });
}
/** One of the map's keys: the cursor, the zoom, or the health colours. */
function pressMap($: ModApi, key: string): void {
try {
map.press(bind($), key);
} catch (err) {
bind($).debug(`map key failed: ${String(err)}`);
}
}
function mapPresses($: ModApi): Record<string, () => void> {
return Object.fromEntries(MAP_PRESSES.map((key) => [key, () => pressMap($, key)]));
}
/** The shown tab's body; the map draws (and animates) only on its own tab, the owl ticks only on Flow's. */
function tabBody(b: Bound, e: PaneRenderEvent): Node {
const tab = state.pane.tab;
if (tab !== "map") map.offScreen();
if (tab !== "flow") flow.hide();
const rows = (e.props.placement === "dock" ? e.props.scroll.bodyRows : PANE_ROWS) - TAB_ROWS;
try {
return TAB_BODIES[tab](b, e, rows);
} catch (err) {
// A body that throws keeps the tab bar and says so, instead of blanking the pane.
b.debug(`${tab} tab render failed: ${String(err)}`);
return text(fit(PANE_COPY.bodyFailed, e.props.bodyColumns), { dimColor: true, wrap: "truncate-end" });
}
}
async function onPane($: ModApi, e: PaneRenderEvent, next: (e: PaneRenderEvent) => Promise<unknown>): Promise<unknown> {
if (e.requestId !== PANE_ID) return next(e);
const b = bind($);
try {
const bar = tabBar(flowOn);
const presses = { ...tabPresses($, bar), ...flowRowPresses($), ...mapPresses($) };
return materialize(paneView(state.pane.tab, tabBody(b, e), bar), $.ui.resolve(e), presses);
} catch (err) {
b.debug(`pane render failed: ${String(err)}`);
return next(e);
}
}
// `options` are the plugin's userConfig toggles; a change reloads the module.
export function register(on: On, options: PluginOptions = {}): void {
reviewOn = options["lens_review"] !== false;
autoOpenOn = options["lens_pane_autoopen"] === true;
healthOn = options["lens_map_health"] === true;
flowOn = options["lens_flow"] !== false;
state = freshSession();
on("session.start", onSessionStart);
on("session.end", onSessionEnd);
on("turn.start", onTurnStart);
on("turn.complete", onTurnComplete);
on("ui.render", { component: "AbovePrompt" }, onBand);
on("ui.render", { component: "Pane" }, onPane);
on("command.run", { command: "lens" }, onLensCommand);
// Literals, so the static check reads the matcher: this plugin's Ask field (ASK_KEY).
on("ui.input", { plugin: "repowise", element: "lens-ask" }, onAskInput);
// The brief is only offered: nothing here hooks `session.compact`.
on("classic.PostCompact", onPostCompact);
on("tool.call", onToolCall);
on("ui.render", { component: "Spinner" }, onSpinner);
if (options["lens_squeeze"] !== false) {
on("ui.render", { component: "ToolResult" }, onToolResult);
}
if (options["lens_margin"] !== false) {
on("classic.PostToolUse", onPostToolUse);
on("ui.render", { component: "ToolUse" }, onToolUse);
}
}