pi-session-mail 0.2.2 → 0.4.0

package/src/picker.ts

@@ -0,0 +1,285 @@
+// The `/mailbox` picker: one list of this session's mail, the filter Tab
+// (Shift+Tab backwards) cycles, and a detail screen for the selected item. It reads no files,
+// running records or clock and imports none of them: the command handler
+// passes the items, a lookup from address to label and running state, the
+// current time, the title and the starting view. It resolves on Esc, or on `d`
+// with the selected item for the handler to delete after a confirmation; the
+// handler reopens it where the user was.
+
+import { DynamicBorder, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type KeybindingsManager,
+	matchesKey,
+	type SelectItem,
+	SelectList,
+	type SelectListTheme,
+	stripTerminalSequences,
+	Text,
+	type TUI,
+} from "@earendil-works/pi-tui";
+import type { Status } from "./mail-status.ts";
+
+/** The filters Tab cycles, in order. */
+export type PickerFilter = "unread" | "awaiting" | "read" | "sent" | "all";
+const FILTERS: readonly PickerFilter[] = ["unread", "awaiting", "read", "sent", "all"];
+
+/** The most rows shown at once; `SelectList` scrolls the rest. */
+const ROW_MAX = 10;
+
+/** Room for a row's status prefix and its first line before the description column. */
+const ROW_LAYOUT = { minPrimaryColumnWidth: 32, maxPrimaryColumnWidth: 50 };
+
+const EMPTY: Record<PickerFilter, string> = {
+	unread: "No unread mail",
+	awaiting: "Nothing is waiting for a reply",
+	read: "No read mail",
+	sent: "Nothing sent",
+	all: "No mail",
+};
+
+/** What the picker shows for one item; plain values, no envelope or file path. */
+export type PickerItem = {
+	id: string;
+	/** `sent/` is mail this session sent; `new/` and `cur/` are mail it received. */
+	box: "new" | "cur" | "sent";
+	from: string;
+	to: string;
+	kind: string;
+	inReplyTo: readonly string[];
+	ts: string;
+	body: string;
+	status: Status;
+};
+
+/** What the picker knows about an address: how to name it and whether it runs. */
+export type Peer = { label: string; running: boolean };
+
+/** Everything the picker needs, all known before it opens. */
+export type PickerOptions = {
+	items: readonly PickerItem[];
+	/** The label and running state of each address, snapshotted before the picker opens. */
+	peers: ReadonlyMap<string, Peer>;
+	/** The session's name (or short id) and short address; the filter is shown after it. */
+	title: string;
+	/** The current time in ms, for relative times. */
+	now: number;
+	filter?: PickerFilter;
+	/** The item to select; when it is gone, `selectedIndex` decides instead. */
+	selectedId?: string;
+	selectedIndex?: number;
+};
+
+/** What the picker resolved: it closed, or the user chose to delete the selected item. */
+export type PickResult =
+	| { action: "close" }
+	| {
+			action: "delete";
+			/** The selected item's id and box, so the handler finds its file. */
+			id: string;
+			box: PickerItem["box"];
+			/** The first line of its body, for the confirmation. */
+			firstLine: string;
+			/** Where the list was, so the handler reopens it where the user was. */
+			filter: PickerFilter;
+			index: number;
+	  };
+
+function listTheme(theme: Theme): SelectListTheme {
+	return {
+		selectedPrefix: (text: string): string => theme.fg("accent", text),
+		selectedText: (text: string): string => theme.bold(text),
+		description: (text: string): string => theme.fg("dim", text),
+		scrollInfo: (text: string): string => theme.fg("dim", text),
+		noMatch: (text: string): string => theme.fg("dim", text),
+	};
+}
+
+/** Untrusted text with terminal escape sequences gone and line endings made `\n`. */
+const clean = (text: string): string => stripTerminalSequences(text).replace(/\r\n?/g, "\n");
+
+/** One display line from untrusted text, without newlines or other control characters. */
+const oneLine = (text: string): string =>
+	clean(text)
+		.split("\n")[0]
+		.replace(/[\p{Cc}\u2028\u2029]/gu, " ")
+		.trim();
+
+/** A body for the detail screen: escape sequences and control characters gone, line breaks kept. */
+const bodyText = (text: string): string => clean(text).replace(/[^\P{Cc}\n\t]/gu, " ");
+
+const firstLine = (body: string): string => oneLine(body) || "(no text)";
+
+/** How long ago `ts` was, as `now`, `5m ago`, `3h ago` or `2d ago`. */
+function ago(ts: string, now: number): string {
+	const at = Date.parse(ts);
+	if (!Number.isFinite(at)) return "unknown time";
+	const minutes = Math.floor(Math.max(0, now - at) / 60_000);
+	if (minutes < 1) return "now";
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	if (days < 7) return `${days}d ago`;
+	if (days < 30) return `${Math.floor(days / 7)}w ago`;
+	if (days < 365) return `${Math.floor(days / 30)}mo ago`;
+	return `${Math.floor(days / 365)}y ago`;
+}
+
+function shows(filter: PickerFilter, status: Status): boolean {
+	if (filter === "all") return true;
+	if (filter === "sent") return status === "awaiting" || status === "answered" || status === "message";
+	return status === filter;
+}
+
+/** `d` deletes read and sent mail; unread mail is refused, since deleting its file would not take it back from the model. */
+const deletable = (item: PickerItem): boolean => item.box !== "new" && item.status !== "unread";
+
+const newestFirst = (a: PickerItem, b: PickerItem): number => b.ts.localeCompare(a.ts) || a.id.localeCompare(b.id);
+
+/** A peer from the snapshot; an address the handler did not resolve is named by its short id. */
+const peerOf = (peers: ReadonlyMap<string, Peer>, address: string): Peer =>
+	peers.get(address) ?? { label: address.slice(0, 8), running: false };
+
+function row(item: PickerItem, peers: ReadonlyMap<string, Peer>, now: number, filter: PickerFilter): SelectItem {
+	const sent = item.box === "sent";
+	const other = peerOf(peers, sent ? item.to : item.from);
+	// SelectList drops descriptions at narrow widths, so required markers go in the label too.
+	const markers: string[] = [];
+	if (filter === "all" || filter === "sent") markers.push(item.status);
+	if (item.status === "awaiting") markers.push(other.running ? "running" : "closed");
+	const parts = [`${sent ? "to" : "from"} ${oneLine(other.label)}`, item.kind, ago(item.ts, now), ...markers];
+	const prefix = markers.length > 0 ? `[${markers.join(" ")}] ` : "";
+	return { value: item.id, label: `${prefix}${firstLine(item.body)}`, description: parts.join(" · ") };
+}
+
+/** The detail screen: the other session, the kind, id, absolute time, what it answers and the whole body. */
+function detailText(item: PickerItem, peers: ReadonlyMap<string, Peer>): string {
+	const sent = item.box === "sent";
+	const address = sent ? item.to : item.from;
+	const lines = [
+		`${sent ? "To" : "From"} ${oneLine(peerOf(peers, address).label)} <${address}>`,
+		`Kind ${oneLine(item.kind)}`,
+		`Id ${oneLine(item.id)}`,
+		`Sent ${new Date(item.ts).toLocaleString()}`,
+	];
+	if (item.inReplyTo.length > 0) lines.push(`In reply to ${item.inReplyTo.map(oneLine).join(", ")}`);
+	lines.push("", bodyText(item.body));
+	return lines.join("\n");
+}
+
+/** A `ctx.ui.custom` factory: the list and detail screens, till Esc closes the list. */
+export function picker(options: PickerOptions) {
+	return (tui: TUI, theme: Theme, _keybindings: KeybindingsManager, done: (result: PickResult) => void): Component => {
+		const border = new DynamicBorder((text) => theme.fg("accent", text));
+		let filter = options.filter ?? "all";
+		let screen: "list" | "detail" = "list";
+		let shown: PickerItem[] = [];
+		let detailItem: PickerItem | undefined;
+		let list: SelectList;
+
+		const build = (selectedId: string | undefined, selectedIndex: number): void => {
+			shown = rowsFor(options.items, filter);
+			list = buildList(options, theme, filter, shown, selectedId, selectedIndex);
+			list.onSelect = (item: SelectItem): void => {
+				detailItem = shown.find((candidate) => candidate.id === item.value);
+				if (detailItem !== undefined) screen = "detail";
+			};
+			list.onCancel = (): void => done({ action: "close" });
+		};
+		build(options.selectedId, options.selectedIndex ?? 0);
+
+		const handleListInput = (data: string): void => {
+			const next = nextFilter(filter, data);
+			if (next !== undefined) {
+				filter = next;
+				build(undefined, 0);
+				return;
+			}
+			const result = data === "d" ? deletion(shown, list, filter) : undefined;
+			if (result !== undefined) done(result);
+			else if (data !== "d") list.handleInput(data);
+		};
+
+		return {
+			render(width: number): string[] {
+				const title = oneLine(`${options.title} · ${filter}`);
+				// The all and sent views mix statuses, so the hint follows the selected row, not the filter.
+				const selected = shown.find((item) => item.id === list.getSelectedItem()?.value);
+				const deletableNow = selected !== undefined && deletable(selected);
+				const hint =
+					screen === "detail" ? "esc back" : `tab filter · enter open${deletableNow ? " · d delete" : ""} · esc close`;
+				return [
+					...border.render(width),
+					...new Text(theme.fg("accent", theme.bold(title)), 0, 0).render(width),
+					...(screen === "detail" && detailItem !== undefined
+						? new Text(detailText(detailItem, options.peers), 0, 0).render(width)
+						: listLines(width, shown, list, filter, theme)),
+					...new Text(theme.fg("dim", hint), 0, 0).render(width),
+					...border.render(width),
+				];
+			},
+			invalidate(): void {
+				list.invalidate();
+			},
+			handleInput(data: string): void {
+				if (screen === "detail") {
+					if (matchesKey(data, "escape")) screen = "list";
+				} else handleListInput(data);
+				tui.requestRender();
+			},
+		};
+	};
+}
+
+/** The filter Tab or Shift+Tab moves to from `filter`; undefined for any other key. */
+function nextFilter(filter: PickerFilter, data: string): PickerFilter | undefined {
+	let step = 0;
+	if (matchesKey(data, "tab")) step = 1;
+	else if (matchesKey(data, "shift+tab")) step = -1;
+	else return undefined;
+	return FILTERS[(FILTERS.indexOf(filter) + step + FILTERS.length) % FILTERS.length];
+}
+
+/** The items `filter` shows, newest first. */
+const rowsFor = (items: readonly PickerItem[], filter: PickerFilter): PickerItem[] =>
+	items.filter((item) => shows(filter, item.status)).sort(newestFirst);
+
+/** A list of `items`, with the selection restored by id when it is there and by index otherwise. */
+function buildList(
+	options: PickerOptions,
+	theme: Theme,
+	filter: PickerFilter,
+	items: PickerItem[],
+	selectedId: string | undefined,
+	selectedIndex: number,
+): SelectList {
+	const list = new SelectList(
+		items.map((item) => row(item, options.peers, options.now, filter)),
+		ROW_MAX,
+		listTheme(theme),
+		ROW_LAYOUT,
+	);
+	const found = selectedId === undefined ? -1 : items.findIndex((item) => item.id === selectedId);
+	list.setSelectedIndex(found >= 0 ? found : Math.max(0, selectedIndex));
+	return list;
+}
+
+/** The list, or the note that the filter is empty. */
+function listLines(
+	width: number,
+	shown: readonly PickerItem[],
+	list: SelectList,
+	filter: PickerFilter,
+	theme: Theme,
+): string[] {
+	return shown.length > 0 ? list.render(width) : new Text(theme.fg("muted", `  ${EMPTY[filter]}`), 0, 0).render(width);
+}
+
+/** What `d` resolves with: the selected item when it may be deleted, otherwise undefined. */
+function deletion(shown: readonly PickerItem[], list: SelectList, filter: PickerFilter): PickResult | undefined {
+	const index = shown.findIndex((item) => item.id === list.getSelectedItem()?.value);
+	const item = shown[index];
+	if (item === undefined || !deletable(item)) return undefined;
+	return { action: "delete", id: item.id, box: item.box, firstLine: firstLine(item.body), filter, index };
+}

package/src/store.ts

@@ -8,7 +8,9 @@
 import { randomUUID } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
+
+import { type MailFile, mailStatus } from "./mail-status.ts";
 
 /** What an envelope is: answered at settle, waited on, plain, or an answer. */
 export type Kind = "request" | "ask" | "message" | "reply";
@@ -137,6 +139,15 @@ function isFile(path: string): boolean {
 	}
 }
 
+/** A real directory: `lstat`, so a symlink to one is not. False when there is nothing there. */
+function isDirectory(path: string): boolean {
+	try {
+		return lstatSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
 /** `.json` names in `box` that are regular files, in readdir order. */
 function jsonFiles(address: string, box: Box): string[] {
 	const dir = boxPath(address, box);
@@ -170,28 +181,39 @@ export type SentCopy = { envelope: Envelope; path: string };
 
 const isHops = (value: unknown): value is number => typeof value === "number" && Number.isInteger(value) && value >= 0;
 
+/** The request ids an envelope answers; throws when the list is not a short list of strings. */
+function replyIds(value: unknown): string[] {
+	if (!Array.isArray(value) || !value.every((id) => typeof id === "string"))
+		throw new Error("in_reply_to is not a list of ids");
+	if (value.length > MAX_REPLY_IDS) throw new Error(`in_reply_to names more than ${MAX_REPLY_IDS} requests`);
+	return value;
+}
+
 /**
- * Parse an envelope file; throws when it is not a well-formed envelope from a
+ * Parse an envelope value; throws when it is not a well-formed envelope from a
  * valid address. An envelope written before `kind` and `hops` existed is read
  * as a reply when it answers something and as a request otherwise, with hops 0.
  * A `kind` this version does not know is read as `message`, so mail from a
  * newer copy is delivered rather than stranded; the original value is dropped.
  */
-export function readEnvelope(path: string): Envelope {
-	const value = JSON.parse(readFileSync(path, "utf8")) as Partial<Envelope>;
+function parseEnvelope(value: unknown): Envelope {
 	if (typeof value !== "object" || value === null) throw new Error("not an object");
-	if (typeof value.id !== "string" || value.id === "") throw new Error("missing id");
-	if (!isAddress(value.from)) throw new Error(`invalid from address ${JSON.stringify(value.from)}`);
-	if (!Array.isArray(value.in_reply_to) || !value.in_reply_to.every((id) => typeof id === "string"))
-		throw new Error("in_reply_to is not a list of ids");
-	if (value.in_reply_to.length > MAX_REPLY_IDS)
-		throw new Error(`in_reply_to names more than ${MAX_REPLY_IDS} requests`);
-	if (typeof value.body !== "string") throw new Error("missing body");
-	if (value.kind === undefined) value.kind = value.in_reply_to.length > 0 ? "reply" : "request";
-	else if (!KINDS.includes(value.kind)) value.kind = "message";
-	if (value.hops === undefined) value.hops = 0;
-	else if (!isHops(value.hops)) throw new Error(`invalid hops ${JSON.stringify(value.hops)}`);
-	return value as Envelope;
+	// Copy so the raw parsed fields stay as written for `diskCounts`.
+	const envelope = { ...value } as Partial<Envelope>;
+	if (typeof envelope.id !== "string" || envelope.id === "") throw new Error("missing id");
+	if (!isAddress(envelope.from)) throw new Error(`invalid from address ${JSON.stringify(envelope.from)}`);
+	envelope.in_reply_to = replyIds(envelope.in_reply_to);
+	if (typeof envelope.body !== "string") throw new Error("missing body");
+	if (envelope.kind === undefined) envelope.kind = envelope.in_reply_to.length > 0 ? "reply" : "request";
+	else if (!KINDS.includes(envelope.kind)) envelope.kind = "message";
+	if (envelope.hops === undefined) envelope.hops = 0;
+	else if (!isHops(envelope.hops)) throw new Error(`invalid hops ${JSON.stringify(envelope.hops)}`);
+	return envelope as Envelope;
+}
+
+/** Parse an envelope file; throws when it is not a well-formed envelope. */
+export function readEnvelope(path: string): Envelope {
+	return parseEnvelope(JSON.parse(readFileSync(path, "utf8")));
 }
 
 /**
@@ -226,31 +248,129 @@ export function findSent(address: string, ids: readonly string[]): Map<string, S
 	return found;
 }
 
-function envelopesIn(address: string, box: Box): Partial<Envelope>[] {
+/**
+ * The same lookup as `findSent`, for deletion: an unreadable `sent/` or a
+ * matching copy that cannot be read throws, because deleting a reply whose
+ * requests stayed behind would make them reappear as awaiting. A missing
+ * `sent/` holds no copies.
+ */
+function sentCopiesForDeletion(address: string, ids: readonly string[]): Map<string, SentCopy> {
+	const found = new Map<string, SentCopy>();
+	if (ids.length === 0) return found;
+	const dir = boxPath(address, "sent");
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return found;
+		throw err;
+	}
+	if (!isDirectory(dir))
+		throw new Error(`refusing to delete sent copies through ${JSON.stringify(dir)}: not a real directory`);
+	for (const name of names) {
+		const id = ids.find((candidate) => name.endsWith(`-${candidate}.json`));
+		if (id === undefined || found.has(id)) continue;
+		const path = join(dir, name);
+		if (!isFile(path)) continue;
+		const envelope = readEnvelope(path);
+		if (envelope.id === id) found.set(id, { envelope, path });
+	}
+	return found;
+}
+
+/**
+ * Delete one mail file from this session's `cur/` or `sent/`, refusing any path
+ * outside those two boxes so a file still in `new/` cannot be taken from the
+ * model. The session folder and the box must be real directories, not symlinks,
+ * so the delete stays inside this mailbox however the path is spelled, and the
+ * file itself must be a regular file or a symlink, which is unlinked without
+ * its target. A `cur/` envelope that answers requests (`in_reply_to`) also
+ * loses this session's `sent/` copies of them, so they do not reappear as
+ * awaiting; a `sent/` that cannot be read throws before anything is removed.
+ */
+export function deleteMail(address: string, path: string): void {
+	const parent = dirname(path);
+	const cur = boxPath(address, "cur");
+	if (parent !== cur && parent !== boxPath(address, "sent"))
+		throw new Error(`refusing to delete mail outside cur/ or sent/: ${JSON.stringify(path)}`);
+	for (const dir of [join(mailRoot(), address), parent])
+		if (!isDirectory(dir)) throw new Error(`refusing to delete through ${JSON.stringify(dir)}: not a real directory`);
+	let stats: ReturnType<typeof lstatSync>;
+	try {
+		stats = lstatSync(path);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return; // already gone
+		throw err;
+	}
+	if (!stats.isFile() && !stats.isSymbolicLink())
+		throw new Error(`refusing to delete ${JSON.stringify(path)}: not a file`);
+	// Copies first, so an unlink that throws keeps the reply the picker was on.
+	const copies =
+		parent === cur && stats.isFile()
+			? [...sentCopiesForDeletion(address, readEnvelope(path).in_reply_to).values()]
+			: [];
+	for (const copy of copies) rmSync(copy.path, { force: true });
+	rmSync(path, { force: true });
+}
+
+/** Every regular `.json` file in `box`, with its path, its parsed JSON and the envelope when valid. */
+function envelopesIn(
+	address: string,
+	box: Box,
+): { path: string; parsed?: unknown; envelope?: Envelope; error?: string }[] {
 	const dir = boxPath(address, box);
-	const out: Partial<Envelope>[] = [];
+	const out: { path: string; parsed?: unknown; envelope?: Envelope; error?: string }[] = [];
 	for (const name of jsonFiles(address, box)) {
+		const path = join(dir, name);
+		let parsed: unknown;
+		let envelope: Envelope | undefined;
+		let error: string | undefined;
 		try {
-			out.push(JSON.parse(readFileSync(join(dir, name), "utf8")));
-		} catch {
-			out.push({});
+			parsed = JSON.parse(readFileSync(path, "utf8"));
+		} catch (err) {
+			error = (err as Error).message;
+		}
+		if (error === undefined) {
+			try {
+				const valid = parseEnvelope(parsed);
+				// The picker shows `to` and sorts by `ts`; delivery does not need them, so only this reader requires them.
+				if (!isAddress(valid.to)) throw new Error(`invalid to address ${JSON.stringify(valid.to)}`);
+				if (typeof valid.ts !== "string") throw new Error("missing ts");
+				envelope = valid;
+			} catch (err) {
+				error = (err as Error).message;
+			}
 		}
+		out.push({ path, parsed, envelope, error });
 	}
 	return out;
 }
 
+/** One file in a session's mailbox: its box, its path, and the envelope it holds when valid. */
+export type InboxFile = MailFile<Envelope> & { path: string; error?: string };
+
+/** Every regular file in this session's `new/`, `cur/` and `sent/`, each with its box and path. */
+export function readMailbox(address: string): InboxFile[] {
+	const out: InboxFile[] = [];
+	for (const box of ["new", "cur", "sent"] as const)
+		for (const file of envelopesIn(address, box)) out.push({ box, ...file });
+	return out;
+}
+
 /**
- * Counts derived from disk: files still in `new/`, envelopes in `cur/`, and
- * requests (not messages) in `sent/` that no envelope in `cur/` answers.
+ * Counts derived from disk: files still in `new/`, files in `cur/`, and
+ * requests (not messages) in `sent/` with a string id that no `cur/` file names
+ * in its `in_reply_to`. It counts the raw parsed JSON, as older copies did, so
+ * sessions running either version agree.
  */
 export function diskCounts(address: string): { unclaimed: number; read: number; awaiting: number } {
-	const cur = envelopesIn(address, "cur");
-	const answered = new Set(cur.flatMap((e) => (Array.isArray(e.in_reply_to) ? e.in_reply_to : [])));
-	// A message expects no answer, so it never counts as awaiting one.
-	const awaiting = envelopesIn(address, "sent").filter(
-		(e) => typeof e.id === "string" && e.kind !== "message" && !answered.has(e.id),
-	).length;
-	return { unclaimed: listNew(address).length, read: cur.length, awaiting };
+	const files = readMailbox(address);
+	const statuses = mailStatus(files, new Set());
+	return {
+		unclaimed: files.filter((file) => file.box === "new").length,
+		read: files.filter((file) => file.box === "cur").length,
+		awaiting: statuses.filter((file) => file.status === "awaiting").length,
+	};
 }
 
 // ---------------------------------------------------------------------------
@@ -282,14 +402,6 @@ const RUNNING = "running";
 /** A folder being pruned is first renamed to this, which is no address, so a send makes a fresh folder. */
 const ASIDE = /^\.pruning\.([A-Za-z0-9_-]+)\.[0-9a-f-]{36}$/;
 
-const isDirectory = (path: string): boolean => {
-	try {
-		return lstatSync(path).isDirectory();
-	} catch {
-		return false;
-	}
-};
-
 /** Names in `aside/<box>` when it is a real directory; a symlink or file there lists nothing. Undefined when it cannot be listed. */
 const boxNames = (aside: string, box: Box): string[] | undefined =>
 	isDirectory(join(aside, box)) ? namesIn(join(aside, box)) : [];