@pi9/todo 0.1.0 → 0.2.0

package/src/settings.ts

@@ -6,39 +6,50 @@ import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
 export type TodoWidgetPlacement = "aboveEditor" | "belowEditor" | "off";
 export type TodoToolVisibility = "all" | "set-only" | "none";
 
-export interface TodoUiSettings {
+export interface TodoSettings {
   widgetPlacement: TodoWidgetPlacement;
   maxVisibleTasks: number;
   fallbackGlyphs: boolean;
   toolVisibility: TodoToolVisibility;
+  dynamicReminders: boolean;
+  reminderMinTurns: number;
+  reminderMaxTurns: number;
+  reminderOutputTokens: number;
+  reminderMaxPerRun: number;
 }
 
-/** The portion of Pi's session context needed to load project-specific settings. */
 export interface TodoSettingsContext {
   cwd: string;
   isProjectTrusted(): boolean;
 }
 
-export interface TodoUiSettingsLoadResult {
-  settings: TodoUiSettings;
+export interface TodoSettingsLoadResult {
+  settings: TodoSettings;
   warning?: string;
 }
 
-export interface TodoUiSettingsStoreOptions {
+export interface TodoSettingsSourceOptions {
   globalSettingsPath?: string;
   projectSettingsPath?: (cwd: string) => string;
 }
 
-export const DEFAULT_TODO_UI_SETTINGS: TodoUiSettings = {
+export const DEFAULT_TODO_SETTINGS: TodoSettings = {
   widgetPlacement: "aboveEditor",
   maxVisibleTasks: 5,
   fallbackGlyphs: false,
   toolVisibility: "set-only",
+  dynamicReminders: true,
+  reminderMinTurns: 4,
+  reminderMaxTurns: 8,
+  reminderOutputTokens: 16000,
+  reminderMaxPerRun: 2,
 };
 
 const WIDGET_PLACEMENTS = new Set<TodoWidgetPlacement>(["aboveEditor", "belowEditor", "off"]);
 const TOOL_VISIBILITIES = new Set<TodoToolVisibility>(["all", "set-only", "none"]);
 
+type PositiveIntegerSetting = "reminderMinTurns" | "reminderMaxTurns" | "reminderOutputTokens" | "reminderMaxPerRun";
+
 export function getTodoGlobalSettingsPath(): string {
   return join(getAgentDir(), "todo", "settings.json");
 }
@@ -47,55 +58,37 @@ export function getTodoProjectSettingsPath(cwd: string): string {
   return join(cwd, CONFIG_DIR_NAME, "todo", "settings.json");
 }
 
-/**
- * Loads global settings and, only for a trusted project, project-local overrides.
- * Pass the event handler's `ctx` directly to `load` or `loadTodoUiSettings`.
- */
-export class TodoUiSettingsStore {
-  private readonly globalSettingsPath: string;
-  private readonly projectSettingsPath: (cwd: string) => string;
-
-  constructor(options: TodoUiSettingsStoreOptions = {}) {
-    this.globalSettingsPath = options.globalSettingsPath ?? getTodoGlobalSettingsPath();
-    this.projectSettingsPath = options.projectSettingsPath ?? getTodoProjectSettingsPath;
-  }
-
-  async load(context?: TodoSettingsContext): Promise<TodoUiSettingsLoadResult> {
-    const settings = cloneDefaults();
-    const warnings: string[] = [];
-
-    await applyFile(this.globalSettingsPath, settings, warnings);
-
-    // Pi resolves trust before session handlers run. Never read project-controlled settings unless
-    // that resolved context says the project is trusted.
-    if (context && isTrusted(context)) {
-      await applyFile(this.projectSettingsPath(context.cwd), settings, warnings);
-    }
+export async function loadTodoSettings(
+  context?: TodoSettingsContext,
+  options: TodoSettingsSourceOptions = {},
+): Promise<TodoSettingsLoadResult> {
+  const settings = defaultTodoSettings();
+  const warnings: string[] = [];
+  const globalPath = options.globalSettingsPath ?? getTodoGlobalSettingsPath();
 
-    return { settings, ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}) };
+  await applyFile(globalPath, settings, warnings);
+  if (context && isTrusted(context)) {
+    const projectPath = options.projectSettingsPath ?? getTodoProjectSettingsPath;
+    await applyFile(projectPath(context.cwd), settings, warnings);
   }
-}
 
-/** Convenience API for loading settings from a Pi session/event context. */
-export async function loadTodoUiSettings(context?: TodoSettingsContext): Promise<TodoUiSettingsLoadResult> {
-  return new TodoUiSettingsStore().load(context);
+  return loadResult(settings, warnings);
 }
 
-/** Validates an object as a complete settings input, defaulting invalid or absent fields. */
-export function normalizeTodoUiSettings(value: unknown): TodoUiSettingsLoadResult {
-  const settings = cloneDefaults();
+export function normalizeTodoSettings(value: unknown): TodoSettingsLoadResult {
+  const settings = defaultTodoSettings();
   const warnings: string[] = [];
   applySettings(value, settings, warnings);
-  return { settings, ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}) };
+  return loadResult(settings, warnings);
 }
 
-async function applyFile(path: string, settings: TodoUiSettings, warnings: string[]): Promise<void> {
+async function applyFile(path: string, settings: TodoSettings, warnings: string[]): Promise<void> {
   let raw: string;
   try {
     raw = await readFile(path, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
-      warnings.push(`Could not read todo settings at ${path}; using available defaults.`);
+      warnings.push(`Could not read todo settings at ${path}; keeping existing settings.`);
     }
     return;
   }
@@ -103,54 +96,80 @@ async function applyFile(path: string, settings: TodoUiSettings, warnings: strin
   try {
     applySettings(JSON.parse(raw) as unknown, settings, warnings);
   } catch {
-    warnings.push(`Invalid todo settings at ${path}; using available defaults.`);
+    warnings.push(`Invalid todo settings at ${path}; keeping existing settings.`);
   }
 }
 
-function applySettings(value: unknown, settings: TodoUiSettings, warnings: string[]): void {
+function applySettings(value: unknown, settings: TodoSettings, warnings: string[]): void {
   if (!isRecord(value)) {
-    warnings.push("Invalid todo settings; using available defaults.");
+    warnings.push("Invalid todo settings; using defaults.");
     return;
   }
 
   if (value.widgetPlacement !== undefined) {
-    if (WIDGET_PLACEMENTS.has(value.widgetPlacement as TodoWidgetPlacement)) {
-      settings.widgetPlacement = value.widgetPlacement as TodoWidgetPlacement;
-    } else {
-      warnings.push("Invalid todo widgetPlacement; ignoring value.");
-    }
+    if (isSetMember(WIDGET_PLACEMENTS, value.widgetPlacement)) settings.widgetPlacement = value.widgetPlacement;
+    else warnings.push("Invalid todo widgetPlacement; ignoring value.");
   }
   if (value.maxVisibleTasks !== undefined) {
-    if (Number.isInteger(value.maxVisibleTasks) && (value.maxVisibleTasks as number) > 0) {
-      settings.maxVisibleTasks = value.maxVisibleTasks as number;
-    } else {
-      warnings.push("Invalid todo maxVisibleTasks; ignoring value.");
-    }
+    if (isPositiveInteger(value.maxVisibleTasks)) settings.maxVisibleTasks = value.maxVisibleTasks;
+    else warnings.push("Invalid todo maxVisibleTasks; ignoring value.");
   }
   if (value.fallbackGlyphs !== undefined) {
-    if (typeof value.fallbackGlyphs === "boolean") {
-      settings.fallbackGlyphs = value.fallbackGlyphs;
-    } else {
-      warnings.push("Invalid todo fallbackGlyphs; ignoring value.");
-    }
+    if (typeof value.fallbackGlyphs === "boolean") settings.fallbackGlyphs = value.fallbackGlyphs;
+    else warnings.push("Invalid todo fallbackGlyphs; ignoring value.");
   }
   if (value.toolVisibility !== undefined) {
-    if (TOOL_VISIBILITIES.has(value.toolVisibility as TodoToolVisibility)) {
-      settings.toolVisibility = value.toolVisibility as TodoToolVisibility;
-    } else {
-      warnings.push("Invalid todo toolVisibility; ignoring value.");
-    }
+    if (isSetMember(TOOL_VISIBILITIES, value.toolVisibility)) settings.toolVisibility = value.toolVisibility;
+    else warnings.push("Invalid todo toolVisibility; ignoring value.");
+  }
+  if (value.dynamicReminders !== undefined) {
+    if (typeof value.dynamicReminders === "boolean") settings.dynamicReminders = value.dynamicReminders;
+    else warnings.push("Invalid todo dynamicReminders; ignoring value.");
+  }
+
+  const priorTurnRange = [settings.reminderMinTurns, settings.reminderMaxTurns] as const;
+  applyPositiveInteger(value, settings, warnings, "reminderMinTurns");
+  applyPositiveInteger(value, settings, warnings, "reminderMaxTurns");
+  if (settings.reminderMaxTurns < settings.reminderMinTurns) {
+    [settings.reminderMinTurns, settings.reminderMaxTurns] = priorTurnRange;
+    warnings.push("Invalid todo reminderMaxTurns; must be at least reminderMinTurns; ignoring reminder turn range.");
   }
+  applyPositiveInteger(value, settings, warnings, "reminderOutputTokens");
+  applyPositiveInteger(value, settings, warnings, "reminderMaxPerRun");
 }
 
-function cloneDefaults(): TodoUiSettings {
-  return { ...DEFAULT_TODO_UI_SETTINGS };
+function applyPositiveInteger(
+  value: Record<string, unknown>,
+  settings: TodoSettings,
+  warnings: string[],
+  field: PositiveIntegerSetting,
+): void {
+  const candidate = value[field];
+  if (candidate === undefined) return;
+  if (isPositiveInteger(candidate)) settings[field] = candidate;
+  else warnings.push(`Invalid todo ${field}; ignoring value.`);
+}
+
+function defaultTodoSettings(): TodoSettings {
+  return { ...DEFAULT_TODO_SETTINGS };
+}
+
+function loadResult(settings: TodoSettings, warnings: string[]): TodoSettingsLoadResult {
+  return { settings, ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}) };
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+function isPositiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function isSetMember<T extends string>(values: ReadonlySet<T>, value: unknown): value is T {
+  return typeof value === "string" && values.has(value as T);
+}
+
 function isTrusted(context: TodoSettingsContext): boolean {
   try {
     return context.isProjectTrusted();

package/src/state.ts

@@ -1,4 +1,16 @@
-import { TODO_ACTIONS, TODO_STATUSES, type TodoAction, type TodoPhase, type TodoPhaseInput, type TodoState, type TodoStatus, type TodoTransitionInput } from "./types.js";
+import {
+  TODO_ACTIONS,
+  TODO_STATUSES,
+  isTodoActionName,
+  isTodoStatus,
+  type TodoAction,
+  type TodoActionName,
+  type TodoPhase,
+  type TodoPhaseInput,
+  type TodoState,
+  type TodoStatus,
+  type TodoTransitionInput,
+} from "./types.js";
 
 export function createTodoState(): TodoState {
   return { phases: [] };
@@ -14,78 +26,117 @@ export function cloneTodoState(state: TodoState): TodoState {
 }
 
 /** Applies an action atomically without mutating the supplied state or action. */
-export function transitionTodoState(state: TodoState, action: TodoAction | unknown): TodoState {
-  assertState(state);
-  const input = record(action, "Todo action");
-  const actionName = input.action;
-  if (typeof actionName !== "string" || !(TODO_ACTIONS as readonly string[]).includes(actionName)) {
-    throw new Error(`Todo action must be one of: ${TODO_ACTIONS.join(", ")}.`);
-  }
+export function transitionTodoState(state: TodoState, value: unknown): TodoState {
+  assertTodoState(state);
+  const action = parseTodoAction(value);
 
-  const next = cloneTodoState(state);
-  switch (actionName) {
+  let next: TodoState;
+  switch (action.action) {
     case "set":
-      assertOnlyFields(input, ["action", "phases"], "set");
-      next.phases = parsePhases(input.phases).map(newPhase);
+      next = { phases: action.phases.map(newPhase) };
       break;
     case "add":
-      assertOnlyFields(input, ["action", "phases"], "add");
-      addPhases(next, parsePhases(input.phases));
+      next = addPhases(state, action.phases);
       break;
     case "transition":
-      assertOnlyFields(input, ["action", "transitions"], "transition");
-      applyTransitions(next, parseTransitions(input.transitions));
+      next = applyTransitions(state, action.transitions);
       break;
     case "view":
-      assertOnlyFields(input, ["action", "phase"], "view");
-      if (input.phase !== undefined) next.phases = [findPhase(next.phases, name(input.phase, "view phase"))];
+      next = action.phase === undefined
+        ? state
+        : { phases: [findPhase(state.phases, action.phase)] };
       break;
   }
 
-  assertState(next);
+  assertTodoState(next);
   return next;
 }
 
-export const applyTodoAction = transitionTodoState;
-
 function newPhase(input: TodoPhaseInput): TodoPhase {
-  return { name: input.name, tasks: input.tasks.map((task) => ({ name: task, status: "pending" })) };
+  return {
+    name: input.name,
+    tasks: input.tasks.map((task) => ({ name: task, status: "pending" })),
+  };
 }
 
-function addPhases(state: TodoState, inputs: TodoPhaseInput[]): void {
+function addPhases(state: TodoState, inputs: readonly TodoPhaseInput[]): TodoState {
   if (!inputs.some((phase) => phase.tasks.length > 0)) {
     throw new Error("add requires at least one task.");
   }
 
+  const existingPhases = new Map(state.phases.map((phase) => [phase.name, phase]));
   for (const input of inputs) {
-    let phase = state.phases.find((candidate) => candidate.name === input.name);
-    if (!phase) {
-      phase = { name: input.name, tasks: [] };
-      state.phases.push(phase);
-    }
-    const names = new Set(phase.tasks.map((task) => task.name));
+    const phase = existingPhases.get(input.name);
+    if (!phase) continue;
+
+    const taskNames = new Set(phase.tasks.map((task) => task.name));
     for (const task of input.tasks) {
-      if (names.has(task)) throw new Error(`Duplicate task name in phase ${input.name}: ${task}.`);
-      names.add(task);
-      phase.tasks.push({ name: task, status: "pending" });
+      if (taskNames.has(task)) throw new Error(`Duplicate task name in phase ${input.name}: ${task}.`);
+      taskNames.add(task);
     }
   }
+
+  const additions = new Map(inputs.map((phase) => [phase.name, phase.tasks]));
+  const phases = state.phases.map((phase) => {
+    const tasks = additions.get(phase.name);
+    return !tasks || tasks.length === 0
+      ? phase
+      : { ...phase, tasks: [...phase.tasks, ...tasks.map((name) => ({ name, status: "pending" as const }))] };
+  });
+
+  for (const input of inputs) {
+    if (!existingPhases.has(input.name)) phases.push(newPhase(input));
+  }
+  return { phases };
 }
 
-function applyTransitions(state: TodoState, transitions: TodoTransitionInput[]): void {
+function applyTransitions(state: TodoState, transitions: readonly TodoTransitionInput[]): TodoState {
   if (transitions.length === 0) throw new Error("transition requires at least one status change.");
-  const addressed = new Set<string>();
 
+  const statuses = new Map<string, TodoStatus>();
   for (const transition of transitions) {
-    const key = addressKey(transition.phase, transition.task);
-    if (addressed.has(key)) throw new Error(`Task may only be transitioned once per call: ${transition.phase} / ${transition.task}.`);
-    addressed.add(key);
+    const key = todoAddressKey(transition.phase, transition.task);
+    if (statuses.has(key)) {
+      throw new Error(`Task may only be transitioned once per call: ${transition.phase} / ${transition.task}.`);
+    }
 
     const phase = state.phases.find((candidate) => candidate.name === transition.phase);
     if (!phase) throw new Error(phaseNotFoundMessage(state.phases, transition.phase));
-    const task = phase.tasks.find((candidate) => candidate.name === transition.task);
-    if (!task) throw new Error(taskNotFoundMessage(phase, transition.task));
-    task.status = transition.status;
+    if (!phase.tasks.some((candidate) => candidate.name === transition.task)) {
+      throw new Error(taskNotFoundMessage(phase, transition.task));
+    }
+    statuses.set(key, transition.status);
+  }
+
+  return {
+    phases: state.phases.map((phase) => ({
+      ...phase,
+      tasks: phase.tasks.map((task) => {
+        const status = statuses.get(todoAddressKey(phase.name, task.name));
+        return status === undefined ? task : { ...task, status };
+      }),
+    })),
+  };
+}
+
+function parseTodoAction(value: unknown): TodoAction {
+  const input = record(value, "Todo action");
+  const action = actionName(input.action);
+
+  switch (action) {
+    case "set":
+    case "add":
+      assertOnlyFields(input, ["action", "phases"], action);
+      return { action, phases: parsePhases(input.phases) };
+    case "transition":
+      assertOnlyFields(input, ["action", "transitions"], action);
+      return { action, transitions: parseTransitions(input.transitions) };
+    case "view":
+      assertOnlyFields(input, ["action", "phase"], action);
+      return {
+        action,
+        ...(input.phase === undefined ? {} : { phase: name(input.phase, "view phase") }),
+      };
   }
 }
 
@@ -128,19 +179,22 @@ function name(value: unknown, label: string): string {
   return value;
 }
 
+function actionName(value: unknown): TodoActionName {
+  if (!isTodoActionName(value)) throw new Error(`Todo action must be one of: ${TODO_ACTIONS.join(", ")}.`);
+  return value;
+}
+
 function status(value: unknown, label: string): TodoStatus {
-  if (typeof value !== "string" || !(TODO_STATUSES as readonly string[]).includes(value)) {
-    throw new Error(`${label} must be one of: ${TODO_STATUSES.join(", ")}.`);
-  }
-  return value as TodoStatus;
+  if (!isTodoStatus(value)) throw new Error(`${label} must be one of: ${TODO_STATUSES.join(", ")}.`);
+  return value;
 }
 
-function assertOnlyFields(input: Record<string, unknown>, allowed: string[], label: string): void {
+function assertOnlyFields(input: Record<string, unknown>, allowed: readonly string[], label: string): void {
   const unexpected = Object.keys(input).find((key) => !allowed.includes(key));
   if (unexpected) throw new Error(`${label} does not accept field: ${unexpected}.`);
 }
 
-function assertUnique(values: string[], message: (value: string) => string): void {
+function assertUnique(values: readonly string[], message: (value: string) => string): void {
   const seen = new Set<string>();
   for (const value of values) {
     if (seen.has(value)) throw new Error(message(value));
@@ -148,13 +202,13 @@ function assertUnique(values: string[], message: (value: string) => string): voi
   }
 }
 
-function findPhase(phases: TodoPhase[], phaseName: string): TodoPhase {
+function findPhase(phases: readonly TodoPhase[], phaseName: string): TodoPhase {
   const phase = phases.find((candidate) => candidate.name === phaseName);
   if (!phase) throw new Error(phaseNotFoundMessage(phases, phaseName));
   return phase;
 }
 
-function phaseNotFoundMessage(phases: TodoPhase[], phaseName: string): string {
+function phaseNotFoundMessage(phases: readonly TodoPhase[], phaseName: string): string {
   const names = phases.map((phase) => `- ${phase.name}`).join("\n");
   return names ? `Phase not found: ${phaseName}.\n\nCurrent phases:\n${names}` : `Phase not found: ${phaseName}. The todo plan is empty.`;
 }
@@ -167,30 +221,50 @@ function taskNotFoundMessage(phase: TodoPhase, taskName: string): string {
 }
 
 export function todoAddressKey(phase: string, task: string): string {
-  return addressKey(phase, task);
+  return `${phase}\0${task}`;
 }
 
-function addressKey(phase: string, task: string): string {
-  return `${phase}\0${task}`;
+export function currentTodoPhaseIndex(phases: readonly TodoPhase[]): number {
+  const active = phases.findIndex((phase) => phase.tasks.some((task) => task.status === "in_progress"));
+  return active >= 0
+    ? active
+    : phases.findIndex((phase) => phase.tasks.some((task) => task.status === "pending"));
 }
 
-function assertState(state: TodoState): void {
-  if (!state || typeof state !== "object" || !Array.isArray(state.phases)) throw new Error("Invalid todo state.");
+export function isTodoState(value: unknown): value is TodoState {
+  try {
+    assertTodoState(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function assertTodoState(value: unknown): asserts value is TodoState {
+  if (!value || typeof value !== "object" || !Array.isArray((value as { phases?: unknown }).phases)) {
+    throw new Error("Invalid todo state.");
+  }
+
+  const state = value as { phases: unknown[] };
   const phaseNames = new Set<string>();
   let activePhase: string | undefined;
 
-  for (const phase of state.phases) {
-    if (!phase || typeof phase !== "object" || !Array.isArray(phase.tasks)) throw new Error("Invalid todo state.");
+  for (const value of state.phases) {
+    if (!value || typeof value !== "object" || !Array.isArray((value as { tasks?: unknown }).tasks)) {
+      throw new Error("Invalid todo state.");
+    }
+    const phase = value as { name?: unknown; tasks: unknown[] };
     const phaseName = name(phase.name, "phase name");
     if (phaseNames.has(phaseName)) throw new Error("Invalid todo state: duplicate phase name.");
     phaseNames.add(phaseName);
 
     const taskNames = new Set<string>();
-    for (const task of phase.tasks) {
-      if (!task || typeof task !== "object") throw new Error("Invalid todo state.");
+    for (const value of phase.tasks) {
+      if (!value || typeof value !== "object") throw new Error("Invalid todo state.");
+      const task = value as { name?: unknown; status?: unknown };
       const taskName = name(task.name, "task name");
       if (taskNames.has(taskName)) throw new Error("Invalid todo state: duplicate task name.");
-      if (!(TODO_STATUSES as readonly string[]).includes(task.status)) throw new Error("Invalid todo state.");
+      if (!isTodoStatus(task.status)) throw new Error("Invalid todo state.");
       if (task.status === "in_progress") {
         if (activePhase !== undefined && activePhase !== phaseName) {
           throw new Error("Invalid todo state: in_progress tasks must all belong to one phase.");