plugsuits 1.0.0

package/src/tools/modify/edit-file.ts

@@ -0,0 +1,252 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import {
+  applyHashlineEditsWithReport,
+  canonicalizeFileText,
+  type HashlineEdit,
+  normalizeHashlineEdits,
+  restoreFileText,
+} from "../utils/hashline";
+import { assertWriteSafety, safeAtomicWriteFile } from "../utils/safety-utils";
+import EDIT_FILE_DESCRIPTION from "./edit-file.txt";
+import { buildEscalationBailMessage } from "./edit-file-diagnostics";
+import type { HashlineToolEdit } from "./edit-file-repair";
+import {
+  assertExpectedFileHash,
+  canCreateFromMissingFile,
+  validateAndRepairEdits,
+} from "./edit-file-validation";
+
+const hashlineToolEditSchema = z
+  .object({
+    op: z
+      .enum(["replace", "append", "prepend"])
+      .describe("replace/append/prepend use hashline anchors."),
+    pos: z
+      .string()
+      .optional()
+      .describe(
+        "Line anchor from read_file (format: {line_number}#{hash_id})."
+      ),
+    end: z
+      .string()
+      .optional()
+      .describe(
+        "Range end anchor for replace operations (format: {line_number}#{hash_id})."
+      ),
+    lines: z
+      .union([z.array(z.string()), z.string(), z.null()])
+      .describe(
+        "Replacement content. string[] for new lines, string for single line, null or [] to delete."
+      ),
+  })
+  .strict();
+
+// Lenient schema: lines optional — fallback when model omits lines
+// Custom validation in validateAndRepairEdits provides better error messages than ZodError
+const lenientEditSchema = z
+  .object({
+    op: z.enum(["replace", "append", "prepend"]),
+    pos: z.string().optional(),
+    end: z.string().optional(),
+    lines: z.union([z.array(z.string()), z.string(), z.null()]).optional(),
+  })
+  .strict();
+
+const lenientInputSchema = z
+  .object({
+    path: z.string(),
+    edits: z.array(lenientEditSchema).min(1),
+    expected_file_hash: z.string().optional(),
+  })
+  .strict();
+
+const inputSchema = z
+  .object({
+    path: z.string().describe("The path to the file"),
+    edits: z
+      .array(hashlineToolEditSchema)
+      .min(1)
+      .describe("Hashline-native edit operations."),
+    expected_file_hash: z
+      .string()
+      .optional()
+      .describe("Optional stale-check file hash from read_file output."),
+  })
+  .strict();
+
+export type EditFileInput = z.input<typeof lenientInputSchema>;
+
+export interface EditFileOptions {
+  /** Override project root for safety checks (defaults to process.cwd()). */
+  rootDir?: string;
+}
+
+// validateAndRepairEdits, canCreateFromMissingFile, assertExpectedFileHash
+// moved to ./edit-file-validation.ts
+
+function formatResult(params: {
+  created: boolean;
+  editCount: number;
+  lineCountDelta: number;
+  path: string;
+  warningLines?: string[];
+}): string {
+  const action = params.created ? "Created" : "Updated";
+  const output: string[] = [`${action} ${params.path}`];
+  const summaryParts: string[] = [`${params.editCount} edit(s) applied`];
+  if (params.lineCountDelta !== 0) {
+    const sign = params.lineCountDelta > 0 ? "+" : "";
+    summaryParts.push(`${sign}${params.lineCountDelta} line(s)`);
+  }
+  output.push(summaryParts.join(", "));
+  if (params.warningLines && params.warningLines.length > 0) {
+    output.push("");
+    output.push("Warnings:");
+    output.push(...params.warningLines);
+  }
+  return output.join("\n");
+}
+
+async function ensureParentDir(path: string): Promise<void> {
+  const directory = dirname(path);
+  if (directory !== ".") {
+    await mkdir(directory, { recursive: true });
+  }
+}
+
+async function readExistingContent(path: string): Promise<{
+  content: string;
+  exists: boolean;
+}> {
+  try {
+    return {
+      content: await readFile(path, "utf-8"),
+      exists: true,
+    };
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return {
+        content: "",
+        exists: false,
+      };
+    }
+    throw error;
+  }
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: complex validation logic
+export async function executeEditFile(input: EditFileInput, options?: EditFileOptions): Promise<string> {
+  let parsed: z.infer<typeof inputSchema>;
+  try {
+    parsed = inputSchema.parse(input);
+  } catch (error) {
+    if (
+      error instanceof z.ZodError &&
+      error.issues.some(
+        (issue) => issue.path.length >= 2 && issue.path.at(-1) === "lines"
+      )
+    ) {
+      // Fall back to lenient parse — custom validation gives better error messages
+      parsed = lenientInputSchema.parse(input) as z.infer<typeof inputSchema>;
+    } else {
+      throw error;
+    }
+  }
+
+  // C-1 + C-2: Path traversal and symlink safety checks
+  const safePath = await assertWriteSafety(parsed.path, options?.rootDir);
+
+  const { content: rawContent, exists } = await readExistingContent(
+    safePath
+  );
+  const oldEnvelope = canonicalizeFileText(rawContent);
+  const fileLines = exists ? oldEnvelope.content.split("\n") : [];
+
+  let repairWarnings: string[];
+  let normalizedEdits: HashlineEdit[];
+  try {
+    const validateResult = validateAndRepairEdits(
+      parsed.edits as HashlineToolEdit[],
+      fileLines,
+      parsed.path
+    );
+    repairWarnings = validateResult.repairWarnings;
+    normalizedEdits = normalizeHashlineEdits(validateResult.edits);
+  } catch (parseError) {
+    if (
+      parseError instanceof Error &&
+      parseError.message.includes("explicit 'lines'")
+    ) {
+      const bailMessage = buildEscalationBailMessage(
+        parsed.edits,
+        parsed.path,
+        fileLines
+      );
+      if (bailMessage) {
+        return bailMessage;
+      }
+    }
+    throw parseError;
+  }
+
+  if (!(exists || canCreateFromMissingFile(normalizedEdits))) {
+    throw new Error(`File not found: ${parsed.path}`);
+  }
+
+  assertExpectedFileHash(parsed.expected_file_hash, rawContent);
+
+  const applyResult = applyHashlineEditsWithReport(
+    oldEnvelope.content,
+    normalizedEdits
+  );
+  const canonicalNewContent = applyResult.content;
+
+  if (canonicalNewContent === oldEnvelope.content) {
+    let diagnostic = `No changes made to ${parsed.path}. The edits produced identical content.`;
+    if (applyResult.noopEdits > 0) {
+      diagnostic += ` No-op edits: ${applyResult.noopEdits}. Re-read the file and provide content that differs from current lines.`;
+    }
+    return `Error: ${diagnostic}`;
+  }
+
+  const writeContent = restoreFileText(canonicalNewContent, oldEnvelope);
+
+  await ensureParentDir(safePath);
+  await safeAtomicWriteFile(safePath, writeContent);
+
+  const originalLineCount = rawContent.split("\n").length;
+  const newLineCount = writeContent.split("\n").length;
+
+  const allWarnings: string[] = [...repairWarnings];
+  if (applyResult.noopEdits > 0) {
+    allWarnings.push(
+      `${applyResult.noopEdits} edit(s) were no-ops because replacement text matched existing content.`
+    );
+  }
+  if (applyResult.deduplicatedEdits > 0) {
+    allWarnings.push(
+      `${applyResult.deduplicatedEdits} duplicate edit(s) were removed.`
+    );
+  }
+
+  return formatResult({
+    created: !exists,
+    editCount: parsed.edits.length,
+    lineCountDelta: newLineCount - originalLineCount,
+    path: parsed.path,
+    warningLines: allWarnings.length > 0 ? allWarnings : undefined,
+  });
+}
+
+export const editFileTool = tool({
+  description: EDIT_FILE_DESCRIPTION,
+  inputSchema,
+  execute: (input) => executeEditFile(input),
+});

package/src/tools/modify/edit-file.txt

@@ -0,0 +1,73 @@
+Applies precise file edits using `LINE#ID` tags from `read_file` output.
+
+**Workflow**:
+1. Call `read_file` to get fresh `{line_number}#{hash_id}|TEXT` anchors.
+2. Pick the smallest operation per change site.
+3. Call `edit_file` once per file with all operations.
+4. Re-read the file before issuing another edit on the same path.
+
+**Input**: `{ path, edits[], expected_file_hash? }`
+
+**Operations**:
+Every edit has `op` and `lines`. Most edits also have `pos`; range replaces add `end`.
+Both `pos` and `end` use `"N#ID"` format (e.g. `"23#XY"`).
+
+`pos` — the anchor line:
+- `replace`: the line to replace (or start of range)
+- `prepend`: insert new lines before this line
+- `append`: insert new lines after this line
+
+`end` — range replace only. The last line of the range (inclusive).
+
+`lines` — the replacement content (REQUIRED for every edit):
+- `["line1", "line2"]` — replace with these lines
+- `"line1"` — shorthand for single line
+- `null` or `[]` — delete the line(s) entirely
+
+**Line or range replace/delete**:
+- `{ op: "replace", pos: "N#ID", lines: ["new content"] }` — replace one line
+- `{ op: "replace", pos: "N#ID", end: "M#ID", lines: ["new"] }` — replace range
+- `{ op: "replace", pos: "N#ID", lines: null }` — delete one line
+- `{ op: "replace", pos: "N#ID", end: "M#ID", lines: null }` — delete range
+
+**Insert new lines**:
+- `{ op: "prepend", pos: "N#ID", lines: ["before"] }` — insert before line
+- `{ op: "append", pos: "N#ID", lines: ["after"] }` — insert after line
+- `{ op: "append", lines: ["at end"] }` — insert at end of file (no pos)
+- `{ op: "prepend", lines: ["at start"] }` — insert at start of file (no pos)
+
+**Rules**:
+- Anchor to structural lines (function signatures, braces), not blank lines.
+- Blank-line hashes are position-dependent and change after edits.
+- Prefer insertion at structure boundaries over rewriting neighbors.
+- Allowed keys per edit: `op`, `pos`, `end`, `lines` — nothing else. `lines` is always required.
+
+**Recovery**:
+- Tag mismatch (`>>>`): retry using fresh tags from the error snippet.
+- No-op (`identical`): re-read target lines and adjust the edit.
+
+**Examples**:
+```
+edit_file({
+  path: "config.ts",
+  edits: [{ op: "replace", pos: "12#AB", lines: ["port: 8080,"] }]
+})
+
+edit_file({
+  path: "routes.ts",
+  edits: [
+    { op: "prepend", pos: "41#MQ", lines: ["  // new route"] },
+    { op: "append", pos: "41#MQ", lines: ["  app.get('/health', handler);"] }
+  ]
+})
+
+edit_file({
+  path: "log.ts",
+  edits: [{ op: "replace", pos: "3#QH", end: "5#KR", lines: ["// consolidated"] }]
+})
+
+edit_file({
+  path: "old.ts",
+  edits: [{ op: "replace", pos: "7#TX", lines: null }]
+})
+```

package/src/tools/modify/write-file.test.ts

@@ -0,0 +1,240 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { executeWriteFile } from "./write-file";
+
+describe("executeWriteFile", () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "write-file-test-"));
+  });
+
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  describe("basic write operations", () => {
+    it("creates new file and returns metadata", async () => {
+      const testFile = join(tempDir, "new.txt");
+      const content = "line1\nline2\nline3";
+
+      const result = await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      expect(result).toContain("OK - created new.txt");
+      expect(result).toContain("bytes:");
+      expect(result).toContain("lines: 3");
+      expect(result).not.toContain("(preview)");
+      expect(result).not.toContain("========");
+
+      const written = readFileSync(testFile, "utf-8");
+      expect(written).toBe(content);
+    });
+
+    it("overwrites existing file and indicates action", async () => {
+      const testFile = join(tempDir, "existing.txt");
+      writeFileSync(testFile, "old content");
+
+      const newContent = "new content";
+      const result = await executeWriteFile(
+        { path: testFile, content: newContent },
+        { rootDir: tempDir }
+      );
+
+      expect(result).toContain("OK - overwrote existing.txt");
+      expect(result).not.toContain("new content");
+
+      const written = readFileSync(testFile, "utf-8");
+      expect(written).toBe(newContent);
+    });
+
+    it("creates parent directories automatically", async () => {
+      const nestedFile = join(tempDir, "deep", "nested", "dir", "file.txt");
+      const content = "nested content";
+
+      const result = await executeWriteFile({ path: nestedFile, content }, { rootDir: tempDir });
+
+      expect(result).toContain("OK - created file.txt");
+      expect(existsSync(nestedFile)).toBe(true);
+
+      const written = readFileSync(nestedFile, "utf-8");
+      expect(written).toBe(content);
+    });
+  });
+
+  describe("output formatting", () => {
+    it("does not include content for small files", async () => {
+      const testFile = join(tempDir, "small.txt");
+      const content = "a\nb\nc\nd\ne";
+
+      const result = await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      expect(result).toContain("bytes:");
+      expect(result).toContain("lines: 5");
+      expect(result).not.toContain("a\nb\nc\nd\ne");
+      expect(result).not.toContain("(preview)");
+    });
+
+    it("does not include content for large files", async () => {
+      const testFile = join(tempDir, "large.txt");
+      const lines = Array.from({ length: 20 }, (_, i) => `line${i + 1}`);
+      const content = lines.join("\n");
+
+      const result = await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      expect(result).toContain("bytes:");
+      expect(result).toContain("lines: 20");
+      expect(result).not.toContain("line1");
+      expect(result).not.toContain("(preview)");
+    });
+
+    it("includes correct byte count", async () => {
+      const testFile = join(tempDir, "bytes.txt");
+      const content = "hello";
+
+      const result = await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      expect(result).toContain("bytes: 5");
+    });
+
+    it("handles unicode content correctly", async () => {
+      const testFile = join(tempDir, "unicode.txt");
+      const content = "한글 테스트\n이모지 🎉";
+
+      const result = await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      expect(result).not.toContain("한글 테스트");
+      expect(result).not.toContain("이모지 🎉");
+      expect(result).toContain("lines: 2");
+
+      const written = readFileSync(testFile, "utf-8");
+      expect(written).toBe(content);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles empty content", async () => {
+      const testFile = join(tempDir, "empty.txt");
+
+      const result = await executeWriteFile({ path: testFile, content: "" }, { rootDir: tempDir });
+
+      expect(result).toContain("OK - created empty.txt");
+      expect(result).toContain("bytes: 0");
+      expect(result).toContain("lines: 1");
+
+      const written = readFileSync(testFile, "utf-8");
+      expect(written).toBe("");
+    });
+
+    it("handles single line content", async () => {
+      const testFile = join(tempDir, "single.txt");
+      const content = "single line without newline";
+
+      const result = await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      expect(result).toContain("lines: 1");
+      expect(result).not.toContain("single line without newline");
+    });
+
+    it("handles content with special characters", async () => {
+      const testFile = join(tempDir, "special.txt");
+      const content = `const x = { a: 1, b: "test" };\nconst y = \`template \${x}\`;`;
+
+      await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      const written = readFileSync(testFile, "utf-8");
+      expect(written).toBe(content);
+    });
+  });
+
+  describe("file safety (C-1, C-2, H-1)", () => {
+    it("C-1: blocks path traversal via .. segments", async () => {
+      const traversalPath = join(tempDir, "..", "..", "etc", "passwd");
+      await expect(
+        executeWriteFile({ path: traversalPath, content: "malicious" }, { rootDir: tempDir })
+      ).rejects.toThrow(/[Pp]ath traversal blocked/);
+    });
+
+    it("C-1: blocks absolute paths outside project root", async () => {
+      await expect(
+        executeWriteFile({ path: "/tmp/outside-project.txt", content: "bad" }, { rootDir: tempDir })
+      ).rejects.toThrow(/[Pp]ath traversal blocked|outside/);
+    });
+
+    it("C-2: blocks writes through symlinks", async () => {
+      const realFile = join(tempDir, "real-target.txt");
+      writeFileSync(realFile, "original");
+      const symlinkPath = join(tempDir, "symlink-to-real.txt");
+      symlinkSync(realFile, symlinkPath);
+
+      await expect(
+        executeWriteFile({ path: symlinkPath, content: "through symlink" }, { rootDir: tempDir })
+      ).rejects.toThrow(/symlink/i);
+
+      // Original file should be unchanged
+      expect(readFileSync(realFile, "utf-8")).toBe("original");
+    });
+
+    it("C-2: blocks writes through symlinks pointing outside root", async () => {
+      const outsideDir = mkdtempSync(join(tmpdir(), "outside-root-"));
+      const outsideFile = join(outsideDir, "secret.txt");
+      writeFileSync(outsideFile, "secret data");
+      const symlinkPath = join(tempDir, "escape-link.txt");
+      symlinkSync(outsideFile, symlinkPath);
+
+      try {
+        await expect(
+          executeWriteFile({ path: symlinkPath, content: "overwrite" }, { rootDir: tempDir })
+        ).rejects.toThrow(/symlink/i);
+        expect(readFileSync(outsideFile, "utf-8")).toBe("secret data");
+      } finally {
+        rmSync(outsideDir, { recursive: true });
+      }
+    });
+
+    it("H-1: atomic write produces correct content (no partial writes)", async () => {
+      const testFile = join(tempDir, "atomic-test.txt");
+      const content = "line1\nline2\nline3";
+
+      await executeWriteFile({ path: testFile, content }, { rootDir: tempDir });
+
+      const written = readFileSync(testFile, "utf-8");
+      expect(written).toBe(content);
+    });
+
+    it("H-1: no temp files left after successful write", async () => {
+      const testFile = join(tempDir, "no-temp-residue.txt");
+      await executeWriteFile({ path: testFile, content: "clean" }, { rootDir: tempDir });
+
+      const dirEntries = readFileSync(testFile, "utf-8");
+      expect(dirEntries).toBe("clean");
+
+      // Check no .tmp- files remain in the directory
+      const { readdirSync } = require("node:fs");
+      const files: string[] = readdirSync(tempDir);
+      const tmpFiles = files.filter((f: string) => f.includes(".tmp-"));
+      expect(tmpFiles.length).toBe(0);
+    });
+
+    it("allows writes within project root (normal operation)", async () => {
+      const safeFile = join(tempDir, "safe-subdir", "nested.txt");
+      const result = await executeWriteFile(
+        { path: safeFile, content: "safe content" },
+        { rootDir: tempDir }
+      );
+
+      expect(result).toContain("OK - created nested.txt");
+      expect(readFileSync(safeFile, "utf-8")).toBe("safe content");
+    });
+  });
+});

package/src/tools/modify/write-file.ts

@@ -0,0 +1,56 @@
+import { mkdir } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { assertWriteSafety, safeAtomicWriteFile } from "../utils/safety-utils";
+import WRITE_FILE_DESCRIPTION from "./write-file.txt";
+
+const inputSchema = z.object({
+  path: z.string().describe("File path (absolute or relative)"),
+  content: z.string().describe("Content to write"),
+});
+
+export type WriteFileInput = z.infer<typeof inputSchema>;
+
+export interface WriteFileOptions {
+  /** Override project root for safety checks (defaults to process.cwd()). */
+  rootDir?: string;
+}
+
+export async function executeWriteFile(
+  { path, content }: WriteFileInput,
+  options?: WriteFileOptions
+): Promise<string> {
+  // C-1 + C-2: Path traversal and symlink safety checks
+  const safePath = await assertWriteSafety(path, options?.rootDir);
+
+  const dir = dirname(safePath);
+  if (dir !== ".") {
+    await mkdir(dir, { recursive: true });
+  }
+
+  // H-1: Atomic write with O_EXCL temp file + rename.
+  // safeAtomicWriteFile handles existence check (lstat), symlink rejection,
+  // crypto-random temp names, O_EXCL to prevent pre-creation attacks,
+  // and POSIX rename() which does not follow symlinks.
+  const { existed } = await safeAtomicWriteFile(safePath, content);
+
+  const lines = content.split("\n");
+  const lineCount = lines.length;
+  const byteCount = Buffer.byteLength(content, "utf-8");
+  const fileName = basename(path);
+  const action = existed ? "overwrote" : "created";
+
+  const output = [
+    `OK - ${action} ${fileName}`,
+    `bytes: ${byteCount}, lines: ${lineCount}`,
+  ];
+
+  return output.join("\n");
+}
+
+export const writeFileTool = tool({
+  description: WRITE_FILE_DESCRIPTION,
+  inputSchema,
+  execute: (input) => executeWriteFile(input),
+});

package/src/tools/modify/write-file.txt

@@ -0,0 +1,9 @@
+### write_file
+**Purpose**: Create new file or completely overwrite existing file
+
+**When to use**:
+- Creating new files from scratch
+- Replacing most or all contents of a file
+- Writing generated code/configuration
+
+**DO NOT use shell**: Prefer this over `echo >`, `cat <<EOF`, `printf >`

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "bun:test";
+import { executeLoadSkill } from "./load-skill";
+
+describe("executeLoadSkill", () => {
+  it("loads git-workflow skill successfully", async () => {
+    const result = await executeLoadSkill({ skillName: "git-workflow" });
+
+    expect(result).toContain("# Skill Loaded: git-workflow");
+    expect(result).toContain("# Git Workflow Skill");
+    expect(result).toContain("gh pr create");
+  });
+
+  it("returns error for non-existent skill", async () => {
+    const result = await executeLoadSkill({ skillName: "non-existent-skill" });
+
+    expect(result).toContain("Error: Skill 'non-existent-skill' not found");
+    expect(result).toContain("system prompt");
+  });
+
+  it("loads skill with frontmatter", async () => {
+    const result = await executeLoadSkill({ skillName: "git-workflow" });
+
+    expect(result).toContain("name: Git Workflow");
+    expect(result).toContain("description:");
+    expect(result).toContain("triggers:");
+  });
+
+  it("loads skill with prompts prefix", async () => {
+    const result = await executeLoadSkill({ skillName: "prompts:example" });
+
+    expect(result).toContain("# Skill Loaded: prompts:example");
+    expect(result).toContain("# Example Skill");
+  });
+
+  it("rejects path traversal attempts with ..", async () => {
+    const result = await executeLoadSkill({ skillName: "../../../etc/passwd" });
+
+    expect(result).toContain("Error: Invalid skill name");
+    expect(result).toContain("cannot contain '..' or '/'");
+  });
+
+  it("rejects path traversal attempts with /", async () => {
+    const result = await executeLoadSkill({ skillName: "foo/bar" });
+
+    expect(result).toContain("Error: Invalid skill name");
+    expect(result).toContain("cannot contain '..' or '/'");
+  });
+});