toyaml

crystal kubernetes cli yaml converter serialization devops toml high-performance

High-performance data serialization CLI converter and Crystal shard streaming TOML to YAML

Lightning-fast, extensible CLI configuration converter and Crystal shard: streaming TOML, JSON, and other formats to canonical YAML.

GitLab Project Metadata:

Description: Lightning-fast, extensible CLI configuration converter and Crystal shard: streaming TOML, JSON, and other formats to canonical YAML.

Topics / Tags: crystal, crystal-lang, yaml, toml, json, converter, cli, serialization, podman, ameba, flaw, sphinx, agplv3

Overview

toyaml is a compiled, high-performance CLI utility and reusable Crystal shard engineered to convert structured configuration formats (starting with TOML and expanding to JSON, INI, and XML) directly into clean, canonical YAML. It features a pluggable format registry, direct streaming I/O into YAML::Builder, sub-millisecond cold starts, and zero runtime dependencies.

Key Highlights

Direct YAML Streaming: Streams parsed tokens directly into YAML::Builder(IO) without constructing intermediate hash graphs or heap string buffers.
Pluggable Architecture: Implements the Strategy and Registry patterns for format converters, making adding new formats frictionless.
Automatic Format Sniffing: Infers input formats from file extensions and stream heuristics, with explicit CLI overrides.
Sub-Millisecond Execution: Instantaneous cold starts (<5ms) and minimal resident memory footprint (<15 MB RSS).
Zero-Defect Quality Gates: Enforces 100% spec coverage, Ameba static analysis, Flaw SAST security scanning, and cRSTLint verification.

Quickstart

Prerequisites

Crystal: >= 1.21.0
Shards: Bundled with Crystal
GNU Make & Git
Podman (optional, for container runs)
cRSTLint (for documentation linting)

Build and Run Locally

# 1. Clone repository
git clone https://gitlab.com/renich/toyaml.git
cd toyaml

# 2. Setup dependencies and pre-commit hooks
make setup

# 3. Build the binary
make build

# 4. Run application CLI
./bin/toyaml --help

Running with Podman

# Build container image with Podman
make containers-build

# Run containerized service
make containers-run

Build System Targets

The repository includes a comprehensive, standard GNUmakefile:

Target	Description
`make build`	Compiles debug binary in `bin/toyaml`
`make release`	Builds stripped, statically optimized production binary
`make test`	Executes the complete spec test suite (`crystal spec`)
`make lint`	Runs Ameba static analysis and Flaw SAST security scanner
`make doc-check`	Lints all reStructuredText files using `crstlint` and `rstcheck`
`make check`	Aggregates `test`, `lint`, and `doc-check`
`make install`	Installs binary to `$(DESTDIR)$(bindir)` (FHS compliant)
`make install-local`	Installs binary to `~/.local/bin/toyaml`
`make containers-build`	Builds rootless container image using Podman
`make clean`	Cleans build artifacts in `bin/`
`make distclean`	Removes dependencies, cache directories, and build outputs

Documentation

Full architectural blueprints, functional specifications, and operational playbooks are maintained under docs/:

Guide	Scope & Highlights	Entry Point
Business Context & Strategy	Stakeholder requirements, ROI objectives, and user personas.	Business Specs
Functional Specifications	Requirements [FUNC-001]–[FUNC-005] and behavioral contracts.	Functional Specs
Technical Architecture	Process lifecycle, concurrency model, and threat modeling.	Technical Specs
Release Playbook	SemVer, Keep a Changelog, and GPG-signed GitLab release steps.	Release Procedure
Architecture Decisions (ADRs)	Immutable logs of architectural decisions and trade-offs.	ADR Index
Project Roadmap	Phased milestone tracking and delivery roadmaps.	Project Roadmap
Crystal API Reference	Compiler-generated API reference.	API Reference