Ukiryu Tool Register (v1)

Collection of YAML tool profiles for Ukiryu platform-adaptive command execution framework.

Purpose

The Ukiryu Tool Register contains declarative YAML profiles that define how to execute various command-line tools across different platforms, shells, and versions.

Each tool profile includes:

• Command definitions with arguments and options

• Platform-specific configurations (macOS, Linux, Windows)

• Shell-specific command formatting (bash, zsh, PowerShell, etc.)

• Version detection and compatibility handling

Schema Version

This register follows the v1 schema. All tool definitions conform to the schema defined in schemas/v1/tool.schema.yaml.

Tool Profiles

Supported Tools

• ImageMagick - Image conversion and processing

• Ghostscript - PostScript and PDF interpreter

• FFmpeg - Video/audio processing

• Pandoc - Document conversion

• jpegoptim - JPEG optimization

• optipng - PNG optimization

• Inkscape - SVG vector graphics

Directory Structure

register/
└── tools/
    ├── imagemagick/
    │   └── 7.1.yaml         # Versioned tool (specific version)
    │   └── index.yaml       # Version routing and implementation index
    ├── ghostscript/
    │   ├── 9.5.yaml
    │   ├── 10.0.yaml
    │   └── index.yaml
    ├── tar/
    │   ├── 1.35.yaml       # GNU tar 1.35
    │   ├── 1.36.1.yaml     # GNU tar 1.36.1
    │   ├── gnu/
    │   │   └── index.yaml  # GNU implementation routing
    │   └── busybox/
    │       └── index.yaml  # BusyBox implementation routing
    ├── cat/
    │   └── generic.yaml     # Generic tool (stable interface)
    ├── sort/
    │   └── generic.yaml     # Generic tool (stable interface)
    └── ...

Version routing with index.yaml

Tool versions are routed through index.yaml files using Versionian's version range matching syntax.

About Versionian

Versionian is a Ruby library for declaring, parsing, comparing, and rendering version schemes. It provides:

• Built-in schemes: Semantic (SemVer), Calendar versioning (CalVer), SoloVer, WendtVer

• Version range matching: equals, after, before, between for version constraints

• Extensible: Custom version schemes via declarative YAML or Ruby

Ukiryu uses Versionian internally to: * Parse detected tool versions * Compare versions against range specifications * Route to the appropriate YAML file based on version matching

Implementation index structure

Each tool can have multiple implementations (GNU, BusyBox, BSD, etc.), each with its own index.yaml:

# tools/tar/gnu/index.yaml
ukiryu_schema: '1.0'
name: tar
interface: tar

implementations:
  - name: gnu
    display_name: GNU tar
    detection:
      executable: tar
      command: ["--version"]
      pattern: "tar (GNU tar) ([0-9.]+)"
    version_scheme: semantic    (1)
    versions:
      # Exact version match (Versionian range type)
      - equals: "1.35"
        file: "1.35.yaml"

      # After version 1.35 (Versionian range type)
      # Uses semantic versioning comparison
      - after: "1.35"
        file: "1.35.yaml"

    # Default file when no version matches
    default: "1.35.yaml"

1. version_scheme tells Ukiryu which Versionian scheme to use for version comparison.

Version specification rules

The versions array in an implementation index supports Versionian’s range types:

• equals: "1.35" - Exact version match

• after: "1.35" - Matches any version >= 1.35 (semantic versioning)

• before: "2.0" - Matches any version < 2.0 (semantic versioning)

• between: "1.35", "2.0" - Matches versions in inclusive range [1.35, 2.0]

• between: "1.35", "2.0" - Matches versions in inclusive range [1.35, 2.0]

Each version spec must point to an actual YAML file that exists in the implementation directory (e.g., file: "1.35.yaml").

Important: Do not use symlinks or special filenames like "latest.yaml". Always reference the actual version file that exists.

Version scheme types

The version_scheme field specifies which Versionian scheme to use:

version_scheme: semantic   # MAJOR.MINOR.PATCH (e.g., 1.35.0)
version_scheme: calver     # YYYY.MM.DD (e.g., 2024.01.17)
version_scheme: solover    # N[+|-]postfix (e.g., 5+hotfix)
version_scheme: wendtver   # MAJOR.MINOR.PATCH.BUILD

Profile Schema

Tool profiles follow the v1 schema defined in schemas.

Key fields:

name

Tool identifier (e.g., "imagemagick")

display_name

Human-readable name

version

Tool version (see Version Naming)

implements

Interface contract this tool implements (e.g., "ping" for ping_gnu, ping_bsd)

version_detection

How to detect installed version (see Version Detection)

search_paths

Platform-specific executable locations

profiles

Array of platform/shell-specific configurations

commands

Command definitions with arguments, options, and flags

Version Naming

Tool profiles use two distinct versioning schemes:

• Versioned tools (e.g., imagemagick/7.1.yaml, ghostscript/10.0.yaml):: Tools with well-defined, detectable versions. These tools have version-specific commands, options, or behaviors that differ between releases.

• Generic tools (e.g., cat/generic.yaml, sort/generic.yaml):: System utilities whose core interface is stable across versions or where version detection is unreliable/unnecessary. These tools use "version: generic" instead of a numeric version.

When to use each:

• Use versioned profiles when:

  • The tool has version-specific command syntax or options

  • Version detection is reliable via --version or similar

  • Different versions have incompatible interfaces

• Use generic profiles when:

  • The tool is a standard Unix utility with stable interface (cat, grep, sort, etc.)

  • Version output varies by OS/distribution or is unreliable

  • The command syntax hasn’t changed meaningfully across versions

Examples:

# Versioned tool - FFmpeg has version-specific features
name: ffmpeg
version: "8.0"
version_detection:
  command: -version
  pattern: ffmpeg version ([\d.]+)

# Generic tool - cat has stable interface across versions
name: cat
version: generic
version_detection:
  detection_methods:
    - type: command
      command: --version
      pattern: cat \\(GNU coreutils\\) ([\\d.]+)
    - type: man_page
      paths:
        macos: /usr/share/man/man1/cat.1
        linux: /usr/share/man/man1/cat.1
  system_tool: true

Version Detection

Version detection determines which installed tool version to use. Ukiryu supports multiple detection methods with automatic fallback:

Detection Methods Array (recommended)

Provides multiple detection strategies with automatic fallback. If one method fails, the next is tried.

version_detection:
  detection_methods:
    # Method 1: Try --version flag first
    - type: command
      command: --version
      pattern: "Version ([\\d.]+)"

    # Method 2: Fall back to parsing man page
    - type: man_page
      paths:
        macos: /usr/share/man/man1/tool.1
        linux: /usr/share/man/man1/tool.1

    # Method 3: Mark as system tool if detection fails
    - type: system_tool

  modern_threshold: "1.0"  # Minimum "modern" version

Legacy Single Method (deprecated)

Simple single-method detection:

version_detection:
  command: --version
  pattern: "Version ([\\d.]+)"
  modern_threshold: "1.0"

Detection method types:

• command:: Run the tool and parse stdout/stderr for version

  • command:: Array of arguments (e.g., ["--version"] or ["-v", "-"])

  • pattern:: Regex with capture group for version number

• man_page:: Parse the man page for version information

  • paths:: Platform-specific man page paths

• system_tool:: Mark as OS-provided utility (no version detection)

The modern_threshold specifies the minimum version considered "modern" for compatibility checks.

Validating Tool Profiles

Local Validation

To validate a tool profile locally, install the Ukiryu gem and use the validate command:

# Install ukiryu
gem install ukiryu

# Validate a specific profile
ukiryu validate --definition tools/imagemagick/7.1.yaml

# Validate with schema from schemas repository
ukiryu validate --definition tools/imagemagick/7.1.yaml \
  --schema ../schemas/v1/tool.schema.yaml

# Validate all profiles in the register
ukiryu validate all

For executable testing (smoke tests), use the --executable flag:

ukiryu validate --definition tools/imagemagick/7.1.yaml --executable

Linting

For best practices checking, use the lint command:

# Lint a specific profile
ukiryu lint file tools/imagemagick/7.1.yaml

# Lint all profiles
ukiryu lint all

# Show all linting rules
ukiryu lint rules

Automated Validation

GitHub Actions automatically validates all tool profiles through two workflows:

Validation workflow (validate.yml)

Runs on:

• Pull requests that modify YAML files in tools//.yaml or interfaces//.yaml

• Pushes to main or v1 branches

• Daily scheduled runs (midnight UTC)

• Manual workflow dispatch

The workflow performs two levels of validation:

1. Schema validation - Always runs, validates YAML syntax and v1 schema compliance

2. Executable testing - Optional, installs actual tools and runs smoke tests

To trigger executable testing:

• Manually: Use workflow_dispatch with validate_executable: true

• Scheduled: Daily runs include executable testing

The workflow uses a tool installation matrix (.github/tools-matrix.yaml) to install tools across platforms:

# Example: imagemagick installation by platform
imagemagick:
  platforms:
    ubuntu:
      - sudo apt-get install -y imagemagick
    macos:
      - brew install imagemagick
    windows:
      - choco install imagemagick --yes

Linting workflow (lint.yml)

Runs on:

• Pull requests that modify YAML files

• Pushes to main or v1 branches

• Manual workflow dispatch

Checks for best practices violations using ukiryu lint all across Ubuntu and macOS.

CI/CD integration

You can add profile validation to your own CI/CD pipeline:

# .github/workflows/validate-profiles.yml
name: Validate Tool Profiles

on:
  pull_request:
    paths:
      - 'tools/**/*.yaml'
  push:
    tags:
      - 'v*'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'

      - name: Install ukiryu
        run: gem install ukiryu

      - name: Validate profiles
        run: |
          # Validate all changed YAML files
          ukiryu validate all

Cross-platform package installation verification

The register includes a comprehensive cross-platform package installation verification system that tests tool installation across all supported platforms.

Failure criteria

The CI build MUST FAIL if any of the following conditions are met:

1. Installation failure - If a package fails to install via the configured package manager (apt, homebrew, chocolatey, winget, etc.), the build fails.

2. Smoke test failure - If a tool installs successfully but the smoke test (basic CLI verification) fails to execute, the build fails. The smoke test verifies the tool executable can run basic commands (e.g., tool --version).

3. Ukiryu detection failure - If a tool passes smoke tests but Ukiryu cannot detect or execute the tool, the build fails. This ensures the tool definitions in the register accurately reflect installed tools.

These strict criteria ensure that:

• All declared packages can be installed on their target platforms

• Installed tools are functional and can execute commands

• Tool definitions accurately match installed tool versions and capabilities

Verification phases

The installation verification runs in these phases:

1. Install phase: Install packages using platform-appropriate package managers

2. Verify phase: For each installed tool:

   1. Locate the executable (checking bundled tools, package manager paths, system paths)

   2. Run smoke test command to verify basic functionality (e.g., tool --version)

   3. Verify the executable exists and is accessible

3. Validate phase: Run Ukiryu validation to verify:

   1. Tool definition matches the installed tool version

   2. Tool can be detected and executed by Ukiryu

   3. All declared commands and options are valid

Success requirements

For CI to pass, ALL of the following must succeed:

1. All packages in packages/*.yaml must install successfully (or be marked as platform-unavailable via platforms.windows: false etc.)

2. All installed tools must pass their smoke tests

3. All tools must be detectable and executable by Ukiryu (except on Windows where a known path handling issue currently skips this step)

Platform support

Verification runs on the following platforms:

• macOS: macOS 15 (ARM), macOS 15 Intel

• Linux: Ubuntu 24.04 (x64), Ubuntu 24.04 ARM

• Windows: Windows 2025 (x64)

Note	Windows 11 ARM is excluded due to nokogiri lacking precompiled binaries for aarch64-mingw-ucrt.

Adding a new tool

To add a new tool profile:

1. Determine the appropriate version naming scheme:

   • Use versioned profiles (tools/<tool>/<version>.yaml) for tools with version-specific interfaces

   • Use generic profiles (tools/<tool>/generic.yaml) for stable system utilities

2. Check the tool’s man page for command syntax

3. Create a new YAML file in tools/<tool-name>/

4. Follow the v1 schema defined in schemas/v1/tool.schema.yaml

5. Implement version detection using detection_methods array with fallback

6. Validate locally: ukiryu validate --definition tools/<tool-name>/<version>.yaml

7. Test the profile with real commands

8. Submit a pull request to the v1 branch

Versioned profile example

name: imagemagick version: "7.1" version_detection: command: -version pattern: Version: ImageMagick ([\d.]+) search_paths: macos: - /opt/homebrew/bin/magick linux: - /usr/bin/convert profiles: - name: default platforms: [macos, linux] shells: [bash, zsh] commands: - name: convert # …​ command definition

=== Generic profile example

[source,yaml]

name: cat
version: generic
version_detection:
  detection_methods:
    - type: command
      command: --version
      pattern: cat \\(GNU coreutils\\) ([\\d.]+)
    - type: man_page
      paths:
        macos: /usr/share/man/man1/cat.1
        linux: /usr/share/man/man1/cat.1
  system_tool: true
search_paths:
  macos:
  - /usr/bin/cat
  linux:
  - /usr/bin/cat
profiles:
  - name: unix
    platforms: [macos, linux]
    shells: [bash, zsh, fish, sh]
    commands:
      - name: concatenate
        # ... command definition

Validation checklist

Before submitting a pull request:

• ❏ YAML syntax is valid

• ❏ Conforms to v1 schema

• ❏ All required fields are present

• ❏ Tool name and version are correct

• ❏ Commands work on all supported platforms

• ❏ Version detection works if defined

• ❏ No linting warnings (or warnings are documented)

Extracting definitions

If you need to create a new profile from an installed tool, use the extract command:

# Extract definition from git
ukiryu extract git --output tools/git/2.45.yaml

# Extract with verbose output
ukiryu extract git --output tools/git/2.45.yaml --verbose

Usage

Tools are loaded automatically by Ukiryu:

require 'ukiryu'

Ukiryu::Register.default_register_path = 'path/to/register'

tool = Ukiryu::Tool.get(:imagemagick)
result = tool.execute(:convert, {
  inputs: ['input.png'],
  output: 'output.jpg',
  resize: '50x50'
})

License

The content is available as open source under the terms of the Ribose BSD 2-Clause License.

Copyright

Copyright Ribose.