@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/domains/user-tasks/store.ts

@@ -0,0 +1,297 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CLIO_PROJECT_DIR } from "../../core/artifact-paths.js";
+import { atomicWrite } from "../../engine/session.js";
+
+export const USER_TASKS_FILE_VERSION = 1 as const;
+export const USER_TASKS_RELATIVE_PATH = `${CLIO_PROJECT_DIR}/user-tasks.json`;
+
+export type UserTaskStatus = "open" | "handed" | "picked" | "done" | "dropped";
+
+export interface UserTask {
+	id: string;
+	title: string;
+	note?: string;
+	status: UserTaskStatus;
+	createdAt: string;
+	updatedAt: string;
+	handedSessionId?: string;
+	boardTaskId?: string;
+}
+
+interface UserTasksFile {
+	version: typeof USER_TASKS_FILE_VERSION;
+	nextId: number;
+	tasks: UserTask[];
+}
+
+export interface UserTasksStoreDeps {
+	cwd: string;
+	now?: () => Date;
+	exists?: (path: string) => boolean;
+	read?: (path: string) => string;
+	write?: (path: string, body: string) => void;
+}
+
+export interface UserTasksStore {
+	readonly path: string;
+	snapshot(): ReadonlyArray<UserTask>;
+	get(id: string): UserTask | null;
+	add(title: string, note?: string): UserTask;
+	hand(id: string, sessionId?: string): UserTask;
+	done(id: string): UserTask;
+	drop(id: string): UserTask;
+	recordPicked(id: string, sessionId: string, boardTaskId: string): UserTask;
+	recordDone(id: string, sessionId: string, boardTaskId: string): UserTask;
+	reconcile(links: ReadonlyArray<UserTaskBoardLink>, sessionId: string): ReadonlyArray<UserTask>;
+}
+
+export interface UserTaskBoardLink {
+	userTaskId: string;
+	boardTaskId: string;
+	status: "pending" | "active" | "completed" | "blocked" | "cancelled";
+}
+
+export class UserTasksStoreError extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "UserTasksStoreError";
+	}
+}
+
+const USER_TASK_STATUSES: ReadonlyArray<UserTaskStatus> = ["open", "handed", "picked", "done", "dropped"];
+const FILE_KEYS = new Set(["version", "nextId", "tasks"]);
+const TASK_KEYS = new Set([
+	"id",
+	"title",
+	"note",
+	"status",
+	"createdAt",
+	"updatedAt",
+	"handedSessionId",
+	"boardTaskId",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
+	return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function isOptionalString(value: unknown): boolean {
+	return value === undefined || typeof value === "string";
+}
+
+function isUserTask(value: unknown): value is UserTask {
+	if (!isRecord(value) || !hasOnlyKeys(value, TASK_KEYS)) return false;
+	return (
+		typeof value.id === "string" &&
+		/^u[1-9]\d*$/.test(value.id) &&
+		typeof value.title === "string" &&
+		value.title.trim().length > 0 &&
+		typeof value.status === "string" &&
+		USER_TASK_STATUSES.includes(value.status as UserTaskStatus) &&
+		typeof value.createdAt === "string" &&
+		typeof value.updatedAt === "string" &&
+		isOptionalString(value.note) &&
+		isOptionalString(value.handedSessionId) &&
+		isOptionalString(value.boardTaskId)
+	);
+}
+
+function parseFile(body: string, path: string): UserTasksFile {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(body);
+	} catch (error) {
+		throw new UserTasksStoreError(`user tasks file is corrupt JSON: ${path}`, { cause: error });
+	}
+	if (!isRecord(parsed) || !hasOnlyKeys(parsed, FILE_KEYS)) {
+		throw new UserTasksStoreError(`user tasks file has an invalid top-level shape: ${path}`);
+	}
+	if (
+		parsed.version !== USER_TASKS_FILE_VERSION ||
+		!Number.isSafeInteger(parsed.nextId) ||
+		(parsed.nextId as number) < 1 ||
+		!Array.isArray(parsed.tasks) ||
+		!parsed.tasks.every(isUserTask)
+	) {
+		throw new UserTasksStoreError(`user tasks file failed schema validation: ${path}`);
+	}
+	const ids = new Set<string>();
+	let maxId = 0;
+	for (const task of parsed.tasks) {
+		if (ids.has(task.id)) throw new UserTasksStoreError(`user tasks file contains duplicate id ${task.id}: ${path}`);
+		ids.add(task.id);
+		maxId = Math.max(maxId, Number(task.id.slice(1)));
+	}
+	if ((parsed.nextId as number) <= maxId) {
+		throw new UserTasksStoreError(`user tasks file nextId would reuse an existing id: ${path}`);
+	}
+	return {
+		version: USER_TASKS_FILE_VERSION,
+		nextId: parsed.nextId as number,
+		tasks: parsed.tasks.map(copyTask),
+	};
+}
+
+function copyTask(task: UserTask): UserTask {
+	return { ...task };
+}
+
+function initialFile(): UserTasksFile {
+	return { version: USER_TASKS_FILE_VERSION, nextId: 1, tasks: [] };
+}
+
+export function createUserTasksStore(deps: UserTasksStoreDeps): UserTasksStore {
+	const path = join(deps.cwd, USER_TASKS_RELATIVE_PATH);
+	const exists = deps.exists ?? existsSync;
+	const read = deps.read ?? ((target: string) => readFileSync(target, "utf8"));
+	const write = deps.write ?? ((target: string, body: string) => atomicWrite(target, body));
+	const now = (): string => (deps.now?.() ?? new Date()).toISOString();
+
+	const load = (): UserTasksFile => {
+		if (!exists(path)) return initialFile();
+		try {
+			return parseFile(read(path), path);
+		} catch (error) {
+			if (error instanceof UserTasksStoreError) throw error;
+			throw new UserTasksStoreError(`could not read user tasks file: ${path}`, { cause: error });
+		}
+	};
+
+	const save = (file: UserTasksFile): void => {
+		try {
+			write(path, `${JSON.stringify(file, null, 2)}\n`);
+		} catch (error) {
+			throw new UserTasksStoreError(`could not write user tasks file: ${path}`, { cause: error });
+		}
+	};
+
+	const mutate = (
+		id: string,
+		allowed: ReadonlyArray<UserTaskStatus>,
+		status: UserTaskStatus,
+		sessionId?: string,
+	): UserTask => {
+		const file = load();
+		const index = file.tasks.findIndex((task) => task.id === id);
+		const current = file.tasks[index];
+		if (!current) throw new UserTasksStoreError(`operator task ${id} was not found`);
+		if (!allowed.includes(current.status)) {
+			throw new UserTasksStoreError(`operator task ${id} is ${current.status}; it cannot move to ${status}`);
+		}
+		const updated: UserTask = { ...current, status, updatedAt: now() };
+		if (status === "handed" && sessionId) updated.handedSessionId = sessionId;
+		file.tasks[index] = updated;
+		save(file);
+		return copyTask(updated);
+	};
+
+	const recordLink = (id: string, status: "picked" | "done", sessionId: string, boardTaskId: string): UserTask => {
+		const file = load();
+		const index = file.tasks.findIndex((task) => task.id === id);
+		const current = file.tasks[index];
+		if (!current) throw new UserTasksStoreError(`operator task ${id} was not found`);
+		if (current.status === "done" || current.status === "dropped") {
+			throw new UserTasksStoreError(`operator task ${id} is ${current.status}; it cannot move to ${status}`);
+		}
+		const updated: UserTask = {
+			...current,
+			status,
+			updatedAt: now(),
+			handedSessionId: sessionId,
+			boardTaskId,
+		};
+		file.tasks[index] = updated;
+		save(file);
+		return copyTask(updated);
+	};
+
+	return {
+		path,
+		snapshot(): ReadonlyArray<UserTask> {
+			return load().tasks.map(copyTask);
+		},
+		get(id: string): UserTask | null {
+			const task = load().tasks.find((candidate) => candidate.id === id);
+			return task ? copyTask(task) : null;
+		},
+		add(title: string, note?: string): UserTask {
+			const normalizedTitle = title.trim();
+			if (normalizedTitle.length === 0) throw new UserTasksStoreError("operator task title cannot be empty");
+			const normalizedNote = note?.trim();
+			const file = load();
+			const timestamp = now();
+			const task: UserTask = {
+				id: `u${file.nextId}`,
+				title: normalizedTitle,
+				...(normalizedNote ? { note: normalizedNote } : {}),
+				status: "open",
+				createdAt: timestamp,
+				updatedAt: timestamp,
+			};
+			file.nextId += 1;
+			file.tasks.push(task);
+			save(file);
+			return copyTask(task);
+		},
+		hand(id: string, sessionId?: string): UserTask {
+			return mutate(id, ["open"], "handed", sessionId);
+		},
+		done(id: string): UserTask {
+			return mutate(id, ["open", "handed", "picked"], "done");
+		},
+		drop(id: string): UserTask {
+			return mutate(id, ["open", "handed", "picked"], "dropped");
+		},
+		recordPicked(id: string, sessionId: string, boardTaskId: string): UserTask {
+			return recordLink(id, "picked", sessionId, boardTaskId);
+		},
+		recordDone(id: string, sessionId: string, boardTaskId: string): UserTask {
+			return recordLink(id, "done", sessionId, boardTaskId);
+		},
+		reconcile(links: ReadonlyArray<UserTaskBoardLink>, sessionId: string): ReadonlyArray<UserTask> {
+			const file = load();
+			let changed = false;
+			for (const [index, current] of file.tasks.entries()) {
+				if (current.status === "done" || current.status === "dropped") continue;
+				const candidates = links.filter((link) => link.userTaskId === current.id);
+				const completed = candidates.find((link) => link.status === "completed");
+				const open = candidates.find((link) => link.status === "active" || link.status === "pending");
+				const link = completed ?? open;
+				if (link) {
+					const status = completed ? "done" : "picked";
+					if (
+						current.status !== status ||
+						current.boardTaskId !== link.boardTaskId ||
+						current.handedSessionId !== sessionId
+					) {
+						file.tasks[index] = {
+							...current,
+							status,
+							boardTaskId: link.boardTaskId,
+							handedSessionId: sessionId,
+							updatedAt: now(),
+						};
+						changed = true;
+					}
+					continue;
+				}
+				// An empty link set is authoritative only for the session recorded as
+				// owning this pickup. Reconciling session B must not release durable
+				// work that session A still owns, or B can pick the same project task.
+				if (current.status === "picked" && current.handedSessionId === sessionId) {
+					const repaired: UserTask = { ...current, status: "handed", updatedAt: now() };
+					delete repaired.boardTaskId;
+					file.tasks[index] = repaired;
+					changed = true;
+				}
+			}
+			if (changed) save(file);
+			return file.tasks.map(copyTask);
+		},
+	};
+}

package/src/engine/acp/errors.ts

@@ -30,3 +30,99 @@ export class AcpProcessError extends AcpError {
 		this.name = "AcpProcessError";
 	}
 }
+
+/**
+ * Upper bound on any `error.message` this process puts on the wire. A JSON-RPC
+ * message is operator-facing prose, not a payload: an unbounded one lets a
+ * provider response, a file body, or a stack walk cross the protocol boundary.
+ */
+export const ACP_MAX_ERROR_MESSAGE_CHARS = 256;
+
+/**
+ * The `error.message` a failed prompt turn always carries. A provider or engine
+ * failure body is text this process never authored: it can name an absolute
+ * path, a URL with credentials, or a token, and stdout is the one channel the
+ * client parses. The client branches on `data._meta`'s `turn_failed` code; the
+ * original prose goes to the diagnostics sink (stderr) instead.
+ */
+export const ACP_TURN_FAILED_MESSAGE = "the prompt turn failed";
+
+/**
+ * The `error.message` an unclassified handler failure always carries, for the
+ * same reason as {@link ACP_TURN_FAILED_MESSAGE}: the thrower did not choose
+ * this text, so nothing bounds what it might disclose.
+ */
+export const ACP_INTERNAL_ERROR_MESSAGE = "internal error";
+
+/**
+ * The `error.message` an unregistered method always carries. The method name is
+ * peer-controlled text, and a bounded copy of peer text is still peer text on a
+ * channel where every message is authored by this process. The client already
+ * knows which method it called, so echoing it back buys nothing and the frame
+ * says only that the method is not served; `data._meta` carries
+ * `method_not_found`.
+ */
+export const ACP_METHOD_NOT_FOUND_MESSAGE = "method not found";
+
+/** `_meta` key carrying Clio's machine-readable error detail (CONTRACT C001 §0). */
+export const ACP_ERROR_META_KEY = "clio-coder/error";
+
+/** Version of the `clio-coder/error` payload shape. */
+export const ACP_ERROR_META_VERSION = 1;
+
+/**
+ * Machine-readable failure detail. `code` is a closed-set string the client
+ * branches on; `reason` and `supported` are the two optional refinements the
+ * profile defines (admission reason, supported protocol versions).
+ */
+export interface AcpErrorDetail {
+	code: string;
+	reason?: string;
+	supported?: number[];
+}
+
+/**
+ * A failure whose JSON-RPC code and machine-readable detail the thrower chooses.
+ * The transport serializes it verbatim; anything else it catches becomes an
+ * `internal_error` with a bounded message and no stack.
+ */
+export class AcpRequestError extends Error {
+	constructor(
+		readonly rpcCode: number,
+		message: string,
+		readonly detail: AcpErrorDetail,
+	) {
+		super(message);
+		this.name = "AcpRequestError";
+	}
+}
+
+/**
+ * The only thing that ever travels in a JSON-RPC `error.data` from this server:
+ * one namespaced, versioned object. A strict ACP client that ignores `_meta`
+ * still sees a conformant error, and nothing else can ride along.
+ */
+export function acpErrorData(detail: AcpErrorDetail): { _meta: Record<string, unknown> } {
+	return {
+		_meta: {
+			[ACP_ERROR_META_KEY]: {
+				version: ACP_ERROR_META_VERSION,
+				code: detail.code,
+				...(detail.reason !== undefined ? { reason: detail.reason } : {}),
+				...(detail.supported !== undefined ? { supported: [...detail.supported] } : {}),
+			},
+		},
+	};
+}
+
+/**
+ * One bounded single-line message from any thrown value. Newlines are what turn
+ * a message into a stack dump, so every run of whitespace collapses to one
+ * space before the length bound applies.
+ */
+export function acpErrorMessage(value: unknown): string {
+	const raw = value instanceof Error ? value.message : String(value);
+	const collapsed = raw.replace(/\s+/g, " ").trim();
+	if (collapsed.length <= ACP_MAX_ERROR_MESSAGE_CHARS) return collapsed;
+	return `${collapsed.slice(0, ACP_MAX_ERROR_MESSAGE_CHARS - 1)}…`;
+}