From 94d0aa6a6b1a3f25b6e57ed51c65dbd31d1dfafe Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:14:14 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 259 ---------------------------------------------------- README.md | 257 ++++++++++++++++++++++++++------------------------- 2 files changed, 132 insertions(+), 384 deletions(-) delete mode 100644 README.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index c03138e..0000000 --- a/README.adoc +++ /dev/null @@ -1,259 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= conflow - Configuration Flow Orchestrator -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/conflow"] - - -image:https://img.shields.io/badge/License-MPL_2.0--1.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] - - -:toc: left -:toclevels: 3 -:icons: font -:source-highlighter: rouge - -Intelligently orchestrate CUE, Nickel, and configuration validation workflows. - -image:https://img.shields.io/badge/RSR-Silver-silver[RSR Compliance, link=https://gitlab.com/hyperpolymath/rhodium-standard-repositories] -image:https://img.shields.io/badge/Rust-1.75+-orange[Rust Version] - -== Why conflow? - -*Problem:* You have configuration files and you're not sure whether to use CUE, Nickel, or both. - -*Solution:* conflow analyzes your configs, recommends the right tool, and orchestrates the entire pipeline. - -[source,bash] ----- -# Instead of: -nickel export config.ncl > temp.json -cue vet schema.cue temp.json -cue export schema.cue --out yaml > deploy.yaml -rm temp.json - -# Just: -conflow run ----- - -== Features - -* *Intelligent analysis* - Recommends CUE vs Nickel based on complexity -* *Pipeline orchestration* - Chain tools with dependency management -* *Smart caching* - Only re-run what changed -* *Educational* - Learn why certain tools fit certain problems -* *Type-safe* - Catch errors before deployment -* *RSR Integration* - Full Rhodium Standard Repository compliance checking - -== Quick Start - -[source,bash] ----- -# Install -cargo install conflow - -# Initialize -conflow init my-project - -# Analyze existing configs -conflow analyze config.yaml - -# Run pipeline -conflow run ----- - -== Example Pipeline - -[source,yaml] ----- -# .conflow.yaml -version: "1" -name: "k8s-deployment" - -stages: - - name: "generate" - tool: - type: nickel - command: export - file: config.ncl - output: generated/config.json - - - name: "validate" - tool: - type: cue - command: vet - schemas: [schemas/k8s.cue] - input: - from_stage: generate - depends_on: [generate] - - - name: "export" - tool: - type: cue - command: export - out_format: yaml - input: - from_stage: generate - depends_on: [validate] - output: deploy/k8s.yaml ----- - -[source,bash] ----- -$ conflow run -✓ generate (0.08s) -✓ validate (0.05s) -✓ export (0.03s) - -Pipeline completed in 0.16s ----- - -== When to Use What? - -=== Use CUE when: - -* ✅ Validating configuration -* ✅ Expressing constraints -* ✅ Merging configurations -* ✅ Simple transformations - -=== Use Nickel when: - -* ✅ Generating configurations -* ✅ Complex logic needed -* ✅ Functions and abstraction -* ✅ DRY configuration - -=== Use Both when: - -* ✅ Nickel generates → CUE validates -* ✅ Complex generation + strict validation - -== Commands - -[cols="1,2"] -|=== -|Command |Description - -|`conflow init [--template ]` -|Initialize project - -|`conflow analyze ` -|Analyze config files - -|`conflow run [--stage ]` -|Execute pipeline - -|`conflow watch` -|Watch mode - -|`conflow validate` -|Validate pipeline - -|`conflow graph [--format ]` -|Show pipeline graph - -|`conflow cache stats` -|Cache statistics - -|`conflow cache clear` -|Clear cache - -|`conflow rsr check` -|Check RSR compliance - -|`conflow rsr requirements` -|List RSR requirements -|=== - -== Templates - -[source,bash] ----- -conflow init --template cue-validation # Simple CUE validation -conflow init --template nickel-generation # Nickel config generation -conflow init --template full-pipeline # Generate → validate → export -conflow init --template kubernetes # Kubernetes manifests -conflow init --template multi-env # Multi-environment configs ----- - -== RSR Compliance - -conflow includes full RSR (Rhodium Standard Repository) integration: - -* *Compliance checking* - Validate against RSR requirements -* *Auto-remediation* - Automatically fix common issues -* *Badge generation* - Generate compliance badges for CI -* *Diff reports* - Track compliance changes over time - -[source,bash] ----- -# Check compliance -conflow rsr check - -# Auto-fix issues -conflow rsr check --fix - -# Generate badge -conflow rsr check --badge badge.svg ----- - -== Development - -[source,bash] ----- -# Using Nix (recommended) -nix develop - -# Using just -just build # Build -just test # Run tests -just check # Run all checks -just install # Install locally ----- - -== Documentation - -* link:CLAUDE.md[CLAUDE.md] - AI assistant guidance -* link:CONTRIBUTING.md[CONTRIBUTING.md] - Contribution guidelines -* link:SECURITY.md[SECURITY.md] - Security policy -* link:GOVERNANCE.md[GOVERNANCE.md] - Project governance -* link:CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] - Code of conduct - -== RSR Standards - -This project follows link:https://gitlab.com/hyperpolymath/rhodium-standard-repositories[Rhodium Standard Repository] guidelines: - -* ✅ Memory-safe language (Rust) -* ✅ Offline-first design -* ✅ Reproducible builds (Nix) -* ✅ Comprehensive documentation -* ✅ SPDX license headers -* ✅ Security policy -* ✅ TPCF contribution framework - -== License - -This project is dual-licensed under: - -* MPL-2.0-1.0 License -* Apache License, Version 2.0 - -See link:LICENSE.txt[LICENSE.txt] for details. - -== Contributing - -Contributions are welcome! Please read our link:CONTRIBUTING.md[Contributing Guide] first. - -== Links - -* *Repository:* https://gitlab.com/hyperpolymath/conflow -* *Issues:* https://gitlab.com/hyperpolymath/conflow/-/issues -* *CUE:* https://cuelang.org -* *Nickel:* https://nickel-lang.org -* *RSR:* https://gitlab.com/hyperpolymath/rhodium-standard-repositories - - -== Architecture - -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md index 4bbe69e..e29655e 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,26 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) + -= conflow - Configuration Flow Orchestrator +[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0--1.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) +[![Palimpsest](https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg)](https://github.com/hyperpolymath/palimpsest-license) -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] +Intelligently orchestrate CUE, Nickel, and configuration validation +workflows. +[![RSR Compliance](https://img.shields.io/badge/RSR-Silver-silver)](https://gitlab.com/hyperpolymath/rhodium-standard-repositories) image:[Rust +Version](https://img.shields.io/badge/Rust-1.75+-orange) -:toc: left -:toclevels: 3 -:icons: font -:source-highlighter: rouge +# Why conflow? -Intelligently orchestrate CUE, Nickel, and configuration validation workflows. +**Problem:** You have configuration files and you’re not sure whether to +use CUE, Nickel, or both. -image:https://img.shields.io/badge/RSR-Silver-silver[RSR Compliance, link=https://gitlab.com/hyperpolymath/rhodium-standard-repositories] -image:https://img.shields.io/badge/Rust-1.75+-orange[Rust Version] +**Solution:** conflow analyzes your configs, recommends the right tool, +and orchestrates the entire pipeline. -== Why conflow? - -*Problem:* You have configuration files and you're not sure whether to use CUE, Nickel, or both. - -*Solution:* conflow analyzes your configs, recommends the right tool, and orchestrates the entire pipeline. - -[source,bash] ----- +```bash # Instead of: nickel export config.ncl > temp.json cue vet schema.cue temp.json @@ -32,21 +29,27 @@ rm temp.json # Just: conflow run ----- +``` + +# Features + +- **Intelligent analysis** - Recommends CUE vs Nickel based on + complexity + +- **Pipeline orchestration** - Chain tools with dependency management + +- **Smart caching** - Only re-run what changed -== Features +- **Educational** - Learn why certain tools fit certain problems -* *Intelligent analysis* - Recommends CUE vs Nickel based on complexity -* *Pipeline orchestration* - Chain tools with dependency management -* *Smart caching* - Only re-run what changed -* *Educational* - Learn why certain tools fit certain problems -* *Type-safe* - Catch errors before deployment -* *RSR Integration* - Full Rhodium Standard Repository compliance checking +- **Type-safe** - Catch errors before deployment -== Quick Start +- **RSR Integration** - Full Rhodium Standard Repository compliance + checking -[source,bash] ----- +# Quick Start + +```bash # Install cargo install conflow @@ -58,12 +61,11 @@ conflow analyze config.yaml # Run pipeline conflow run ----- +``` -== Example Pipeline +# Example Pipeline -[source,yaml] ----- +```yaml # .conflow.yaml version: "1" name: "k8s-deployment" @@ -94,98 +96,83 @@ stages: from_stage: generate depends_on: [validate] output: deploy/k8s.yaml ----- +``` -[source,bash] ----- +```bash $ conflow run ✓ generate (0.08s) ✓ validate (0.05s) ✓ export (0.03s) Pipeline completed in 0.16s ----- - -== When to Use What? - -=== Use CUE when: - -* ✅ Validating configuration -* ✅ Expressing constraints -* ✅ Merging configurations -* ✅ Simple transformations +``` -=== Use Nickel when: +# When to Use What? -* ✅ Generating configurations -* ✅ Complex logic needed -* ✅ Functions and abstraction -* ✅ DRY configuration +## Use CUE when: -=== Use Both when: +- ✅ Validating configuration -* ✅ Nickel generates → CUE validates -* ✅ Complex generation + strict validation +- ✅ Expressing constraints -== Commands +- ✅ Merging configurations -[cols="1,2"] -|=== -|Command |Description +- ✅ Simple transformations -|`conflow init [--template ]` -|Initialize project +## Use Nickel when: -|`conflow analyze ` -|Analyze config files +- ✅ Generating configurations -|`conflow run [--stage ]` -|Execute pipeline +- ✅ Complex logic needed -|`conflow watch` -|Watch mode +- ✅ Functions and abstraction -|`conflow validate` -|Validate pipeline +- ✅ DRY configuration -|`conflow graph [--format ]` -|Show pipeline graph +## Use Both when: -|`conflow cache stats` -|Cache statistics +- ✅ Nickel generates → CUE validates -|`conflow cache clear` -|Clear cache +- ✅ Complex generation + strict validation -|`conflow rsr check` -|Check RSR compliance +# Commands -|`conflow rsr requirements` -|List RSR requirements -|=== +| Command | Description | +|------------------------------------------|-----------------------| +| `conflow` `init` `[--template` `]` | Initialize project | +| `conflow` `analyze` `` | Analyze config files | +| `conflow` `run` `[--stage` `]` | Execute pipeline | +| `conflow` `watch` | Watch mode | +| `conflow` `validate` | Validate pipeline | +| `conflow` `graph` `[--format` `]` | Show pipeline graph | +| `conflow` `cache` `stats` | Cache statistics | +| `conflow` `cache` `clear` | Clear cache | +| `conflow` `rsr` `check` | Check RSR compliance | +| `conflow` `rsr` `requirements` | List RSR requirements | -== Templates +# Templates -[source,bash] ----- +```bash conflow init --template cue-validation # Simple CUE validation conflow init --template nickel-generation # Nickel config generation conflow init --template full-pipeline # Generate → validate → export conflow init --template kubernetes # Kubernetes manifests conflow init --template multi-env # Multi-environment configs ----- +``` -== RSR Compliance +# RSR Compliance conflow includes full RSR (Rhodium Standard Repository) integration: -* *Compliance checking* - Validate against RSR requirements -* *Auto-remediation* - Automatically fix common issues -* *Badge generation* - Generate compliance badges for CI -* *Diff reports* - Track compliance changes over time +- **Compliance checking** - Validate against RSR requirements + +- **Auto-remediation** - Automatically fix common issues + +- **Badge generation** - Generate compliance badges for CI + +- **Diff reports** - Track compliance changes over time -[source,bash] ----- +```bash # Check compliance conflow rsr check @@ -194,12 +181,11 @@ conflow rsr check --fix # Generate badge conflow rsr check --badge badge.svg ----- +``` -== Development +# Development -[source,bash] ----- +```bash # Using Nix (recommended) nix develop @@ -208,50 +194,71 @@ just build # Build just test # Run tests just check # Run all checks just install # Install locally ----- +``` -== Documentation +# Documentation -* link:CLAUDE.md[CLAUDE.md] - AI assistant guidance -* link:CONTRIBUTING.md[CONTRIBUTING.md] - Contribution guidelines -* link:SECURITY.md[SECURITY.md] - Security policy -* link:GOVERNANCE.md[GOVERNANCE.md] - Project governance -* link:CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] - Code of conduct +- CLAUDE - AI assistant guidance -== RSR Standards +- CONTRIBUTING - Contribution + guidelines -This project follows link:https://gitlab.com/hyperpolymath/rhodium-standard-repositories[Rhodium Standard Repository] guidelines: +- SECURITY - Security policy -* ✅ Memory-safe language (Rust) -* ✅ Offline-first design -* ✅ Reproducible builds (Nix) -* ✅ Comprehensive documentation -* ✅ SPDX license headers -* ✅ Security policy -* ✅ TPCF contribution framework +- GOVERNANCE - Project governance -== License +- CODE_OF_CONDUCT - Code of + conduct + +# RSR Standards + +This project follows [Rhodium Standard +Repository](https://gitlab.com/hyperpolymath/rhodium-standard-repositories) +guidelines: + +- ✅ Memory-safe language (Rust) + +- ✅ Offline-first design + +- ✅ Reproducible builds (Nix) + +- ✅ Comprehensive documentation + +- ✅ SPDX license headers + +- ✅ Security policy + +- ✅ TPCF contribution framework + +# License This project is dual-licensed under: -* Palimpsest-MPL-1.0 License -* Apache License, Version 2.0 +- MPL-2.0-1.0 License + +- Apache License, Version 2.0 + +See LICENSE for details. + +# Contributing + +Contributions are welcome! Please read our [Contributing +Guide](CONTRIBUTING.md) first. -See link:LICENSE.txt[LICENSE.txt] for details. +# Links -== Contributing +- **Repository:** -Contributions are welcome! Please read our link:CONTRIBUTING.md[Contributing Guide] first. +- **Issues:** -== Links +- **CUE:** -* *Repository:* https://gitlab.com/hyperpolymath/conflow -* *Issues:* https://gitlab.com/hyperpolymath/conflow/-/issues -* *CUE:* https://cuelang.org -* *Nickel:* https://nickel-lang.org -* *RSR:* https://gitlab.com/hyperpolymath/rhodium-standard-repositories +- **Nickel:** +- **RSR:** + -== Architecture +# Architecture -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. +See TOPOLOGY for a visual +architecture map and completion dashboard.