@bumpyclock/pi-tasque 0.1.0 → 0.2.0

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

@@ -0,0 +1,176 @@
+/**
+ * Public contract types and validation for `bulk` and `create_tree` task actions.
+ *
+ * Defines the input shapes, validates them eagerly, and exports result type
+ * scaffolds used by the separate bulk and create-tree executors. Dispatch
+ * happens in the unified task tool.
+ */
+
+// ── Bulk item contract ─────────────────────────────────────────────
+
+export const BULK_ITEM_ACTIONS = [
+	"start",
+	"finish",
+	"reopen",
+	"defer",
+	"note",
+	"mark_planned",
+] as const;
+
+export type BulkItemAction = (typeof BULK_ITEM_ACTIONS)[number];
+
+/** A single lifecycle/note mutation inside a `bulk` call. */
+export interface BulkItem {
+	/** Lifecycle or note action to run on the target task. */
+	readonly action: BulkItemAction;
+	/** Durable task id (e.g. "tsq-3"). */
+	readonly task: string;
+	/** Note/reason text — required for `note`, optional for `finish`/`defer`. */
+	readonly because?: string;
+}
+
+/** Result shape bulk executors will produce (tsq-6.2). */
+export interface BulkResult {
+	readonly completed: readonly string[];
+	readonly failed?: { readonly task: string; readonly error: string };
+	readonly skipped: readonly string[];
+}
+
+// ── Create-tree node contract ──────────────────────────────────────
+
+/** A node in the `create_tree` input. Recursive via `children`. */
+export interface CreateTreeNode {
+	readonly title: string;
+	readonly kind: string;
+	readonly priority: number;
+	readonly description?: string;
+	/** Mark this node as already planned. Contradicts `needsPlan`. */
+	readonly planned?: boolean;
+	/** Mark this node as needing planning. Contradicts `planned`. */
+	readonly needsPlan?: boolean;
+	readonly children?: readonly CreateTreeNode[];
+}
+
+/** Result shape tree executors will produce (tsq-6.3). */
+export interface CreateTreeResult {
+	readonly created: readonly { readonly id: string; readonly title: string }[];
+	readonly failed?: { readonly title: string; readonly error: string };
+	readonly skipped: readonly { readonly title: string }[];
+}
+
+// ── Validation ─────────────────────────────────────────────────────
+
+type Ok = { readonly ok: true };
+type Fail = { readonly ok: false; readonly message: string };
+type ValidationResult = Ok | Fail;
+
+const OK: Ok = { ok: true } as const;
+
+function fail(message: string): Fail {
+	return { ok: false, message };
+}
+
+/**
+ * Validate a `bulk` action's `items` array.
+ *
+ * Rejects: missing/empty array, missing action/task on any item,
+ * unsupported action values, missing `because` when action is `note`.
+ */
+export function validateBulkItems(items: unknown): ValidationResult {
+	if (!Array.isArray(items) || items.length === 0) {
+		return fail("items must be a non-empty array");
+	}
+
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i] as Record<string, unknown>;
+		const prefix = `items[${i}]`;
+
+		if (typeof item !== "object" || item === null || Array.isArray(item)) {
+			return fail(`${prefix} must be an object`);
+		}
+
+		const action = item.action;
+		if (typeof action !== "string" || action.trim().length === 0) {
+			return fail(`${prefix}.action is required`);
+		}
+		if (!(BULK_ITEM_ACTIONS as readonly string[]).includes(action)) {
+			return fail(
+				`${prefix}.action "${action}" is not supported; use one of: ${BULK_ITEM_ACTIONS.join(", ")}`,
+			);
+		}
+
+		const task = item.task;
+		if (typeof task !== "string" || task.trim().length === 0) {
+			return fail(`${prefix}.task is required`);
+		}
+
+		// `note` requires `because`
+		if (action === "note") {
+			const because = item.because;
+			if (typeof because !== "string" || because.trim().length === 0) {
+				return fail(`${prefix}.because is required when action is "note"`);
+			}
+		}
+	}
+
+	return OK;
+}
+
+/**
+ * Validate a `create_tree` action's `root` node, recursively.
+ *
+ * Rejects: missing title/kind/priority, contradictory planned+needsPlan,
+ * empty children arrays.
+ */
+export function validateCreateTreeNode(
+	node: unknown,
+	path = "root",
+): ValidationResult {
+	if (typeof node !== "object" || node === null || Array.isArray(node)) {
+		return fail(`${path} must be an object`);
+	}
+
+	const n = node as Record<string, unknown>;
+
+	// Required fields
+	if (typeof n.title !== "string" || n.title.trim().length === 0) {
+		return fail(`${path}.title is required`);
+	}
+	if (typeof n.kind !== "string" || n.kind.trim().length === 0) {
+		return fail(`${path}.kind is required`);
+	}
+	if (typeof n.priority !== "number" || !Number.isInteger(n.priority)) {
+		return fail(`${path}.priority is required`);
+	}
+
+	if (n.description !== undefined && typeof n.description !== "string") {
+		return fail(`${path}.description must be a string`);
+	}
+	if (n.planned !== undefined && typeof n.planned !== "boolean") {
+		return fail(`${path}.planned must be a boolean`);
+	}
+	if (n.needsPlan !== undefined && typeof n.needsPlan !== "boolean") {
+		return fail(`${path}.needsPlan must be a boolean`);
+	}
+
+	// Contradictory planning flags
+	if (n.planned === true && n.needsPlan === true) {
+		return fail(`${path}: planned and needsPlan cannot both be true`);
+	}
+
+	// Recursive children validation
+	if (n.children !== undefined) {
+		if (!Array.isArray(n.children) || n.children.length === 0) {
+			return fail(`${path}.children must be a non-empty array when provided`);
+		}
+		for (let i = 0; i < n.children.length; i++) {
+			const childResult = validateCreateTreeNode(
+				n.children[i],
+				`${path}.children[${i}]`,
+			);
+			if (!childResult.ok) return childResult;
+		}
+	}
+
+	return OK;
+}

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/status.ts

@@ -8,10 +8,11 @@ import {
 	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 +57,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 +193,10 @@ function hasStatusUi(ctx: ExtensionContext): boolean {
 	);
 }
 
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }