@bachi/pi-coder 1.0.0

package/extensions/startup-logo/logo.ts

@@ -0,0 +1,124 @@
+/**
+ * logo.ts — 启动 logo 的字形（静态）
+ *
+ * 字形是 `curl -fsSL https://pi.dev/install.sh | sh` 顶部那只 π 印记，取自
+ * `npm:pi-claude-code-tui@0.1.14`（它自己也是照抄安装脚本）。上游把它做成 22 帧动画，
+ * 本仓库只要一只静态 logo，所以这里**只留落定态那一格的形状**，帧表、笔画推进、底座闪动
+ * 全部去掉。
+ *
+ * 形状用 4×4 的布尔格（一格 = 三个 `█`，实心 / 空格），比上游那张「1 基坐标 + 逐帧取色」
+ * 的表好读也好测。
+ *
+ * **刻意补了上游漏掉的一格**：上游落定帧（phase 6）的格子表是
+ * `3,2 3,3 3,4 4,2 4,4 5,2 5,3 6,2 6,5`，而它前几帧（phase 4/5 以及白闪帧）都带 `(5,5)`。
+ * 少了这格，右腿会断成「悬空的一只脚」，静态显示时特别明显（动画里一闪而过没人注意），
+ * 显然是上游那张表的笔误。这里按 `(5,5)` 在场的那版形状画。
+ *
+ * 本文件不 import pi / pi-tui：颜色由 `index.ts` 用 `theme.fg("accent", …)` 现取，
+ * 所以 `/theme` 换肤能跟随；也让 `node --test clients/pi/extensions/startup-logo/*.test.ts` 能直接跑。
+ */
+
+/** 一格 = 三个块字符。 */
+export const MARK_CELL = "███";
+
+/** 空格占位（与 `MARK_CELL` 等宽，保证每行可见宽度一致，侧栏才对得齐）。 */
+export const MARK_BLANK = " ".repeat(MARK_CELL.length);
+
+/**
+ * 印记左侧留白：每行前面一个空格。
+ *
+ * 顶格贴着终端最左边看着太挤，统一缩进一格；这一格算进 `MARK_WIDTH`，侧栏列与窄终端判定
+ * 都跟着走，调用方不需要另补。
+ */
+export const MARK_INDENT = " ";
+
+/** 4×4 布尔格，1 = 实心。行序自上而下，列序自左而右。 */
+const MARK_GRID: readonly (readonly (0 | 1)[])[] = [
+	[1, 1, 1, 0],
+	[1, 0, 1, 0],
+	[1, 1, 0, 1],
+	[1, 0, 0, 1],
+];
+
+/** 印记高度（行）。 */
+export const MARK_ROWS = MARK_GRID.length;
+
+/** 印记本体宽度（列）× 每格字符数 = 12。 */
+export const MARK_COLS = MARK_GRID[0]!.length;
+export const MARK_GLYPH_WIDTH = MARK_COLS * MARK_CELL.length;
+
+/** 每行可见宽度（含左侧留白）= 13。 */
+export const MARK_WIDTH = MARK_INDENT.length + MARK_GLYPH_WIDTH;
+
+/** 单格查询（越界当作空格），给单测和调试用。 */
+export function markCellFilled(row: number, col: number): boolean {
+	return MARK_GRID[row]?.[col] === 1;
+}
+
+/**
+ * 印记行的画笔：收「这一格实不实心」，返回**可见宽度为 3** 的字符串。
+ *
+ * 刻意做成逐格而不是「整行交给一个 paint」：整行包色会把行尾那几个占位空格也吃进色块里，
+ * 于是「每行可见宽度 == MARK_WIDTH」这个不变量在带色版本上就不成立了（侧栏列会歪）。
+ *
+ * 默认画笔返回未着色的 `███` / 空格，方便单测。
+ */
+export type MarkCellPainter = (filled: boolean) => string;
+
+export function markLines(paintCell: MarkCellPainter = (filled) => (filled ? MARK_CELL : MARK_BLANK)): string[] {
+	return MARK_GRID.map((row) => MARK_INDENT + row.map((filled) => paintCell(filled === 1)).join(""));
+}
+
+/**
+ * 把侧栏文字（已着色）贴到印记右侧，**垂直居中**（2 条落在第 1、2 行）。
+ *
+ * 前提：传进来的行**可见宽度已等于 `MARK_WIDTH`**（`markLines` 保证），所以直接接在行尾就
+ * 对得齐，这里不按字符串长度补 —— 行里有 ANSI 时按长度补一定歪。左侧留白（`MARK_INDENT`）
+ * 已经算在 `MARK_WIDTH` 里，所以侧栏列也跟着右移一格，不需要在这里额外处理。
+ *
+ * **不裁行尾占位空格**：它们是「每行 `MARK_WIDTH` 列」这个不变量的一部分。上游那种整行包色的写法
+ * 在这里也不成立（行尾是 ANSI 重置符而不是空白，`trimEnd` 会静默变成空操作），所以统一不裁，
+ * 让行为与调用方怎么上色无关。这些空格没有底色，终端里不可见，pi 也照样按宽度截断。
+ */
+export function attachSideText(lines: readonly string[], side: readonly string[], gap = 2): string[] {
+	if (lines.length === 0) return [];
+	const start = Math.max(0, Math.floor((lines.length - side.length) / 2));
+	return lines.map((line, i) => {
+		const text = side[i - start];
+		return i >= start && text ? `${line}${" ".repeat(gap)}${text}` : line;
+	});
+}
+
+export interface HeaderSections {
+	/** 已着色的 logo 行（含侧栏文字）。 */
+	logo: readonly string[];
+	/** 已着色的快捷键提示行（内置 header 那一行紧凑版）。 */
+	hints?: string;
+	/** 已着色的说明行。 */
+	onboarding?: string;
+}
+
+/**
+ * 完整 header 行序：logo → 空行 → 提示 → 空行 → 说明。
+ * 缺某段就不留多余空行（窄终端回退时 logo 段为空）。
+ */
+export function composeHeaderLines(sections: HeaderSections): string[] {
+	const lines = [...sections.logo];
+	if (sections.hints) {
+		if (lines.length > 0) lines.push("");
+		lines.push(sections.hints);
+	}
+	if (sections.onboarding) {
+		if (lines.length > 0) lines.push("");
+		lines.push(sections.onboarding);
+	}
+	return lines;
+}
+
+/** 绝对路径缩短：家目录内显示成 `~/...`。 */
+export function shortenPath(cwd: string, home: string | undefined): string {
+	if (!home) return cwd;
+	if (cwd === home) return "~";
+	if (cwd.startsWith(`${home}/`)) return `~${cwd.slice(home.length)}`;
+	return cwd;
+}

package/extensions/statusline/footer-guard.test.ts

@@ -0,0 +1,273 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	FOOTER_GUARD_KEY,
+	findRenderContainer,
+	freezeFooterContainer,
+	releaseFooterGuard,
+	type RenderableContainer,
+} from "./footer-guard.ts";
+
+/**
+ * 仿 pi-tui 的 `Container`：`clear()` 会**换掉**整个 children 数组
+ * （`this.children = []`），所以守卫必须每次重读该字段而不是缓存它。
+ */
+class FakeContainer implements RenderableContainer {
+	children: unknown[] = [];
+	/** 原 render 被调用的次数（断言「默认 footer 一帧都没出」用）。 */
+	originalRenders = 0;
+
+	addChild(component: unknown): void {
+		this.children.push(component);
+	}
+
+	clear(): void {
+		this.children = [];
+	}
+
+	render(width: number): string[] {
+		this.originalRenders += 1;
+		return this.children.flatMap((child) => (child as Leaf).render(width));
+	}
+}
+
+/** 仿叶子组件：行里带上自己的名字和宽度，方便看出行是谁、按哪个宽度渲染的。 */
+interface Leaf {
+	render(width: number): string[];
+}
+
+function leaf(name: string, lines = 1): Leaf {
+	return { render: (width: number) => Array.from({ length: lines }, () => `${name}#${width}`) };
+}
+
+/** 仿 `tui`：只有 children，没有 render（findRenderContainer 只认 children）。 */
+function tuiRoot(...children: unknown[]): { children: unknown[] } {
+	return { children };
+}
+
+test("findRenderContainer 按对象身份认出直接持有它的容器", () => {
+	const ours = leaf("statusline");
+	const inner = new FakeContainer();
+	inner.addChild(ours);
+	const outer = new FakeContainer();
+	outer.addChild(inner);
+	const root = tuiRoot(new FakeContainer(), outer);
+
+	assert.equal(findRenderContainer(root, ours), inner);
+});
+
+test("findRenderContainer 找不到就返回 undefined，不猜位置", () => {
+	const inner = new FakeContainer();
+	inner.addChild(leaf("other"));
+	const root = tuiRoot(inner);
+
+	assert.equal(findRenderContainer(root, leaf("missing")), undefined);
+	assert.equal(findRenderContainer(root, undefined), undefined);
+	assert.equal(findRenderContainer(undefined, leaf("x")), undefined);
+	assert.equal(findRenderContainer({ notAContainer: true }, leaf("x")), undefined);
+});
+
+test("findRenderContainer 容忍环状引用与只读 children", () => {
+	const a = new FakeContainer();
+	const b = new FakeContainer();
+	a.addChild(b);
+	b.addChild(a);
+
+	assert.equal(findRenderContainer(a, leaf("nope")), undefined);
+
+	const frozenRoot = tuiRoot({ children: Object.freeze([leaf("x")]) as unknown[] });
+	assert.equal(findRenderContainer(frozenRoot, leaf("y")), undefined);
+});
+
+test("我们的组件在位时原样透传，被换成内置 footer 时出重放行", () => {
+	const ours = leaf("statusline");
+	const builtIn = leaf("pi-default");
+	const container = new FakeContainer();
+	container.addChild(ours);
+
+	const release = freezeFooterContainer({
+		container,
+		ownComponent: ours,
+		frozenRender: (width) => [`frozen#${width}`],
+	});
+	assert.equal(typeof release, "function");
+
+	// 正常会话：真实渲染照旧。
+	assert.deepEqual(container.render(80), ["statusline#80"]);
+	assert.equal(container.originalRenders, 1);
+
+	// 换会话窗口：pi 已经 clear() 并挂上内置 footer。
+	container.clear();
+	container.addChild(builtIn);
+	assert.deepEqual(container.render(80), ["frozen#80"]);
+	assert.deepEqual(container.render(40), ["frozen#40"]);
+	// 内置 footer 一次都没被渲染 → 屏幕上不会出现默认 footer。
+	assert.equal(container.originalRenders, 1);
+});
+
+test("重放行按当前宽度重新截断", () => {
+	const ours = leaf("statusline");
+	const container = new FakeContainer();
+	container.addChild(ours);
+	const wide = " ".repeat(30);
+	freezeFooterContainer({
+		container,
+		ownComponent: ours,
+		frozenRender: (width) => [wide.slice(0, width)],
+	});
+
+	container.clear();
+	container.addChild(leaf("pi-default"));
+	assert.deepEqual(container.render(10), [wide.slice(0, 10)]);
+});
+
+test("解除接管后恢复原渲染，且不留 own render 属性与接管记录", () => {
+	const ours = leaf("statusline");
+	const builtIn = leaf("pi-default");
+	const container = new FakeContainer();
+	container.addChild(ours);
+
+	const release = freezeFooterContainer({
+		container,
+		ownComponent: ours,
+		frozenRender: () => ["frozen"],
+	})!;
+	container.clear();
+	container.addChild(builtIn);
+	assert.deepEqual(container.render(10), ["frozen"]);
+
+	release();
+	assert.equal(Object.prototype.hasOwnProperty.call(container, "render"), false);
+	assert.equal((container as { [FOOTER_GUARD_KEY]?: unknown })[FOOTER_GUARD_KEY], undefined);
+	assert.deepEqual(container.render(10), ["pi-default#10"]);
+
+	// 幂等：重复解除不再改动任何东西。
+	release();
+	assert.equal(Object.prototype.hasOwnProperty.call(container, "render"), false);
+});
+
+test("对同一容器重复接管会先交还上一次，不叠两层", () => {
+	const first = leaf("first");
+	const second = leaf("second");
+	const container = new FakeContainer();
+	container.addChild(first);
+	container.addChild(second);
+
+	freezeFooterContainer({ container, ownComponent: first, frozenRender: () => ["frozen-first"] });
+	freezeFooterContainer({ container, ownComponent: second, frozenRender: () => ["frozen-second"] });
+
+	// first 在位、second 不在位：若两层的 wrapper 还叠着，这里会出 frozen-first；
+	// 只保留最后一次接管 → 判定 second 不在位 → 出 frozen-second。
+	container.clear();
+	container.addChild(first);
+	assert.deepEqual(container.render(7), ["frozen-second"]);
+
+	// second 回到位 → 透传。
+	container.addChild(second);
+	assert.deepEqual(container.render(7), ["first#7", "second#7"]);
+});
+
+test("超时后自愈：组件在位与否都交还原渲染", () => {
+	const ours = leaf("statusline");
+	const builtIn = leaf("pi-default");
+	const container = new FakeContainer();
+	container.addChild(ours);
+	let clock = 1000;
+	const release = freezeFooterContainer({
+		container,
+		ownComponent: ours,
+		frozenRender: () => ["frozen"],
+		maxAgeMs: 500,
+		now: () => clock,
+	})!;
+
+	// 组件仍在新位置（正常交接后的样子）+ 已超时 → 透传并交还。
+	clock = 1600;
+	assert.deepEqual(container.render(9), ["statusline#9"]);
+	assert.equal(Object.prototype.hasOwnProperty.call(container, "render"), false);
+
+	// 另一侧：新 footer 一直没来（换会话失败）→ 超时后回到 pi 默认行为。
+	const ours2 = leaf("statusline2");
+	const container2 = new FakeContainer();
+	container2.addChild(ours2);
+	let clock2 = 0;
+	freezeFooterContainer({
+		container: container2,
+		ownComponent: ours2,
+		frozenRender: () => ["frozen"],
+		maxAgeMs: 500,
+		now: () => clock2,
+	});
+	container2.clear();
+	container2.addChild(builtIn);
+	clock2 = 501;
+	assert.deepEqual(container2.render(9), ["pi-default#9"]);
+	release();
+});
+
+test("未超时期间无论多少帧都只出重放行", () => {
+	const ours = leaf("statusline");
+	const container = new FakeContainer();
+	container.addChild(ours);
+	freezeFooterContainer({
+		container,
+		ownComponent: ours,
+		frozenRender: (width) => [`frozen#${width}`, `frozen#${width}`],
+	});
+	container.clear();
+	container.addChild(leaf("pi-default"));
+
+	for (let frame = 0; frame < 5; frame += 1) {
+		assert.deepEqual(container.render(80), ["frozen#80", "frozen#80"]);
+	}
+});
+
+test("容器形状不对时什么都不做（非 tui 模式 / pi 改了结构）", () => {
+	const noop = () => ["frozen"];
+	assert.equal(freezeFooterContainer({ container: undefined, ownComponent: {}, frozenRender: noop }), undefined);
+	assert.equal(freezeFooterContainer({ container: {}, ownComponent: {}, frozenRender: noop }), undefined);
+	assert.equal(
+		freezeFooterContainer({ container: { children: [] }, ownComponent: {}, frozenRender: noop }),
+		undefined,
+	);
+	assert.equal(
+		freezeFooterContainer({
+			container: { children: "not-an-array", render: noop } as unknown as RenderableContainer,
+			ownComponent: {},
+			frozenRender: noop,
+		}),
+		undefined,
+	);
+	assert.equal(freezeFooterContainer({ container: new FakeContainer(), ownComponent: undefined, frozenRender: noop }), undefined);
+});
+
+test("接管过程中容器不可写时不抛错", () => {
+	const container = new FakeContainer();
+	const ours = leaf("statusline");
+	container.addChild(ours);
+	Object.defineProperty(container, "render", {
+		configurable: false,
+		writable: false,
+		value: (width: number) => [`locked#${width}`],
+	});
+
+	assert.equal(
+		freezeFooterContainer({ container, ownComponent: ours, frozenRender: () => ["frozen"] }),
+		undefined,
+	);
+	assert.deepEqual(container.render(4), ["locked#4"]);
+});
+
+test("releaseFooterGuard 能解除别人（别的扩展实例）留下的接管", () => {
+	const ours = leaf("statusline");
+	const builtIn = leaf("pi-default");
+	const container = new FakeContainer();
+	container.addChild(ours);
+	freezeFooterContainer({ container, ownComponent: ours, frozenRender: () => ["frozen"] });
+
+	assert.equal(releaseFooterGuard(container), true);
+	assert.equal(releaseFooterGuard(container), false);
+	container.clear();
+	container.addChild(builtIn);
+	assert.deepEqual(container.render(3), ["pi-default#3"]);
+});

package/extensions/statusline/footer-guard.ts

@@ -0,0 +1,171 @@
+/**
+ * footer-guard.ts — 会话替换期间的 footer「冻结」
+ *
+ * 要解决的问题：pi 每次换会话（`/new`、`/clear`、`/resume`、fork、rewind）都会在
+ * `session_shutdown` 之后、新会话 `session_start` 之前调 `resetExtensionUI()`，它无条件
+ * `setExtensionFooter(undefined)` 把 footer 还原成内置那只、并 `clearExtensionStatuses()`
+ * 清掉所有 `setStatus` 文本（`interactive-mode.js`）。中间要新建会话对象、重绑扩展，
+ * 几十毫秒起步，而 pi-tui 的渲染节流只有 16ms（`TuiBase.MIN_RENDER_INTERVAL_MS`），
+ * 所以这段窗口至少会出几帧 —— 用 `ctx.ui.setFooter()` 装的 statusline 就「闪」成
+ * pi 默认 footer，第二行（cwd / checkpoint）整行消失。
+ *
+ * 为什么只能在渲染路径上解决：扩展侧没有更早的钩子。新扩展实例要等
+ * `bindCurrentSessionExtensions()` 才拿到 ctx，而那正是窗口结束的时刻；在窗口内主动
+ * 重挂 footer 也不可靠（`resetExtensionUI` 发生在我们的 `session_shutdown` 回调**之后**，
+ * 且整条链上有多个 await，`setImmediate` / 微任务谁先谁后取决于别的扩展在这段里等多久）。
+ * 所以保证落在**出帧那一刻**：接管 footer 容器的 `render`，发现里面装的已经不是我们的
+ * 组件时，返回上一帧的行 —— 默认 footer 一帧都不会出现。
+ *
+ * 做法上的约束（和本目录其它文件一致）：
+ *   - 只替换 footer 容器的 `render` 方法，不改 `children`、不猜下标、不碰 pi 的内部状态；
+ *   - 容器用**对象身份**从 `tui.children` 找（`findRenderContainer`），找不到就什么都不做；
+ *   - 任何一步抛错都当作「没冻住」，绝不把异常漏给宿主弹 extension error；
+ *   - 接管记录挂在容器的 `FOOTER_GUARD_KEY`（`Symbol.for`，所以 `/reload` 后新的扩展实例
+ *     也能看到并解除旧实例遗留的接管）；另有 `maxAgeMs` 兜底，交接万一失败也只冻一小会儿。
+ *
+ * 已知小代价：冻结期间该容器的鼠标命中测试（`Container.handleMouse` 读 `children`）会按
+ * 内置 footer 的高度算，而窗口只有一两帧、footer 本来不可点，可忽略。
+ */
+
+/** 挂在 footer 容器上的接管记录键（全局符号注册表：跨扩展实例可见）。 */
+export const FOOTER_GUARD_KEY: symbol = Symbol.for("litellm-any.pi-statusline.footerGuard");
+
+/** 冻结的最长时长：正常情况下新会话的 `session_start` 会远早于它解除。 */
+export const FOOTER_GUARD_MAX_AGE_MS = 3000;
+
+/** pi-tui `Container` 里本模块用到的那部分结构（`children` 是公开字段）。 */
+export interface RenderableContainer {
+	children: unknown[];
+	render(width: number): string[];
+}
+
+interface GuardRecord {
+	release: () => void;
+}
+
+/**
+ * 在 `root` 的子树里按对象身份找「直接装着 `component` 的那个容器」。
+ * 只认对象身份（同形状的组件到处都是），带 seen 集与深度上限，任何异常都当作没找到。
+ */
+export function findRenderContainer(
+	root: unknown,
+	component: unknown,
+	maxDepth = 6,
+): RenderableContainer | undefined {
+	if (component === undefined || component === null) return undefined;
+	const seen = new Set<unknown>();
+
+	const walk = (node: unknown, depth: number): RenderableContainer | undefined => {
+		if (depth > maxDepth || node === null || typeof node !== "object" || seen.has(node)) {
+			return undefined;
+		}
+		seen.add(node);
+		const children = (node as { children?: unknown }).children;
+		if (!Array.isArray(children)) return undefined;
+		if (children.includes(component)) return node as RenderableContainer;
+		for (const child of children) {
+			const found = walk(child, depth + 1);
+			if (found) return found;
+		}
+		return undefined;
+	};
+
+	try {
+		return walk(root, 0);
+	} catch {
+		return undefined;
+	}
+}
+
+/** 解除 `container` 上现有的接管（可能是别的扩展实例遗留的）。返回是否解掉了什么。 */
+export function releaseFooterGuard(container: unknown): boolean {
+	try {
+		const record = (container as { [FOOTER_GUARD_KEY]?: GuardRecord } | undefined)?.[FOOTER_GUARD_KEY];
+		if (!record || typeof record.release !== "function") return false;
+		record.release();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * 接管 footer 容器的渲染，返回解除函数（幂等）。
+ *
+ * - `ownComponent` 还在容器里 → 原样透传（并在超时后顺手交还，自愈）；
+ * - 容器被 pi 换成内置 footer → 返回 `frozenRender(width)` 的行；
+ * - 超过 `maxAgeMs` 仍等不到新 footer → 交还，回到 pi 默认行为。
+ */
+export function freezeFooterContainer(options: {
+	container: unknown;
+	ownComponent: unknown;
+	frozenRender: (width: number) => string[];
+	maxAgeMs?: number;
+	now?: () => number;
+}): (() => void) | undefined {
+	const container = options.container as RenderableContainer | undefined;
+	if (
+		!container ||
+		typeof container.render !== "function" ||
+		!Array.isArray(container.children) ||
+		options.ownComponent === undefined
+	) {
+		return undefined;
+	}
+	// 先解除已有接管（自己重入 / 上一个扩展实例遗留），避免叠两层 wrapper。
+	releaseFooterGuard(container);
+
+	const ownComponent = options.ownComponent;
+	const maxAgeMs = options.maxAgeMs ?? FOOTER_GUARD_MAX_AGE_MS;
+	const now = options.now ?? Date.now;
+	const armedAt = now();
+	const hadOwnRender = Object.prototype.hasOwnProperty.call(container, "render");
+	const originalRender = container.render;
+	const state: { released: boolean; record?: GuardRecord } = { released: false };
+
+	const release = (): void => {
+		if (state.released) return;
+		state.released = true;
+		try {
+			const holder = container as { [FOOTER_GUARD_KEY]?: GuardRecord };
+			if (state.record && holder[FOOTER_GUARD_KEY] === state.record) delete holder[FOOTER_GUARD_KEY];
+			if (hadOwnRender) container.render = originalRender;
+			else delete (container as { render?: unknown }).render;
+		} catch {
+			// 容器只读 / 已被替换：wrapper 自己会因 released 标志透传，不再冻。
+		}
+	};
+
+	const wrapper = (width: number): string[] => {
+		if (state.released) return originalRender.call(container, width);
+		const expired = now() - armedAt > maxAgeMs;
+		let mounted = false;
+		try {
+			mounted = Array.isArray(container.children) && container.children.includes(ownComponent);
+		} catch {
+			mounted = true; // 读 children 都抛：别硬撑，交还给原渲染。
+		}
+		if (mounted) {
+			if (expired) release();
+			return originalRender.call(container, width);
+		}
+		if (expired) {
+			release();
+			return originalRender.call(container, width);
+		}
+		try {
+			return options.frozenRender(width);
+		} catch {
+			return originalRender.call(container, width);
+		}
+	};
+
+	try {
+		container.render = wrapper as RenderableContainer["render"];
+		state.record = { release };
+		(container as { [FOOTER_GUARD_KEY]?: GuardRecord })[FOOTER_GUARD_KEY] = state.record;
+	} catch {
+		return undefined;
+	}
+	return release;
+}