adachsoft/composer-tool
Advanced tools
AI tool-call adapter for running Composer operations via adachsoft/composer-lib.
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 primary AI tool named composer for Composer CLI
operations, and additional tools for direct composer.json inspection,
modification, and validation/fixing.
adachsoft/ai-tool-calladachsoft/composer-libadachsoft/command-executor-libadachsoft/normalized-safe-pathInstall via Composer:
composer require adachsoft/composer-tool
composer tool in AiToolCalluse 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();
composer tool// Example: install with defaults
$result = $facade->callTool(new ToolCallRequestDto(
toolName: 'composer',
parameters: [
'operation' => 'install',
],
));
$data = $result->result->all();
// $data contains (minimal, AI-friendly payload):
// - operation (string)
// - status (string enum from composer-lib, e.g. SUCCESS|FAILURE)
// - stdout (string)
// - stderr (string)
// 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',
],
));
composer tool)The composer tool exposes the following operations (aligned with the
adachsoft/composer-lib 0.3.x public API; see
AdachSoft\ComposerTool\Tool\ComposerTool::getDefinition() for
machine-readable schema):
Common optional parameter:
package_path (string, optional) - relative path (from the configured working_directory) to a monorepo package directory whose composer.json and working directory should be used for the operation, e.g. "packages/some-package". When omitted or an empty string, the base working_directory (root project) is used. Invalid or unsafe paths (e.g. traversing outside the working_directory) cause the tool call to fail with an InvalidToolCallException.
install
no_dev (bool, default: false) - skip dev dependenciesprefer_dist (bool, default: true)optimize_autoloader (bool, default: true)dry_run (bool, default: false)update
packages (string[] optional) - list of package names to updatewith_all_dependencies (bool, default: false)no_dev (bool, default: false)dry_run (bool, default: false)require
package_constraints (map<string,string>, required) - package => constraintdev (bool, default: false) - require as dev dependencydry_run (bool, default: false)remove
packages (string[] required) - list of package names to removedry_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 packagesdiagnose
show
package (string, optional) - package name to show (all if omitted)tree (bool, default: false) - show dependency treelicenses
depends
package (string, required) - package name to inspecttree (bool, default: false) - show dependency treeprohibits
package (string, required) - package nameconstraint (string, optional) - version constraintrun_script
script (string, required) - Composer script name from composer.jsonargs (string[] optional, default: []) - additional argumentsclear_cache
In addition to the composer CLI-like tool, this library provides four
SPI tools dedicated to working with composer.json in a given working
directory. These tools are intended to be called by AI agents, not by
humans directly.
composer_json_file
composer.json depending on
the operation parameter:
readwriteread_and_writepackage_path parameter to target a specific package directory inside a monorepo relative to the configured working_directory. When omitted or empty, the root composer.json in working_directory is used.composer_json_read
composer_json_file in read mode.composer.json file.package_path parameter to read composer.json from a specific monorepo package directory relative to working_directory. When omitted or empty, the root composer.json is read.composer_json_write
composer_json_file in write mode.composer.json.package_path parameter to write composer.json for a specific monorepo package directory relative to working_directory. When omitted or empty, the root composer.json is written.composer_json_fix
composer.json using adachsoft/composer-json-fixer.validate and fix.package_path parameter to validate/fix composer.json for a specific monorepo package directory relative to working_directory. When omitted or empty, the root composer.json is targeted.Each of these tools expects a working_directory configuration passed
via its corresponding factory:
ComposerJsonReadWriteToolFactoryComposerJsonReadToolFactoryComposerJsonWriteToolFactoryComposerJsonFixToolFactoryuse AdachSoft\AiToolCall\PublicApi\Builder\AiToolCallFacadeBuilder;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\ComposerTool\Tool\ComposerJsonReadToolFactory;
use AdachSoft\ComposerTool\Tool\ComposerJsonWriteToolFactory;
use AdachSoft\ComposerTool\Tool\ComposerJsonReadWriteToolFactory;
use AdachSoft\ComposerTool\Tool\ComposerJsonFixToolFactory;
$facade = AiToolCallFacadeBuilder::new()
->withSpiFactories([
new ComposerJsonReadToolFactory(),
new ComposerJsonWriteToolFactory(),
new ComposerJsonReadWriteToolFactory(),
new ComposerJsonFixToolFactory(),
])
->withToolConfigs([
'composer_json_read' => new ConfigMap([
'working_directory' => __DIR__,
]),
'composer_json_write' => new ConfigMap([
'working_directory' => __DIR__,
]),
'composer_json_file' => new ConfigMap([
'working_directory' => __DIR__,
]),
'composer_json_fix' => new ConfigMap([
'working_directory' => __DIR__,
]),
])
->build();
json vs dataFor tools that write composer.json (composer_json_write and
composer_json_file in write / read_and_write modes), the desired
file content can be provided in two alternative forms:
json (string)
composer.json contents as a raw JSON string.data (object / map)
composer.json as a JSON object
(associative array in PHP).At least one of json or data is required for write operations.
If neither is provided, the call is rejected with an
InvalidToolCallException.
The detailed rationale for this dual input model is described in
docs/ADR-001-composer-json-write-parameters.md.
use AdachSoft\AiToolCall\PublicApi\Dto\ToolCallRequestDto;
$result = $facade->callTool(new ToolCallRequestDto(
toolName: 'composer_json_read',
parameters: [],
));
$payload = $result->result->all();
// payload contains, among others:
// - operation: "read"
// - data: decoded JSON as a map
// - raw: raw JSON string content
$result = $facade->callTool(new ToolCallRequestDto(
toolName: 'composer_json_fix',
parameters: [
'operation' => 'validate',
],
));
$payload = $result->result->all();
// payload contains:
// - operation: "validate"
// - valid: bool - whether composer.json is valid
// - issues: array - list of validation issues (empty if valid)
$result = $facade->callTool(new ToolCallRequestDto(
toolName: 'composer_json_fix',
parameters: [
'operation' => 'fix',
],
));
$payload = $result->result->all();
// payload contains:
// - operation: "fix"
// - valid: bool - whether composer.json is valid after fixes
// - issues: array - list of remaining issues
// - diff: string - unified diff of changes made
// - was_written: bool - whether changes were written to disk
$result = $facade->callTool(new ToolCallRequestDto(
toolName: 'composer_json_write',
parameters: [
'json' => "{\n \"name\": \"vendor/package\"\n}\n",
'backup' => true,
'pretty' => true,
],
));
$result = $facade->callTool(new ToolCallRequestDto(
toolName: 'composer_json_write',
parameters: [
'data' => [
'name' => 'vendor/package',
'description' => 'Updated by AI agent',
],
'backup' => true,
'pretty' => true,
],
));
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)
FULL, STDOUT_ONLY, STDERR_ONLY, DISCARDconfig_patch_mode (string, default: PERMANENT)
PERMANENT, TEMPORARY, SKIPbackup_enabled (bool, default: true)Invalid configuration results in ToolConfigurationException being thrown
by the SPI layer (ComposerToolFactory).
The tool is designed so that AI agents receive clear, structured feedback about what went wrong.
The following cases result in AdachSoft\AiToolCall\SPI\Exception\InvalidToolCallException:
operation field:
Composer tool call is missing required parameter "operation".Composer tool parameter "operation" must be a string, got int.operation value:
Unsupported Composer operation "foo". Allowed operations: install, update, require, remove, dump_autoload, validate, outdated, diagnose, show, licenses, depends, prohibits, run_script, clear_cache.These messages are intended to be directly consumable by an AI agent and are
also propagated to any higher-level wrapper (for example as
"Tool call failed: <message>").
Certain domain-specific failures from adachsoft/composer-lib are reported
as regular tool results instead of SPI exceptions:
InvalidComposerJsonExceptionNonInteractiveViolationExceptionIn these cases the tool call succeeds from the SPI perspective, but the result payload indicates failure:
{
"operation": "install",
"status": "FAILURE",
"stdout": "",
"stderr": "Interactive mode is not allowed here."
}
This makes it easy for an AI agent to understand what Composer reported and decide how to proceed (e.g. adjust arguments and retry).
Any other unexpected failure during Composer execution (bugs, environment
issues, unhandled exceptions thrown by ComposerClientInterface or its
collaborators) is wrapped in
AdachSoft\AiToolCall\SPI\Exception\ToolExecutionException.
The exception message always includes the Composer operation name and the original error message, for example:
Composer operation "install" failed: <original-message>
Higher-level tooling (such as the AI integration layer) can then format
this as a single error string (e.g. "Tool call failed: Composer operation \"install\" failed: ..."),
while still retaining the original exception as the previous cause.
This package follows Semantic Versioning and is versioned exclusively
through Git tags. The composer.json file intentionally does not contain
an explicit version field.
MIT
FAQs
AI tool-call adapter for running Composer operations via adachsoft/composer-lib.
We found that adachsoft/composer-tool demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Compromised maintainer accounts pushed malicious @ethersphere/bee-js 13.3.0 and Swarm Desktop 0.56.2, reusing SleepyDuck’s Ethereum-addressed C2 infrastructure.
Security News
Socket has released a free Certified Patch for a critical Rails Active Storage vulnerability, giving developers time to upgrade to a secure Rails version.
Security News
/Threat Research
A malicious Ruby gem runs a credential-stealing worm during installation, poisons AI coding tools, and can wipe files when a stolen GitHub token is revoked.