pi-plan-task 1.0.0

package/extensions/parse.ts

@@ -0,0 +1,88 @@
+import type { TaskItem } from "./types.ts";
+
+const NUMBERED_ITEM = /^[-*]\s+\[([ xX])\]\s+(\d+)\.\s+(.+)$/;
+const PLAIN_ITEM = /^[-*]\s+\[([ xX])\]\s+(.+)$/;
+const TASK_HEADING = /^##\s+Task\s+(\d+)\b/i;
+
+function splitChecklist(raw: string): { checklist: string; rest: string } {
+	const lines = raw.split(/\r?\n/);
+	const index = lines.findIndex((line) => TASK_HEADING.test(line));
+	if (index < 0) return { checklist: raw, rest: "" };
+	return {
+		checklist: lines.slice(0, index).join("\n"),
+		rest: lines.slice(index).join("\n"),
+	};
+}
+
+function extractBody(raw: string, id: number): string {
+	const lines = raw.split(/\r?\n/);
+	const start = lines.findIndex((line) => {
+		const match = line.match(TASK_HEADING);
+		return match?.[1] === String(id);
+	});
+	if (start < 0) return "";
+	let end = lines.length;
+	for (let i = start + 1; i < lines.length; i++) {
+		const match = lines[i]?.match(TASK_HEADING);
+		if (match && match[1] !== String(id)) {
+			end = i;
+			break;
+		}
+	}
+	return lines.slice(start, end).join("\n").trim();
+}
+
+export function parseTaskMarkdown(raw: string): TaskItem[] {
+	const { checklist } = splitChecklist(raw);
+	const numbered: TaskItem[] = [];
+	for (const line of checklist.split(/\r?\n/)) {
+		const match = line.match(NUMBERED_ITEM);
+		if (!match) continue;
+		const id = Number(match[2]);
+		if (!Number.isFinite(id)) continue;
+		numbered.push({
+			id,
+			title: match[3].trim(),
+			done: match[1].toLowerCase() === "x",
+			body: extractBody(raw, id),
+		});
+	}
+	if (numbered.length > 0) return numbered;
+
+	const plain: TaskItem[] = [];
+	for (const line of checklist.split(/\r?\n/)) {
+		const match = line.match(PLAIN_ITEM);
+		if (!match) continue;
+		const id = plain.length + 1;
+		plain.push({
+			id,
+			title: match[2].trim(),
+			done: match[1].toLowerCase() === "x",
+			body: extractBody(raw, id),
+		});
+	}
+	return plain;
+}
+
+export function markTaskDoneInMarkdown(raw: string, id: number): string {
+	const lines = raw.split(/\r?\n/);
+	let remaining = id;
+	let changed = false;
+	const next = lines.map((line) => {
+		const numbered = line.match(NUMBERED_ITEM);
+		if (numbered && Number(numbered[2]) === id && numbered[1] !== "x" && numbered[1] !== "X") {
+			changed = true;
+			return line.replace(/\[ \]/, "[x]");
+		}
+		const plain = line.match(PLAIN_ITEM);
+		if (!numbered && plain) {
+			remaining -= 1;
+			if (remaining === 0 && plain[1] !== "x" && plain[1] !== "X") {
+				changed = true;
+				return line.replace(/\[ \]/, "[x]");
+			}
+		}
+		return line;
+	});
+	return changed ? next.join("\n") : raw;
+}

package/extensions/paths.ts

@@ -0,0 +1,39 @@
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolve } from "node:path";
+import { CONFIG_FILE_NAME, PLAN_DIR_NAME, PLAN_FILE_NAME, TASK_FILE_NAME } from "./types.ts";
+
+export function planDir(cwd: string): string {
+	return resolve(cwd, PLAN_DIR_NAME);
+}
+
+export function planFilePath(cwd: string): string {
+	return resolve(cwd, PLAN_DIR_NAME, PLAN_FILE_NAME);
+}
+
+export function taskFilePath(cwd: string): string {
+	return resolve(cwd, PLAN_DIR_NAME, TASK_FILE_NAME);
+}
+
+export function globalConfigPath(): string {
+	return resolve(getAgentDir(), CONFIG_FILE_NAME);
+}
+
+export function projectConfigPath(cwd: string): string {
+	return resolve(cwd, CONFIG_DIR_NAME, CONFIG_FILE_NAME);
+}
+
+export function samePath(a: string, b: string): boolean {
+	const left = resolve(a);
+	const right = resolve(b);
+	return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+export function isPlanArtifactPath(cwd: string, filePath: string): boolean {
+	const absolute = resolve(cwd, stripAtPrefix(filePath));
+	return samePath(absolute, planFilePath(cwd)) || samePath(absolute, taskFilePath(cwd));
+}
+
+export function stripAtPrefix(filePath: string): string {
+	return filePath.startsWith("@") ? filePath.slice(1) : filePath;
+}
+

package/extensions/plan-input.test.ts

@@ -0,0 +1,142 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, it } from "node:test";
+import {
+	isExplicitFileRef,
+	loadPlanSource,
+	parsePlanArgs,
+	type PathKind,
+	resolveUserPath,
+	tokenizePlanArgs,
+} from "./plan-input.ts";
+
+const cwd = process.platform === "win32" ? "D:\\proj" : "/proj";
+
+function kinds(entries: Record<string, PathKind>): (path: string) => PathKind {
+	return (path) => entries[path] ?? "none";
+}
+
+describe("tokenizePlanArgs", () => {
+	it("splits on whitespace and unwraps quotes", () => {
+		assert.deepEqual(tokenizePlanArgs(`docs/spec.md focus on auth`), ["docs/spec.md", "focus", "on", "auth"]);
+		assert.deepEqual(tokenizePlanArgs(`"my spec.md" extra`), ["my spec.md", "extra"]);
+		assert.deepEqual(tokenizePlanArgs(`'my spec.md'`), ["my spec.md"]);
+	});
+});
+
+describe("isExplicitFileRef", () => {
+	it("treats path-like and spec-extension tokens as file refs", () => {
+		assert.equal(isExplicitFileRef("spec.md"), true);
+		assert.equal(isExplicitFileRef("./notes.txt"), true);
+		assert.equal(isExplicitFileRef("@docs/spec.md"), true);
+		assert.equal(isExplicitFileRef("src/auth"), false);
+		assert.equal(isExplicitFileRef("Add"), false);
+	});
+});
+
+describe("parsePlanArgs", () => {
+	it("treats empty args as empty", () => {
+		assert.deepEqual(parsePlanArgs("  ", cwd, kinds({})), { kind: "empty" });
+	});
+
+	it("treats free text as a prompt", () => {
+		assert.deepEqual(parsePlanArgs("Add login with OAuth", cwd, kinds({})), {
+			kind: "prompt",
+			prompt: "Add login with OAuth",
+		});
+	});
+
+	it("treats an existing first token as a spec file", () => {
+		const spec = resolveUserPath(cwd, "docs/spec.md");
+		assert.deepEqual(parsePlanArgs("docs/spec.md focus on the callback", cwd, kinds({ [spec]: "file" })), {
+			kind: "file",
+			displayPath: "docs/spec.md",
+			resolvedPath: spec,
+			notes: "focus on the callback",
+		});
+	});
+
+	it("treats an unquoted path with spaces as a file when the whole string exists", () => {
+		const spec = resolveUserPath(cwd, "my spec.md");
+		assert.deepEqual(parsePlanArgs("my spec.md", cwd, kinds({ [spec]: "file" })), {
+			kind: "file",
+			displayPath: "my spec.md",
+			resolvedPath: spec,
+			notes: "",
+		});
+	});
+
+	it("accepts @-prefixed and quoted paths", () => {
+		const spec = resolveUserPath(cwd, "docs/spec.md");
+		assert.deepEqual(parsePlanArgs("@docs/spec.md", cwd, kinds({ [spec]: "file" })), {
+			kind: "file",
+			displayPath: "docs/spec.md",
+			resolvedPath: spec,
+			notes: "",
+		});
+		assert.deepEqual(parsePlanArgs(`"docs/spec.md" extra`, cwd, kinds({ [spec]: "file" })), {
+			kind: "file",
+			displayPath: "docs/spec.md",
+			resolvedPath: spec,
+			notes: "extra",
+		});
+	});
+
+	it("errors when an explicit file ref is missing or a directory", () => {
+		const missing = resolveUserPath(cwd, "./gone.md");
+		const folder = resolveUserPath(cwd, "docs");
+		assert.deepEqual(parsePlanArgs("./gone.md", cwd, kinds({})), {
+			kind: "missing",
+			displayPath: "./gone.md",
+			resolvedPath: missing,
+		});
+		assert.deepEqual(parsePlanArgs("docs", cwd, kinds({ [folder]: "dir" })), {
+			kind: "prompt",
+			prompt: "docs",
+		});
+		assert.deepEqual(parsePlanArgs("./docs", cwd, kinds({ [folder]: "dir" })), {
+			kind: "directory",
+			displayPath: "./docs",
+			resolvedPath: folder,
+		});
+	});
+
+	it("keeps path-like text as a prompt when the file does not exist", () => {
+		assert.deepEqual(parsePlanArgs("src/auth should use JWT", cwd, kinds({})), {
+			kind: "prompt",
+			prompt: "src/auth should use JWT",
+		});
+	});
+});
+
+describe("loadPlanSource", () => {
+	it("inlines text from an existing spec file", async () => {
+		const root = await mkdtemp(join(tmpdir(), "pi-plan-task-"));
+		const spec = join(root, "spec.md");
+		await writeFile(spec, "# Auth\n\nAdd login.\n", "utf8");
+		const loaded = await loadPlanSource("spec.md extra notes", root);
+		assert.equal(loaded.ok, true);
+		if (!loaded.ok) return;
+		assert.deepEqual(loaded.source, {
+			kind: "file",
+			displayPath: "spec.md",
+			resolvedPath: resolve(root, "spec.md"),
+			notes: "extra notes",
+			content: "# Auth\n\nAdd login.\n",
+		});
+	});
+
+	it("rejects a missing explicit file", async () => {
+		const loaded = await loadPlanSource("./missing.md", cwd, kinds({}));
+		assert.deepEqual(loaded, { ok: false, error: "File not found: ./missing.md" });
+	});
+
+	it("rejects a directory that was given as an explicit path", async () => {
+		const root = await mkdtemp(join(tmpdir(), "pi-plan-task-"));
+		await mkdir(join(root, "docs"));
+		const loaded = await loadPlanSource("./docs", root);
+		assert.deepEqual(loaded, { ok: false, error: "Path is a directory: ./docs" });
+	});
+});

package/extensions/plan-input.ts

@@ -0,0 +1,162 @@
+import { statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+function stripAtPrefix(filePath: string): string {
+	return filePath.startsWith("@") ? filePath.slice(1) : filePath;
+}
+
+export const MAX_INLINE_SPEC_CHARS = 100_000;
+
+const SPEC_EXT = /\.(md|markdown|txt|rst|adoc|org|html?)$/i;
+
+export type PathKind = "file" | "dir" | "none";
+
+export type PlanSource =
+	| { kind: "empty" }
+	| { kind: "prompt"; prompt: string }
+	| {
+			kind: "file";
+			displayPath: string;
+			resolvedPath: string;
+			notes: string;
+			content?: string;
+	  };
+
+export type ParsedPlanArgs =
+	| { kind: "empty" }
+	| { kind: "prompt"; prompt: string }
+	| { kind: "file"; displayPath: string; resolvedPath: string; notes: string }
+	| { kind: "missing"; displayPath: string; resolvedPath: string }
+	| { kind: "directory"; displayPath: string; resolvedPath: string };
+
+export const EMPTY_PLAN_SOURCE: PlanSource = { kind: "empty" };
+
+export function tokenizePlanArgs(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: '"' | "'" | null = null;
+	for (const char of input) {
+		if (quote) {
+			if (char === quote) {
+				quote = null;
+			} else {
+				current += char;
+			}
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			quote = char;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += char;
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}
+
+export function isExplicitFileRef(token: string): boolean {
+	if (token.startsWith("@")) return true;
+	const raw = stripAtPrefix(token);
+	if (raw.startsWith("./") || raw.startsWith(".\\") || raw.startsWith("../") || raw.startsWith("..\\")) {
+		return true;
+	}
+	if (raw.startsWith("~")) return true;
+	if (raw.startsWith("/") || raw.startsWith("\\\\")) return true;
+	if (/^[A-Za-z]:[\\/]/.test(raw)) return true;
+	return SPEC_EXT.test(raw);
+}
+
+export function resolveUserPath(cwd: string, raw: string): string {
+	const path = stripAtPrefix(raw);
+	if (path === "~") return homedir();
+	if (path.startsWith("~/") || path.startsWith("~\\")) {
+		return resolve(homedir(), path.slice(2));
+	}
+	return resolve(cwd, path);
+}
+
+export function pathKind(path: string): PathKind {
+	try {
+		const info = statSync(path);
+		if (info.isFile()) return "file";
+		if (info.isDirectory()) return "dir";
+		return "none";
+	} catch {
+		return "none";
+	}
+}
+
+export function parsePlanArgs(
+	args: string,
+	cwd: string,
+	kindOf: (path: string) => PathKind = pathKind,
+): ParsedPlanArgs {
+	const trimmed = args.trim();
+	if (!trimmed) return { kind: "empty" };
+
+	const wholePath = resolveUserPath(cwd, trimmed);
+	if (kindOf(wholePath) === "file") {
+		return { kind: "file", displayPath: stripAtPrefix(trimmed), resolvedPath: wholePath, notes: "" };
+	}
+
+	const tokens = tokenizePlanArgs(trimmed);
+	if (tokens.length === 0) return { kind: "empty" };
+
+	const first = tokens[0] ?? "";
+	const resolvedPath = resolveUserPath(cwd, first);
+	const kind = kindOf(resolvedPath);
+	const displayPath = stripAtPrefix(first);
+	const notes = tokens.slice(1).join(" ");
+
+	if (kind === "file") {
+		return { kind: "file", displayPath, resolvedPath, notes };
+	}
+	if (isExplicitFileRef(first)) {
+		if (kind === "dir") return { kind: "directory", displayPath, resolvedPath };
+		return { kind: "missing", displayPath, resolvedPath };
+	}
+	return { kind: "prompt", prompt: tokens.join(" ") };
+}
+
+export async function loadPlanSource(
+	args: string,
+	cwd: string,
+	kindOf: (path: string) => PathKind = pathKind,
+): Promise<{ ok: true; source: PlanSource } | { ok: false; error: string }> {
+	const parsed = parsePlanArgs(args, cwd, kindOf);
+	if (parsed.kind === "missing") {
+		return { ok: false, error: `File not found: ${parsed.displayPath}` };
+	}
+	if (parsed.kind === "directory") {
+		return { ok: false, error: `Path is a directory: ${parsed.displayPath}` };
+	}
+	if (parsed.kind === "empty" || parsed.kind === "prompt") {
+		return { ok: true, source: parsed };
+	}
+
+	try {
+		const raw = await readFile(parsed.resolvedPath, "utf8");
+		if (raw.includes("\0")) {
+			return { ok: false, error: `Not a text file: ${parsed.displayPath}` };
+		}
+		return {
+			ok: true,
+			source: {
+				...parsed,
+				content: raw.length <= MAX_INLINE_SPEC_CHARS ? raw : undefined,
+			},
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Could not read ${parsed.displayPath}: ${message}` };
+	}
+}