@fyeeme/pi-todo 1.0.0

package/src/commands.ts

@@ -0,0 +1,457 @@
+/**
+ * pi-todo — /todo command.
+ *
+ * Ported from oh-my-pi `todo-command-controller.ts` (+ its ACP helper in
+ * slash-commands/helpers/todo.ts): view, edit, copy, export, import, append,
+ * start, done, drop, rm, help — with quote-aware tokenizing, fuzzy
+ * task/phase matching, and the developer system-reminder injection that tells
+ * the agent the user manually modified the list.
+ *
+ * Host-internal surfaces map to pi:
+ *   $EDITOR round-trip      → ctx.ui.editor (prefilled Markdown)
+ *   clipboard copy          → printed (extension API has no clipboard write;
+ *                             mirrors omp's own ACP fallback text)
+ *   developer message       → pi.sendMessage display:false (custom role)
+ *   user_todo_edit entry    → "todo-phases" snapshot (pi-todo's documented
+ *                             entry contract, read back by restore and
+ *                             pi-goal's todo bridge)
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+	type TodoItem,
+	applyOpsToPhases,
+	type TodoPhase,
+	markdownToPhases,
+	phasesToMarkdown,
+	resolveTodoMarkdownPath,
+} from "./state.ts";
+
+export interface TodoCommandDeps {
+	getPhases(): TodoPhase[];
+	setPhases(phases: TodoPhase[]): void;
+	persist(phases: TodoPhase[]): void;
+	broadcast(phases: TodoPhase[]): void;
+	/** Latest event context so the reminder can reach the agent mid-session. */
+	sendHiddenMessage?(content: string): void;
+}
+
+const USAGE = [
+	"Usage: /todo <verb> [args]",
+	"  /todo                              Show current todos",
+	"  /todo edit                         Open todos in the editor (Markdown round-trip)",
+	"  /todo copy                         Print todos as Markdown",
+	"  /todo export [<path>]              Write todos to file (default: TODO.md)",
+	"  /todo import [<path>]              Replace todos from file (default: TODO.md)",
+	"  /todo append [<phase>] <task...>   Append a task; phase fuzzy-matched or auto-created",
+	"  /todo start  <task>                Mark task in_progress (fuzzy content match)",
+	"  /todo done   [<task|phase>]        Mark task/phase/all completed",
+	"  /todo drop   [<task|phase>]        Mark task/phase/all abandoned",
+	"  /todo rm     [<task|phase>]        Remove task/phase/all",
+].join("\n");
+
+// =============================================================================
+// Argument tokenizer (respects double-quoted strings) — omp tokenize
+// =============================================================================
+
+function tokenize(input: string): string[] {
+	const tokens: string[] = [];
+	let cur = "";
+	let inQuote = false;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input[i];
+		if (ch === "\\" && i + 1 < input.length) {
+			cur += input[++i];
+			continue;
+		}
+		if (ch === '"') {
+			inQuote = !inQuote;
+			continue;
+		}
+		if (!inQuote && /\s/.test(ch)) {
+			if (cur) {
+				tokens.push(cur);
+				cur = "";
+			}
+			continue;
+		}
+		cur += ch;
+	}
+	if (cur) tokens.push(cur);
+	return tokens;
+}
+
+// =============================================================================
+// Name normalization + fuzzy matching — omp #append / findPhaseFuzzy / findTaskFuzzy
+// =============================================================================
+
+function titleCase(s: string): string {
+	return s
+		.split(/\s+/)
+		.filter(Boolean)
+		.map(word => word[0].toUpperCase() + word.slice(1))
+		.join(" ");
+}
+
+/** Capitalize first letter only — keeps acronyms / casing in the rest intact. */
+function titleCaseSentence(s: string): string {
+	const trimmed = s.trim();
+	if (!trimmed) return trimmed;
+	return trimmed[0].toUpperCase() + trimmed.slice(1);
+}
+
+interface TodoTaskMatch {
+	task: TodoItem;
+	phase: TodoPhase;
+}
+
+function findPhaseFuzzy(phases: TodoPhase[], query: string): TodoPhase | undefined {
+	const q = query.trim().toLowerCase();
+	if (!q) return undefined;
+	// Exact name (case-insensitive)
+	const byName = phases.find(p => p.name.toLowerCase() === q);
+	if (byName) return byName;
+	// Substring (prefer prefix match)
+	const prefixMatches = phases.filter(p => p.name.toLowerCase().startsWith(q));
+	if (prefixMatches.length === 1) return prefixMatches[0];
+	const subMatches = phases.filter(p => p.name.toLowerCase().includes(q));
+	if (subMatches.length === 1) return subMatches[0];
+	return undefined;
+}
+
+function findTaskFuzzy(phases: TodoPhase[], query: string): TodoTaskMatch | undefined {
+	const q = query.trim().toLowerCase();
+	if (!q) return undefined;
+	// Exact content (case-insensitive)
+	for (const phase of phases) {
+		for (const task of phase.tasks) {
+			if (task.content.toLowerCase() === q) return { task, phase };
+		}
+	}
+	const matches: TodoTaskMatch[] = [];
+	for (const phase of phases) {
+		for (const task of phase.tasks) {
+			if (task.content.toLowerCase().includes(q)) {
+				matches.push({ task, phase });
+			}
+		}
+	}
+	if (matches.length === 1) return matches[0];
+	// Prefer single in_progress/pending hit when ambiguous
+	const active = matches.filter(m => m.task.status === "in_progress" || m.task.status === "pending");
+	if (active.length === 1) return active[0];
+	return undefined;
+}
+
+// =============================================================================
+// System reminder (omp buildSystemReminder) — tells the agent the list changed
+// =============================================================================
+
+function buildSystemReminder(action: string, phases: TodoPhase[], removed = false): string {
+	const md = phases.length === 0 ? "(empty)" : phasesToMarkdown(phases).trimEnd();
+	const lines = ["<system-reminder>", `The user manually modified the todo list (${action}).`];
+	if (removed) {
+		lines.push(
+			phases.length === 0
+				? "The user intentionally cleared the todo list. Do NOT recreate or re-populate it unless the user explicitly asks; continue the current request without a todo list."
+				: "The user intentionally removed the entries no longer shown below. Do NOT re-add them unless the user explicitly asks.",
+		);
+	}
+	lines.push("Current todo list:", "", md, "</system-reminder>");
+	return lines.join("\n");
+}
+
+// =============================================================================
+// Command handler
+// =============================================================================
+
+export function createTodoCommand(deps: TodoCommandDeps): (args: string, ctx: ExtensionCommandContext) => Promise<void> {
+	return async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
+		const trimmed = args.trim();
+		if (!trimmed) {
+			showCurrent(deps, ctx);
+			return;
+		}
+
+		const spaceIdx = trimmed.search(/\s/);
+		const verb = (spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx)).toLowerCase();
+		const rest = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1).trim();
+
+		switch (verb) {
+			case "edit":
+				await editInEditor(deps, ctx);
+				return;
+			case "copy":
+				copyMarkdown(deps, ctx);
+				return;
+			case "export":
+				await exportToFile(deps, ctx, rest);
+				return;
+			case "import":
+				await importFromFile(deps, ctx, rest);
+				return;
+			case "help":
+			case "?":
+				emit(ctx, USAGE);
+				return;
+			case "append":
+				append(deps, ctx, rest);
+				return;
+			case "start":
+				start(deps, ctx, rest);
+				return;
+			case "done":
+				mutateStatus(deps, ctx, rest, "completed");
+				return;
+			case "drop":
+				mutateStatus(deps, ctx, rest, "abandoned");
+				return;
+			case "rm":
+				remove(deps, ctx, rest);
+				return;
+			default:
+				emit(ctx, `Unknown /todo verb "${verb}".\n${USAGE}`, "error");
+		}
+	};
+}
+
+/** Headless-safe output: notify in dialog-capable UIs, stderr text elsewhere. */
+function emit(ctx: ExtensionCommandContext, text: string, severity: "info" | "warning" | "error" = "info"): void {
+	if (ctx.hasUI) {
+		ctx.ui.notify(text, severity);
+		return;
+	}
+	// stderr: stdout carries the protocol in json/rpc/print modes.
+	console.error(text);
+}
+
+function commit(deps: TodoCommandDeps, nextPhases: TodoPhase[], action: string, opts?: { removed?: boolean }): void {
+	deps.setPhases(nextPhases);
+	deps.persist(nextPhases);
+	deps.broadcast(nextPhases);
+	// omp #commit step 3: inject the system reminder so the agent learns about
+	// the change next turn. Removals carry explicit intent (omp issue #5258).
+	deps.sendHiddenMessage?.(buildSystemReminder(action, nextPhases, opts?.removed ?? false));
+}
+
+function showCurrent(deps: TodoCommandDeps, ctx: ExtensionCommandContext): void {
+	const phases = deps.getPhases();
+	if (phases.length === 0) {
+		emit(ctx, "No todos. Use /todo append <task> to start one.");
+		return;
+	}
+	emit(ctx, phasesToMarkdown(phases).trimEnd());
+}
+
+function copyMarkdown(deps: TodoCommandDeps, ctx: ExtensionCommandContext): void {
+	const phases = deps.getPhases();
+	// omp ACP fallback (no clipboard in the extension API either):
+	// "Copy not available in ACP mode; printing instead".
+	const markdown = phases.length === 0 ? "" : phasesToMarkdown(phases).trimEnd();
+	emit(ctx, `Copy not available without a clipboard integration; printing instead:\n\n${markdown || "No todos."}`);
+}
+
+async function exportToFile(deps: TodoCommandDeps, ctx: ExtensionCommandContext, rest: string): Promise<void> {
+	const phases = deps.getPhases();
+	if (phases.length === 0) {
+		emit(ctx, "No todos to export.", "warning");
+		return;
+	}
+	try {
+		const target = resolveTodoMarkdownPath(rest, ctx.cwd);
+		writeFileSync(target, phasesToMarkdown(phases), "utf8");
+		emit(ctx, `Wrote todos to ${target}`);
+	} catch (error) {
+		emit(ctx, `Failed to write todos: ${error instanceof Error ? error.message : String(error)}`, "error");
+	}
+}
+
+async function importFromFile(deps: TodoCommandDeps, ctx: ExtensionCommandContext, rest: string): Promise<void> {
+	let source = "";
+	let content: string;
+	try {
+		source = resolveTodoMarkdownPath(rest, ctx.cwd);
+		content = readFileSync(source, "utf8");
+	} catch (error) {
+		emit(ctx, `Failed to read todos: ${error instanceof Error ? error.message : String(error)}`, "error");
+		return;
+	}
+	const { phases, errors } = markdownToPhases(content);
+	if (errors.length > 0) {
+		emit(ctx, `Could not parse ${source}:\n  ${errors.join("\n  ")}`, "error");
+		return;
+	}
+	commit(deps, phases, `/todo import ${source}`);
+	const taskCount = phases.reduce((sum, p) => sum + p.tasks.length, 0);
+	emit(ctx, `Imported ${phases.length} phase(s), ${taskCount} task(s) from ${source}.`);
+}
+
+function append(deps: TodoCommandDeps, ctx: ExtensionCommandContext, rest: string): void {
+	const tokens = tokenize(rest);
+	if (tokens.length === 0) {
+		emit(ctx, "Usage: /todo append [<phase>] <task...>", "error");
+		return;
+	}
+
+	const current = deps.getPhases();
+	let phaseName: string | undefined;
+	let content: string;
+
+	if (tokens.length === 1) {
+		content = tokens[0];
+	} else {
+		phaseName = tokens[0];
+		content = tokens.slice(1).join(" ");
+	}
+
+	const next = current.map(phase => ({ ...phase, tasks: phase.tasks.slice() }));
+	let targetPhase: TodoPhase;
+
+	if (phaseName) {
+		const existing = findPhaseFuzzy(next, phaseName);
+		targetPhase = existing ?? { name: titleCase(phaseName), tasks: [] };
+		if (!existing) next.push(targetPhase);
+	} else if (next.length > 0) {
+		targetPhase = next[next.length - 1];
+	} else {
+		targetPhase = { name: "Todos", tasks: [] };
+		next.push(targetPhase);
+	}
+
+	const finalContent = titleCaseSentence(content);
+	targetPhase.tasks.push({ content: finalContent, status: "pending" });
+
+	commit(deps, next, `/todo append → ${targetPhase.name}`);
+	emit(ctx, `Appended to ${targetPhase.name}: ${finalContent}`);
+}
+
+function start(deps: TodoCommandDeps, ctx: ExtensionCommandContext, rest: string): void {
+	if (!rest) {
+		emit(ctx, "Usage: /todo start <task>", "error");
+		return;
+	}
+	const current = deps.getPhases();
+	const hit = findTaskFuzzy(current, rest);
+	if (!hit) {
+		emit(ctx, `No task matched "${rest}". Use /todo to list current tasks.`, "error");
+		return;
+	}
+	const { phases, errors } = applyOpsToPhases(current, [{ op: "start", task: hit.task.content }]);
+	if (errors.length > 0) {
+		emit(ctx, errors.join("; "), "error");
+		return;
+	}
+	commit(deps, phases, `/todo start ${hit.task.content}`);
+	emit(ctx, `Started: ${hit.task.content}`);
+}
+
+function mutateStatus(
+	deps: TodoCommandDeps,
+	ctx: ExtensionCommandContext,
+	rest: string,
+	target: "completed" | "abandoned",
+): void {
+	const op = target === "completed" ? "done" : "drop";
+	const current = deps.getPhases();
+	const trimmedArg = rest.trim();
+	if (!trimmedArg) {
+		// no-arg: apply to all
+		const { phases, errors } = applyOpsToPhases(current, [{ op }]);
+		if (errors.length > 0) {
+			emit(ctx, errors.join("; "), "error");
+			return;
+		}
+		commit(deps, phases, `/todo ${op} (all)`);
+		emit(ctx, `Marked all tasks ${target}.`);
+		return;
+	}
+
+	const taskHit = findTaskFuzzy(current, trimmedArg);
+	if (taskHit) {
+		const { phases, errors } = applyOpsToPhases(current, [{ op, task: taskHit.task.content }]);
+		if (errors.length > 0) {
+			emit(ctx, errors.join("; "), "error");
+			return;
+		}
+		commit(deps, phases, `/todo ${op} ${taskHit.task.content}`);
+		emit(ctx, `Marked ${target}: ${taskHit.task.content}`);
+		return;
+	}
+
+	const phaseHit = findPhaseFuzzy(current, trimmedArg);
+	if (phaseHit) {
+		const { phases, errors } = applyOpsToPhases(current, [{ op, phase: phaseHit.name }]);
+		if (errors.length > 0) {
+			emit(ctx, errors.join("; "), "error");
+			return;
+		}
+		commit(deps, phases, `/todo ${op} ${phaseHit.name}`);
+		emit(ctx, `Marked phase ${phaseHit.name} ${target}.`);
+		return;
+	}
+
+	emit(ctx, `No task or phase matched "${trimmedArg}".`, "error");
+}
+
+function remove(deps: TodoCommandDeps, ctx: ExtensionCommandContext, rest: string): void {
+	const current = deps.getPhases();
+	const trimmedArg = rest.trim();
+	if (!trimmedArg) {
+		commit(deps, [], "/todo rm (all)", { removed: true });
+		emit(ctx, "Cleared all todos.");
+		return;
+	}
+	const taskHit = findTaskFuzzy(current, trimmedArg);
+	if (taskHit) {
+		const { phases, errors } = applyOpsToPhases(current, [{ op: "rm", task: taskHit.task.content }]);
+		if (errors.length > 0) {
+			emit(ctx, errors.join("; "), "error");
+			return;
+		}
+		commit(deps, phases, `/todo rm ${taskHit.task.content}`, { removed: true });
+		emit(ctx, `Removed: ${taskHit.task.content}`);
+		return;
+	}
+	const phaseHit = findPhaseFuzzy(current, trimmedArg);
+	if (phaseHit) {
+		const { phases, errors } = applyOpsToPhases(current, [{ op: "rm", phase: phaseHit.name }]);
+		if (errors.length > 0) {
+			emit(ctx, errors.join("; "), "error");
+			return;
+		}
+		commit(deps, phases, `/todo rm ${phaseHit.name}`, { removed: true });
+		emit(ctx, `Removed phase: ${phaseHit.name}`);
+		return;
+	}
+	emit(ctx, `No task or phase matched "${trimmedArg}".`, "error");
+}
+
+/** omp #editInExternalEditor with pi's dialog editor as the $EDITOR surface. */
+async function editInEditor(deps: TodoCommandDeps, ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		emit(
+			ctx,
+			"/todo edit requires the TUI editor; use /todo export then /todo import for non-interactive edits.",
+			"warning",
+		);
+		return;
+	}
+	const current = deps.getPhases();
+	const initialMarkdown =
+		current.length > 0 ? phasesToMarkdown(current) : "# Todos\n- [ ] (replace this with your tasks)\n";
+
+	const result = await ctx.ui.editor("Todo (Markdown round-trip)", initialMarkdown);
+	if (result === null || result === undefined) {
+		emit(ctx, "Editor exited without saving; todos unchanged.", "warning");
+		return;
+	}
+	const { phases: parsed, errors } = markdownToPhases(result);
+	if (errors.length > 0) {
+		emit(ctx, `Could not parse Markdown:\n  ${errors.join("\n  ")}`, "error");
+		return;
+	}
+	commit(deps, parsed, "/todo edit");
+	const taskCount = parsed.reduce((sum, p) => sum + p.tasks.length, 0);
+	emit(ctx, `Todos updated from editor: ${parsed.length} phase(s), ${taskCount} task(s).`);
+}

package/src/prompts/todo.md

@@ -0,0 +1,44 @@
+**Tasks: verbatim content strings, NEVER auto-generated IDs; no "task-1"/"task-N". Pass content in `task`.**
+
+Each completion: earliest still-open task (phase order) auto-promotes to `in_progress`. Out-of-order completion may move pointer back to an earlier phase—expected; completed tasks NEVER revert.
+
+## Operations
+
+|`op`|Fields|Effect|
+|---|---|---|
+|`init`|`list: [{phase, items: string[]}]`|Initialize full list; replaces existing|
+|`init`|`items: string[]`|Flattened single-phase init|
+|`start`|`task`|Mark in progress|
+|`done`|`task` or `phase`|Mark completed|
+|`drop`|`task` or `phase`|Mark abandoned|
+|`block`|`task` or `phase`; optional `reason`|Mark blocked: open, awaiting external input; excluded from stop-time incomplete-todo reminder|
+|`unblock`|`task` or `phase`|Blocked task → `pending`|
+|`rm`|optional `task` or `phase`|Remove task/phase; omit both → clear|
+|`append`|`phase`; `items: string[]`|Append tasks to phase; lazily creates phase|
+|`view`|—|Read-only; echo list|
+
+## Anatomy
+
+- Task content: 5–10 words; what, not how; unique identifier.
+- Phase name: short noun phrase (e.g. `Foundation`, `Auth`, `Verification`); unique identifier. NEVER prefix `1.`, `A)`, `Phase 1:`.
+
+## Rules
+
+- Mark tasks done immediately after finishing; complete phases in order.
+- NEVER make a todo call the turn's only tool call. Batch with real work: `init` with first reads/edits; each `done`/`start` with next action. Solo todo turns waste a round trip.
+- Waiting on something you can't act on—a user decision, another agent, external service: `block` task (optional `reason`); remains tracked but avoids stop reminder. `unblock` when actionable. If blocker agent-actionable, `append` an unblocking task instead.
+- Keep introduced `task`/`phase` strings stable.
+- Lost exact task text: `view` echoes list; NEVER guess from memory.
+
+## Create a list
+
+- Task requires 3+ distinct steps.
+- User explicitly requests one.
+- User provides a set of tasks.
+- New instructions arrive mid-task: capture before proceeding.
+
+<critical>
+User gives multi-step plan—phased todo, numbered/bulleted checklist, or "N bugs/items/tasks":
+- MUST `init` every item as its own task before working.
+- Enumerate all; NEVER summarize into fewer tasks, sample "the important ones", drop items, or track the rest from memory.
+</critical>