pi-lazy-panel 0.1.0

package/src/actions/tree-actions.ts

@@ -0,0 +1,161 @@
+/**
+ * Tree actions — side effects triggered from the tree pane.
+ *
+ *   restore -> ctx.navigateTree(entryId, { summarize, customInstructions })   (/tree Enter)
+ *              other session: ctx.switchSession first, then navigate inside withSession
+ *   copy    -> copyToClipboard(full entry text)                               (/tree ctrl+x)
+ *   label   -> pi.setLabel / SessionManager.appendLabelChange                 (/tree shift+T)
+ *
+ * No dialogs here: the caller collects the summary choice / label first.
+ */
+
+import {
+	copyToClipboard,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { EXTENSION_ID } from "../constants.ts";
+import { isEffectiveLeaf, loadNodeText } from "../data/tree.ts";
+import { t } from "../i18n/index.ts";
+import type { EnterOutcome, RestoreOptions } from "../types.ts";
+import { isCurrentSession, openSessionFile, resumeSession } from "./session-actions.ts";
+
+/** The slice of the command context `restoreNode` needs; the `withSession` context has the same shape. */
+export type RestoreContext = Pick<
+	ExtensionCommandContext,
+	"sessionManager" | "switchSession" | "navigateTree" | "isIdle" | "abort" | "waitForIdle" | "ui"
+>;
+
+type NavigateContext = Pick<RestoreContext, "navigateTree" | "isIdle" | "abort" | "waitForIdle" | "ui">;
+
+/** How long to wait for pi to settle after aborting the current response before giving up. */
+const IDLE_TIMEOUT_MS = 15_000;
+
+/** Enter without a choice (the node is the leaf, or pi's `branchSummary.skipPrompt`): no summary. */
+const NO_SUMMARY: RestoreOptions = { summarize: false };
+
+/**
+ * Continue the conversation from `entryId` of `sessionFile` (what `/tree` does on Enter).
+ *
+ * 分流和打标签一致：目标是当前会话就直接走 pi 内存里的 `navigateTree`；是其他历史会话就先
+ * `switchSession`，再在 pi 给 `withSession` 的新 ctx 里 navigate（切换后旧 ctx 已失效，不能复用）。
+ * 光标节点就是活动叶子时不重复 restore，等价于直接进入该会话。
+ * `options` 就是 /tree 的三个选择：不做摘要 / 让模型总结被放弃的分支 / 带自定义指令总结。
+ *
+ * Throws when the file / entry does not exist, pi is busy for too long, the
+ * summary needs a model pi does not have, or the switch / navigation was
+ * cancelled. A failed navigation *after* a successful switch cannot be thrown
+ * back to the panel (pi has already torn it down), so it is reported through
+ * the new session's `ui.notify` and the outcome is `switched`.
+ */
+export async function restoreNode(
+	ctx: RestoreContext,
+	sessionFile: string,
+	entryId: string,
+	options: RestoreOptions = NO_SUMMARY,
+): Promise<EnterOutcome> {
+	const current = isCurrentSession(ctx, sessionFile);
+	const manager = current ? ctx.sessionManager : openSessionFile(sessionFile);
+	if (!manager.getEntry(entryId)) throw new Error(`entry ${entryId} not found in session`);
+	if (isEffectiveLeaf(manager, entryId)) return resumeSession(ctx, sessionFile);
+	if (current) {
+		await navigateTo(ctx, entryId, options);
+		return "restored";
+	}
+	let outcome: EnterOutcome = "restored";
+	await resumeSession(ctx, sessionFile, {
+		withSession: async (next) => {
+			try {
+				await navigateTo(next, entryId, options);
+			} catch (err) {
+				outcome = "switched";
+				next.ui.notify(`restore failed: ${(err as Error).message}`, "error");
+			}
+		},
+	});
+	return outcome;
+}
+
+/**
+ * `navigateTree` refuses to run while pi is still streaming, so do what the
+ * built-in /tree does once the user has committed: abort the response, wait for
+ * pi to go idle, then move the leaf.
+ *
+ * 摘要要等模型写完，这期间面板是隐藏的，所以进度写到 pi 自己的 footer 上（`ui.setStatus`），
+ * 结束后清掉。扩展 ctx 的 `navigateTree` 把摘要被中止（aborted）也折叠成 `cancelled: true`，
+ * 这里分不出是被中止还是被别的扩展否决，只能统一报 cancelled。
+ */
+async function navigateTo(ctx: NavigateContext, entryId: string, options: RestoreOptions): Promise<void> {
+	if (!ctx.isIdle()) {
+		ctx.abort();
+		await withTimeout(ctx.waitForIdle(), IDLE_TIMEOUT_MS, "pi is still busy; try again once the current response has stopped");
+	}
+	if (options.summarize) ctx.ui.setStatus(EXTENSION_ID, t("status.summarizing"));
+	try {
+		const result = await ctx.navigateTree(entryId, navigateOptions(options));
+		if (result.cancelled) {
+			throw new Error(options.summarize ? "branch summary cancelled" : "restore cancelled by an extension");
+		}
+	} finally {
+		if (options.summarize) ctx.ui.setStatus(EXTENSION_ID, undefined);
+	}
+}
+
+/** The `navigateTree` options for a choice; `customInstructions` is only set when there is one. */
+function navigateOptions(options: RestoreOptions): { summarize: boolean; customInstructions?: string } {
+	return options.customInstructions
+		? { summarize: options.summarize, customInstructions: options.customInstructions }
+		: { summarize: options.summarize };
+}
+
+/** Reject with `message` if `promise` has not settled within `ms`. */
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(message)), ms);
+		promise.then(
+			(value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			(err) => {
+				clearTimeout(timer);
+				reject(err);
+			},
+		);
+	});
+}
+
+/**
+ * Copy the full text of a tree node to the system clipboard.
+ * Resolves to `false` when the entry has no text to copy (like /tree's
+ * "Selected entry has no text to copy").
+ */
+export async function copyNodeText(sessionFile: string, entryId: string): Promise<boolean> {
+	const text = loadNodeText(sessionFile, entryId);
+	if (!text) return false;
+	await copyToClipboard(text);
+	return true;
+}
+
+/**
+ * Set (or clear with `undefined` / "") a label on a tree node.
+ *
+ * 面板操作的可能是任意历史会话文件：如果就是 pi 当前打开的会话，走 `pi.setLabel`
+ * 让 pi 内存里的 SessionManager 同步；否则单独打开该文件追加 label 条目
+ * （SessionManager.open 会持久化到 .jsonl）。
+ */
+export async function labelNode(
+	pi: Pick<ExtensionAPI, "setLabel">,
+	ctx: Pick<ExtensionCommandContext, "sessionManager">,
+	sessionFile: string,
+	entryId: string,
+	label: string | undefined,
+): Promise<void> {
+	const value = label?.trim() || undefined;
+	if (isCurrentSession(ctx, sessionFile)) {
+		pi.setLabel(entryId, value);
+		return;
+	}
+	SessionManager.open(sessionFile).appendLabelChange(entryId, value);
+}

package/src/config/config.ts

@@ -0,0 +1,155 @@
+/**
+ * User configuration loading.
+ *
+ * Reads `~/.pi/agent/lazy-panel.json` (if present) and merges it over the
+ * built-in defaults. Only this module should know where the file lives.
+ *
+ * 用户配置示例（所有字段可选）：
+ * {
+ *   "locale": "zh",
+ *   "defaultScope": "all",
+ *   "keymap": {
+ *     "global":   { "help": "F1", "scope-all": ["A", "ctrl+space"] },
+ *     "sessions": { "session-delete": "ctrl+d", "session-share": null }
+ *   }
+ * }
+ * 同一个 action 的用户键位会整体替换默认键位；值为 null 表示解绑。
+ * locale 缺省时按系统语言自动检测（见 i18n/index.ts）。
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_FILE_NAME, KEY_SCOPES, SESSION_SORT_MODES } from "../constants.ts";
+import { type Locale, SUPPORTED_LOCALES } from "../i18n/index.ts";
+import type { ActionId, KeyChord, Keymap, KeyScope, PaneKeymap, SessionSortMode, UserConfig, UserPaneKeymap } from "../types.ts";
+import { DEFAULT_KEYMAP } from "./keymap.ts";
+
+/** Fully resolved configuration used at runtime. */
+export interface ResolvedConfig {
+	keymap: Keymap;
+	/** UI 语言；缺省（未在用户配置里指定）时按系统语言自动检测。 */
+	locale?: Locale;
+	defaultScope: NonNullable<UserConfig["defaultScope"]>;
+	defaultSort: NonNullable<UserConfig["defaultSort"]>;
+	leftColumnRatio: number;
+	/** Non-fatal problems found while reading the user file (shown in the footer). */
+	warnings: string[];
+}
+
+export const DEFAULT_CONFIG: ResolvedConfig = {
+	keymap: DEFAULT_KEYMAP,
+	defaultScope: "current-folder",
+	defaultSort: "recent",
+	leftColumnRatio: 0.25,
+	warnings: [],
+};
+
+/**
+ * Load user config from disk and merge over defaults.
+ * A missing file yields the defaults; a broken file yields the defaults plus a warning.
+ * @param agentDir pi agent directory (usually ~/.pi/agent)
+ */
+export async function loadConfig(agentDir: string): Promise<ResolvedConfig> {
+	const file = join(agentDir, CONFIG_FILE_NAME);
+	let raw: string;
+	try {
+		raw = await readFile(file, "utf8");
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return DEFAULT_CONFIG;
+		return { ...DEFAULT_CONFIG, warnings: [`config: cannot read ${file}: ${(err as Error).message}`] };
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		return { ...DEFAULT_CONFIG, warnings: [`config: invalid JSON in ${file}: ${(err as Error).message}`] };
+	}
+	return resolveConfig(parsed);
+}
+
+/** Pure merge step, separated from I/O so it can be unit-tested. */
+export function resolveConfig(user: unknown): ResolvedConfig {
+	const warnings: string[] = [];
+	if (!isRecord(user)) {
+		return { ...DEFAULT_CONFIG, warnings: ["config: top level must be an object"] };
+	}
+	const u = user as UserConfig;
+
+	// locale 只接受我们发布的语言（en / zh），非法值退回系统语言检测（不写入 locale）。
+	let locale: Locale | undefined;
+	if (u.locale !== undefined) {
+		if ((SUPPORTED_LOCALES as readonly string[]).includes(u.locale as string)) {
+			locale = u.locale;
+		} else {
+			warnings.push(`config: unknown locale "${String(u.locale)}"`);
+		}
+	}
+
+	const defaultScope =
+		u.defaultScope === "all" || u.defaultScope === "current-folder" ? u.defaultScope : DEFAULT_CONFIG.defaultScope;
+	if (u.defaultScope !== undefined && defaultScope !== u.defaultScope) warnings.push(`config: unknown defaultScope "${String(u.defaultScope)}"`);
+
+	const defaultSort = (SESSION_SORT_MODES as readonly string[]).includes(u.defaultSort as string)
+		? (u.defaultSort as SessionSortMode)
+		: DEFAULT_CONFIG.defaultSort;
+	if (u.defaultSort !== undefined && defaultSort !== u.defaultSort) warnings.push(`config: unknown defaultSort "${String(u.defaultSort)}"`);
+
+	let leftColumnRatio = DEFAULT_CONFIG.leftColumnRatio;
+	if (u.leftColumnRatio !== undefined) {
+		if (typeof u.leftColumnRatio === "number" && u.leftColumnRatio >= 0.15 && u.leftColumnRatio <= 0.6) {
+			leftColumnRatio = u.leftColumnRatio;
+		} else {
+			warnings.push("config: leftColumnRatio must be a number between 0.15 and 0.6");
+		}
+	}
+
+	const keymap = mergeKeymap(DEFAULT_KEYMAP, u.keymap, warnings);
+	// locale 未指定时不写入该键（exactOptionalPropertyTypes），运行时按系统语言。
+	return { keymap, defaultScope, defaultSort, leftColumnRatio, warnings, ...(locale !== undefined ? { locale } : {}) };
+}
+
+/**
+ * Deep-merge the user keymap over the defaults, scope by scope, action by action.
+ * 用户为某个 action 提供的键位整体替换默认值（不是追加），null 表示解绑。
+ */
+export function mergeKeymap(base: Keymap, user: UserConfig["keymap"], warnings: string[] = []): Keymap {
+	const out = {} as Keymap;
+	for (const scope of KEY_SCOPES) out[scope] = { ...base[scope] };
+	if (user === undefined) return out;
+	if (!isRecord(user)) {
+		warnings.push("config: keymap must be an object");
+		return out;
+	}
+	for (const [scopeName, paneMap] of Object.entries(user)) {
+		if (!KEY_SCOPES.includes(scopeName as KeyScope)) {
+			warnings.push(`config: unknown keymap scope "${scopeName}"`);
+			continue;
+		}
+		if (!isRecord(paneMap)) {
+			warnings.push(`config: keymap.${scopeName} must be an object`);
+			continue;
+		}
+		const target: PaneKeymap = out[scopeName as KeyScope];
+		for (const [action, value] of Object.entries(paneMap as UserPaneKeymap)) {
+			if (value === null) {
+				delete target[action as ActionId];
+				continue;
+			}
+			if (isChordValue(value)) {
+				target[action as ActionId] = value;
+			} else {
+				warnings.push(`config: keymap.${scopeName}.${action} must be a string, string[] or null`);
+			}
+		}
+	}
+	return out;
+}
+
+function isChordValue(v: unknown): v is KeyChord | KeyChord[] {
+	if (typeof v === "string") return v.trim().length > 0;
+	return Array.isArray(v) && v.length > 0 && v.every((c) => typeof c === "string" && c.trim().length > 0);
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}

package/src/config/keymap.ts

@@ -0,0 +1,219 @@
+/**
+ * Default keymap.
+ *
+ * Bindings follow docs/design.md and lazygit / vim conventions.
+ * Users can override any of these via `~/.pi/agent/lazy-panel.json`
+ * (see ./config.ts). Chord syntax (see ./keys.ts):
+ *   "j"          single key            "ctrl+d"   modifier combo
+ *   "G"          uppercase = shift+g   "gg"       two-key sequence
+ *   "ctrl+w h"   space-separated multi-step sequence
+ *
+ * 默认键位是纯数据；解析/匹配逻辑在 keys.ts，合并用户配置在 config.ts。
+ */
+
+import { TREE_DIALOG_SCOPE } from "../constants.ts";
+import { t } from "../i18n/index.ts";
+import type { ActionId, KeyScope, Keymap, PaneId } from "../types.ts";
+
+export const DEFAULT_KEYMAP: Keymap = {
+	// 每个 scope 里 key 的书写顺序 = ? 帮助里的展示顺序（buildScopeLines 遍历 Object.keys），
+	// 所以按使用频率排：高频在前。键位解析和顺序无关，footer 另有 FOOTER_HINTS 顺序，互不影响。
+	global: {
+		search: "/",
+		// 面板切换参考 lazygit：h/l 前后切换，1/2/3 直接跳到对应编号的面板。
+		"focus-next": ["l", "tab"],
+		"focus-prev": "h",
+		"focus-sessions": "1",
+		"focus-tree": "2",
+		"focus-content": "3",
+		"search-next": "n",
+		"search-prev": "N",
+		// C / A 各自只切到一种范围，不做 toggle。
+		"scope-current": "C",
+		"scope-all": "A",
+		help: "?",
+		// 和 pi 的 /changelog 一样查看 pi 的更新日志（居中大弹窗，可滚动）。
+		changelog: "@",
+		quit: ["q", "ctrl+c"],
+	},
+
+	sessions: {
+		"session-resume": "return",
+		"move-down": ["j", "down"],
+		"move-up": ["k", "up"],
+		"go-top": "gg",
+		"go-bottom": "G",
+		"session-new": "n",
+		"session-delete": "d",
+		"session-rename": "r",
+		"session-sort": "s",
+		"session-info": "i",
+		"session-toggle-select": "space",
+		// c 压缩光标所在会话（对应 /compact）；C（大写）是全局 scope-current，不冲突。
+		"session-compact": "c",
+		"session-fork": "o",
+		"session-clone": "y",
+		"session-copy-last-reply": "Y",
+		"scroll-content-down": "J",
+		"scroll-content-up": "K",
+		"session-export": "e",
+		"session-import": "I",
+		"session-share": "S",
+	},
+
+	tree: {
+		"tree-restore": "return",
+		"move-down": ["j", "down"],
+		"move-up": ["k", "up"],
+		"go-top": "gg",
+		"go-bottom": "G",
+		// 折叠 / 展开光标所在的分支段（vim 的 za）。
+		"tree-fold": "z",
+		// 小面板只显示部分数据，搜索 / 过滤放在 a 打开的完整树对话框里。
+		"tree-open": "a",
+		// 打标签用 T，和 pi 自带 /tree 的 shift+T 一致；这样 l 留给全局的“下一个面板”。
+		"tree-label": "T",
+		"tree-copy": "y",
+	},
+
+	// 只读面板：只保留上下滚动 + 顶部/底部（搜索 / 帮助等走 global）。
+	content: {
+		"move-down": ["j", "down"],
+		"move-up": ["k", "up"],
+		"go-top": "gg",
+		"go-bottom": "G",
+	},
+
+	// 树对话框（a 打开）：这里只放对话框独有的键；j/k、gg/G、Enter、y、T、z 沿用 tree 面板的绑定，
+	// `/` 沿用 global 的 search（在对话框里是聚焦顶部的搜索框）。过滤键和 pi /tree 的 ctrl+d/t/u/l/a 一一对应，
+	// 所以 l 在对话框里是 labeled 过滤而不是"下一个面板"（h 没有对话框绑定，切面板在这里被关掉）。
+	[TREE_DIALOG_SCOPE]: {
+		"tree-filter-default": "d",
+		"tree-filter-no-tools": "t",
+		"tree-filter-user": "u",
+		"tree-filter-labeled": "l",
+		"tree-filter-all": "a",
+		"tree-dialog-close": "q",
+	},
+};
+
+/** Short description of `action`, shown in the help overlay (localised). */
+export function actionDescription(action: ActionId): string {
+	return t(`action.${action}`);
+}
+
+/**
+ * Actions of outer scopes that do nothing while `scope` has the keys.
+ * Inside the tree dialog, pane switching, list scope, n / N, quitting the
+ * panel, `?` (every key is on the dialog's own hint row), `a` (the dialog
+ * is already open) and `@` (the changelog) are switched off.
+ *
+ * 外层 scope 里在这里关掉的动作：对话框里 h/1/2/3/Tab 等不再切换面板（l 被对话框自己的
+ * labeled 过滤遮住了），? 也不开帮助——对话框底部一行已经列全了它的键。
+ */
+export const DISABLED_ACTIONS: Partial<Record<KeyScope, ActionId[]>> = {
+	[TREE_DIALOG_SCOPE]: [
+		"focus-next",
+		"focus-prev",
+		"focus-sessions",
+		"focus-tree",
+		"focus-content",
+		"scope-current",
+		"scope-all",
+		"search-next",
+		"search-prev",
+		"help",
+		"quit",
+		"tree-open",
+		"changelog",
+	],
+};
+
+/** Is `action` (bound in an outer scope) switched off while `scope` is focused? */
+export function isDisabledIn(scope: KeyScope, action: ActionId): boolean {
+	return DISABLED_ACTIONS[scope]?.includes(action) ?? false;
+}
+
+/**
+ * Actions merged into a single help line (`?` overlay).
+ *
+ * 帮助面板里同类操作合并成一行，省空间：例如 1/2/3 显示成 `1..3  Focus pane by number`。
+ * 合并只影响帮助展示，不影响键位解析。组内只要有 ≥2 个动作在当前 scope 绑定了键位就合并，
+ * 否则退回单条展示；用户自定义键位一样会如实显示。
+ */
+export interface HelpGroup {
+	/** Member actions, in the order their keys are listed. */
+	actions: ActionId[];
+	/** i18n key (under `helpGroup.`) for the merged line's description. */
+	key: string;
+}
+
+/** Localised description of a merged help line. */
+export function helpGroupText(group: HelpGroup): string {
+	return t(`helpGroup.${group.key}`);
+}
+
+export const HELP_GROUPS: HelpGroup[] = [
+	{ actions: ["focus-prev", "focus-next"], key: "focus" },
+	{ actions: ["focus-sessions", "focus-tree", "focus-content"], key: "focusNumber" },
+	{ actions: ["scope-current", "scope-all"], key: "scope" },
+	{ actions: ["search-next", "search-prev"], key: "searchStep" },
+	{ actions: ["go-top", "go-bottom"], key: "topBottom" },
+	{ actions: ["scroll-content-down", "scroll-content-up"], key: "scrollContent" },
+	{
+		actions: ["tree-filter-default", "tree-filter-no-tools", "tree-filter-user", "tree-filter-labeled", "tree-filter-all"],
+		key: "filters",
+	},
+];
+
+/**
+ * Actions shown as footer hints per pane, in display order (first few that fit).
+ *
+ * 只留最常用的键，长尾（排序 / 信息 / 压缩 / fork / clone / 复制 / 导出 / 导入 / 分享 / changelog）
+ * 都收进 ? 帮助里，避免 footer 挤满一串半高频的键。
+ */
+export const FOOTER_HINTS: Record<PaneId, ActionId[]> = {
+	sessions: ["search", "focus-next", "scope-current", "scope-all", "session-resume", "session-delete", "session-rename", "session-new", "help", "quit"],
+	tree: ["search", "focus-next", "tree-restore", "tree-fold", "tree-open", "help", "quit"],
+	content: ["search", "focus-next", "go-top", "go-bottom", "help", "quit"],
+};
+
+/**
+ * Hint rows of the tree dialog (its bottom row and the footer), in display
+ * order — the first ones survive a narrow terminal, so `q close` comes before
+ * the filters; an inner array is one merged hint such as `d/t/u/l/a filter`.
+ * Keys come from the resolved keymap (`tree-dialog` scope, then `tree`, then
+ * `global`), the wording from treeDialogHintText().
+ */
+export const TREE_DIALOG_FOOTER: ActionId[][] = [
+	["search"],
+	["move-down", "move-up"],
+	["tree-restore"],
+	["tree-dialog-close"],
+	["tree-fold"],
+	["tree-filter-default", "tree-filter-no-tools", "tree-filter-user", "tree-filter-labeled", "tree-filter-all"],
+	["tree-copy"],
+	["tree-label"],
+];
+
+/** Wording of a TREE_DIALOG_FOOTER hint (localised), keyed by its first action. */
+export function treeDialogHintText(action: ActionId): string {
+	return t(`treeHint.${action}`);
+}
+
+/** Display name of a scope in the help overlay (localised). */
+export function scopeTitle(scope: KeyScope): string {
+	return t(`scopeTitle.${scope}`);
+}
+
+/** Pane title shown in the frame header (localised); the panel prefixes it with the jump key ("[1] SESSIONS"). */
+export function paneTitleText(pane: PaneId): string {
+	return t(`pane.${pane}Title`);
+}
+
+/** Action that focuses each pane, used to derive the "[1]" prefix from the resolved keymap. */
+export const FOCUS_ACTIONS: Record<PaneId, ActionId> = {
+	sessions: "focus-sessions",
+	tree: "focus-tree",
+	content: "focus-content",
+};