adachsoft/git-tool

Git tool adapter for adachsoft/ai-tool-call built on top of adachsoft/gitlib.

v0.2.0 2025-12-23 07:16 UTC

Requires

• adachsoft/ai-tool-call: *
• adachsoft/gitlib: 1.2.0
• adachsoft/normalized-safe-path: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4

MIT

• Arkadiusz Adach

• git
• adapter
• spi
• ai-tool-call
• ai-tool

README

Git tool adapter for adachsoft/ai-tool-call.

This library exposes a small, well-defined subset of Git operations as an AI-callable tool. It is built on top of adachsoft/gitlib and is intended to be used by agents via the SPI layer of adachsoft/ai-tool-call.

Currently supported operations:

• status  read repository status (branch, staged/modified/untracked/deleted files, raw output)
• add  stage files in the index
• commit  create a new commit with a message
• push  push commits or tags to a remote

The tool is designed to be explicit and safe: all operations and their options are clearly described in the SpiToolDefinitionDto returned by GitTool::getDefinition().

Installation

Install via Composer:

composer require adachsoft/git-tool

This package depends on:

• adachsoft/ai-tool-call  SPI + public API for calling tools from agents
• adachsoft/gitlib  Git operations backend

Check their respective composer.json files for exact PHP version requirements.

Architecture overview

The package is intentionally small and split into three main layers:

• SPI Tool (integration layer)
  • AdachSoft\GitTool\Tool\GitTool  implementation of AdachSoft\AiToolCall\SPI\ToolInterface
  • AdachSoft\GitTool\Tool\GitToolFactory  implementation of AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface
• Service layer
  • AdachSoft\GitTool\Service\GitToolService / GitToolServiceInterface
  • AdachSoft\GitTool\Service\GitOperationRegistry / GitOperationRegistryInterface
• DTOs & Exceptions
  • AdachSoft\GitTool\Dto\GitToolRequestDto, GitToolResultDto
  • Domain-specific exceptions under AdachSoft\GitTool\Exception

The SPI layer knows only about the generic operation and options structure. The service layer maps these operations to concrete calls on Adachsoft\GitLab\Contracts\GitRepositoryInterface from adachsoft/gitlib.

Configuration: base_path

The Git repository location is configured once, when the tool is created by the factory. It is not provided per call.

GitToolFactory::create() accepts an AdachSoft\AiToolCall\SPI\Collection\ConfigMap with the following option:

• base_path (string, optional)
  • Base path of the Git repository.
  • When omitted, the current working directory (getcwd()) is used.
  • When provided, it must be a non-empty string and an existing directory.

Example:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\GitTool\Tool\GitToolFactory;

$config = new ConfigMap([
    'base_path' => '/path/to/your/git/repository',
]);

$factory = new GitToolFactory();
$tool = $factory->create($config); // returns an instance of AdachSoft\GitTool\Tool\GitTool

The hosting application is responsible for wiring the factory into the SPI infrastructure of adachsoft/ai-tool-call (see that package's documentation for exact integration steps).

Tool interface: operations and options

The tool parameters are described by GitTool::getDefinition() via SpiToolDefinitionDto. Conceptually, the parameters have the following shape:

{
  "operation": "status | add | commit | push",
  "options": {
    // operation-specific
  }
}

operation

• Type: string
• Required: yes
• Allowed values:
  • status
  • add
  • commit
  • push

options

• Type: object
• Required: no (but some fields become required depending on the operation)

Operation: status

Returns a snapshot of the repository status.

• Options: none required; extra keys are currently ignored.
• Result (data) contains at least:
  • branch (string)
  • staged (string[])
  • modified (string[])
  • untracked (string[])
  • deleted (string[])
  • raw_output (string)  raw git status output

Operation: add

Stages files in the index (git add).

Options:

• files (string[], required)
  • List of file paths to stage.

Result (data):

• success (bool)  true on success

Operation: commit

Creates a new commit with the given message.

Options:

• message (string, required)
  • Commit message.

Result (data):

• success (bool)  true when the commit was created

Operation: push

Pushes commits or tags to a remote. Under the hood this builds a Adachsoft\GitLab\DTO\Options\PushOptions instance and calls GitRepositoryInterface::push().

Options (all optional; semantics follow PushOptions):

• remote (string, nullable)
  • Remote name, e.g. origin.
• branch (string, nullable)
  • Branch name to push.
• tag (string, nullable)
  • Tag name to push.
• force (bool, nullable)
  • Force push.
• forceWithLease (bool, nullable)
  • Force with lease.
• setUpstream (bool, nullable)
  • Set upstream tracking for the branch.

Result (data):

• success (bool)  true on successful push

Result format

Every successful tool call returns a ToolCallResultDto that wraps a KeyValueMap with the following structure:

{
  "operation": "status | add | commit | push",
  "data": { /* operation-specific result */ }
}

Examples:

// status
{
  "operation": "status",
  "data": {
    "branch": "main",
    "staged": ["src/GitTool.php"],
    "modified": [],
    "untracked": ["README.md"],
    "deleted": [],
    "raw_output": "On branch main..."
  }
}

// commit
{
  "operation": "commit",
  "data": {
    "success": true
  }
}

Error handling

The tool validates input at the SPI boundary:

• missing or empty operation  InvalidToolCallException
• non-array options  InvalidToolCallException

Domain-level errors are mapped to ToolExecutionException:

• unsupported operation value
• invalid per-operation options (e.g. missing message for commit)
• failures coming from the underlying Git library

The original domain exception is attached as the previous exception for easier debugging.

Development & tests

The repository includes a small set of PHPUnit tests covering:

• the SPI tool (GitTool)
• the factory (GitToolFactory)
• the service layer (GitToolService)
• the operation registry (GitOperationRegistry)

Run the test suite with:

composer install
vendor/bin/phpunit