pi-task-manager 0.1.0

package/lib/task.ts

@@ -0,0 +1,57 @@
+/**
+ * Task model — a tree node. The tree (parent/children links) is the
+ * single source of truth for hierarchy; depth, position, parent_id, and
+ * children_ids are all derived from it.
+ */
+
+export interface Task {
+	id: string;
+	description: string;
+	/** ' ' = open, 'x' = done, '>' = in progress, '!' = failed, '-' = cancelled */
+	status: string;
+	/** lowest | low | normal | medium | high | highest */
+	priority: string | null;
+	dateCreated: string | null;
+	dateModified: string | null;
+	dateScheduled: string | null;
+	dateStart: string | null;
+	dateDue: string | null;
+	dateDone: string | null;
+	dateCancelled: string | null;
+	recurrence: string | null;
+	/** keep | delete (null = keep, the default) */
+	onCompletion: string | null;
+	dependsOn: string[];
+	hasSpec: boolean;
+	parent: Task | null;
+	children: Task[];
+}
+
+export function newTask(id: string, description: string): Task {
+	return {
+		id,
+		description,
+		status: " ",
+		priority: null,
+		dateCreated: null,
+		dateModified: null,
+		dateScheduled: null,
+		dateStart: null,
+		dateDue: null,
+		dateDone: null,
+		dateCancelled: null,
+		recurrence: null,
+		onCompletion: null,
+		dependsOn: [],
+		hasSpec: false,
+		parent: null,
+		children: [],
+	};
+}
+
+/** Depth of a task (0 = top level). */
+export function depthOf(task: Task): number {
+	let depth = 0;
+	for (let p = task.parent; p; p = p.parent) depth++;
+	return depth;
+}

package/lib/tools.ts

@@ -0,0 +1,179 @@
+/**
+ * Tool schemas for the task manager (8 tools).
+ * Parameter names are snake_case to match the Python tool contract.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type TSchema } from "typebox";
+
+const StatusEnum = StringEnum([" ", "x", ">", "!", "-"] as const);
+const PriorityEnum = StringEnum([
+	"lowest",
+	"low",
+	"normal",
+	"medium",
+	"high",
+	"highest",
+	"null",
+] as const);
+const OnCompletionEnum = StringEnum(["keep", "delete", "null"] as const);
+
+const date = (what: string) =>
+	Type.Optional(Type.String({ description: `${what}, YYYY-MM-DD` }));
+
+const TaskOpenParams = Type.Object({
+	path: Type.String({
+		description: "Workspace directory containing TODO.md (created if missing)",
+	}),
+});
+
+const TaskAddParams = Type.Object({
+	description: Type.String({ description: "Task description" }),
+	parent_id: Type.Optional(
+		Type.String({ description: "Add as last child of this task" }),
+	),
+	before_id: Type.Optional(
+		Type.String({ description: "Insert before this task (same level)" }),
+	),
+	after_id: Type.Optional(
+		Type.String({
+			description: "Insert after this task (same level)",
+		}),
+	),
+	priority: Type.Optional(PriorityEnum),
+	scheduled: date("Scheduled date"),
+	start: date("Start date"),
+	due: date("Due date"),
+	recurrence: Type.Optional(
+		Type.String({
+			description: "Recurrence rule, e.g. 'weekly' or 'every 2 weeks on Monday'",
+		}),
+	),
+	on_completion: Type.Optional(OnCompletionEnum),
+	depends_on: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "IDs of tasks this task depends on",
+		}),
+	),
+	spec: Type.Optional(
+		Type.Boolean({ description: "Also create a task-<id>.md spec file" }),
+	),
+});
+
+const TaskEditParams = Type.Object({
+	task_id: Type.String({ description: "ID of the task to edit" }),
+	description: Type.Optional(Type.String()),
+	status: Type.Optional(StatusEnum),
+	priority: Type.Optional(PriorityEnum),
+	scheduled: date("Scheduled date"),
+	start: date("Start date"),
+	due: date("Due date"),
+	recurrence: Type.Optional(Type.String()),
+	on_completion: Type.Optional(OnCompletionEnum),
+	depends_on: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "New full dependency list (replaces existing)",
+		}),
+	),
+});
+
+const TaskMoveParams = Type.Object({
+	task_id: Type.String({ description: "ID of the task to move" }),
+	under_id: Type.Optional(
+		Type.String({
+			description: "Make this task a child of the target (last child)",
+		}),
+	),
+	before_id: Type.Optional(
+		Type.String({ description: "Place before this task (same level)" }),
+	),
+	after_id: Type.Optional(
+		Type.String({
+			description: "Place after this task (same level)",
+		}),
+	),
+});
+
+const TaskGetParams = Type.Object({
+	task_id: Type.String({ description: "ID of the task to fetch" }),
+});
+
+const TaskListParams = Type.Object({
+	parent_id: Type.Optional(
+		Type.String({ description: "Only tasks under this parent" }),
+	),
+	status: Type.Optional(StatusEnum),
+	priority: Type.Optional(PriorityEnum),
+	include_subtasks: Type.Optional(
+		Type.Boolean({
+			description: "With parent_id: include the whole subtree",
+		}),
+	),
+});
+
+const TaskSaveParams = Type.Object({});
+const TaskCloseParams = Type.Object({});
+
+export interface ToolDef {
+	name: string;
+	label: string;
+	description: string;
+	parameters: TSchema;
+}
+
+export const TOOLS: ToolDef[] = [
+	{
+		name: "task_open",
+		label: "Task Open",
+		description:
+			"Open a TODO.md task file in a workspace directory. Call once before other task tools.",
+		parameters: TaskOpenParams,
+	},
+	{
+		name: "task_add",
+		label: "Task Add",
+		description:
+			"Add a task. Hierarchy: parent_id (last child), before_id/after_id (sibling placement). Returns the new 6-char task ID.",
+		parameters: TaskAddParams,
+	},
+	{
+		name: "task_edit",
+		label: "Task Edit",
+		description:
+			"Edit fields of an existing task. Only provided fields change. Status 'x' stamps date_done, '-' stamps date_cancelled.",
+		parameters: TaskEditParams,
+	},
+	{
+		name: "task_move",
+		label: "Task Move",
+		description:
+			"Move a task (with its subtree) under/before/after another task. Omit all destinations to delete the task and its subtree.",
+		parameters: TaskMoveParams,
+	},
+	{
+		name: "task_get",
+		label: "Task Get",
+		description: "Get full details of one task by ID.",
+		parameters: TaskGetParams,
+	},
+	{
+		name: "task_list",
+		label: "Task List",
+		description:
+			"List tasks, optionally filtered by parent, status, or priority. include_subtasks=true returns the whole subtree under parent_id.",
+		parameters: TaskListParams,
+	},
+	{
+		name: "task_save",
+		label: "Task Save",
+		description:
+			"Force a save of the task file to disk (changes are also auto-saved after each mutation).",
+		parameters: TaskSaveParams,
+	},
+	{
+		name: "task_close",
+		label: "Task Close",
+		description: "Save and close the current task file.",
+		parameters: TaskCloseParams,
+	},
+];

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "pi-task-manager",
+	"version": "0.1.0",
+	"description": "Task/todo management extension for pi",
+	"keywords": ["pi-package"],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gilgil/pi-task-manager.git"
+	},
+	"type": "module",
+	"pi": {
+		"extensions": ["./index.ts"],
+		"skills": ["./skills"]
+	},
+	"scripts": {
+		"test": "node --test tests/*.test.ts",
+		"typecheck": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@types/node": "^22",
+		"typescript": "^5"
+	}
+}

package/skills/task-manager/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: task-manager
+description: Manage tasks in a TODO.md tree using the task_* tools (task_open, task_add, task_edit, task_move, task_list, task_get, task_save, task_close). Use when tracking TODOs or tasks in a pi session.
+---
+
+# Task Manager
+
+Manage tasks in a `TODO.md` tree using the `task_*` tools.
+
+## Workflow
+
+1. `task_open(path)` — open `<path>/TODO.md` (created if missing). Call once before anything else.
+2. `task_list()` — see what exists.
+3. `task_add(description, ...)` — add tasks. Returns the new 6-char ID.
+4. `task_edit(task_id, ...)` — change fields (only provided fields).
+5. `task_move(task_id, ...)` — reposition a task (with its subtree).
+6. `task_save()` / `task_close()` — save and close when done.
+
+Mutations auto-save; `task_save` is a manual force-save.
+
+## Hierarchy
+
+Tasks form a tree via indentation. Placement parameters:
+
+- `parent_id` — add/move as **last child** of that task
+- `before_id` / `after_id` — insert at the **same level**, before/after that
+  sibling (it must share the target's parent)
+- `task_move` with **no** destination deletes the task and its subtree
+
+Example: add "Organic" under task `5Tvc0d`:
+`task_add("Organic", parent_id: "5Tvc0d")`
+
+## Fields
+
+- Descriptions must be single-line and must not contain the annotation
+  emojis (⏬🔽🔼⏫🔺⏳🛫📅✅❌➕🖊️🔁🗑️🏁⛔📎🆔) — they are reserved for metadata.
+- `priority`: `lowest` `low` `normal` `medium` `high` `highest`
+- `status`: ` ` open · `x` done · `>` in-progress · `!` failed · `-` cancelled
+  (setting `x` / `-` stamps `date_done` / `date_cancelled`)
+- dates `scheduled` / `start` / `due`: `YYYY-MM-DD`
+- `recurrence`: e.g. `weekly`, `every 2 weeks on Monday`
+- `depends_on`: list of task IDs (circular dependencies are rejected)
+- `spec: true` on add — also create a `task-<id>.md` spec file
+
+## Tips
+
+- Always `task_open` first; `task_list` before adding to find `parent_id`s.
+- Use `task_list(parent_id, include_subtasks: true)` to inspect a subtree.
+- `task_get(task_id)` for full details of one task.
+- IDs are stable 6-char strings — reuse them across calls in a session.

package/tests/parser.test.ts

@@ -0,0 +1,120 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+	parseTaskLine,
+	parseTodoFile,
+	buildTaskLine,
+	tasksToMarkdown,
+} from "../lib/parser.ts";
+import { depthOf, type Task } from "../lib/task.ts";
+
+/** Flatten a tree to DFS order (for assertions). */
+function flatten(roots: Task[]): Task[] {
+	const out: Task[] = [];
+	const walk = (tasks: Task[]): void => {
+		for (const t of tasks) {
+			out.push(t);
+			walk(t.children);
+		}
+	};
+	walk(roots);
+	return out;
+}
+
+test("parse simple task line", () => {
+	const t = parseTaskLine("- [ ] Buy milk (ID: `abc123`)")!;
+	assert.equal(t.id, "abc123");
+	assert.equal(t.description, "Buy milk");
+	assert.equal(t.status, " ");
+	assert.equal(t.parent, null);
+	assert.deepEqual(t.children, []);
+});
+
+test("parse indented task line", () => {
+	const t = parseTaskLine("  - [x] Done thing (ID: `def456`)")!;
+	assert.equal(t.id, "def456");
+	assert.equal(t.status, "x");
+});
+
+test("parse all annotations", () => {
+	const line =
+		"- [>] Roof 🔺 ⏳ 2026-01-01 🛫 2026-01-02 📅 2026-01-03 ✅ 2026-01-04 ❌ 2026-01-05 🔁 weekly 🗑️ ⛔ abc123,def456 📎 [spec](task-ghi789.md) ➕ 2026-01-01 🖊️ 2026-01-02 (ID: `ghi789`)";
+	const t = parseTaskLine(line)!;
+	assert.equal(t.description, "Roof");
+	assert.equal(t.priority, "highest");
+	assert.equal(t.dateScheduled, "2026-01-01");
+	assert.equal(t.dateStart, "2026-01-02");
+	assert.equal(t.dateDue, "2026-01-03");
+	assert.equal(t.dateDone, "2026-01-04");
+	assert.equal(t.dateCancelled, "2026-01-05");
+	assert.equal(t.recurrence, "weekly");
+	assert.equal(t.onCompletion, "delete");
+	assert.deepEqual(t.dependsOn, ["abc123", "def456"]);
+	assert.equal(t.hasSpec, true);
+	assert.equal(t.dateCreated, "2026-01-01");
+	assert.equal(t.dateModified, "2026-01-02");
+});
+
+test("recurrence rule extends to next emoji", () => {
+	const t = parseTaskLine("- [ ] Meet 🔁 every 2 weeks on Monday 📅 2026-02-01 (ID: `abc123`)")!;
+	assert.equal(t.recurrence, "every 2 weeks on Monday");
+	assert.equal(t.dateDue, "2026-02-01");
+});
+
+test("invalid lines return null", () => {
+	assert.equal(parseTaskLine("- [ ] No id here"), null);
+	assert.equal(parseTaskLine("- [q] Bad status (ID: `abc123`)"), null);
+	assert.equal(parseTaskLine("# comment"), null);
+	assert.equal(parseTaskLine(""), null);
+});
+
+test("hierarchy: depth, parent, children", () => {
+	const content = [
+		"# TODO",
+		"",
+		"- [ ] A (ID: `aaaaaa`)",
+		"  - [ ] B (ID: `bbbbbb`)",
+		"    - [ ] C (ID: `cccccc`)",
+		"  - [ ] D (ID: `dddddd`)",
+		"- [ ] E (ID: `eeeeee`)",
+		"",
+	].join("\n");
+	const roots = parseTodoFile(content);
+	assert.deepEqual(roots.map((t) => t.id), ["aaaaaa", "eeeeee"]);
+	const byId = Object.fromEntries(flatten(roots).map((t) => [t.id, t]));
+	assert.equal(byId["bbbbbb"].parent?.id, "aaaaaa");
+	assert.equal(depthOf(byId["bbbbbb"]), 1);
+	assert.equal(byId["cccccc"].parent?.id, "bbbbbb");
+	assert.equal(depthOf(byId["cccccc"]), 2);
+	assert.equal(byId["dddddd"].parent?.id, "aaaaaa");
+	assert.equal(byId["aaaaaa"].children.indexOf(byId["dddddd"]), 1);
+	assert.deepEqual(byId["aaaaaa"].children.map((c) => c.id), [
+		"bbbbbb",
+		"dddddd",
+	]);
+	assert.deepEqual(byId["bbbbbb"].children.map((c) => c.id), ["cccccc"]);
+});
+
+test("round-trip: parse -> build -> parse is stable", () => {
+	const content = [
+		"# TODO",
+		"",
+		"- [ ] A ⏫ ⏳ 2026-09-01 📅 2026-12-01 ➕ 2026-08-14 🖊️ 2026-08-14 (ID: `aaaaaa`)",
+		"  - [>] B 🔺 🔁 monthly 🗑️ ⛔ aaaaaa ➕ 2026-08-14 🖊️ 2026-08-14 (ID: `bbbbbb`)",
+		"",
+	].join("\n");
+	const once = parseTodoFile(content);
+	const rebuilt = tasksToMarkdown(once);
+	assert.equal(rebuilt, content);
+	const twice = parseTodoFile(rebuilt);
+	assert.deepEqual(
+		flatten(twice).map((t) => t.id),
+		flatten(once).map((t) => t.id),
+	);
+	assert.equal(tasksToMarkdown(twice), content);
+});
+
+test("buildTaskLine: no annotations", () => {
+	const t = parseTaskLine("- [ ] Plain (ID: `aaaaaa`)")!;
+	assert.equal(buildTaskLine(t), "- [ ] Plain (ID: `aaaaaa`)");
+});

package/tests/robustness.test.ts

@@ -0,0 +1,154 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { TaskManager } from "../lib/task-manager.ts";
+
+function setup() {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tm-rob-"));
+	const tm = new TaskManager();
+	tm.openFile(dir);
+	return { tm, dir };
+}
+
+const id = (r: Record<string, unknown>) => r.task_id as string;
+
+// ── annotation emoji in descriptions (CdqV8G) ─────────────────────────
+
+test("addTask: rejects description containing priority emoji", () => {
+	const { tm } = setup();
+	const r = tm.addTask("Fix 🔺 icon");
+	assert.equal(r.status, "error");
+	assert.match(r.error as string, /emoji/i);
+});
+
+test("addTask: rejects description containing date emoji", () => {
+	const { tm } = setup();
+	const r = tm.addTask("done ✅ today");
+	assert.equal(r.status, "error");
+	assert.match(r.error as string, /emoji/i);
+});
+
+test("addTask: rejects description containing recurrence emoji", () => {
+	const { tm } = setup();
+	const r = tm.addTask("repeats 🔁 forever");
+	assert.equal(r.status, "error");
+	assert.match(r.error as string, /emoji/i);
+});
+
+test("editTask: rejects description containing annotation emoji", () => {
+	const { tm } = setup();
+	const a = id(tm.addTask("A"));
+	const r = tm.editTask(a, "Fix 🔺 icon");
+	assert.equal(r.status, "error");
+	assert.match(r.error as string, /emoji/i);
+});
+
+test("addTask: accepts description with non-annotation emoji (round-trips)", () => {
+	const { tm, dir } = setup();
+	const a = id(tm.addTask("Fix the 🐛 bug"));
+	tm.closeFile();
+	const tm2 = new TaskManager();
+	tm2.openFile(dir);
+	const t = tm2.getTask(a) as any;
+	assert.equal(t.task.description, "Fix the 🐛 bug");
+});
+
+// ── status revert (hjKhGg) ───────────────────────────────────────────────────
+
+test("editTask: reverting status from x clears date_done", () => {
+	const { tm } = setup();
+	const a = id(tm.addTask("A"));
+	tm.editTask(a, undefined, "x");
+	assert.ok((tm.getTask(a) as any).task.date_done, "date_done stamped on x");
+	tm.editTask(a, undefined, " ");
+	assert.equal((tm.getTask(a) as any).task.date_done, null);
+});
+
+test("editTask: reverting status from - clears date_cancelled", () => {
+	const { tm } = setup();
+	const a = id(tm.addTask("A"));
+	tm.editTask(a, undefined, "-");
+	assert.ok((tm.getTask(a) as any).task.date_cancelled, "date_cancelled stamped on -");
+	tm.editTask(a, undefined, " ");
+	assert.equal((tm.getTask(a) as any).task.date_cancelled, null);
+});
+
+test("editTask: x to - clears date_done and stamps date_cancelled", () => {
+	const { tm } = setup();
+	const a = id(tm.addTask("A"));
+	tm.editTask(a, undefined, "x");
+	tm.editTask(a, undefined, "-");
+	const t = (tm.getTask(a) as any).task;
+	assert.equal(t.date_done, null);
+	assert.ok(t.date_cancelled);
+});
+
+// ── openFile error handling (3Dqwgr) ──────────────────────────────────
+
+test("openFile: bad path returns error Result instead of throwing", () => {
+	const tm = new TaskManager();
+	const r = tm.openFile("/nonexistent/definitely/missing");
+	assert.equal(r.status, "error");
+	assert.match(r.error as string, /open/i);
+	assert.equal(tm.isOpen, false);
+});
+
+test("openFile: path is a file, not a directory → error Result", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tm-rob-"));
+	const file = path.join(dir, "notadir");
+	fs.writeFileSync(file, "hi");
+	const tm = new TaskManager();
+	const r = tm.openFile(file);
+	assert.equal(r.status, "error");
+	assert.equal(tm.isOpen, false);
+});
+
+// ── save failure surfacing (gtoVfN) ───────────────────────────────────
+
+test("save: returns error when directory is read-only", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tm-rob-"));
+	const tm = new TaskManager();
+	tm.openFile(dir);
+	const a = id(tm.addTask("A"));
+	fs.chmodSync(dir, 0o555);
+	try {
+		const r = tm.save();
+		assert.equal(r.status, "error");
+		assert.match(r.error as string, /save/i);
+	} finally {
+		fs.chmodSync(dir, 0o755);
+	}
+});
+
+test("addTask: reports warning when auto-save fails", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tm-rob-"));
+	const tm = new TaskManager();
+	tm.openFile(dir);
+	id(tm.addTask("A"));
+	fs.chmodSync(dir, 0o555);
+	try {
+		const r = tm.addTask("B");
+		assert.equal(r.status, "ok");
+		assert.match(r.warning as string, /save failed/i);
+	} finally {
+		fs.chmodSync(dir, 0o755);
+	}
+});
+
+test("closeFile: save failure returns error and keeps file open", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tm-rob-"));
+	const tm = new TaskManager();
+	tm.openFile(dir);
+	fs.chmodSync(dir, 0o555);
+	try {
+		tm.addTask("A"); // auto-save fails, stays dirty
+		const r = tm.closeFile();
+		assert.equal(r.status, "error");
+		assert.match(r.error as string, /save/i);
+		assert.equal(tm.isOpen, true);
+	} finally {
+		fs.chmodSync(dir, 0o755);
+	}
+});