plugsuits 1.0.0

package/src/tools/planning/load-skill.ts

@@ -0,0 +1,136 @@
+import { readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, normalize, relative } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { loadSkillById, type SkillInfo } from "../../context/skills";
+import LOAD_SKILL_DESCRIPTION from "./load-skill.txt";
+
+const inputSchema = z.object({
+  skillName: z
+    .string()
+    .describe("Name of the skill to load (e.g., 'git-workflow')"),
+  relativePath: z
+    .string()
+    .optional()
+    .describe(
+      "Optional: Relative path to file within v2 skill directory (e.g., 'scripts/setup.sh')"
+    ),
+});
+
+export type LoadSkillInput = z.infer<typeof inputSchema>;
+
+function validateSkillName(skillName: string): string | null {
+  if (!skillName || skillName.trim() === "") {
+    throw new Error("skillName must be a non-empty string");
+  }
+
+  if (skillName.includes("..") || skillName.includes("/")) {
+    return `Error: Invalid skill name '${skillName}'. Skill names cannot contain '..' or '/'.`;
+  }
+
+  return null;
+}
+
+function validateRelativePath(relativePath: string): string | null {
+  if (relativePath.includes("..") || isAbsolute(relativePath)) {
+    return `Error: Invalid relative path '${relativePath}'. Path must be relative and cannot contain '..'.`;
+  }
+  return null;
+}
+
+async function loadSubFile(
+  skillName: string,
+  relativePath: string,
+  info: SkillInfo & { dirPath: string }
+): Promise<string> {
+  const fullPath = normalize(join(info.dirPath, relativePath));
+  const realSkillDir = await realpath(info.dirPath);
+  const realFilePath = await realpath(fullPath).catch(() => fullPath);
+
+  const relativeFromSkillDir = relative(realSkillDir, realFilePath);
+  const isWithinSkillDir =
+    relativeFromSkillDir === "" ||
+    !(
+      relativeFromSkillDir.startsWith("..") || isAbsolute(relativeFromSkillDir)
+    );
+
+  if (!isWithinSkillDir) {
+    return `Error: Path '${relativePath}' resolves outside skill directory. This is not allowed.`;
+  }
+
+  try {
+    const fileContent = await readFile(realFilePath, "utf-8");
+    return `# Skill File: ${skillName}/${relativePath}\n\n${fileContent}`;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return `Error: File '${relativePath}' not found in skill '${skillName}'.`;
+    }
+    throw error;
+  }
+}
+
+function getSourceLabel(source: SkillInfo["source"]): string {
+  if (source === "bundled") {
+    return "Bundled";
+  }
+  if (source === "global") {
+    return "Global";
+  }
+  return "Project";
+}
+
+export async function executeLoadSkill({
+  skillName,
+  relativePath,
+}: LoadSkillInput): Promise<string> {
+  // Validate skill name
+  const nameError = validateSkillName(skillName);
+  if (nameError) {
+    return nameError;
+  }
+
+  // Validate relative path if provided
+  if (relativePath) {
+    const pathError = validateRelativePath(relativePath);
+    if (pathError) {
+      return pathError;
+    }
+  }
+
+  try {
+    const result = await loadSkillById(skillName);
+
+    if (!result) {
+      return `Error: Skill '${skillName}' not found. Available skills can be found in the system prompt.`;
+    }
+
+    const { content, info } = result;
+
+    // If relativePath is provided, load that file instead
+    if (relativePath) {
+      if (info.format !== "v2" || !info.dirPath) {
+        return `Error: Skill '${skillName}' is a legacy format skill. Only v2 skills support subdirectory files.`;
+      }
+
+      return loadSubFile(
+        skillName,
+        relativePath,
+        info as SkillInfo & { dirPath: string }
+      );
+    }
+
+    // Load main skill file
+    const sourceLabel = getSourceLabel(info.source);
+    const formatLabel = info.format === "v2" ? " (v2)" : "";
+
+    return `# Skill Loaded: ${skillName} [${sourceLabel}${formatLabel}]\n\n${content}`;
+  } catch (error) {
+    return `Error loading skill '${skillName}': ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+export const loadSkillTool = tool({
+  description: LOAD_SKILL_DESCRIPTION,
+  inputSchema,
+  execute: executeLoadSkill,
+});

package/src/tools/planning/load-skill.txt

@@ -0,0 +1,6 @@
+### load_skill
+**Purpose**: Load detailed skill documentation and optional skill subfiles
+
+**When to use**:
+- Fetching workflow instructions from a named skill
+- Loading referenced files from v2 skill directories

package/src/tools/planning/todo-write.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { initializeSession } from "../../context/session";
+import { executeTodoWrite } from "./todo-write";
+
+const testDir = join(process.cwd(), ".cea");
+
+describe("executeTodoWrite", () => {
+  beforeEach(async () => {
+    initializeSession();
+    try {
+      await rm(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore if directory doesn't exist
+    }
+  });
+
+  afterEach(async () => {
+    try {
+      await rm(testDir, { recursive: true, force: true });
+    } catch {
+      // Cleanup - ignore errors
+    }
+  });
+
+  test("creates todo list with multiple tasks", async () => {
+    const result = await executeTodoWrite({
+      todos: [
+        {
+          id: "1",
+          content: "First task",
+          status: "pending",
+          priority: "high",
+        },
+        {
+          id: "2",
+          content: "Second task",
+          status: "in_progress",
+          priority: "medium",
+        },
+      ],
+    });
+
+    expect(result).toContain("OK - updated todo list");
+    expect(result).toContain("total: 2 tasks");
+    expect(result).toContain("pending: 1");
+    expect(result).toContain("in_progress: 1");
+  });
+
+  test("handles empty todo list", async () => {
+    const result = await executeTodoWrite({
+      todos: [],
+    });
+
+    expect(result).toContain("OK - updated todo list");
+    expect(result).toContain("total: 0 tasks");
+  });
+
+  test("includes task descriptions in output", async () => {
+    const result = await executeTodoWrite({
+      todos: [
+        {
+          id: "1",
+          content: "Task with description",
+          status: "pending",
+          priority: "high",
+          description: "Detailed description here",
+        },
+      ],
+    });
+
+    expect(result).toContain("Task with description");
+    expect(result).toContain("Detailed description here");
+  });
+
+  test("rejects empty content", () => {
+    expect(
+      executeTodoWrite({
+        todos: [
+          {
+            id: "1",
+            content: "",
+            status: "pending",
+            priority: "high",
+          },
+        ],
+      })
+    ).rejects.toThrow('Todo item with id "1" has empty content');
+  });
+});

package/src/tools/planning/todo-write.ts

@@ -0,0 +1,141 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { TODO_DIR } from "../../context/paths";
+import { getSessionId } from "../../context/session";
+import TODO_WRITE_DESCRIPTION from "./todo-write.txt";
+
+const todoItemSchema = z.object({
+  id: z.string().describe("Unique identifier for the todo item"),
+  content: z.string().describe("Brief description of the task"),
+  status: z
+    .enum(["pending", "in_progress", "completed", "cancelled"])
+    .describe("Current status of the task"),
+  priority: z
+    .enum(["high", "medium", "low"])
+    .describe("Priority level of the task"),
+  description: z.string().optional().describe("Detailed task description"),
+});
+
+const inputSchema = z.object({
+  todos: z
+    .array(todoItemSchema)
+    .describe("Array of todo items for the task list"),
+});
+
+export type TodoItem = z.infer<typeof todoItemSchema>;
+export type TodoWriteInput = z.infer<typeof inputSchema>;
+
+function generateMarkdown(todos: TodoItem[]): string {
+  const lines = ["# Current Task List", ""];
+
+  const byStatus = {
+    in_progress: todos.filter((t) => t.status === "in_progress"),
+    pending: todos.filter((t) => t.status === "pending"),
+    completed: todos.filter((t) => t.status === "completed"),
+    cancelled: todos.filter((t) => t.status === "cancelled"),
+  };
+
+  if (byStatus.in_progress.length > 0) {
+    lines.push("## 🔄 In Progress");
+    for (const todo of byStatus.in_progress) {
+      lines.push(`- [~] **${todo.content}** (${todo.priority})`);
+      if (todo.description) {
+        lines.push(`  ${todo.description}`);
+      }
+    }
+    lines.push("");
+  }
+
+  if (byStatus.pending.length > 0) {
+    lines.push("## 📋 Pending");
+    for (const todo of byStatus.pending) {
+      lines.push(`- [ ] ${todo.content} (${todo.priority})`);
+      if (todo.description) {
+        lines.push(`  ${todo.description}`);
+      }
+    }
+    lines.push("");
+  }
+
+  if (byStatus.completed.length > 0) {
+    lines.push("## ✅ Completed");
+    for (const todo of byStatus.completed) {
+      lines.push(`- [x] ${todo.content}`);
+    }
+    lines.push("");
+  }
+
+  if (byStatus.cancelled.length > 0) {
+    lines.push("## ❌ Cancelled");
+    for (const todo of byStatus.cancelled) {
+      lines.push(`- [-] ${todo.content}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export async function executeTodoWrite({
+  todos,
+}: TodoWriteInput): Promise<string> {
+  // Validate content is not empty (runtime check to avoid minLength in JSON schema)
+  for (const todo of todos) {
+    if (!todo.content || todo.content.trim() === "") {
+      throw new Error(`Todo item with id "${todo.id}" has empty content`);
+    }
+  }
+
+  const sessionId = getSessionId();
+  const cwd = process.cwd();
+  const todoDir = join(cwd, TODO_DIR);
+
+  await mkdir(todoDir, { recursive: true });
+
+  const timestamp = new Date().toISOString();
+  const todoData = {
+    todos,
+    updatedAt: timestamp,
+    sessionId,
+  };
+
+  const jsonPath = join(todoDir, `${sessionId}.json`);
+  await writeFile(jsonPath, JSON.stringify(todoData, null, 2), "utf-8");
+
+  const markdown = generateMarkdown(todos);
+  const mdPath = join(todoDir, `${sessionId}.md`);
+  await writeFile(mdPath, markdown, "utf-8");
+
+  const stats = {
+    total: todos.length,
+    completed: todos.filter((t) => t.status === "completed").length,
+    inProgress: todos.filter((t) => t.status === "in_progress").length,
+    pending: todos.filter((t) => t.status === "pending").length,
+    cancelled: todos.filter((t) => t.status === "cancelled").length,
+  };
+
+  const output = [
+    "OK - updated todo list",
+    `session: ${sessionId}`,
+    `path: ${TODO_DIR}/${sessionId}.json`,
+    `total: ${stats.total} tasks`,
+    `completed: ${stats.completed}`,
+    `in_progress: ${stats.inProgress}`,
+    `pending: ${stats.pending}`,
+    `cancelled: ${stats.cancelled}`,
+    "",
+    "======== Current Task List ========",
+    markdown,
+    "======== end ========",
+  ];
+
+  return output.join("\n");
+}
+
+export const todoWriteTool = tool({
+  description: TODO_WRITE_DESCRIPTION,
+  inputSchema,
+  execute: executeTodoWrite,
+});

package/src/tools/planning/todo-write.txt

@@ -0,0 +1,7 @@
+### todo_write
+**Purpose**: Create and update structured task lists
+
+**When to use**:
+- Tasks with 3+ distinct steps
+- Multi-requirement work needing progress tracking
+- Complex refactor/feature sessions

package/src/tools/utils/execute/format-utils.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "bun:test";
+import {
+  formatBackgroundMessage,
+  formatTerminalScreen,
+  formatTimeoutMessage,
+} from "./format-utils";
+
+describe("formatTerminalScreen", () => {
+  it("wraps content with screen markers", () => {
+    const result = formatTerminalScreen("hello world");
+
+    expect(result).toContain("=== Current Terminal Screen ===");
+    expect(result).toContain("hello world");
+    expect(result).toContain("=== End of Screen ===");
+  });
+
+  it("returns no visible output message for empty content", () => {
+    expect(formatTerminalScreen("")).toBe("(no visible output)");
+  });
+
+  it("returns no visible output for whitespace-only content", () => {
+    expect(formatTerminalScreen("   \n\n   ")).toBe("(no visible output)");
+  });
+
+  it("trims terminal output before wrapping", () => {
+    const result = formatTerminalScreen("  hello\nworld  \n");
+
+    expect(result).toContain("hello\nworld");
+    expect(result).not.toContain("  ");
+  });
+});
+
+describe("formatTimeoutMessage", () => {
+  it("formats timeout message with terminal screen", () => {
+    const result = formatTimeoutMessage(1000, "output");
+
+    expect(result).toContain("[TIMEOUT] Command timed out after 1000ms.");
+    expect(result).toContain("=== Current Terminal Screen ===");
+    expect(result).toContain("output");
+    expect(result).toContain("[POSSIBLE ACTIONS]");
+  });
+});
+
+describe("formatBackgroundMessage", () => {
+  it("formats background message with terminal screen and reminder", () => {
+    const result = formatBackgroundMessage("output");
+
+    expect(result).toContain("[Background process started]");
+    expect(result).toContain("=== Current Terminal Screen ===");
+    expect(result).toContain("output");
+    expect(result).toContain("[IMPORTANT] Process started in background.");
+  });
+});

package/src/tools/utils/execute/format-utils.ts

@@ -0,0 +1,37 @@
+const TERMINAL_SCREEN_PREFIX = "=== Current Terminal Screen ===";
+const TERMINAL_SCREEN_SUFFIX = "=== End of Screen ===";
+
+const TIMEOUT_PREFIX = "[TIMEOUT]";
+const BACKGROUND_PREFIX = "[Background process started]";
+
+export function formatTerminalScreen(content: string): string {
+  if (!content?.trim()) {
+    return "(no visible output)";
+  }
+  return `${TERMINAL_SCREEN_PREFIX}\n${content.trim()}\n${TERMINAL_SCREEN_SUFFIX}`;
+}
+
+export function formatTimeoutMessage(
+  timeoutMs: number,
+  terminalScreen: string
+): string {
+  const formattedScreen = formatTerminalScreen(terminalScreen);
+  const timeoutHeader = `${TIMEOUT_PREFIX} Command timed out after ${timeoutMs}ms. The process may still be running.`;
+  const reminder = [
+    "[POSSIBLE ACTIONS]",
+    "• Use shell_interact to send keys to the process",
+    "• If the process should continue, increase timeout_ms parameter",
+  ].join("\n");
+  return `${timeoutHeader}\n\n${formattedScreen}\n\n${reminder}`;
+}
+
+export function formatBackgroundMessage(terminalScreen: string): string {
+  const screen = formatTerminalScreen(terminalScreen);
+  const reminder = [
+    "[IMPORTANT] Process started in background.",
+    "• VERIFY the service is running before concluding (e.g., curl endpoint, check logs)",
+    "• Do NOT assume success without verification",
+    "• Use shell_interact to check status or send signals if needed",
+  ].join("\n");
+  return `${BACKGROUND_PREFIX}\n\n${screen}\n\n${reminder}`;
+}