README

A thin AI tool-call compatible wrapper around adachsoft/changelog-linter for managing changelog.json and CHANGELOG.md.

Installation

Install via Composer:

composer require adachsoft/changelog-tool

Usage with adachsoft/ai-tool-call

Register the SPI factory in your ai-tool-call setup:

use AdachSoft\AiToolCall\PublicApi\Builder\AiToolCallFacadeBuilder;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\ChangelogTool\Tool\ChangelogToolFactory;

$facade = AiToolCallFacadeBuilder::new()
 ->withSpiFactories([
 new ChangelogToolFactory(),
 ])
 ->withToolConfigs([
 'changelog_tool' => new ConfigMap([
 'base_path' => getcwd(),
 'changelog_binary_path' => 'vendor/bin/changelog',
 // Default locations and behaviour (config-only, not per-call parameters)
 'json_path' => 'changelog.json',
 'markdown_path' => 'CHANGELOG.md',
 'timeout' => 900, // 15 minutes
 'with_created_at' => true, // used for generate-json
 'default_lenient' => false, // default when `lenient` is not provided per call
 ]),
 ])
 ->build();

Then call the tool from your agent or application:

use AdachSoft\AiToolCall\PublicApi\Dto\ToolCallRequestDto;

// Validate changelog.json (paths and behaviour come from ConfigMap)
$result = $facade->callTool(new ToolCallRequestDto(
 toolName: 'changelog_tool',
 parameters: [
 'mode' => 'validate',
 ],
));

// Generate CHANGELOG.md from changelog.json
$result = $facade->callTool(new ToolCallRequestDto(
 toolName: 'changelog_tool',
 parameters: [
 'mode' => 'generate_md',
 ],
));

// Generate changelog.json from CHANGELOG.md with lenient parsing
$result = $facade->callTool(new ToolCallRequestDto(
 toolName: 'changelog_tool',
 parameters: [
 'mode' => 'generate_json',
 'lenient' => true,
 ],
));

Parameters (per-call)

The changelog_tool exposes the following per-call parameters (snake_case):

• mode (string, required): one of validate, generate_md, generate_json.
• lenient (bool, optional): enable lenient parsing/validation for Markdown to JSON (when omitted, default_lenient from ConfigMap is used).

All file paths, timeout and with_created_at behaviour are configured only via ConfigMap in the factory, not as per-call parameters.

Configuration (ConfigMap keys)

The factory ChangelogToolFactory reads the following configuration keys:

• base_path (string, required): project root used as cwd and base for resolving relative paths.
• changelog_binary_path (string, optional): path to the changelog CLI, relative to base_path or absolute (default: vendor/bin/changelog).
• json_path (string, optional): default path to changelog.json (default: changelog.json).
• markdown_path (string, optional): default path to CHANGELOG.md (default: CHANGELOG.md).
• timeout (int, optional): default timeout in seconds for the CLI process (default: 900 seconds).
• with_created_at (bool, optional): when generating JSON from Markdown, add createdAt metadata (default: true).
• default_lenient (bool, optional): default value for lenient mode when lenient is not provided per call (default: false).

Result shape

The tool always returns a structured result with the following keys:

• stdout (string)
• stderr (string)
• exit_code (int)
• success (bool)

Paths in stdout/stderr are sanitized to remove the configured base_path prefix where applicable.