adachsoft/composer-tool

AI tool-call adapter for running Composer operations via adachsoft/composer-lib.

v0.2.1 2025-12-15 06:49 UTC

Requires

• adachsoft/ai-tool-call: *
• adachsoft/command-executor-lib: *
• adachsoft/composer-lib: ^0.3.1
• adachsoft/normalized-safe-path: *

Requires (Dev)

• adachsoft/php-code-style: ^0.2.1
• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4

MIT

• Arkadiusz Adach

• composer
• automation
• ai
• dependency-management
• tool-call

README

AI tool-call adapter for running Composer operations via adachsoft/composer-lib, implemented as a SPI tool for adachsoft/ai-tool-call.

This library exposes a single AI tool named composer that can perform non-interactive Composer operations such as install, update, require, remove, dump_autoload, validate, outdated, diagnose, show, licenses, depends, prohibits, run_script, and clear_cache.

Requirements

• PHP ^8.3
• adachsoft/ai-tool-call
• adachsoft/composer-lib
• adachsoft/command-executor-lib
• adachsoft/normalized-safe-path

Installation

Install via Composer:

composer require adachsoft/composer-tool

Quick Start

Registering the tool in AiToolCall

use AdachSoft\AiToolCall\PublicApi\Builder\AiToolCallFacadeBuilder;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\AiToolCall\PublicApi\Dto\ToolCallRequestDto;
use AdachSoft\ComposerTool\Tool\ComposerToolFactory;

$facade = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([
        new ComposerToolFactory(),
    ])
    ->withToolConfigs([
        'composer' => new ConfigMap([
            'working_directory' => __DIR__,
            // optional configuration, see below
            'hard_timeout_seconds' => 60,
            'activity_timeout_seconds' => 30,
            'non_interactive_enforced' => true,
            'output_capture_mode' => 'FULL',      // FULL|STDOUT_ONLY|STDERR_ONLY|DISCARD
            'config_patch_mode' => 'PERMANENT',   // PERMANENT|TEMPORARY|SKIP
            'backup_enabled' => true,
        ]),
    ])
    ->build();

Calling the composer tool

// Example: install with defaults
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'install',
    ],
));

$data = $result->result->all();

// $data contains:
// - operation           (string)
// - working_directory   (string)
// - success             (bool)
// - exit_code           (int)
// - status              (string enum from composer-lib)
// - stdout              (string)
// - stderr              (string)
// - duration_seconds    (float|int)

// Example: update specific packages in dry-run mode
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'update',
        'packages' => ['vendor/package-a', 'vendor/package-b'],
        'with_all_dependencies' => true,
        'dry_run' => true,
    ],
));

// Example: require packages with constraints as dev dependencies
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'require',
        'package_constraints' => [
            'vendor/package-a' => '^1.0',
            'vendor/package-b' => '~2.3',
        ],
        'dev' => true,
    ],
));

// Example: show package information with dependency tree
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'show',
        'package' => 'vendor/package',
        'tree' => true,
    ],
));

// Example: list licenses for all installed packages
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'licenses',
    ],
));

// Example: find why a package is installed
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'depends',
        'package' => 'vendor/package',
        'tree' => true,
    ],
));

// Example: check which packages prevent installing a given version
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'prohibits',
        'package' => 'vendor/package',
        'constraint' => '^1.0',
    ],
));

// Example: run a Composer script with additional arguments
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'run_script',
        'script' => 'my-script',
        'args' => ['--flag', 'value'],
    ],
));

// Example: clear Composer cache
$result = $facade->callTool(new ToolCallRequestDto(
    toolName: 'composer',
    parameters: [
        'operation' => 'clear_cache',
    ],
));

Available operations and parameters

The composer tool exposes the following operations (aligned with the adachsoft/composer-lib 0.3.0 public API; see AdachSoft\\ComposerTool\\Tool\\ComposerTool::getDefinition() for machine-readable schema):

• install

  • no_dev (bool, default: false)  skip dev dependencies
  • prefer_dist (bool, default: true)
  • optimize_autoloader (bool, default: true)
  • dry_run (bool, default: false)

• update

  • packages (string[] optional)  list of package names to update
  • with_all_dependencies (bool, default: false)
  • no_dev (bool, default: false)
  • dry_run (bool, default: false)

• require

  • package_constraints (map<string,string>, required)  package => constraint
  • dev (bool, default: false)  require as dev dependency
  • dry_run (bool, default: false)

• remove

  • packages (string[] required)  list of package names to remove
  • dry_run (bool, default: false)

• dump_autoload

  • optimize (bool, default: true)
  • classmap_authoritative (bool, default: false)

• validate

  • no_check_publish (bool, default: true)

• outdated

  • direct (bool, default: true)  only directly required packages

• diagnose

  • no extra parameters

• show

  • package (string, optional)  package name to show (all if omitted)
  • tree (bool, default: false)  show dependency tree

• licenses

  • no extra parameters

• depends

  • package (string, required)  package name to inspect
  • tree (bool, default: false)  show dependency tree

• prohibits

  • package (string, required)  package name
  • constraint (string, optional)  version constraint

• run_script

  • script (string, required)  Composer script name from composer.json
  • args (string[] optional, default: [])  additional arguments

• clear_cache

  • no extra parameters

Configuration options (factory)

ComposerToolFactory reads configuration from ConfigMap with the following keys:

• working_directory (string, required, non-empty)
• hard_timeout_seconds (int, default: 60)
• activity_timeout_seconds (int, default: 30)
• non_interactive_enforced (bool, default: true)
• output_capture_mode (string, default: FULL)
  • allowed values: FULL, STDOUT_ONLY, STDERR_ONLY, DISCARD
• config_patch_mode (string, default: PERMANENT)
  • allowed values: PERMANENT, TEMPORARY, SKIP
• backup_enabled (bool, default: true)

Invalid configuration results in ToolConfigurationException being thrown by the SPI layer (ComposerToolFactory).

Error handling

During execution, the following error cases are wrapped into SPI exceptions from adachsoft/ai-tool-call:

• Invalid or unsupported operation value results in SPI\Exception\InvalidToolCallException.
• If Composer attempts to run in interactive mode, NonInteractiveViolationException from adachsoft/composer-lib is converted to SPI\Exception\ToolExecutionException with an explanatory message.
• Any other failure during Composer execution (non-zero exit code, internal errors) is reported as SPI\Exception\ToolExecutionException.

The concrete error details are still available via the wrapped previous exception and via the stdout/stderr fields in the tool result payload.

Versioning

This package follows Semantic Versioning and is versioned exclusively through Git tags. The composer.json file intentionally does not contain an explicit version field.

License

MIT