pi-lazy-panel 0.1.0

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * pi-lazy-panel — entry point.
+ *
+ * Registers the `/lazy-panel` command. When invoked, it opens the full-screen
+ * lazygit-style panel (see ./ui/app.ts). Everything else lives in sub-modules:
+ *
+ *   config/   keymap + user configuration
+ *   data/     read-only adapters over pi's SessionManager (sessions, tree, content)
+ *   actions/  side-effecting operations (resume, restore, label, copy, delete, fork, ...)
+ *   ui/       TUI components (panes, dialogs, footer, search bar)
+ */
+
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	cloneSession,
+	compactSession,
+	copyLastReply,
+	copyText,
+	deleteSession,
+	exportSession,
+	exportTarget,
+	forkSession,
+	importSession,
+	newSession,
+	renameSession,
+	resumeSession,
+	shareSession,
+} from "./actions/session-actions.ts";
+import { copyNodeText, labelNode, restoreNode } from "./actions/tree-actions.ts";
+import { loadConfig } from "./config/config.ts";
+import { loadPiSettings } from "./config/pi-settings.ts";
+import { COMMAND_NAME } from "./constants.ts";
+import { loadChangelog } from "./data/changelog.ts";
+import { loadContent, loadForkPoints, loadSessionInfo } from "./data/content.ts";
+import { initI18n, t } from "./i18n/index.ts";
+import { listSessions, sortSessions } from "./data/sessions.ts";
+import { applyTreeFilter, loadTree } from "./data/tree.ts";
+import { type ActionSource, type DataSource, LazyPanel } from "./ui/app.ts";
+import { attachMouse } from "./ui/mouse-input.ts";
+
+/** 读本插件 package.json 的版本号，展示在 footer 右下角；读不到就返回空串（不显示）。 */
+function extensionVersion(): string {
+	try {
+		const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: unknown };
+		return typeof pkg.version === "string" ? pkg.version : "";
+	} catch {
+		return "";
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	// 按系统语言初始化 i18n（命令描述在注册时就要用到，一次会话内固定）。
+	initI18n();
+	pi.registerCommand(COMMAND_NAME, {
+		description: t("command.description"),
+		handler: async (_args, ctx) => {
+			// 按系统语言初始化 i18n（一次会话内固定），之后所有 UI 文案走 t()。
+			initI18n();
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify(t("notify.tuiOnly", { command: COMMAND_NAME }), "warning");
+				return;
+			}
+			const config = await loadConfig(getAgentDir());
+			// 用户配置里的 locale（en / zh）覆盖系统语言；没配就沿用上面按系统语言检测的结果。t() 在渲染时才调用，这里切换后面板 UI 即用新语言。
+			if (config.locale) initI18n(config.locale);
+			// pi 自己的 branchSummary.skipPrompt 打开时，TREE Enter 和内置 /tree 一样不弹摘要菜单；
+			// treeFilterMode 是内置 /tree 的默认过滤，面板的 TREE 也从它开始。
+			const piSettings = loadPiSettings(ctx.cwd, getAgentDir(), ctx.isProjectTrusted());
+			const data: DataSource = {
+				listSessions: async (scope, sort) => sortSessions(await listSessions({ cwd: ctx.cwd, scope }), sort),
+				loadTree: async (file, filter) => applyTreeFilter(await loadTree(file), filter),
+				loadContent: (file, leafEntryId) =>
+					loadContent(leafEntryId ? { sessionFile: file, leafEntryId } : { sessionFile: file }),
+				loadSessionInfo,
+				loadForkPoints,
+				loadChangelog: () => loadChangelog(),
+			};
+			// 副作用统一走 actions 层；目标是当前会话时用 pi 内存里的 API（setLabel / setSessionName / navigateTree），
+			// 其他历史会话则直接读写文件或先 switchSession。
+			const actions: ActionSource = {
+				copyNodeText,
+				setNodeLabel: (file, entryId, label) => labelNode(pi, ctx, file, entryId, label),
+				resumeSession: (file) => resumeSession(ctx, file),
+				restoreNode: (file, entryId, options) => restoreNode(ctx, file, entryId, options),
+				deleteSession: (file) => deleteSession(ctx, file),
+				renameSession: (file, name) => renameSession(pi, ctx, file, name),
+				newSession: (name) => newSession(ctx, name),
+				forkSession: (file, entryId) => forkSession(ctx, file, entryId),
+				cloneSession: (file) => cloneSession(ctx, file),
+				compactSession: (file, customInstructions) => compactSession(ctx, file, customInstructions),
+				copyLastReply,
+				copyText,
+				// 导出 / 分享的 HTML 走 pi 自己的 `pi --export`；相对路径和默认文件名都按 pi 的工作目录算。
+				exportTarget: (file, format, input) => exportTarget(ctx.cwd, file, format, input),
+				exportSession: (file, format, outputPath) => exportSession(ctx, file, format, outputPath),
+				importSession: (input) => importSession(ctx, input),
+				shareSession: (file) => shareSession(file),
+			};
+			// overlay 句柄在面板显示后才拿到；Enter 等待 pi 切换时用它暂时隐藏面板。
+			let setHidden: ((hidden: boolean) => void) | undefined;
+			// regular 模式下 pi 不开鼠标追踪，面板自己开；关闭时再关掉（fullscreen 由 pi 管，不碰）。
+			let disableMouse: (() => void) | undefined;
+			const currentFile = ctx.sessionManager.getSessionFile();
+			const version = extensionVersion();
+
+			await ctx.ui.custom<void>(
+				(tui, theme, _keybindings, done) => {
+					// overlay 模式默认不清理"腾空"的行（pi 的 terminal.clearOnShrink 默认 false）：关掉 ? 帮助框后
+					// 会留残影（切面板时闪一下），在有内容的当前会话里滚动时整块面板还会整体往下漂。全屏面板下打开
+					// 这个开关，让缩小后的区域被清掉。老版本 pi 可能没有这个方法，先做一次存在性判断。
+					if (typeof tui.setClearOnShrink === "function") tui.setClearOnShrink(true);
+					const panel = new LazyPanel({
+						theme,
+						data,
+						actions,
+						getHeight: () => tui.terminal.rows,
+						requestRender: () => tui.requestRender(),
+						onClose: () => done(),
+						setHidden: (hidden) => setHidden?.(hidden),
+						keymap: config.keymap,
+						initialState: { scope: config.defaultScope, sort: config.defaultSort, treeFilter: piSettings.treeFilter },
+						leftColumnRatio: config.leftColumnRatio,
+						skipSummaryPrompt: piSettings.skipBranchSummaryPrompt,
+						// 打开时 SESSIONS 光标落到 pi 当前打开的会话上；新会话没有文件 / 还没列出时留在第一行。
+						...(currentFile ? { currentSessionFile: currentFile } : {}),
+						// 配置文件有问题时在底部提示，但不阻止面板打开。
+						...(config.warnings.length ? { status: config.warnings[0] } : {}),
+						// footer 右下角的版本号（读不到 package.json 时为空、不显示）。
+						...(version ? { version } : {}),
+					});
+					// fullscreen 模式 pi 已经开了鼠标并派给 overlay 的 handleMouse；regular 模式
+					// 由 attachMouse 自己开 SGR 上报并解析（fullscreen 下是 no-op）。
+					disableMouse = attachMouse(tui, panel);
+					void panel.load();
+					return panel;
+				},
+				{
+					// Full-screen overlay: covers pi's own header/editor/footer instead of
+					// being embedded in the editor slot (which would overflow the terminal).
+					overlay: true,
+					overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+					onHandle: (handle) => {
+						setHidden = (hidden) => handle.setHidden(hidden);
+					},
+				},
+			);
+			// 面板关闭后恢复终端自己的滚动 / 选择。
+			disableMouse?.();
+		},
+	});
+}

package/src/types.ts

@@ -0,0 +1,346 @@
+/**
+ * Shared type definitions for pi-lazy-panel.
+ *
+ * Keep this file free of runtime code — types only.
+ */
+
+import type { KEY_SCOPES, PANE_IDS, SESSION_SORT_MODES } from "./constants.ts";
+import type { Locale } from "./i18n/index.ts";
+
+// ---------------------------------------------------------------------------
+// Panes / focus
+// ---------------------------------------------------------------------------
+
+/** One of the three focusable panes. */
+export type PaneId = (typeof PANE_IDS)[number];
+
+/** Which set of sessions the sessions pane lists. */
+export type ListScope = "current-folder" | "all";
+
+/** Sort order of the sessions pane (mirrors pi's /resume picker; `s` cycles them in `SESSION_SORT_MODES` order). */
+export type SessionSortMode = (typeof SESSION_SORT_MODES)[number];
+
+/**
+ * Input mode of the panel, shown in the footer (vim-like). `restore` = the
+ * summary menu / custom prompt of TREE Enter is open, `tree` = the full tree
+ * dialog (`a` in the tree pane) is open, `confirm` / `rename` / `info` = the
+ * delete confirmation, the Rename prompt or the Session Info dialog is open;
+ * `export` / `import` / `share` = the dialogs of SESSIONS `e` / `I` / `S`;
+ * `changelog` = the `@` changelog dialog.
+ */
+export type PanelMode =
+	| "normal"
+	| "search"
+	| "label"
+	| "restore"
+	| "tree"
+	| "confirm"
+	| "rename"
+	| "info"
+	| "new"
+	| "fork"
+	| "clone"
+	| "compact"
+	| "export"
+	| "import"
+	| "share"
+	| "changelog"
+	| "visual"
+	| "preview";
+
+/** A `key description` pair shown as a hint in the footer or a prompt bar. */
+export type KeyHint = [key: string, text: string];
+
+/**
+ * What Enter did (SESSIONS resume / TREE restore):
+ * `switched` = pi now shows another session, `restored` = the leaf moved to the
+ * chosen node, `unchanged` = pi was already there, `compacted` = the current
+ * session's active branch was compacted in place. Failures throw instead.
+ */
+export type EnterOutcome = "switched" | "restored" | "unchanged" | "compacted";
+
+/**
+ * How a session file was removed (SESSIONS `d`, same as pi's /resume):
+ * `trash` = moved to the system trash by the `trash` CLI, `unlink` = deleted
+ * for good because `trash` was unavailable or failed.
+ */
+export type DeleteMethod = "trash" | "unlink";
+
+/** File format of SESSIONS `e` (pi's /export): the whole tree as HTML, or the active branch as JSONL. */
+export type ExportFormat = "html" | "jsonl";
+
+/** Where an export would be written, resolved from what the user typed (blank = pi's default name in the cwd). */
+export interface ExportTarget {
+	/** Absolute output path. */
+	path: string;
+	/** A file is already there (the panel asks before overwriting it). */
+	exists: boolean;
+}
+
+/** What SESSIONS `S` (pi's /share) produced: the pi.dev viewer link and the gist behind it. */
+export interface ShareResult {
+	url: string;
+	gistUrl: string;
+}
+
+/**
+ * How TREE Enter leaves the branch it abandons — the three choices of pi's
+ * `/tree`: no summary, a model-written summary of the abandoned branch, or a
+ * summary written with extra instructions. Passed through to `ctx.navigateTree`.
+ */
+export interface RestoreOptions {
+	summarize: boolean;
+	/** Extra instructions for the summarizer ("Summarize with custom prompt"). */
+	customInstructions?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Data rows
+// ---------------------------------------------------------------------------
+
+/** A row in the sessions (left-top) pane. */
+export interface SessionRow {
+	/** Absolute path to the session .jsonl file. */
+	file: string;
+	/** Session UUID. */
+	id: string;
+	/** User-defined display name, if any (/name). */
+	name?: string;
+	/** Working directory the session was created in. */
+	cwd: string;
+	/** Session file this one was forked from, if any (drives "threaded" sort). */
+	parentFile?: string;
+	/** Indentation level assigned by "threaded" sort (0 = root). */
+	threadDepth?: number;
+	/** Model id last used in the session, if known. */
+	model?: string;
+	/** Short preview of the first user message. */
+	preview: string;
+	createdAt: number;
+	updatedAt: number;
+	messageCount: number;
+}
+
+/** A row in the tree (left-bottom) pane. */
+export interface TreeRow {
+	/** Entry id inside the session. */
+	entryId: string;
+	/**
+	 * Nearest ancestor that is also a row, undefined for roots. Entries that
+	 * never become rows (labels, hidden by the filter…) are skipped over, so the
+	 * rows always form a consistent forest the UI can draw guide lines for.
+	 */
+	parentId?: string;
+	role: "user" | "assistant" | "system" | "tool";
+	/**
+	 * Coarse category used by the tree filters (same split as pi's /tree):
+	 * `message` user / assistant, `tool` tool results, `system` structural
+	 * entries always shown (system prompt, bash, compaction, branch summary),
+	 * `meta` bookkeeping hidden by default (model / thinking / name changes).
+	 */
+	kind: "message" | "tool" | "system" | "meta";
+	/** User-defined label on this entry (/tree shift+t). */
+	label?: string;
+	/** Truncated single-line text. */
+	text: string;
+	timestamp: number;
+	/** Whether this entry is on the currently active branch. */
+	onActiveBranch: boolean;
+	/**
+	 * Restoring here would leave the conversation where it already is (the leaf,
+	 * or a message followed only by bookkeeping entries — see `isEffectiveLeaf`),
+	 * so Enter skips the summary menu.
+	 */
+	isLeaf?: boolean;
+}
+
+/**
+ * Tree filters (mirror /tree ctrl+d/t/u/l/a: `no-tools` is pi's ctrl+t,
+ * `labeled` pi's `labeled-only`). Set from the tree dialog (d/t/u/l/a); the
+ * pane shows the same filtered tree.
+ */
+export type TreeFilter = "default" | "no-tools" | "user-only" | "labeled" | "all";
+
+/** A message block rendered in the content (right) pane. */
+export interface ContentBlock {
+	entryId: string;
+	role: "user" | "assistant";
+	timestamp: number;
+	/** Raw markdown to render. */
+	markdown: string;
+}
+
+/** A user message the `/fork` selector can fork before (entry id + one-line preview). */
+export interface ForkPoint {
+	entryId: string;
+	text: string;
+}
+
+/** Data shown in the Session Info dialog (mirrors /session). */
+export interface SessionInfo {
+	name?: string;
+	model?: string;
+	messages: number;
+	tokens: number;
+	cost: number;
+	createdAt: number;
+	updatedAt: number;
+	path: string;
+	id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+
+/**
+ * Parsed search query. Supports GitHub-style qualifiers:
+ *   name:foo model:opus path:bar tag:scan role:user after:2026-09-01 before:2026-09-20
+ * plus free text.
+ */
+export interface SearchQuery {
+	text: string;
+	name?: string;
+	model?: string;
+	path?: string;
+	tag?: string;
+	/** Tree rows: the role (`user`, `assistant`, `system`, `tool`) must contain it. */
+	role?: string;
+	after?: Date;
+	before?: Date;
+}
+
+/**
+ * The `/` search active in one pane (lazygit-style: the rows are not filtered,
+ * the cursor jumps between the matches with n / N). Kept per pane, so switching
+ * panes does not lose a query.
+ *
+ * 每个面板各自的搜索状态：列表不过滤，只在匹配之间跳转。
+ */
+export interface PaneSearch {
+	/** Raw query as typed after `/`. */
+	query: string;
+	/**
+	 * Matches, ascending: row indices for the list panes (the sessions list; the
+	 * whole tree, folded rows included) and body-line indices of the rendered
+	 * layout for the content pane.
+	 */
+	matches: number[];
+	/** Position in `matches` of the current match (the content pane's scroll target), -1 when there is none. */
+	current: number;
+}
+
+/**
+ * What a pane paints for the search active in it: which of the rows / lines it
+ * renders match, which one is the current match, the terms to highlight and
+ * the counts for its header ("2/7 matches").
+ */
+export interface SearchView {
+	/** Terms to highlight on matching rows (free-text tokens and qualifier values). */
+	terms: string[];
+	/** Indices, in what the pane renders, of the matching rows (list panes) or body lines (content pane). */
+	matches: ReadonlySet<number>;
+	/** Index of the current match, undefined when the cursor is not on one. */
+	current: number | undefined;
+	/** 1-based position of the current match among the matches, 0 when there is none. */
+	position: number;
+	total: number;
+}
+
+// ---------------------------------------------------------------------------
+// Keymap
+// ---------------------------------------------------------------------------
+
+/** Logical actions the panel can perform. Keys are bound to these. */
+export type ActionId =
+	// global
+	| "focus-next"
+	| "focus-prev"
+	| "focus-sessions"
+	| "focus-tree"
+	| "focus-content"
+	| "scope-current"
+	| "scope-all"
+	| "help"
+	| "quit"
+	| "search"
+	| "search-next"
+	| "search-prev"
+	| "changelog"
+	// list navigation
+	| "move-down"
+	| "move-up"
+	| "go-top"
+	| "go-bottom"
+	| "scroll-content-down"
+	| "scroll-content-up"
+	// sessions pane
+	| "session-resume"
+	| "session-delete"
+	| "session-rename"
+	| "session-fork"
+	| "session-toggle-select"
+	| "session-export"
+	| "session-import"
+	| "session-share"
+	| "session-clone"
+	| "session-copy-last-reply"
+	| "session-compact"
+	| "session-sort"
+	| "session-new"
+	| "session-info"
+	// tree pane
+	| "tree-restore"
+	| "tree-copy"
+	| "tree-label"
+	| "tree-open"
+	| "tree-fold"
+	// tree dialog only (the dialog also uses the tree pane's actions and the global `search`)
+	| "tree-filter-default"
+	| "tree-filter-no-tools"
+	| "tree-filter-user"
+	| "tree-filter-labeled"
+	| "tree-filter-all"
+	| "tree-dialog-close";
+// content pane is read-only and only uses the shared navigation actions
+// (move-down / move-up / go-top / go-bottom) plus the global search, see docs/design.md.
+// Tree filters (d/t/u/l/a) live in the tree dialog (`tree-open`), which also has
+// its own live-filtering search row; `/` in the panes jumps between matches.
+
+/**
+ * A single key chord in pi-tui key syntax, e.g. "j", "ctrl+d", "tab".
+ * Multi-key sequences are written either verbatim when every step is one
+ * printable character ("gg", "yy") or space-separated ("ctrl+w h").
+ * An uppercase letter ("G") means shift + that letter.
+ */
+export type KeyChord = string;
+
+/**
+ * Binding scope: the global scope, one pane, or the tree dialog. Keys are
+ * resolved innermost first: `tree-dialog` → `tree` → `global` inside the
+ * dialog, `<pane>` → `global` in a pane (see `scopeChain` in config/keys.ts).
+ */
+export type KeyScope = (typeof KEY_SCOPES)[number];
+
+/** Keymap for one scope (a pane, the tree dialog or the global scope). */
+export type PaneKeymap = Partial<Record<ActionId, KeyChord | KeyChord[]>>;
+
+/** Full keymap: global bindings plus per-scope overrides. */
+export type Keymap = Record<KeyScope, PaneKeymap>;
+
+// ---------------------------------------------------------------------------
+// User config
+// ---------------------------------------------------------------------------
+
+/** Per-scope keymap in the user file. `null` unbinds an action. */
+export type UserPaneKeymap = Partial<Record<ActionId, KeyChord | KeyChord[] | null>>;
+
+/** Shape of `~/.pi/agent/lazy-panel.json`. All fields optional. */
+export interface UserConfig {
+	keymap?: Partial<Record<KeyScope, UserPaneKeymap>>;
+	/** UI 语言（"en" / "zh"）；缺省时按系统语言自动检测。 */
+	locale?: Locale;
+	defaultScope?: ListScope;
+	defaultSort?: SessionSortMode;
+	leftColumnRatio?: number;
+}