plugsuits 1.0.0

package/src/tools/explore/read-file.test.ts

@@ -0,0 +1,355 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { executeReadFile } from "./read-file";
+
+const ISO_DATE_PATTERN = /\d{4}-\d{2}-\d{2}T/;
+const FILE_HASH_PATTERN = /file_hash:\s+[0-9a-f]{8}/;
+const LINE_TAG_PATTERN = /\d+#(?:[ZPMQVRWSNKTXJBYH]{2})\|/;
+const HASHLINE_ALPHABET = "[ZPMQVRWSNKTXJBYH]{2}";
+const REGEX_ESCAPE_PATTERN = /[.*+?^${}()|[\]\\]/g;
+
+function buildTaggedLinePattern(lineNumber: number, text: string): RegExp {
+  const escaped = text.replaceAll(REGEX_ESCAPE_PATTERN, "\\$&");
+  return new RegExp(`${lineNumber}#${HASHLINE_ALPHABET}\\|${escaped}`);
+}
+
+describe("executeReadFile", () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "read-file-test-"));
+  });
+
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  describe("basic read operations", () => {
+    it("reads file and returns structured response", async () => {
+      const testFile = join(tempDir, "basic.txt");
+      writeFileSync(testFile, "line1\nline2\nline3");
+
+      const result = await executeReadFile({ path: testFile });
+
+      expect(result).toContain("OK - read file");
+      expect(result).toContain(`path: ${testFile}`);
+      expect(result).toContain("bytes:");
+      expect(result).toContain("lines: 3");
+      expect(result).toMatch(FILE_HASH_PATTERN);
+      expect(result).toContain("range: L1-L3");
+      expect(result).toContain("======== basic.txt L1-L3 ========");
+      expect(result).toMatch(buildTaggedLinePattern(1, "line1"));
+      expect(result).toMatch(buildTaggedLinePattern(2, "line2"));
+      expect(result).toMatch(buildTaggedLinePattern(3, "line3"));
+      expect(result).toContain("======== end ========");
+    });
+
+    it("includes last_modified timestamp", async () => {
+      const testFile = join(tempDir, "mtime.txt");
+      writeFileSync(testFile, "content");
+
+      const result = await executeReadFile({ path: testFile });
+
+      expect(result).toContain("last_modified:");
+      expect(result).toMatch(ISO_DATE_PATTERN);
+    });
+  });
+
+  describe("offset and limit", () => {
+    it("respects offset parameter", async () => {
+      const testFile = join(tempDir, "offset.txt");
+      writeFileSync(testFile, "a\nb\nc\nd\ne");
+
+      const result = await executeReadFile({ path: testFile, offset: 2 });
+
+      expect(result).toContain("range: L3-L5");
+      expect(result).toMatch(buildTaggedLinePattern(3, "c"));
+      expect(result).toMatch(buildTaggedLinePattern(4, "d"));
+      expect(result).toMatch(buildTaggedLinePattern(5, "e"));
+      expect(result).not.toMatch(buildTaggedLinePattern(1, "a"));
+      expect(result).not.toMatch(buildTaggedLinePattern(2, "b"));
+    });
+
+    it("respects limit parameter", async () => {
+      const testFile = join(tempDir, "limit.txt");
+      writeFileSync(testFile, "a\nb\nc\nd\ne");
+
+      const result = await executeReadFile({ path: testFile, limit: 2 });
+
+      expect(result).toContain("range: L1-L2");
+      expect(result).toContain("returned: 2");
+      expect(result).toMatch(buildTaggedLinePattern(1, "a"));
+      expect(result).toMatch(buildTaggedLinePattern(2, "b"));
+    });
+
+    it("combines offset and limit", async () => {
+      const testFile = join(tempDir, "combo.txt");
+      writeFileSync(testFile, "1\n2\n3\n4\n5\n6\n7\n8\n9\n10");
+
+      const result = await executeReadFile({
+        path: testFile,
+        offset: 3,
+        limit: 3,
+      });
+
+      expect(result).toContain("range: L4-L6");
+      expect(result).toMatch(buildTaggedLinePattern(4, "4"));
+      expect(result).toMatch(buildTaggedLinePattern(5, "5"));
+      expect(result).toMatch(buildTaggedLinePattern(6, "6"));
+    });
+  });
+
+  describe("around_line feature", () => {
+    it("reads around specified line with defaults", async () => {
+      const testFile = join(tempDir, "around.txt");
+      const lines = Array.from({ length: 30 }, (_, i) => `line${i + 1}`);
+      writeFileSync(testFile, lines.join("\n"));
+
+      const result = await executeReadFile({
+        path: testFile,
+        around_line: 15,
+      });
+
+      expect(result).toContain("L10-L25");
+      expect(result).toContain("line15");
+      expect(result).toContain("line10");
+      expect(result).toContain("line25");
+    });
+
+    it("respects before parameter", async () => {
+      const testFile = join(tempDir, "before.txt");
+      const lines = Array.from({ length: 20 }, (_, i) => `line${i + 1}`);
+      writeFileSync(testFile, lines.join("\n"));
+
+      const result = await executeReadFile({
+        path: testFile,
+        around_line: 10,
+        before: 2,
+        after: 2,
+      });
+
+      expect(result).toContain("L8-L12");
+      expect(result).toContain("line8");
+      expect(result).toContain("line10");
+      expect(result).toContain("line12");
+    });
+
+    it("handles around_line at start of file", async () => {
+      const testFile = join(tempDir, "start.txt");
+      writeFileSync(testFile, "1\n2\n3\n4\n5\n6\n7\n8\n9\n10");
+
+      const result = await executeReadFile({
+        path: testFile,
+        around_line: 1,
+        before: 5,
+        after: 3,
+      });
+
+      expect(result).toContain("L1-L4");
+    });
+
+    it("handles around_line at end of file", async () => {
+      const testFile = join(tempDir, "end.txt");
+      writeFileSync(testFile, "1\n2\n3\n4\n5");
+
+      const result = await executeReadFile({
+        path: testFile,
+        around_line: 5,
+        before: 2,
+        after: 10,
+      });
+
+      expect(result).toContain("L3-L5");
+    });
+  });
+
+  describe("truncation indication", () => {
+    it("indicates when file is truncated", async () => {
+      const testFile = join(tempDir, "trunc.txt");
+      writeFileSync(testFile, "a\nb\nc\nd\ne");
+
+      const result = await executeReadFile({ path: testFile, limit: 2 });
+
+      expect(result).toContain("truncated: true");
+    });
+
+    it("indicates when file is not truncated", async () => {
+      const testFile = join(tempDir, "notrunc.txt");
+      writeFileSync(testFile, "a\nb");
+
+      const result = await executeReadFile({ path: testFile });
+
+      expect(result).toContain("truncated: false");
+      expect(result).toMatch(LINE_TAG_PATTERN);
+    });
+  });
+
+  describe("error handling", () => {
+    it("throws error for non-existent file", async () => {
+      await expect(
+        executeReadFile({ path: join(tempDir, "nonexistent.txt") })
+      ).rejects.toThrow();
+    });
+
+    it("respects .ignore and .fdignore by default", async () => {
+      const isolatedDir = mkdtempSync(join(tmpdir(), "read-ignore-"));
+      try {
+        const ignoredByDotIgnore = join(isolatedDir, "blocked-ignore.txt");
+        const ignoredByFdIgnore = join(isolatedDir, "blocked-fd.txt");
+        writeFileSync(join(isolatedDir, ".ignore"), "blocked-ignore.txt\n");
+        writeFileSync(join(isolatedDir, ".fdignore"), "blocked-fd.txt\n");
+        writeFileSync(ignoredByDotIgnore, "blocked");
+        writeFileSync(ignoredByFdIgnore, "blocked");
+
+        await expect(
+          executeReadFile({ path: ignoredByDotIgnore })
+        ).rejects.toThrow("excluded by ignore rules");
+        await expect(
+          executeReadFile({ path: ignoredByFdIgnore })
+        ).rejects.toThrow("excluded by ignore rules");
+      } finally {
+        if (existsSync(isolatedDir)) {
+          rmSync(isolatedDir, { recursive: true });
+        }
+      }
+    });
+
+    it("can bypass ignore rules when respect_git_ignore is false", async () => {
+      const isolatedDir = mkdtempSync(join(tmpdir(), "read-ignore-off-"));
+      try {
+        const ignoredFile = join(isolatedDir, "blocked.txt");
+        writeFileSync(join(isolatedDir, ".ignore"), "blocked.txt\n");
+        writeFileSync(ignoredFile, "allowed");
+
+        const result = await executeReadFile({
+          path: ignoredFile,
+          respect_git_ignore: false,
+        });
+
+        expect(result).toContain("OK - read file");
+        expect(result).toContain("respect_git_ignore: false");
+        expect(result).toMatch(buildTaggedLinePattern(1, "allowed"));
+      } finally {
+        if (existsSync(isolatedDir)) {
+          rmSync(isolatedDir, { recursive: true });
+        }
+      }
+    });
+
+    it("applies parent .gitignore when reading from subdirectory", async () => {
+      const repoDir = mkdtempSync(join(tmpdir(), "read-parent-gitignore-"));
+      const workspaceDir = join(repoDir, "workspace");
+      try {
+        mkdirSync(join(repoDir, ".git"));
+        mkdirSync(workspaceDir);
+        writeFileSync(join(repoDir, ".gitignore"), "/workspace/blocked.txt\n");
+        writeFileSync(join(workspaceDir, "blocked.txt"), "blocked");
+
+        await expect(
+          executeReadFile({ path: join(workspaceDir, "blocked.txt") })
+        ).rejects.toThrow("excluded by ignore rules");
+      } finally {
+        if (existsSync(repoDir)) {
+          rmSync(repoDir, { recursive: true });
+        }
+      }
+    });
+
+    it("applies slashless nested .gitignore patterns to descendants", async () => {
+      const repoDir = mkdtempSync(join(tmpdir(), "read-nested-gitignore-"));
+      const srcDir = join(repoDir, "src");
+      const nestedDir = join(srcDir, "nested");
+      try {
+        mkdirSync(join(repoDir, ".git"));
+        mkdirSync(srcDir);
+        mkdirSync(nestedDir);
+        writeFileSync(join(srcDir, ".gitignore"), "ignored.ts\n");
+        writeFileSync(join(nestedDir, "ignored.ts"), "blocked");
+
+        await expect(
+          executeReadFile({ path: join(nestedDir, "ignored.ts") })
+        ).rejects.toThrow("excluded by ignore rules");
+      } finally {
+        if (existsSync(repoDir)) {
+          rmSync(repoDir, { recursive: true });
+        }
+      }
+    });
+
+    it("does not bypass ignore rules with relative parent paths", async () => {
+      const originalCwd = process.cwd();
+      const repoDir = mkdtempSync(join(tmpdir(), "read-relative-parent-"));
+      const nestedDir = join(repoDir, "nested");
+      try {
+        mkdirSync(join(repoDir, ".git"));
+        mkdirSync(nestedDir);
+        writeFileSync(join(repoDir, ".gitignore"), "/blocked.txt\n");
+        writeFileSync(join(repoDir, "blocked.txt"), "blocked");
+
+        process.chdir(nestedDir);
+        await expect(
+          executeReadFile({ path: "../blocked.txt" })
+        ).rejects.toThrow("excluded by ignore rules");
+      } finally {
+        process.chdir(originalCwd);
+        if (existsSync(repoDir)) {
+          rmSync(repoDir, { recursive: true });
+        }
+      }
+    });
+
+    it("rejects negative offset", async () => {
+      const testFile = join(tempDir, "invalid-offset.txt");
+      writeFileSync(testFile, "a\nb\n");
+
+      await expect(
+        executeReadFile({
+          path: testFile,
+          offset: -1,
+        })
+      ).rejects.toThrow();
+    });
+
+    it("rejects non-positive limit", async () => {
+      const testFile = join(tempDir, "invalid-limit.txt");
+      writeFileSync(testFile, "a\nb\n");
+
+      await expect(
+        executeReadFile({
+          path: testFile,
+          limit: 0,
+        })
+      ).rejects.toThrow();
+    });
+
+    it("rejects binary content even with text extension", async () => {
+      const testFile = join(tempDir, "binary.txt");
+      writeFileSync(testFile, Buffer.from([0x00, 0x61, 0x62, 0x63]));
+
+      await expect(executeReadFile({ path: testFile })).rejects.toThrow(
+        "binary"
+      );
+    });
+
+    it("allows text files with .lock extension", async () => {
+      const testFile = join(tempDir, "plain.lock");
+      writeFileSync(testFile, "line1\nline2");
+
+      const result = await executeReadFile({ path: testFile });
+
+      expect(result).toContain("OK - read file");
+      expect(result).toMatch(buildTaggedLinePattern(1, "line1"));
+      expect(result).toMatch(buildTaggedLinePattern(2, "line2"));
+    });
+  });
+});

package/src/tools/explore/read-file.ts

@@ -0,0 +1,102 @@
+import { basename } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { formatBlock, safeReadFileEnhanced } from "../utils/safety-utils";
+import READ_FILE_DESCRIPTION from "./read-file.txt";
+
+const inputSchema = z.object({
+  path: z.string().describe("File path (absolute or relative)"),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(
+      "Start line (0-based, default: 0). Use around_line for smarter reading."
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe("Max lines to read (default: 2000)"),
+  around_line: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe("Read around this line (1-based). Combines with before/after."),
+  before: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Lines before around_line (default: 5)"),
+  after: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Lines after around_line (default: 10)"),
+  respect_git_ignore: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe("Respect ignore rules from .gitignore/.ignore/.fdignore"),
+});
+
+export type ReadFileInput = z.input<typeof inputSchema>;
+
+export async function executeReadFile({
+  path,
+  offset,
+  limit,
+  around_line,
+  before,
+  after,
+  respect_git_ignore,
+}: ReadFileInput): Promise<string> {
+  const parsedInput = inputSchema.parse({
+    path,
+    offset,
+    limit,
+    around_line,
+    before,
+    after,
+    respect_git_ignore,
+  });
+
+  const result = await safeReadFileEnhanced(path, {
+    offset: parsedInput.offset,
+    limit: parsedInput.limit,
+    around_line: parsedInput.around_line,
+    before: parsedInput.before,
+    after: parsedInput.after,
+    respect_git_ignore: parsedInput.respect_git_ignore,
+  });
+
+  const fileName = basename(path);
+  const rangeStr = `L${result.startLine1}-L${result.endLine1}`;
+
+  const output = [
+    "OK - read file",
+    `path: ${path}`,
+    `bytes: ${result.bytes}`,
+    `last_modified: ${result.lastModified}`,
+    `lines: ${result.totalLines} (returned: ${result.endLine1 - result.startLine1 + 1})`,
+    `file_hash: ${result.fileHash}`,
+    `range: ${rangeStr}`,
+    `truncated: ${result.truncated}`,
+    `respect_git_ignore: ${parsedInput.respect_git_ignore}`,
+    "",
+    formatBlock(`${fileName} ${rangeStr}`, result.numberedContent),
+  ];
+
+  return output.join("\n");
+}
+
+export const readFileTool = tool({
+  description: READ_FILE_DESCRIPTION,
+  inputSchema,
+  execute: executeReadFile,
+});

package/src/tools/explore/read-file.txt

@@ -0,0 +1,24 @@
+### read_file
+**Purpose**: Read file contents with hashline anchors (`{line_number}#{hash_id}`)
+
+**When to use**:
+- ALWAYS read a file before editing it
+- Inspecting data files to confirm real structure
+- Capturing `{line_number}#{hash_id}` and `file_hash` for `edit_file`
+
+**Parameters**:
+- `path` (required): file path
+- `offset` (optional, 0-based, min 0): start line index
+- `limit` (optional, min 1): max lines to return
+- `around_line` (optional, 1-based, min 1): center line for windowed read
+- `before` / `after` (optional, min 0): context window around `around_line`
+- `respect_git_ignore` (optional, default true): apply `.gitignore` / `.ignore` / `.fdignore`
+
+**Output fields**:
+- `file_hash`: stale-check token for `edit_file.expected_file_hash`
+- `range`: returned line range (`Lx-Ly`)
+- `truncated`: whether partial content was returned
+
+**Guidelines**:
+- Prefer `around_line` after `grep_files` hits
+- Re-run `read_file` before retrying stale hashline edits

package/src/tools/index.ts

@@ -0,0 +1,29 @@
+import { shellExecuteTool } from "./execute/shell-execute";
+import { shellInteractTool } from "./execute/shell-interact";
+import { globTool } from "./explore/glob";
+import { grepTool } from "./explore/grep";
+import { readFileTool } from "./explore/read-file";
+import { deleteFileTool } from "./modify/delete-file";
+import { editFileTool } from "./modify/edit-file";
+import { writeFileTool } from "./modify/write-file";
+import { loadSkillTool } from "./planning/load-skill";
+import { todoWriteTool } from "./planning/todo-write";
+
+export const createTools = () => {
+  return {
+    shell_execute: shellExecuteTool,
+    shell_interact: shellInteractTool,
+    write_file: writeFileTool,
+    edit_file: editFileTool,
+    read_file: readFileTool,
+    delete_file: deleteFileTool,
+    glob_files: globTool,
+    grep_files: grepTool,
+    load_skill: loadSkillTool,
+    todo_write: todoWriteTool,
+  } as const;
+};
+
+export type ToolRegistry = ReturnType<typeof createTools>;
+
+export const tools: ToolRegistry = createTools();

package/src/tools/modify/AGENTS.md

@@ -0,0 +1,38 @@
+# MODIFY TOOLS KNOWLEDGE BASE
+
+**Generated:** 2026-02-23 14:40 KST
+**Scope:** `src/tools/modify/**`
+
+## OVERVIEW
+`modify/` owns all write operations: deterministic edits, file creation/overwrite, and deletion.
+
+## STRUCTURE
+```text
+src/tools/modify/
+|- edit-file.ts            # Hashline-native edit engine
+|- edit-file.txt           # edit_file description snippet
+|- write-file.ts           # Create or overwrite full files
+|- write-file.txt          # write_file description snippet
+|- delete-file.ts          # Safe file/directory deletion wrapper
+`- delete-file.txt         # delete_file description snippet
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Surgical line-anchored edits | `src/tools/modify/edit-file.ts` | Supports hashline ops |
+| Hashline integrity logic | `src/tools/utils/hashline/hashline.ts` | Anchors, hashing, and operation ordering |
+| Full-file replacement behavior | `src/tools/modify/write-file.ts` | Creates parent directories and returns metadata |
+| Deletion semantics and safeguards | `src/tools/modify/delete-file.ts` | Recursive behavior and ignore-missing handling |
+
+## CONVENTIONS
+- Prefer hashline edits with `expected_file_hash` for stale-safe deterministic updates.
+- Preserve line-ending normalization behavior during write/edit operations.
+- Maintain rich failure messages for near-match and context diagnostics.
+- Keep all mutation behavior covered by colocated tests before changing edit semantics.
+
+## ANTI-PATTERNS
+- Bypassing expected hash checks when deterministic edits are available.
+- Replacing anchored edits with non-deterministic text matching.
+- Introducing shell-based file mutation flows for behavior already handled here.
+- Silencing partial-match or stale-anchor failures instead of surfacing actionable errors.