@leo-alvarenga/pi-todo-list 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leo-alvarenga/pi-todo-list",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Session-aware todo list overlay for Pi: todo tool, /todos command, and a live TUI panel",
   "license": "MIT",
   "repository": "github.com/leo-alvarenga/pi-mono",
@@ -15,10 +15,10 @@
   ],
   "files": [
     "src",
+    "!src/test",
     "skills",
     "README.md",
-    "LICENSE",
-    "!src/*.test.ts"
+    "LICENSE"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -26,6 +26,9 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "dependencies": {
+    "@leo-alvarenga/pi-ext-core": "^0.3.4"
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"
@@ -33,11 +36,12 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "tsc --noEmit",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/command.ts

@@ -1,10 +1,11 @@
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 
-import { applyAction, groupByStatus } from "./core";
+import { applyAction } from "./core";
+import { groupByStatus } from "./query";
 import { REPORT_ENTRY } from "./constants";
-import type { TodoStore } from "./state";
-import type { Todo } from "./types";
+import type { SessionRecordStore } from "@leo-alvarenga/pi-ext-core";
+import type { Todo, TodoState } from "./types";
 import { getStyledTodo } from "./utils";
 
 const renderList = (todos: Todo[], theme: Theme): string => {
@@ -29,7 +30,10 @@ const renderList = (todos: Todo[], theme: Theme): string => {
   return lines.join("\n");
 };
 
-export function registerTodosCommand(pi: ExtensionAPI, store: TodoStore): void {
+export function registerTodosCommand(
+  pi: ExtensionAPI,
+  store: SessionRecordStore<TodoState>,
+): void {
   pi.registerCommand("todos", {
     description: "Show all todos grouped by status",
     handler: async (_args, ctx) => {

package/src/constants.ts

@@ -1,10 +1,12 @@
 import type { KeyId } from "@earendil-works/pi-tui";
-import { TodoStatus, TodoStatusUi } from "./types";
+import type { StatusUi } from "@leo-alvarenga/pi-ext-core";
+
+import type { TodoStatus } from "./types";
 
 /** Task statuses, in lifecycle order. All limits are hardcoded — no config files. */
 export const STATUSES = ["pending", "in-progress", "completed"] as const;
 
-export const STATUS_STYLES: Record<TodoStatus, TodoStatusUi> = {
+export const STATUS_STYLES: Record<TodoStatus, StatusUi> = {
   pending: { icon: " ", fg: "text", color: "text" },
   "in-progress": { icon: "󱥸 ", fg: "accent", color: "accent", bold: true },
   completed: { icon: " ", fg: "dim", color: "success", strikethrough: true },
@@ -27,8 +29,3 @@ export const REPORT_ENTRY = "todos.report";
 
 /** Chord that toggles the panel. Chosen in setup: free in pi's default keybindings. */
 export const PANEL_TOGGLE_CHORD: KeyId = "alt+t";
-
-export const PANEL_STATE_ICON = {
-  collapsed: "󰅂",
-  expanded: "󰅀",
-};

package/src/core.ts

@@ -1,5 +1,6 @@
 import { MAX_TEXT_LENGTH } from "./constants";
 import type { Todo, TodoAction, TodoState, TodoStatus } from "./types";
+import { wouldCreateCycle } from "./query";
 
 export type Patch = {
   text?: string;
@@ -129,37 +130,6 @@ function remove(state: TodoState, id: number): ActionResult {
   };
 }
 
-const blockedSuffix = (t: Todo, todos: Todo[]): string => {
-  const waiting = t.blockedBy.filter((b) => {
-    const bt = todos.find((x) => x.id === b);
-
-    return !bt || bt.status !== "completed";
-  });
-
-  if (waiting.length > 0) {
-    return ` (blocked by ${waiting.map((b) => `#${b}`).join(", ")})`;
-  }
-
-  return "";
-};
-
-function list(state: TodoState): ActionResult {
-  if (state.todos.length === 0) {
-    return { ok: true, state, text: "No todos" };
-  }
-
-  return {
-    state,
-    ok: true,
-    text: state.todos
-      .map(
-        (t) =>
-          `[${t.status === "completed" ? "x" : " "}] #${t.id}: ${t.text}${blockedSuffix(t, state.todos)}`,
-      )
-      .join("\n"),
-  };
-}
-
 function clear(): ActionResult {
   return {
     ok: true,
@@ -207,10 +177,6 @@ function removeMany(state: TodoState, ids: number[]): ActionResult {
   };
 }
 
-/**
- * Apply a tool action against a copy of the state.
- * Returns the new state only when validation passes; the caller commits it.
- */
 export function applyAction(
   state: TodoState,
   params: {
@@ -246,57 +212,24 @@ export function applyAction(
       return remove(state, params.id);
 
     case "list":
-      return list(state);
+      return { ...list(state), ok: true, state };
 
     case "clear":
-      return clear();
+      return clear() as any;
   }
 }
 
-/**
- * True if `changedId` can reach itself by following blockedBy edges
- * (direct, or through a chain) — i.e. the update would create a cycle.
- */
-export function wouldCreateCycle(todos: Todo[], changedId: number): boolean {
-  const adj = new Map<number, number[]>();
-  for (const t of todos) adj.set(t.id, [...t.blockedBy]);
-
-  const done = new Set<number>();
-  const visiting = new Set<number>();
-
-  const dfs = (id: number): boolean => {
-    if (visiting.has(id)) return true;
-    if (done.has(id)) return false;
-
-    visiting.add(id);
-
-    for (const dep of adj.get(id) ?? []) {
-      if (dfs(dep)) return true;
-    }
-
-    visiting.delete(id);
-    done.add(id);
-
-    return false;
-  };
-
-  return dfs(changedId);
-}
-
-export function groupByStatus(todos: Todo[]): {
-  completed: Todo[];
-  inProgress: Todo[];
-  pending: Todo[];
-} {
-  const completed: Todo[] = [];
-  const inProgress: Todo[] = [];
-  const pending: Todo[] = [];
-
-  for (const t of todos) {
-    if (t.status === "completed") completed.push(t);
-    else if (t.status === "in-progress") inProgress.push(t);
-    else pending.push(t);
+function list(state: TodoState): { text: string } {
+  if (state.todos.length === 0) {
+    return { text: "No todos" };
   }
 
-  return { completed, inProgress, pending };
+  return {
+    text: state.todos
+      .map(
+        (t) =>
+          `[${t.status === "completed" ? "x" : " "}] #${t.id}: ${t.text}`,
+      )
+      .join("\n"),
+  };
 }

package/src/index.ts

@@ -2,23 +2,29 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { registerTodosCommand } from "./command";
 import { STATE_ENTRY, WIDGET_KEY } from "./constants";
-import { TodoStore } from "./state";
+import { createTodoStore } from "./state";
 import { registerTodoTool, registerTodoCompleteAllTool } from "./tool";
-import { registerTodoWidget, refreshWidget } from "./widget";
+import { registerTodoWidget } from "./widget";
 
 export default function (pi: ExtensionAPI): void {
-  const store = new TodoStore(
-    (snapshot) => pi.appendEntry(STATE_ENTRY, snapshot),
-    (ctx) => refreshWidget(ctx, store),
+  const store = createTodoStore((snapshot) =>
+    pi.appendEntry(STATE_ENTRY, snapshot),
   );
 
+  const panelControls = registerTodoWidget(pi, store);
+
   registerTodoTool(pi, store);
   registerTodoCompleteAllTool(pi, store);
   registerTodosCommand(pi, store);
-  registerTodoWidget(pi, store);
 
-  pi.on("session_start", (_event, ctx) => store.replay(ctx));
-  pi.on("session_tree", (_event, ctx) => store.replay(ctx));
+  pi.on("session_start", (_event, ctx) => {
+    store.replay(ctx);
+    panelControls.refresh(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    store.replay(ctx);
+    panelControls.refresh(ctx);
+  });
   pi.on("session_before_compact", (_event, ctx) => store.persistSnapshot(ctx));
   pi.on("session_shutdown", (_event, ctx) => {
     if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);

package/src/query.ts

@@ -0,0 +1,73 @@
+import type { Todo, TodoState } from "./types";
+
+const blockedSuffix = (t: Todo, todos: Todo[]): string => {
+  const waiting = t.blockedBy.filter((b) => {
+    const bt = todos.find((x) => x.id === b);
+    return !bt || bt.status !== "completed";
+  });
+
+  if (waiting.length > 0) {
+    return ` (blocked by ${waiting.map((b) => `#${b}`).join(", ")})`;
+  }
+
+  return "";
+};
+
+export function list(state: TodoState): { text: string } {
+  if (state.todos.length === 0) {
+    return { text: "No todos" };
+  }
+
+  return {
+    text: state.todos
+      .map(
+        (t) =>
+          `[${t.status === "completed" ? "x" : " "}] #${t.id}: ${t.text}${blockedSuffix(t, state.todos)}`,
+      )
+      .join("\n"),
+  };
+}
+
+export function wouldCreateCycle(todos: Todo[], changedId: number): boolean {
+  const adj = new Map<number, number[]>();
+  for (const t of todos) adj.set(t.id, [...t.blockedBy]);
+
+  const done = new Set<number>();
+  const visiting = new Set<number>();
+
+  const dfs = (id: number): boolean => {
+    if (visiting.has(id)) return true;
+    if (done.has(id)) return false;
+
+    visiting.add(id);
+
+    for (const dep of adj.get(id) ?? []) {
+      if (dfs(dep)) return true;
+    }
+
+    visiting.delete(id);
+    done.add(id);
+
+    return false;
+  };
+
+  return dfs(changedId);
+}
+
+export function groupByStatus(todos: Todo[]): {
+  completed: Todo[];
+  inProgress: Todo[];
+  pending: Todo[];
+} {
+  const completed: Todo[] = [];
+  const inProgress: Todo[] = [];
+  const pending: Todo[] = [];
+
+  for (const t of todos) {
+    if (t.status === "completed") completed.push(t);
+    else if (t.status === "in-progress") inProgress.push(t);
+    else pending.push(t);
+  }
+
+  return { completed, inProgress, pending };
+}

package/src/state.ts

@@ -1,82 +1,25 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { STATE_ENTRY } from "./constants";
-import type { TodoDetails, TodoState } from "./types";
-
-/**
- * Session-scoped todo state.
- *
- * State is keyed by the active session id so forked/parallel sessions never
- * overwrite each other, and it is replayed from the session branch on every
- * session event, so it survives /reload and compaction without the extension
- * writing any of its own files.
- */
-export class TodoStore {
-  private readonly stateBySession = new Map<string, TodoState>();
-
-  constructor(
-    private readonly persist: (snapshot: TodoState) => void,
-    private readonly emitChange: (ctx: ExtensionContext) => void,
-  ) {}
-
-  private sid(ctx: ExtensionContext): string {
-    return ctx.sessionManager.getSessionId();
-  }
-
-  getState(ctx: ExtensionContext): TodoState {
-    const sid = this.sid(ctx);
-
-    let s = this.stateBySession.get(sid);
-    if (!s) this.stateBySession.set(sid, (s = { todos: [], nextId: 1 }));
-
-    return s;
-  }
-
-  /** Commit a validated snapshot: update memory, persist, refresh the panel. */
-  commit(ctx: ExtensionContext, next: TodoState): void {
-    this.stateBySession.set(this.sid(ctx), next);
-    this.persist(next);
-    this.emitChange(ctx);
-  }
+import {
+  createSessionStore,
+  type SessionRecordStore,
+} from "@leo-alvarenga/pi-ext-core";
 
-  /** Rebuild the current session's state from the session branch (no disk writes). */
-  replay(ctx: ExtensionContext): void {
-    const s = this.getState(ctx);
-    s.todos = [];
-    s.nextId = 1;
-
-    for (const entry of ctx.sessionManager.getBranch()) {
-      if (entry.type === "custom" && entry.customType === STATE_ENTRY) {
-        const d = entry.data as TodoState | undefined;
-
-        if (d) {
-          s.todos = d.todos;
-          s.nextId = d.nextId;
-        }
-
-        continue;
-      }
-
-      if (
-        entry.type === "message" &&
-        entry.message.role === "toolResult" &&
-        entry.message.toolName === "todo"
-      ) {
-        const d = entry.message.details as TodoDetails | undefined;
-
-        if (d && !d.error) {
-          s.todos = d.todos;
-          s.nextId = d.nextId;
-        }
-      }
-    }
-
-    this.emitChange(ctx);
-  }
-
-  /** Persist the latest snapshot right before compaction so it lands after the cut point. */
-  persistSnapshot(ctx: ExtensionContext): void {
-    const s = this.getState(ctx);
-    if (s.todos.length > 0) this.persist(s);
-  }
+import { STATE_ENTRY } from "./constants";
+import type { TodoState } from "./types";
+
+/** Session-scoped todo state, committed to the `todos.state` custom entry. */
+export function createTodoStore(
+  persist: (snapshot: TodoState) => void,
+  onRefresh?: (ctx: ExtensionContext) => void,
+): SessionRecordStore<TodoState> {
+  return createSessionStore<TodoState>({
+    empty: () => ({ todos: [], nextId: 1 }),
+    entryType: STATE_ENTRY,
+    snapshotOf: (entry) => entry.data as TodoState | undefined,
+    onChange: (state, ctx) => {
+      persist(state);
+      onRefresh?.(ctx);
+    },
+  });
 }

package/src/tool.ts

@@ -5,7 +5,7 @@ import { Type } from "typebox";
 
 import { STATUSES } from "./constants";
 import { applyAction } from "./core";
-import type { TodoStore } from "./state";
+import type { SessionRecordStore } from "@leo-alvarenga/pi-ext-core";
 import type { TodoDetails, TodoState } from "./types";
 
 const TodoParams = Type.Object({
@@ -38,7 +38,10 @@ const TodoParams = Type.Object({
   ),
 });
 
-export function registerTodoTool(pi: ExtensionAPI, store: TodoStore): void {
+export function registerTodoTool(
+  pi: ExtensionAPI,
+  store: SessionRecordStore<TodoState>,
+): void {
   pi.registerTool({
     name: "todo",
     label: "Todo",
@@ -106,7 +109,7 @@ export function registerTodoTool(pi: ExtensionAPI, store: TodoStore): void {
 
 export function registerTodoCompleteAllTool(
   pi: ExtensionAPI,
-  store: TodoStore,
+  store: SessionRecordStore<TodoState>,
 ): void {
   pi.registerTool({
     name: "todo_complete_all",

package/src/types.ts

@@ -1,16 +1,7 @@
-import { ThemeColor } from "@earendil-works/pi-coding-agent";
 import { STATUSES } from "./constants";
 
 export type TodoStatus = (typeof STATUSES)[number];
 
-export type TodoStatusUi = {
-  icon: string;
-  fg: ThemeColor;
-  bold?: boolean;
-  color: ThemeColor;
-  strikethrough?: boolean;
-};
-
 export interface Todo {
   id: number;
   text: string;

package/src/utils.ts

@@ -1,63 +1,14 @@
 import { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
+import { PANEL_STATE_ICON } from "@leo-alvarenga/pi-ext-core";
 
-import { Todo, TodoStatus } from "./types";
-import { MAX_PANEL_ROWS, PANEL_STATE_ICON, STATUS_STYLES } from "./constants";
+import type { Todo, TodoStatus } from "./types";
+import { MAX_PANEL_ROWS, STATUS_STYLES } from "./constants";
 
-export function getStyledTodoList(
+/** Panel header: collapsed/expanded icon plus per-status counts. */
+export function getHeader(
   todos: Todo[],
   th: Theme,
-  width: number,
-  isCollapsed?: boolean,
-): string[] {
-  const indent = (str: string, level = 1) => "  ".repeat(Math.abs(level)) + str;
-
-  const lines: string[] = [
-    truncateToWidth(
-      indent(getStyledTodoListHeader(todos, th, isCollapsed)),
-      width,
-    ),
-  ];
-
-  if (!isCollapsed) {
-    lines.push("");
-
-    if (todos.length === 0) {
-      lines.push(
-        truncateToWidth(
-          indent(th.fg("dim", "No todos yet. Ask the agent to add some!"), 2),
-          width,
-        ),
-      );
-    } else {
-      const visible = todos.slice(0, MAX_PANEL_ROWS);
-
-      for (const t of visible) {
-        lines.push(
-          truncateToWidth(indent(getStyledTodo(t, todos, th), 2), width),
-        );
-      }
-
-      if (todos.length > visible.length) {
-        lines.push(
-          truncateToWidth(
-            indent(th.fg("dim", `… +${todos.length - visible.length} more`), 3),
-            width,
-          ),
-        );
-      }
-    }
-  }
-
-  lines.push("");
-
-  return lines;
-}
-
-export function getStyledTodoListHeader(
-  todos: Todo[],
-  th: Theme,
-  isCollapsed?: boolean,
+  isCollapsed: boolean,
 ): string {
   const count = todos.reduce<Record<TodoStatus, number>>(
     (acc, t) => {
@@ -67,27 +18,50 @@ export function getStyledTodoListHeader(
     { pending: 0, "in-progress": 0, completed: 0 },
   );
 
-  const collapseState = isCollapsed ? "collapsed" : "expanded";
-
-  const statuses: TodoStatus[] = ["pending", "in-progress", "completed"];
-
-  const counter = statuses
+  const counter = (["pending", "in-progress", "completed"] as TodoStatus[])
     .map((s) => {
-      const { icon, color } = STATUS_STYLES[s] ?? STATUS_STYLES.pending;
+      const { icon, color = "text" } =
+        STATUS_STYLES[s] ?? STATUS_STYLES.pending;
 
       return th.fg(color, `${icon}${count[s] ?? 0}`);
     })
     .join(th.fg("dim", " / "));
 
-  return th.fg(
-    "accent",
-    `${PANEL_STATE_ICON[collapseState]}  Todos - ${counter}`,
-  );
+  const state = isCollapsed ? "collapsed" : "expanded";
+
+  return th.fg("accent", `${PANEL_STATE_ICON[state]} 󰄲 Todos - ${counter}`);
+}
+
+export function getSortedTodos(todos: Todo[]): Todo[] {
+  if (todos.length <= MAX_PANEL_ROWS) return todos;
+
+  const weights: Record<TodoStatus, number> = {
+    pending: 0,
+    completed: 2,
+    "in-progress": 1,
+  };
+
+  const sorted = todos.sort((a, b) => {
+    const wa = weights[a.status];
+    const wb = weights[b.status];
+
+    if (wa === wb) return a.id - b.id;
+
+    return wa - wb;
+  });
+
+  return sorted;
 }
 
+/** One panel/report row for a todo. */
 export function getStyledTodo(t: Todo, todos: Todo[], th: Theme): string {
-  const { icon, fg, bold, strikethrough, color } =
-    STATUS_STYLES[t.status] ?? STATUS_STYLES.pending;
+  const {
+    fg,
+    bold,
+    icon,
+    strikethrough,
+    color = "text",
+  } = STATUS_STYLES[t.status] ?? STATUS_STYLES.pending;
 
   const check = th.fg(color, icon);
   const id = th.fg("accent", `#${t.id}`);

package/src/widget.ts

@@ -1,76 +1,36 @@
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-  Theme,
-} from "@earendil-works/pi-coding-agent";
-
-import { PANEL_TOGGLE_CHORD, WIDGET_KEY } from "./constants";
-import type { TodoStore } from "./state";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  createPanelWidget,
+  type PanelWidgetSpec,
+  type SessionRecordStore,
+} from "@leo-alvarenga/pi-ext-core";
+
+import { MAX_PANEL_ROWS, PANEL_TOGGLE_CHORD, WIDGET_KEY } from "./constants";
 import type { TodoState } from "./types";
-import { getStyledTodoList } from "./utils";
-
-let collapsed = true;
-const hideIfEmpty = true;
-
-class TodoWidget {
-  private cachedWidth: number | undefined;
-  private cachedLines: string[] | undefined;
-
-  constructor(
-    private readonly theme: Theme,
-    private readonly snapshot: () => TodoState,
-    private readonly isCollapsed: () => boolean,
-  ) {}
-
-  render(width: number): string[] {
-    if (hideIfEmpty && this.snapshot().todos.length === 0) {
-      return [];
-    }
-
-    if (this.cachedLines !== undefined && this.cachedWidth === width) {
-      return this.cachedLines;
-    }
-
-    const lines = getStyledTodoList(
-      this.snapshot().todos,
-      this.theme,
-      width,
-      this.isCollapsed(),
-    );
-
-    this.cachedWidth = width;
-    this.cachedLines = lines;
-
-    return lines;
-  }
-
-  invalidate(): void {
-    this.cachedWidth = undefined;
-    this.cachedLines = undefined;
-  }
-}
-
-export function refreshWidget(ctx: ExtensionContext, store: TodoStore): void {
-  if (!ctx.hasUI) return;
-
-  ctx.ui.setWidget(
-    WIDGET_KEY,
-    (_tui, theme) =>
-      new TodoWidget(
-        theme,
-        () => store.getState(ctx),
-        () => collapsed,
-      ),
-  );
-}
-
-export function registerTodoWidget(pi: ExtensionAPI, store: TodoStore): void {
-  pi.registerShortcut(PANEL_TOGGLE_CHORD, {
-    description: "Toggle todos panel",
-    handler: (ctx) => {
-      collapsed = !collapsed;
-
-      refreshWidget(ctx, store);
-    },
-  });
+import { getHeader, getSortedTodos, getStyledTodo } from "./utils";
+
+export function registerTodoWidget(
+  pi: ExtensionAPI,
+  store: SessionRecordStore<TodoState>,
+) {
+  const spec: PanelWidgetSpec<TodoState> = {
+    store,
+    widgetKey: WIDGET_KEY,
+    maxRows: MAX_PANEL_ROWS,
+    toggleChord: PANEL_TOGGLE_CHORD,
+    moreLabel: (n) => `… +${n} more`,
+    emptyText: "No todos yet. Ask the agent to add some!",
+    header: (s, theme, isCollapsed) => getHeader(s.todos, theme, isCollapsed),
+
+    rows: (s, theme) =>
+      getSortedTodos(s.todos).map((t) => getStyledTodo(t, s.todos, theme)),
+
+    isEmpty: (s) =>
+      s.todos.length === 0 || s.todos.every((t) => t.status === "completed"),
+  };
+
+  const controls = createPanelWidget(pi, spec);
+  controls.register();
+
+  return controls;
 }