README

Tools for safe file read/write/delete operations integrated with adachsoft/ai-tool-call SPI.

• Namespaces: AdachSoft\AiFileTool
• Tools:
  • file_read: read multiple files with extension policy and size limits
  • file_write: write multiple files with modes (create_new/overwrite/append)
  • file_delete: delete multiple files with safe paths and extension policies
  • directory_delete: delete multiple directories recursively with safe paths
• Global configuration driven at factory time (ConfigMap)
• Safe paths (normalized-safe-path) and filesystem operations (adachsoft/filesystem)
• Binary support via Base64 with global toggle
• Per-file results: ok/status/message/content without mixing content with error messages

Requirements

• PHP >= 8.3
• ext-mbstring
• adachsoft/ai-tool-call 2.0.0
• adachsoft/filesystem 1.3.0
• adachsoft/ai-tool-call-plugin >= 0.2.0

Installation

composer require adachsoft/ai-file-tool

Enable the composer plugin discovery in your root project and ensure entry-file points to resources/ai-tool-call.php.

Factories (entry-file)

resources/ai-tool-call.php returns SPI factories for this package:

<?php

declare(strict_types=1);

use AdachSoft\AiFileTool\Factory\DirectoryDeleteToolFactory;
use AdachSoft\AiFileTool\Factory\FileDeleteToolFactory;
use AdachSoft\AiFileTool\Factory\FileReadToolFactory;
use AdachSoft\AiFileTool\Factory\FileWriteToolFactory;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;

return [
    'factories' => [
        [
            'factory' => FileReadToolFactory::class,
            'config' => new ConfigMap([
                'base_dir' => '.',
                'allow_extensions' => null,
                'deny_extensions' => null,
                'allow_binary' => true,
                'default_encoding' => 'text',
                'max_file_size_bytes' => 65536,
                'allow_overwrite' => false,
                'create_directories' => true,
            ]),
        ],
        [
            'factory' => FileWriteToolFactory::class,
            'config' => new ConfigMap([
                'base_dir' => '.',
                'allow_extensions' => null,
                'deny_extensions' => null,
                'allow_binary' => true,
                'default_encoding' => 'text',
                'max_file_size_bytes' => 65536,
                'allow_overwrite' => false,
                'create_directories' => true,
            ]),
        ],
        [
            'factory' => FileDeleteToolFactory::class,
            'config' => new ConfigMap([
                'base_dir' => '.',
                'allow_extensions' => null,
                'deny_extensions' => null,
                'allow_binary' => true,
                'default_encoding' => 'text',
                'max_file_size_bytes' => 65536,
                'allow_overwrite' => false,
                'create_directories' => true,
            ]),
        ],
        [
            'factory' => DirectoryDeleteToolFactory::class,
            'config' => new ConfigMap([
                'base_dir' => '.',
                'allow_extensions' => null,
                'deny_extensions' => null,
                'allow_binary' => true,
                'default_encoding' => 'text',
                'max_file_size_bytes' => 65536,
                'allow_overwrite' => false,
                'create_directories' => true,
            ]),
        ],
    ],
];

Configuration (global)

See AdachSoft\AiFileTool\Config\FileToolConfigDto for available options. Typical values:

• baseDir: "var/data"
• allowExtensions: ["md","txt","php"]
• denyExtensions: ["php","js"] => final allowed: ["md","txt"]
• allowOverwrite: false, createDirectories: true
• allowBinary: true, defaultEncoding: "text", maxFileSizeBytes: 65536

Configuration is applied by the factories using ConfigMap when creating the SPI tools. Note that ConfigMap keys are snake_case (e.g. base_dir, allow_extensions), while FileToolConfigDto properties use camelCase.

Parameters & Results

• file_read

  • parameters: { paths: string[], encoding?: 'text'|'base64' }
  • result: { files: [ { path, ok, status, message?, content?, size_bytes? } ] }

• file_write

  • parameters: { files: [ { path, content, encoding?: 'text'|'base64', mode?: 'create_new'|'overwrite'|'append' } ] }
  • result: { files: [ { path, ok, status, message?, bytes_written? } ] }

• file_delete

  • parameters: { paths: string[] }
  • result: { files: [ { path, ok, status, message? } ] }

• directory_delete

  • parameters: { paths: string[] }
  • result: { directories: [ { path, ok, status, message? } ] }

Note: The public API accepts strings for encoding/mode; internally the library uses enums for strictness where applicable.

Notes

• All path operations go through normalized-safe-path and AdachSoft FileSystem implementations.
• "File not found" as a literal content is not treated as error.
• Deny list subtracts from allow list. When allow is null => all allowed except deny.

Versioning

This project is versioned exclusively via Git tags. The composer.json does not contain the version field.