noya-cli 0.0.4

Contents

• Install — every channel mapped
• Quick Start — common workflows
• noyafmt — formatter reference
• noyavalidate — validator + autofix reference
• Exit codes — for shell pipelines and CI gates
• Examples — runnable demo scripts
• Shell completions and man pages
• Verification — cosign + SLSA cookbook
• When not to use these tools
• Documentation
• License

Install

Pre-built tarballs for 14 targets (Linux gnu + musl, macOS Intel + Apple Silicon + universal, Windows x86_64 + i686 + aarch64) are attached to every GitHub Release. Each artefact is signed with cosign keyless and carries a SLSA L3 build provenance attestation — see Verification for the verify commands or pkg/VERIFY.md for the full cookbook.

MSRV: Rust 1.85.0. The clap dep tree pulls clap_builder 4.6 (edition 2024); the noyalib core library itself stays at 1.75.

Quick Start

# Format a file in-place; comments + indentation preserved.
noyafmt --write config.yaml

# CI gate — exits 1 if any file would change.
noyafmt --check ci/*.yaml

# Validate syntax + JSON Schema 2020-12.
noyavalidate --schema schema.yaml deploy.yaml

# Validate + auto-fix obvious type slips (port: "8080" → 8080).
noyavalidate --schema schema.yaml --fix deploy.yaml

noyafmt

YAML formatter mirroring the rustfmt / prettier ergonomics:

noyafmt config.yaml                # print formatted source to stdout (default)
noyafmt --write config.yaml        # rewrite in place
noyafmt --check ci/*.yaml          # CI gate
noyafmt --indent 4 config.yaml     # override default 2-space indent
cat foo.yaml | noyafmt --stdin     # editor pipe (Vim, Emacs, …)
git ls-files '*.yaml' | xargs noyafmt --check

The formatter runs through noyalib's lossless CST: comments, anchor positions, and document structure are preserved byte-for-byte; only whitespace and quoting are normalised.

noyavalidate

YAML syntax checker with optional JSON Schema 2020-12 enforcement and schema-driven autofix.

noyavalidate manifest.yaml                          # syntax only
noyavalidate --schema schema.yaml deploy.yaml       # + schema check
noyavalidate --schema schema.yaml --fix deploy.yaml # + autofix
cat manifest.yaml | noyavalidate                    # stdin

The autofix engine (coerce_to_schema) rewrites string-shaped scalars into the schema's expected type when the parse succeeds. Loops until convergence; unparseable inputs (port: "abc" against type: integer) are left in place so a follow-up validate_against_schema call surfaces the residue.

Diagnostics use miette for rustc-style source pointers:

× schema violation: "8080" is not of type "integer"
   ╭─[deploy.yaml:3:7]
 2 │ replicas: 3
 3 │ port: "8080"
   ·       ─┬───
   ·        ╰── here
 4 │ host: api
   ╰────
   help: pass --fix to coerce string-shaped scalars to the
         schema's declared type.

Exit codes

Examples

End-to-end runnable demos under crates/noya-cli/examples/:

chmod +x crates/noya-cli/examples/*.sh
crates/noya-cli/examples/fix-quoted-numbers.sh

Shell completions and man pages

Tarball releases ship pre-built completions for bash, fish, zsh, and PowerShell, plus roff man pages. Distro packages drop them into the standard system locations (/usr/share/bash-completion/completions/, /usr/share/man/man1/, …).

If installing via cargo install, regenerate locally:

git clone https://github.com/sebastienrousseau/noyalib
cd noyalib
cargo xtask completions    # writes complete/{noyafmt,noyavalidate}.{bash,fish,zsh,ps1}
cargo xtask manpages       # writes doc/{noyafmt,noyavalidate}.1

Verification

Every release artefact ships with a cosign keyless signature (<artefact>.sig + <artefact>.pem) and a SLSA L3 build provenance attestation. Verify before trusting a downloaded binary:

COSIGN_EXPERIMENTAL=1 cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/sebastienrousseau/noyalib/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  --certificate <artefact>.pem \
  --signature   <artefact>.sig \
  <artefact>

gh attestation verify --owner sebastienrousseau <artefact>

Full cookbook including the offline / FIPS-bound flow: pkg/VERIFY.md.

When not to use these tools

• You need to format YAML faster than human-perceivable latency. noyafmt runs end-to-end on a 1 MiB document in ~10 ms; for <100 KB documents that's already invisible. But for a streaming editor pipeline that wants per-keystroke formatting, the LSP server (noyalib-lsp) issues incremental TextEdit[]s instead.
• You need YAML 1.1-only behaviour, top to bottom. noyavalidate follows YAML 1.2; the legacy_booleans opt-in is exposed at the library level but not yet plumbed through the CLI.
• You need to embed the formatter or validator in your own Rust binary. Use the noyalib library directly — every CLI feature flows through public library APIs (cst::format_with_config, validate_against_schema, coerce_to_schema).

Documentation

• Engineering policies (MSRV, SemVer, security, performance, concurrency, platform support, feature flags): doc/POLICIES.md
• Security policy: SECURITY.md
• CLI flag reference: doc/cli-reference.md
• Recipes (CI gates, pre-commit, editor integration): doc/recipes.md
• Workspace README: https://github.com/sebastienrousseau/noyalib#readme
• Per-channel install + verify: pkg/VERIFY.md
• Library API the binaries call into: https://docs.rs/noyalib

License

Dual-licensed under Apache 2.0 or MIT, at your option.