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.