@pi9/todo 0.1.0

package/src/types.ts

@@ -0,0 +1,63 @@
+export const TODO_STATUSES = ["pending", "in_progress", "completed", "cancelled"] as const;
+export type TodoStatus = typeof TODO_STATUSES[number];
+
+export const TODO_ACTIONS = ["set", "add", "transition", "view"] as const;
+export type TodoActionName = typeof TODO_ACTIONS[number];
+
+export type Todo = {
+  name: string;
+  status: TodoStatus;
+};
+
+export type TodoPhase = {
+  name: string;
+  tasks: Todo[];
+};
+
+export type TodoState = {
+  phases: TodoPhase[];
+};
+
+export type TodoAddress = {
+  phase: string;
+  task: string;
+};
+
+/** Persisted with a successful tool result so session state can be restored. */
+export type TodoToolDetails = {
+  action: TodoActionName;
+  state: TodoState;
+  changedTasks: TodoAddress[];
+  completedTasks: TodoAddress[];
+};
+
+export type TodoPhaseInput = {
+  name: string;
+  tasks: string[];
+};
+
+export type TodoTransitionInput = TodoAddress & {
+  status: TodoStatus;
+};
+
+export type SetTodoAction = {
+  action: "set";
+  phases: TodoPhaseInput[];
+};
+
+export type AddTodoAction = {
+  action: "add";
+  phases: TodoPhaseInput[];
+};
+
+export type TransitionTodoAction = {
+  action: "transition";
+  transitions: TodoTransitionInput[];
+};
+
+export type ViewTodoAction = {
+  action: "view";
+  phase?: string;
+};
+
+export type TodoAction = SetTodoAction | AddTodoAction | TransitionTodoAction | ViewTodoAction;

package/src/visibility.ts

@@ -0,0 +1,20 @@
+import type { TodoToolVisibility } from "./settings.js";
+import { TODO_ACTIONS, type TodoActionName } from "./types.js";
+
+function isTodoActionName(action: unknown): action is TodoActionName {
+  return typeof action === "string" && (TODO_ACTIONS as readonly string[]).includes(action);
+}
+
+/** Returns whether a successful todo action should be shown in tool output. */
+export function shouldRenderTodoAction(action: unknown, visibility: TodoToolVisibility): boolean {
+  if (!isTodoActionName(action)) return false;
+
+  switch (visibility) {
+    case "all":
+      return true;
+    case "set-only":
+      return action === "set";
+    case "none":
+      return false;
+  }
+}

package/src/widget-component.ts

@@ -0,0 +1,57 @@
+import { wrapTextWithAnsi, type Component, type TUI } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { TodoState } from "./types.js";
+import { renderTodoWidgetLines, type TodoWidgetLayoutOptions } from "./widget-layout.js";
+
+const DROPLET_FRAMES = ["", "", "󰺕", "󰻃", ""] as const;
+const DROPLET_DURATIONS_MS = [220, 110, 80, 100, 420] as const;
+const PI_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+const PI_SPINNER_INTERVAL_MS = 80;
+
+/** A width-aware component for Pi's persistent widget area. */
+export class TodoWidgetComponent implements Component {
+  private frameIndex = 0;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(
+    private readonly state: TodoState,
+    private readonly theme: Theme | undefined,
+    private readonly options: TodoWidgetLayoutOptions = {},
+    private readonly tui?: Pick<TUI, "requestRender">,
+  ) {
+    if (tui && state.phases.some(phase => phase.tasks.some(task => task.status === "in_progress"))) {
+      this.scheduleNextFrame();
+    }
+  }
+
+  invalidate(): void { }
+
+  render(width: number): string[] {
+    const safeWidth = Math.max(1, Math.floor(width) || 1);
+    return renderTodoWidgetLines(this.state, this.theme, safeWidth, {
+      ...this.options,
+      activeMarker: this.frames[this.frameIndex],
+    }).flatMap(line => wrapTextWithAnsi(line, safeWidth));
+  }
+
+  dispose(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+
+  private get frames(): readonly string[] {
+    return this.options.fallbackGlyphs ? PI_SPINNER_FRAMES : DROPLET_FRAMES;
+  }
+
+  private scheduleNextFrame(): void {
+    const delay = this.options.fallbackGlyphs
+      ? PI_SPINNER_INTERVAL_MS
+      : DROPLET_DURATIONS_MS[this.frameIndex];
+    this.timer = setTimeout(() => {
+      this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+      this.tui?.requestRender();
+      this.scheduleNextFrame();
+    }, delay);
+  }
+}

package/src/widget-layout.ts

@@ -0,0 +1,161 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import { todoGlyph } from "./glyphs.js";
+import type { Todo, TodoPhase, TodoState } from "./types.js";
+
+export type TodoWidgetLayoutOptions = {
+  maxVisible?: number;
+  fallbackGlyphs?: boolean;
+  activeMarker?: string;
+};
+
+type ThemeLike = Partial<Pick<Theme, "bold" | "fg" | "strikethrough">>;
+
+type DisplayTask = Todo & { taskIndex: number };
+
+/**
+ * Produces compact widget rows. Every returned row is constrained to the supplied display width;
+ * the component may subsequently wrap a row when a host chooses a narrower cell.
+ */
+export function renderTodoWidgetLines(
+  state: TodoState | undefined,
+  theme: ThemeLike | undefined,
+  width: number,
+  options: TodoWidgetLayoutOptions = {},
+): string[] {
+  const safeWidth = Math.max(1, Math.floor(width) || 1);
+  const phases = Array.isArray(state?.phases) ? state.phases : [];
+  if (phases.length === 0 || !phases.some(phase => phase.tasks.length > 0)) return [];
+
+  const selectedPhaseIndex = selectPhase(phases);
+  if (selectedPhaseIndex < 0) return [];
+  const selectedPhase = phases[selectedPhaseIndex];
+  const maxVisible = boundedMaxVisible(options.maxVisible);
+  const selectedTasks = visibleTasks(selectedPhase.tasks, maxVisible);
+  const lines: string[] = [fit(toolTitle(summary(phases), theme), safeWidth)];
+
+  for (let phaseIndex = 0; phaseIndex < phases.length; phaseIndex++) {
+    const phase = phases[phaseIndex];
+    const selected = phaseIndex === selectedPhaseIndex;
+    lines.push(fit(phaseTitle(phase, phaseIndex, selected, theme), safeWidth));
+
+    if (selected) {
+      for (const task of selectedTasks) {
+        lines.push(fit(taskLine(task, theme, options.fallbackGlyphs, options.activeMarker), safeWidth));
+      }
+      const openTasks = phase.tasks.filter(task => !isTerminal(task));
+      const hidden = openTasks.length - selectedTasks.length;
+      if (hidden > 0) lines.push(fit(`    +${hidden} more`, safeWidth));
+      const terminalSummary = terminalTaskSummary(phase.tasks);
+      if (terminalSummary) {
+        const line = `    + ${terminalSummary}`;
+        lines.push(fit(theme?.fg ? theme.fg("dim", line) : line, safeWidth));
+      }
+    }
+  }
+
+  return lines;
+}
+
+/** Alias kept for callers that prefer a builder-style name. */
+export const buildTodoWidgetLines = renderTodoWidgetLines;
+
+function boundedMaxVisible(value: number | undefined): number {
+  if (!Number.isFinite(value)) return 5;
+  return Math.max(1, Math.floor(value!));
+}
+
+function summary(phases: TodoPhase[]): string {
+  const tasks = phases.flatMap(phase => phase.tasks);
+  const active = tasks.filter(isActive).length;
+  const pending = tasks.filter(task => task.status === "pending").length;
+  const completed = tasks.filter(task => task.status === "completed").length;
+  const cancelled = tasks.filter(task => task.status === "cancelled").length;
+  return [
+    "Todos",
+    ...(active ? [`${active} active`] : []),
+    ...(pending ? [`${pending} pending`] : []),
+    ...(completed ? [`${completed} completed`] : []),
+    ...(cancelled ? [`${cancelled} cancelled`] : []),
+  ].join(" · ");
+}
+
+function phaseTitle(phase: TodoPhase, phaseIndex: number, selected: boolean, theme: ThemeLike | undefined): string {
+  const title = `${phaseIndex + 1}. ${phaseSummary(phase)}`;
+  if (selected) return toolTitle(`  ${title}`, theme);
+  return theme?.fg ? theme.fg("dim", `  ${title}`) : `  ${title}`;
+}
+
+function phaseSummary(phase: TodoPhase): string {
+  const active = phase.tasks.filter(isActive).length;
+  const pending = phase.tasks.filter(task => task.status === "pending").length;
+  const completed = phase.tasks.filter(task => task.status === "completed").length;
+  const cancelled = phase.tasks.filter(task => task.status === "cancelled").length;
+  return [
+    phase.name,
+    ...(active ? [`${active} active`] : []),
+    ...(pending ? [`${pending} pending`] : []),
+    ...(completed ? [`${completed} completed`] : []),
+    ...(cancelled ? [`${cancelled} cancelled`] : []),
+  ].join(" · ");
+}
+
+function toolTitle(text: string, theme: ThemeLike | undefined): string {
+  const bold = theme?.bold ? theme.bold(text) : text;
+  return theme?.fg ? theme.fg("toolTitle", bold) : bold;
+}
+
+function visibleTasks(tasks: Todo[], maxVisible: number): DisplayTask[] {
+  const ordered = tasks
+    .map((task, taskIndex) => ({ ...task, taskIndex }))
+    .filter(task => !isTerminal(task))
+    .sort((left, right) => taskPriority(left) - taskPriority(right) || left.taskIndex - right.taskIndex);
+  const active = ordered.filter(isActive);
+  return active.length > maxVisible ? active : ordered.slice(0, maxVisible);
+}
+
+function taskLine(task: Todo, theme: ThemeLike | undefined, fallbackGlyphs = false, activeMarker?: string): string {
+  const marker = isActive(task) && activeMarker ? activeMarker : todoGlyph(task.status, fallbackGlyphs);
+  const color = task.status === "in_progress" ? "text" : task.status === "completed" ? "success" : "dim";
+  const name = (task.status === "completed" || task.status === "cancelled") && theme?.strikethrough
+    ? theme.strikethrough(task.name)
+    : task.name;
+  let line = `    ${marker} ${name}`;
+  if (isActive(task) && theme?.bold) line = theme.bold(line);
+  return theme?.fg ? theme.fg(color, line) : line;
+}
+
+function taskPriority(task: Todo): number {
+  if (isActive(task)) return 0;
+  if (task.status === "pending") return 1;
+  return 2;
+}
+
+function selectPhase(phases: TodoPhase[]): number {
+  const active = phases.findIndex(phase => phase.tasks.some(isActive));
+  if (active >= 0) return active;
+  return phases.findIndex(phase => phase.tasks.some(task => task.status === "pending"));
+}
+
+function terminalTaskSummary(tasks: Todo[]): string | undefined {
+  const completed = tasks.filter(task => task.status === "completed").length;
+  const cancelled = tasks.filter(task => task.status === "cancelled").length;
+  const parts = [
+    ...(completed ? [`${completed} complete ${completed === 1 ? "task" : "tasks"}`] : []),
+    ...(cancelled ? [`${cancelled} cancelled ${cancelled === 1 ? "task" : "tasks"}`] : []),
+  ];
+  return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+
+function isActive(task: Todo): boolean {
+  return task.status === "in_progress";
+}
+
+function isTerminal(task: Todo): boolean {
+  return task.status === "completed" || task.status === "cancelled";
+}
+
+function fit(line: string, width: number): string {
+  return visibleWidth(line) <= width ? line : truncateToWidth(line, width, "…");
+}

package/src/widget.ts

@@ -0,0 +1,57 @@
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { TodoState } from "./types.js";
+import { TodoWidgetComponent } from "./widget-component.js";
+
+export type TodoWidgetPlacement = "belowEditor" | "aboveEditor" | "off";
+
+/**
+ * Deliberately structural so this unit does not depend on the settings persistence layer.
+ * The widget-prefixed forms allow a future settings module to expose namespaced UI settings.
+ */
+export type TodoWidgetSettings = {
+  widgetPlacement?: TodoWidgetPlacement;
+  maxVisibleTasks?: number;
+  fallbackGlyphs?: boolean;
+};
+
+type WidgetComponentFactory = (tui: TUI, theme: Theme) => Component & { dispose?(): void };
+
+export type TodoWidgetContext = {
+  hasUI?: boolean;
+  ui?: {
+    notify?: (message: string, level?: "info" | "warning" | "error") => void;
+    setWidget?: {
+      (id: string, content: string[] | undefined, options?: { placement?: "belowEditor" | "aboveEditor" }): void;
+      (id: string, content: WidgetComponentFactory | undefined, options?: { placement?: "belowEditor" | "aboveEditor" }): void;
+    };
+  };
+};
+
+/** Update (or clear) the persistent todo widget without requiring the host UI at runtime. */
+export function updateTodoWidget(ctx: TodoWidgetContext | undefined, state: TodoState | undefined, settings: TodoWidgetSettings = {}): void {
+  if (!ctx?.hasUI || !ctx.ui?.setWidget) return;
+  try {
+    const placement = settings.widgetPlacement ?? "aboveEditor";
+    if (placement === "off") {
+      ctx.ui.setWidget("todo", undefined);
+      return;
+    }
+
+    const hasVisibleTasks = state?.phases.some(phase => phase.tasks.some(task =>
+      task.status === "pending" || task.status === "in_progress",
+    )) ?? false;
+    const factory: WidgetComponentFactory | undefined = hasVisibleTasks
+      ? (tui, theme) => new TodoWidgetComponent(state!, theme, {
+          maxVisible: settings.maxVisibleTasks,
+          fallbackGlyphs: settings.fallbackGlyphs,
+        }, tui)
+      : undefined;
+    ctx.ui.setWidget("todo", factory, { placement });
+  } catch (error) {
+    try {
+      ctx.ui.notify?.(`Todo widget update failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+    } catch { }
+  }
+}