@ag-eco/agentplate-cli 0.13.0

package/src/errors.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Tests for all Agentplate error classes.
+ *
+ * Validates constructor fields, instanceof chains, name, code, and cause chaining.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+	AgentError,
+	AgentplateError,
+	ConfigError,
+	GroupError,
+	HierarchyError,
+	LifecycleError,
+	MailError,
+	MergeError,
+	ValidationError,
+	WorktreeError,
+} from "./errors.ts";
+
+describe("AgentplateError", () => {
+	test("sets message, code, and name", () => {
+		const err = new AgentplateError("something broke", "TEST_CODE");
+		expect(err.message).toBe("something broke");
+		expect(err.code).toBe("TEST_CODE");
+		expect(err.name).toBe("AgentplateError");
+	});
+
+	test("is instanceof Error", () => {
+		const err = new AgentplateError("msg", "CODE");
+		expect(err).toBeInstanceOf(Error);
+		expect(err).toBeInstanceOf(AgentplateError);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("root cause");
+		const err = new AgentplateError("wrapper", "CODE", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("ConfigError", () => {
+	test("sets code and name", () => {
+		const err = new ConfigError("bad config");
+		expect(err.code).toBe("CONFIG_ERROR");
+		expect(err.name).toBe("ConfigError");
+	});
+
+	test("defaults context fields to null", () => {
+		const err = new ConfigError("missing");
+		expect(err.configPath).toBeNull();
+		expect(err.field).toBeNull();
+	});
+
+	test("stores context fields", () => {
+		const err = new ConfigError("invalid", {
+			configPath: "/path/to/config.yaml",
+			field: "agents.maxConcurrent",
+		});
+		expect(err.configPath).toBe("/path/to/config.yaml");
+		expect(err.field).toBe("agents.maxConcurrent");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new ConfigError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("parse failed");
+		const err = new ConfigError("bad yaml", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("AgentError", () => {
+	test("sets code and name", () => {
+		const err = new AgentError("spawn failed");
+		expect(err.code).toBe("AGENT_ERROR");
+		expect(err.name).toBe("AgentError");
+	});
+
+	test("defaults context fields to null", () => {
+		const err = new AgentError("msg");
+		expect(err.agentName).toBeNull();
+		expect(err.capability).toBeNull();
+	});
+
+	test("stores context fields", () => {
+		const err = new AgentError("failed", {
+			agentName: "builder-1",
+			capability: "builder",
+		});
+		expect(err.agentName).toBe("builder-1");
+		expect(err.capability).toBe("builder");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new AgentError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("tmux failed");
+		const err = new AgentError("spawn failed", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("HierarchyError", () => {
+	test("sets code and name", () => {
+		const err = new HierarchyError("depth exceeded");
+		expect(err.code).toBe("HIERARCHY_VIOLATION");
+		expect(err.name).toBe("HierarchyError");
+	});
+
+	test("defaults context fields to null", () => {
+		const err = new HierarchyError("msg");
+		expect(err.agentName).toBeNull();
+		expect(err.requestedCapability).toBeNull();
+	});
+
+	test("stores context fields", () => {
+		const err = new HierarchyError("violation", {
+			agentName: "coordinator",
+			requestedCapability: "builder",
+		});
+		expect(err.agentName).toBe("coordinator");
+		expect(err.requestedCapability).toBe("builder");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new HierarchyError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("inner");
+		const err = new HierarchyError("violation", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("WorktreeError", () => {
+	test("sets code and name", () => {
+		const err = new WorktreeError("creation failed");
+		expect(err.code).toBe("WORKTREE_ERROR");
+		expect(err.name).toBe("WorktreeError");
+	});
+
+	test("defaults context fields to null", () => {
+		const err = new WorktreeError("msg");
+		expect(err.worktreePath).toBeNull();
+		expect(err.branchName).toBeNull();
+	});
+
+	test("stores context fields", () => {
+		const err = new WorktreeError("conflict", {
+			worktreePath: "/tmp/wt",
+			branchName: "agent/builder-1",
+		});
+		expect(err.worktreePath).toBe("/tmp/wt");
+		expect(err.branchName).toBe("agent/builder-1");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new WorktreeError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("git error");
+		const err = new WorktreeError("failed", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("MailError", () => {
+	test("sets code and name", () => {
+		const err = new MailError("db locked");
+		expect(err.code).toBe("MAIL_ERROR");
+		expect(err.name).toBe("MailError");
+	});
+
+	test("defaults context fields to null", () => {
+		const err = new MailError("msg");
+		expect(err.agentName).toBeNull();
+		expect(err.messageId).toBeNull();
+	});
+
+	test("stores context fields", () => {
+		const err = new MailError("delivery failed", {
+			agentName: "scout-1",
+			messageId: "msg-abc",
+		});
+		expect(err.agentName).toBe("scout-1");
+		expect(err.messageId).toBe("msg-abc");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new MailError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("sqlite busy");
+		const err = new MailError("failed", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("MergeError", () => {
+	test("sets code and name", () => {
+		const err = new MergeError("conflict");
+		expect(err.code).toBe("MERGE_ERROR");
+		expect(err.name).toBe("MergeError");
+	});
+
+	test("defaults context fields to null/empty", () => {
+		const err = new MergeError("msg");
+		expect(err.branchName).toBeNull();
+		expect(err.conflictFiles).toEqual([]);
+	});
+
+	test("stores context fields including conflictFiles array", () => {
+		const err = new MergeError("unresolvable", {
+			branchName: "agent/builder-1",
+			conflictFiles: ["src/index.ts", "src/types.ts"],
+		});
+		expect(err.branchName).toBe("agent/builder-1");
+		expect(err.conflictFiles).toEqual(["src/index.ts", "src/types.ts"]);
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new MergeError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("git merge failed");
+		const err = new MergeError("conflict", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("ValidationError", () => {
+	test("sets code and name", () => {
+		const err = new ValidationError("invalid input");
+		expect(err.code).toBe("VALIDATION_ERROR");
+		expect(err.name).toBe("ValidationError");
+	});
+
+	test("defaults context fields to null", () => {
+		const err = new ValidationError("msg");
+		expect(err.field).toBeNull();
+		expect(err.value).toBeNull();
+	});
+
+	test("stores context fields", () => {
+		const err = new ValidationError("bad name", {
+			field: "agentName",
+			value: "",
+		});
+		expect(err.field).toBe("agentName");
+		expect(err.value).toBe("");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new ValidationError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("schema violation");
+		const err = new ValidationError("failed", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("GroupError", () => {
+	test("sets code and name", () => {
+		const err = new GroupError("not found");
+		expect(err.code).toBe("GROUP_ERROR");
+		expect(err.name).toBe("GroupError");
+	});
+
+	test("defaults groupId to null", () => {
+		const err = new GroupError("msg");
+		expect(err.groupId).toBeNull();
+	});
+
+	test("stores groupId", () => {
+		const err = new GroupError("not found", { groupId: "group-abc12345" });
+		expect(err.groupId).toBe("group-abc12345");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new GroupError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("disk error");
+		const err = new GroupError("failed", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});
+
+describe("LifecycleError", () => {
+	test("sets code and name", () => {
+		const err = new LifecycleError("checkpoint failed");
+		expect(err.code).toBe("LIFECYCLE_ERROR");
+		expect(err.name).toBe("LifecycleError");
+	});
+
+	test("defaults context fields to null", () => {
+		const err = new LifecycleError("msg");
+		expect(err.agentName).toBeNull();
+		expect(err.sessionId).toBeNull();
+	});
+
+	test("stores context fields", () => {
+		const err = new LifecycleError("handoff failed", {
+			agentName: "lead-1",
+			sessionId: "sess-xyz",
+		});
+		expect(err.agentName).toBe("lead-1");
+		expect(err.sessionId).toBe("sess-xyz");
+	});
+
+	test("is instanceof AgentplateError and Error", () => {
+		const err = new LifecycleError("msg");
+		expect(err).toBeInstanceOf(AgentplateError);
+		expect(err).toBeInstanceOf(Error);
+	});
+
+	test("supports cause chaining", () => {
+		const cause = new Error("save failed");
+		const err = new LifecycleError("checkpoint", { cause });
+		expect(err.cause).toBe(cause);
+	});
+});

package/src/errors.ts

@@ -0,0 +1,217 @@
+/**
+ * Base error class for all Agentplate errors.
+ * Includes a machine-readable `code` field for programmatic handling.
+ */
+export class AgentplateError extends Error {
+	readonly code: string;
+
+	constructor(message: string, code: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "AgentplateError";
+		this.code = code;
+	}
+}
+
+/**
+ * Raised when config loading or validation fails.
+ * Examples: missing config file, invalid YAML, schema violations.
+ */
+export class ConfigError extends AgentplateError {
+	readonly configPath: string | null;
+	readonly field: string | null;
+
+	constructor(
+		message: string,
+		context?: {
+			configPath?: string;
+			field?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, "CONFIG_ERROR", { cause: context?.cause });
+		this.name = "ConfigError";
+		this.configPath = context?.configPath ?? null;
+		this.field = context?.field ?? null;
+	}
+}
+
+/**
+ * Raised for agent lifecycle issues.
+ * Examples: spawn failure, agent not found, depth limit exceeded.
+ */
+export class AgentError extends AgentplateError {
+	readonly agentName: string | null;
+	readonly capability: string | null;
+
+	constructor(
+		message: string,
+		context?: {
+			agentName?: string;
+			capability?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, "AGENT_ERROR", { cause: context?.cause });
+		this.name = "AgentError";
+		this.agentName = context?.agentName ?? null;
+		this.capability = context?.capability ?? null;
+	}
+}
+
+/**
+ * Raised when hierarchy constraints are violated.
+ * Examples: coordinator spawning a builder directly instead of through a lead.
+ */
+export class HierarchyError extends AgentplateError {
+	readonly agentName: string | null;
+	readonly requestedCapability: string | null;
+
+	constructor(
+		message: string,
+		context?: {
+			agentName?: string;
+			requestedCapability?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, "HIERARCHY_VIOLATION", { cause: context?.cause });
+		this.name = "HierarchyError";
+		this.agentName = context?.agentName ?? null;
+		this.requestedCapability = context?.requestedCapability ?? null;
+	}
+}
+
+/**
+ * Raised when git worktree operations fail.
+ * Examples: worktree creation, branch conflicts, cleanup failures.
+ */
+export class WorktreeError extends AgentplateError {
+	readonly worktreePath: string | null;
+	readonly branchName: string | null;
+
+	constructor(
+		message: string,
+		context?: {
+			worktreePath?: string;
+			branchName?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, "WORKTREE_ERROR", { cause: context?.cause });
+		this.name = "WorktreeError";
+		this.worktreePath = context?.worktreePath ?? null;
+		this.branchName = context?.branchName ?? null;
+	}
+}
+
+/**
+ * Raised when mail system operations fail.
+ * Examples: DB access errors, invalid message format, delivery failures.
+ */
+export class MailError extends AgentplateError {
+	readonly agentName: string | null;
+	readonly messageId: string | null;
+
+	constructor(
+		message: string,
+		context?: {
+			agentName?: string;
+			messageId?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, "MAIL_ERROR", { cause: context?.cause });
+		this.name = "MailError";
+		this.agentName = context?.agentName ?? null;
+		this.messageId = context?.messageId ?? null;
+	}
+}
+
+/**
+ * Raised when merge or conflict resolution fails.
+ * Examples: unresolvable conflicts, merge queue errors, tier escalation failures.
+ */
+export class MergeError extends AgentplateError {
+	readonly branchName: string | null;
+	readonly conflictFiles: string[];
+
+	constructor(
+		message: string,
+		context?: {
+			branchName?: string;
+			conflictFiles?: string[];
+			cause?: Error;
+		},
+	) {
+		super(message, "MERGE_ERROR", { cause: context?.cause });
+		this.name = "MergeError";
+		this.branchName = context?.branchName ?? null;
+		this.conflictFiles = context?.conflictFiles ?? [];
+	}
+}
+
+/**
+ * Raised when input validation fails.
+ * Examples: invalid agent names, malformed taskIds, bad CLI arguments.
+ */
+export class ValidationError extends AgentplateError {
+	readonly field: string | null;
+	readonly value: unknown;
+
+	constructor(
+		message: string,
+		context?: {
+			field?: string;
+			value?: unknown;
+			cause?: Error;
+		},
+	) {
+		super(message, "VALIDATION_ERROR", { cause: context?.cause });
+		this.name = "ValidationError";
+		this.field = context?.field ?? null;
+		this.value = context?.value ?? null;
+	}
+}
+
+/**
+ * Raised when task group operations fail.
+ * Examples: group not found, duplicate member, auto-close failures.
+ */
+export class GroupError extends AgentplateError {
+	readonly groupId: string | null;
+
+	constructor(
+		message: string,
+		context?: {
+			groupId?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, "GROUP_ERROR", { cause: context?.cause });
+		this.name = "GroupError";
+		this.groupId = context?.groupId ?? null;
+	}
+}
+
+/**
+ * Raised when session lifecycle operations fail.
+ * Examples: checkpoint save/restore failures, handoff failures.
+ */
+export class LifecycleError extends AgentplateError {
+	readonly agentName: string | null;
+	readonly sessionId: string | null;
+
+	constructor(
+		message: string,
+		context?: {
+			agentName?: string;
+			sessionId?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, "LIFECYCLE_ERROR", { cause: context?.cause });
+		this.name = "LifecycleError";
+		this.agentName = context?.agentName ?? null;
+		this.sessionId = context?.sessionId ?? null;
+	}
+}