@bumpyclock/pi-tasque 0.1.0 → 0.2.1

package/src/bridge/types.ts

@@ -23,61 +23,60 @@ export const TaskBridgeParamsSchema = Type.Object(
 	{
 		action: StringEnum(TASK_BRIDGE_ACTIONS, {
 			description:
-				"Explicit bridge operation between session todo state and durable Tasque tasks.",
+				"Explicit bridge operation between session todo state and durable tasks.",
 		}),
 		todoId: Type.Optional(
 			Type.Integer({
 				description:
-					"Session todo id. Required for link and promote_todo actions.",
+					"Session todo id. Required when linking or promoting a todo.",
 				minimum: 1,
 			}),
 		),
 		tsqId: Type.Optional(
 			Type.String({
 				description:
-					"Durable Tasque task id. Required for link and import_tsq actions.",
+					"Durable task id. Required when linking or importing a task.",
 			}),
 		),
 		assignee: Type.Optional(
 			Type.String({
 				description:
-					"Agent/owner name used by promote_todo/import_tsq bridge actions.",
+					"Agent/owner name used when creating or importing linked task todos.",
 			}),
 		),
 		owner: Type.Optional(
 			Type.String({
-				description: "Todo owner used by import_tsq bridge action.",
+				description: "Todo owner used when importing a durable task.",
 			}),
 		),
 		kind: Type.Optional(
 			Type.String({
-				description: "Tasque task kind used by promote_todo bridge action.",
+				description: "Durable task kind used when promoting a todo.",
 			}),
 		),
 		priority: Type.Optional(
 			Type.Integer({
-				description: "Tasque priority used by promote_todo bridge action.",
+				description: "Durable task priority used when promoting a todo.",
 			}),
 		),
 		description: Type.Optional(
 			Type.String({
-				description: "Description override used by promote_todo bridge action.",
+				description: "Description override used when promoting a todo.",
 			}),
 		),
 		parent: Type.Optional(
 			Type.String({
-				description:
-					"Parent Tasque task id used by promote_todo bridge action.",
+				description: "Parent durable task id used when promoting a todo.",
 			}),
 		),
 		planned: Type.Optional(
 			Type.Boolean({
-				description: "Planning flag used by promote_todo bridge action.",
+				description: "Planning flag used when promoting a todo.",
 			}),
 		),
 		needsPlan: Type.Optional(
 			Type.Boolean({
-				description: "Planning flag used by promote_todo bridge action.",
+				description: "Planning flag used when promoting a todo.",
 			}),
 		),
 	},

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

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "../shared/error-utils.js";
 import { runTsqJson, type TsqRunContext } from "./runner.js";
 
 export interface TasqueStatusCacheState {
@@ -161,7 +162,3 @@ function truncateInline(text: string, maxLength: number): string {
 	}
 	return `${text.slice(0, Math.max(0, maxLength - 1))}…`;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/durable-tasks/change-command-builder.ts

@@ -0,0 +1,315 @@
+export 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 ValidationResult =
+	| {
+			readonly ok: true;
+			readonly action: TsqChangeAction;
+			readonly argv: string[];
+	  }
+	| { readonly ok: false; readonly message: string };
+
+export 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");
+	}
+}
+
+export function isTsqChangeAction(value: unknown): value is TsqChangeAction {
+	return (
+		typeof value === "string" &&
+		(TSQ_CHANGE_ACTIONS as readonly string[]).includes(value)
+	);
+}
+
+// --- argv builders ---
+
+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;
+}
+
+// --- validation helpers (params+field pattern, specific to builders) ---
+
+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 };
+}