repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/memory/src/viewer.ts
Rawimport type { ExtensionContext } from "@earendil-works/pi-coding-agent";
import type { TUI as PiTui } from "@earendil-works/pi-tui";
import {
Box,
matchesKey,
truncateToWidth,
wrapTextWithAnsi,
} from "@earendil-works/pi-tui";
import { pruneSpills, runSql, undoEntry } from "./exec.ts";
import { SCHEMA_VERSION } from "./guide.ts";
import type {
HealthReport,
JournalRow,
MemoryStore,
SizeOverview,
UsageTableRow,
} from "./store.ts";
type Tab = "usage" | "size" | "health" | "browse" | "journal";
const TAB_ORDER: Tab[] = ["usage", "size", "health", "browse", "journal"];
const tabAt = (index: number): Tab => TAB_ORDER[index] ?? "usage";
const SPARK = "▁▂▃▄▅▆▇█";
function sparkline(values: number[]): string {
const max = Math.max(1, ...values);
return values
.map((value) => SPARK[Math.min(7, Math.floor((value / max) * 7.999))])
.join("");
}
function relative(iso: string): string {
if (!iso) return "never";
const elapsed = Date.now() - Date.parse(iso);
if (!Number.isFinite(elapsed)) return "never";
if (elapsed < 60_000) return "just now";
if (elapsed < 3_600_000) return `${Math.floor(elapsed / 60_000)}m ago`;
if (elapsed < 86_400_000) return `${Math.floor(elapsed / 3_600_000)}h ago`;
return `${Math.floor(elapsed / 86_400_000)}d ago`;
}
function bytesLabel(bytes: number): string {
if (bytes >= 1024 * 1024 * 1024)
return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
if (bytes >= 1024 * 1024) return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
if (bytes >= 1024) return `${Math.round(bytes / 1024)} KiB`;
return `${bytes} B`;
}
function countLabel(rows: number | null): string {
if (rows === null) return "—";
if (rows >= 10_000) return `${Math.round(rows / 1000)}k`;
return String(rows);
}
const pad = (text: string, width: number) => text.padEnd(width);
const padL = (text: string, width: number) => text.padStart(width);
export async function viewer(
_pi: unknown,
store: MemoryStore,
ctx: ExtensionContext,
initialSql: string,
): Promise<void> {
await ctx.ui.custom<void>(
(tui: PiTui, theme, _keybindings, done) => {
let tab: Tab = "usage";
let alive = true;
let cachedWidth = 0;
let cachedLines: string[] | undefined;
let status = "";
let confirm: { text: string; run: () => Promise<void> } | undefined;
let filterZombies = false;
let usageRows: UsageTableRow[] = [];
let callsByDay = new Map<string, number>();
let totals = {
calls: 0,
errors: 0,
timeouts: 0,
busy: 0,
spills: 0,
undos: 0,
};
let size: SizeOverview | undefined;
let health: HealthReport | undefined;
let journalRows: JournalRow[] = [];
let journalIndex = 0;
let journalDetail: JournalRow | undefined;
let browseSql = initialSql;
let browseRows: string[][] = [];
let browseColumns: string[] = [];
let browseStatus = "enter runs read-only · ctrl+w arms one write";
let browseTruncated = false;
let browseSpill: string | null = null;
let browseDetail: number | undefined;
const fg = (
color:
| "accent"
| "muted"
| "dim"
| "success"
| "error"
| "warning"
| "text",
text: string,
) => theme.fg(color, text);
function invalidate(): void {
cachedLines = undefined;
}
function refreshData(): void {
if (tab === "usage") {
usageRows = store.usageTableRows();
callsByDay = new Map(
store.callsPerDay(14).map((row) => [row.day, row.calls]),
);
totals = store.journalTotals(14);
} else if (tab === "size") {
size = store.sizeOverview();
} else if (tab === "health") {
void store.healthChecks().then((report) => {
health = report;
invalidate();
tui.requestRender();
});
health ??= {
verdict: "ok",
checks: [{ label: "checking…", status: "ok" }],
};
} else if (tab === "journal") {
journalRows = store.recentJournal(100);
}
invalidate();
}
function switchTo(next: Tab): void {
tab = next;
confirm = undefined;
refreshData();
tui.requestRender();
}
async function executeBrowse(write: boolean): Promise<void> {
const sql = browseSql.trim();
if (!sql) {
browseStatus = "type a SQL statement first";
return;
}
try {
const outcome = await runSql(store, sql, {
actor: "human",
readonly: !write,
...(write ? { mode: "fix" as const } : {}),
});
browseColumns = outcome.columns;
browseRows = outcome.rows.map((row) =>
row.map((cell) => (cell === null ? "NULL" : String(cell))),
);
browseTruncated = outcome.truncated;
browseSpill = outcome.spillPath;
browseDetail = undefined;
browseStatus = `${outcome.rowCount} row(s)${
outcome.changes > 0 ? `, ${outcome.changes} written` : ""
} · ${outcome.durationMs}ms · journaled #${outcome.journalSeq}${
outcome.schemaChanged
? " · document new tables in _schema_docs"
: ""
}`;
refreshData();
} catch (error) {
browseStatus =
error instanceof Error
? error.message.slice(0, 300)
: "query failed";
}
tui.requestRender();
}
async function runConfirmed(): Promise<void> {
const action = confirm;
confirm = undefined;
if (!action) return;
status = "working…";
await action.run();
refreshData();
tui.requestRender();
}
function renderUsage(_width: number): string[] {
const days: string[] = [];
for (let offset = 13; offset >= 0; offset--) {
const day = new Date(Date.now() - offset * 86_400_000)
.toISOString()
.slice(0, 10);
days.push(String(callsByDay.get(day) ?? 0));
}
const lines = [
` calls/day ${fg("success", sparkline(days.map(Number)))} ${totals.calls} calls in 14d`,
` ${fg("muted", `reads/writes · ${totals.errors} errors · ${totals.busy} busy · ${totals.timeouts} timeouts · ${totals.spills} spills · ${totals.undos} undos`)}`,
"",
fg(
"dim",
`${pad("table", 20)}${pad("bytes", 10)}${padL("rows", 7)}${padL("reads", 7)}${padL("writes", 7)}${padL("last read", 11)} flag`,
),
];
const shown = usageRows.filter(
(row) =>
!filterZombies || row.flag === "ZOMBIE" || row.flag === "DEAD",
);
if (!shown.length)
lines.push(
` ${fg("muted", filterZombies ? "no unread tables" : "no tables yet — the agent creates them")}`,
);
for (const row of shown.slice(0, 14)) {
const flag =
row.flag === "ZOMBIE"
? fg("warning", "ZOMBIE")
: row.flag === "DEAD"
? fg("error", "DEAD")
: row.flag === "HOT"
? fg("accent", "HOT")
: "";
lines.push(
` ${pad(row.name, 20)}${pad(bytesLabel(row.bytes), 10)}${padL(countLabel(row.rows), 7)}${padL(String(row.reads), 7)}${padL(String(row.writes), 7)}${padL(relative(row.lastRead), 11)} ${flag}`,
);
}
lines.push(
"",
fg("dim", "reads/writes from the audit journal · f zombie filter"),
);
return lines;
}
function renderSize(_width: number): string[] {
if (!size) return [` ${fg("muted", "measuring…")}`];
const lines = [
` total ${bytesLabel(size.totalBytes)} · pages ${size.pageCount} · freelist ${size.freelist} · data ${bytesLabel(size.dataBytes)} · index ${bytesLabel(size.indexBytes)}`,
"",
fg(
"dim",
`${pad("object", 34)}${pad("type", 8)}${padL("bytes", 10)} bar (█ = ${bytesLabel(Math.max(1024, Math.round(size.totalBytes / 40)))})`,
),
];
const scale = Math.max(1, size.totalBytes / 40);
for (const object of size.objects.slice(0, 12)) {
const bars = Math.max(1, Math.round(object.bytes / scale));
lines.push(
` ${pad(object.name.slice(0, 34), 34)}${pad(object.type, 8)}${padL(bytesLabel(object.bytes), 10)} ${fg("accent", "█".repeat(Math.min(60, bars)))}${object.rows !== null ? ` ${countLabel(object.rows)} rows` : ""}`,
);
}
const tail = size.objects.slice(12);
if (tail.length)
lines.push(
` ${fg("dim", `… ${tail.length} smaller objects (${bytesLabel(tail.reduce((sum, object) => sum + object.bytes, 0))})`)}`,
);
lines.push("", fg("dim", "junk = big + never read → see Usage tab"));
return lines;
}
function renderHealth(_width: number): string[] {
if (!health) return [` ${fg("muted", "checking…")}`];
const dot =
health.verdict === "ok"
? fg("success", "● ok")
: health.verdict === "warning"
? fg("warning", "● warning")
: fg("error", "● error");
const lines = [` ${dot}`, ""];
for (const check of health.checks) {
const mark =
check.status === "ok"
? fg("success", "✓")
: check.status === "warn"
? fg("warning", "⚠")
: fg("error", "✗");
lines.push(
` ${mark} ${check.label}${check.hint ? ` ${fg("dim", check.hint)}` : ""}`,
);
}
lines.push("", fg("dim", "v VACUUM · c checkpoint · r re-check now"));
return lines;
}
function renderBrowse(width: number): string[] {
const lines = [
` sql${fg("dim", "[ro]")}▸ ${fg("accent", browseSql || "")}_`,
"",
];
if (browseColumns.length) {
lines.push(
fg(
"dim",
browseColumns
.map((column) => pad(column.slice(0, 18), 20))
.join(""),
),
);
for (const [index, row] of browseRows.entries()) {
const selected = browseDetail === index;
lines.push(
`${selected ? fg("accent", ">") : " "} ${row.map((cell) => pad(cell.slice(0, 18), 20)).join("")}`,
);
}
if (browseTruncated)
lines.push(
` ${fg("dim", `full result: ${browseSpill ?? "(spill pending)"}`)}`,
);
lines.push("");
}
lines.push(
` ${fg(browseStatus.startsWith("no such") || /failed/iu.test(browseStatus) ? "error" : "dim", browseStatus)}`,
);
lines.push(
fg(
"dim",
"type SQL · enter run read-only · ctrl+w arm write · ↑↓ row · enter row detail · esc clear",
),
);
if (browseDetail !== undefined && browseRows[browseDetail]) {
const detail = browseDetail;
lines.push("", fg("accent", `row ${detail + 1}`));
for (const [column, value] of browseColumns.map((column, index) => [
column,
browseRows[detail]?.[index] ?? "",
])) {
for (const part of wrapTextWithAnsi(
`${column}: ${value}`,
Math.max(20, width - 4),
))
lines.push(` ${part}`);
}
}
return lines;
}
function renderJournal(width: number): string[] {
const lines = [fg("dim", " seq time mode actor statement")];
if (!journalRows.length)
lines.push(
` ${fg("muted", "journal is empty; the first SQL call starts the audit trail")}`,
);
// Window: first 12 entries, plus the selected row when it is below.
for (const [index, row] of journalRows.entries()) {
if (index >= 12 && index !== journalIndex) continue;
const selected = index === journalIndex && !journalDetail;
const mark = row.ok ? " " : fg("error", "!");
const mode =
row.mode === "undo"
? fg("accent", pad(row.mode, 6))
: row.ok
? fg("dim", pad(row.mode, 6))
: fg("error", pad(row.mode, 6));
lines.push(
`${selected ? fg("accent", ">") : " "} ${mark}#${pad(String(row.seq), 5)}${pad(row.ts.slice(5, 16).replace("T", " "), 11)}${mode} ${pad(row.actor, 7)}${row.sql.replaceAll(/\s+/gu, " ").slice(0, Math.max(10, width - 42))}${row.undone ? fg("muted", " · undone") : ""}${row.undoPath ? "" : row.mode !== "read" && row.mode !== "undo" ? fg("dim", " · no undo") : ""}`,
);
}
if (journalDetail) {
lines.push("", fg("accent", `#${journalDetail.seq} detail`));
for (const key of [
`sql: ${journalDetail.sql}`,
`actor: ${journalDetail.actor} · mode: ${journalDetail.mode} · ${journalDetail.durationMs}ms`,
`rows: ${journalDetail.rowsReturned} returned · ${journalDetail.rowsWritten} written`,
journalDetail.error ? `error: ${journalDetail.error}` : "",
journalDetail.spilledTo ? `spill: ${journalDetail.spilledTo}` : "",
journalDetail.undoPath ? "undo: snapshot available" : "",
]) {
if (!key) continue;
for (const part of wrapTextWithAnsi(key, Math.max(20, width - 4)))
lines.push(` ${part}`);
}
}
lines.push(
"",
fg(
"dim",
`↑↓ select · enter detail · u undo snapshot${journalRows.length ? ` · ${journalRows.length} recent` : ""}`,
),
);
return lines;
}
function renderConfirm(): string[] {
if (!confirm) return [];
return ["", ` ${fg("warning", `${confirm.text} (y/n)`)}`];
}
function render(width: number): string[] {
if (cachedLines && cachedWidth === width && cachedLines)
return cachedLines;
cachedWidth = width;
const header = [
`memory · ${store.path.replace(/^\/home\/[^/]+\//u, "~/")} · ${bytesLabel(store.sizeOverview().totalBytes)} · v${SCHEMA_VERSION}${status ? ` · ${status}` : ""} esc quit`,
];
const tabs = TAB_ORDER.map((name, index) => {
const label = `${index + 1} ${name.slice(0, 1).toUpperCase()}${name.slice(1)}`;
return name === tab
? fg("accent", `[${label}]`)
: fg("dim", ` ${label} `);
}).join("");
const body =
tab === "usage"
? renderUsage(width)
: tab === "size"
? renderSize(width)
: tab === "health"
? renderHealth(width)
: tab === "browse"
? renderBrowse(width)
: renderJournal(width);
const content = [...header, tabs, "", ...body, ...renderConfirm()].map(
(line) => truncateToWidth(line, width),
);
cachedLines = content;
return content;
}
function handleInput(data: string): void {
// pi-tui delivers bracketed paste wrapped in ESC markers; unwrap first
// so pasted digits still drive tab keys and pasted text lands cleanly.
const paste = /^\u001b\[200~([\s\S]*)\u001b\[201~$/u.exec(data);
if (paste?.[1] !== undefined) data = paste[1];
if (
matchesKey(data, "escape") &&
!browseSql &&
!journalDetail &&
!confirm
) {
if (alive) {
alive = false;
done();
}
return;
}
if (confirm) {
if (data === "y") void runConfirmed();
else if (data === "n" || matchesKey(data, "escape")) {
confirm = undefined;
invalidate();
}
tui.requestRender();
return;
}
if (matchesKey(data, "escape")) {
if (journalDetail) {
journalDetail = undefined;
invalidate();
tui.requestRender();
return;
}
if (browseSql) {
browseSql = "";
browseRows = [];
browseColumns = [];
browseDetail = undefined;
browseStatus = "enter runs read-only · ctrl+w arms one write";
invalidate();
tui.requestRender();
return;
}
}
// In browse, digits 1-5 type into the SQL editor; esc, enter, tab
// (cycle tabs), and ctrl+w remain the only global keys there.
if (matchesKey(data, "tab")) {
switchTo(tabAt((TAB_ORDER.indexOf(tab) + 1) % TAB_ORDER.length));
return;
}
if (tab !== "browse") {
const numberTab = /^[1-5]$/u.exec(data);
if (numberTab?.[0]) {
switchTo(tabAt(Number(numberTab[0]) - 1));
return;
}
if (matchesKey(data, "right")) {
switchTo(tabAt((TAB_ORDER.indexOf(tab) + 1) % TAB_ORDER.length));
return;
}
if (matchesKey(data, "left")) {
switchTo(
tabAt(
(TAB_ORDER.indexOf(tab) + TAB_ORDER.length - 1) %
TAB_ORDER.length,
),
);
return;
}
}
if (tab === "usage") {
if (data === "f") {
filterZombies = !filterZombies;
invalidate();
tui.requestRender();
return;
}
return;
}
if (tab === "health") {
if (data === "r") {
status = "re-checking";
void store.healthChecks(true).then((report) => {
health = report;
status = "";
refreshData();
tui.requestRender();
});
return;
}
if (data === "v") {
confirm = {
text: "VACUUM the database now?",
run: async () => {
try {
await runSql(store, "VACUUM", {
actor: "human",
mode: "fix",
snapshot: false,
});
status = "VACUUM done";
} catch (error) {
status =
error instanceof Error
? error.message.slice(0, 120)
: "VACUUM failed";
}
},
};
invalidate();
tui.requestRender();
return;
}
if (data === "c") {
confirm = {
text: "Checkpoint the WAL (TRUNCATE)?",
run: async () => {
try {
await runSql(store, "PRAGMA wal_checkpoint(TRUNCATE)", {
actor: "human",
mode: "fix",
snapshot: false,
});
status = "checkpoint done";
} catch (error) {
status =
error instanceof Error
? error.message.slice(0, 120)
: "checkpoint failed";
}
},
};
invalidate();
tui.requestRender();
return;
}
return;
}
if (tab === "size") return;
if (tab === "browse") {
if (matchesKey(data, "escape")) {
browseSql = "";
browseRows = [];
browseColumns = [];
browseDetail = undefined;
browseTruncated = false;
browseSpill = null;
browseStatus = "enter runs read-only · ctrl+w arms one write";
invalidate();
tui.requestRender();
return;
}
if (matchesKey(data, "return")) {
if (browseDetail !== undefined) {
browseDetail = undefined;
invalidate();
tui.requestRender();
return;
}
void executeBrowse(false);
return;
}
if (data === "\x17") {
confirm = {
text: `Run this in WRITE mode: ${browseSql.trim().slice(0, 60)}?`,
run: () => executeBrowse(true),
};
invalidate();
tui.requestRender();
return;
}
if (matchesKey(data, "up")) {
browseDetail =
browseDetail === undefined
? undefined
: Math.max(0, browseDetail - 1);
invalidate();
tui.requestRender();
return;
}
if (matchesKey(data, "down")) {
// First ↓ selects the first row; ↓ past the end stays put.
if (browseDetail === undefined) {
if (browseRows.length > 0) browseDetail = 0;
} else {
browseDetail = Math.min(browseRows.length - 1, browseDetail + 1);
}
invalidate();
tui.requestRender();
return;
}
if (matchesKey(data, "backspace") || matchesKey(data, "delete")) {
browseSql = browseSql.slice(0, -1);
invalidate();
tui.requestRender();
return;
}
// Keystrokes and paste chunks (unwrapped at entry) append; escape
// sequences belong to key handling above.
if (
!data.includes("\u001b") &&
data !== "\u007f" &&
data !== "\u0003" &&
data !== "\u0017"
) {
browseSql += data;
invalidate();
tui.requestRender();
return;
}
return;
}
if (tab === "journal") {
if (matchesKey(data, "up")) {
journalIndex = Math.max(0, journalIndex - 1);
invalidate();
tui.requestRender();
return;
}
if (matchesKey(data, "down")) {
journalIndex = Math.min(journalRows.length - 1, journalIndex + 1);
invalidate();
tui.requestRender();
return;
}
if (matchesKey(data, "return")) {
const selected = journalRows[journalIndex];
if (selected) journalDetail = selected;
invalidate();
tui.requestRender();
return;
}
if (data === "u") {
const row = journalRows[journalIndex];
if (!row) return;
const seq = row.seq;
confirm = {
text: `Undo #${seq} (restore pre-write snapshot)?`,
run: async () => {
const result = undoEntry(store, seq);
status = result.ok
? `#${row.seq} undone: ${result.restored.join(", ")}`
: `undo failed: ${result.failed.join("; ")}`;
journalRows = store.recentJournal(100);
},
};
invalidate();
tui.requestRender();
return;
}
}
}
pruneSpills(new Date());
refreshData();
const box = new Box(1, 0, (text) => text);
box.addChild({ render, invalidate: () => {} });
return {
render: (width: number) => box.render(width),
handleInput(data: string) {
if (alive) handleInput(data);
},
invalidate: () => box.invalidate(),
};
},
{
blocked: { kind: "question", message: "Inspect memory database" },
},
);
}