@bumpyclock/pi-tasque 0.1.0

package/src/session-todos/state/state-reducer.ts

@@ -0,0 +1,292 @@
+import type {
+	Task,
+	TaskAction,
+	TaskMutationParams,
+	TaskStatus,
+} from "../tool/types.js";
+import { isTransitionValid } from "./invariants.js";
+import type { TaskState } from "./state.js";
+import { detectCycle } from "./task-graph.js";
+
+export { EMPTY_STATE } from "./state.js";
+export type { TaskState } from "./state.js";
+
+export type Op =
+	| { kind: "create"; taskId: number }
+	| { kind: "update"; id: number; fromStatus: TaskStatus; toStatus: TaskStatus }
+	| { kind: "delete"; id: number; subject: string }
+	| { kind: "list"; statusFilter?: TaskStatus; includeDeleted: boolean }
+	| { kind: "get"; task: Task }
+	| { kind: "clear"; count: number }
+	| { kind: "error"; message: string };
+
+export interface ApplyResult {
+	state: TaskState;
+	op: Op;
+}
+
+function errorResult(state: TaskState, message: string): ApplyResult {
+	return { state, op: { kind: "error", message } };
+}
+
+function isValidId(id: unknown): id is number {
+	return typeof id === "number" && Number.isFinite(id);
+}
+
+function findTask(tasks: readonly Task[], id: number): Task | undefined {
+	return tasks.find((task) => task.id === id);
+}
+
+function dedupeIds(ids: readonly number[]): number[] {
+	return [...new Set(ids)];
+}
+
+function validateBlockers(
+	state: TaskState,
+	taskId: number,
+	blockerIds: readonly number[],
+	fieldName: "blockedBy" | "addBlockedBy",
+): string | undefined {
+	for (const blockerId of blockerIds) {
+		if (blockerId === taskId) return `cannot block #${taskId} on itself`;
+		const blocker = findTask(state.tasks, blockerId);
+		if (!blocker) return `${fieldName}: #${blockerId} not found`;
+		if (blocker.status === "deleted")
+			return `${fieldName}: #${blockerId} is deleted`;
+	}
+	return undefined;
+}
+
+function validateRemovals(
+	state: TaskState,
+	blockerIds: readonly number[],
+): string | undefined {
+	for (const blockerId of blockerIds) {
+		if (!findTask(state.tasks, blockerId))
+			return `removeBlockedBy: #${blockerId} not found`;
+	}
+	return undefined;
+}
+
+function mergeMetadata(
+	current: Readonly<Record<string, unknown>> | undefined,
+	patch: Readonly<Record<string, unknown>>,
+): Record<string, unknown> | undefined {
+	const merged: Record<string, unknown> = { ...(current ?? {}) };
+	for (const [key, value] of Object.entries(patch)) {
+		if (value === null) delete merged[key];
+		else merged[key] = value;
+	}
+	return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+function assignOptionalTaskFields(
+	task: Task,
+	params: TaskMutationParams,
+): void {
+	if (params.description !== undefined) task.description = params.description;
+	if (params.activeForm !== undefined) task.activeForm = params.activeForm;
+	if (params.owner !== undefined) task.owner = params.owner;
+}
+
+/**
+ * Pure reducer: (state, action, params) -> { state, op }.
+ *
+ * The reducer owns validation and returns failures as in-band error ops so tool
+ * response code can preserve the same replay snapshot shape for success/error.
+ */
+export function applyTaskMutation(
+	state: TaskState,
+	action: TaskAction,
+	params: TaskMutationParams,
+): ApplyResult {
+	switch (action) {
+		case "create": {
+			if (!params.subject?.trim()) {
+				return errorResult(state, "subject required for create");
+			}
+
+			const blockedBy = dedupeIds(params.blockedBy ?? []);
+			const blockerError = validateBlockers(
+				state,
+				state.nextId,
+				blockedBy,
+				"blockedBy",
+			);
+			if (blockerError) return errorResult(state, blockerError);
+
+			const task: Task = {
+				id: state.nextId,
+				subject: params.subject,
+				status: "pending",
+			};
+			assignOptionalTaskFields(task, params);
+			if (blockedBy.length > 0) task.blockedBy = blockedBy;
+			if (params.metadata !== undefined) task.metadata = { ...params.metadata };
+
+			const tasks = [...state.tasks, task];
+			if (detectCycle(tasks, task.id, blockedBy)) {
+				return errorResult(
+					state,
+					"blockedBy would create a cycle in the blockedBy graph",
+				);
+			}
+
+			return {
+				state: { tasks, nextId: state.nextId + 1 },
+				op: { kind: "create", taskId: task.id },
+			};
+		}
+
+		case "update": {
+			if (!isValidId(params.id))
+				return errorResult(state, "id required for update");
+			const index = state.tasks.findIndex((task) => task.id === params.id);
+			if (index === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[index];
+			if (!current) return errorResult(state, `#${params.id} not found`);
+
+			const hasMutation =
+				params.subject !== undefined ||
+				params.description !== undefined ||
+				params.activeForm !== undefined ||
+				params.status !== undefined ||
+				params.blockedBy !== undefined ||
+				params.owner !== undefined ||
+				params.metadata !== undefined ||
+				(params.addBlockedBy !== undefined && params.addBlockedBy.length > 0) ||
+				(params.removeBlockedBy !== undefined &&
+					params.removeBlockedBy.length > 0);
+			if (!hasMutation) {
+				return errorResult(state, "update requires at least one mutable field");
+			}
+
+			let nextStatus = current.status;
+			if (params.status !== undefined) {
+				if (!isTransitionValid(current.status, params.status)) {
+					return errorResult(
+						state,
+						`illegal transition ${current.status} → ${params.status}`,
+					);
+				}
+				nextStatus = params.status;
+			}
+
+			let nextBlockedBy = [...(current.blockedBy ?? [])];
+			if (params.blockedBy !== undefined) {
+				nextBlockedBy = dedupeIds(params.blockedBy);
+				const blockerError = validateBlockers(
+					state,
+					current.id,
+					nextBlockedBy,
+					"blockedBy",
+				);
+				if (blockerError) return errorResult(state, blockerError);
+			}
+
+			if (params.removeBlockedBy?.length) {
+				const removalIds = dedupeIds(params.removeBlockedBy);
+				const removalError = validateRemovals(state, removalIds);
+				if (removalError) return errorResult(state, removalError);
+				const removals = new Set(removalIds);
+				nextBlockedBy = nextBlockedBy.filter(
+					(blockerId) => !removals.has(blockerId),
+				);
+			}
+
+			if (params.addBlockedBy?.length) {
+				const additions = dedupeIds(params.addBlockedBy);
+				const blockerError = validateBlockers(
+					state,
+					current.id,
+					additions,
+					"addBlockedBy",
+				);
+				if (blockerError) return errorResult(state, blockerError);
+				for (const blockerId of additions) {
+					if (!nextBlockedBy.includes(blockerId)) nextBlockedBy.push(blockerId);
+				}
+			}
+
+			const cycleCheckTasks = state.tasks.map((task) =>
+				task.id === current.id ? { ...task, blockedBy: [] } : task,
+			);
+			if (detectCycle(cycleCheckTasks, current.id, nextBlockedBy)) {
+				return errorResult(
+					state,
+					"addBlockedBy would create a cycle in the blockedBy graph",
+				);
+			}
+
+			const updated: Task = { ...current, status: nextStatus };
+			if (params.subject !== undefined) updated.subject = params.subject;
+			assignOptionalTaskFields(updated, params);
+			if (nextBlockedBy.length > 0) updated.blockedBy = nextBlockedBy;
+			else delete updated.blockedBy;
+
+			if (params.metadata !== undefined) {
+				const nextMetadata = mergeMetadata(current.metadata, params.metadata);
+				if (nextMetadata) updated.metadata = nextMetadata;
+				else delete updated.metadata;
+			}
+
+			const tasks = [...state.tasks];
+			tasks[index] = updated;
+
+			return {
+				state: { tasks, nextId: state.nextId },
+				op: {
+					kind: "update",
+					id: updated.id,
+					fromStatus: current.status,
+					toStatus: nextStatus,
+				},
+			};
+		}
+
+		case "list":
+			return {
+				state,
+				op: {
+					kind: "list",
+					includeDeleted: params.includeDeleted === true,
+					...(params.status !== undefined
+						? { statusFilter: params.status }
+						: {}),
+				},
+			};
+
+		case "get": {
+			if (!isValidId(params.id))
+				return errorResult(state, "id required for get");
+			const task = findTask(state.tasks, params.id);
+			if (!task) return errorResult(state, `#${params.id} not found`);
+			return { state, op: { kind: "get", task } };
+		}
+
+		case "delete": {
+			if (!isValidId(params.id))
+				return errorResult(state, "id required for delete");
+			const index = state.tasks.findIndex((task) => task.id === params.id);
+			if (index === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[index];
+			if (!current) return errorResult(state, `#${params.id} not found`);
+			if (current.status === "deleted")
+				return errorResult(state, `#${params.id} is already deleted`);
+
+			const updated: Task = { ...current, status: "deleted" };
+			const tasks = [...state.tasks];
+			tasks[index] = updated;
+			return {
+				state: { tasks, nextId: state.nextId },
+				op: { kind: "delete", id: updated.id, subject: updated.subject },
+			};
+		}
+
+		case "clear":
+			return {
+				state: { tasks: [], nextId: 1 },
+				op: { kind: "clear", count: state.tasks.length },
+			};
+	}
+}

package/src/session-todos/state/state.ts

@@ -0,0 +1,69 @@
+import type { Task } from "../tool/types.js";
+
+/**
+ * Canonical in-session todo state. Reducers and replay produce this shape;
+ * store.ts is the only module-level live state cell.
+ */
+export interface TaskState {
+	tasks: Task[];
+	nextId: number;
+}
+
+export const EMPTY_STATE: TaskState = { tasks: [], nextId: 1 };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+function cloneMetadataValue(value: unknown): unknown {
+	if (value === null || typeof value !== "object") return value;
+
+	if (typeof globalThis.structuredClone === "function") {
+		try {
+			return globalThis.structuredClone(value);
+		} catch {
+			// Fall through for values structuredClone cannot copy, like functions.
+		}
+	}
+
+	if (Array.isArray(value)) return value.map(cloneMetadataValue);
+
+	if (isPlainObject(value)) {
+		const cloned: Record<string, unknown> = {};
+		for (const [key, nestedValue] of Object.entries(value)) {
+			cloned[key] = cloneMetadataValue(nestedValue);
+		}
+		return cloned;
+	}
+
+	return value;
+}
+
+function cloneMetadata(
+	metadata: Record<string, unknown>,
+): Record<string, unknown> {
+	const cloned: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(metadata)) {
+		cloned[key] = cloneMetadataValue(value);
+	}
+	return cloned;
+}
+
+export function cloneTask(task: Task): Task {
+	const cloned: Task = { ...task };
+	if (task.blockedBy !== undefined) cloned.blockedBy = [...task.blockedBy];
+	else delete cloned.blockedBy;
+	if (task.metadata !== undefined)
+		cloned.metadata = cloneMetadata(task.metadata);
+	else delete cloned.metadata;
+	return cloned;
+}
+
+export function cloneTaskState(state: TaskState): TaskState {
+	return {
+		tasks: state.tasks.map(cloneTask),
+		nextId: state.nextId,
+	};
+}

package/src/session-todos/state/store.ts

@@ -0,0 +1,37 @@
+import type { Task } from "../tool/types.js";
+import {
+	cloneTask,
+	cloneTaskState,
+	EMPTY_STATE,
+	type TaskState,
+} from "./state.js";
+
+let state: TaskState = cloneTaskState(EMPTY_STATE);
+
+/** Task snapshot accessor for UI/command readers. */
+export function getTodos(): readonly Task[] {
+	return state.tasks.map(cloneTask);
+}
+
+export function getNextId(): number {
+	return state.nextId;
+}
+
+/** State snapshot accessor for reducer callers. */
+export function getState(): TaskState {
+	return cloneTaskState(state);
+}
+
+/** Replace live state from branch replay. */
+export function replaceState(next: TaskState): void {
+	state = cloneTaskState(next);
+}
+
+/** Commit reducer output as live state. */
+export function commitState(next: TaskState): void {
+	state = cloneTaskState(next);
+}
+
+export function __resetState(): void {
+	state = cloneTaskState(EMPTY_STATE);
+}

package/src/session-todos/state/task-graph.ts

@@ -0,0 +1,58 @@
+import type { Task } from "../tool/types.js";
+
+/**
+ * Checks whether merging `newBlockedBy` into `taskId`'s blockedBy set would
+ * introduce any cycle in the todo dependency graph.
+ */
+export function detectCycle(
+	taskList: readonly Task[],
+	taskId: number,
+	newBlockedBy: readonly number[],
+): boolean {
+	const edges = new Map<number, number[]>();
+
+	for (const task of taskList) {
+		if (task.id === taskId) {
+			const merged = new Set([...(task.blockedBy ?? []), ...newBlockedBy]);
+			edges.set(task.id, [...merged]);
+		} else {
+			edges.set(task.id, [...(task.blockedBy ?? [])]);
+		}
+	}
+
+	const visiting = new Set<number>();
+	const visited = new Set<number>();
+
+	const hasCycleFrom = (node: number): boolean => {
+		if (visiting.has(node)) return true;
+		if (visited.has(node)) return false;
+
+		visiting.add(node);
+		for (const blocker of edges.get(node) ?? []) {
+			if (hasCycleFrom(blocker)) return true;
+		}
+		visiting.delete(node);
+		visited.add(node);
+		return false;
+	};
+
+	for (const node of edges.keys()) {
+		if (hasCycleFrom(node)) return true;
+	}
+	return false;
+}
+
+/**
+ * Inverts blockedBy edges: blocker id -> task ids blocked by that blocker.
+ */
+export function deriveBlocks(taskList: readonly Task[]): Map<number, number[]> {
+	const blocks = new Map<number, number[]>();
+	for (const task of taskList) {
+		for (const blockerId of task.blockedBy ?? []) {
+			const blockedTaskIds = blocks.get(blockerId) ?? [];
+			blockedTaskIds.push(task.id);
+			blocks.set(blockerId, blockedTaskIds);
+		}
+	}
+	return blocks;
+}

package/src/session-todos/todo-overlay.ts

@@ -0,0 +1,223 @@
+/**
+ * Persistent above-editor widget showing in-session todos.
+ *
+ * This class owns only widget lifecycle/rendering. Session lifecycle wiring lives
+ * outside this module so callers can decide when to bind UI, update, or hide
+ * completed tasks from previous turns.
+ */
+
+import type {
+	ExtensionUIContext,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import { type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	selectHasActive,
+	selectOverlayLayout,
+	selectShowTaskIds,
+	selectTodoCounts,
+} from "./state/selectors.js";
+import type { TaskState } from "./state/state.js";
+import { getState } from "./state/store.js";
+import { formatOverlayTaskLine, formatStatusLabel } from "./view/format.js";
+
+const WIDGET_KEY = "rpiv-todos";
+const MAX_WIDGET_LINES = 12;
+const OVERLAY_HEADING = "Todos";
+const OVERLAY_MORE = "more";
+
+type TaskSnapshot = ReturnType<TodoOverlay["getSnapshot"]>;
+type SnapshotTask = TaskSnapshot["tasks"][number];
+
+export class TodoOverlay {
+	private uiCtx: ExtensionUIContext | undefined;
+	private widgetRegistered = false;
+	private tui: TUI | undefined;
+	private completedTaskIdsPendingHide = new Set<number>();
+	private hiddenCompletedTaskIds = new Set<number>();
+	private lastNextId: number | undefined;
+
+	setUICtx(ctx: ExtensionUIContext): void {
+		if (ctx === this.uiCtx) return;
+		this.uiCtx = ctx;
+		this.widgetRegistered = false;
+		this.tui = undefined;
+	}
+
+	update(): void {
+		if (!this.uiCtx) return;
+
+		const snapshot = this.getSnapshot();
+		const visibleTasks = this.selectOverlayTasks(snapshot);
+
+		if (visibleTasks.length === 0) {
+			if (this.widgetRegistered) {
+				this.uiCtx.setWidget(WIDGET_KEY, undefined);
+				this.widgetRegistered = false;
+				this.tui = undefined;
+			}
+			return;
+		}
+
+		if (!this.widgetRegistered) {
+			this.uiCtx.setWidget(
+				WIDGET_KEY,
+				(tui, theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => this.renderWidget(theme, width),
+						invalidate: () => {
+							this.widgetRegistered = false;
+							this.tui = undefined;
+						},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
+			this.widgetRegistered = true;
+			return;
+		}
+
+		this.tui?.requestRender();
+	}
+
+	resetCompletedDisplayState(): void {
+		this.completedTaskIdsPendingHide.clear();
+		this.hiddenCompletedTaskIds.clear();
+		this.lastNextId = undefined;
+	}
+
+	hideCompletedTasksFromPreviousTurn(): void {
+		if (this.completedTaskIdsPendingHide.size === 0) return;
+		for (const taskId of this.completedTaskIdsPendingHide) {
+			this.hiddenCompletedTaskIds.add(taskId);
+		}
+		this.completedTaskIdsPendingHide.clear();
+		this.update();
+	}
+
+	dispose(): void {
+		if (this.uiCtx) this.uiCtx.setWidget(WIDGET_KEY, undefined);
+		this.widgetRegistered = false;
+		this.tui = undefined;
+		this.uiCtx = undefined;
+		this.resetCompletedDisplayState();
+	}
+
+	private getSnapshot(): TaskState {
+		const state = getState();
+		if (this.lastNextId !== undefined && state.nextId < this.lastNextId) {
+			this.resetCompletedDisplayState();
+		}
+		this.lastNextId = state.nextId;
+
+		const completedTaskIds = new Set(
+			state.tasks
+				.filter((task) => task.status === "completed")
+				.map((task) => task.id),
+		);
+		for (const taskId of this.completedTaskIdsPendingHide) {
+			if (!completedTaskIds.has(taskId)) {
+				this.completedTaskIdsPendingHide.delete(taskId);
+			}
+		}
+		for (const taskId of this.hiddenCompletedTaskIds) {
+			if (!completedTaskIds.has(taskId)) {
+				this.hiddenCompletedTaskIds.delete(taskId);
+			}
+		}
+
+		return state;
+	}
+
+	private selectOverlayTasks(snapshot: TaskSnapshot): SnapshotTask[] {
+		return snapshot.tasks.filter(
+			(task) =>
+				task.status !== "deleted" && !this.shouldHideCompletedTask(task),
+		);
+	}
+
+	private shouldHideCompletedTask(task: SnapshotTask): boolean {
+		return (
+			task.status === "completed" && this.hiddenCompletedTaskIds.has(task.id)
+		);
+	}
+
+	private renderWidget(theme: Theme, width: number): string[] {
+		const snapshot = this.getSnapshot();
+		const overlayTasks = this.selectOverlayTasks(snapshot);
+		if (overlayTasks.length === 0) return [];
+
+		const overlayState: TaskState = {
+			tasks: overlayTasks,
+			nextId: snapshot.nextId,
+		};
+		const truncate = (line: string): string =>
+			truncateToWidth(line, width, "…");
+		const counts = selectTodoCounts(overlayState);
+		const hasActive = selectHasActive(overlayState);
+		const showIds = selectShowTaskIds(overlayState);
+		const headingColor = hasActive ? "accent" : "dim";
+		const headingIcon = hasActive ? "●" : "○";
+		const headingText = `${OVERLAY_HEADING} (${counts.completed}/${counts.total})`;
+		const heading = truncate(
+			`${theme.fg(headingColor, headingIcon)} ${theme.fg(
+				headingColor,
+				headingText,
+			)}`,
+		);
+		const lines = [heading];
+		const layout = selectOverlayLayout(overlayState, MAX_WIDGET_LINES - 1);
+
+		for (const task of layout.visible) {
+			lines.push(
+				truncate(
+					`${theme.fg("dim", "├─")} ${formatOverlayTaskLine(
+						task,
+						theme,
+						showIds,
+					)}`,
+				),
+			);
+		}
+
+		const newlyDisplayedCompletedTaskIds = overlayTasks
+			.filter(
+				(task) =>
+					task.status === "completed" &&
+					!this.completedTaskIdsPendingHide.has(task.id) &&
+					!this.hiddenCompletedTaskIds.has(task.id),
+			)
+			.map((task) => task.id);
+		for (const taskId of newlyDisplayedCompletedTaskIds) {
+			this.completedTaskIdsPendingHide.add(taskId);
+		}
+
+		if (layout.hiddenCompleted === 0 && layout.truncatedTail === 0) {
+			const lastIndex = lines.length - 1;
+			lines[lastIndex] = lines[lastIndex]!.replace("├─", "└─");
+			return lines;
+		}
+
+		const totalHidden = layout.hiddenCompleted + layout.truncatedTail;
+		const overflowParts: string[] = [];
+		if (layout.hiddenCompleted > 0) {
+			overflowParts.push(
+				`${layout.hiddenCompleted} ${formatStatusLabel("completed")}`,
+			);
+		}
+		if (layout.truncatedTail > 0) {
+			overflowParts.push(
+				`${layout.truncatedTail} ${formatStatusLabel("pending")}`,
+			);
+		}
+		const summary =
+			overflowParts.length > 0
+				? `+${totalHidden} ${OVERLAY_MORE} (${overflowParts.join(", ")})`
+				: `+${totalHidden} ${OVERLAY_MORE}`;
+		lines.push(
+			truncate(`${theme.fg("dim", "└─")} ${theme.fg("dim", summary)}`),
+		);
+		return lines;
+	}
+}