@bumpyclock/pi-tasque 0.1.0 → 0.2.1

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

@@ -0,0 +1,329 @@
+/**
+ * Read-only handoff readiness checker.
+ *
+ * Collects session todo state and linked durable task statuses to produce a
+ * structured ready/not-ready report. Never mutates session todos or durable
+ * task state. Uses only read-only `show` CLI calls for linked tasks.
+ *
+ * @module
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { deriveTaskLinks } from "../bridge/link-store.js";
+import { selectVisibleTasks } from "../session-todos/state/selectors.js";
+import { getState } from "../session-todos/state/store.js";
+import type { Task } from "../session-todos/tool/types.js";
+import { resolveProjectRoot } from "./project.js";
+import { TsqCommandError, TsqProcessError, runTsqJson } from "./runner.js";
+import type { TsqShowData, TsqTaskStatus } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Status classification
+// ---------------------------------------------------------------------------
+
+/** Durable task statuses that count as "ready" (work complete). */
+const READY_STATUSES: ReadonlySet<TsqTaskStatus> = new Set(["closed"]);
+
+/** Durable task statuses that count as "warning" (not blocking). */
+const WARNING_STATUSES: ReadonlySet<TsqTaskStatus> = new Set(["canceled"]);
+
+/**
+ * Classify a durable task status for handoff readiness.
+ *
+ * - `"ready"` — closed, work done.
+ * - `"blocker"` — open/in_progress/blocked/deferred/unknown/missing.
+ * - `"warning"` — canceled (notable but not blocking).
+ */
+export function classifyDurableStatus(
+	status: string | undefined | null,
+): "ready" | "blocker" | "warning" {
+	if (status == null || status.trim().length === 0) return "blocker";
+	if (READY_STATUSES.has(status)) return "ready";
+	if (WARNING_STATUSES.has(status)) return "warning";
+	return "blocker";
+}
+
+// ---------------------------------------------------------------------------
+// Read-error classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Error codes from linked `tsq show` that are *actionable* (user can fix them)
+ * rather than infrastructure failures. These become `ok:true, ready:false` with
+ * structured `readErrors`, not `ok:false`.
+ */
+const ACTIONABLE_ERROR_CODES: ReadonlySet<string> = new Set([
+	"not_found",
+	"task_not_found",
+	"validation_error",
+	"read_error",
+]);
+
+/**
+ * Classify a tsq CLI error code from a linked `show` call.
+ *
+ * - `"actionable"` — not-found, validation, read-envelope → ok:true, ready:false
+ * - `"internal"` — process/timeout/abort/invalid-JSON → ok:false
+ */
+export function classifyReadError(code: string): "actionable" | "internal" {
+	return ACTIONABLE_ERROR_CODES.has(code.toLowerCase())
+		? "actionable"
+		: "internal";
+}
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+export interface HandoffTodoBlocker {
+	readonly todoId: number;
+	readonly subject: string;
+	readonly status: string;
+	readonly reason: string;
+}
+
+export interface HandoffLinkedBlocker {
+	readonly todoId: number;
+	readonly tsqId: string;
+	readonly status: string;
+	readonly classification: "blocker" | "warning";
+}
+
+export interface HandoffReadError {
+	readonly tsqId: string;
+	readonly code: string;
+	readonly message: string;
+}
+
+export interface HandoffReadyResult {
+	readonly ok: true;
+	readonly ready: true;
+	readonly projectRoot?: string;
+}
+
+export interface HandoffNotReadyResult {
+	readonly ok: true;
+	readonly ready: false;
+	readonly projectRoot?: string;
+	readonly todoBlockers?: readonly HandoffTodoBlocker[];
+	readonly linkedBlockers?: readonly HandoffLinkedBlocker[];
+	readonly linkedWarnings?: readonly HandoffLinkedBlocker[];
+	readonly readErrors?: readonly HandoffReadError[];
+}
+
+export interface HandoffInternalError {
+	readonly ok: false;
+	readonly code: string;
+	readonly message: string;
+}
+
+export type HandoffCheckResult =
+	| HandoffReadyResult
+	| HandoffNotReadyResult
+	| HandoffInternalError;
+
+// ---------------------------------------------------------------------------
+// Collector options
+// ---------------------------------------------------------------------------
+
+export interface CollectHandoffOptions {
+	readonly pi: ExtensionAPI;
+	readonly cwd: string;
+	readonly signal?: AbortSignal;
+}
+
+// ---------------------------------------------------------------------------
+// Collector implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect handoff readiness from session todo state and linked durable tasks.
+ *
+ * Read-only: never mutates session todos or durable task state.
+ * Only uses `tsq show <id>` (read-only) for linked tasks.
+ */
+export async function collectHandoffStatus(
+	options: CollectHandoffOptions,
+): Promise<HandoffCheckResult> {
+	const { pi, cwd, signal } = options;
+
+	// 1. Read session todo state (snapshot, no mutation)
+	const state = getState();
+	const visibleTodos = selectVisibleTasks(state);
+
+	// 2. Collect todo blockers
+	const todoBlockers = collectTodoBlockers(visibleTodos);
+
+	// 3. Derive todo↔task links
+	const links = deriveTaskLinks(state);
+
+	// 4. If links exist, resolve project root and read linked task statuses
+	if (links.length > 0) {
+		let projectRoot: string;
+		try {
+			projectRoot = await resolveProjectRoot(
+				pi,
+				cwd,
+				signal != null ? { signal } : {},
+			);
+		} catch (err) {
+			return {
+				ok: false,
+				code: "project_resolution_error",
+				message:
+					err instanceof Error ? err.message : "Unable to resolve project root",
+			};
+		}
+
+		const linkedBlockers: HandoffLinkedBlocker[] = [];
+		const linkedWarnings: HandoffLinkedBlocker[] = [];
+		const readErrors: HandoffReadError[] = [];
+
+		for (const link of links) {
+			const result = await readLinkedTaskStatus(
+				pi,
+				projectRoot,
+				link.tsqId,
+				link.todoId,
+				signal,
+			);
+
+			if (result.type === "internal_error") {
+				return { ok: false, code: result.code, message: result.message };
+			}
+			if (result.type === "read_error") {
+				readErrors.push(result.error);
+			} else if (result.type === "blocker") {
+				linkedBlockers.push(result.entry);
+			} else if (result.type === "warning") {
+				linkedWarnings.push(result.entry);
+			}
+			// "ready" → no action needed
+		}
+
+		const hasBlockers =
+			todoBlockers.length > 0 ||
+			linkedBlockers.length > 0 ||
+			readErrors.length > 0;
+		const hasWarnings = linkedWarnings.length > 0;
+
+		if (!hasBlockers && !hasWarnings) {
+			return { ok: true, ready: true, projectRoot };
+		}
+
+		return {
+			ok: true,
+			ready: !hasBlockers,
+			projectRoot,
+			...(todoBlockers.length > 0 ? { todoBlockers } : {}),
+			...(linkedBlockers.length > 0 ? { linkedBlockers } : {}),
+			...(linkedWarnings.length > 0 ? { linkedWarnings } : {}),
+			...(readErrors.length > 0 ? { readErrors } : {}),
+		} as HandoffCheckResult;
+	}
+
+	// No links: todo-only readiness (no git root needed)
+	if (todoBlockers.length > 0) {
+		return { ok: true, ready: false, todoBlockers };
+	}
+
+	return { ok: true, ready: true };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function collectTodoBlockers(todos: readonly Task[]): HandoffTodoBlocker[] {
+	const blockers: HandoffTodoBlocker[] = [];
+
+	for (const todo of todos) {
+		if (todo.status === "pending") {
+			const hasUnresolvedBlockers =
+				todo.blockedBy != null && todo.blockedBy.length > 0;
+			blockers.push({
+				todoId: todo.id,
+				subject: todo.subject,
+				status: "pending",
+				reason: hasUnresolvedBlockers ? "blocked" : "pending",
+			});
+		} else if (todo.status === "in_progress") {
+			blockers.push({
+				todoId: todo.id,
+				subject: todo.subject,
+				status: "in_progress",
+				reason: "in_progress",
+			});
+		}
+	}
+
+	return blockers;
+}
+
+type LinkedReadResult =
+	| { type: "ready" }
+	| { type: "blocker"; entry: HandoffLinkedBlocker }
+	| { type: "warning"; entry: HandoffLinkedBlocker }
+	| { type: "read_error"; error: HandoffReadError }
+	| { type: "internal_error"; code: string; message: string };
+
+async function readLinkedTaskStatus(
+	pi: ExtensionAPI,
+	projectRoot: string,
+	tsqId: string,
+	todoId: number,
+	signal?: AbortSignal,
+): Promise<LinkedReadResult> {
+	try {
+		const data = await runTsqJson<TsqShowData>(
+			pi,
+			{ cwd: projectRoot },
+			["show", tsqId],
+			signal != null ? { signal } : {},
+		);
+
+		const status = data.task?.status;
+		const classification = classifyDurableStatus(status);
+
+		if (classification === "ready") return { type: "ready" };
+
+		return {
+			type: classification,
+			entry: {
+				todoId,
+				tsqId,
+				status: status ?? "unknown",
+				classification,
+			},
+		};
+	} catch (err) {
+		if (err instanceof TsqCommandError) {
+			const errClass = classifyReadError(err.code);
+			if (errClass === "actionable") {
+				return {
+					type: "read_error",
+					error: { tsqId, code: err.code, message: err.message },
+				};
+			}
+			return {
+				type: "internal_error",
+				code: err.code,
+				message: err.message,
+			};
+		}
+
+		if (err instanceof TsqProcessError) {
+			return {
+				type: "internal_error",
+				code: "process_error",
+				message: err.message,
+			};
+		}
+
+		return {
+			type: "internal_error",
+			code: "unknown",
+			message: err instanceof Error ? err.message : "Unknown error",
+		};
+	}
+}

package/src/durable-tasks/project.ts

@@ -0,0 +1,71 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_GIT_TIMEOUT_MS = 5_000;
+
+export interface ProjectResolutionOptions {
+	readonly signal?: AbortSignal;
+	readonly timeout?: number;
+}
+
+export class ProjectResolutionError extends Error {
+	override readonly name = "ProjectResolutionError";
+	readonly cwd: string;
+	readonly code: number;
+	readonly stderr: string;
+	readonly stdout: string;
+	readonly killed: boolean;
+
+	constructor(
+		cwd: string,
+		result: {
+			readonly code: number;
+			readonly stderr: string;
+			readonly stdout: string;
+			readonly killed: boolean;
+		},
+	) {
+		super(buildProjectResolutionMessage(cwd, result));
+		this.cwd = cwd;
+		this.code = result.code;
+		this.stderr = result.stderr;
+		this.stdout = result.stdout;
+		this.killed = result.killed;
+	}
+}
+
+export async function resolveProjectRoot(
+	pi: ExtensionAPI,
+	cwd: string,
+	options: ProjectResolutionOptions = {},
+): Promise<string> {
+	const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], {
+		cwd,
+		timeout: options.timeout ?? DEFAULT_GIT_TIMEOUT_MS,
+		...(options.signal === undefined ? {} : { signal: options.signal }),
+	});
+
+	const projectRoot = result.stdout.trim();
+	if (result.code !== 0 || result.killed || projectRoot.length === 0) {
+		throw new ProjectResolutionError(cwd, result);
+	}
+
+	return projectRoot;
+}
+
+function buildProjectResolutionMessage(
+	cwd: string,
+	result: {
+		readonly code: number;
+		readonly stderr: string;
+		readonly stdout: string;
+		readonly killed: boolean;
+	},
+): string {
+	if (result.killed) {
+		return `Unable to resolve Tasque project root from ${cwd}: git rev-parse timed out`;
+	}
+	const detail = (result.stderr || result.stdout).replace(/\s+/gu, " ").trim();
+	return detail.length === 0
+		? `Unable to resolve Tasque project root from ${cwd}`
+		: `Unable to resolve Tasque project root from ${cwd}: ${detail}`;
+}

package/src/durable-tasks/runner.ts

@@ -3,6 +3,7 @@ import type {
 	ExecResult,
 	ExtensionAPI,
 } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "../shared/error-utils.js";
 import {
 	TSQ_SCHEMA_VERSION,
 	type JsonValue,
@@ -228,7 +229,3 @@ function buildProcessErrorMessage(result: ExecResult): string {
 	}
 	return `tsq failed with exit code ${result.code}${killed}: ${summary}`;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/durable-tasks/status.ts

@@ -2,16 +2,18 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "../shared/error-utils.js";
 import {
 	createTasqueStatusCache,
 	formatTasqueStatusText,
 	refreshTasqueStatusCache,
 	type TasqueStatusCache,
 } from "./cache.js";
+import { resolveProjectRoot } from "./project.js";
 
 export const TASQUE_STATUS_KEY = "pi-tasque";
 
-const MUTATING_TOOL_NAMES = new Set(["tsq_change", "tsq_claim", "task_bridge"]);
+const MUTATING_TOOL_NAMES = new Set(["task"]);
 const DEFAULT_INTERVAL_MS = 60_000;
 
 export interface TasqueStatusLifecycleOptions {
@@ -56,12 +58,25 @@ export function registerTasqueStatusLifecycle(
 		}
 
 		let refreshPromise: Promise<void>;
-		refreshPromise = refreshTasqueStatusCache(pi, { cwd: ctx.cwd }, cache, {
-			...(options.now === undefined ? {} : { now: options.now }),
+		refreshPromise = resolveProjectRoot(pi, ctx.cwd, {
 			...(options.refreshTimeoutMs === undefined
 				? {}
 				: { timeout: options.refreshTimeoutMs }),
 		})
+			.then((projectRoot) =>
+				refreshTasqueStatusCache(pi, { cwd: projectRoot }, cache, {
+					...(options.now === undefined ? {} : { now: options.now }),
+					...(options.refreshTimeoutMs === undefined
+						? {}
+						: { timeout: options.refreshTimeoutMs }),
+				}),
+			)
+			.catch((error) =>
+				createTasqueStatusCache({
+					...cache.state,
+					error: getErrorMessage(error),
+				}),
+			)
 			.then((nextCache) => {
 				if (!statusActive || generation !== lifecycleGeneration) {
 					return;
@@ -179,6 +194,6 @@ function hasStatusUi(ctx: ExtensionContext): boolean {
 	);
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
 }

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

@@ -0,0 +1,160 @@
+import type { TaskBridgeParams } from "../bridge/types.js";
+import { definedParams } from "../shared/validation.js";
+import type { TaskParams } from "./task-schema.js";
+import { getTodoId, hasWith } from "./task-validation.js";
+import type { TsqChangeParams } from "./tools-change.js";
+import type { TsqQueryParams } from "./tools-query.js";
+
+export function toQueryParams(params: TaskParams): TsqQueryParams {
+	switch (params.action) {
+		case "doctor":
+			return { action: "doctor" };
+		case "find":
+			if (params.view === "tree") {
+				return definedParams<TsqQueryParams>({
+					action: "find_tree",
+					id: params.task,
+				});
+			}
+			return params.tasks === "open"
+				? definedParams<TsqQueryParams>({
+						action: "find_open",
+						assignee: params.for,
+					})
+				: definedParams<TsqQueryParams>({
+						action: "find_ready",
+						lane: params.lane,
+						assignee: params.for,
+					});
+		case "show":
+			return definedParams<TsqQueryParams>({
+				action: hasWith(params, "spec") ? "show_with_spec" : "show",
+				id: params.task,
+			});
+		case "deps":
+			return definedParams<TsqQueryParams>({ action: "deps", id: params.task });
+		case "notes":
+			return definedParams<TsqQueryParams>({
+				action: "notes",
+				id: params.task,
+			});
+		case "similar":
+			return definedParams<TsqQueryParams>({
+				action: "similar",
+				query: params.query,
+			});
+		default:
+			throw new Error(`Unsupported query action: ${params.action}`);
+	}
+}
+
+export function toChangeParams(params: TaskParams): TsqChangeParams {
+	switch (params.action) {
+		case "create":
+			return definedParams<TsqChangeParams>({
+				action: "create",
+				title: params.task,
+				kind: params.kind,
+				priority: params.priority,
+				description: params.description,
+				parent: params.under,
+				planned: params.planned,
+				needsPlan: params.needsPlan,
+			});
+		case "note":
+			return definedParams<TsqChangeParams>({
+				action: "note",
+				id: params.task,
+				note: params.because,
+			});
+		case "finish":
+			return definedParams<TsqChangeParams>({
+				action: "done",
+				id: params.task,
+				note: params.because,
+			});
+		case "reopen":
+		case "start":
+			return definedParams<TsqChangeParams>({
+				action: params.action,
+				id: params.task,
+			});
+		case "defer":
+			return definedParams<TsqChangeParams>({
+				action: "defer",
+				id: params.task,
+				note: params.because,
+			});
+		case "block":
+			return definedParams<TsqChangeParams>({
+				action: "block",
+				child: params.task,
+				blocker: params.by,
+			});
+		case "unblock":
+			return definedParams<TsqChangeParams>({
+				action: "unblock",
+				child: params.task,
+				blocker: params.by,
+			});
+		case "order":
+			return definedParams<TsqChangeParams>({
+				action: "order",
+				later: params.task,
+				earlier: params.after,
+			});
+		case "unorder":
+			return definedParams<TsqChangeParams>({
+				action: "unorder",
+				later: params.task,
+				earlier: params.after,
+			});
+		default:
+			throw new Error(`Unsupported change action: ${params.action}`);
+	}
+}
+
+export function toClaimParams(
+	params: TaskParams,
+): Readonly<Record<string, unknown>> {
+	return definedParams<Readonly<Record<string, unknown>>>({
+		id: params.task,
+		assignee: params.for,
+		start: params.start,
+		requireSpec: params.requireSpec,
+		createTodo: params.todo === true,
+	});
+}
+
+export function toBridgeParams(params: TaskParams): TaskBridgeParams {
+	switch (params.action) {
+		case "link":
+			return definedParams<TaskBridgeParams>({
+				action: "link",
+				todoId: getTodoId(params.todo),
+				tsqId: params.task,
+			});
+		case "list_links":
+			return { action: "list_links" };
+		case "promote":
+			return definedParams<TaskBridgeParams>({
+				action: "promote_todo",
+				todoId: getTodoId(params.todo),
+				assignee: params.for,
+				kind: params.kind,
+				priority: params.priority,
+				description: params.description,
+				parent: params.under,
+				planned: params.planned,
+				needsPlan: params.needsPlan,
+			});
+		case "import":
+			return definedParams<TaskBridgeParams>({
+				action: "import_tsq",
+				tsqId: params.task,
+				owner: params.for,
+			});
+		default:
+			throw new Error(`Unsupported bridge action: ${params.action}`);
+	}
+}