README

Surgical file editing toolkit for Coqui. Provides precise, token-efficient code editing operations with full undo history — replace, insert, remove, indent, batch operations, all sandboxed to the workspace.

Requirements

• PHP 8.4+
• Coqui (auto-discovered via Composer)

Installation

composer require coquibot/coqui-toolkit-code-edit

When installed alongside Coqui, the toolkit is auto-discovered via Composer's extra.php-agents.toolkits — no manual registration needed.

Tools Provided

replace_in_file

Replace text in a file using plain string or PCRE regex matching.

insert_before

Insert content before lines matching an anchor pattern.

insert_after

Insert content after lines matching an anchor pattern.

replace_block

Replace a block of content between start and end markers (inclusive).

remove_lines

Remove a range of lines from a file.

extract_lines

Extract a range of lines from a file (read-only, does not modify the file).

batch_replace

Run search/replace across multiple files matching a glob pattern.

append_to_file

Append text to the end of a file. Creates the file if it doesn't exist.

write_lines

Overwrite a specific range of lines with new content.

indent_lines

Indent or outdent a range of lines.

undo_edit

Undo previous code-edit operations by restoring original file content.

Architecture

src/
├── CodeEditToolkit.php          # Main toolkit — registers all tools
├── Exception/
│   └── CodeEditException.php    # Domain exceptions
├── Storage/
│   └── EditHistory.php          # SQLite edit log + file backups
├── Support/
│   ├── FileOperations.php       # Atomic reads/writes, EOL detection
│   └── PathResolver.php         # Workspace sandbox enforcement
└── Tool/
    ├── AppendToFileTool.php
    ├── BatchReplaceTool.php
    ├── ExtractLinesTool.php
    ├── IndentTool.php
    ├── InsertAfterTool.php
    ├── InsertBeforeTool.php
    ├── RemoveLinesTool.php
    ├── ReplaceBlockTool.php
    ├── ReplaceInFileTool.php
    ├── UndoEditTool.php
    └── WriteLinesTool.php

Key Design Decisions

Notes

• All paths are relative to the workspace root and sandboxed — directory traversal is blocked.
• Regex uses PCRE with ~ as delimiter (no need to escape / in patterns).
• Writes are atomic via temp file + rename to prevent corruption.
• Edit history is stored in .workspace/code-edit/history.db with file backups in .workspace/code-edit/backups/.
• Use undo_edit(prune_days: 7) periodically to clean up old backups.

Development

composer install
composer test        # Run Pest tests
composer analyse     # Run PHPStan (level 8)

License

MIT