adachsoft/npm-tool

AI npm tool for executing npm commands via adachsoft/ai-tool-call SPI.

v0.1.0 2026-02-03 16:32 UTC

Requires

• php: ^8.2
• adachsoft/ai-tool-call: 2.0.1
• adachsoft/command-executor-lib: ^2.0
• adachsoft/normalized-safe-path: ^0.1.0
• symfony/process: ^7.0

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.5
• rector/rector: ^1.0

MIT

• sandbox
• tool
• node
• npm
• ai
• package-manager
• ai-tool-call
• command-executor

README

AI-friendly npm tool for executing npm commands via the adachsoft/ai-tool-call SPI.

This library exposes a single SPI tool named npm_tool that allows an AI agent to run safe npm commands inside a sandboxed project directory, using adachsoft/command-executor-lib and adachsoft/normalized-safe-path under the hood.

Installation

composer require adachsoft/npm-tool

Requirements

• PHP >= 8.2
• adachsoft/ai-tool-call >= 2.0.1
• adachsoft/command-executor-lib >= 2.0
• adachsoft/normalized-safe-path >= 0.1.0

Quick start

Register the NpmToolFactory in your AI tool-call configuration and provide a ConfigMap for the npm_tool with keys:

• base_path (string, required): absolute path to the project root (sandbox root),
• npm_path (string, optional): path to the npm binary (default: npm),
• safe_mode (bool, optional): whether to restrict commands to a safe allow-list (default: true),
• default_timeout (int|null, optional): default timeout in seconds,
• max_output_length (int, optional): maximum length of stdout/stderr,
• sanitize_base_path (bool, optional): whether to sanitize absolute base_path from output.

The AI agent only sees the logical project workspace; base_path is an internal configuration detail used to enforce filesystem sandboxing.

More detailed usage examples are available in:

• .docs/NPM_TOOL_USAGE_EXAMPLES.md

Tool behavior

• Tool name: npm_tool.
• Parameters:
  • command (string, required): npm command to execute (without npm prefix), e.g. install, run build, --version.
  • cwd (string, optional): working directory inside the project (relative path, cannot escape the project).
  • timeout (int, optional): per-call timeout in seconds overriding default_timeout from config.
• Output fields:
  • success (bool),
  • stdout (string),
  • stderr (string),
  • exitCode (int),
  • command (string, full command executed),
  • workingDirectory (string, effective working directory).

Safe mode ensures that only a predefined allow-list of npm subcommands can be executed (e.g. install, update, audit, outdated, list, run, test, build, --version, etc.).

Versioning

This project follows semantic versioning as closely as possible.

See CHANGELOG.md for a list of notable changes per release.