ukiryu 0.1.1 → 0.1.3

data/docs/.gitignore

@@ -0,0 +1 @@
+.sass-cache/

data/docs/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'jekyll', '~> 3.10'
+gem 'jekyll-asciidoc', '~> 3.0'
+gem 'jekyll-seo-tag', '~> 2.8'
+gem 'jekyll-sitemap', '~> 1.4'
+gem 'just-the-docs', '~> 0.7.0'
+gem 'kramdown-parser-gfm', '~> 1.1'

data/docs/INDEX.adoc

@@ -0,0 +1,261 @@
+---
+layout: default
+title: "Ukiryu: Open Definitions For CLI Tools"
+nav_order: 1
+---
+
+== Ukiryu: Open Definitions For CLI Tools
+
+The "OpenAPI" for Command Line Interfaces.
+
+// Purpose
+== Purpose
+
+Ukiryu is a framework for defining command-line interfaces as declarative APIs.
+
+It makes the following possible:
+
+* Declarative definition of command-line interfaces, options, parameters and
+  typed arguments
+* Harmonized definitions across platforms and shell environments
+* Unified action interface across versioned and variant command interfaces
+* Structured input and output handling, with type safety and validation
+
+
+The Ukiryu framework has the following components:
+
+* **Register**: A collection of tool profiles encoded in YAML, organized by tool
+name and version
+
+* **Schema**: A formal definition of the structure and types used in tool
+profiles
+
+* **Runtime**: A platform-adaptive Ruby library that provides a harmonized API
+interface for CLI commands.
+
+
+== Origin
+
+The name 浮流 "ukiryu" (lit. "Floating Flow") is inspired by 天浮橋
+"ame-no-ukihashi" (lit. "Floating Bridge of Heaven"), the mythical bridge that
+connects heaven and earth.
+
+The ame-no-ukihashi is described in Japanese mythology as the place where the
+God Izanagi and Goddess Izanami stood at creating the Japanese archipelago.
+
+The pronunciation of "ukiryu" ("yoo-kee-rhoo") is the English transliteration of
+the Kanji characters 「浮流」, read in Hiragana as 「うきりゅう」.
+
+In the view that a command line tool is a vessel for performing tasks, Ukiryu
+serves as the flexible flow that guides its path through different environments.
+
+
+== Why Ukiryu?
+
+* **Platform-adaptive**: Commands work seamlessly across macOS, Linux, and Windows
+* **Shell-aware**: Proper quoting and escaping for bash, zsh, fish, PowerShell, and cmd
+* **Versioned**: Support multiple tool versions with distinct interfaces
+* **Interface-capable**: Different implementations of the same command interface
+* **Declarative**: Tool behavior defined in YAML profiles, not code
+* **Type-safe**: Parameter validation with automatic type coercion
+
+
+== Quick Start
+
+Use the command-line interface:
+
+[source,bash]
+----
+# List available tools
+ukiryu list
+
+# Show tool information
+ukiryu info inkscape
+
+# Describe a command
+ukiryu describe inkscape export
+
+# Convert SVG to PNG
+ukiryu exec inkscape export inputs=input.svg output=output.png format=png
+----
+
+Or use the Ruby API:
+
+[source,ruby]
+----
+# Install
+gem install ukiryu
+
+# Use in Ruby
+require 'ukiryu'
+
+tool = Ukiryu::Tool.get(:inkscape)
+result = tool.execute(:export, {
+  inputs: ['input.svg'],
+  output: 'output.png',
+  format: :png
+})
+
+puts result.success? ? "Success!" : "Failed: #{result.stderr}"
+----
+
+
+== What Can You Do With Ukiryu?
+
+=== By Role
+
+[source]
+==== Developer
+* Integrate command-line tools into Ruby applications
+* Write cross-platform scripts that work everywhere
+* Build tools with consistent interfaces across platforms
+
+==== QA Engineer
+* Automate testing with tools like ImageMagick, Ghostscript
+* Run tests on CI/CD across different platforms
+* Validate tool outputs programmatically
+
+==== DevOps Engineer
+* Create deployment scripts that work on any platform
+* Manage tool versions and compatibility
+* Debug tool execution issues
+
+==== Tool Maintainer
+* Publish tool profiles for community use
+* Support multiple tool versions simultaneously
+* Handle platform-specific differences declaratively
+
+=== By Task
+
+[source]
+==== Execute Commands
+* Run tools with type-safe parameters
+* Get structured results with success/failure info
+* Handle timeouts and errors gracefully
+
+==== Format Conversion
+* Convert between image formats (ImageMagick, Inkscape)
+* Process PDF/PostScript (Ghostscript)
+* Transform data formats (jq, yq)
+
+==== Testing & Validation
+* Compare outputs with diff tools
+* Validate file formats and metadata
+* Test CLI behavior programmatically
+
+==== Platform Adaptation
+* Handle path differences (/ vs \)
+* Manage shell quoting and escaping
+* Adapt to platform-specific tool locations
+
+// How Ukiryu Works
+== How Ukiryu Works
+
+Ukiryu uses a three-layer architecture:
+
+[source]
+----
+┌─────────────────────────────────────────────┐
+│           Ruby API / CLI                    │
+│  Tool.get(:imagemagick).execute(...)        │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│         Register & Profiles                 │
+│  tools/inkscape/1.0.yaml (declarative)     │
+└─────────────────┬───────────────────────────┐
+                  │
+┌─────────────────▼───────────────────────────┐
+│      Platform & Shell Adaptation            │
+│  Bash / Zsh / Fish / PowerShell / Cmd       │
+└─────────────────────────────────────────────┘
+----
+
+* **Register**: Loads tool profiles from YAML files
+* **Profiles**: Define tool behavior, versions, and platform support
+* **Shell Layer**: Handles quoting, escaping, and command formatting
+
+// Learning Paths
+== Learning Paths
+
+=== Beginner
+
+1. link:/getting-started/installation[Installation]
+2. link:/getting-started/quick-start[Quick Start Guide]
+3. link:/getting-started/core-concepts[Core Concepts]
+
+=== Intermediate
+
+1. link:/interfaces/ruby-api[Ruby API]
+2. link:/interfaces/cli[Command Line Interface]
+3. link:/features/configuration[Configuration Layers]
+
+=== Advanced
+
+1. link:/understanding/architecture[Architecture & Internals]
+2. link:/advanced/writing-profiles[Writing Tool Profiles]
+3. link:/advanced/platform-handling[Platform-Specific Handling]
+
+=== Reference
+
+1. link:/reference/tool-profile-schema[Tool Profile Schema]
+2. link:/reference/configuration-options[All Configuration Options]
+3. link:/reference/error-codes[Error Codes & Messages]
+
+// Configuration Methods
+== Configuration Methods
+
+Ukiryu supports three ways to configure tool execution, with clear precedence:
+
+[NOTE]
+Configuration precedence (highest to lowest):
+1. Environment variables
+2. Command-line parameters
+3. Ruby API parameters
+4. Profile defaults
+
+=== Ruby API
+
+[source,ruby]
+----
+tool = Ukiryu::Tool.get(:inkscape)
+result = tool.execute(:export, {
+  inputs: ['drawing.svg'],
+  output: 'drawing.png',
+  format: :png,
+  dpi: 300
+})
+----
+
+=== Command Line
+
+[source,bash]
+----
+ukiryu exec inkscape export \
+  inputs=drawing.svg \
+  output=drawing.png \
+  format=png \
+  dpi=300
+----
+
+=== Environment Variables
+
+[source,bash]
+----
+# Set register location
+export UKIRYU_REGISTER=/path/to/register
+
+# Set default timeout
+export UKIRYU_TIMEOUT=120
+
+# Enable debug output
+export UKIRYU_DEBUG=true
+----
+
+// Next Steps
+== Next Steps
+
+* link:/getting-started/installation[Install Ukiryu] and get started
+* link:/getting-started/quick-start[Try the quick start guide]
+* link:/features/configuration[Explore configuration options]
+* link:/reference/tool-profile-schema[Learn the profile schema]

data/docs/_config.yml

@@ -0,0 +1,180 @@
+# Site settings
+title: Ukiryu
+description: >-
+  Platform-adaptive command execution framework for Ruby tools
+baseurl: "/ukiryu"
+url: "https://ukiryu.com"
+logo: "/assets/logo.svg"
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
+color_scheme: light
+
+# Search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: true
+
+# Navigation
+nav_sort: case_insensitive
+nav_fold: true
+
+# External links
+aux_links:
+  "GitHub":
+    - "https://github.com/ukiryu/ukiryu"
+  "RubyGems":
+    - "https://rubygems.org/gems/ukiryu"
+
+aux_links_new_tab: true
+
+# Back to top
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Heading anchors
+heading_anchors: true
+
+# Footer
+footer_content: 'Copyright &copy; 2025 Ribose. Distributed under the <a href="https://github.com/ukiryu/ukiryu/blob/main/LICENSE">MIT license</a>.'
+
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
+# Plugins
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# AsciiDoc support
+asciidoc: {}
+asciidoctor:
+  attributes:
+    idprefix: ''
+    idseparator: '-'
+    source-highlighter: rouge
+    icons: font
+    experimental: true
+    sectanchors: true
+    linkattrs: true
+    sectnums: true
+
+# Markdown settings
+markdown: kramdown
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge
+
+# Collections for organizing content
+collections:
+  pages:
+    permalink: "/:path/"
+    output: true
+  getting-started:
+    permalink: "/:collection/:path/"
+    output: true
+  interfaces:
+    permalink: "/:collection/:path/"
+    output: true
+  understanding:
+    permalink: "/:collection/:path/"
+    output: true
+  features:
+    permalink: "/:collection/:path/"
+    output: true
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+  advanced:
+    permalink: "/:collection/:path/"
+    output: true
+  reference:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    pages:
+      name: Pages
+      nav_fold: false
+    getting-started:
+      name: Getting Started
+      nav_fold: false
+    interfaces:
+      name: Interfaces
+      nav_fold: false
+    understanding:
+      name: Understanding
+      nav_fold: true
+    features:
+      name: Features
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    advanced:
+      name: Advanced
+      nav_fold: true
+    reference:
+      name: Reference
+      nav_fold: true
+
+# Defaults
+defaults:
+  - scope:
+      path: ""
+      type: pages
+    values:
+      layout: default
+
+# Include additional files
+include:
+  - "*.adoc"
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor
+  - .sass-cache
+  - .jekyll-cache
+  - .bundle
+  - README.md
+  - LICENSE
+  - .git
+  - .gitignore
+
+permalink: pretty