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

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.