@bumpyclock/pi-tasque 0.2.0 → 0.2.1

package/src/durable-tasks/task-validation.ts

@@ -0,0 +1,123 @@
+import {
+	fieldRequired,
+	requireStringField,
+} from "../shared/validation.js";
+import {
+	validateBulkItems,
+	validateCreateTreeNode,
+} from "./bulk-contract.js";
+import type { TaskAction, TaskParams } from "./task-schema.js";
+
+export function validateTaskParams(
+	params: TaskParams,
+): { readonly ok: true } | { readonly ok: false; readonly message: string } {
+	switch (params.action) {
+		case "find":
+			if (params.view === "tree") return { ok: true };
+			if (params.tasks === undefined) return fieldRequired("tasks");
+			return { ok: true };
+		case "show":
+		case "deps":
+		case "notes":
+		case "note":
+		case "finish":
+		case "reopen":
+		case "defer":
+		case "start":
+		case "claim":
+		case "import":
+			return requireStringField(params.task, "task");
+		case "create": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			const kind = requireStringField(params.kind, "kind");
+			if (!kind.ok) return kind;
+			return typeof params.priority === "number"
+				? { ok: true }
+				: fieldRequired("priority");
+		}
+		case "similar":
+			return requireStringField(params.query, "query");
+		case "block":
+		case "unblock": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			return requireStringField(params.by, "by");
+		}
+		case "order":
+		case "unorder": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			return requireStringField(params.after, "after");
+		}
+		case "link": {
+			const todo = requireTodoId(params.todo);
+			if (!todo.ok) return todo;
+			return requireStringField(params.task, "task");
+		}
+		case "promote":
+			return requireTodoId(params.todo);
+		case "mark_planned":
+			return requireStringField(params.task, "task");
+		case "spec": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			const mode = params.mode as string | undefined;
+			if (mode === undefined || mode.trim().length === 0)
+				return fieldRequired("mode");
+			const isRead = mode === "show" || mode === "check";
+			const isWrite = mode === "set" || mode === "update";
+			if (!isRead && !isWrite)
+				return {
+					ok: false,
+					message: "mode must be show, check, set, or update",
+				};
+			if (isRead && params.text !== undefined)
+				return {
+					ok: false,
+					message: `spec ${mode} does not accept text`,
+				};
+			if (isWrite) {
+				const text = params.text?.trim();
+				if (text === undefined || text.length === 0)
+					return {
+						ok: false,
+						message: `spec ${mode} requires text`,
+					};
+			}
+			return { ok: true };
+		}
+		case "bulk":
+			return validateBulkItems(params.items);
+		case "create_tree":
+			return validateCreateTreeNode(params.root);
+		case "handoff_check":
+		case "doctor":
+		case "list_links":
+			return { ok: true };
+	}
+}
+
+export function actionUsesTasque(action: TaskAction): boolean {
+	return (
+		action !== "link" && action !== "list_links" && action !== "handoff_check"
+	);
+}
+
+export function hasWith(params: TaskParams, value: string): boolean {
+	return Array.isArray(params.with) && params.with.includes(value);
+}
+
+export function getTodoId(
+	value: boolean | number | undefined,
+): number | undefined {
+	return typeof value === "number" ? value : undefined;
+}
+
+export function requireTodoId(
+	value: boolean | number | undefined,
+): { readonly ok: true } | { readonly ok: false; readonly message: string } {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1
+		? { ok: true }
+		: fieldRequired("todo");
+}

package/src/durable-tasks/tools-bulk.ts

@@ -12,6 +12,7 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import type { BulkItem, BulkItemAction, BulkResult } from "./bulk-contract.js";
+import { isRecord } from "../shared/error-utils.js";
 import type { StandardToolDetails } from "../shared/tool-result.js";
 import { okToolDetails, textToolResult } from "../shared/tool-result.js";
 import {
@@ -138,7 +139,3 @@ function formatBulkText(result: BulkResult, total: number): string {
 }
 
 // ── Utilities ──────────────────────────────────────────────────────
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/durable-tasks/tools-change.ts

@@ -10,31 +10,26 @@ import {
 	CHANGE_TASKS_PROMPT_GUIDELINES,
 	CHANGE_TASKS_PROMPT_SNIPPET,
 } from "../guidelines/internal-tools.js";
+import {
+	asRecord,
+	copyKnownErrorFields,
+} from "../shared/error-utils.js";
 import {
 	errorToolDetails,
 	okToolDetails,
 	textToolResult,
 } from "../shared/tool-result.js";
+import {
+	buildMutationCommand,
+	TSQ_CHANGE_ACTIONS,
+	type TsqChangeAction,
+} from "./change-command-builder.js";
 import { runQueuedMutation } from "./mutation-queue.js";
 import { runTsqJson } from "./runner.js";
 
 export const TSQ_CHANGE_TOOL_NAME = "tsq_change";
 
-const TSQ_CHANGE_ACTIONS = [
-	"create",
-	"note",
-	"done",
-	"reopen",
-	"defer",
-	"start",
-	"claim_assign_only",
-	"block",
-	"unblock",
-	"order",
-	"unorder",
-] as const;
-
-export type TsqChangeAction = (typeof TSQ_CHANGE_ACTIONS)[number];
+export type { TsqChangeAction } from "./change-command-builder.js";
 
 export const TsqChangeParamsSchema = Type.Object(
 	{
@@ -116,14 +111,6 @@ export type TsqChangeDetails = ReturnType<
 	typeof okToolDetails<TsqChangeSuccessData>
 >;
 
-type ValidationResult =
-	| {
-			readonly ok: true;
-			readonly action: TsqChangeAction;
-			readonly argv: string[];
-	  }
-	| { readonly ok: false; readonly message: string };
-
 export function registerTsqChangeTool(pi: ExtensionAPI): void {
 	pi.registerTool(
 		defineTool({
@@ -241,294 +228,6 @@ function runMutation(
 	);
 }
 
-function buildMutationCommand(
-	params: Readonly<Record<string, unknown>>,
-): ValidationResult {
-	const action = params.action;
-	if (!isTsqChangeAction(action)) {
-		return {
-			ok: false,
-			message: "action must be a supported durable task mutation",
-		};
-	}
-
-	switch (action) {
-		case "create":
-			return buildCreateArgv(params, action);
-		case "note":
-			return buildNoteArgv(params, action);
-		case "done":
-			return buildOptionalNoteArgv(params, action, "done");
-		case "reopen":
-			return buildIdOnlyArgv(params, action, "reopen");
-		case "defer":
-			return buildOptionalNoteArgv(params, action, "defer");
-		case "start":
-			return buildIdOnlyArgv(params, action, "start");
-		case "claim_assign_only":
-			return buildClaimAssignOnlyArgv(params, action);
-		case "block":
-			return buildBlockArgv(params, action, "block");
-		case "unblock":
-			return buildBlockArgv(params, action, "unblock");
-		case "order":
-			return buildOrderArgv(params, action, "order");
-		case "unorder":
-			return buildOrderArgv(params, action, "unorder");
-	}
-}
-
-function buildCreateArgv(
-	params: Readonly<Record<string, unknown>>,
-	action: TsqChangeAction,
-): ValidationResult {
-	const title = requireNonEmptyString(params, "title");
-	if (!title.ok) {
-		return title;
-	}
-	const kind = requireNonEmptyString(params, "kind");
-	if (!kind.ok) {
-		return kind;
-	}
-	const priority = requireInteger(params, "priority");
-	if (!priority.ok) {
-		return priority;
-	}
-	const planned = getOptionalBoolean(params, "planned");
-	if (!planned.ok) {
-		return planned;
-	}
-	const needsPlan = getOptionalBoolean(params, "needsPlan");
-	if (!needsPlan.ok) {
-		return needsPlan;
-	}
-	if (planned.value === true && needsPlan.value === true) {
-		return {
-			ok: false,
-			message: "planned and needsPlan cannot both be true",
-		};
-	}
-
-	const argv = ["create", `--kind=${kind.value}`, "-p", String(priority.value)];
-	const description = appendOptionalStringFlag(
-		argv,
-		params,
-		"description",
-		"--description",
-	);
-	if (description !== undefined) {
-		return description;
-	}
-	const parent = appendOptionalStringFlag(argv, params, "parent", "--parent");
-	if (parent !== undefined) {
-		return parent;
-	}
-	if (planned.value === true) {
-		argv.push("--planned");
-	} else if (needsPlan.value === true) {
-		argv.push("--needs-plan");
-	}
-	argv.push("--", title.value);
-
-	return { ok: true, action, argv };
-}
-
-function buildNoteArgv(
-	params: Readonly<Record<string, unknown>>,
-	action: TsqChangeAction,
-): ValidationResult {
-	const id = requireNonEmptyString(params, "id");
-	if (!id.ok) {
-		return id;
-	}
-	const note = requireNonEmptyString(params, "note");
-	if (!note.ok) {
-		return note;
-	}
-	return { ok: true, action, argv: ["note", id.value, "--", note.value] };
-}
-
-function buildOptionalNoteArgv(
-	params: Readonly<Record<string, unknown>>,
-	action: TsqChangeAction,
-	command: "done" | "defer",
-): ValidationResult {
-	const id = requireNonEmptyString(params, "id");
-	if (!id.ok) {
-		return id;
-	}
-	const argv = [command, id.value];
-	const note = getOptionalNonEmptyString(params, "note");
-	if (!note.ok) {
-		return note;
-	}
-	if (note.value !== undefined) {
-		argv.push(`--note=${note.value}`);
-	}
-	return { ok: true, action, argv };
-}
-
-function buildIdOnlyArgv(
-	params: Readonly<Record<string, unknown>>,
-	action: TsqChangeAction,
-	command: "reopen" | "start",
-): ValidationResult {
-	const id = requireNonEmptyString(params, "id");
-	if (!id.ok) {
-		return id;
-	}
-	return { ok: true, action, argv: [command, id.value] };
-}
-
-function buildClaimAssignOnlyArgv(
-	params: Readonly<Record<string, unknown>>,
-	action: TsqChangeAction,
-): ValidationResult {
-	const id = requireNonEmptyString(params, "id");
-	if (!id.ok) {
-		return id;
-	}
-	const assignee = requireNonEmptyString(params, "assignee");
-	if (!assignee.ok) {
-		return assignee;
-	}
-	return {
-		ok: true,
-		action,
-		argv: ["claim", id.value, `--assignee=${assignee.value}`],
-	};
-}
-
-function buildBlockArgv(
-	params: Readonly<Record<string, unknown>>,
-	action: TsqChangeAction,
-	command: "block" | "unblock",
-): ValidationResult {
-	const child = requireNonEmptyString(params, "child");
-	if (!child.ok) {
-		return child;
-	}
-	const blocker = requireNonEmptyString(params, "blocker");
-	if (!blocker.ok) {
-		return blocker;
-	}
-	if (child.value === blocker.value) {
-		return { ok: false, message: "child and blocker cannot be the same task" };
-	}
-	return {
-		ok: true,
-		action,
-		argv: [command, child.value, "by", blocker.value],
-	};
-}
-
-function buildOrderArgv(
-	params: Readonly<Record<string, unknown>>,
-	action: TsqChangeAction,
-	command: "order" | "unorder",
-): ValidationResult {
-	const later = requireNonEmptyString(params, "later");
-	if (!later.ok) {
-		return later;
-	}
-	const earlier = requireNonEmptyString(params, "earlier");
-	if (!earlier.ok) {
-		return earlier;
-	}
-	if (later.value === earlier.value) {
-		return { ok: false, message: "later and earlier cannot be the same task" };
-	}
-	return {
-		ok: true,
-		action,
-		argv: [command, later.value, "after", earlier.value],
-	};
-}
-
-function appendOptionalStringFlag(
-	argv: string[],
-	params: Readonly<Record<string, unknown>>,
-	field: "description" | "parent",
-	flag: string,
-): ValidationResult | undefined {
-	const value = getOptionalNonEmptyString(params, field);
-	if (!value.ok) {
-		return value;
-	}
-	if (value.value !== undefined) {
-		argv.push(`${flag}=${value.value}`);
-	}
-	return undefined;
-}
-
-function requireNonEmptyString(
-	params: Readonly<Record<string, unknown>>,
-	field: string,
-):
-	| { readonly ok: true; readonly value: string }
-	| { readonly ok: false; readonly message: string } {
-	const value = params[field];
-	if (typeof value !== "string" || value.trim().length === 0) {
-		return { ok: false, message: `${field} is required` };
-	}
-	return { ok: true, value };
-}
-
-function getOptionalNonEmptyString(
-	params: Readonly<Record<string, unknown>>,
-	field: string,
-):
-	| { readonly ok: true; readonly value: string | undefined }
-	| { readonly ok: false; readonly message: string } {
-	const value = params[field];
-	if (value === undefined) {
-		return { ok: true, value: undefined };
-	}
-	if (typeof value !== "string") {
-		return { ok: false, message: `${field} must be a string` };
-	}
-	if (value.trim().length === 0) {
-		return { ok: true, value: undefined };
-	}
-	return { ok: true, value };
-}
-
-function requireInteger(
-	params: Readonly<Record<string, unknown>>,
-	field: string,
-):
-	| { readonly ok: true; readonly value: number }
-	| { readonly ok: false; readonly message: string } {
-	const value = params[field];
-	if (typeof value !== "number" || !Number.isInteger(value)) {
-		return { ok: false, message: `${field} is required` };
-	}
-	return { ok: true, value };
-}
-
-function getOptionalBoolean(
-	params: Readonly<Record<string, unknown>>,
-	field: string,
-):
-	| { readonly ok: true; readonly value: boolean | undefined }
-	| { readonly ok: false; readonly message: string } {
-	const value = params[field];
-	if (value === undefined) {
-		return { ok: true, value: undefined };
-	}
-	if (typeof value !== "boolean") {
-		return { ok: false, message: `${field} must be a boolean` };
-	}
-	return { ok: true, value };
-}
-
-function isTsqChangeAction(value: unknown): value is TsqChangeAction {
-	return (
-		typeof value === "string" &&
-		(TSQ_CHANGE_ACTIONS as readonly string[]).includes(value)
-	);
-}
-
 function validationErrorResult(message: string) {
 	return textToolResult(
 		`Error: ${message}`,
@@ -602,13 +301,6 @@ function extractTaskLike(result: unknown): {
 	};
 }
 
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		return undefined;
-	}
-	return value as Record<string, unknown>;
-}
-
 function getErrorMessage(error: unknown): string {
 	if (error instanceof Error) {
 		return error.message;
@@ -635,22 +327,3 @@ function serializeError(error: unknown): Record<string, unknown> {
 	}
 	return { value: String(error) };
 }
-
-function copyKnownErrorFields(error: Error): Record<string, unknown> {
-	const record = error as unknown as Record<string, unknown>;
-	const output: Record<string, unknown> = {};
-	for (const key of [
-		"code",
-		"command",
-		"details",
-		"stderr",
-		"stdout",
-		"killed",
-		"args",
-	] as const) {
-		if (record[key] !== undefined) {
-			output[key] = record[key];
-		}
-	}
-	return output;
-}

package/src/durable-tasks/tools-claim.ts

@@ -15,6 +15,11 @@ import {
 } from "../session-todos/state/state-reducer.js";
 import { commitState, getState } from "../session-todos/state/store.js";
 import type { Task } from "../session-todos/tool/types.js";
+import {
+	asRecord,
+	copyKnownErrorFields,
+	isRecord,
+} from "../shared/error-utils.js";
 import {
 	errorToolDetails,
 	okToolDetails,
@@ -391,33 +396,3 @@ function serializeError(error: unknown): Record<string, unknown> {
 	}
 	return { value: String(error) };
 }
-
-function copyKnownErrorFields(error: Error): Record<string, unknown> {
-	const record = error as unknown as Record<string, unknown>;
-	const output: Record<string, unknown> = {};
-	for (const key of [
-		"code",
-		"command",
-		"details",
-		"stderr",
-		"stdout",
-		"killed",
-		"args",
-	] as const) {
-		if (record[key] !== undefined) {
-			output[key] = record[key];
-		}
-	}
-	return output;
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		return undefined;
-	}
-	return value as Record<string, unknown>;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return asRecord(value) !== undefined;
-}

package/src/durable-tasks/tools-handoff.ts

@@ -0,0 +1,95 @@
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { errorToolDetails, textToolResult } from "../shared/tool-result.js";
+import {
+	collectHandoffStatus,
+	type HandoffCheckResult,
+} from "./handoff-guard.js";
+
+export async function executeHandoffCheck(
+	pi: ExtensionAPI,
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+): Promise<AgentToolResult<unknown>> {
+	const result = await collectHandoffStatus({
+		pi,
+		cwd: ctx.cwd,
+		...(signal != null ? { signal } : {}),
+	});
+
+	if (!result.ok) {
+		return textToolResult(
+			`Error: ${result.message}`,
+			errorToolDetails({ code: result.code, message: result.message }),
+		);
+	}
+
+	return textToolResult(formatHandoffText(result), {
+		ok: true,
+		ready: result.ready,
+		...formatHandoffDetails(result),
+	});
+}
+
+function formatHandoffText(result: HandoffCheckResult & { ok: true }): string {
+	const lines: string[] = [
+		result.ready
+			? "Handoff ready: all session todos complete and linked tasks resolved."
+			: "Handoff not ready.",
+	];
+
+	if ("todoBlockers" in result && result.todoBlockers?.length) {
+		lines.push("", "Todo blockers:");
+		for (const b of result.todoBlockers) {
+			lines.push(`- #${b.todoId} "${b.subject}" — ${b.reason}`);
+		}
+	}
+
+	if ("linkedBlockers" in result && result.linkedBlockers?.length) {
+		lines.push("", "Linked task blockers:");
+		for (const b of result.linkedBlockers) {
+			lines.push(`- ${b.tsqId} (todo #${b.todoId}) — ${b.status}`);
+		}
+	}
+
+	if ("linkedWarnings" in result && result.linkedWarnings?.length) {
+		lines.push("", "Warnings:");
+		for (const w of result.linkedWarnings) {
+			lines.push(`- ${w.tsqId} (todo #${w.todoId}) — ${w.status}`);
+		}
+	}
+
+	if ("readErrors" in result && result.readErrors?.length) {
+		lines.push("", "Read errors:");
+		for (const e of result.readErrors) {
+			lines.push(`- ${e.tsqId} — ${e.code}: ${e.message}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+function formatHandoffDetails(
+	result: HandoffCheckResult & { ok: true },
+): Record<string, unknown> {
+	const details: Record<string, unknown> = {};
+	if (result.projectRoot !== undefined) {
+		details.projectRoot = result.projectRoot;
+	}
+	if ("todoBlockers" in result && result.todoBlockers?.length) {
+		details.todoBlockers = result.todoBlockers;
+	}
+	if ("linkedBlockers" in result && result.linkedBlockers?.length) {
+		details.linkedBlockers = result.linkedBlockers;
+	}
+	if ("linkedWarnings" in result && result.linkedWarnings?.length) {
+		details.linkedWarnings = result.linkedWarnings;
+	}
+	if ("readErrors" in result && result.readErrors?.length) {
+		details.readErrors = result.readErrors;
+	}
+	return details;
+}

package/src/durable-tasks/tools-query.ts

@@ -9,6 +9,7 @@ import {
 	READ_TASKS_PROMPT_GUIDELINES,
 	READ_TASKS_PROMPT_SNIPPET,
 } from "../guidelines/internal-tools.js";
+import { isRecord } from "../shared/error-utils.js";
 import { truncatedTextToolResult } from "../shared/tool-result.js";
 import type { TruncatedText } from "../shared/truncation.js";
 import { runTsqJson } from "./runner.js";
@@ -522,7 +523,3 @@ function isTaskTreeNode(value: unknown): value is TsqTaskTreeNode {
 		isRecord(value) && isTsqTask(value.task) && Array.isArray(value.children)
 	);
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/durable-tasks/tools-tree-create.ts

@@ -17,6 +17,7 @@ import type {
 import type { CreateTreeNode, CreateTreeResult } from "./bulk-contract.js";
 import { runQueuedMutation } from "./mutation-queue.js";
 import { runTsqJson } from "./runner.js";
+import { asRecord } from "../shared/error-utils.js";
 import {
 	okToolDetails,
 	textToolResult,
@@ -218,10 +219,3 @@ function formatResultText(result: CreateTreeResult): string {
 function getErrorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		return undefined;
-	}
-	return value as Record<string, unknown>;
-}