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 (default: 300; null disables the timeout),
• 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 is fully controlled by configuration via the default_timeout key in the ConfigMap; the tool does not accept any per-call timeout parameter.
• 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.).

Error handling

• If the underlying npm command finishes with a non-zero exit code but starts successfully, the tool returns a structured result with success = false, a non-zero exitCode, and captured stdout/stderr (after optional sanitization and truncation).
• ToolExecutionException is reserved for configuration or runtime-level issues (invalid configuration, sandbox/working directory problems, executor-level failures, timeouts, or unexpected internal errors).

Versioning

This project follows semantic versioning as closely as possible.

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