@getpipher/armory-todo 0.1.0 → 0.3.0

package/src/panel.ts

@@ -0,0 +1,382 @@
+// Interactive /todo TUI panel (SPEC-3) — a Container subclass adopting the
+// @getpipher/cursor + @getpipher/vision pattern. Box tabs (Active / Parked /
+// Archive / Config), a filter Input, a SelectList, an action submenu on Enter,
+// and a SettingsList for config. Live-persist on every change. Non-TUI modes
+// fall back to ctx.ui.notify (handled by the extension, not here).
+//
+// Manual-gate: the pi-tui components need a real terminal. The pure data
+// helpers (panel-data.ts) are unit-tested; this component is verified in a
+// real pi session.
+
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  SelectList,
+  SettingsList,
+  Spacer,
+  Text,
+  matchesKey,
+  type SelectItem,
+  type Theme,
+} from "@earendil-works/pi-tui";
+import { listTodos, parkTodo, completeTodo, deleteTodo, updateTodo, type Todo, type Status } from "./todo-store.ts";
+import { restoreTodo, archiveSummary, listArchived } from "./archive.ts";
+import { loadConfig, saveConfig, type TodoConfig } from "./config.ts";
+import { healthReport } from "./health.ts";
+import { todoToItem, archiveSummaryToItems, actionsForTodo, configToSettingItems } from "./panel-data.ts";
+
+export type Box = "active" | "parked" | "archive" | "config";
+const BOXES: Box[] = ["active", "parked", "archive", "config"];
+
+export interface TodoPanelOpts {
+  theme: Theme;
+  onDone: () => void;
+  onNotify: (msg: string, type?: "info" | "warning" | "error") => void;
+}
+
+export class TodoPanel extends Container {
+  private readonly theme: Theme;
+  private readonly onDone: () => void;
+  private readonly onNotify: (msg: string, type?: "info" | "warning" | "error") => void;
+  private currentBox: Box = "active";
+  private filterInput: Input;
+  private selectList: SelectList;
+  private actionMode = false;
+  private actionList: SelectList | null = null;
+  private editMode = false;
+  private editInput: Input | null = null;
+  private editId = "";
+  private detailMode = false;
+  private detailId = "";
+  private settingsList: SettingsList | null = null;
+  private config: TodoConfig;
+  private healthFlags: string[] = [];
+
+  constructor(opts: TodoPanelOpts) {
+    super();
+    this.theme = opts.theme;
+    this.onDone = opts.onDone;
+    this.onNotify = opts.onNotify;
+    this.config = loadConfig();
+    try { this.healthFlags = healthReport().flags; } catch { /* optional */ }
+
+    const accent = (s: string) => this.theme.fg("accent", s);
+    this.addChild(new DynamicBorder(accent));
+    this.addChild(new Spacer(1));
+
+    this.filterInput = new Input();
+    this.filterInput.onEscape = () => { this.onDone(); };
+
+    this.selectList = new SelectList([], 12, {
+      selectedPrefix: (s) => this.theme.fg("accent", s),
+      selectedText: (s) => this.theme.fg("accent", s),
+      description: (s) => this.theme.fg("muted", s),
+      scrollInfo: (s) => this.theme.fg("dim", s),
+      noMatch: (s) => this.theme.fg("warning", s),
+    });
+    this.selectList.onSelect = (item) => this.onItemSelect(item);
+    this.selectList.onCancel = () => { this.onDone(); };
+
+    this.refreshList();
+    this.renderShell();
+  }
+
+  private renderShell(): void {
+    // Keep children 0 (top border) + 1 (spacer); rebuild the rest.
+    const keep = this.children.slice(0, 2);
+    this.children.length = 0;
+    this.children.push(...keep);
+    this.settingsList = null; // cleared; renderConfigBox sets it if active
+
+    const accent = (s: string) => this.theme.fg("accent", s);
+    const tabs = BOXES.map((b) => b === this.currentBox ? this.theme.fg("accent", this.theme.bold(`[${b}]`)) : this.theme.fg("dim", b)).join("  ");
+    this.addChild(new Text(accent(this.theme.bold("  TODO")) + "  " + tabs, 0, 0));
+    if (this.healthFlags.length > 0) {
+      this.addChild(new Text(this.theme.fg("warning", `  ⚠ ${this.healthFlags.length} bloat signals — see Config tab`), 0, 0));
+    }
+    this.addChild(new Spacer(1));
+    this.addChild(new Text(this.theme.fg("muted", "  filter:"), 0, 0));
+    this.addChild(this.filterInput);
+    this.addChild(new Spacer(1));
+
+    if (this.editMode && this.editInput) {
+      this.addChild(new Text(this.theme.fg("accent", `  Edit [${this.editId}]:`), 0, 0));
+      this.addChild(this.editInput);
+      this.addChild(new Text(this.theme.fg("dim", "  enter save • esc cancel"), 0, 0));
+    } else if (this.actionMode && this.actionList) {
+      this.addChild(new Text(this.theme.fg("accent", "  Action:"), 0, 0));
+      this.addChild(this.actionList);
+    } else if (this.detailMode) {
+      const all = listTodos({ status: "all", limit: 200 });
+      const t = all.find((x) => x.id === this.detailId);
+      if (!t) { this.detailMode = false; this.renderShell(); return; }
+      const proj = t.project || "no project";
+      const tags = t.tags.length ? t.tags.join(" ") : "(none)";
+      const notesText = t.notes || "(empty)";
+      this.addChild(new Text(this.theme.fg("accent", "  " + t.title), 0, 0));
+      this.addChild(new Text(this.theme.fg("muted", "  (" + t.priority + "/" + t.status + ") - " + proj + " - #" + tags), 0, 0));
+      this.addChild(new Spacer(1));
+      this.addChild(new Text(this.theme.fg("dim", "  notes:"), 0, 0));
+      this.addChild(new Text("  " + notesText, 0, 0));
+      this.addChild(new Spacer(1));
+      this.addChild(new Text(this.theme.fg("dim", "  notes: read-only - todo update <id> notes=... to edit"), 0, 0));
+    } else if (this.currentBox === "config") {
+      this.renderConfigBox();
+    } else {
+      this.addChild(this.selectList);
+    }
+
+    this.addChild(new Spacer(1));
+    this.addChild(new Text(this.theme.fg("dim", "  ↑↓ navigate • enter select/action • tab switch box • esc done"), 0, 0));
+    this.addChild(new Spacer(1));
+    this.addChild(new DynamicBorder(accent));
+    this.invalidate();
+  }
+
+  private refreshList(): void {
+    const filter = this.filterInput.getValue();
+    if (this.currentBox === "active") {
+      const todos = listTodos({ text: filter || undefined, limit: 50 });
+      this.setSelectItems(todos.map(todoToItem));
+    } else if (this.currentBox === "parked") {
+      const todos = listTodos({ status: "parked", text: filter || undefined, limit: 50 });
+      this.setSelectItems(todos.map(todoToItem));
+    } else if (this.currentBox === "archive") {
+      if (!filter) {
+        const s = archiveSummary();
+        this.setSelectItems(archiveSummaryToItems(s));
+      } else {
+        const res = listArchived({ text: filter, limit: 50 });
+        this.setSelectItems(res.items.map(todoToItem));
+      }
+    }
+  }
+
+  /** Replace the SelectList's items by reconstructing it (SelectList has no
+   *  public items setter; setFilter does fuzzy matching on the original list). */
+  private setSelectItems(items: SelectItem[]): void {
+    const wasSelected = this.selectList.getSelectedItem();
+    const fresh = new SelectList(items, 12, {
+      selectedPrefix: (s) => this.theme.fg("accent", s),
+      selectedText: (s) => this.theme.fg("accent", s),
+      description: (s) => this.theme.fg("muted", s),
+      scrollInfo: (s) => this.theme.fg("dim", s),
+      noMatch: (s) => this.theme.fg("warning", s),
+    });
+    fresh.onSelect = (item) => this.onItemSelect(item);
+    fresh.onCancel = () => { this.onDone(); };
+    if (wasSelected) {
+      const idx = items.findIndex((i) => i.value === wasSelected.value);
+      if (idx >= 0) fresh.setSelectedIndex(idx);
+    }
+    this.selectList = fresh;
+    this.renderShell();
+  }
+
+  private onItemSelect(item: SelectItem): void {
+    if (this.currentBox === "archive" && (item.value === "total" || item.value.startsWith("project:") || item.value.startsWith("month:"))) {
+      if (item.value.startsWith("project:")) {
+        this.filterInput.setValue(item.value.slice("project:".length));
+      } else if (item.value.startsWith("month:")) {
+        this.filterInput.setValue(item.value.slice("month:".length));
+      }
+      this.refreshList();
+      this.renderShell();
+      return;
+    }
+    this.openActionSubmenu(item.value);
+  }
+
+  private openActionSubmenu(id: string): void {
+    const all = listTodos({ status: "all", limit: 200 });
+    const todo = all.find((t) => t.id === id);
+    if (!todo) {
+      this.onNotify("Todo not found in the live store (archive restore: use the archive box).", "info");
+      return;
+    }
+    const acts = [{ label: "View detail", action: "view" }, ...actionsForTodo(todo)];
+    const items: SelectItem[] = acts.map((a) => ({ value: a.action, label: a.label }));
+    this.actionList = new SelectList(items, 8, {
+      selectedPrefix: (s) => this.theme.fg("accent", s),
+      selectedText: (s) => this.theme.fg("accent", s),
+      description: (s) => this.theme.fg("muted", s),
+      scrollInfo: (s) => this.theme.fg("dim", s),
+      noMatch: (s) => this.theme.fg("warning", s),
+    });
+    this.actionList.onSelect = (a) => this.executeAction(id, a.value);
+    this.actionList.onCancel = () => { this.actionMode = false; this.actionList = null; this.renderShell(); };
+    this.actionMode = true;
+    this.renderShell();
+  }
+
+  private viewDetail(id: string): void {
+    const all = listTodos({ status: "all", limit: 200 });
+    const t = all.find((x) => x.id === id);
+    if (!t) { this.onNotify("Todo not found.", "info"); return; }
+    this.detailId = id;
+    this.detailMode = true;
+    this.actionMode = false;
+    this.actionList = null;
+    this.editMode = false;
+    this.editInput = null;
+    this.renderShell();
+  }
+
+  private async executeAction(id: string, action: string): Promise<void> {
+    try {
+      switch (action) {
+        case "view": this.viewDetail(id); return;
+        case "complete": completeTodo(id); this.onNotify(`Completed ${id}`); break;
+        case "park": parkTodo(id); this.onNotify(`Parked ${id}`); break;
+        case "open": updateTodo(id, { status: "open" as Status }); this.onNotify(`Re-activated ${id}`); break;
+        case "restore": restoreTodo(id); this.onNotify(`Restored ${id}`); break;
+        case "delete": deleteTodo(id); this.onNotify(`Cancelled ${id}`); break;
+        case "edit": {
+          const all = listTodos({ status: "all", limit: 200 });
+          const t = all.find((x) => x.id === id);
+          this.editId = id;
+          this.editInput = new Input();
+          this.editInput.setValue(t?.title ?? "");
+          this.editInput.onSubmit = (value) => {
+            if (value.trim()) {
+              try { updateTodo(id, { title: value.trim() }); this.onNotify(`Edited ${id}`); }
+              catch (err) { this.onNotify((err as Error).message, "error"); }
+            }
+            this.exitEditMode();
+          };
+          this.editInput.onEscape = () => this.exitEditMode();
+          this.actionMode = false;
+          this.actionList = null;
+          this.editMode = true;
+          this.renderShell();
+          break;
+        }
+      }
+    } catch (err) {
+      this.onNotify((err as Error).message, "error");
+    }
+    this.actionMode = false;
+    this.actionList = null;
+    this.refreshList();
+    this.renderShell();
+  }
+
+  private renderConfigBox(): void {
+    const settings = configToSettingItems(this.config);
+    const sl = new SettingsList(settings, 12, {
+      label: (text, sel) => sel ? this.theme.fg("accent", this.theme.bold(text)) : text,
+      value: (text, sel) => sel ? this.theme.fg("accent", text) : this.theme.fg("muted", text),
+      description: (text) => this.theme.fg("dim", text),
+      cursor: "❯",
+      hint: (text) => this.theme.fg("dim", text),
+    },
+    (id, newValue) => {
+      this.applyConfigChange(id, newValue);
+      sl.updateValue(id, this.configValueDisplay(id));
+    },
+    () => { this.onDone(); });
+    this.settingsList = sl;
+    this.addChild(sl);
+  }
+
+  private configValueDisplay(id: string): string {
+    const c = this.config;
+    switch (id) {
+      case "defaultAgeDays": return String(c.prune.defaultAgeDays);
+      case "hardAgeDays": return String(c.prune.hardAgeDays);
+      case "activeMaxOpen": return String(c.health.activeMaxOpen);
+      case "activeStaleDays": return String(c.health.activeStaleDays);
+      case "parkedMax": return String(c.health.parkedMax);
+      case "parkedStaleDays": return String(c.health.parkedStaleDays);
+      case "archiveMax": return String(c.health.archiveMax);
+      case "archiveOldDays": return String(c.health.archiveOldDays);
+      default: return "";
+    }
+  }
+
+  private applyConfigChange(id: string, value: string): void {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return;
+    switch (id) {
+      case "defaultAgeDays": this.config.prune.defaultAgeDays = n; break;
+      case "hardAgeDays": this.config.prune.hardAgeDays = n; break;
+      case "activeMaxOpen": this.config.health.activeMaxOpen = n; break;
+      case "activeStaleDays": this.config.health.activeStaleDays = n; break;
+      case "parkedMax": this.config.health.parkedMax = n; break;
+      case "parkedStaleDays": this.config.health.parkedStaleDays = n; break;
+      case "archiveMax": this.config.health.archiveMax = n; break;
+      case "archiveOldDays": this.config.health.archiveOldDays = n; break;
+    }
+    saveConfig(this.config);
+    this.onNotify(`Config saved: ${id} = ${value}`, "info");
+  }
+
+  private exitEditMode(): void {
+    this.editMode = false;
+    this.editInput = null;
+    this.editId = "";
+    this.refreshList();
+    this.renderShell();
+  }
+
+  private switchBox(dir: 1 | -1): void {
+    const idx = BOXES.indexOf(this.currentBox);
+    const next = (idx + dir + BOXES.length) % BOXES.length;
+    this.currentBox = BOXES[next]!;
+    this.filterInput.setValue("");
+    this.actionMode = false;
+    this.actionList = null;
+    this.refreshList();
+    this.renderShell();
+  }
+
+  handleInput(data: string): void {
+    if (this.editMode && this.editInput) {
+      if (matchesKey(data, "escape") || matchesKey(data, "esc")) {
+        this.exitEditMode();
+        return;
+      }
+      this.editInput.handleInput(data);
+      this.invalidate();
+      return;
+    }
+    if (this.detailMode) {
+      if (matchesKey(data, "escape") || matchesKey(data, "esc") || matchesKey(data, "enter") || matchesKey(data, "return")) {
+        this.detailMode = false;
+        this.detailId = "";
+        this.refreshList();
+        this.renderShell();
+        return;
+      }
+      this.invalidate();
+      return;
+    }
+    if (this.actionMode && this.actionList) {
+      if (matchesKey(data, "escape") || matchesKey(data, "esc")) {
+        this.actionMode = false;
+        this.actionList = null;
+        this.renderShell();
+        return;
+      }
+      this.actionList.handleInput(data);
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, "escape") || matchesKey(data, "esc")) { this.onDone(); return; }
+    if (matchesKey(data, "tab")) { this.switchBox(1); return; }
+    if (matchesKey(data, "shift+tab")) { this.switchBox(-1); return; }
+    if (matchesKey(data, "up") || matchesKey(data, "down") || matchesKey(data, "enter") || matchesKey(data, "return")) {
+      if (this.currentBox === "config" && this.settingsList) {
+        this.settingsList.handleInput(data);
+      } else {
+        this.selectList.handleInput(data);
+      }
+      this.invalidate();
+      return;
+    }
+    this.filterInput.handleInput(data);
+    this.refreshList();
+    this.invalidate();
+  }
+}

package/src/paths.ts

@@ -0,0 +1,36 @@
+// Path resolution for the armory-todo folder layout (v2).
+//
+// All store files live under TODO_DIR (default ~/.pi/agent/todo/):
+//   todo.json          — live store (open, in_progress, parked)
+//   todo-archive.json  — sealed history (done, cancelled)
+//   todo.config.json   — prune ages + health thresholds
+//
+// The legacy v1 single file was ~/.pi/agent/todo.json; migrate.ts handles
+// moving it into the folder on first load.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DEFAULT_DIR = join(homedir(), ".pi", "agent", "todo");
+const LEGACY_PATH = join(homedir(), ".pi", "agent", "todo.json");
+
+export function getTodoDir(): string {
+  return process.env.TODO_DIR || DEFAULT_DIR;
+}
+
+export function getLivePath(): string {
+  return join(getTodoDir(), "todo.json");
+}
+
+export function getArchivePath(): string {
+  return join(getTodoDir(), "todo-archive.json");
+}
+
+export function getConfigPath(): string {
+  return join(getTodoDir(), "todo.config.json");
+}
+
+/** The pre-v2 single-file store location. Used by migrate.ts. */
+export function getLegacyPath(): string {
+  return LEGACY_PATH;
+}

package/src/todo-store.ts

@@ -1,8 +1,10 @@
 // Pure, pi-independent TODO store for armory-todo.
 //
-// A global, cross-session TODO list backed by a single JSON file on disk
-// (default ~/.pi/agent/todo.json; override with TODO_STORE_PATH for tests).
-// Deliberately NOT pi session-entries — this survives across all sessions.
+// A global, cross-session TODO list backed by a JSON file under TODO_DIR
+// (default ~/.pi/agent/todo/todo.json). The live store holds open, in_progress,
+// and parked todos; done/cancelled are moved to todo-archive.json by `prune`
+// (see archive.ts). v1 single-file stores at ~/.pi/agent/todo.json are
+// migrated into the folder on first load (see migrate.ts).
 //
 // Kept free of any pi/typebox imports so it can be unit-tested standalone.
 
@@ -14,24 +16,23 @@ import {
   renameSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-
-const DEFAULT_PATH = join(homedir(), ".pi", "agent", "todo.json");
-const STORE_PATH = process.env.TODO_STORE_PATH || DEFAULT_PATH;
+import { dirname } from "node:path";
+import { getLivePath, getTodoDir, getLegacyPath } from "./paths.ts";
+import { migrateIfNeeded, migrateV2ToV3 } from "./migrate.ts";
 
 export type Priority = "low" | "med" | "high" | "critical";
-export type Status = "open" | "in_progress" | "done" | "cancelled";
+export type Status = "open" | "in_progress" | "parked" | "done" | "cancelled";
 
 const PRIO_ORDER: Record<Priority, number> = { critical: 0, high: 1, med: 2, low: 3 };
 const PRIORITIES: Priority[] = ["low", "med", "high", "critical"];
-const STATUSES: Status[] = ["open", "in_progress", "done", "cancelled"];
+const STATUSES: Status[] = ["open", "in_progress", "parked", "done", "cancelled"];
 const PRIO_SET = new Set(PRIORITIES);
 const STATUS_SET = new Set(STATUSES);
 
 export interface Todo {
   id: string;
-  text: string;
+  title: string;       // ≤120 chars, non-empty, trimmed
+  notes: string;       // any length, may be ""
   project: string;
   tags: string[];
   priority: Priority;
@@ -43,13 +44,14 @@ export interface Todo {
 }
 
 export interface Store {
-  version: 1;
+  version: 3;
   updatedAt: string;
   todos: Todo[];
 }
 
 export interface AddInput {
-  text: string;
+  title: string;
+  notes?: string;
   project?: string;
   tags?: string[];
   priority?: Priority;
@@ -57,7 +59,8 @@ export interface AddInput {
 }
 
 export interface UpdateInput {
-  text?: string;
+  title?: string;
+  notes?: string;
   project?: string;
   tags?: string[];
   priority?: Priority;
@@ -68,6 +71,11 @@ export interface ListFilter {
   status?: Status | "all";
   project?: string;
   tag?: string;
+  text?: string;       // substring match on todo.text (case-insensitive)
+  since?: string;      // ISO date; filter createdAt >= since
+  before?: string;     // ISO date; filter createdAt < before
+  limit?: number;      // default 20
+  page?: number;       // default 1 (1-indexed)
 }
 
 export class TodoError extends Error {}
@@ -81,31 +89,53 @@ function genId(): string {
   return "td-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
 }
 
+const TITLE_MAX = 120;  // must match the constant in migrate.ts
+
+function normalizeTitle(raw: string): string {
+  const t = raw.trim();
+  if (!t) throw new TodoError("title is required");
+  if (t.length > TITLE_MAX) {
+    throw new TodoError(`title must be ≤${TITLE_MAX} chars (got ${t.length}); move detail into notes`);
+  }
+  return t;
+}
+
 function emptyStore(): Store {
-  return { version: 1, updatedAt: now(), todos: [] };
+  return { version: 3, updatedAt: now(), todos: [] };
 }
 
 export function getStorePath(): string {
-  return STORE_PATH;
+  return getLivePath();
 }
 
-/** Load the store from disk. On corruption, back up the bad file and start fresh. */
+/** Load the live store from disk. Runs v1→v2 migration first — but ONLY when
+ *  using the default TODO_DIR (not overridden by TODO_DIR env, e.g. tests).
+ *  On corruption, backs up the bad file and starts fresh. */
 export function loadStore(): Store {
-  if (!existsSync(STORE_PATH)) return emptyStore();
+  if (!process.env.TODO_DIR) {
+    migrateIfNeeded({ todoDir: getTodoDir(), legacyPath: getLegacyPath() });
+  }
+  const path = getLivePath();
+  if (!existsSync(path)) return emptyStore();
   try {
-    const raw = readFileSync(STORE_PATH, "utf8");
-    const parsed = JSON.parse(raw) as Store;
+    const raw = readFileSync(path, "utf8");
+    let parsed = JSON.parse(raw) as Store;
     if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.todos)) {
       throw new Error("invalid store shape");
     }
-    if (parsed.version !== 1) {
-      // Future: migrate. v1 only — reset on unknown version with backup.
-      throw new Error("unsupported store version: " + String(parsed.version));
+    if (parsed.version === 2) {
+      // v2 → v3: curated map + fallback, persist once so migration runs a single time.
+      const migrated = migrateV2ToV3(parsed as any) as unknown as Store;
+      saveStore(migrated);
+      return migrated;
+    }
+    if (parsed.version !== 3) {
+      throw new Error("invalid store shape");
     }
     return parsed;
   } catch {
     try {
-      renameSync(STORE_PATH, `${STORE_PATH}.bad-${Date.now()}`);
+      renameSync(path, `${path}.bad-${Date.now()}`);
     } catch {
       // best-effort backup; swallow
     }
@@ -116,16 +146,17 @@ export function loadStore(): Store {
 /** Atomic, 0600 write. */
 export function saveStore(store: Store): void {
   store.updatedAt = now();
-  const dir = dirname(STORE_PATH);
+  const path = getLivePath();
+  const dir = dirname(path);
   mkdirSync(dir, { recursive: true });
-  const tmp = `${STORE_PATH}.tmp`;
+  const tmp = `${path}.tmp`;
   writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
   try {
     chmodSync(tmp, 0o600);
   } catch {
     // some filesystems ignore mode bits; not fatal
   }
-  renameSync(tmp, STORE_PATH);
+  renameSync(tmp, path);
 }
 
 function assertPriority(p: unknown): asserts p is Priority {
@@ -147,13 +178,14 @@ function findOrFail(store: Store, id: string): Todo {
 }
 
 export function addTodo(input: AddInput): Todo {
-  const text = (input.text ?? "").trim();
-  if (!text) throw new TodoError("text is required");
+  const title = normalizeTitle(input.title);
   if (input.priority) assertPriority(input.priority);
+  const notes = (input.notes ?? "").trim();
   const store = loadStore();
   const todo: Todo = {
     id: genId(),
-    text,
+    title,
+    notes,
     project: (input.project ?? "").trim(),
     tags: (input.tags ?? []).map((t) => t.trim()).filter(Boolean),
     priority: input.priority ?? "med",
@@ -180,7 +212,13 @@ export function listTodos(filter: ListFilter = {}): Todo[] {
   }
   if (filter.project) out = out.filter((t) => t.project === filter.project);
   if (filter.tag) out = out.filter((t) => t.tags.includes(filter.tag as string));
-  return out.slice().sort((a, b) => {
+  if (filter.text) {
+    const q = filter.text.toLowerCase();
+    out = out.filter((t) => t.title.toLowerCase().includes(q) || t.notes.toLowerCase().includes(q));
+  }
+  if (filter.since) out = out.filter((t) => t.createdAt >= (filter.since as string));
+  if (filter.before) out = out.filter((t) => t.createdAt < (filter.before as string));
+  const sorted = out.slice().sort((a, b) => {
     if (a.status !== b.status) {
       // in_progress before open (actionable ordering)
       return a.status === "in_progress" ? -1 : b.status === "in_progress" ? 1 : 0;
@@ -190,16 +228,17 @@ export function listTodos(filter: ListFilter = {}): Todo[] {
     }
     return a.createdAt.localeCompare(b.createdAt);
   });
+  const limit = filter.limit ?? 20;
+  const page = filter.page ?? 1;
+  const start = (page - 1) * limit;
+  return sorted.slice(start, start + limit);
 }
 
 export function updateTodo(id: string, patch: UpdateInput): Todo {
   const store = loadStore();
   const todo = findOrFail(store, id);
-  if (patch.text !== undefined) {
-    const text = patch.text.trim();
-    if (!text) throw new TodoError("text must not be empty");
-    todo.text = text;
-  }
+  if (patch.title !== undefined) todo.title = normalizeTitle(patch.title);
+  if (patch.notes !== undefined) todo.notes = patch.notes.trim();
   if (patch.project !== undefined) todo.project = patch.project.trim();
   if (patch.tags !== undefined) todo.tags = patch.tags.map((t) => t.trim()).filter(Boolean);
   if (patch.priority !== undefined) {
@@ -219,10 +258,19 @@ export function updateTodo(id: string, patch: UpdateInput): Todo {
   return todo;
 }
 
+export function getTodo(id: string): Todo {
+  const store = loadStore();
+  return findOrFail(store, id);
+}
+
 export function completeTodo(id: string): Todo {
   return updateTodo(id, { status: "done" });
 }
 
+export function parkTodo(id: string): Todo {
+  return updateTodo(id, { status: "parked" });
+}
+
 export function deleteTodo(id: string): Todo {
   return updateTodo(id, { status: "cancelled" });
 }
@@ -245,7 +293,8 @@ export function renderOpenBlock(max = 15): string {
   const lines = shown.map((t) => {
     const tag = t.project ? ` (${t.project})` : "";
     const pin = t.status === "in_progress" ? " ⏵" : "";
-    return `- [${t.id}] (${t.priority})${pin} ${t.text}${tag}`;
+    const dot = t.notes.trim() ? " •" : "";
+    return `- [${t.id}] (${t.priority})${pin}${dot} ${t.title}${tag}`;
   });
   const overflow = todos.length > max ? `\n- … +${todos.length - max} more (use \`todo list\`)` : "";
   return `## Open TODOs (${todos.length})\n${lines.join("\n")}${overflow}\n`;