From 1680d80a3d44ad8965913f6cd14e2d089810c4fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesu=CC=81s=20Pe=CC=81rez?= Date: Thu, 22 Jan 2026 22:15:19 +0000 Subject: [PATCH] chore: Init repo, add docs --- .cargo/audit.toml | 37 + .cargo/config.toml | 77 + .clippy.toml | 17 + .github/workflows/nickel-typecheck.yml | 116 + .github/workflows/rust-ci.yml | 47 + .gitignore | 67 + .markdownlint-cli2.jsonc | 109 + .pre-commit-config.yaml | 128 ++ .rustfmt.toml | 53 + .shellcheckrc | 40 + .taplo.toml | 49 + .typedialog/ci/README.md | 316 +++ .typedialog/ci/config.ncl | 203 ++ .typedialog/ci/configure.sh | 116 + .typedialog/ci/envrc | 27 + .typedialog/ci/form.toml | 175 ++ .vale.ini | 41 + .vale/Vocab/TypeDialog/accept.txt | 25 + .vale/Vocab/TypeDialog/reject.txt | 2 + .vale/styles/Google/AMPM.yml | 9 + .vale/styles/Google/Acronyms.yml | 64 + .vale/styles/Google/Colons.yml | 8 + .vale/styles/Google/Contractions.yml | 30 + .vale/styles/Google/DateFormat.yml | 9 + .vale/styles/Google/Ellipses.yml | 9 + .vale/styles/Google/EmDash.yml | 12 + .vale/styles/Google/Exclamation.yml | 12 + .vale/styles/Google/FirstPerson.yml | 13 + .vale/styles/Google/Gender.yml | 9 + .vale/styles/Google/GenderBias.yml | 43 + .vale/styles/Google/HeadingPunctuation.yml | 13 + .vale/styles/Google/Headings.yml | 29 + .vale/styles/Google/Latin.yml | 11 + .vale/styles/Google/LyHyphens.yml | 14 + .vale/styles/Google/OptionalPlurals.yml | 12 + .vale/styles/Google/Ordinal.yml | 7 + .vale/styles/Google/OxfordComma.yml | 7 + .vale/styles/Google/Parens.yml | 7 + .vale/styles/Google/Passive.yml | 184 ++ .vale/styles/Google/Periods.yml | 7 + .vale/styles/Google/Quotes.yml | 7 + .vale/styles/Google/Ranges.yml | 7 + .vale/styles/Google/Semicolons.yml | 8 + .vale/styles/Google/Slang.yml | 11 + .vale/styles/Google/Spacing.yml | 10 + .vale/styles/Google/Spelling.yml | 10 + .vale/styles/Google/Units.yml | 8 + .vale/styles/Google/We.yml | 11 + .vale/styles/Google/Will.yml | 7 + .vale/styles/Google/WordList.yml | 80 + .vale/styles/Google/meta.json | 4 + .vale/styles/Google/vocab.txt | 0 .vale/styles/write-good/Cliches.yml | 702 ++++++ .vale/styles/write-good/E-Prime.yml | 32 + .vale/styles/write-good/Illusions.yml | 11 + .vale/styles/write-good/Passive.yml | 183 ++ .vale/styles/write-good/README.md | 27 + .vale/styles/write-good/So.yml | 5 + .vale/styles/write-good/ThereIs.yml | 6 + .vale/styles/write-good/TooWordy.yml | 221 ++ .vale/styles/write-good/Weasel.yml | 29 + .vale/styles/write-good/meta.json | 4 + .woodpecker/Dockerfile | 45 + .woodpecker/Dockerfile.cross | 42 + .woodpecker/README.md | 78 + .woodpecker/ci-advanced.yml | 168 ++ .woodpecker/ci.yml | 84 + .yamllint-ci.yml | 18 + CODE_OF_CONDUCT.md | 103 + CONTRIBUTING.md | 129 ++ README.md | 235 ++ SECURITY.md | 98 + assets/branding/README.md | 239 ++ assets/branding/index.html | 1438 ++++++++++++ assets/branding/stratumiops-ascii.txt | 8 + .../branding/stratumiops-assets-showcase.html | 1984 +++++++++++++++++ assets/en/stratumiops-brand-strategy.md | 476 ++++ assets/en/stratumiops-branding-guide.md | 454 ++++ assets/en/stratumiops-logo-prompts.md | 220 ++ assets/es/stratumiops-brand-strategy.md | 476 ++++ assets/es/stratumiops-branding-guide.md | 454 ++++ assets/es/stratumiops-logo-prompts.md | 220 ++ assets/logos/stratumiops-dark-h.svg | 77 + assets/logos/stratumiops-dark-v.svg | 78 + assets/logos/stratumiops-favicon-16.svg | 21 + assets/logos/stratumiops-favicon-32.svg | 21 + assets/logos/stratumiops-h-static.svg | 76 + assets/logos/stratumiops-h.svg | 191 ++ assets/logos/stratumiops-icon-dark-static.svg | 64 + assets/logos/stratumiops-icon-dark.svg | 176 ++ assets/logos/stratumiops-icon-static.svg | 61 + assets/logos/stratumiops-icon.svg | 177 ++ assets/logos/stratumiops-mono-black-h.svg | 42 + assets/logos/stratumiops-mono-black-v.svg | 46 + assets/logos/stratumiops-mono-white-h.svg | 42 + assets/logos/stratumiops-mono-white-v.svg | 46 + .../logos/stratumiops-social-square-dark.svg | 84 + .../logos/stratumiops-social-square-light.svg | 84 + assets/logos/stratumiops-v-static.svg | 77 + assets/logos/stratumiops-v.svg | 180 ++ assets/stratumiops-h.svg | 185 ++ assets/web/README.md | 265 +++ assets/web/index.html | 1 + assets/web/minify.sh | 87 + assets/web/src/index.html | 978 ++++++++ assets/web/src/stratumiops.svg | 191 ++ assets/web/stratumiops.svg | 191 ++ deny.toml | 74 + docs/README.md | 49 + docs/en/README.md | 40 + docs/en/ia/README.md | 44 + .../ia/ia-stratumiops-projects-positioning.md | 554 +++++ ...ia-stratumiops-projects-technical-specs.md | 1319 +++++++++++ docs/en/ia/ia-stratumiops-projects.md | 313 +++ docs/en/ops/README.md | 37 + .../ops-stratumiops-projects-positioning.md | 623 ++++++ ...ps-stratumiops-projects-technical-specs.md | 1704 ++++++++++++++ docs/en/ops/ops-stratumiops-projects.md | 735 ++++++ docs/en/stratiumiops-technical-specs.md | 1784 +++++++++++++++ docs/en/stratiumiops_market.md | 410 ++++ docs/en/stratiumiops_position.md | 910 ++++++++ docs/es/README.md | 40 + docs/es/ia/README.md | 44 + .../ia/ia-stratumiops-projects-positioning.md | 450 ++++ ...ia-stratumiops-projects-technical-specs.md | 1319 +++++++++++ docs/es/ia/ia-stratumiops-projects.md | 312 +++ docs/es/ops/README.md | 37 + .../ops-stratumiops-projects-positioning.md | 623 ++++++ ...ps-stratumiops-projects-technical-specs.md | 1812 +++++++++++++++ docs/es/ops/ops-stratumiops-projects.md | 735 ++++++ docs/es/stratiumiops-technical-specs.md | 1784 +++++++++++++++ docs/es/stratiumiops_market.md | 410 ++++ docs/es/stratiumiops_position.md | 910 ++++++++ 133 files changed, 31019 insertions(+) create mode 100644 .cargo/audit.toml create mode 100644 .cargo/config.toml create mode 100644 .clippy.toml create mode 100644 .github/workflows/nickel-typecheck.yml create mode 100644 .github/workflows/rust-ci.yml create mode 100644 .gitignore create mode 100644 .markdownlint-cli2.jsonc create mode 100644 .pre-commit-config.yaml create mode 100644 .rustfmt.toml create mode 100644 .shellcheckrc create mode 100644 .taplo.toml create mode 100644 .typedialog/ci/README.md create mode 100644 .typedialog/ci/config.ncl create mode 100755 .typedialog/ci/configure.sh create mode 100644 .typedialog/ci/envrc create mode 100644 .typedialog/ci/form.toml create mode 100644 .vale.ini create mode 100644 .vale/Vocab/TypeDialog/accept.txt create mode 100644 .vale/Vocab/TypeDialog/reject.txt create mode 100644 .vale/styles/Google/AMPM.yml create mode 100644 .vale/styles/Google/Acronyms.yml create mode 100644 .vale/styles/Google/Colons.yml create mode 100644 .vale/styles/Google/Contractions.yml create mode 100644 .vale/styles/Google/DateFormat.yml create mode 100644 .vale/styles/Google/Ellipses.yml create mode 100644 .vale/styles/Google/EmDash.yml create mode 100644 .vale/styles/Google/Exclamation.yml create mode 100644 .vale/styles/Google/FirstPerson.yml create mode 100644 .vale/styles/Google/Gender.yml create mode 100644 .vale/styles/Google/GenderBias.yml create mode 100644 .vale/styles/Google/HeadingPunctuation.yml create mode 100644 .vale/styles/Google/Headings.yml create mode 100644 .vale/styles/Google/Latin.yml create mode 100644 .vale/styles/Google/LyHyphens.yml create mode 100644 .vale/styles/Google/OptionalPlurals.yml create mode 100644 .vale/styles/Google/Ordinal.yml create mode 100644 .vale/styles/Google/OxfordComma.yml create mode 100644 .vale/styles/Google/Parens.yml create mode 100644 .vale/styles/Google/Passive.yml create mode 100644 .vale/styles/Google/Periods.yml create mode 100644 .vale/styles/Google/Quotes.yml create mode 100644 .vale/styles/Google/Ranges.yml create mode 100644 .vale/styles/Google/Semicolons.yml create mode 100644 .vale/styles/Google/Slang.yml create mode 100644 .vale/styles/Google/Spacing.yml create mode 100644 .vale/styles/Google/Spelling.yml create mode 100644 .vale/styles/Google/Units.yml create mode 100644 .vale/styles/Google/We.yml create mode 100644 .vale/styles/Google/Will.yml create mode 100644 .vale/styles/Google/WordList.yml create mode 100644 .vale/styles/Google/meta.json create mode 100644 .vale/styles/Google/vocab.txt create mode 100644 .vale/styles/write-good/Cliches.yml create mode 100644 .vale/styles/write-good/E-Prime.yml create mode 100644 .vale/styles/write-good/Illusions.yml create mode 100644 .vale/styles/write-good/Passive.yml create mode 100644 .vale/styles/write-good/README.md create mode 100644 .vale/styles/write-good/So.yml create mode 100644 .vale/styles/write-good/ThereIs.yml create mode 100644 .vale/styles/write-good/TooWordy.yml create mode 100644 .vale/styles/write-good/Weasel.yml create mode 100644 .vale/styles/write-good/meta.json create mode 100644 .woodpecker/Dockerfile create mode 100644 .woodpecker/Dockerfile.cross create mode 100644 .woodpecker/README.md create mode 100644 .woodpecker/ci-advanced.yml create mode 100644 .woodpecker/ci.yml create mode 100644 .yamllint-ci.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 SECURITY.md create mode 100644 assets/branding/README.md create mode 100644 assets/branding/index.html create mode 100644 assets/branding/stratumiops-ascii.txt create mode 100644 assets/branding/stratumiops-assets-showcase.html create mode 100644 assets/en/stratumiops-brand-strategy.md create mode 100644 assets/en/stratumiops-branding-guide.md create mode 100644 assets/en/stratumiops-logo-prompts.md create mode 100644 assets/es/stratumiops-brand-strategy.md create mode 100644 assets/es/stratumiops-branding-guide.md create mode 100644 assets/es/stratumiops-logo-prompts.md create mode 100644 assets/logos/stratumiops-dark-h.svg create mode 100644 assets/logos/stratumiops-dark-v.svg create mode 100644 assets/logos/stratumiops-favicon-16.svg create mode 100644 assets/logos/stratumiops-favicon-32.svg create mode 100644 assets/logos/stratumiops-h-static.svg create mode 100644 assets/logos/stratumiops-h.svg create mode 100644 assets/logos/stratumiops-icon-dark-static.svg create mode 100644 assets/logos/stratumiops-icon-dark.svg create mode 100644 assets/logos/stratumiops-icon-static.svg create mode 100644 assets/logos/stratumiops-icon.svg create mode 100644 assets/logos/stratumiops-mono-black-h.svg create mode 100644 assets/logos/stratumiops-mono-black-v.svg create mode 100644 assets/logos/stratumiops-mono-white-h.svg create mode 100644 assets/logos/stratumiops-mono-white-v.svg create mode 100644 assets/logos/stratumiops-social-square-dark.svg create mode 100644 assets/logos/stratumiops-social-square-light.svg create mode 100644 assets/logos/stratumiops-v-static.svg create mode 100644 assets/logos/stratumiops-v.svg create mode 100644 assets/stratumiops-h.svg create mode 100644 assets/web/README.md create mode 100644 assets/web/index.html create mode 100755 assets/web/minify.sh create mode 100644 assets/web/src/index.html create mode 100644 assets/web/src/stratumiops.svg create mode 100644 assets/web/stratumiops.svg create mode 100644 deny.toml create mode 100644 docs/README.md create mode 100644 docs/en/README.md create mode 100644 docs/en/ia/README.md create mode 100644 docs/en/ia/ia-stratumiops-projects-positioning.md create mode 100644 docs/en/ia/ia-stratumiops-projects-technical-specs.md create mode 100644 docs/en/ia/ia-stratumiops-projects.md create mode 100644 docs/en/ops/README.md create mode 100644 docs/en/ops/ops-stratumiops-projects-positioning.md create mode 100644 docs/en/ops/ops-stratumiops-projects-technical-specs.md create mode 100644 docs/en/ops/ops-stratumiops-projects.md create mode 100644 docs/en/stratiumiops-technical-specs.md create mode 100644 docs/en/stratiumiops_market.md create mode 100644 docs/en/stratiumiops_position.md create mode 100644 docs/es/README.md create mode 100644 docs/es/ia/README.md create mode 100644 docs/es/ia/ia-stratumiops-projects-positioning.md create mode 100644 docs/es/ia/ia-stratumiops-projects-technical-specs.md create mode 100644 docs/es/ia/ia-stratumiops-projects.md create mode 100644 docs/es/ops/README.md create mode 100644 docs/es/ops/ops-stratumiops-projects-positioning.md create mode 100644 docs/es/ops/ops-stratumiops-projects-technical-specs.md create mode 100644 docs/es/ops/ops-stratumiops-projects.md create mode 100644 docs/es/stratiumiops-technical-specs.md create mode 100644 docs/es/stratiumiops_market.md create mode 100644 docs/es/stratiumiops_position.md diff --git a/.cargo/audit.toml b/.cargo/audit.toml new file mode 100644 index 0000000..b965267 --- /dev/null +++ b/.cargo/audit.toml @@ -0,0 +1,37 @@ +# Generated by dev-system/ci +# cargo-audit configuration for security vulnerability scanning + +# Database configuration +[advisories] +# The database path +db-path = "~/.cargo/advisory-db" + +# Advisory database URLs +db-urls = ["https://github.com/rustsec/advisory-db"] + +# How to handle different kinds of advisories +# "allow" - Pass the check despite the warning +# "warn" - Pass the check but warn about the issue +# "deny" - Fail the check +deny = ["unmaintained", "unsound", "yanked"] + +# Specific vulnerability IDs to ignore (in case of false positives) +# You can use: https://rustsec.org/ +ignore = [ + # Example: { id = "RUSTSEC-2023-XXXX", reason = "Not applicable to our use case" } +] + +# How to handle vulnerabilities based on severity +[output] +# Deny on high severity vulnerabilities +deny = ["high", "critical"] +# Warn on medium severity vulnerabilities +warn = ["medium", "low"] +# Advisory format: "terminal", "json" +format = "terminal" + +# Target configuration +[target] +# Check only specific targets +# Uncomment to restrict to specific target triples +# triple = "x86_64-unknown-linux-gnu" diff --git a/.cargo/config.toml b/.cargo/config.toml new file mode 100644 index 0000000..09b8772 --- /dev/null +++ b/.cargo/config.toml @@ -0,0 +1,77 @@ +# Generated by dev-system/ci +# Cargo configuration for build and compilation settings + +[build] +# Number of parallel jobs for compilation +jobs = 4 + +# Code generation backend +# codegen-backend = "llvm" + +[profile.dev] +# Development profile - fast compilation, debug info +opt-level = 0 +debug = true +debug-assertions = true +overflow-checks = true +lto = false +panic = "unwind" +incremental = true + +[profile.release] +# Release profile - slow compilation, optimized binary +opt-level = 3 +debug = false +debug-assertions = false +overflow-checks = false +lto = "thin" +codegen-units = 1 +panic = "abort" +incremental = false +strip = false + +[profile.test] +# Test profile - inherits from dev but can be optimized +opt-level = 1 +debug = true +debug-assertions = true +overflow-checks = true +lto = false +panic = "unwind" +incremental = true + +[profile.bench] +# Benchmark profile - same as release +opt-level = 3 +debug = false +debug-assertions = false +overflow-checks = false +lto = "thin" +codegen-units = 1 +panic = "abort" +incremental = false + +# Resolver version +resolver = "2" + +[term] +# Terminal colors +color = "auto" +verbose = false +progress.when = "auto" +progress.width = 80 + +[net] +# Network settings +git-fetch-with-cli = true +offline = false + +# Strict version requirements for dependencies +# force-non-semver-pre = true + +[alias] +# Custom cargo commands +build-all = "build --all-targets" +check-all = "check --all-targets --all-features" +test-all = "test --all-features --workspace" +doc-all = "doc --all-features --no-deps --open" diff --git a/.clippy.toml b/.clippy.toml new file mode 100644 index 0000000..5da36da --- /dev/null +++ b/.clippy.toml @@ -0,0 +1,17 @@ +# Generated by dev-system/ci +# Clippy configuration for Rust linting + +# Lint level thresholds +cognitive-complexity-threshold = 25 +type-complexity-threshold = 500 +excessive-nesting-threshold = 5 + +# Allowed patterns (prevent lints on specific code) +# allow-expect-in-tests = true +# allow-unwrap-in-tests = true + +# Single-character variable name threshold +single-char-binding-names-threshold = 4 + +# Note: Lint configurations belong in Cargo.toml under [lints.clippy] or [workspace.lints.clippy] +# This file only contains clippy configuration parameters, not lint levels diff --git a/.github/workflows/nickel-typecheck.yml b/.github/workflows/nickel-typecheck.yml new file mode 100644 index 0000000..325a550 --- /dev/null +++ b/.github/workflows/nickel-typecheck.yml @@ -0,0 +1,116 @@ +# GitHub Actions Nickel Type Checking Workflow +# Generated by dev-system/ci +# Validates all Nickel schemas with nickel typecheck + +name: Nickel Type Check + +on: + push: + branches: [main, develop] + paths: ['**.ncl'] + pull_request: + branches: [main] + paths: ['**.ncl'] + +jobs: + typecheck: + name: Nickel Type Checking + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Nickel + run: | + #!/usr/bin/env bash + set -e + + echo "πŸ“¦ Installing Nickel..." + + if command -v nickel &> /dev/null; then + echo "βœ“ Nickel already installed" + nickel --version + else + echo "Installing via homebrew..." + brew install nickel || { + echo "Homebrew installation failed, trying from source..." + curl --proto '=https' --tlsv1.2 -sSf https://install.nickel-lang.org | bash || exit 1 + } + fi + + nickel --version + + - name: Setup environment + run: | + #!/usr/bin/env bash + # Set NICKEL_IMPORT_PATH for schema imports + export NICKEL_IMPORT_PATH="/Users/Akasha/Tools/dev-system/ci/schemas:/Users/Akasha/Tools/dev-system/ci/validators:/Users/Akasha/Tools/dev-system/ci/defaults" + echo "NICKEL_IMPORT_PATH=$NICKEL_IMPORT_PATH" >> $GITHUB_ENV + + - name: Type check schemas + run: | + #!/usr/bin/env bash + set -e + + echo "πŸ” Type checking Nickel schemas..." + + # Find all .ncl files + SCHEMAS=$(find . -name "*.ncl" -type f \ + ! -path "./target/*" \ + ! -path "./.git/*" \ + ! -path "./node_modules/*" \ + | sort) + + if [ -z "$SCHEMAS" ]; then + echo "⚠️ No Nickel schemas found" + exit 0 + fi + + FAILED=0 + PASSED=0 + + # Set import path + export NICKEL_IMPORT_PATH="/Users/Akasha/Tools/dev-system/ci/schemas:/Users/Akasha/Tools/dev-system/ci/validators:/Users/Akasha/Tools/dev-system/ci/defaults:." + + for schema in $SCHEMAS; do + echo "Checking: $schema" + if nickel typecheck "$schema" > /dev/null 2>&1; then + echo " βœ“ Valid" + ((PASSED++)) + else + echo " ❌ Type error" + nickel typecheck "$schema" || true + ((FAILED++)) + fi + done + + echo "" + echo "Summary: $PASSED passed, $FAILED failed" + + if [ $FAILED -gt 0 ]; then + exit 1 + fi + + - name: Export and validate + run: | + #!/usr/bin/env bash + set -e + + echo "πŸ“Š Exporting Nickel configurations..." + + export NICKEL_IMPORT_PATH="/Users/Akasha/Tools/dev-system/ci/schemas:/Users/Akasha/Tools/dev-system/ci/validators:/Users/Akasha/Tools/dev-system/ci/defaults:." + + # Export main configs if they exist + if [ -f ".typedialog/ci/schemas/ci-local.ncl" ]; then + echo "Exporting CI config..." + nickel export .typedialog/ci/schemas/ci-local.ncl > /tmp/ci-export.json + if [ $? -eq 0 ]; then + echo " βœ“ Successfully exported" + else + echo " ❌ Export failed" + exit 1 + fi + fi + + echo "βœ“ All exports successful" diff --git a/.github/workflows/rust-ci.yml b/.github/workflows/rust-ci.yml new file mode 100644 index 0000000..73c2af1 --- /dev/null +++ b/.github/workflows/rust-ci.yml @@ -0,0 +1,47 @@ +jobs: + audit: + name: Security Audit + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Install Rust + uses: dtolnay/rust-toolchain@stable + - name: Audit + run: cargo audit --deny warnings + - name: Deny Check + run: cargo deny check licenses advisories + check: + name: Check + Test + Lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Install Rust + uses: dtolnay/rust-toolchain@master + with: + toolchain: ${{ matrix.rust-version }} + - name: Cache + uses: Swatinem/rust-cache@v2 + - name: Check + run: cargo check --all-targets + - name: Format Check + run: cargo fmt --all -- --check + - name: Clippy + run: cargo clippy --all-targets -- -D warnings + - name: Tests + run: cargo test --workspace + strategy: + matrix: + rust-version: + - stable + - nightly +name: Rust CI +on: + pull_request: + branches: + - main + push: + branches: + - main + - develop diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f93f883 --- /dev/null +++ b/.gitignore @@ -0,0 +1,67 @@ +CLAUDE.md +.claude +utils/save*sh +COMMIT_MESSAGE.md +.wrks +nushell +nushell-* +*.tar.gz +#*-nushell-plugins.tar.gz +github-com +.coder +target +distribution +.qodo +# enviroment to load on bin/build +.env +# OSX trash +.DS_Store + +# Vscode files +.vscode + +# Emacs save files +*~ +\#*\# +.\#* + +# Vim-related files +[._]*.s[a-w][a-z] +[._]s[a-w][a-z] +*.un~ +Session.vim +.netrwhist + +# cscope-related files +cscope.* + +# User cluster configs +.kubeconfig + +.tags* + +# direnv .envrc files +.envrc + +# make-related metadata +/.make/ + +# Just in time generated data in the source, should never be committed +/test/e2e/generated/bindata.go + +# This file used by some vendor repos (e.g. github.com/go-openapi/...) to store secret variables and should not be ignored +!\.drone\.sec + +# Godeps workspace +/Godeps/_workspace + +/bazel-* +*.pyc + +# generated by verify-vendor.sh +vendordiff.patch +.claude/settings.local.json + +# Generated SBOM files +SBOM.*.json +*.sbom.json diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..a133fa0 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,109 @@ +// Markdownlint-cli2 Configuration +// Documentation quality enforcement for technical projects +// See: https://github.com/DavidAnson/markdownlint-cli2 +// Generated by dev-system/ci + +{ + "config": { + "default": true, + + // Headings - enforce proper hierarchy + "MD001": false, // heading-increment (relaxed - allow flexibility) + "MD026": { "punctuation": ".,;:!?" }, // heading-punctuation + + // Lists - enforce consistency + "MD004": { "style": "consistent" }, // ul-style (consistent list markers) + "MD005": false, // inconsistent-indentation (relaxed) + "MD007": { "indent": 2 }, // ul-indent + "MD029": false, // ol-prefix (allow flexible list numbering) + "MD030": { "ul_single": 1, "ol_single": 1, "ul_multi": 1, "ol_multi": 1 }, + + // Code blocks - fenced only + "MD046": { "style": "fenced" }, // code-block-style + + // CRITICAL: MD040 only checks opening fences, NOT closing fences + // It does NOT catch malformed closing fences with language specifiers (e.g., ```plaintext) + // CommonMark spec requires closing fences to be ``` only (no language) + // Use separate validation script to check closing fences + "MD040": true, // fenced-code-language (code blocks need language on OPENING fence) + + // Formatting - strict whitespace + "MD009": true, // no-hard-tabs + "MD010": true, // hard-tabs + "MD011": true, // reversed-link-syntax + "MD018": true, // no-missing-space-atx + "MD019": true, // no-multiple-space-atx + "MD020": true, // no-missing-space-closed-atx + "MD021": true, // no-multiple-space-closed-atx + "MD023": true, // heading-starts-line + "MD027": true, // no-multiple-spaces-blockquote + "MD037": true, // no-space-in-emphasis + "MD039": true, // no-space-in-links + + // Trailing content + "MD012": false, // no-multiple-blanks (relaxed - allow formatting space) + "MD024": false, // no-duplicate-heading (too strict for docs) + "MD028": false, // no-blanks-blockquote (relaxed) + "MD047": true, // single-trailing-newline + + // Links and references + "MD034": true, // no-bare-urls (links must be formatted) + "MD042": true, // no-empty-links + + // HTML - allow for documentation formatting and images + "MD033": { "allowed_elements": ["br", "hr", "details", "summary", "p", "img"] }, + + // Line length - relaxed for technical documentation + "MD013": { + "line_length": 150, + "heading_line_length": 150, + "code_block_line_length": 150, + "code_blocks": true, + "tables": true, + "headers": true, + "headers_line_length": 150, + "strict": false, + "stern": false + }, + + // Images + "MD045": true, // image-alt-text + + // Tables - enforce proper formatting + "MD060": true, // table-column-style (proper spacing: | ---- | not |------|) + + // Disable rules that conflict with relaxed style + "MD003": false, // consistent-indentation + "MD041": false, // first-line-heading + "MD025": false, // single-h1 / multiple-top-level-headings + "MD022": false, // blanks-around-headings (flexible spacing) + "MD032": false, // blanks-around-lists (flexible spacing) + "MD035": false, // hr-style (consistent) + "MD036": false, // no-emphasis-as-heading + "MD044": false // proper-names + }, + + // Documentation patterns + "globs": [ + "**/*.md", + "!node_modules/**", + "!target/**", + "!.git/**", + "!build/**", + "!dist/**" + ], + + // Ignore build artifacts, external content, and operational directories + "ignores": [ + "node_modules/**", + "target/**", + ".git/**", + "build/**", + "dist/**", + ".coder/**", + ".claude/**", + ".wrks/**", + ".vale/**", + "vendor/**" + ] +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..72f9a42 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,128 @@ +# Pre-commit Framework Configuration +# Generated by dev-system/ci +# Configures git pre-commit hooks for Rust projects + +repos: + # ============================================================================ + # Rust Hooks + # ============================================================================ + - repo: local + hooks: + - id: rust-fmt + name: Rust formatting (cargo +nightly fmt) + entry: bash -c 'cargo +nightly fmt --all -- --check' + language: system + types: [rust] + pass_filenames: false + stages: [pre-commit] + + - id: rust-clippy + name: Rust linting (cargo clippy) + entry: bash -c 'cargo clippy --all-targets -- -D warnings' + language: system + types: [rust] + pass_filenames: false + stages: [pre-commit] + + - id: rust-test + name: Rust tests + entry: bash -c 'cargo test --workspace' + language: system + types: [rust] + pass_filenames: false + stages: [pre-push] + + - id: cargo-deny + name: Cargo deny (licenses & advisories) + entry: bash -c 'cargo deny check licenses advisories' + language: system + pass_filenames: false + stages: [pre-push] + + # ============================================================================ + # Nushell Hooks (optional - enable if using Nushell) + # ============================================================================ + # - repo: local + # hooks: + # - id: nushell-check + # name: Nushell validation (nu --ide-check) + # entry: >- + # bash -c 'for f in $(git diff --cached --name-only --diff-filter=ACM | grep "\.nu$"); do + # echo "Checking: $f"; nu --ide-check 100 "$f" || exit 1; done' + # language: system + # types: [file] + # files: \.nu$ + # pass_filenames: false + # stages: [pre-commit] + + # ============================================================================ + # Nickel Hooks (optional - enable if using Nickel) + # ============================================================================ + # - repo: local + # hooks: + # - id: nickel-typecheck + # name: Nickel type checking + # entry: >- + # bash -c 'export NICKEL_IMPORT_PATH="../:."; for f in $(git diff --cached --name-only --diff-filter=ACM | grep "\.ncl$"); do + # echo "Checking: $f"; nickel typecheck "$f" || exit 1; done' + # language: system + # types: [file] + # files: \.ncl$ + # pass_filenames: false + # stages: [pre-commit] + + # ============================================================================ + # Bash Hooks (optional - enable if using Bash) + # ============================================================================ + # - repo: local + # hooks: + # - id: shellcheck + # name: Shellcheck (bash linting) + # entry: shellcheck + # language: system + # types: [shell] + # stages: [pre-commit] + # + # - id: shfmt + # name: Shell script formatting + # entry: bash -c 'shfmt -i 2 -d' + # language: system + # types: [shell] + # stages: [pre-commit] + + # ============================================================================ + # Markdown Hooks (RECOMMENDED - enable for documentation quality) + # ============================================================================ + - repo: local + hooks: + - id: markdownlint + name: Markdown linting (markdownlint-cli2) + entry: markdownlint-cli2 + language: system + types: [markdown] + stages: [pre-commit] + + # ============================================================================ + # General Pre-commit Hooks + # ============================================================================ + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-added-large-files + args: ['--maxkb=1000'] + + - id: check-case-conflict + + - id: check-merge-conflict + + - id: check-toml + + - id: check-yaml + exclude: ^\.woodpecker/ + + - id: end-of-file-fixer + + - id: trailing-whitespace + exclude: \.md$ + + - id: mixed-line-ending diff --git a/.rustfmt.toml b/.rustfmt.toml new file mode 100644 index 0000000..8bd3887 --- /dev/null +++ b/.rustfmt.toml @@ -0,0 +1,53 @@ +# Generated by dev-system/ci +# Rustfmt configuration for consistent Rust code formatting +# Configured for cargo +nightly fmt with advanced features enabled + +# Basic formatting options +edition = "2021" +max_width = 100 +hard_tabs = false +tab_spaces = 4 +newline_style = "Unix" + +# Code structure +use_small_heuristics = "Default" + +# Imports +reorder_imports = true +reorder_modules = true +remove_nested_parens = true +group_imports = "StdExternalCrate" + +# Match expressions +match_block_trailing_comma = false + +# Chains +chain_width = 60 + +# Comment formatting (nightly) +comment_width = 80 +wrap_comments = true +normalize_comments = true +normalize_doc_attributes = true + +# Spaces and indentation (nightly) +fn_single_line = false +fn_params_layout = "Tall" +where_single_line = false + +# Formatting (nightly) +format_strings = true +format_code_in_doc_comments = false + +# Spaces (nightly) +space_before_colon = false +space_after_colon = true +spaces_around_ranges = false + +# Line breaks (nightly) +match_arm_blocks = true +blank_lines_lower_bound = 0 +blank_lines_upper_bound = 1 + +# Enable nightly features +unstable_features = true diff --git a/.shellcheckrc b/.shellcheckrc new file mode 100644 index 0000000..5eaa967 --- /dev/null +++ b/.shellcheckrc @@ -0,0 +1,40 @@ +# ShellCheck Configuration Template +# Bash/shell script linting configuration +# Generated by dev-system/ci +# Location: .shellcheckrc + + +# Generated by dev-system/ci +# ShellCheck configuration for Bash script validation + +# Enable all optional checks +enable=all + +# Disable specific checks that are too strict +# SC1091 - Not following sourced files (noisy in monorepos) +# disable=SC1091 + +# Source path for sourced files +source-path=SCRIPTDIR + +# Severity levels: error, warning, info, style +severity=warning + +# Format: gcc, json, json1, quiet +format=gcc + +# Exit status thresholds +# 0: All checks passed +# 1: Warning found +# 2: Error found + +# Shell dialect (bash, sh, ksh, etc) +# shell=bash + +# Check style guide compliance +# These are considered good practices but optional + +# Common problematic patterns +# SC2086 - Double quote to prevent globbing +# SC2181 - Check exit code explicitly +# SC2207 - Array from command substitution diff --git a/.taplo.toml b/.taplo.toml new file mode 100644 index 0000000..5d20bf8 --- /dev/null +++ b/.taplo.toml @@ -0,0 +1,49 @@ +# Taplo configuration for TOML formatting and linting +# https://taplo.tamasfe.dev/configuration/ + +[formatting] +# Indent tables with 2 spaces +indent_string = " " +indent_tables = true + +# Reorder keys alphabetically within tables +reorder_keys = true + +# Reorder arrays to be more readable +reorder_arrays = false + +# Align entries vertically in inline tables +align_entries = false + +# Allow compact inline tables +allowed_blank_lines = 1 + +# Trailing newline +trailing_newline = true + +# Column width for wrapping +column_width = 100 + +# Compact arrays +compact_arrays = true + +# Compact inline tables +compact_inline_tables = false + +# === INCLUDE/EXCLUDE PATTERNS === + +include = ["Cargo.toml", "*/Cargo.toml", "config/**/*.toml", "**/*.toml"] + +exclude = ["target/**", "node_modules/**", ".git/**"] + +# === SCHEMA VALIDATION === + +# Cargo.toml schema validation +[[rule]] +include = ["**/Cargo.toml"] +# Taplo includes built-in Cargo.toml schema + +# TypeDialog form definition TOML files +[[rule]] +include = ["**/.typedialog/**/*.toml", "config/**/forms/*.toml", "tests/fixtures/**/*.toml"] +keys = ["name", "description", "fields", "items", "elements"] diff --git a/.typedialog/ci/README.md b/.typedialog/ci/README.md new file mode 100644 index 0000000..3ec29bf --- /dev/null +++ b/.typedialog/ci/README.md @@ -0,0 +1,316 @@ +# CI System - Configuration Guide + +**Installed**: 2026-01-22 +**Detected Languages**: markdown + +--- + +## Quick Start + +### Option 1: Using configure.sh (Recommended) + +A convenience script is installed in `.typedialog/ci/`: + +```bash +# Use web backend (default) - Opens in browser +.typedialog/ci/configure.sh + +# Use TUI backend - Terminal interface +.typedialog/ci/configure.sh tui + +# Use CLI backend - Command-line prompts +.typedialog/ci/configure.sh cli +``` + +**This script automatically:** +- Sources `.typedialog/ci/envrc` for environment setup +- Loads defaults from `config.ncl` (Nickel format) +- Uses cascading search for fragments (local β†’ Tools) +- Creates backup before overwriting existing config +- Saves output in Nickel format using nickel-roundtrip with documented template +- Generates `config.ncl` compatible with `nickel doc` command + +### Option 2: Direct TypeDialog Commands + +Use TypeDialog nickel-roundtrip directly with manual paths: + +#### Web Backend (Recommended - Easy Viewing) + +```bash +cd .typedialog/ci # Change to CI directory +source envrc # Load environment +typedialog-web nickel-roundtrip config.ncl form.toml \ + --output config.ncl \ + --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 +``` + +#### TUI Backend + +```bash +cd .typedialog/ci +source envrc +typedialog-tui nickel-roundtrip config.ncl form.toml \ + --output config.ncl \ + --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 +``` + +#### CLI Backend + +```bash +cd .typedialog/ci +source envrc +typedialog nickel-roundtrip config.ncl form.toml \ + --output config.ncl \ + --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 +``` + +**Note:** The `--ncl-template` flag uses a Tera template that adds: +- Descriptive comments for each section +- Documentation compatible with `nickel doc config.ncl` +- Consistent formatting and structure + +**All backends will:** +- Show only options relevant to your detected languages +- Guide you through all configuration choices +- Validate your inputs +- Generate config.ncl in Nickel format + +### Option 3: Manual Configuration + +Edit `config.ncl` directly: + +```bash +vim .typedialog/ci/config.ncl +``` + +--- + +## Configuration Format: Nickel + +**This project uses Nickel format by default** for all configuration files. + +### Why Nickel? + +- βœ… **Typed configuration** - Static type checking with `nickel typecheck` +- βœ… **Documentation** - Generate docs with `nickel doc config.ncl` +- βœ… **Validation** - Built-in schema validation +- βœ… **Comments** - Rich inline documentation support +- βœ… **Modular** - Import/export system for reusable configs + +### Nickel Template + +The output structure is controlled by a **Tera template** at: +- **Tools default**: `$TOOLS_PATH/dev-system/ci/templates/config.ncl.j2` +- **Local override**: `.typedialog/ci/config.ncl.j2` (optional) + +**To customize the template:** + +```bash +# Copy the default template +cp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \ + .typedialog/ci/config.ncl.j2 + +# Edit to add custom comments, documentation, or structure +vim .typedialog/ci/config.ncl.j2 + +# Your template will now be used automatically +``` + +**Template features:** +- Customizable comments per section +- Control field ordering +- Add project-specific documentation +- Configure output for `nickel doc` command + +### TypeDialog Environment Variables + +You can customize TypeDialog behavior with environment variables: + +```bash +# Web server configuration +export TYPEDIALOG_PORT=9000 # Port for web backend (default: 9000) +export TYPEDIALOG_HOST=localhost # Host binding (default: localhost) + +# Localization +export TYPEDIALOG_LANG=en_US.UTF-8 # Form language (default: system locale) + +# Run with custom settings +TYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web +``` + +**Common use cases:** + +```bash +# Access from other machines in network +TYPEDIALOG_HOST=0.0.0.0 TYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web + +# Use different port if 9000 is busy +TYPEDIALOG_PORT=3000 .typedialog/ci/configure.sh web + +# Spanish interface +TYPEDIALOG_LANG=es_ES.UTF-8 .typedialog/ci/configure.sh web +``` + +## Configuration Structure + +Your config.ncl is organized in the `ci` namespace (Nickel format): + +```nickel +{ + ci = { + project = { + name = "markdown", + detected_languages = ["markdown"], + primary_language = "markdown", + }, + tools = { + # Tools are added based on detected languages + }, + features = { + # CI features (pre-commit, GitHub Actions, etc.) + }, + ci_providers = { + # CI provider configurations + }, + }, +} +``` + +## Available Fragments + +Tool configurations are modular. Check `.typedialog/ci/fragments/` for: + +- markdown-tools.toml - Tools for markdown +- general-tools.toml - Cross-language tools +- ci-providers.toml - GitHub Actions, Woodpecker, etc. + +## Cascading Override System + +This project uses a **local β†’ Tools cascading search** for all resources: + +### How It Works + +Resources are searched in priority order: + +1. **Local files** (`.typedialog/ci/`) - **FIRST** (highest priority) +2. **Tools files** (`$TOOLS_PATH/dev-system/ci/`) - **FALLBACK** (default) + +### Affected Resources + +| Resource | Local Path | Tools Path | +|----------|------------|------------| +| Fragments | `.typedialog/ci/fragments/` | `$TOOLS_PATH/dev-system/ci/forms/fragments/` | +| Schemas | `.typedialog/ci/schemas/` | `$TOOLS_PATH/dev-system/ci/schemas/` | +| Validators | `.typedialog/ci/validators/` | `$TOOLS_PATH/dev-system/ci/validators/` | +| Defaults | `.typedialog/ci/defaults/` | `$TOOLS_PATH/dev-system/ci/defaults/` | +| Nickel Template | `.typedialog/ci/config.ncl.j2` | `$TOOLS_PATH/dev-system/ci/templates/config.ncl.j2` | + +### Environment Setup (.envrc) + +The `.typedialog/ci/.envrc` file configures search paths: + +```bash +# Source this file to load environment +source .typedialog/ci/.envrc + +# Or use direnv for automatic loading +echo 'source .typedialog/ci/.envrc' >> .envrc +``` + +**What's in .envrc:** + +```bash +export NICKEL_IMPORT_PATH="schemas:$TOOLS_PATH/dev-system/ci/schemas:validators:..." +export TYPEDIALOG_FRAGMENT_PATH=".:$TOOLS_PATH/dev-system/ci/forms" +export NCL_TEMPLATE="" +export TYPEDIALOG_PORT=9000 # Web server port +export TYPEDIALOG_HOST=localhost # Web server host +export TYPEDIALOG_LANG="${LANG}" # Form localization +``` + +### Creating Overrides + +**By default:** All resources come from Tools (no duplication). + +**To customize:** Create file in local directory with same name: + +```bash +# Override a fragment +cp $TOOLS_PATH/dev-system/ci/fragments/rust-tools.toml \ + .typedialog/ci/fragments/rust-tools.toml + +# Edit your local version +vim .typedialog/ci/fragments/rust-tools.toml + +# Override Nickel template (customize comments, structure, nickel doc output) +cp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \ + .typedialog/ci/config.ncl.j2 + +# Edit to customize documentation and structure +vim .typedialog/ci/config.ncl.j2 + +# Now your version will be used instead of Tools version +``` + +**Benefits:** + +- βœ… Override only what you need +- βœ… Everything else stays synchronized with Tools +- βœ… No duplication by default +- βœ… Automatic updates when Tools is updated + +**See:** `$TOOLS_PATH/dev-system/ci/docs/cascade-override.md` for complete documentation. + +## Testing Your Configuration + +### Validate Configuration + +```bash +nu $env.TOOLS_PATH/dev-system/ci/scripts/validator.nu \ + --config .typedialog/ci/config.ncl \ + --project . \ + --namespace ci +``` + +### Regenerate CI Files + +```bash +nu $env.TOOLS_PATH/dev-system/ci/scripts/generate-configs.nu \ + --config .typedialog/ci/config.ncl \ + --templates $env.TOOLS_PATH/dev-system/ci/templates \ + --output . \ + --namespace ci +``` + +## Common Tasks + +### Add a New Tool + +Edit `config.ncl` and add under `ci.tools`: + +```nickel +{ + ci = { + tools = { + newtool = { + enabled = true, + install_method = "cargo", + version = "latest", + }, + }, + }, +} +``` + +### Disable a Feature + +```toml +[ci.features] +enable_pre_commit = false +``` + +## Need Help? + +For detailed documentation, see: +- $env.TOOLS_PATH/dev-system/ci/docs/configuration-guide.md +- $env.TOOLS_PATH/dev-system/ci/docs/installation-guide.md diff --git a/.typedialog/ci/config.ncl b/.typedialog/ci/config.ncl new file mode 100644 index 0000000..72b2ecf --- /dev/null +++ b/.typedialog/ci/config.ncl @@ -0,0 +1,203 @@ +# CI Configuration - Nickel Format +# Auto-generated by dev-system CI installer +# +# This file is managed by TypeDialog using nickel-roundtrip. +# Edit via: .typedialog/ci/configure.sh +# Or manually edit and validate with: nickel typecheck config.ncl +# +# Documentation: nickel doc config.ncl + +{ + # CI namespace - all configuration lives under 'ci' + ci = { + # Project Information + # Detected languages and primary language for this project + project = { + # Project name + name = "", + # Project description + description = "", + # Project website or documentation site URL + site_url = "", + # Project repository URL (GitHub, GitLab, etc.) + repo_url = "", + # Languages detected in codebase (auto-detected by installer) + detected_languages = [ + "rust", + "markdown", + "nickel" + ], + # Primary language (determines default tooling) + primary_language = "rust", + }, + + # CI Tools Configuration + # Each tool can be enabled/disabled and configured here + tools = { + # Taplo - TOML formatter and linter + taplo = { + enabled = true, + install_method = "cargo", + }, + # YAMLlint - YAML formatter and linter + yamllint = { + enabled = true, + install_method = "pip", + }, + # Clippy - Rust linting tool + clippy = { + enabled = true, + install_method = "cargo", + deny_warnings = true, + }, + # Cargo Audit - Security vulnerability scanner + audit = { + enabled = true, + install_method = "cargo", + }, + # Cargo Deny - Dependency checker + deny = { + enabled = true, + install_method = "cargo", + }, + # Cargo SBOM - Software Bill of Materials + sbom = { + enabled = true, + install_method = "cargo", + }, + # LLVM Coverage - Code coverage tool + llvm-cov = { + enabled = true, + install_method = "cargo", + }, + # Shellcheck - Bash/shell script linter + shellcheck = { + enabled = true, + install_method = "brew", + }, + # Shfmt - Shell script formatter + shfmt = { + enabled = true, + install_method = "brew", + }, + # Markdownlint - Markdown linter + markdownlint = { + enabled = true, + install_method = "npm", + }, + # Vale - Prose linter + vale = { + enabled = true, + install_method = "brew", + }, + # Nickel - Configuration language type checker + nickel = { + enabled = true, + install_method = "brew", + check_all = true, + }, + # NuShell - Shell script validator + nushell = { + enabled = true, + install_method = "builtin", + check_all = true, + }, + # Ruff - Fast Python linter + ruff = { + enabled = true, + install_method = "pip", + }, + # Black - Python code formatter + black = { + enabled = true, + install_method = "pip", + }, + # Mypy - Python static type checker + mypy = { + enabled = false, + install_method = "pip", + }, + # Pytest - Python testing framework + pytest = { + enabled = true, + install_method = "pip", + }, + # Golangci-lint - Go linter aggregator + "golangci-lint" = { + enabled = true, + install_method = "brew", + }, + # Gofmt - Go code formatter + gofmt = { + enabled = true, + install_method = "builtin", + }, + # Staticcheck - Go static analysis + staticcheck = { + enabled = true, + install_method = "brew", + }, + # Gosec - Go security checker + gosec = { + enabled = false, + install_method = "brew", + }, + # ESLint - JavaScript linter + eslint = { + enabled = true, + install_method = "npm", + }, + # Prettier - Code formatter + prettier = { + enabled = true, + install_method = "npm", + }, + # TypeScript - Type checking + typescript = { + enabled = false, + install_method = "npm", + }, + # Jest - JavaScript testing framework + jest = { + enabled = true, + install_method = "npm", + }, + }, + + # CI Features + # High-level feature flags for CI behavior + features = { + enable_ci_cd = true, + enable_pre_commit = true, + generate_taplo_config = true, + generate_contributing = true, + generate_security = true, + generate_code_of_conduct = true, + generate_dockerfiles = true, + enable_cross_compilation = true, + }, + + # CI Provider Configurations + # Settings for GitHub Actions, Woodpecker, GitLab CI, etc. + ci_providers = { + # GitHub Actions + github_actions = { + enabled = true, + branches_push = "main,develop", + branches_pr = "main", + }, + # Woodpecker CI + woodpecker = { + enabled = true, + }, + }, + + # CI Settings + settings = { + parallel_jobs = 1, + job_timeout_minutes = 1, + require_status_checks = true, + run_on_draft_prs = true, + }, + }, +} diff --git a/.typedialog/ci/configure.sh b/.typedialog/ci/configure.sh new file mode 100755 index 0000000..28cf7c8 --- /dev/null +++ b/.typedialog/ci/configure.sh @@ -0,0 +1,116 @@ +#!/usr/bin/env bash +# CI Configuration Script +# Auto-generated by dev-system/ci installer +# +# Interactive configuration for CI tools using TypeDialog. +# Uses Nickel format for configuration files. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +TYPEDIALOG_CI="${SCRIPT_DIR}" + +# Source envrc to load fragment paths and other environment variables +if [[ -f "${TYPEDIALOG_CI}/envrc" ]]; then + # shellcheck source=/dev/null + source "${TYPEDIALOG_CI}/envrc" +fi + +# Configuration files +FORM_FILE="${TYPEDIALOG_CI}/form.toml" +CONFIG_FILE="${TYPEDIALOG_CI}/config.ncl" + +# NCL_TEMPLATE is set by envrc (cascading: local β†’ Tools) +# If not set, use default from Tools +NCL_TEMPLATE="${NCL_TEMPLATE:-${TOOLS_PATH}/dev-system/ci/templates/config.ncl.j2}" + +# TypeDialog environment variables (can be overridden) +# Port for web backend (default: 9000) +export TYPEDIALOG_PORT="${TYPEDIALOG_PORT:-9000}" + +# Host for web backend (default: localhost) +export TYPEDIALOG_HOST="${TYPEDIALOG_HOST:-localhost}" + +# Locale for form localization (default: system locale) +export TYPEDIALOG_LANG="${TYPEDIALOG_LANG:-${LANG:-en_US.UTF-8}}" + +# Detect which TypeDialog backend to use (default: web) +BACKEND="${1:-web}" + +# Validate backend +case "$BACKEND" in + cli|tui|web) + ;; + *) + echo "Usage: $0 [cli|tui|web]" + echo "" + echo "Launches TypeDialog for interactive CI configuration." + echo "Backend options:" + echo " cli - Command-line interface (simple prompts)" + echo " tui - Terminal UI (interactive panels)" + echo " web - Web server (browser-based) [default]" + exit 1 + ;; +esac + +# Check if form exists +if [[ ! -f "$FORM_FILE" ]]; then + echo "Error: Form file not found: $FORM_FILE" + exit 1 +fi + +# Create backup if config exists +if [[ -f "$CONFIG_FILE" ]]; then + BACKUP="${CONFIG_FILE}.$(date +%Y%m%d_%H%M%S).bak" + cp "$CONFIG_FILE" "$BACKUP" + echo "ℹ️ Backed up existing config to: $(basename "$BACKUP")" +fi + +# Launch TypeDialog with Nickel roundtrip (preserves Nickel format) +echo "πŸ”§ Launching TypeDialog ($BACKEND backend)..." +echo "" + +# Show web server info if using web backend +if [[ "$BACKEND" == "web" ]]; then + echo "🌐 Web server will start on: http://${TYPEDIALOG_HOST}:${TYPEDIALOG_PORT}" + echo " (Override with: TYPEDIALOG_PORT=8080 TYPEDIALOG_HOST=0.0.0.0 $0)" + echo "" +fi + +# Build nickel-roundtrip command with optional template +NCL_TEMPLATE_ARG="" +if [[ -f "$NCL_TEMPLATE" ]]; then + NCL_TEMPLATE_ARG="--ncl-template $NCL_TEMPLATE" + echo "ℹ️ Using Nickel template: $NCL_TEMPLATE" +fi + +case "$BACKEND" in + cli) + typedialog nickel-roundtrip "$CONFIG_FILE" "$FORM_FILE" --output "$CONFIG_FILE" $NCL_TEMPLATE_ARG + ;; + tui) + typedialog-tui nickel-roundtrip "$CONFIG_FILE" "$FORM_FILE" --output "$CONFIG_FILE" $NCL_TEMPLATE_ARG + ;; + web) + typedialog-web nickel-roundtrip "$CONFIG_FILE" "$FORM_FILE" --output "$CONFIG_FILE" $NCL_TEMPLATE_ARG + ;; +esac + +EXIT_CODE=$? + +if [[ $EXIT_CODE -eq 0 ]]; then + echo "" + echo "βœ… Configuration saved to: $CONFIG_FILE" + echo "" + echo "Next steps:" + echo " - Review the configuration: cat $CONFIG_FILE" + echo " - Apply CI tools: (run your CI setup command)" + echo " - Re-run this script anytime to update: $0" +else + echo "" + echo "❌ Configuration cancelled or failed (exit code: $EXIT_CODE)" + if [[ -f "${CONFIG_FILE}.bak" ]]; then + echo " Previous config restored from backup" + fi + exit $EXIT_CODE +fi diff --git a/.typedialog/ci/envrc b/.typedialog/ci/envrc new file mode 100644 index 0000000..4c00a1b --- /dev/null +++ b/.typedialog/ci/envrc @@ -0,0 +1,27 @@ +# Auto-generated by dev-system/ci +# +# Cascading Path Strategy: +# 1. Local files in .typedialog/ci/ take precedence (overrides) +# 2. Central files in $TOOLS_PATH/dev-system/ci/ as fallback (defaults) +# +# To customize: Create file in .typedialog/ci/{schemas,validators,defaults,fragments}/ +# Your local version will be used instead of the Tools version. + +# Nickel import paths (cascading: local β†’ Tools) +export NICKEL_IMPORT_PATH="schemas:$TOOLS_PATH/dev-system/ci/schemas:validators:$TOOLS_PATH/dev-system/ci/validators:defaults:$TOOLS_PATH/dev-system/ci/defaults" + +# TypeDialog fragment search paths (cascading: local β†’ Tools) +export TYPEDIALOG_FRAGMENT_PATH=".typedialog/ci:$TOOLS_PATH/dev-system/ci/forms" + +# Nickel template for config.ncl generation (with cascading) +# Local template takes precedence if exists +if [[ -f ".typedialog/ci/config.ncl.j2" ]]; then + export NCL_TEMPLATE=".typedialog/ci/config.ncl.j2" +else + export NCL_TEMPLATE="$TOOLS_PATH/dev-system/ci/templates/config.ncl.j2" +fi + +# TypeDialog web backend configuration (override if needed) +export TYPEDIALOG_PORT=${TYPEDIALOG_PORT:-9000} +export TYPEDIALOG_HOST=${TYPEDIALOG_HOST:-localhost} +export TYPEDIALOG_LANG=${TYPEDIALOG_LANG:-${LANG:-en_US.UTF-8}} diff --git a/.typedialog/ci/form.toml b/.typedialog/ci/form.toml new file mode 100644 index 0000000..5e2a578 --- /dev/null +++ b/.typedialog/ci/form.toml @@ -0,0 +1,175 @@ +description = "Interactive configuration for continuous integration and code quality tools" +display_mode = "complete" +locales_path = "" +name = "CI Configuration Form" + +[[elements]] +border_bottom = true +border_top = true +name = "project_header" +title = "πŸ“¦ Project Information" +type = "section_header" + +[[elements]] +help = "Name of the project" +name = "project_name" +nickel_path = [ + "ci", + "project", + "name", +] +placeholder = "my-project" +prompt = "Project name" +required = true +type = "text" + +[[elements]] +help = "Optional description" +name = "project_description" +nickel_path = [ + "ci", + "project", + "description", +] +placeholder = "Brief description of what this project does" +prompt = "Project description" +required = false +type = "text" + +[[elements]] +default = "" +help = "Project website or documentation site URL" +name = "project_site_url" +nickel_path = [ + "ci", + "project", + "site_url", +] +placeholder = "https://example.com" +prompt = "Project Site URL" +required = false +type = "text" + +[[elements]] +default = "" +help = "Project repository URL (GitHub, GitLab, etc.)" +name = "project_repo_url" +nickel_path = [ + "ci", + "project", + "repo_url", +] +placeholder = "https://github.com/user/repo" +prompt = "Project Repo URL" +required = false +type = "text" + +[[elements]] +border_bottom = true +border_top = true +name = "languages_header" +title = "πŸ” Detected Languages" +type = "section_header" + +[[elements]] +default = "markdown" +display_mode = "grid" +help = "Select all languages detected or used in the project" +min_selected = 1 +name = "detected_languages" +nickel_path = [ + "ci", + "project", + "detected_languages", +] +prompt = "Which languages are used in this project?" +required = true +searchable = true +type = "multiselect" + +[[elements.options]] +value = "markdown" +label = "πŸ“ Markdown/Documentation" + +[[elements]] +help = "Main language used for defaults (e.g., in GitHub Actions workflows)" +name = "primary_language" +nickel_path = [ + "ci", + "project", + "primary_language", +] +options_from = "detected_languages" +prompt = "Primary language" +required = true +type = "select" +default = "markdown" + +[[elements.options]] +value = "markdown" +label = "πŸ“ Markdown" + +[[elements]] +includes = ["fragments/markdown-tools.toml"] +name = "markdown_tools_group" +type = "group" +when = "markdown in detected_languages" + +[[elements]] +includes = ["fragments/general-tools.toml"] +name = "general_tools_group" +type = "group" + +[[elements]] +border_bottom = true +border_top = true +name = "ci_cd_header" +title = "πŸ”„ CI/CD Configuration" +type = "section_header" + +[[elements]] +default = "true" +help = "Set up continuous integration and deployment pipelines" +name = "enable_ci_cd" +nickel_path = [ + "ci", + "features", + "enable_ci_cd", +] +prompt = "Enable CI/CD integration?" +type = "confirm" + +[[elements]] +includes = ["fragments/ci-providers.toml"] +name = "ci_providers_group" +type = "group" +when = "enable_ci_cd == true" + +[[elements]] +includes = ["fragments/ci-settings.toml"] +name = "ci_settings_group" +type = "group" +when = "enable_ci_cd == true" + +[[elements]] +includes = ["fragments/build-deployment.toml"] +name = "build_deployment_group" +type = "group" +when = "enable_ci_cd == true" + +[[elements]] +includes = ["fragments/documentation.toml"] +name = "documentation_group" +type = "group" + +[[elements]] +border_bottom = true +border_top = true +name = "confirmation_header" +title = "βœ… Ready to Install" +type = "section_header" + +[[elements]] +content = "Review your configuration above. After confirming, the CI system will be installed with your chosen settings." +name = "confirmation_footer" +type = "footer" diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..6289603 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,41 @@ +# Vale configuration for TypeDialog documentation +# https://vale.sh/docs/topics/config/ + +StylesPath = .vale/styles +MinAlertLevel = warning + +# Global settings +[*] +Packages = Google, write-good +Vocab = TypeDialog + +# Markdown files: docs/**/*.md and root *.md (excluding .claude, .coder, CLAUDE.md) +[*.md] +BasedOnStyles = write-good, Google + +# Ignore code blocks and specific patterns +TokenIgnores = (\$\{[^\}]+\}), (`[^`]+`), (\*\*[^\*]+\*\*) + +# Disable noisy rules for technical documentation +Google.Headings = NO +Google.Parens = NO +Google.Acronyms = NO +Google.Passive = NO +Google.We = NO +Google.Will = NO +Google.WordList = NO +Google.Colons = NO + +write-good.E-Prime = NO +write-good.TooWordy = NO +write-good.Passive = NO + +Vale.Spelling = NO + +# Keep enabled (useful for technical docs): +# - write-good.Weasel (vague words like "various") +# - Google.Contractions (maintain formal tone) +# - Google.FirstPerson (avoid "we/our") +# - Google.Exclamation +# - Google.Slang +# - Google.Units diff --git a/.vale/Vocab/TypeDialog/accept.txt b/.vale/Vocab/TypeDialog/accept.txt new file mode 100644 index 0000000..ffc7ad8 --- /dev/null +++ b/.vale/Vocab/TypeDialog/accept.txt @@ -0,0 +1,25 @@ +# TypeDialog accepted terms (case-insensitive) +# Technical acronyms and abbreviations +API +CLI +TUI +JSON +YAML +TOML +REST +HTTP +HTTPS +TLS +SSL +CORS +URL +URI +NPM +SDK +HTML +CSS +JWT +WASM +WebAssembly +README +CHANGELOG diff --git a/.vale/Vocab/TypeDialog/reject.txt b/.vale/Vocab/TypeDialog/reject.txt new file mode 100644 index 0000000..a7f5a8f --- /dev/null +++ b/.vale/Vocab/TypeDialog/reject.txt @@ -0,0 +1,2 @@ +# TypeDialog rejected terms +# Add terms that should never be used diff --git a/.vale/styles/Google/AMPM.yml b/.vale/styles/Google/AMPM.yml new file mode 100644 index 0000000..37b49ed --- /dev/null +++ b/.vale/styles/Google/AMPM.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'AM' or 'PM' (preceded by a space)." +link: "https://developers.google.com/style/word-list" +level: error +nonword: true +tokens: + - '\d{1,2}[AP]M\b' + - '\d{1,2} ?[ap]m\b' + - '\d{1,2} ?[aApP]\.[mM]\.' diff --git a/.vale/styles/Google/Acronyms.yml b/.vale/styles/Google/Acronyms.yml new file mode 100644 index 0000000..f41af01 --- /dev/null +++ b/.vale/styles/Google/Acronyms.yml @@ -0,0 +1,64 @@ +extends: conditional +message: "Spell out '%s', if it's unfamiliar to the audience." +link: 'https://developers.google.com/style/abbreviations' +level: suggestion +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/.vale/styles/Google/Colons.yml b/.vale/styles/Google/Colons.yml new file mode 100644 index 0000000..4a027c3 --- /dev/null +++ b/.vale/styles/Google/Colons.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' should be in lowercase." +link: 'https://developers.google.com/style/colons' +nonword: true +level: warning +scope: sentence +tokens: + - '(?=1.0.0" +} diff --git a/.vale/styles/Google/vocab.txt b/.vale/styles/Google/vocab.txt new file mode 100644 index 0000000..e69de29 diff --git a/.vale/styles/write-good/Cliches.yml b/.vale/styles/write-good/Cliches.yml new file mode 100644 index 0000000..c953143 --- /dev/null +++ b/.vale/styles/write-good/Cliches.yml @@ -0,0 +1,702 @@ +extends: existence +message: "Try to avoid using clichΓ©s like '%s'." +ignorecase: true +level: warning +tokens: + - a chip off the old block + - a clean slate + - a dark and stormy night + - a far cry + - a fine kettle of fish + - a loose cannon + - a penny saved is a penny earned + - a tough row to hoe + - a word to the wise + - ace in the hole + - acid test + - add insult to injury + - against all odds + - air your dirty laundry + - all fun and games + - all in a day's work + - all talk, no action + - all thumbs + - all your eggs in one basket + - all's fair in love and war + - all's well that ends well + - almighty dollar + - American as apple pie + - an axe to grind + - another day, another dollar + - armed to the teeth + - as luck would have it + - as old as time + - as the crow flies + - at loose ends + - at my wits end + - avoid like the plague + - babe in the woods + - back against the wall + - back in the saddle + - back to square one + - back to the drawing board + - bad to the bone + - badge of honor + - bald faced liar + - ballpark figure + - banging your head against a brick wall + - baptism by fire + - barking up the wrong tree + - bat out of hell + - be all and end all + - beat a dead horse + - beat around the bush + - been there, done that + - beggars can't be choosers + - behind the eight ball + - bend over backwards + - benefit of the doubt + - bent out of shape + - best thing since sliced bread + - bet your bottom dollar + - better half + - better late than never + - better mousetrap + - better safe than sorry + - between a rock and a hard place + - beyond the pale + - bide your time + - big as life + - big cheese + - big fish in a small pond + - big man on campus + - bigger they are the harder they fall + - bird in the hand + - bird's eye view + - birds and the bees + - birds of a feather flock together + - bit the hand that feeds you + - bite the bullet + - bite the dust + - bitten off more than he can chew + - black as coal + - black as pitch + - black as the ace of spades + - blast from the past + - bleeding heart + - blessing in disguise + - blind ambition + - blind as a bat + - blind leading the blind + - blood is thicker than water + - blood sweat and tears + - blow off steam + - blow your own horn + - blushing bride + - boils down to + - bolt from the blue + - bone to pick + - bored stiff + - bored to tears + - bottomless pit + - boys will be boys + - bright and early + - brings home the bacon + - broad across the beam + - broken record + - brought back to reality + - bull by the horns + - bull in a china shop + - burn the midnight oil + - burning question + - burning the candle at both ends + - burst your bubble + - bury the hatchet + - busy as a bee + - by hook or by crook + - call a spade a spade + - called onto the carpet + - calm before the storm + - can of worms + - can't cut the mustard + - can't hold a candle to + - case of mistaken identity + - cat got your tongue + - cat's meow + - caught in the crossfire + - caught red-handed + - checkered past + - chomping at the bit + - cleanliness is next to godliness + - clear as a bell + - clear as mud + - close to the vest + - cock and bull story + - cold shoulder + - come hell or high water + - cool as a cucumber + - cool, calm, and collected + - cost a king's ransom + - count your blessings + - crack of dawn + - crash course + - creature comforts + - cross that bridge when you come to it + - crushing blow + - cry like a baby + - cry me a river + - cry over spilt milk + - crystal clear + - curiosity killed the cat + - cut and dried + - cut through the red tape + - cut to the chase + - cute as a bugs ear + - cute as a button + - cute as a puppy + - cuts to the quick + - dark before the dawn + - day in, day out + - dead as a doornail + - devil is in the details + - dime a dozen + - divide and conquer + - dog and pony show + - dog days + - dog eat dog + - dog tired + - don't burn your bridges + - don't count your chickens + - don't look a gift horse in the mouth + - don't rock the boat + - don't step on anyone's toes + - don't take any wooden nickels + - down and out + - down at the heels + - down in the dumps + - down the hatch + - down to earth + - draw the line + - dressed to kill + - dressed to the nines + - drives me up the wall + - dull as dishwater + - dyed in the wool + - eagle eye + - ear to the ground + - early bird catches the worm + - easier said than done + - easy as pie + - eat your heart out + - eat your words + - eleventh hour + - even the playing field + - every dog has its day + - every fiber of my being + - everything but the kitchen sink + - eye for an eye + - face the music + - facts of life + - fair weather friend + - fall by the wayside + - fan the flames + - feast or famine + - feather your nest + - feathered friends + - few and far between + - fifteen minutes of fame + - filthy vermin + - fine kettle of fish + - fish out of water + - fishing for a compliment + - fit as a fiddle + - fit the bill + - fit to be tied + - flash in the pan + - flat as a pancake + - flip your lid + - flog a dead horse + - fly by night + - fly the coop + - follow your heart + - for all intents and purposes + - for the birds + - for what it's worth + - force of nature + - force to be reckoned with + - forgive and forget + - fox in the henhouse + - free and easy + - free as a bird + - fresh as a daisy + - full steam ahead + - fun in the sun + - garbage in, garbage out + - gentle as a lamb + - get a kick out of + - get a leg up + - get down and dirty + - get the lead out + - get to the bottom of + - get your feet wet + - gets my goat + - gilding the lily + - give and take + - go against the grain + - go at it tooth and nail + - go for broke + - go him one better + - go the extra mile + - go with the flow + - goes without saying + - good as gold + - good deed for the day + - good things come to those who wait + - good time was had by all + - good times were had by all + - greased lightning + - greek to me + - green thumb + - green-eyed monster + - grist for the mill + - growing like a weed + - hair of the dog + - hand to mouth + - happy as a clam + - happy as a lark + - hasn't a clue + - have a nice day + - have high hopes + - have the last laugh + - haven't got a row to hoe + - head honcho + - head over heels + - hear a pin drop + - heard it through the grapevine + - heart's content + - heavy as lead + - hem and haw + - high and dry + - high and mighty + - high as a kite + - hit paydirt + - hold your head up high + - hold your horses + - hold your own + - hold your tongue + - honest as the day is long + - horns of a dilemma + - horse of a different color + - hot under the collar + - hour of need + - I beg to differ + - icing on the cake + - if the shoe fits + - if the shoe were on the other foot + - in a jam + - in a jiffy + - in a nutshell + - in a pig's eye + - in a pinch + - in a word + - in hot water + - in the gutter + - in the nick of time + - in the thick of it + - in your dreams + - it ain't over till the fat lady sings + - it goes without saying + - it takes all kinds + - it takes one to know one + - it's a small world + - it's only a matter of time + - ivory tower + - Jack of all trades + - jockey for position + - jog your memory + - joined at the hip + - judge a book by its cover + - jump down your throat + - jump in with both feet + - jump on the bandwagon + - jump the gun + - jump to conclusions + - just a hop, skip, and a jump + - just the ticket + - justice is blind + - keep a stiff upper lip + - keep an eye on + - keep it simple, stupid + - keep the home fires burning + - keep up with the Joneses + - keep your chin up + - keep your fingers crossed + - kick the bucket + - kick up your heels + - kick your feet up + - kid in a candy store + - kill two birds with one stone + - kiss of death + - knock it out of the park + - knock on wood + - knock your socks off + - know him from Adam + - know the ropes + - know the score + - knuckle down + - knuckle sandwich + - knuckle under + - labor of love + - ladder of success + - land on your feet + - lap of luxury + - last but not least + - last hurrah + - last-ditch effort + - law of the jungle + - law of the land + - lay down the law + - leaps and bounds + - let sleeping dogs lie + - let the cat out of the bag + - let the good times roll + - let your hair down + - let's talk turkey + - letter perfect + - lick your wounds + - lies like a rug + - life's a bitch + - life's a grind + - light at the end of the tunnel + - lighter than a feather + - lighter than air + - like clockwork + - like father like son + - like taking candy from a baby + - like there's no tomorrow + - lion's share + - live and learn + - live and let live + - long and short of it + - long lost love + - look before you leap + - look down your nose + - look what the cat dragged in + - looking a gift horse in the mouth + - looks like death warmed over + - loose cannon + - lose your head + - lose your temper + - loud as a horn + - lounge lizard + - loved and lost + - low man on the totem pole + - luck of the draw + - luck of the Irish + - make hay while the sun shines + - make money hand over fist + - make my day + - make the best of a bad situation + - make the best of it + - make your blood boil + - man of few words + - man's best friend + - mark my words + - meaningful dialogue + - missed the boat on that one + - moment in the sun + - moment of glory + - moment of truth + - money to burn + - more power to you + - more than one way to skin a cat + - movers and shakers + - moving experience + - naked as a jaybird + - naked truth + - neat as a pin + - needle in a haystack + - needless to say + - neither here nor there + - never look back + - never say never + - nip and tuck + - nip it in the bud + - no guts, no glory + - no love lost + - no pain, no gain + - no skin off my back + - no stone unturned + - no time like the present + - no use crying over spilled milk + - nose to the grindstone + - not a hope in hell + - not a minute's peace + - not in my backyard + - not playing with a full deck + - not the end of the world + - not written in stone + - nothing to sneeze at + - nothing ventured nothing gained + - now we're cooking + - off the top of my head + - off the wagon + - off the wall + - old hat + - older and wiser + - older than dirt + - older than Methuselah + - on a roll + - on cloud nine + - on pins and needles + - on the bandwagon + - on the money + - on the nose + - on the rocks + - on the spot + - on the tip of my tongue + - on the wagon + - on thin ice + - once bitten, twice shy + - one bad apple doesn't spoil the bushel + - one born every minute + - one brick short + - one foot in the grave + - one in a million + - one red cent + - only game in town + - open a can of worms + - open and shut case + - open the flood gates + - opportunity doesn't knock twice + - out of pocket + - out of sight, out of mind + - out of the frying pan into the fire + - out of the woods + - out on a limb + - over a barrel + - over the hump + - pain and suffering + - pain in the + - panic button + - par for the course + - part and parcel + - party pooper + - pass the buck + - patience is a virtue + - pay through the nose + - penny pincher + - perfect storm + - pig in a poke + - pile it on + - pillar of the community + - pin your hopes on + - pitter patter of little feet + - plain as day + - plain as the nose on your face + - play by the rules + - play your cards right + - playing the field + - playing with fire + - pleased as punch + - plenty of fish in the sea + - point with pride + - poor as a church mouse + - pot calling the kettle black + - pretty as a picture + - pull a fast one + - pull your punches + - pulling your leg + - pure as the driven snow + - put it in a nutshell + - put one over on you + - put the cart before the horse + - put the pedal to the metal + - put your best foot forward + - put your foot down + - quick as a bunny + - quick as a lick + - quick as a wink + - quick as lightning + - quiet as a dormouse + - rags to riches + - raining buckets + - raining cats and dogs + - rank and file + - rat race + - reap what you sow + - red as a beet + - red herring + - reinvent the wheel + - rich and famous + - rings a bell + - ripe old age + - ripped me off + - rise and shine + - road to hell is paved with good intentions + - rob Peter to pay Paul + - roll over in the grave + - rub the wrong way + - ruled the roost + - running in circles + - sad but true + - sadder but wiser + - salt of the earth + - scared stiff + - scared to death + - sealed with a kiss + - second to none + - see eye to eye + - seen the light + - seize the day + - set the record straight + - set the world on fire + - set your teeth on edge + - sharp as a tack + - shoot for the moon + - shoot the breeze + - shot in the dark + - shoulder to the wheel + - sick as a dog + - sigh of relief + - signed, sealed, and delivered + - sink or swim + - six of one, half a dozen of another + - skating on thin ice + - slept like a log + - slinging mud + - slippery as an eel + - slow as molasses + - smart as a whip + - smooth as a baby's bottom + - sneaking suspicion + - snug as a bug in a rug + - sow wild oats + - spare the rod, spoil the child + - speak of the devil + - spilled the beans + - spinning your wheels + - spitting image of + - spoke with relish + - spread like wildfire + - spring to life + - squeaky wheel gets the grease + - stands out like a sore thumb + - start from scratch + - stick in the mud + - still waters run deep + - stitch in time + - stop and smell the roses + - straight as an arrow + - straw that broke the camel's back + - strong as an ox + - stubborn as a mule + - stuff that dreams are made of + - stuffed shirt + - sweating blood + - sweating bullets + - take a load off + - take one for the team + - take the bait + - take the bull by the horns + - take the plunge + - takes one to know one + - takes two to tango + - the more the merrier + - the real deal + - the real McCoy + - the red carpet treatment + - the same old story + - there is no accounting for taste + - thick as a brick + - thick as thieves + - thin as a rail + - think outside of the box + - third time's the charm + - this day and age + - this hurts me worse than it hurts you + - this point in time + - three sheets to the wind + - through thick and thin + - throw in the towel + - tie one on + - tighter than a drum + - time and time again + - time is of the essence + - tip of the iceberg + - tired but happy + - to coin a phrase + - to each his own + - to make a long story short + - to the best of my knowledge + - toe the line + - tongue in cheek + - too good to be true + - too hot to handle + - too numerous to mention + - touch with a ten foot pole + - tough as nails + - trial and error + - trials and tribulations + - tried and true + - trip down memory lane + - twist of fate + - two cents worth + - two peas in a pod + - ugly as sin + - under the counter + - under the gun + - under the same roof + - under the weather + - until the cows come home + - unvarnished truth + - up the creek + - uphill battle + - upper crust + - upset the applecart + - vain attempt + - vain effort + - vanquish the enemy + - vested interest + - waiting for the other shoe to drop + - wakeup call + - warm welcome + - watch your p's and q's + - watch your tongue + - watching the clock + - water under the bridge + - weather the storm + - weed them out + - week of Sundays + - went belly up + - wet behind the ears + - what goes around comes around + - what you see is what you get + - when it rains, it pours + - when push comes to shove + - when the cat's away + - when the going gets tough, the tough get going + - white as a sheet + - whole ball of wax + - whole hog + - whole nine yards + - wild goose chase + - will wonders never cease? + - wisdom of the ages + - wise as an owl + - wolf at the door + - words fail me + - work like a dog + - world weary + - worst nightmare + - worth its weight in gold + - wrong side of the bed + - yanking your chain + - yappy as a dog + - years young + - you are what you eat + - you can run but you can't hide + - you only live once + - you're the boss + - young and foolish + - young and vibrant diff --git a/.vale/styles/write-good/E-Prime.yml b/.vale/styles/write-good/E-Prime.yml new file mode 100644 index 0000000..074a102 --- /dev/null +++ b/.vale/styles/write-good/E-Prime.yml @@ -0,0 +1,32 @@ +extends: existence +message: "Try to avoid using '%s'." +ignorecase: true +level: suggestion +tokens: + - am + - are + - aren't + - be + - been + - being + - he's + - here's + - here's + - how's + - i'm + - is + - isn't + - it's + - she's + - that's + - there's + - they're + - was + - wasn't + - we're + - were + - weren't + - what's + - where's + - who's + - you're diff --git a/.vale/styles/write-good/Illusions.yml b/.vale/styles/write-good/Illusions.yml new file mode 100644 index 0000000..b4f1321 --- /dev/null +++ b/.vale/styles/write-good/Illusions.yml @@ -0,0 +1,11 @@ +extends: repetition +message: "'%s' is repeated!" +level: warning +alpha: true +action: + name: edit + params: + - truncate + - " " +tokens: + - '[^\s]+' diff --git a/.vale/styles/write-good/Passive.yml b/.vale/styles/write-good/Passive.yml new file mode 100644 index 0000000..f472cb9 --- /dev/null +++ b/.vale/styles/write-good/Passive.yml @@ -0,0 +1,183 @@ +extends: existence +message: "'%s' may be passive voice. Use active voice if you can." +ignorecase: true +level: warning +raw: + - \b(am|are|were|being|is|been|was|be)\b\s* +tokens: + - '[\w]+ed' + - awoken + - beat + - become + - been + - begun + - bent + - beset + - bet + - bid + - bidden + - bitten + - bled + - blown + - born + - bought + - bound + - bred + - broadcast + - broken + - brought + - built + - burnt + - burst + - cast + - caught + - chosen + - clung + - come + - cost + - crept + - cut + - dealt + - dived + - done + - drawn + - dreamt + - driven + - drunk + - dug + - eaten + - fallen + - fed + - felt + - fit + - fled + - flown + - flung + - forbidden + - foregone + - forgiven + - forgotten + - forsaken + - fought + - found + - frozen + - given + - gone + - gotten + - ground + - grown + - heard + - held + - hidden + - hit + - hung + - hurt + - kept + - knelt + - knit + - known + - laid + - lain + - leapt + - learnt + - led + - left + - lent + - let + - lighted + - lost + - made + - meant + - met + - misspelt + - mistaken + - mown + - overcome + - overdone + - overtaken + - overthrown + - paid + - pled + - proven + - put + - quit + - read + - rid + - ridden + - risen + - run + - rung + - said + - sat + - sawn + - seen + - sent + - set + - sewn + - shaken + - shaven + - shed + - shod + - shone + - shorn + - shot + - shown + - shrunk + - shut + - slain + - slept + - slid + - slit + - slung + - smitten + - sold + - sought + - sown + - sped + - spent + - spilt + - spit + - split + - spoken + - spread + - sprung + - spun + - stolen + - stood + - stridden + - striven + - struck + - strung + - stuck + - stung + - stunk + - sung + - sunk + - swept + - swollen + - sworn + - swum + - swung + - taken + - taught + - thought + - thrived + - thrown + - thrust + - told + - torn + - trodden + - understood + - upheld + - upset + - wed + - wept + - withheld + - withstood + - woken + - won + - worn + - wound + - woven + - written + - wrung diff --git a/.vale/styles/write-good/README.md b/.vale/styles/write-good/README.md new file mode 100644 index 0000000..3edcc9b --- /dev/null +++ b/.vale/styles/write-good/README.md @@ -0,0 +1,27 @@ +Based on [write-good](https://github.com/btford/write-good). + +> Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too. + +``` +The MIT License (MIT) + +Copyright (c) 2014 Brian Ford + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` diff --git a/.vale/styles/write-good/So.yml b/.vale/styles/write-good/So.yml new file mode 100644 index 0000000..e57f099 --- /dev/null +++ b/.vale/styles/write-good/So.yml @@ -0,0 +1,5 @@ +extends: existence +message: "Don't start a sentence with '%s'." +level: error +raw: + - '(?:[;-]\s)so[\s,]|\bSo[\s,]' diff --git a/.vale/styles/write-good/ThereIs.yml b/.vale/styles/write-good/ThereIs.yml new file mode 100644 index 0000000..8b82e8f --- /dev/null +++ b/.vale/styles/write-good/ThereIs.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Don't start a sentence with '%s'." +ignorecase: false +level: error +raw: + - '(?:[;-]\s)There\s(is|are)|\bThere\s(is|are)\b' diff --git a/.vale/styles/write-good/TooWordy.yml b/.vale/styles/write-good/TooWordy.yml new file mode 100644 index 0000000..275701b --- /dev/null +++ b/.vale/styles/write-good/TooWordy.yml @@ -0,0 +1,221 @@ +extends: existence +message: "'%s' is too wordy." +ignorecase: true +level: warning +tokens: + - a number of + - abundance + - accede to + - accelerate + - accentuate + - accompany + - accomplish + - accorded + - accrue + - acquiesce + - acquire + - additional + - adjacent to + - adjustment + - admissible + - advantageous + - adversely impact + - advise + - aforementioned + - aggregate + - aircraft + - all of + - all things considered + - alleviate + - allocate + - along the lines of + - already existing + - alternatively + - amazing + - ameliorate + - anticipate + - apparent + - appreciable + - as a matter of fact + - as a means of + - as far as I'm concerned + - as of yet + - as to + - as yet + - ascertain + - assistance + - at the present time + - at this time + - attain + - attributable to + - authorize + - because of the fact that + - belated + - benefit from + - bestow + - by means of + - by virtue of + - by virtue of the fact that + - cease + - close proximity + - commence + - comply with + - concerning + - consequently + - consolidate + - constitutes + - demonstrate + - depart + - designate + - discontinue + - due to the fact that + - each and every + - economical + - eliminate + - elucidate + - employ + - endeavor + - enumerate + - equitable + - equivalent + - evaluate + - evidenced + - exclusively + - expedite + - expend + - expiration + - facilitate + - factual evidence + - feasible + - finalize + - first and foremost + - for all intents and purposes + - for the most part + - for the purpose of + - forfeit + - formulate + - have a tendency to + - honest truth + - however + - if and when + - impacted + - implement + - in a manner of speaking + - in a timely manner + - in a very real sense + - in accordance with + - in addition + - in all likelihood + - in an effort to + - in between + - in excess of + - in lieu of + - in light of the fact that + - in many cases + - in my opinion + - in order to + - in regard to + - in some instances + - in terms of + - in the case of + - in the event that + - in the final analysis + - in the nature of + - in the near future + - in the process of + - inception + - incumbent upon + - indicate + - indication + - initiate + - irregardless + - is applicable to + - is authorized to + - is responsible for + - it is + - it is essential + - it seems that + - it was + - magnitude + - maximum + - methodology + - minimize + - minimum + - modify + - monitor + - multiple + - necessitate + - nevertheless + - not certain + - not many + - not often + - not unless + - not unlike + - notwithstanding + - null and void + - numerous + - objective + - obligate + - obtain + - on the contrary + - on the other hand + - one particular + - optimum + - overall + - owing to the fact that + - participate + - particulars + - pass away + - pertaining to + - point in time + - portion + - possess + - preclude + - previously + - prior to + - prioritize + - procure + - proficiency + - provided that + - purchase + - put simply + - readily apparent + - refer back + - regarding + - relocate + - remainder + - remuneration + - requirement + - reside + - residence + - retain + - satisfy + - shall + - should you wish + - similar to + - solicit + - span across + - strategize + - subsequent + - substantial + - successfully complete + - sufficient + - terminate + - the month of + - the point I am trying to make + - therefore + - time period + - took advantage of + - transmit + - transpire + - type of + - until such time as + - utilization + - utilize + - validate + - various different + - what I mean to say is + - whether or not + - with respect to + - with the exception of + - witnessed diff --git a/.vale/styles/write-good/Weasel.yml b/.vale/styles/write-good/Weasel.yml new file mode 100644 index 0000000..d1d90a7 --- /dev/null +++ b/.vale/styles/write-good/Weasel.yml @@ -0,0 +1,29 @@ +extends: existence +message: "'%s' is a weasel word!" +ignorecase: true +level: warning +tokens: + - clearly + - completely + - exceedingly + - excellent + - extremely + - fairly + - huge + - interestingly + - is a number + - largely + - mostly + - obviously + - quite + - relatively + - remarkably + - several + - significantly + - substantially + - surprisingly + - tiny + - usually + - various + - vast + - very diff --git a/.vale/styles/write-good/meta.json b/.vale/styles/write-good/meta.json new file mode 100644 index 0000000..a115d28 --- /dev/null +++ b/.vale/styles/write-good/meta.json @@ -0,0 +1,4 @@ +{ + "feed": "https://github.com/errata-ai/write-good/releases.atom", + "vale_version": ">=1.0.0" +} diff --git a/.woodpecker/Dockerfile b/.woodpecker/Dockerfile new file mode 100644 index 0000000..892a63a --- /dev/null +++ b/.woodpecker/Dockerfile @@ -0,0 +1,45 @@ +# Custom Docker image for Woodpecker CI +# Pre-installs common tools to speed up CI runs +# +# Build: docker build -t your-registry/ci:latest -f .woodpecker/Dockerfile . +# Push: docker push your-registry/ci:latest +# +# Then update .woodpecker/ci.yml to use: image: your-registry/ci:latest + +FROM rust:latest + +# Install system dependencies +RUN apt-get update && apt-get install -y \ + shellcheck \ + curl \ + git \ + && rm -rf /var/lib/apt/lists/* + +# Install just +RUN curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin + +# Install Rust components +RUN rustup component add clippy rustfmt + +# Install Rust tools (pre-compiled to speed up CI) +RUN cargo install \ + cargo-audit \ + cargo-deny \ + cargo-sbom \ + nickel-lang-cli \ + nu \ + --locked + +# Set working directory +WORKDIR /workspace + +# Verify installations +RUN just --version && \ + cargo --version && \ + cargo audit --version && \ + cargo deny --version && \ + cargo sbom --version && \ + nickel --version && \ + nu --version + +CMD ["/bin/bash"] \ No newline at end of file diff --git a/.woodpecker/Dockerfile.cross b/.woodpecker/Dockerfile.cross new file mode 100644 index 0000000..ea1edca --- /dev/null +++ b/.woodpecker/Dockerfile.cross @@ -0,0 +1,42 @@ +# Dockerfile for cross-platform compilation +# Supports building for multiple targets using docker + +FROM ubuntu:22.04 + +# Install build essentials +RUN apt-get update && apt-get install -y \ + build-essential \ + curl \ + git \ + pkg-config \ + && rm -rf /var/lib/apt/lists/* + +# Install Rust +RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable +ENV PATH="/root/.cargo/bin:${PATH}" + +# Install cross tool for cross-compilation +RUN cargo install cross --locked + +# Create workspace directory +WORKDIR /workspace + +# Copy entire project +COPY . . + +# Default build target +ARG TARGET=x86_64-unknown-linux-gnu +ENV BUILD_TARGET="${TARGET}" + +# Build command +RUN cross build --target "${BUILD_TARGET}" --release + +# Extract binaries to output directory +RUN mkdir -p /output/bin && \ + find target/"${BUILD_TARGET}"/release -maxdepth 1 -type f -executable -exec cp {} /output/bin/ \; + +# Create manifest +RUN echo "{ \"target\": \"${BUILD_TARGET}\", \"built\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\" }" > /output/BUILD_INFO.json + +# Default command +CMD ["/bin/bash"] \ No newline at end of file diff --git a/.woodpecker/README.md b/.woodpecker/README.md new file mode 100644 index 0000000..58b4853 --- /dev/null +++ b/.woodpecker/README.md @@ -0,0 +1,78 @@ +# Woodpecker CI Configuration + +Pipelines for Gitea/Forgejo + Woodpecker CI. + +## Files + +- **`ci.yml`** - Main CI pipeline (push, pull requests) +- **`Dockerfile`** - Custom CI image with pre-installed tools +- **`Dockerfile.cross`** - Cross-compilation image for multi-platform builds + +## Setup + +### 1. Activate Woodpecker CI + +Enable Woodpecker CI in your Gitea/Forgejo repository settings. + +### 2. (Optional) Build Custom Image + +Speeds up CI by pre-installing tools (~5 min faster per run). + +```bash +# Build CI image +docker build -t your-registry/ci:latest -f .woodpecker/Dockerfile . + +# Push to your registry +docker push your-registry/ci:latest + +# Update .woodpecker/ci.yml +# Change: image: rust:latest +# To: image: your-registry/ci:latest +``` + +### 3. Cross-Compilation Setup + +For multi-platform builds: + +```bash +# Build cross-compilation image +docker build -t your-registry/ci-cross:latest -f .woodpecker/Dockerfile.cross . + +# Push to registry +docker push your-registry/ci-cross:latest +``` + +## CI Pipeline (`ci.yml`) + +**Triggers**: Push to `main`/`develop`, Pull Requests + +**Jobs**: +1. Lint (Rust, Bash, Nickel, Nushell, Markdown) - Parallel +2. Test (all features) +3. Build (release) +4. Security audit +5. License compliance check + +**Duration**: ~15-20 minutes (without custom image), ~10-15 minutes (with custom image) + +## Triggering Pipelines + +```bash +# CI pipeline (automatic on push/PR) +git push origin main +``` + +## Viewing Results + +- **Gitea/Forgejo**: Repository β†’ Actions β†’ Pipeline runs +- **Woodpecker UI**: https://your-woodpecker.instance/repos/{user}/{repo} + +## Differences from GitHub Actions + +| Feature | GitHub Actions | Woodpecker CI | +|---------|---------------|---------------| +| Matrix builds | βœ… 3 OS | ❌ Linux only* | +| Caching | βœ… Built-in | ⚠️ Server-side** | + +\* Multi-OS builds require multiple Woodpecker agents +\*\* Configure in Woodpecker server settings diff --git a/.woodpecker/ci-advanced.yml b/.woodpecker/ci-advanced.yml new file mode 100644 index 0000000..3bda3c4 --- /dev/null +++ b/.woodpecker/ci-advanced.yml @@ -0,0 +1,168 @@ +# Woodpecker CI - Advanced Pipeline +# Multi-platform builds, coverage, benchmarks, and security scanning + +when: + event: [push, pull_request, manual] + branch: + - main + - develop + +matrix: + PLATFORM: + - linux/amd64 + - linux/arm64 + +steps: + # === LINTING (Parallel) === + + lint-rust: + image: rust:latest + commands: + - curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin + - rustup component add clippy rustfmt + - cargo fmt --all -- --check + - cargo clippy --all-targets --all-features -- -D warnings + environment: + CARGO_TERM_COLOR: always + + lint-bash: + image: koalaman/shellcheck-alpine:stable + commands: + - apk add --no-cache curl bash + - find . -name '*.sh' -type f ! -path './target/*' -exec shellcheck {} + + + lint-nickel: + image: rust:latest + commands: + - cargo install nickel-lang-cli --locked + - find . -name '*.ncl' -type f ! -path './target/*' -exec nickel typecheck {} \; + + lint-nushell: + image: rust:latest + commands: + - cargo install nu --locked + - find . -name '*.nu' -type f ! -path './target/*' -exec nu --ide-check 100 {} \; + + lint-markdown: + image: node:alpine + commands: + - npm install -g markdownlint-cli2 + - markdownlint-cli2 '**/*.md' '#node_modules' '#target' + + # === TESTING === + + test: + image: rust:latest + commands: + - cargo test --workspace --all-features --no-fail-fast + depends_on: + - lint-rust + - lint-bash + - lint-nickel + - lint-nushell + - lint-markdown + environment: + RUST_BACKTRACE: 1 + + # === CODE COVERAGE === + + coverage: + image: rust:latest + commands: + - cargo install cargo-tarpaulin --locked + - cargo tarpaulin --workspace --all-features --out Xml --output-dir coverage + - | + if [ -f coverage/cobertura.xml ]; then + echo "Coverage report generated successfully" + fi + depends_on: + - test + when: + event: [push, pull_request] + branch: [main, develop] + + # === BUILD (Multi-platform) === + + build-native: + image: rust:latest + commands: + - cargo build --release --workspace + - ls -lh target/release/ + depends_on: + - test + + build-cross: + image: rust:latest + commands: + - cargo install cross --locked + - cross build --target x86_64-unknown-linux-musl --release + - cross build --target aarch64-unknown-linux-musl --release + depends_on: + - test + when: + matrix: + PLATFORM: linux/amd64 + + # === BENCHMARKS === + + benchmark: + image: rust:latest + commands: + - rustup toolchain install nightly + - cargo +nightly bench --workspace --no-fail-fast + - | + if [ -d target/criterion ]; then + echo "Benchmark results available in target/criterion" + fi + depends_on: + - build-native + when: + event: pull_request + + # === SECURITY AUDITS === + + security-audit: + image: rust:latest + commands: + - cargo install cargo-audit --locked + - cargo audit --deny warnings --deny unmaintained --deny unsound + depends_on: + - lint-rust + + license-check: + image: rust:latest + commands: + - cargo install cargo-deny --locked + - cargo deny check licenses advisories sources bans + depends_on: + - lint-rust + + dependency-check: + image: rust:latest + commands: + - cargo install cargo-outdated --locked + - cargo outdated --exit-code 1 --root-deps-only + depends_on: + - lint-rust + when: + event: manual + + # === SONARQUBE ANALYSIS === + + sonarqube: + image: sonarsource/sonar-scanner-cli:latest + commands: + - | + sonar-scanner \ + -Dsonar.projectKey=${CI_REPO_NAME} \ + -Dsonar.sources=. \ + -Dsonar.host.url=${SONAR_HOST_URL} \ + -Dsonar.token=${SONAR_TOKEN} \ + -Dsonar.rust.clippy.reportPaths=clippy-report.json \ + -Dsonar.coverageReportPaths=coverage/cobertura.xml + depends_on: + - coverage + secrets: [sonar_host_url, sonar_token] + when: + event: [push, pull_request] + branch: [main, develop] diff --git a/.woodpecker/ci.yml b/.woodpecker/ci.yml new file mode 100644 index 0000000..be8aba9 --- /dev/null +++ b/.woodpecker/ci.yml @@ -0,0 +1,84 @@ +# Woodpecker CI Pipeline +# Equivalent to GitHub Actions CI workflow +# Generated by dev-system/ci + +when: + event: [push, pull_request, manual] + branch: + - main + - develop + +steps: + # === LINTING === + + lint-rust: + image: rust:latest + commands: + - curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin + - rustup component add clippy + - cargo fmt --all -- --check + - cargo clippy --all-targets -- -D warnings + + lint-bash: + image: koalaman/shellcheck-alpine:stable + commands: + - apk add --no-cache curl bash + - find . -name '*.sh' -type f ! -path './target/*' -exec shellcheck {} + + + lint-nickel: + image: rust:latest + commands: + - cargo install nickel-lang-cli --locked + - find . -name '*.ncl' -type f ! -path './target/*' -exec nickel typecheck {} \; + + lint-nushell: + image: rust:latest + commands: + - cargo install nu --locked + - find . -name '*.nu' -type f ! -path './target/*' -exec nu --ide-check 100 {} \; + + lint-markdown: + image: node:alpine + commands: + - npm install -g markdownlint-cli2 + - markdownlint-cli2 '**/*.md' '#node_modules' '#target' + + # === TESTING === + + test: + image: rust:latest + commands: + - cargo test --workspace --all-features + depends_on: + - lint-rust + - lint-bash + - lint-nickel + - lint-nushell + - lint-markdown + + # === BUILD === + + build: + image: rust:latest + commands: + - cargo build --release + depends_on: + - test + + # === SECURITY === + + security-audit: + image: rust:latest + commands: + - cargo install cargo-audit --locked + - cargo audit --deny warnings + depends_on: + - lint-rust + + license-check: + image: rust:latest + commands: + - cargo install cargo-deny --locked + - cargo deny check licenses advisories + depends_on: + - lint-rust diff --git a/.yamllint-ci.yml b/.yamllint-ci.yml new file mode 100644 index 0000000..3575afe --- /dev/null +++ b/.yamllint-ci.yml @@ -0,0 +1,18 @@ +extends: default + +rules: + line-length: + max: 200 # More reasonable for infrastructure code + comments: + min-spaces-from-content: 1 # Allow single space before comments + document-start: disable # Cloud-init files don't need --- start + truthy: + allowed-values: ["true", "false", "yes", "no", "on", "off"] # Allow cloud-init and GitHub Actions common values + +# Ignore cloud-init files for comment spacing since #cloud-config is a special directive +# Ignore directories with generated/runtime files +ignore: | + **/cloud-init.yml + build/** + data/** + envs/** diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ef8db03 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,103 @@ +# Code of Conduct + +## Our Pledge + +We, as members, contributors, and leaders, pledge to make participation in our project and community a harassment-free experience for everyone, regardless of: + +- Age +- Body size +- Visible or invisible disability +- Ethnicity +- Sex characteristics +- Gender identity and expression +- Level of experience +- Education +- Socioeconomic status +- Nationality +- Personal appearance +- Race +- Caste +- Color +- Religion +- Sexual identity and orientation + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by mistakes +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery +- Trolling, insulting, or derogatory comments +- Personal or political attacks +- Public or private harassment +- Publishing others' private information (doxing) +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate corrective action in response to unacceptable behavior. + +Maintainers have the right and responsibility to: + +- Remove, edit, or reject comments, commits, code, and other contributions +- Ban contributors for behavior they deem inappropriate, threatening, or harmful + +## Scope + +This Code of Conduct applies to: + +- All community spaces (GitHub, forums, chat, events, etc.) +- Official project channels and representations +- Interactions between community members related to the project + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to project maintainers: + +- Email: [project contact] +- GitHub: Private security advisory +- Issues: Report with `conduct` label (public discussions only) + +All complaints will be reviewed and investigated promptly and fairly. + +### Enforcement Guidelines + +**1. Correction** +- Community impact: Use of inappropriate language or unwelcoming behavior +- Action: Private written warning with explanation and clarity on impact +- Consequence: Warning and no further violations + +**2. Warning** +- Community impact: Violation through single incident or series of actions +- Action: Written warning with severity consequences for continued behavior +- Consequence: Suspension from community interaction + +**3. Temporary Ban** +- Community impact: Serious violation of standards +- Action: Temporary ban from community interaction +- Consequence: Revocation of ban after reflection period + +**4. Permanent Ban** +- Community impact: Pattern of violating community standards +- Action: Permanent ban from community interaction + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. + +For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. + +--- + +**Thank you for being part of our community!** + +We believe in creating a welcoming and inclusive space where everyone can contribute their best work. Together, we make this project better. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f41ec4b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,129 @@ +# Contributing to + +Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project. + +## Code of Conduct + +This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for details. + +## Getting Started + +### Prerequisites + +- Rust 1.70+ (if project uses Rust) +- NuShell (if project uses Nushell scripts) +- Git + +### Development Setup + +1. Fork the repository +2. Clone your fork: `git clone ` +3. Add upstream: `git remote add upstream ` +4. Create a branch: `git checkout -b feature/your-feature` + +## Development Workflow + +### Before You Code + +- Check existing issues and pull requests to avoid duplication +- Create an issue to discuss major changes before implementing +- Assign yourself to let others know you're working on it + +### Code Standards + +#### Rust + +- Run `cargo fmt --all` before committing +- All code must pass `cargo clippy -- -D warnings` +- Write tests for new functionality +- Maintain 100% documentation coverage for public APIs + +#### Nushell + +- Validate scripts with `nu --ide-check 100 script.nu` +- Follow consistent naming conventions +- Use type hints where applicable + +#### Nickel + +- Type check schemas with `nickel typecheck` +- Document schema fields with comments +- Test schema validation + +### Commit Guidelines + +- Write clear, descriptive commit messages +- Reference issues with `Fixes #123` or `Related to #123` +- Keep commits focused on a single concern +- Use imperative mood: "Add feature" not "Added feature" + +### Testing + +All changes must include tests: + +```bash +# Run all tests +cargo test --workspace + +# Run with coverage +cargo llvm-cov --all-features --lcov + +# Run locally before pushing +just ci-full +``` + +### Pull Request Process + +1. Update documentation for any changed functionality +2. Add tests for new code +3. Ensure all CI checks pass +4. Request review from maintainers +5. Be responsive to feedback and iterate quickly + +## Review Process + +- Maintainers will review your PR within 3-5 business days +- Feedback is constructive and meant to improve the code +- All discussions should be respectful and professional +- Once approved, maintainers will merge the PR + +## Reporting Bugs + +Found a bug? Please file an issue with: + +- **Title**: Clear, descriptive title +- **Description**: What happened and what you expected +- **Steps to reproduce**: Minimal reproducible example +- **Environment**: OS, Rust version, etc. +- **Screenshots**: If applicable + +## Suggesting Enhancements + +Have an idea? Please file an issue with: + +- **Title**: Clear feature title +- **Description**: What, why, and how +- **Use cases**: Real-world scenarios where this would help +- **Alternative approaches**: If you've considered any + +## Documentation + +- Keep README.md up to date +- Document public APIs with rustdoc comments +- Add examples for non-obvious functionality +- Update CHANGELOG.md with your changes + +## Release Process + +Maintainers handle releases following semantic versioning: +- MAJOR: Breaking changes +- MINOR: New features (backward compatible) +- PATCH: Bug fixes + +## Questions? + +- Check existing documentation and issues +- Ask in discussions or open an issue +- Join our community channels + +Thank you for contributing! diff --git a/README.md b/README.md new file mode 100644 index 0000000..7a0b8f9 --- /dev/null +++ b/README.md @@ -0,0 +1,235 @@ +
+ StratumIOps Logo +
+ +# StratumIOps + +**Infrastructure operations, AI agent orchestration, knowledge management, secrets management, and configuration generation.** + +Five integrated Rust projects. One ecosystem. Zero compromises. + +--- + +## The 4 Problems It Solves + +### 01 Β· Scattered Knowledge +Decisions in Slack, guidelines in wikis, patterns in docsβ€”all disconnected. **Kogral** unifies knowledge with git-native markdown and MCP for AI agents. + +### 02 Β· Uncontrolled LLM Costs + +No visibility or limits on AI spending per team. **Vapora** provides real-time budgets, automatic fallback to cheaper +providers, and expertise-based agent routing. + +### 03 Β· Fragile YAML Configuration +Runtime errors from untyped configuration. **Provisioning** uses Nickel with pre-runtime validation, **TypeDialog** generates forms with contract validation. + +### 04 Β· Static Cryptography +No preparation for quantum threats. **SecretumVault** implements production post-quantum crypto (ML-KEM-768, ML-DSA-65) with pluggable backends today. + +--- + +## Ecosystem Projects + +| Project | Description | Metrics | +| ------- | ----------- | ------- | +| **[Vapora](https://repo.jesusperez.pro/jesus/vapora)** | AI agent orchestration with learning and cost control | 13 crates, 218 tests, 50K LOC | +| **[Kogral](https://repo.jesusperez.pro/jesus/kogral)** | Knowledge graph with MCP for Claude Code | 3 crates, 56 tests, 15K LOC | +| **[TypeDialog](https://repo.jesusperez.pro/jesus/typedialog)** | Multi-backend forms (CLI, TUI, Web, AI, Agent, Prov-gen) | 8 crates, 3,818 tests, 90K LOC | +| **[Provisioning](https://repo.jesusperez.pro/jesus/provisioning)** | Declarative IaC with Nickel + AI-assisted generation | 15+ crates, 218 tests, 40K LOC | +| **[SecretumVault](https://repo.jesusperez.pro/jesus/secretumvault)** | Secrets management with post-quantum cryptography | 1 crate, 50+ tests, 11K LOC | + +### Vapora Β· AI Agent Orchestration + +AI agent orchestration with learning and cost control. Agents improve from experience, automatic budget fallback, NATS JetStream coordination. + +- AI agent orchestration with learning +- Agents improve from experience +- Automatic budget fallback +- NATS JetStream coordination +- 13 crates, 218 tests, 50K LOC + +### Kogral Β· Knowledge Graph + +Knowledge graph with MCP for Claude Code. 6 node types (Notes, ADRs, Guidelines, Patterns, Journals, Executions). Git-native markdown with semantic search. + +- Knowledge graph with MCP for Claude Code +- 6 node types: Notes, ADRs, Guidelines, Patterns, Journals, Executions +- Git-native markdown storage +- Semantic search with embeddings +- 3 crates, 56 tests, 15K LOC + +### TypeDialog Β· Multi-Backend Forms + +Multi-backend forms (CLI, TUI, Web, AI, Agent, Prov-gen). One TOML definition, 6 interfaces. Nickel contract validation. + +- 6 backends: CLI, TUI, Web, AI, Agent, Prov-gen +- One TOML definition for all interfaces +- Nickel contract validation +- Conditional fields & repeating groups +- 8 crates, 3,818 tests, 90K LOC + +### Provisioning Β· Declarative IaC + +Declarative IaC with Nickel + AI-assisted generation. Multi-cloud (AWS, UpCloud, Local), RAG with 1,200+ docs, MCP server, orchestrator with rollback. + +- Declarative IaC with Nickel + AI-assisted generation +- Multi-cloud: AWS, UpCloud, Local (LXD) +- RAG with 1,200+ domain docs +- MCP server for natural language queries +- Orchestrator with automatic rollback +- 15+ crates, 218 tests, 40K LOC + +### SecretumVault Β· Secrets Management + +Secrets management with post-quantum crypto. ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204). 4 crypto backends, 4 storage backends, 4 secrets engines. + +- Post-quantum crypto: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) +- 4 crypto backends: OpenSSL, OQS, AWS-LC, RustCrypto +- 4 storage backends: Filesystem, etcd, SurrealDB, PostgreSQL +- 4 secrets engines: KV, Transit, PKI, Database +- Shamir Secret Sharing for unsealing +- 1 crate, 50+ tests, 11K LOC + +--- + +## Technology Stack + +- **Languages**: Rust Edition 2021, Nickel, Nushell, Bash, Markdown +- **Databases**: SurrealDB (multi-tenant), etcd (HA), PostgreSQL (enterprise) +- **Messaging**: NATS JetStream (durable, ordered) +- **Frameworks**: Axum (REST), Leptos (WASM), Ratatui (TUI) +- **Crypto**: OpenSSL, OQS (Post-Quantum), AWS-LC, RustCrypto +- **Observability**: Prometheus, OpenTelemetry, Grafana + +--- + +## Ecosystem Metrics + +| Metric | Value | +| ------ | ----- | +| **Total Rust crates** | 40+ | +| **Total tests** | 4,360+ | +| **Total LOC** | ~206K | +| **Clippy warnings** | 0 | +| **Unsafe code blocks** | 0 | +| **Public API doc coverage** | 100% | +| **Crypto backends** | 4 (OpenSSL, OQS, AWS-LC, RustCrypto) | +| **Storage backends** | 4 (Filesystem, etcd, SurrealDB, PostgreSQL) | +| **TypeDialog backends** | 6 (CLI, TUI, Web, AI, Agent, Prov-gen) | +| **MCP Tools** | 14+ | +| **Multi-Cloud Support** | AWS, UpCloud, Local (LXD) | +| **Post-Quantum Ready** | Yes (ML-KEM-768, ML-DSA-65) | + +--- + +## What is StratumIOps + +StratumIOps is not a single project. It's the **orchestration layer** that coordinates: + +- **Documentation**: Unified docs for all ecosystem projects (bilingual en/es) +- **Branding Assets**: Logos, color schemes, web landing pages +- **Integration Patterns**: How projects work together +- **Shared Standards**: Language guidelines (Rust, Nickel, Nushell, Bash) + +### Documentation Structure + +```text +docs/ +β”œβ”€β”€ en/ # English documentation +β”‚ β”œβ”€β”€ ia/ # AI/Development track +β”‚ └── ops/ # Ops/DevOps track +└── es/ # Spanish documentation + β”œβ”€β”€ ia/ # AI/Development track + └── ops/ # Ops/DevOps track +``` + +### Branding Assets + +Complete branding system with 18+ assets: + +- **8 Logo variants**: Horizontal, vertical, animated, static, dark mode +- **4 Icon variants**: Animated, static, dark mode +- **4 Monochrome variants**: Black/white for print and accessibility +- **2 Social variants**: Optimized for social platforms (1080Γ—1080) +- **2 Favicon variants**: Browser tabs (16Γ—16, 32Γ—32) + +See [assets/branding/README.md](assets/branding/README.md) for detailed guidelines. + +--- + +## Integration Patterns + +### Example: Kogral β†’ Vapora + +```rust +// Vapora agent queries Kogral for guidelines before generating code +async fn get_project_context(task: &Task) -> Result { + let kogral = KogralMcpClient::connect().await?; + + let guidelines = kogral.call("get_guidelines", json!({ + "topic": &task.task_type, + "include_shared": true, + })).await?; + + Ok(ProjectContext { guidelines }) +} +``` + +### Example: TypeDialog β†’ Provisioning + +```rust +// TypeDialog prov-gen backend generates Nickel for Provisioning +async fn generate_infrastructure(form_response: &FormResponse) -> Result { + let generator = ProvGenBackend::new(); + let iac = generator.generate(&form_response.into()).await?; + + let provisioning = ProvisioningClient::connect().await?; + let workflow_id = provisioning.submit_workflow(iac).await?; + + Ok(workflow_id) +} +``` + +--- + +## Related Projects + +| Project | Local Path | Git Repo | +| ------- | ---------- | -------- | +| vapora | `/Users/Akasha/Development/vapora` | `https://repo.jesusperez.pro/jesus/vapora` | +| kogra | `/Users/Akasha/Development/kogral` | `https://repo.jesusperez.pro/jesus/kogra` | +| typedialog | `/Users/Akasha/Development/typedialog` | `https://repo.jesusperez.pro/jesus/typedialog` | +| provisioning | `/Users/Akasha/project-provisioning/provisioning` | `https://repo.jesusperez.pro/jesus/provisioning` | +| secretumvault | `/Users/Akasha/Development/secretumvault` | `https://repo.jesusperez.pro/jesus/secretumvault` | + +--- + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, code standards, and pull request process. + +## Security + +See [SECURITY.md](SECURITY.md) for security policy, vulnerability reporting, and security best practices. + +## Code of Conduct + +See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines and expected behavior. + +## License + +Proprietary / To be defined + +--- + +
+ +**StratumIOps v0.1.0** + +*Integrated ecosystem with Rust excellence ✨* + +Infrastructure Operations | AI Orchestration | Knowledge Management | Secrets & Configuration + +**100% Rust. Zero compromises.** + +
diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e49aa37 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,98 @@ +# Security Policy + +## Supported Versions + +This project provides security updates for the following versions: + +| Version | Supported | +|---------|-----------| +| 1.x | βœ… Yes | +| 0.x | ❌ No | + +Only the latest major version receives security patches. Users are encouraged to upgrade to the latest version. + +## Reporting a Vulnerability + +**Do not open public GitHub issues for security vulnerabilities.** + +Instead, please report security issues to the maintainers privately: + +### Reporting Process + +1. Email security details to the maintainers (see project README for contact) +2. Include: + - Description of the vulnerability + - Steps to reproduce (if possible) + - Potential impact + - Suggested fix (if you have one) + +3. Expect acknowledgment within 48 hours +4. We will work on a fix and coordinate disclosure timing + +### Responsible Disclosure + +- Allow reasonable time for a fix before public disclosure +- Work with us to understand and validate the issue +- Maintain confidentiality until the fix is released + +## Security Best Practices + +### For Users + +- Keep dependencies up to date +- Use the latest version of this project +- Review security advisories regularly +- Report vulnerabilities responsibly + +### For Contributors + +- Run `cargo audit` before submitting PRs +- Use `cargo deny` to check license compliance +- Follow secure coding practices +- Don't hardcode secrets or credentials +- Validate all external inputs + +## Dependency Security + +We use automated tools to monitor dependencies: + +- **cargo-audit**: Scans for known security vulnerabilities +- **cargo-deny**: Checks licenses and bans unsafe dependencies + +These run in CI on every push and PR. + +## Code Review + +All code changes go through review before merging: +- At least one maintainer review required +- Security implications considered +- Tests required for all changes +- CI checks must pass + +## Known Vulnerabilities + +We maintain transparency about known issues: +- Documented in GitHub security advisories +- Announced in release notes +- Tracked in issues with `security` label + +## Security Contact + +For security inquiries, please contact: +- Email: [project maintainers] +- Issue: Open a private security advisory on GitHub + +## Changelog + +Security fixes are highlighted in CHANGELOG.md with [SECURITY] prefix. + +## Resources + +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [CWE: Common Weakness Enumeration](https://cwe.mitre.org/) +- [Rust Security](https://www.rust-lang.org/governance/security-disclosures) +- [npm Security](https://docs.npmjs.com/about-npm/security) + +## Questions? + +If you have security questions (not vulnerabilities), open a discussion or issue with the `security` label. diff --git a/assets/branding/README.md b/assets/branding/README.md new file mode 100644 index 0000000..4a7b273 --- /dev/null +++ b/assets/branding/README.md @@ -0,0 +1,239 @@ +# StratumIOps Branding Assets + +Complete branding system for StratumIOps - Intelligent Infrastructure Operations platform. + +## Directory Structure + +```text +branding/ +β”œβ”€β”€ README.md # This file +β”œβ”€β”€ index.html # Quick reference showcase +└── stratumiops-assets-showcase.html # Comprehensive assets catalog +``` + +## Quick Start + +Open either HTML file in your browser to view the interactive branding showcase: + +- **`index.html`** - Compact version with dark/light mode toggle +- **`stratumiops-assets-showcase.html`** - Full-featured showcase with navigation, statistics, comparison tables, and detailed guidelines + +## Asset Categories + +### Logo Variants (8 total) + +All logos are available in the `../logos/` directory: + +| Variant | Dimensions | Features | Use Case | +|---------|------------|----------|----------| +| `stratumiops-h.svg` | 1200Γ—300px | Animated | Banners, headers | +| `stratumiops-v.svg` | 400Γ—520px | Animated | Posters, vertical UI | +| `stratumiops-h-static.svg` | 1200Γ—300px | Static bars | Print, documents | +| `stratumiops-v-static.svg` | 400Γ—520px | Static bars | Print, documents | +| `stratumiops-dark-h.svg` | 1200Γ—300px | Dark BG, glow | Dark mode UI | +| `stratumiops-dark-v.svg` | 400Γ—520px | Dark BG, glow | Dark mode UI | + +### Icon Variants (4 total) + +All icons feature layered architecture with central processor design: + +| Variant | Dimensions | Features | Use Case | +|---------|------------|----------|----------| +| `stratumiops-icon.svg` | 512Γ—512px | Animated particles | App icons, UI | +| `stratumiops-icon-static.svg` | 512Γ—512px | Static | Print, static UI | +| `stratumiops-icon-dark.svg` | 512Γ—512px | Dark BG, particles | Dark mode apps | +| `stratumiops-icon-dark-static.svg` | 512Γ—512px | Dark BG, static | Dark mode print | + +### Monochrome Variants (4 total) + +Black and white versions for print and accessibility: + +| Variant | Dimensions | Use Case | +|---------|------------|----------| +| `stratumiops-mono-black-h.svg` | 1200Γ—300px | Print, documents (light BG) | +| `stratumiops-mono-black-v.svg` | 400Γ—520px | Print, documents (light BG) | +| `stratumiops-mono-white-h.svg` | 1200Γ—300px | Dark backgrounds | +| `stratumiops-mono-white-v.svg` | 400Γ—520px | Dark backgrounds | + +### Social & Favicons (4 total) + +Optimized for social platforms and browser tabs: + +| Variant | Dimensions | Use Case | +|---------|------------|----------| +| `stratumiops-social-square-dark.svg` | 1080Γ—1080px | Social profiles (dark) | +| `stratumiops-social-square-light.svg` | 1080Γ—1080px | Social profiles (light) | +| `stratumiops-favicon-16.svg` | 16Γ—16px | Browser tabs | +| `stratumiops-favicon-32.svg` | 32Γ—32px | Browser tabs | + +## Color Palette + +Core brand colors with semantic meaning: + +- **Primary Indigo** (`#6366F1`) - Main brand identity, primary actions +- **Secondary Indigo** (`#4F46E5`) - Gradients, depth, secondary elements +- **Cyan Accent** (`#22D3EE`) - Highlights, active states, energy +- **Cyan Dark** (`#06B6D4`) - Processor core, technical elements +- **Slate** (`#64748b`) - Secondary text, borders, subtle elements +- **Dark Background** (`#0F172A`) - Dark mode UI, backgrounds + +## Usage Guidelines + +### Logo Sizing + +- Use horizontal variants for banners, headers, and wide layouts +- Use vertical variants for posters, splash screens, and tall layouts +- Maintain minimum 20px clear space around all logos +- Never distort, rotate, or modify the aspect ratio +- Prefer animated variants for digital applications with animation support + +### Color Usage + +- Primary Indigo (#6366F1) is the main brand color for all primary actions +- Cyan (#22D3EE) highlights active states and the central processor element +- Use gradients (Primary to Secondary Indigo, or Primary to Cyan) for visual depth +- Dark variants use enhanced glow effects for optimal dark mode visibility +- Monochrome variants ensure accessibility in all contexts + +### Animations + +- Animated variants include: + - Flowing particle paths between layers + - Pulsing equalizer bars in the central processor + - Synchronized glow effects +- Use static variants for print, emails, or contexts without animation support +- Animations are preserved in SVG format and scale responsively + +### Dark Mode + +- Dark variants (`-dark-h`, `-dark-v`, `-icon-dark`) optimized for dark backgrounds +- Enhanced glow and lighter stroke weights for visibility +- Mono-white variants for pure black backgrounds +- Ensure WCAG AA contrast compliance in all implementations + +### Digital Applications + +- All assets are SVG format for infinite scalability +- Use favicon variants (16Γ—16, 32Γ—32) for browser tabs and bookmarks +- Social square variants (1080Γ—1080) are optimized for profile pictures +- Icons (512Γ—512) work for app icons, PWA icons, and large UI elements +- Export to PNG at 2x or 3x resolution for high-DPI displays when needed + +### Print Production + +- Use static variants for print materials to ensure consistent output +- Monochrome black variants work for single-color prints +- Test on actual materials before production +- Ensure minimum 1/4" clear space around all logos +- Export to high-resolution PDF or PNG (300 DPI minimum) when needed + +### Social Media + +- Use `stratumiops-social-square-dark.svg` for dark-themed profiles +- Use `stratumiops-social-square-light.svg` for light-themed profiles +- Horizontal variants work for banners and cover images +- Always export at 2x scale for retina/high-DPI displays +- Provide alt-text: "StratumIOps - Intelligent Infrastructure Operations" + +### Accessibility + +- All color combinations meet WCAG AA contrast standards +- Monochrome variants ensure colorblind accessibility +- Use descriptive alt-text for all logo images +- Animated variants do not flash or strobe (safe for photosensitivity) +- Dark/light variants provide optimal visibility in all contexts + +## Asset Features + +✨ **Interactive HTML Showcases** + +- Dark/light mode toggle with localStorage persistence +- Responsive grid layouts for all screen sizes +- One-click filename copy to clipboard +- Sticky navigation with smooth scrolling (showcase version) +- Color palette visualization with HEX codes +- Comprehensive comparison tables + +🎨 **SVG Animations** + +- Flowing particle paths between infrastructure layers +- Pulsing equalizer bars in central processor +- Smooth glow effects on layers and I/O points +- Synchronized animations across all elements + +πŸ“Š **Format & Scalability** + +- All assets in SVG format +- Infinite scalability without quality loss +- Animations preserved across all sizes +- Print-ready static and monochrome variants +- Favicon variants optimized for browser rendering + +## File Sizes + +- Logo variants: ~4-6KB each (animated), ~3-4KB (static) +- Icon variants: ~3-5KB each (animated), ~2-3KB (static) +- Monochrome variants: ~2-3KB each +- Social/Favicon variants: ~1-3KB each +- HTML showcases: index.html (~18KB), showcase (~30KB) + +## Technical Specifications + +### SVG Features + +- Linear gradients for depth and visual interest +- SMIL animations for particle flows and pulsing effects +- Optimized viewBox dimensions for each variant +- Clean, minimal markup for fast loading + +### Design Elements + +- **Layers**: Three horizontal bars representing infrastructure strata +- **Flows**: Curved paths showing data flow between layers +- **Processor**: Central rectangle with internal elements (equalizer bars) +- **I/O Points**: Circles marking input/output connections +- **Particles**: Animated circles flowing along connection paths + +## Version Information + +- **Last Updated:** 2026-01-22 +- **Version:** 1.0 +- **Format:** SVG + HTML5 +- **Compatibility:** All modern browsers +- **Total Assets:** 18 (8 logos, 4 icons, 4 mono, 2 social, 2 favicons) + +## Brand Identity + +**StratumIOps** represents: + +- πŸ—οΈ Layered infrastructure architecture +- ⚑ Intelligent automation and operations +- πŸ”„ Data flows across system boundaries +- πŸŽ›οΈ Central processing and orchestration +- 🌐 Modern, animated visual identity +- πŸ”§ DevOps, GitOps, and infrastructure as code + +## Design Philosophy + +The StratumIOps visual identity communicates: + +1. **Layered Architecture**: Three horizontal bars represent infrastructure layers (compute, storage, network) +2. **Data Flow**: Curved connection paths show information flow between layers +3. **Central Processing**: The processor element represents orchestration and intelligence +4. **Technical Precision**: Clean lines, geometric shapes, and systematic organization +5. **Energy and Motion**: Animations convey active processing and continuous operation + +## Related Assets + +- Logo variants: `/assets/logos/stratumiops-*.svg` +- Icon variants: `/assets/logos/stratumiops-icon*.svg` +- Monochrome variants: `/assets/logos/stratumiops-mono-*.svg` +- Social/Favicon variants: `/assets/logos/stratumiops-social-*.svg`, `/assets/logos/stratumiops-favicon-*.svg` + +## Contact & Updates + +For asset requests, updates, or branding questions, refer to the StratumIOps project documentation. + +--- + +**All assets in the StratumIOps branding system are optimized for scalability, accessibility, and brand consistency across digital and print media.** diff --git a/assets/branding/index.html b/assets/branding/index.html new file mode 100644 index 0000000..5934e47 --- /dev/null +++ b/assets/branding/index.html @@ -0,0 +1,1438 @@ + + + + + + StratumIOps Branding Assets + + + + + + + + +
+ +
+

Logo Variants

+
+ +
+
+ StratumIOps Logo Horizontal +
+
+
Horizontal
+
MAIN
+
+
+ Size + 1200x300px +
+
+ Format + SVG +
+
+
+
+ stratumiops-h.svg + +
+
+
+
+ + +
+
+ StratumIOps Logo Vertical +
+
+
Vertical
+
LAYOUTS
+
+
+ Size + 400x520px +
+
+ Use + Mobile +
+
+
+
+ stratumiops-v.svg + +
+
+
+
+ + +
+
+ StratumIOps Horizontal Static +
+
+
Horizontal Static
+
STATIC
+
+
+ Size + 1200x300px +
+
+ Use + Print +
+
+
+
+ stratumiops-h-static.svg + +
+
+
+
+ + +
+
+ StratumIOps Vertical Static +
+
+
Vertical Static
+
STATIC
+
+
+ Size + 400x520px +
+
+ Use + Print +
+
+
+
+ stratumiops-v-static.svg + +
+
+
+
+ + +
+
+ StratumIOps Dark Horizontal +
+
+
Dark Horizontal
+
DARK
+
+
+ Size + 1200x300px +
+
+ Use + Dark BG +
+
+
+
+ stratumiops-dark-h.svg + +
+
+
+
+ + +
+
+ StratumIOps Dark Vertical +
+
+
Dark Vertical
+
DARK
+
+
+ Size + 400x520px +
+
+ Use + Dark BG +
+
+
+
+ stratumiops-dark-v.svg + +
+
+
+
+
+
+ + +
+

Icon Variants

+
+ +
+
+ StratumIOps Icon +
+
+
Main Icon
+
ICON
+
+
+ Size + 512x512px +
+
+ Use + Apps +
+
+
+
+ stratumiops-icon.svg + +
+
+
+
+ + +
+
+ StratumIOps Icon Static +
+
+
Icon Static
+
STATIC
+
+
+ Size + 512x512px +
+
+ Use + Print +
+
+
+
+ stratumiops-icon-static.svg + +
+
+
+
+ + +
+
+ StratumIOps Icon Dark +
+
+
Icon Dark
+
DARK
+
+
+ Size + 512x512px +
+
+ Use + Dark BG +
+
+
+
+ stratumiops-icon-dark.svg + +
+
+
+
+
+
+ + +
+

Monochrome Variants

+
+ +
+
+ StratumIOps Mono Black Horizontal +
+
+
Mono Black Horizontal
+
MONO
+
+
+ Use + Print +
+
+
+
+ stratumiops-mono-black-h.svg + +
+
+
+
+ + +
+
+ StratumIOps Mono White Horizontal +
+
+
Mono White Horizontal
+
MONO
+
+
+ Use + Dark BG +
+
+
+
+ stratumiops-mono-white-h.svg + +
+
+
+
+
+
+ + +
+

Social Media

+
+ +
+
+ StratumIOps Social Dark +
+
+
Social Square Dark
+
SOCIAL
+
+
+ Size + 1080x1080px +
+
+ Use + Social Media +
+
+
+
+ stratumiops-social-square-dark.svg + +
+
+
+
+ + +
+
+ StratumIOps Social Light +
+
+
Social Square Light
+
SOCIAL
+
+
+ Size + 1080x1080px +
+
+ Use + Social Media +
+
+
+
+ stratumiops-social-square-light.svg + +
+
+
+
+
+
+ +
+

Scalability Test

+
+

+ Icon clarity at different sizes - from favicon to app icons +

+
+
+
+
+ 16Γ—16 Icon +
+
16Γ—16
+
Favicon
+
+ +
+
+ 32Γ—32 Icon +
+
32Γ—32
+
Browser tab
+
+ +
+
+ 64Γ—64 Icon +
+
64Γ—64
+
App icon
+
+ +
+
+ 128Γ—128 Icon +
+
128Γ—128
+
Apple touch
+
+ +
+
+ 256Γ—256 Icon +
+
256Γ—256
+
PWA icon
+
+
+
+ + +
+

Color Palette

+
+
+
+
Primary Indigo
+
#6366F1
+
+
+
+
Secondary Indigo
+
#4F46E5
+
+
+
+
Cyan Accent
+
#22D3EE
+
+
+
+
Cyan Dark
+
#06B6D4
+
+
+
+
Slate Secondary
+
#64748b
+
+
+
+
Dark Background
+
#0F172A
+
+
+
+ + +
+

Typography

+
+
+
Display / Headings
+
+ StratumIOps +
+
+
+ Family + Inter +
+
+ Weight + 800 +
+
+ Size + 32px+ +
+
+ Use + Hero, H1 +
+
+
+ +
+
Headings / Titles
+
+ Infrastructure Operations +
+
+
+ Family + Inter +
+
+ Weight + 700 +
+
+ Size + 24px +
+
+ Use + H2, H3 +
+
+
+ +
+
Body / Regular
+
+ Declarative infrastructure orchestration with GitOps workflows and + intelligent automation. +
+
+
+ Family + Inter +
+
+ Weight + 400 +
+
+ Size + 16px +
+
+ Use + Body text +
+
+
+ +
+
Emphasis / Semibold
+
+ Multi-cloud provisioning and policy enforcement +
+
+
+ Family + Inter +
+
+ Weight + 600 +
+
+ Size + 16px +
+
+ Use + Emphasis +
+
+
+ +
+
Small / UI Elements
+
+ Configuration Β· GitOps Β· Kubernetes +
+
+
+ Family + Inter +
+
+ Weight + 500 +
+
+ Size + 14px +
+
+ Use + Labels, UI +
+
+
+ +
+
Code / Monospace
+
+ stratumiops-h.svg +
+
+
+ Family + Courier +
+
+ Weight + 400 +
+
+ Size + 14px +
+
+ Use + Code, files +
+
+
+
+ +
+

Font Usage

+

+ Inter is used for all typography in StratumIOps branding. The font + is clean, modern, and highly readable at all sizes. +

+
+
+ Import from Google Fonts: +
+
+ @import + url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap'); + +
+
+
+
+ CSS Font-family declaration: +
+
+ font-family: Inter, -apple-system, BlinkMacSystemFont, + sans-serif; + +
+
+
+
+ + +
+

Usage Guidelines

+
+

Logo Usage

+

+ Use the horizontal logo for primary brand + identification on websites, marketing materials, and product pages. + The vertical variant works well for mobile and social media. For + print, use the static variants. Always maintain sufficient + whitespace around the logo (minimum 20px). +

+
+ +
+

Color Palette

+

+ Primary Indigo (#6366F1) represents the layered + infrastructure architecture. + Cyan (#22D3EE) highlights the central processing + and intelligent operations. Use the monochrome variants for print + and high-contrast applications. +

+
+ +
+

Typography

+

+ Use Inter font family from Google Fonts for all + text. Weight 800 for display/hero text, 700 for headings, 600 for + subheadings, 400 for body text, and 500 for UI elements. Use + Courier New monospace for code, filenames, and HEX + values. Maintain line height of 1.3-1.7 for optimal readability. +

+
+ +
+

Icon Usage

+

+ Use stratumiops-icon.svg (512x512px) for most + applications including favicons and UI elements. The + static variant is optimized for print. The dark + versions are suitable for dark backgrounds and accessibility + contexts. +

+
+
+ +
+

+ StratumIOps Branding System β€’ All assets are SVG format for maximum + scalability β€’ Last updated 2026-01-22 +

+
+
+ + + + diff --git a/assets/branding/stratumiops-ascii.txt b/assets/branding/stratumiops-ascii.txt new file mode 100644 index 0000000..799d4a7 --- /dev/null +++ b/assets/branding/stratumiops-ascii.txt @@ -0,0 +1,8 @@ + β•”β•β•—β”Œβ”¬β”β”¬β”€β”β”Œβ”€β”β”Œβ”¬β”β”¬ β”¬β”Œβ”¬β” ╦ β”Œβ”€β”β”Œβ”€β”β”Œβ”€β” + β•šβ•β•— β”‚ β”œβ”¬β”˜β”œβ”€β”€ β”‚ β”‚ β”‚β”‚β”‚β”‚ β•‘ β”‚ β”‚β”œβ”€β”˜β””β”€β” + β•šβ•β• β”΄ ┴└─┴ β”΄ β”΄ β””β”€β”˜β”΄ β”΄ β•© β””β”€β”˜β”΄ β””β”€β”˜ +╔═══════════════════════════════════════╗ +β•‘ Infrastructure operations hub β•‘ +β•‘ for STRATUMIOPS projects ecosystem β•‘ +β•‘ stratumiops.dev β•‘ +β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• diff --git a/assets/branding/stratumiops-assets-showcase.html b/assets/branding/stratumiops-assets-showcase.html new file mode 100644 index 0000000..d403ce5 --- /dev/null +++ b/assets/branding/stratumiops-assets-showcase.html @@ -0,0 +1,1984 @@ + + + + + + StratumIOps Assets Showcase + + + + + + + + + +
+
+

StratumIOps Branding Assets

+
+
+
18
+
Total Assets
+
+
+
8
+
Logo Variants
+
+
+
4
+
Icon Variants
+
+
+
6
+
Brand Colors
+
+
+
SVG
+
Format
+
+
+
+
+ +
+ +
+
+
+

Logo Variants

+

Animated and static brand identities

+
+ +
+ +
+
+ Horizontal Logo +
+
+
Horizontal (Animated)
+
Primary
+
+
+
Dimensions
+
1200Γ—300px
+
+
+
Features
+
Animated
+
+
+
+ stratumiops-h.svg + +
+
+
+ + +
+
+ Vertical Logo +
+
+
Vertical (Animated)
+
Layout
+
+
+
Dimensions
+
400Γ—520px
+
+
+
Features
+
Animated
+
+
+
+ stratumiops-v.svg + +
+
+
+ + +
+
+ Horizontal Static Logo +
+
+
Horizontal Static
+
Print Ready
+
+
+
Dimensions
+
1200Γ—300px
+
+
+
Use Case
+
Print/Static
+
+
+
+ stratumiops-h-static.svg + +
+
+
+ + +
+
+ Vertical Static Logo +
+
+
Vertical Static
+
Print Ready
+
+
+
Dimensions
+
400Γ—520px
+
+
+
Use Case
+
Print/Static
+
+
+
+ stratumiops-v-static.svg + +
+
+
+ + +
+
+ Dark Horizontal Logo +
+
+
Dark Horizontal
+
Dark Mode
+
+
+
Dimensions
+
1200Γ—300px
+
+
+
Use Case
+
Dark UI
+
+
+
+ stratumiops-dark-h.svg + +
+
+
+ + +
+
+ Dark Vertical Logo +
+
+
Dark Vertical
+
Dark Mode
+
+
+
Dimensions
+
400Γ—520px
+
+
+
Use Case
+
Dark UI
+
+
+
+ stratumiops-dark-v.svg + +
+
+
+
+
+
+ + +
+
+
+

Icon Variants

+

Scalable icons with dynamic elements

+
+ +
+ +
+
+ Main Icon +
+
+
Main Icon (Animated)
+
Primary
+
+
+
Dimensions
+
512Γ—512px
+
+
+
Features
+
Particles
+
+
+
+ stratumiops-icon.svg + +
+
+
+ + +
+
+ Static Icon +
+
+
Static Icon
+
Print Ready
+
+
+
Dimensions
+
512Γ—512px
+
+
+
Use Case
+
Static UI
+
+
+
+ stratumiops-icon-static.svg + +
+
+
+ + +
+
+ Dark Icon +
+
+
Dark Icon (Animated)
+
Dark Mode
+
+
+
Dimensions
+
512Γ—512px
+
+
+
Features
+
Particles
+
+
+
+ stratumiops-icon-dark.svg + +
+
+
+ + +
+
+ Dark Static Icon +
+
+
Dark Static Icon
+
Dark Mode
+
+
+
Dimensions
+
512Γ—512px
+
+
+
Use Case
+
Dark UI
+
+
+
+ stratumiops-icon-dark-static.svg + +
+
+
+
+
+
+ + +
+
+
+

Monochrome Variants

+

+ Black and white versions for print and accessibility +

+
+ +
+ +
+
+ Mono Black Horizontal +
+
+
Black Horizontal
+
Monochrome
+
+
+
Dimensions
+
1200Γ—300px
+
+
+
Use Case
+
Print/Docs
+
+
+
+ stratumiops-mono-black-h.svg + +
+
+
+ + +
+
+ Mono Black Vertical +
+
+
Black Vertical
+
Monochrome
+
+
+
Dimensions
+
400Γ—520px
+
+
+
Use Case
+
Print/Docs
+
+
+
+ stratumiops-mono-black-v.svg + +
+
+
+ + +
+
+ Mono White Horizontal +
+
+
White Horizontal
+
Monochrome
+
+
+
Dimensions
+
1200Γ—300px
+
+
+
Use Case
+
Dark BG
+
+
+
+ stratumiops-mono-white-h.svg + +
+
+
+ + +
+
+ Mono White Vertical +
+
+
White Vertical
+
Monochrome
+
+
+
Dimensions
+
400Γ—520px
+
+
+
Use Case
+
Dark BG
+
+
+
+ stratumiops-mono-white-v.svg + +
+
+
+
+
+
+ + +
+
+
+

Social Media Assets

+

+ Optimized for social platforms and favicons +

+
+ +
+ +
+
+ Social Square Dark +
+
+
Social Square Dark
+
Social Media
+
+
+
Dimensions
+
1080Γ—1080px
+
+
+
Use Case
+
Profiles
+
+
+
+ stratumiops-social-square-dark.svg + +
+
+
+ + +
+
+ Social Square Light +
+
+
Social Square Light
+
Social Media
+
+
+
Dimensions
+
1080Γ—1080px
+
+
+
Use Case
+
Profiles
+
+
+
+ stratumiops-social-square-light.svg + +
+
+
+ + +
+
+ Favicon 16x16 +
+
+
Favicon 16Γ—16
+
Favicon
+
+
+
Dimensions
+
16Γ—16px
+
+
+
Use Case
+
Browser
+
+
+
+ stratumiops-favicon-16.svg + +
+
+
+ + +
+
+ Favicon 32x32 +
+
+
Favicon 32Γ—32
+
Favicon
+
+
+
Dimensions
+
32Γ—32px
+
+
+
Use Case
+
Browser
+
+
+
+ stratumiops-favicon-32.svg + +
+
+
+
+
+
+ +
+
+
+

Scalability Test

+

+ Icon clarity at different sizes - from favicon to app icons +

+
+ +
+
+
+ 16Γ—16 Icon +
+
16Γ—16
+
Favicon
+
+ +
+
+ 32Γ—32 Icon +
+
32Γ—32
+
Browser tab
+
+ +
+
+ 64Γ—64 Icon +
+
64Γ—64
+
App icon
+
+ +
+
+ 128Γ—128 Icon +
+
128Γ—128
+
Apple touch
+
+ +
+
+ 256Γ—256 Icon +
+
256Γ—256
+
PWA icon
+
+
+
+
+ + +
+
+
+

Color Palette

+

+ Core brand colors with semantic meaning +

+
+ +
+
+
+
+
Primary Indigo
+
#6366F1
+
Main Brand Identity
+
+
+ +
+
+
+
Secondary Indigo
+
#4F46E5
+
Gradients & Depth
+
+
+ +
+
+
+
Cyan Accent
+
#22D3EE
+
Highlights & Active
+
+
+ +
+
+
+
Cyan Dark
+
#06B6D4
+
Processor & Core
+
+
+ +
+
+
+
Slate
+
#64748b
+
Secondary & Text
+
+
+ +
+
+
+
Dark Background
+
#0F172A
+
Dark Mode & UI
+
+
+
+
+
+ + +
+
+
+

Typography

+

+ Font family, weights, and usage guidelines +

+
+ +
+
+
Display / Hero
+
+ StratumIOps +
+
+
+ Family + Inter +
+
+ Weight + 800 (ExtraBold) +
+
+ Size + 32-48px +
+
+ Use Case + Hero, H1 +
+
+
+ +
+
Headings / Titles
+
+ Infrastructure Operations +
+
+
+ Family + Inter +
+
+ Weight + 700 (Bold) +
+
+ Size + 20-28px +
+
+ Use Case + H2, H3, Sections +
+
+
+ +
+
Subheadings
+
+ GitOps workflows and multi-cloud +
+
+
+ Family + Inter +
+
+ Weight + 600 (SemiBold) +
+
+ Size + 16-20px +
+
+ Use Case + H4, Cards +
+
+
+ +
+
Body Text / Regular
+
+ Declarative infrastructure orchestration with GitOps workflows, + configuration as code, and intelligent automation for + multi-cloud environments. +
+
+
+ Family + Inter +
+
+ Weight + 400 (Regular) +
+
+ Size + 16px +
+
+ Use Case + Paragraphs, Body +
+
+
+ +
+
Small / UI Elements
+
+ Configuration Β· Policy Β· Kubernetes Β· ArgoCD +
+
+
+ Family + Inter +
+
+ Weight + 500 (Medium) +
+
+ Size + 14px +
+
+ Use Case + Labels, Badges, UI +
+
+
+ +
+
Code / Monospace
+
+ stratumiops-h.svg
+ #6366F1 +
+
+
+ Family + Courier New +
+
+ Weight + 400 (Regular) +
+
+ Size + 13-14px +
+
+ Use Case + Code, Files, HEX +
+
+
+
+
+
+ +
+
+
+

Usage Guidelines

+

Best practices for brand consistency

+
+ +
+
+

πŸ“ Logo Sizing

+

+ Use horizontal variants for banners and headers. Vertical + variants work best for posters and vertical layouts. Maintain + minimum 20px clear space around all logos. Never distort, + rotate, or modify the aspect ratio. +

+
+ +
+

🎨 Color Usage

+

+ Primary Indigo (#6366F1) is the main brand color. Cyan (#22D3EE) + highlights active states and processor elements. Use gradients + for visual depth. Dark variants use white elements for optimal + dark mode visibility. +

+
+ +
+

πŸ”€ Typography

+

+ Use Inter font family from Google Fonts. Weight 800 for + display/hero text, 700 for headings, 600 for subheadings, 400 + for body text, and 500 for UI elements. Courier New monospace + for code and filenames. Line height 1.3-1.7 for readability. +

+
+ +
+

⚑ Animations

+

+ Animated variants include particle flows and pulsing equalizer + bars. Use animated versions for digital applications with + animation support. Static variants ensure compatibility with + print and static contexts. +

+
+ +
+

πŸŒ“ Dark Mode

+

+ Dark variants (-dark-h, -dark-v) are optimized for dark + backgrounds with enhanced glow effects. Use mono-white variants + for pure black backgrounds. Ensure WCAG AA contrast compliance. +

+
+ +
+

πŸ“± Digital Applications

+

+ All assets are SVG format for infinite scalability. Use favicon + variants (16Γ—16, 32Γ—32) for browser tabs. Social square variants + (1080Γ—1080) are optimized for profile pictures and thumbnails. +

+
+ +
+

πŸ–¨οΈ Print Production

+

+ Use static variants for print materials to ensure consistent + output. Monochrome black variants work for single-color prints. + Test on actual materials before production. Export to + high-resolution PNG/PDF when needed. +

+
+ +
+

β™Ώ Accessibility

+

+ All color combinations meet WCAG AA standards. Monochrome + variants ensure colorblind accessibility. Always provide + alt-text: "StratumIOps - Intelligent Infrastructure Operations". +

+
+ +
+

πŸ”§ Technical Usage

+

+ SVG files preserve animations and are infinitely scalable. Icons + use 512Γ—512 base dimensions for optimal rendering at all sizes. + Favicons are pre-optimized for browser rendering. +

+
+
+
+
+ + +
+
+
+

Variant Comparison

+

+ Complete overview of all 18 asset variations +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryVariantDimensionsFeaturesBest ForFilename
LogosHorizontal1200Γ—300pxAnimatedBanners, headersstratumiops-h.svg
Vertical400Γ—520pxAnimatedPosters, vertical UIstratumiops-v.svg
Horizontal Static1200Γ—300pxStatic barsPrint, documentsstratumiops-h-static.svg
Vertical Static400Γ—520pxStatic barsPrint, documentsstratumiops-v-static.svg
Dark Horizontal1200Γ—300pxDark BG, glowDark mode UIstratumiops-dark-h.svg
Dark Vertical400Γ—520pxDark BG, glowDark mode UIstratumiops-dark-v.svg
IconsMain Icon512Γ—512pxAnimated particlesApp icons, UIstratumiops-icon.svg
Static Icon512Γ—512pxStaticPrint, static UIstratumiops-icon-static.svg
Dark Icon512Γ—512pxDark BG, particlesDark mode appsstratumiops-icon-dark.svg
Dark Static Icon512Γ—512pxDark BG, staticDark mode printstratumiops-icon-dark-static.svg
MonochromeBlack Horizontal1200Γ—300pxBlack onlyPrint, docsstratumiops-mono-black-h.svg
Black Vertical400Γ—520pxBlack onlyPrint, docsstratumiops-mono-black-v.svg
White Horizontal1200Γ—300pxWhite onlyDark backgroundsstratumiops-mono-white-h.svg
White Vertical400Γ—520pxWhite onlyDark backgroundsstratumiops-mono-white-v.svg
SocialSocial Square Dark1080Γ—1080pxDark backgroundSocial profilesstratumiops-social-square-dark.svg
Social Square Light1080Γ—1080pxLight backgroundSocial profilesstratumiops-social-square-light.svg
Favicon 1616Γ—16pxSimplifiedBrowser tabsstratumiops-favicon-16.svg
Favicon 3232Γ—32pxSimplifiedBrowser tabsstratumiops-favicon-32.svg
+
+
+
+ + +
+
+

StratumIOps Branding System

+

+ 18 Total Assets β€’ 8 Logo Variants β€’ 4 Icon Variants β€’ 4 Monochrome β€’ 2 + Social β€’ 2 Favicons +

+

+ All assets in SVG format β€’ Fully scalable β€’ Animations preserved β€’ + Print-ready β€’ Accessible +

+

+ Last updated: 2026-01-22 β€’ Version 1.0 +

+
+
+ + + + diff --git a/assets/en/stratumiops-brand-strategy.md b/assets/en/stratumiops-brand-strategy.md new file mode 100644 index 0000000..268ef57 --- /dev/null +++ b/assets/en/stratumiops-brand-strategy.md @@ -0,0 +1,476 @@ +# StratumIOps: Brand Strategy and Business Model + +## Executive Summary + +| Aspect | Decision | +|---------|----------| +| **Name** | StratumIOps | +| **Pronunciation** | "Stratum-I-Ops" | +| **Tagline** | "Intelligent layers. Automated operations." | +| **Model** | Open Core + Enterprise + Services | +| **Target** | Mid-market tech companies (50-500 devs) | +| **Differentiator** | Only Rust-native integrated platform with AI | +| **Domain** | stratumiops.dev + +--- + +## 1. Name and Branding + +### Selected Name: StratumIOps + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•— β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ•— +β”‚ β–ˆβ–ˆβ•”β•β•β•β•β•β•šβ•β•β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β•šβ•β•β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ•‘ +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β–ˆβ–ˆβ–ˆβ–ˆβ•”β–ˆβ–ˆβ•‘ +β”‚ β•šβ•β•β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘β•šβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ β•šβ•β• β–ˆβ–ˆβ•‘ +β”‚ β•šβ•β•β•β•β•β•β• β•šβ•β• β•šβ•β• β•šβ•β•β•šβ•β• β•šβ•β• β•šβ•β• β•šβ•β•β•β•β•β• β•šβ•β• β•šβ•β• +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— +β”‚ β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β•β• +β”‚ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— +β”‚ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•β• β•šβ•β•β•β•β–ˆβ–ˆβ•‘ +β”‚ β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘ +β”‚ β•šβ•β•β•β•β•β• β•šβ•β• β•šβ•β•β•β•β•β•β• +β”‚ β”‚ +β”‚ "Intelligent layers. Automated operations." β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Rationale + +| Criterion | Evaluation | +|----------|------------| +| **Tech-feel** | "-Ops" suffix immediately tech-recognizable (GitOps, DevOps, MLOps, AIOps) | +| **Metaphor** | "Stratum" = layers. Each project is a layer of the stack | +| **Market fit** | Connects with Platform Engineering / DevOps market | +| **Scalability** | Allows adding more "layers" in the future | +| **Bilingual** | Works equally well in English and Spanish | +| **Availability** | stratumiops.dev / stratumiops.io likely available | +| **Differentiation** | No direct competitors with that name | +| **Memorable** | Easy to remember, not too long | + +### Alternatives Considered + +| Name | Concept | Reason for Rejection | +|--------|----------|-------------------| +| STRATUMIOPS (alone) | Geological layers | Lacks tech-feel, stratum.dev unavailable | +| NEXUS | Connection point | Overused in tech | +| Layerix | Layers + tech suffix | Invented, less recognizable | +| Forgelayer | Forge + layers | Longer, less memorable | +| DevSTRATUMIOPS | Dev + layers | Sounds generic | + +--- + +## 2. Brand Architecture + +### Product Hierarchy + +```text + StratumIOps + "Intelligent layers. + Automated operations." + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚StratumIOpsβ”‚ β”‚StratumIOpsβ”‚ β”‚ StratumIOps β”‚ + β”‚ Core β”‚ β”‚ Pro β”‚ β”‚ Enterprise β”‚ + β”‚ (OSS) β”‚ β”‚(License) β”‚ β”‚ (Support) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Products Under the Umbrella + +| Product | Origin | Public Name | Tagline | +|----------|--------|----------------|---------| +| Kogral | Knowledge Graph | StratumIOps/knowledge | "Capture and query team knowledge" | +| Vapora | Orchestration | StratumIOps/orchestrate | "Coordinate agents and workflows" | +| TypeDialog | Forms/Automation | StratumIOps/interact | "Universal forms and automation" | +| Provisioning | Infrastructure | StratumIOps/provision | "Infrastructure as typed code" | + +### Visualization + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps/knowledge ←── Kogral β”‚ +β”‚ "Capture and query team knowledge" β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ StratumIOps/orchestrate ←── Vapora β”‚ +β”‚ "Coordinate agents and development workflows" β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ StratumIOps/interact ←── TypeDialog β”‚ +β”‚ "Universal forms and automation" β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ StratumIOps/provision ←── Provisioning β”‚ +β”‚ "Infrastructure as typed code" β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 3. Taglines + +### Main Tagline + +> **"Intelligent layers. Automated operations."** + +### Context-Specific Variants + +| Context | Tagline | Use | +|----------|---------|-----| +| **Main** | "Intelligent layers. Automated operations." | General branding | +| **Technical** | "Stack intelligence. Automate everything." | Developer marketing | +| **Flow** | "From knowledge to deployment. Automated." | Presentations | +| **Benefits** | "Build smarter. Deploy faster." | Marketing, ads | +| **Enterprise** | "The full-stack operations platform" | B2B sales | +| **Pain point** | "Development without friction" | Landing pages | +| **Kogral-centric** | "Where your team's knowledge becomes code" | Content marketing | + +### Key Sales Message + +> "StratumIOps is the only platform that unifies knowledge management, agent orchestration, universal forms, and infrastructure-as-code in a coherent Rust stack. No more 10 disconnected tools. No more lost knowledge. No more uncontrolled LLM costs. One ecosystem. Real integration." + +--- + +## 4. Business Model + +### 4.1 Open Core + Enterprise + +#### FREE Tier (Open Source) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps FREE (OSS) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β€’ Kogral core (knowledge graph, CLI, MCP) β”‚ +β”‚ β€’ Vapora community (agents, basic routing) β”‚ +β”‚ β€’ TypeDialog core (6 backends, forms) β”‚ +β”‚ β€’ Provisioning community (AWS, basic orchestration) β”‚ +β”‚ β€’ Single-tenant, self-hosted β”‚ +β”‚ β€’ Community support (GitHub Issues) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +#### PRO Tier (License) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps PRO ($X/user/month) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Everything in Free + β”‚ +β”‚ β€’ Multi-tenant with SurrealDB scopes β”‚ +β”‚ β€’ Advanced budget enforcement (alerts, dashboards) β”‚ +β”‚ β€’ All cloud providers (GCP, Azure, Hetzner, UpCloud) β”‚ +β”‚ β€’ SSO (SAML, OIDC) β”‚ +β”‚ β€’ Priority support (48h SLA) β”‚ +β”‚ β€’ Automatic updates β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +#### ENTERPRISE Tier (Custom) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps ENTERPRISE (Custom pricing) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Everything in Pro + β”‚ +β”‚ β€’ Complete security layer (39K lines) β”‚ +β”‚ β€’ Audit logging (7 years, 5 export formats) β”‚ +β”‚ β€’ Advanced MFA (WebAuthn/FIDO2) β”‚ +β”‚ β€’ 5 KMS backends β”‚ +β”‚ β€’ Custom Cedar policies β”‚ +β”‚ β€’ Multi-party break-glass β”‚ +β”‚ β€’ Compliance packs (SOC2, HIPAA, GDPR) β”‚ +β”‚ β€’ Dedicated support (4h SLA) β”‚ +β”‚ β€’ Custom integrations β”‚ +β”‚ β€’ On-premise deployment assistance β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 4.2 Professional Services + +#### Implementation + +| Service | Duration | Reference Rate | +|----------|----------|-------------------| +| Initial assessment | 1-2 days | €2,000 - €4,000 | +| Basic implementation | 1 week | €8,000 - €15,000 | +| Enterprise implementation | 1 month | €30,000 - €60,000 | +| Migration from other tools | Variable | Custom | + +#### Consulting + +| Specialty | Rate/Day | +|--------------|------------| +| AI agent architecture | €1,500 | +| Knowledge management strategy | €1,500 | +| IaC modernization (Nickel) | €1,500 | +| Security audit | €2,000 | + +#### Premium Support + +| Modality | Monthly Rate | +|-----------|----------------| +| Dedicated engineer | €5,000 - €10,000 | +| 24/7 on-call support | €3,000 additional | +| Quarterly business reviews | Included in Enterprise | + +### 4.3 Training and Certification + +#### StratumIOps Academy - Courses + +| Course | Format | Price | +|-------|---------|--------| +| StratumIOps Fundamentals | Online, self-paced | €500 | +| StratumIOps for DevOps | 2 days, in-person | €1,200 | +| AI Agent Development with Vapora | 3 days | €1,800 | +| Nickel IaC Masterclass | 2 days | €1,200 | +| Enterprise Security Workshop | 1 day | €800 | + +#### Certifications + +| Certification | Exam | +|---------------|--------| +| StratumIOps Certified Developer (SOCD) | €300 | +| StratumIOps Certified Architect (SOCA) | €500 | +| StratumIOps Certified Administrator (SOCAD) | €400 | + +#### Corporate Training + +| Modality | Price | +|-----------|--------| +| Team training (up to 10 people) | €8,000/day | + +--- + +## 5. Reputation Strategy + +### 5.1 Thought Leadership + +| Channel | Content | +|-------|-----------| +| **Tech blog** (stratumiops.dev/blog) | Rust architecture deep dives, comparisons vs Terraform/LangChain, case studies | +| **YouTube** | Product demos, technical tutorials, conference talks | +| **Newsletter** | Release notes, industry insights, tips & tricks | +| **GitHub** | OSS contributions, example repos, community engagement | + +### 5.2 Community Building + +| Initiative | Purpose | +|------------|-----------| +| Discord/Slack community | Peer-to-peer support, feedback | +| GitHub Discussions | Technical Q&A, public RFCs | +| Virtual meetups (monthly) | Demos, AMA sessions | +| Conference presence | RustConf, KubeCon, local meetups | +| Open source contributions | Plugins, integrations, examples | + +### 5.3 Technical Credibility + +**Differentiators to communicate**: + +| Metric | Message | +|---------|---------| +| 195K lines of Rust | Performance and type-safety | +| 4,310+ tests | Quality and reliability | +| 39K lines of security | Enterprise-ready | +| Zero unsafe code | Security by design | +| 100% documented APIs | Developer experience | +| Full stack Rust | Technological consistency | + +--- + +## 6. Competitive Positioning + +### Positioning Map + +```text + ENTERPRISE FEATURES + β–² + β”‚ + Terraform/Pulumi β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + ● β”‚ β”‚StratumIOps β”‚ + β”‚ β”‚ (here) β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + ───────────────────────┼───────────────────────▢ + SINGLE TOOL β”‚ INTEGRATED PLATFORM + β”‚ + LangChain ● β”‚ + β”‚ + Notion ● β”‚ ● Obsidian + β”‚ + β”‚ + β–Ό + BASIC FEATURES +``` + +### Positioning Statement + +> "The only platform that integrates knowledge management, agent orchestration, forms automation, and IaC in a coherent Rust stack." + +### Comparison with Alternatives + +| Aspect | StratumIOps | Competition | +|---------|------------|-------------| +| **Stack** | End-to-end Rust | Python/JS/Go mix | +| **Config** | Nickel (typed) | YAML/JSON (runtime errors) | +| **Multi-tenant** | Native SurrealDB scopes | DIY isolation | +| **AI** | Native in all products | Retrofitted | +| **Self-hosted** | Complete | SaaS lock-in | +| **Agents** | Learning-based, budget control | Static chains | + +--- + +## 7. Financial Projection + +### Conservative Scenario + +#### Year 1: Establishment + +| Source | Calculation | Revenue | +|--------|---------|----------| +| Enterprise (5 customers) | 5 Γ— €50K avg | €250,000 | +| Pro (50 customers) | 50 Γ— €500/month Γ— 12 | €300,000 | +| Consulting | 200 days Γ— €1,500 | €300,000 | +| Training | 20 courses Γ— €5K avg | €100,000 | +| **TOTAL YEAR 1** | | **€950,000** | + +#### Year 2: Growth + +| Source | Calculation | Revenue | +|--------|---------|----------| +| Enterprise (15 customers) | 15 Γ— €50K avg | €750,000 | +| Pro (200 customers) | 200 Γ— €500/month Γ— 12 | €1,200,000 | +| Consulting | 300 days Γ— €1,500 | €450,000 | +| Training + Certs | | €200,000 | +| **TOTAL YEAR 2** | | **€2,600,000** | + +#### Year 3: Scale + +| Source | Calculation | Revenue | +|--------|---------|----------| +| Enterprise (40 customers) | 40 Γ— €50K avg | €2,000,000 | +| Pro (500 customers) | 500 Γ— €500/month Γ— 12 | €3,000,000 | +| Professional services | | €800,000 | +| Academy | | €400,000 | +| **TOTAL YEAR 3** | | **€6,200,000** | + +### Projection Summary + +```text +Year 1: €950K β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ +Year 2: €2.6M β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ +Year 3: €6.2M β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ +``` + +--- + +## 8. Go-to-Market Plan + +### Phase 1: Foundations (Months 1-3) + +- [ ] Register stratumiops.dev / stratumiops.io domain +- [ ] Create landing page with waitlist +- [ ] Publish StratumIOps/knowledge (Kogral) as OSS +- [ ] Write 5 technical blog posts +- [ ] Create Discord channel + +### Phase 2: Community (Months 4-6) + +- [ ] Publish StratumIOps/orchestrate (Vapora) as OSS +- [ ] Launch newsletter +- [ ] Participate in 2 conferences +- [ ] Reach 500 GitHub stars +- [ ] First 10 active users + +### Phase 3: Monetization (Months 7-12) + +- [ ] Launch StratumIOps Pro +- [ ] Close 3 Enterprise pilot customers +- [ ] Launch StratumIOps Academy +- [ ] Reach €500K ARR +- [ ] Hire first Customer Success + +--- + +## 9. Key Metrics (KPIs) + +### Product + +| Metric | Year 1 Target | +|---------|--------------| +| GitHub stars | 2,000 | +| Monthly active users (free) | 500 | +| Pro subscribers | 50 | +| Enterprise customers | 5 | + +### Revenue + +| Metric | Year 1 Target | +|---------|--------------| +| ARR | €950K | +| MRR growth | 15% month | +| Net Revenue Retention | 110% | +| CAC payback | < 12 months | + +### Community + +| Metric | Year 1 Target | +|---------|--------------| +| Discord members | 1,000 | +| Newsletter subscribers | 3,000 | +| Blog monthly visitors | 10,000 | +| Conference talks | 5 | + +--- + +## 10. Risks and Mitigation + +| Risk | Probability | Impact | Mitigation | +|--------|--------------|---------|------------| +| Better-funded competitor | High | High | Technical differentiation (Rust), OSS community | +| Slow Nickel adoption | Medium | Medium | Excellent documentation, migration paths | +| LLM provider dependency | High | Medium | Multi-provider support, local Ollama | +| Enterprise sales complexity | Medium | High | Initial mid-market focus, case studies | + +--- + +## 11. Visual Identity (Proposal) + +### Colors + +| Color | Hex | Use | +|-------|-----|-----| +| **Primary** | `#6366F1` (Indigo) | Logo, CTAs, accents | +| **Secondary** | `#22D3EE` (Cyan) | Highlights, gradients | +| **Dark** | `#0F172A` (Slate 900) | Backgrounds, text | +| **Light** | `#F8FAFC` (Slate 50) | Light backgrounds | + +### Logo Concept + +```text + ╔═══╗ + β•‘ S β•‘ ← Stacked layers (stratum) + ╠═══╣ + β•‘ O β•‘ ← Ops = gear/automation + β•šβ•β•β•β• +``` + +### Typography + +| Use | Font | +|-----|------| +| **Headings** | Inter (bold, clean, tech) | +| **Body** | Inter (regular) | +| **Code** | JetBrains Mono | + +--- + +*Document generated: 2026-01-22* +*Updated: 2026-01-22 (STRATUMIOPS β†’ StratumIOps)* +*Type: info (brand and business strategy)* +*Project: StratumIOps (portfolio name)* diff --git a/assets/en/stratumiops-branding-guide.md b/assets/en/stratumiops-branding-guide.md new file mode 100644 index 0000000..c9e0e2d --- /dev/null +++ b/assets/en/stratumiops-branding-guide.md @@ -0,0 +1,454 @@ +# StratumIOps: Branding Guide + +## 1. Brand Identity + +### Name + +| Element | Value | +|----------|-------| +| **Full name** | StratumIOps | +| **Pronunciation** | "Stratum-I-Ops" | +| **Abbreviation** | SIO (internal use) | +| **Domain** | stratumiops.dev | + +### Meaning + +```text +STRATUMIOPS + I + Ops + β”‚ β”‚ β”‚ + β”‚ β”‚ └── Operations: automation, DevOps, workflows + β”‚ β”‚ + β”‚ └── Intelligence: AI, intelligent agents, decisions + β”‚ + └── Layers: architecture layers, full stack +``` + +### Main Tagline + +> **"Intelligent layers. Automated operations."** + +### Alternative Taglines + +| Context | Tagline | +|----------|---------| +| Technical | "Stack intelligence. Automate everything." | +| Flow | "From knowledge to deployment. Automated." | +| Benefits | "Build smarter. Deploy faster." | +| Enterprise | "The full-stack operations platform." | + +--- + +## 2. Logo + +### Concept + +The logo represents: +- **Three horizontal layers**: Tiered architecture (Stratum) +- **Bright central node**: Intelligence connecting the layers (I) +- **Connection lines**: Data flow and operations (Ops) + +### Available Versions + +| File | Use | +|---------|-----| +| `stratumiops-logo.svg` | Primary, light background | +| `stratumiops-logo-dark.svg` | Dark background with background | +| `stratumiops-logo-minimal.svg` | Simplified version | +| `stratumiops-logo-monochrome.svg` | Single color | +| `stratumiops-logo-horizontal.svg` | With wordmark | + +### Logo Construction + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ +β”‚ β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“ ← Layer 1 β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ ← Connection β”‚ +β”‚ β–Ό β”‚ +β”‚ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓●▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ← Layer 2 + Node β”‚ +β”‚ β”‚ (cyan) β”‚ +β”‚ β”‚ ← Connection β”‚ +β”‚ β–Ό β”‚ +β”‚ β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“ ← Layer 3 β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Clear Space + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ +β”‚ β”Œβ”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ ═══════════════ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ ═══════●═══════ β”‚ β”‚ β”‚ +β”‚ β”‚Xβ”‚ ═══════════════ β”‚Xβ”‚ β”‚ X = node height +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + +Minimum space around logo = 1X (central node height) +``` + +### Minimum Sizes + +| Context | Minimum size | +|----------|---------------| +| Digital (screen) | 32px height | +| Print | 12mm height | +| Favicon | 16x16px (use simplified version) | + +--- + +## 3. Color Palette + +### Primary Colors + +| Name | Hex | RGB | Use | +|--------|-----|-----|-----| +| **Indigo 500** | `#6366F1` | 99, 102, 241 | Primary logo, primary CTAs | +| **Indigo 600** | `#4F46E5` | 79, 70, 229 | Hover states, dark variant | +| **Indigo 400** | `#818CF8` | 129, 140, 248 | Light backgrounds, highlights | + +### Secondary Colors (Accent) + +| Name | Hex | RGB | Use | +|--------|-----|-----|-----| +| **Cyan 400** | `#22D3EE` | 34, 211, 238 | Intelligent node, accents | +| **Cyan 500** | `#06B6D4` | 6, 182, 212 | Highlights, icons | +| **Cyan 300** | `#67E8F9` | 103, 232, 249 | Glow effects | + +### Neutral Colors + +| Name | Hex | RGB | Use | +|--------|-----|-----|-----| +| **Slate 900** | `#0F172A` | 15, 23, 42 | Primary text, dark backgrounds | +| **Slate 700** | `#334155` | 51, 65, 85 | Secondary text | +| **Slate 400** | `#94A3B8` | 148, 163, 184 | Tertiary text, placeholders | +| **Slate 200** | `#E2E8F0` | 226, 232, 240 | Borders, dividers | +| **Slate 50** | `#F8FAFC` | 248, 250, 252 | Light backgrounds | + +### Semantic Colors + +| Name | Hex | Use | +|--------|-----|-----| +| **Success** | `#22C55E` | Confirmations, OK states | +| **Warning** | `#F59E0B` | Alerts, cautions | +| **Error** | `#EF4444` | Errors, critical states | +| **Info** | `#3B82F6` | Information, tooltips | + +### Gradients + +```css +/* Primary logo gradient */ +.gradient-primary { + background: linear-gradient(135deg, #6366F1 0%, #4F46E5 100%); +} + +/* Intelligent node gradient */ +.gradient-node { + background: radial-gradient(circle, #22D3EE 0%, #06B6D4 100%); +} + +/* Hero background gradient */ +.gradient-hero { + background: linear-gradient(180deg, #0F172A 0%, #1E293B 100%); +} + +/* Accent gradient */ +.gradient-accent { + background: linear-gradient(90deg, #6366F1 0%, #22D3EE 100%); +} +``` + +--- + +## 4. Typography + +### Primary Font: Inter + +| Weight | Use | +|------|-----| +| **Inter Bold (700)** | Headings, main titles | +| **Inter SemiBold (600)** | Subtitles, emphasis | +| **Inter Medium (500)** | Labels, navigation | +| **Inter Regular (400)** | Body text | + +### Code Font: JetBrains Mono + +| Weight | Use | +|------|-----| +| **JetBrains Mono Regular** | Code, terminal, snippets | +| **JetBrains Mono Bold** | Highlighted code | + +### Typographic Scale + +| Name | Size | Line Height | Use | +|--------|--------|-------------|-----| +| **Display** | 48px / 3rem | 1.1 | Hero headlines | +| **H1** | 36px / 2.25rem | 1.2 | Page titles | +| **H2** | 30px / 1.875rem | 1.25 | Main sections | +| **H3** | 24px / 1.5rem | 1.3 | Subsections | +| **H4** | 20px / 1.25rem | 1.4 | Cards, minor titles | +| **Body Large** | 18px / 1.125rem | 1.6 | Lead text | +| **Body** | 16px / 1rem | 1.6 | Main text | +| **Body Small** | 14px / 0.875rem | 1.5 | Captions, metadata | +| **Code** | 14px / 0.875rem | 1.6 | Inline code | + +### CSS Variables + +```css +:root { + /* Font families */ + --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + --font-mono: 'JetBrains Mono', 'Fira Code', monospace; + + /* Font sizes */ + --text-xs: 0.75rem; + --text-sm: 0.875rem; + --text-base: 1rem; + --text-lg: 1.125rem; + --text-xl: 1.25rem; + --text-2xl: 1.5rem; + --text-3xl: 1.875rem; + --text-4xl: 2.25rem; + --text-5xl: 3rem; +} +``` + +--- + +## 5. Iconography + +### Style + +- **Type**: Outline icons (line, not filled) +- **Stroke width**: 1.5px - 2px +- **Corner radius**: Consistent with logo (rounded) +- **Base size**: 24x24px +- **Recommended set**: Lucide Icons, Heroicons (outline) + +### Product Icons + +| Product | Suggested Icon | +|----------|----------------| +| StratumIOps/knowledge | `book-open` + `brain` | +| StratumIOps/orchestrate | `workflow` + `bot` | +| StratumIOps/interact | `form-input` + `terminal` | +| StratumIOps/provision | `server` + `cloud` | + +--- + +## 6. UI Components + +### Buttons + +```css +/* Primary */ +.btn-primary { + background: linear-gradient(135deg, #6366F1 0%, #4F46E5 100%); + color: white; + border-radius: 8px; + padding: 12px 24px; + font-weight: 600; +} + +.btn-primary:hover { + background: linear-gradient(135deg, #4F46E5 0%, #4338CA 100%); +} + +/* Secondary */ +.btn-secondary { + background: transparent; + color: #6366F1; + border: 2px solid #6366F1; + border-radius: 8px; +} + +/* Ghost */ +.btn-ghost { + background: transparent; + color: #6366F1; +} +``` + +### Cards + +```css +.card { + background: white; + border-radius: 12px; + border: 1px solid #E2E8F0; + box-shadow: 0 1px 3px rgba(0,0,0,0.1); +} + +.card-dark { + background: #1E293B; + border: 1px solid #334155; +} +``` + +### Inputs + +```css +.input { + border: 1px solid #E2E8F0; + border-radius: 8px; + padding: 12px 16px; + font-size: 16px; +} + +.input:focus { + border-color: #6366F1; + box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.1); +} +``` + +--- + +## 7. Applications + +### Website + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ [Logo] Products Pricing Docs Blog [Sign In] β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ StratumIOps β”‚ +β”‚ β”‚ +β”‚ Intelligent layers. β”‚ +β”‚ Automated operations. β”‚ +β”‚ β”‚ +β”‚ [Get Started] [View Demo] β”‚ +β”‚ β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚Knowledgeβ”‚ β”‚Orchestr.β”‚ β”‚ Interactβ”‚ β”‚Provisionβ”‚ β”‚ +β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ +β”‚ β”‚ ═●═ β”‚ β”‚ ═●═ β”‚ β”‚ ═●═ β”‚ β”‚ ═●═ β”‚ β”‚ +β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Documentation + +- Background: Slate 50 (#F8FAFC) +- Sidebar: White with Slate 200 border +- Code blocks: Slate 900 with syntax highlighting +- Headers: Indigo 600 + +### Presentations + +- Dark template: Slate 900 background, white text +- Light template: White background, Slate 900 text +- Accent on all slides: Cyan for highlights + +--- + +## 8. Incorrect Usage + +### Don't Do This + +```text +❌ Change logo colors +❌ Rotate the logo +❌ Add effects (shadows, extra outlines) +❌ Stretch or compress disproportionately +❌ Use on backgrounds that reduce contrast +❌ Separate the node from the layers +❌ Change wordmark typography +❌ Use full version when space is very small +``` + +### Allowed Backgrounds + +| Background | Logo Version | +|-------|------------------| +| White / Light | Primary logo (colors) | +| Slate 900 / Black | Dark version logo | +| Indigo (brand color) | White monochromatic logo | +| Photographs | Only if sufficient contrast | + +--- + +## 9. Voice and Tone + +### Brand Personality + +| Attribute | Description | +|----------|-------------| +| **Intelligent** | We know the space, we speak with technical authority | +| **Direct** | No beating around the bush, straight to the point | +| **Accessible** | Technical but not intimidating | +| **Reliable** | Enterprise-ready, serious, professional | +| **Innovative** | Rust, Nickel, native AI - we're ahead | + +### Copy Examples + +**Yes**: +- "Deploy infrastructure with type-safe confidence." +- "Your agents learn. Your costs drop." +- "Knowledge that your AI actually uses." + +**No**: +- "Revolutionary AI-powered paradigm shift!" (hype) +- "Super easy to use!" (vague) +- "The best platform ever!" (empty superlatives) + +--- + +## 10. Digital Assets + +### Logo Files + +``` +.coder/ +β”œβ”€β”€ 2026-01-22-stratumiops-logo.svg # Primary +β”œβ”€β”€ 2026-01-22-stratumiops-logo-dark.svg # Dark background +β”œβ”€β”€ 2026-01-22-stratumiops-logo-minimal.svg # Simplified +β”œβ”€β”€ 2026-01-22-stratumiops-logo-monochrome.svg # Single color +└── 2026-01-22-stratumiops-logo-horizontal.svg # With wordmark +``` + +### Required Exports + +``` +/brand/ +β”œβ”€β”€ logo/ +β”‚ β”œβ”€β”€ svg/ # All SVGs +β”‚ β”œβ”€β”€ png/ # 64, 128, 256, 512, 1024px +β”‚ β”œβ”€β”€ favicon/ # ico, png 16/32/48 +β”‚ └── social/ # Open Graph, Twitter cards +β”œβ”€β”€ colors/ +β”‚ └── palette.css # CSS variables +β”œβ”€β”€ fonts/ +β”‚ └── README.md # Links to Inter and JetBrains Mono +└── templates/ + β”œβ”€β”€ presentation/ # Slide templates + └── documents/ # Letterhead, etc. +``` + +--- + +## 11. Contact and Resources + +| Resource | URL | +|---------|-----| +| Website | stratumiops.dev | +| Docs | docs.stratumiops.dev | +| GitHub | github.com/stratumiops | +| Twitter/X | @stratumiops | +| Discord | discord.gg/stratumiops | + +--- + +*Branding Guide v1.0* +*Document generated: 2026-01-22* +*Project: StratumIOps* diff --git a/assets/en/stratumiops-logo-prompts.md b/assets/en/stratumiops-logo-prompts.md new file mode 100644 index 0000000..c063320 --- /dev/null +++ b/assets/en/stratumiops-logo-prompts.md @@ -0,0 +1,220 @@ +# StratumIOps: Logo Generation Prompts + +## Logo Concept + +| Element | Visual Meaning | +|----------|-------------------| +| **Stratum** | Stacked layers, geological strata, tiered architecture | +| **I** | Intelligence, central node, neural connection | +| **Ops** | Gears, flow, automation, continuous cycle | + +--- + +## AI Prompts (Midjourney/DALL-E/Ideogram) + +### Main Prompt (Abstract Geometric) + +``` +A modern minimalist tech logo for "StratumIOps", featuring three horizontal +stacked layers with a glowing neural node in the center representing +intelligence. Clean geometric design with subtle gradient from indigo (#6366F1) +to cyan (#22D3EE). The layers suggest depth and architecture. Professional +SaaS company aesthetic. Vector style, scalable, works on dark and light +backgrounds. No text in the logo mark. +``` + +### Variant 1 (Layers + Circuit) + +``` +Minimalist logo icon: three horizontal parallel lines stacked vertically +representing layers/strata, with a small glowing circuit node connecting +them in the center. Color palette: indigo to cyan gradient. Tech startup +aesthetic, clean lines, geometric precision. Silicon Valley style. +Suitable for app icon and favicon. Vector art, flat design with subtle +depth. Dark background version. +``` + +### Variant 2 (Hexagonal) + +``` +Hexagonal tech logo with three internal horizontal divisions representing +layers. A bright intelligent core at the center. Modern DevOps platform +branding. Colors: deep indigo (#4F46E5) transitioning to electric cyan +(#06B6D4). Minimalist, professional, suitable for enterprise software. +Clean vector style, no gradients on the shape, gradient only on accent. +``` + +### Variant 3 (Isometric) + +``` +Isometric 3D logo showing three stacked platform layers with a glowing +intelligence core. Modern cloud infrastructure aesthetic. Clean geometric +shapes, professional tech company style. Primary color indigo with cyan +accent highlights. Suitable for both light and dark modes. Minimal, +sophisticated, enterprise-ready design. +``` + +### Variant 4 (Stylized S) + +``` +Stylized letter "S" logo made of three horizontal stacked segments +representing layers/strata. A small glowing dot in the center segment +representing the "I" of intelligence. Modern tech company aesthetic. +Indigo (#6366F1) as primary color with cyan (#22D3EE) accent on the +intelligence node. Clean, minimal, vector style. Works as app icon. +``` + +### Variant 5 (Data Flow) + +``` +Abstract logo showing data flowing through three horizontal layers, +with a central processing node glowing with intelligence. Represents +automated operations across architectural layers. Tech platform aesthetic. +Indigo to cyan color scheme. Minimalist, professional, suitable for +developer tools company. Vector art, clean lines. +``` + +--- + +## Prompts for Specific Versions + +### App Icon / Favicon + +``` +Square app icon design: simplified three-layer stack with glowing center +node. Must be recognizable at 16x16 pixels. High contrast, indigo +background with cyan/white accent. Minimal detail, bold shapes. +Tech platform favicon style. +``` + +### Monochrome Version + +``` +Single color logo version: three stacked horizontal bars with center +connection point. Works in pure white, pure black, or single brand color. +No gradients, pure vector shapes. Suitable for watermarks, embossing, +single-color printing. +``` + +### Horizontal Version (with Wordmark) + +``` +Horizontal logo lockup: geometric icon of three stacked layers with +intelligent core on the left, "StratumIOps" wordmark on the right in +clean sans-serif font (Inter or similar). Professional tech company +style. Indigo primary with cyan accent. Balanced spacing. +``` + +--- + +## Technical Specifications for Designer + +### Base Dimensions + +| Use | Size | Format | +|-----|--------|---------| +| Logo mark (icon) | 512x512 px | SVG, PNG | +| Favicon | 32x32, 16x16 px | ICO, PNG | +| App icon | 1024x1024 px | PNG | +| Social media | 400x400 px | PNG | +| Horizontal lockup | 1200x300 px | SVG, PNG | + +### Colors to Specify + +| Color | Hex | RGB | Use | +|-------|-----|-----|-----| +| Primary Indigo | `#6366F1` | 99, 102, 241 | Primary logo | +| Deep Indigo | `#4F46E5` | 79, 70, 229 | Dark variant | +| Cyan Accent | `#22D3EE` | 34, 211, 238 | Intelligent node | +| Electric Cyan | `#06B6D4` | 6, 182, 212 | Highlights | +| Dark Background | `#0F172A` | 15, 23, 42 | Dark background | +| Light Background | `#F8FAFC` | 248, 250, 252 | Light background | + +### Delivery Requirements + +``` +β–‘ Logo mark SVG (scalable vector) +β–‘ Logo mark PNG (512px, 1024px, 2048px) +β–‘ Favicon ICO (16px, 32px, 48px) +β–‘ App icon PNG (1024px with rounded corners) +β–‘ Horizontal lockup SVG +β–‘ Horizontal lockup PNG (multiple sizes) +β–‘ Monochrome version (white, black) +β–‘ Dark background version +β–‘ Light background version +β–‘ Editable source file (Figma/AI/Sketch) +``` + +--- + +## Visual Reference Concepts + +### Mood Board Keywords + +``` +- Layered architecture +- Neural network node +- Cloud infrastructure +- DevOps pipeline +- Data flow visualization +- Geometric minimalism +- Enterprise SaaS +- Developer tools +- Platform engineering +- Intelligent automation +``` + +### Reference Logos (Similar Style) + +- **Vercel** - Geometric simplicity, triangle +- **Linear** - Minimalism, clean lines +- **Supabase** - Subtle gradients, tech feel +- **Prisma** - Geometric shapes, depth +- **Planetscale** - Layers, movement +- **Railway** - Simple, memorable, tech + +--- + +## ASCII Concept Examples + +### Concept 1: Layers with Central Node + +``` + ════════════════ + ════════●═══════ ← Intelligent node (cyan) + ════════════════ +``` + +### Concept 2: Stylized S + +``` + ╔═══════════╗ + ╠═════●═════╣ ← I of Intelligence + β•šβ•β•β•β•β•β•β•β•β•β•β•β• +``` + +### Concept 3: Hexagonal + +``` + ╱────────╲ + ╱──────────╲ + β”‚ ● β”‚ ← Intelligent core + ╲──────────╱ + ╲────────╱ +``` + +### Concept 4: Isometric + +``` + ▁▁▁▁▁▁▁ + β•± β•² + β–• ● ▏ ← Node + β•²_______β•± + β–”β–”β–”β–”β–”β–”β–” +``` + +--- + +*Document generated: 2026-01-22* +*Project: StratumIOps* +*Use: AI logo generation or designer brief* diff --git a/assets/es/stratumiops-brand-strategy.md b/assets/es/stratumiops-brand-strategy.md new file mode 100644 index 0000000..56906fd --- /dev/null +++ b/assets/es/stratumiops-brand-strategy.md @@ -0,0 +1,476 @@ +# StratumIOps: Estrategia de Marca y Modelo de Negocio + +## Resumen Ejecutivo + +| Aspecto | DecisiΓ³n | +|---------|----------| +| **Nombre** | StratumIOps | +| **PronunciaciΓ³n** | "Stratum-I-Ops" | +| **Eslogan** | "Intelligent layers. Automated operations." | +| **Modelo** | Open Core + Enterprise + Services | +| **Target** | Mid-market tech companies (50-500 devs) | +| **Diferenciador** | Único platform integrado Rust-native con IA | +| **Dominio** | stratumiops.dev + +--- + +## 1. Nombre y Branding + +### Nombre Seleccionado: StratumIOps + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•— β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ•— +β”‚ β–ˆβ–ˆβ•”β•β•β•β•β•β•šβ•β•β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β•šβ•β•β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ•‘ +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β–ˆβ–ˆβ–ˆβ–ˆβ•”β–ˆβ–ˆβ•‘ +β”‚ β•šβ•β•β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘β•šβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘ β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ β•šβ•β• β–ˆβ–ˆβ•‘ +β”‚ β•šβ•β•β•β•β•β•β• β•šβ•β• β•šβ•β• β•šβ•β•β•šβ•β• β•šβ•β• β•šβ•β• β•šβ•β•β•β•β•β• β•šβ•β• β•šβ•β• +β”‚ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— +β”‚ β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β•β• +β”‚ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— +β”‚ β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•β• β•šβ•β•β•β•β–ˆβ–ˆβ•‘ +β”‚ β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘ +β”‚ β•šβ•β•β•β•β•β• β•šβ•β• β•šβ•β•β•β•β•β•β• +β”‚ β”‚ +β”‚ "Intelligent layers. Automated operations." β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### JustificaciΓ³n + +| Criterio | EvaluaciΓ³n | +|----------|------------| +| **Tech-feel** | Sufijo "-Ops" inmediatamente tecnolΓ³gico (GitOps, DevOps, MLOps, AIOps) | +| **MetΓ‘fora** | "Stratum" = capas. Cada proyecto es una capa del stack | +| **Market fit** | Conecta con Platform Engineering / DevOps market | +| **Escalabilidad** | Permite aΓ±adir mΓ‘s "capas" en el futuro | +| **BilingΓΌe** | Funciona igual en inglΓ©s y espaΓ±ol | +| **Disponibilidad** | stratumiops.dev / stratumiops.io probablemente disponibles | +| **DiferenciaciΓ³n** | No hay competidores directos con ese nombre | +| **Memorable** | FΓ‘cil de recordar, no muy largo | + +### Alternativas Consideradas + +| Nombre | Concepto | RazΓ³n de Descarte | +|--------|----------|-------------------| +| STRATUMIOPS (solo) | Capas geolΓ³gicas | Falta tech-feel, stratum.dev no disponible | +| NEXUS | Punto de conexiΓ³n | Muy usado en tech | +| Layerix | Layers + suffix tech | Inventado, menos reconocible | +| Forgelayer | Forge + layers | MΓ‘s largo, menos memorable | +| DevSTRATUMIOPS | Dev + layers | Suena genΓ©rico | + +--- + +## 2. Arquitectura de Marca + +### JerarquΓ­a de Productos + +```text + StratumIOps + "Intelligent layers. + Automated operations." + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚StratumIOpsβ”‚ β”‚StratumIOpsβ”‚ β”‚ StratumIOps β”‚ + β”‚ Core β”‚ β”‚ Pro β”‚ β”‚ Enterprise β”‚ + β”‚ (OSS) β”‚ β”‚(License) β”‚ β”‚ (Support) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Productos Bajo el Paraguas + +| Producto | Origen | Nombre PΓΊblico | Tagline | +|----------|--------|----------------|---------| +| Kogral | Knowledge Graph | StratumIOps/knowledge | "Capture and query team knowledge" | +| Vapora | Orchestration | StratumIOps/orchestrate | "Coordinate agents and workflows" | +| TypeDialog | Forms/Automation | StratumIOps/interact | "Universal forms and automation" | +| Provisioning | Infrastructure | StratumIOps/provision | "Infrastructure as typed code" | + +### VisualizaciΓ³n + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps/knowledge ←── Kogral β”‚ +β”‚ "Capture and query team knowledge" β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ StratumIOps/orchestrate ←── Vapora β”‚ +β”‚ "Coordinate agents and development workflows" β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ StratumIOps/interact ←── TypeDialog β”‚ +β”‚ "Universal forms and automation" β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ StratumIOps/provision ←── Provisioning β”‚ +β”‚ "Infrastructure as typed code" β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 3. EslΓ³ganes + +### Principal + +> **"Intelligent layers. Automated operations."** + +### Variantes por Contexto + +| Contexto | Eslogan | Uso | +|----------|---------|-----| +| **Principal** | "Intelligent layers. Automated operations." | Branding general | +| **TΓ©cnico** | "Stack intelligence. Automate everything." | Developer marketing | +| **Flujo** | "From knowledge to deployment. Automated." | Presentaciones | +| **Beneficios** | "Build smarter. Deploy faster." | Marketing, ads | +| **Enterprise** | "The full-stack operations platform" | Ventas B2B | +| **Pain point** | "Development without friction" | Landing pages | +| **Kogral-centric** | "Where your team's knowledge becomes code" | Content marketing | + +### Mensaje Clave para Ventas + +> "StratumIOps es la ΓΊnica plataforma que unifica knowledge management, agent orchestration, universal forms, y infrastructure-as-code en un stack coherente de Rust. No mΓ‘s 10 herramientas desconectadas. No mΓ‘s conocimiento perdido. No mΓ‘s costos LLM descontrolados. Un ecosistema. IntegraciΓ³n real." + +--- + +## 4. Modelo de Negocio + +### 4.1 Open Core + Enterprise + +#### Tier FREE (Open Source) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps FREE (OSS) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β€’ Kogral core (knowledge graph, CLI, MCP) β”‚ +β”‚ β€’ Vapora community (agents, basic routing) β”‚ +β”‚ β€’ TypeDialog core (6 backends, forms) β”‚ +β”‚ β€’ Provisioning community (AWS, basic orchestration) β”‚ +β”‚ β€’ Single-tenant, self-hosted β”‚ +β”‚ β€’ Community support (GitHub Issues) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +#### Tier PRO (Licencia) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps PRO ($X/user/month) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Todo de Free + β”‚ +β”‚ β€’ Multi-tenant con SurrealDB scopes β”‚ +β”‚ β€’ Budget enforcement avanzado (alertas, dashboards) β”‚ +β”‚ β€’ Todos los cloud providers (GCP, Azure, Hetzner, UpCloud) β”‚ +β”‚ β€’ SSO (SAML, OIDC) β”‚ +β”‚ β€’ Priority support (48h SLA) β”‚ +β”‚ β€’ Actualizaciones automΓ‘ticas β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +#### Tier ENTERPRISE (Custom) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ StratumIOps ENTERPRISE (Custom pricing) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Todo de Pro + β”‚ +β”‚ β€’ Security layer completo (39K lΓ­neas) β”‚ +β”‚ β€’ Audit logging (7 aΓ±os, 5 formatos export) β”‚ +β”‚ β€’ MFA avanzado (WebAuthn/FIDO2) β”‚ +β”‚ β€’ 5 KMS backends β”‚ +β”‚ β€’ Cedar policies custom β”‚ +β”‚ β€’ Break-glass multi-party β”‚ +β”‚ β€’ Compliance packs (SOC2, HIPAA, GDPR) β”‚ +β”‚ β€’ Dedicated support (4h SLA) β”‚ +β”‚ β€’ Custom integrations β”‚ +β”‚ β€’ On-premise deployment assistance β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 4.2 Servicios Profesionales + +#### ImplementaciΓ³n + +| Servicio | DuraciΓ³n | Tarifa Referencia | +|----------|----------|-------------------| +| Assessment inicial | 1-2 dΓ­as | €2,000 - €4,000 | +| ImplementaciΓ³n bΓ‘sica | 1 semana | €8,000 - €15,000 | +| ImplementaciΓ³n enterprise | 1 mes | €30,000 - €60,000 | +| MigraciΓ³n desde otras tools | Variable | Custom | + +#### ConsultorΓ­a + +| Especialidad | Tarifa/DΓ­a | +|--------------|------------| +| Arquitectura de agentes IA | €1,500 | +| Knowledge management strategy | €1,500 | +| IaC modernization (Nickel) | €1,500 | +| Security audit | €2,000 | + +#### Soporte Premium + +| Modalidad | Tarifa Mensual | +|-----------|----------------| +| Dedicated engineer | €5,000 - €10,000 | +| On-call support 24/7 | €3,000 adicional | +| Quarterly business reviews | Incluido en Enterprise | + +### 4.3 Training y CertificaciΓ³n + +#### StratumIOps Academy - Cursos + +| Curso | Formato | Precio | +|-------|---------|--------| +| StratumIOps Fundamentals | Online, self-paced | €500 | +| StratumIOps for DevOps | 2 dΓ­as, presencial | €1,200 | +| AI Agent Development con Vapora | 3 dΓ­as | €1,800 | +| Nickel IaC Masterclass | 2 dΓ­as | €1,200 | +| Enterprise Security Workshop | 1 dΓ­a | €800 | + +#### Certificaciones + +| CertificaciΓ³n | Examen | +|---------------|--------| +| StratumIOps Certified Developer (SOCD) | €300 | +| StratumIOps Certified Architect (SOCA) | €500 | +| StratumIOps Certified Administrator (SOCAD) | €400 | + +#### Corporate Training + +| Modalidad | Precio | +|-----------|--------| +| Team training (hasta 10 personas) | €8,000/dΓ­a | + +--- + +## 5. Estrategia de ReputaciΓ³n + +### 5.1 Thought Leadership + +| Canal | Contenido | +|-------|-----------| +| **Blog tΓ©cnico** (stratumiops.dev/blog) | Deep dives arquitectura Rust, comparativas vs Terraform/LangChain, case studies | +| **YouTube** | Demos de productos, tutoriales tΓ©cnicos, conference talks | +| **Newsletter** | Release notes, industry insights, tips & tricks | +| **GitHub** | OSS contributions, example repos, community engagement | + +### 5.2 Community Building + +| Iniciativa | PropΓ³sito | +|------------|-----------| +| Discord/Slack community | Soporte peer-to-peer, feedback | +| GitHub Discussions | Q&A tΓ©cnico, RFCs pΓΊblicos | +| Meetups virtuales (mensuales) | Demos, AMA sessions | +| Conference presence | RustConf, KubeCon, local meetups | +| Open source contributions | Plugins, integrations, examples | + +### 5.3 Credibilidad TΓ©cnica + +**Diferenciadores para comunicar**: + +| MΓ©trica | Mensaje | +|---------|---------| +| 195K lΓ­neas de Rust | Performance y type-safety | +| 4,310+ tests | Calidad y confiabilidad | +| 39K lΓ­neas de seguridad | Enterprise-ready | +| Zero unsafe code | Security by design | +| 100% documented APIs | Developer experience | +| Full stack Rust | Consistencia tecnolΓ³gica | + +--- + +## 6. Posicionamiento Competitivo + +### Mapa de Posicionamiento + +```text + ENTERPRISE FEATURES + β–² + β”‚ + Terraform/Pulumi β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + ● β”‚ β”‚StratumIOps β”‚ + β”‚ β”‚ (aquΓ­) β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + ───────────────────────┼───────────────────────▢ + SINGLE TOOL β”‚ INTEGRATED PLATFORM + β”‚ + LangChain ● β”‚ + β”‚ + Notion ● β”‚ ● Obsidian + β”‚ + β”‚ + β–Ό + BASIC FEATURES +``` + +### Mensaje de Posicionamiento + +> "El ΓΊnico platform que integra knowledge management, agent orchestration, forms automation, y IaC en un stack coherente de Rust." + +### Comparativa con Alternativas + +| Aspecto | StratumIOps | Competencia | +|---------|------------|-------------| +| **Stack** | Rust end-to-end | Python/JS/Go mix | +| **Config** | Nickel (typed) | YAML/JSON (runtime errors) | +| **Multi-tenant** | SurrealDB scopes nativo | DIY isolation | +| **IA** | Nativa en todos los productos | Retrofitted | +| **Self-hosted** | Completo | SaaS lock-in | +| **Agentes** | Learning-based, budget control | Chains estΓ‘ticos | + +--- + +## 7. ProyecciΓ³n Financiera + +### Escenario Conservador + +#### AΓ±o 1: Establecimiento + +| Fuente | CΓ‘lculo | Ingresos | +|--------|---------|----------| +| Enterprise (5 clientes) | 5 Γ— €50K avg | €250,000 | +| Pro (50 clientes) | 50 Γ— €500/mes Γ— 12 | €300,000 | +| ConsultorΓ­a | 200 dΓ­as Γ— €1,500 | €300,000 | +| Training | 20 cursos Γ— €5K avg | €100,000 | +| **TOTAL AΓ‘O 1** | | **€950,000** | + +#### AΓ±o 2: Crecimiento + +| Fuente | CΓ‘lculo | Ingresos | +|--------|---------|----------| +| Enterprise (15 clientes) | 15 Γ— €50K avg | €750,000 | +| Pro (200 clientes) | 200 Γ— €500/mes Γ— 12 | €1,200,000 | +| ConsultorΓ­a | 300 dΓ­as Γ— €1,500 | €450,000 | +| Training + Certs | | €200,000 | +| **TOTAL AΓ‘O 2** | | **€2,600,000** | + +#### AΓ±o 3: Escala + +| Fuente | CΓ‘lculo | Ingresos | +|--------|---------|----------| +| Enterprise (40 clientes) | 40 Γ— €50K avg | €2,000,000 | +| Pro (500 clientes) | 500 Γ— €500/mes Γ— 12 | €3,000,000 | +| Servicios profesionales | | €800,000 | +| Academy | | €400,000 | +| **TOTAL AΓ‘O 3** | | **€6,200,000** | + +### Resumen ProyecciΓ³n + +```text +AΓ±o 1: €950K β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ +AΓ±o 2: €2.6M β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ +AΓ±o 3: €6.2M β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ +``` + +--- + +## 8. Plan de Go-to-Market + +### Fase 1: Foundations (Meses 1-3) + +- [ ] Registrar dominio stratumiops.dev / stratumiops.io +- [ ] Crear landing page con waitlist +- [ ] Publicar StratumIOps/knowledge (Kogral) como OSS +- [ ] Escribir 5 blog posts tΓ©cnicos +- [ ] Crear canal Discord + +### Fase 2: Community (Meses 4-6) + +- [ ] Publicar StratumIOps/orchestrate (Vapora) como OSS +- [ ] Lanzar newsletter +- [ ] Participar en 2 conferencias +- [ ] Alcanzar 500 estrellas GitHub +- [ ] Primeros 10 usuarios activos + +### Fase 3: Monetization (Meses 7-12) + +- [ ] Lanzar StratumIOps Pro +- [ ] Cerrar 3 clientes Enterprise pilot +- [ ] Lanzar StratumIOps Academy +- [ ] Alcanzar €500K ARR +- [ ] Contratar primer Customer Success + +--- + +## 9. MΓ©tricas Clave (KPIs) + +### Product + +| MΓ©trica | Target AΓ±o 1 | +|---------|--------------| +| GitHub stars | 2,000 | +| Monthly active users (free) | 500 | +| Pro subscribers | 50 | +| Enterprise customers | 5 | + +### Revenue + +| MΓ©trica | Target AΓ±o 1 | +|---------|--------------| +| ARR | €950K | +| MRR growth | 15% mes | +| Net Revenue Retention | 110% | +| CAC payback | < 12 meses | + +### Community + +| MΓ©trica | Target AΓ±o 1 | +|---------|--------------| +| Discord members | 1,000 | +| Newsletter subscribers | 3,000 | +| Blog monthly visitors | 10,000 | +| Conference talks | 5 | + +--- + +## 10. Riesgos y MitigaciΓ³n + +| Riesgo | Probabilidad | Impacto | MitigaciΓ³n | +|--------|--------------|---------|------------| +| Competidor con mΓ‘s recursos | Alta | Alto | DiferenciaciΓ³n tΓ©cnica (Rust), comunidad OSS | +| AdopciΓ³n lenta de Nickel | Media | Medio | DocumentaciΓ³n excelente, migration paths | +| Dependencia de LLM providers | Alta | Medio | Soporte multi-provider, Ollama local | +| Complejidad de venta enterprise | Media | Alto | Focus inicial en mid-market, case studies | + +--- + +## 11. Identidad Visual (Propuesta) + +### Colores + +| Color | Hex | Uso | +|-------|-----|-----| +| **Primary** | `#6366F1` (Indigo) | Logo, CTAs, accents | +| **Secondary** | `#22D3EE` (Cyan) | Highlights, gradients | +| **Dark** | `#0F172A` (Slate 900) | Backgrounds, text | +| **Light** | `#F8FAFC` (Slate 50) | Light backgrounds | + +### Logo Concept + +```text + ╔═══╗ + β•‘ S β•‘ ← Capas apiladas (stratum) + ╠═══╣ + β•‘ O β•‘ ← Ops = engranaje/automation + β•šβ•β•β•β• +``` + +### Typography + +| Uso | Font | +|-----|------| +| **Headings** | Inter (bold, clean, tech) | +| **Body** | Inter (regular) | +| **Code** | JetBrains Mono | + +--- + +*Documento generado: 2026-01-22* +*Actualizado: 2026-01-22 (STRATUMIOPS β†’ StratumIOps)* +*Tipo: info (estrategia de marca y negocio)* +*Proyecto: StratumIOps (nombre del portfolio)* diff --git a/assets/es/stratumiops-branding-guide.md b/assets/es/stratumiops-branding-guide.md new file mode 100644 index 0000000..f917b29 --- /dev/null +++ b/assets/es/stratumiops-branding-guide.md @@ -0,0 +1,454 @@ +# StratumIOps: GuΓ­a de Branding + +## 1. Identidad de Marca + +### Nombre + +| Elemento | Valor | +|----------|-------| +| **Nombre completo** | StratumIOps | +| **PronunciaciΓ³n** | "Stratum-I-Ops" | +| **AbreviaciΓ³n** | SIO (uso interno) | +| **Dominio** | stratumiops.dev | + +### Significado + +```text +STRATUMIOPS + I + Ops + β”‚ β”‚ β”‚ + β”‚ β”‚ └── Operations: automatizaciΓ³n, DevOps, flujos + β”‚ β”‚ + β”‚ └── Intelligence: IA, agentes inteligentes, decisiones + β”‚ + └── Layers: capas de arquitectura, stack completo +``` + +### Eslogan Principal + +> **"Intelligent layers. Automated operations."** + +### EslΓ³ganes Alternativos + +| Contexto | Eslogan | +|----------|---------| +| TΓ©cnico | "Stack intelligence. Automate everything." | +| Flujo | "From knowledge to deployment. Automated." | +| Beneficios | "Build smarter. Deploy faster." | +| Enterprise | "The full-stack operations platform." | + +--- + +## 2. Logo + +### Concepto + +El logo representa: +- **Tres capas horizontales**: Arquitectura en niveles (Stratum) +- **Nodo central brillante**: Inteligencia conectando las capas (I) +- **LΓ­neas de conexiΓ³n**: Flujo de datos y operaciones (Ops) + +### Versiones Disponibles + +| Archivo | Uso | +|---------|-----| +| `stratumiops-logo.svg` | Principal, fondo claro | +| `stratumiops-logo-dark.svg` | Fondo oscuro con background | +| `stratumiops-logo-minimal.svg` | VersiΓ³n simplificada | +| `stratumiops-logo-monochrome.svg` | Un solo color | +| `stratumiops-logo-horizontal.svg` | Con wordmark | + +### ConstrucciΓ³n del Logo + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ +β”‚ β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“ ← Capa 1 β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ ← ConexiΓ³n β”‚ +β”‚ β–Ό β”‚ +β”‚ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓●▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ← Capa 2 + Nodo β”‚ +β”‚ β”‚ (cyan) β”‚ +β”‚ β”‚ ← ConexiΓ³n β”‚ +β”‚ β–Ό β”‚ +β”‚ β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“ ← Capa 3 β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Área de ProtecciΓ³n + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ +β”‚ β”Œβ”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ ═══════════════ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ ═══════●═══════ β”‚ β”‚ β”‚ +β”‚ β”‚Xβ”‚ ═══════════════ β”‚Xβ”‚ β”‚ X = altura del nodo +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + +Espacio mΓ­nimo alrededor del logo = 1X (altura del nodo central) +``` + +### TamaΓ±os MΓ­nimos + +| Contexto | TamaΓ±o mΓ­nimo | +|----------|---------------| +| Digital (pantalla) | 32px altura | +| Impreso | 12mm altura | +| Favicon | 16x16px (usar versiΓ³n simplificada) | + +--- + +## 3. Paleta de Colores + +### Colores Primarios + +| Nombre | Hex | RGB | Uso | +|--------|-----|-----|-----| +| **Indigo 500** | `#6366F1` | 99, 102, 241 | Logo principal, CTAs primarios | +| **Indigo 600** | `#4F46E5` | 79, 70, 229 | Hover states, variante oscura | +| **Indigo 400** | `#818CF8` | 129, 140, 248 | Fondos claros, highlights | + +### Colores Secundarios (Accent) + +| Nombre | Hex | RGB | Uso | +|--------|-----|-----|-----| +| **Cyan 400** | `#22D3EE` | 34, 211, 238 | Nodo inteligente, accents | +| **Cyan 500** | `#06B6D4` | 6, 182, 212 | Highlights, iconos | +| **Cyan 300** | `#67E8F9` | 103, 232, 249 | Glow effects | + +### Colores Neutrales + +| Nombre | Hex | RGB | Uso | +|--------|-----|-----|-----| +| **Slate 900** | `#0F172A` | 15, 23, 42 | Texto principal, fondos dark | +| **Slate 700** | `#334155` | 51, 65, 85 | Texto secundario | +| **Slate 400** | `#94A3B8` | 148, 163, 184 | Texto terciario, placeholders | +| **Slate 200** | `#E2E8F0` | 226, 232, 240 | Bordes, divisores | +| **Slate 50** | `#F8FAFC` | 248, 250, 252 | Fondos claros | + +### Colores SemΓ‘nticos + +| Nombre | Hex | Uso | +|--------|-----|-----| +| **Success** | `#22C55E` | Confirmaciones, estados OK | +| **Warning** | `#F59E0B` | Alertas, precauciones | +| **Error** | `#EF4444` | Errores, estados crΓ­ticos | +| **Info** | `#3B82F6` | InformaciΓ³n, tooltips | + +### Gradientes + +```css +/* Gradiente principal del logo */ +.gradient-primary { + background: linear-gradient(135deg, #6366F1 0%, #4F46E5 100%); +} + +/* Gradiente del nodo inteligente */ +.gradient-node { + background: radial-gradient(circle, #22D3EE 0%, #06B6D4 100%); +} + +/* Gradiente para fondos hero */ +.gradient-hero { + background: linear-gradient(180deg, #0F172A 0%, #1E293B 100%); +} + +/* Gradiente accent */ +.gradient-accent { + background: linear-gradient(90deg, #6366F1 0%, #22D3EE 100%); +} +``` + +--- + +## 4. TipografΓ­a + +### Fuente Principal: Inter + +| Peso | Uso | +|------|-----| +| **Inter Bold (700)** | Headings, tΓ­tulos principales | +| **Inter SemiBold (600)** | SubtΓ­tulos, Γ©nfasis | +| **Inter Medium (500)** | Labels, navegaciΓ³n | +| **Inter Regular (400)** | Cuerpo de texto | + +### Fuente CΓ³digo: JetBrains Mono + +| Peso | Uso | +|------|-----| +| **JetBrains Mono Regular** | CΓ³digo, terminal, snippets | +| **JetBrains Mono Bold** | CΓ³digo destacado | + +### Escala TipogrΓ‘fica + +| Nombre | TamaΓ±o | Line Height | Uso | +|--------|--------|-------------|-----| +| **Display** | 48px / 3rem | 1.1 | Hero headlines | +| **H1** | 36px / 2.25rem | 1.2 | TΓ­tulos de pΓ‘gina | +| **H2** | 30px / 1.875rem | 1.25 | Secciones principales | +| **H3** | 24px / 1.5rem | 1.3 | Subsecciones | +| **H4** | 20px / 1.25rem | 1.4 | Cards, tΓ­tulos menores | +| **Body Large** | 18px / 1.125rem | 1.6 | Lead text | +| **Body** | 16px / 1rem | 1.6 | Texto principal | +| **Body Small** | 14px / 0.875rem | 1.5 | Captions, metadata | +| **Code** | 14px / 0.875rem | 1.6 | CΓ³digo inline | + +### CSS Variables + +```css +:root { + /* Font families */ + --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + --font-mono: 'JetBrains Mono', 'Fira Code', monospace; + + /* Font sizes */ + --text-xs: 0.75rem; + --text-sm: 0.875rem; + --text-base: 1rem; + --text-lg: 1.125rem; + --text-xl: 1.25rem; + --text-2xl: 1.5rem; + --text-3xl: 1.875rem; + --text-4xl: 2.25rem; + --text-5xl: 3rem; +} +``` + +--- + +## 5. IconografΓ­a + +### Estilo + +- **Tipo**: Outline icons (lΓ­nea, no filled) +- **Stroke width**: 1.5px - 2px +- **Corner radius**: Consistente con el logo (redondeado) +- **TamaΓ±o base**: 24x24px +- **Set recomendado**: Lucide Icons, Heroicons (outline) + +### Iconos del Producto + +| Producto | Icono Sugerido | +|----------|----------------| +| StratumIOps/knowledge | `book-open` + `brain` | +| StratumIOps/orchestrate | `workflow` + `bot` | +| StratumIOps/interact | `form-input` + `terminal` | +| StratumIOps/provision | `server` + `cloud` | + +--- + +## 6. Componentes UI + +### Botones + +```css +/* Primario */ +.btn-primary { + background: linear-gradient(135deg, #6366F1 0%, #4F46E5 100%); + color: white; + border-radius: 8px; + padding: 12px 24px; + font-weight: 600; +} + +.btn-primary:hover { + background: linear-gradient(135deg, #4F46E5 0%, #4338CA 100%); +} + +/* Secundario */ +.btn-secondary { + background: transparent; + color: #6366F1; + border: 2px solid #6366F1; + border-radius: 8px; +} + +/* Ghost */ +.btn-ghost { + background: transparent; + color: #6366F1; +} +``` + +### Cards + +```css +.card { + background: white; + border-radius: 12px; + border: 1px solid #E2E8F0; + box-shadow: 0 1px 3px rgba(0,0,0,0.1); +} + +.card-dark { + background: #1E293B; + border: 1px solid #334155; +} +``` + +### Inputs + +```css +.input { + border: 1px solid #E2E8F0; + border-radius: 8px; + padding: 12px 16px; + font-size: 16px; +} + +.input:focus { + border-color: #6366F1; + box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.1); +} +``` + +--- + +## 7. Aplicaciones + +### Website + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ [Logo] Products Pricing Docs Blog [Sign In] β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ StratumIOps β”‚ +β”‚ β”‚ +β”‚ Intelligent layers. β”‚ +β”‚ Automated operations. β”‚ +β”‚ β”‚ +β”‚ [Get Started] [View Demo] β”‚ +β”‚ β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚Knowledgeβ”‚ β”‚Orchestr.β”‚ β”‚ Interactβ”‚ β”‚Provisionβ”‚ β”‚ +β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ +β”‚ β”‚ ═●═ β”‚ β”‚ ═●═ β”‚ β”‚ ═●═ β”‚ β”‚ ═●═ β”‚ β”‚ +β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ ════ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### DocumentaciΓ³n + +- Fondo: Slate 50 (#F8FAFC) +- Sidebar: White con borde Slate 200 +- Code blocks: Slate 900 con syntax highlighting +- Headers: Indigo 600 + +### Presentaciones + +- Template dark: Slate 900 fondo, texto blanco +- Template light: White fondo, texto Slate 900 +- Accent en todos los slides: Cyan para highlights + +--- + +## 8. Uso Incorrecto + +### No Hacer + +```text +❌ Cambiar los colores del logo +❌ Rotar el logo +❌ AΓ±adir efectos (sombras, outlines extra) +❌ Estirar o comprimir desproporcionadamente +❌ Usar sobre fondos que reduzcan contraste +❌ Separar el nodo de las capas +❌ Cambiar la tipografΓ­a del wordmark +❌ Usar versiΓ³n completa cuando el espacio es muy pequeΓ±o +``` + +### Fondos Permitidos + +| Fondo | VersiΓ³n del Logo | +|-------|------------------| +| Blanco / Claro | Logo principal (colores) | +| Slate 900 / Negro | Logo dark version | +| Indigo (brand color) | Logo monocromΓ‘tico blanco | +| FotografΓ­as | Solo si hay suficiente contraste | + +--- + +## 9. Tono de Voz + +### Personalidad de Marca + +| Atributo | DescripciΓ³n | +|----------|-------------| +| **Inteligente** | Conocemos el espacio, hablamos con autoridad tΓ©cnica | +| **Directo** | Sin rodeos, vamos al grano | +| **Accesible** | TΓ©cnico pero no intimidante | +| **Confiable** | Enterprise-ready, serio, profesional | +| **Innovador** | Rust, Nickel, IA nativa - estamos adelante | + +### Ejemplos de Copy + +**SΓ­**: +- "Deploy infrastructure with type-safe confidence." +- "Your agents learn. Your costs drop." +- "Knowledge that your AI actually uses." + +**No**: +- "Revolutionary AI-powered paradigm shift!" (hype) +- "Super easy to use!" (vago) +- "The best platform ever!" (superlativos vacΓ­os) + +--- + +## 10. Assets Digitales + +### Archivos de Logo + +``` +.coder/ +β”œβ”€β”€ 2026-01-22-stratumiops-logo.svg # Principal +β”œβ”€β”€ 2026-01-22-stratumiops-logo-dark.svg # Fondo oscuro +β”œβ”€β”€ 2026-01-22-stratumiops-logo-minimal.svg # Simplificado +β”œβ”€β”€ 2026-01-22-stratumiops-logo-monochrome.svg # Un color +└── 2026-01-22-stratumiops-logo-horizontal.svg # Con wordmark +``` + +### Exportaciones Necesarias + +``` +/brand/ +β”œβ”€β”€ logo/ +β”‚ β”œβ”€β”€ svg/ # Todos los SVG +β”‚ β”œβ”€β”€ png/ # 64, 128, 256, 512, 1024px +β”‚ β”œβ”€β”€ favicon/ # ico, png 16/32/48 +β”‚ └── social/ # Open Graph, Twitter cards +β”œβ”€β”€ colors/ +β”‚ └── palette.css # Variables CSS +β”œβ”€β”€ fonts/ +β”‚ └── README.md # Links a Inter y JetBrains Mono +└── templates/ + β”œβ”€β”€ presentation/ # Slides templates + └── documents/ # Letterhead, etc. +``` + +--- + +## 11. Contacto y Recursos + +| Recurso | URL | +|---------|-----| +| Website | stratumiops.dev | +| Docs | docs.stratumiops.dev | +| GitHub | github.com/stratumiops | +| Twitter/X | @stratumiops | +| Discord | discord.gg/stratumiops | + +--- + +*GuΓ­a de Branding v1.0* +*Documento generado: 2026-01-22* +*Proyecto: StratumIOps* diff --git a/assets/es/stratumiops-logo-prompts.md b/assets/es/stratumiops-logo-prompts.md new file mode 100644 index 0000000..4e953f4 --- /dev/null +++ b/assets/es/stratumiops-logo-prompts.md @@ -0,0 +1,220 @@ +# StratumIOps: Prompts para GeneraciΓ³n de Logo + +## Concepto del Logo + +| Elemento | Significado Visual | +|----------|-------------------| +| **Stratum** | Capas apiladas, estratos geolΓ³gicos, arquitectura en niveles | +| **I** | Inteligencia, nodo central, conexiΓ³n neuronal | +| **Ops** | Engranajes, flujo, automatizaciΓ³n, ciclo continuo | + +--- + +## Prompts para IA (Midjourney/DALL-E/Ideogram) + +### Prompt Principal (Abstracto GeomΓ©trico) + +``` +A modern minimalist tech logo for "StratumIOps", featuring three horizontal +stacked layers with a glowing neural node in the center representing +intelligence. Clean geometric design with subtle gradient from indigo (#6366F1) +to cyan (#22D3EE). The layers suggest depth and architecture. Professional +SaaS company aesthetic. Vector style, scalable, works on dark and light +backgrounds. No text in the logo mark. +``` + +### Prompt Variante 1 (Capas + Circuito) + +``` +Minimalist logo icon: three horizontal parallel lines stacked vertically +representing layers/strata, with a small glowing circuit node connecting +them in the center. Color palette: indigo to cyan gradient. Tech startup +aesthetic, clean lines, geometric precision. Silicon Valley style. +Suitable for app icon and favicon. Vector art, flat design with subtle +depth. Dark background version. +``` + +### Prompt Variante 2 (Hexagonal) + +``` +Hexagonal tech logo with three internal horizontal divisions representing +layers. A bright intelligent core at the center. Modern DevOps platform +branding. Colors: deep indigo (#4F46E5) transitioning to electric cyan +(#06B6D4). Minimalist, professional, suitable for enterprise software. +Clean vector style, no gradients on the shape, gradient only on accent. +``` + +### Prompt Variante 3 (IsomΓ©trico) + +``` +Isometric 3D logo showing three stacked platform layers with a glowing +intelligence core. Modern cloud infrastructure aesthetic. Clean geometric +shapes, professional tech company style. Primary color indigo with cyan +accent highlights. Suitable for both light and dark modes. Minimal, +sophisticated, enterprise-ready design. +``` + +### Prompt Variante 4 (Letra S Estilizada) + +``` +Stylized letter "S" logo made of three horizontal stacked segments +representing layers/strata. A small glowing dot in the center segment +representing the "I" of intelligence. Modern tech company aesthetic. +Indigo (#6366F1) as primary color with cyan (#22D3EE) accent on the +intelligence node. Clean, minimal, vector style. Works as app icon. +``` + +### Prompt Variante 5 (Flujo de Datos) + +``` +Abstract logo showing data flowing through three horizontal layers, +with a central processing node glowing with intelligence. Represents +automated operations across architectural layers. Tech platform aesthetic. +Indigo to cyan color scheme. Minimalist, professional, suitable for +developer tools company. Vector art, clean lines. +``` + +--- + +## Prompts para Versiones EspecΓ­ficas + +### App Icon / Favicon + +``` +Square app icon design: simplified three-layer stack with glowing center +node. Must be recognizable at 16x16 pixels. High contrast, indigo +background with cyan/white accent. Minimal detail, bold shapes. +Tech platform favicon style. +``` + +### VersiΓ³n MonocromΓ‘tica + +``` +Single color logo version: three stacked horizontal bars with center +connection point. Works in pure white, pure black, or single brand color. +No gradients, pure vector shapes. Suitable for watermarks, embossing, +single-color printing. +``` + +### VersiΓ³n Horizontal (con Wordmark) + +``` +Horizontal logo lockup: geometric icon of three stacked layers with +intelligent core on the left, "StratumIOps" wordmark on the right in +clean sans-serif font (Inter or similar). Professional tech company +style. Indigo primary with cyan accent. Balanced spacing. +``` + +--- + +## Especificaciones TΓ©cnicas para el DiseΓ±ador + +### Dimensiones Base + +| Uso | TamaΓ±o | Formato | +|-----|--------|---------| +| Logo mark (icon) | 512x512 px | SVG, PNG | +| Favicon | 32x32, 16x16 px | ICO, PNG | +| App icon | 1024x1024 px | PNG | +| Social media | 400x400 px | PNG | +| Horizontal lockup | 1200x300 px | SVG, PNG | + +### Colores para Especificar + +| Color | Hex | RGB | Uso | +|-------|-----|-----|-----| +| Primary Indigo | `#6366F1` | 99, 102, 241 | Logo principal | +| Deep Indigo | `#4F46E5` | 79, 70, 229 | Variante oscura | +| Cyan Accent | `#22D3EE` | 34, 211, 238 | Nodo inteligente | +| Electric Cyan | `#06B6D4` | 6, 182, 212 | Highlights | +| Dark Background | `#0F172A` | 15, 23, 42 | Fondo oscuro | +| Light Background | `#F8FAFC` | 248, 250, 252 | Fondo claro | + +### Requisitos de Entrega + +``` +β–‘ Logo mark SVG (vector escalable) +β–‘ Logo mark PNG (512px, 1024px, 2048px) +β–‘ Favicon ICO (16px, 32px, 48px) +β–‘ App icon PNG (1024px con esquinas redondeadas) +β–‘ Horizontal lockup SVG +β–‘ Horizontal lockup PNG (mΓΊltiples tamaΓ±os) +β–‘ VersiΓ³n monocromΓ‘tica (blanco, negro) +β–‘ VersiΓ³n sobre fondo oscuro +β–‘ VersiΓ³n sobre fondo claro +β–‘ Archivo fuente editable (Figma/AI/Sketch) +``` + +--- + +## Conceptos Visuales de Referencia + +### Mood Board Keywords + +``` +- Layered architecture +- Neural network node +- Cloud infrastructure +- DevOps pipeline +- Data flow visualization +- Geometric minimalism +- Enterprise SaaS +- Developer tools +- Platform engineering +- Intelligent automation +``` + +### Logos de Referencia (Estilo Similar) + +- **Vercel** - Simplicidad geomΓ©trica, triΓ‘ngulo +- **Linear** - Minimalismo, lΓ­neas limpias +- **Supabase** - Gradientes sutiles, tech feel +- **Prisma** - Formas geomΓ©tricas, profundidad +- **Planetscale** - Capas, movimiento +- **Railway** - Simple, memorable, tech + +--- + +## Ejemplos de Concepto ASCII + +### Concepto 1: Capas con Nodo Central + +``` + ════════════════ + ════════●═══════ ← Nodo inteligente (cyan) + ════════════════ +``` + +### Concepto 2: S Estilizada + +``` + ╔═══════════╗ + ╠═════●═════╣ ← I de Intelligence + β•šβ•β•β•β•β•β•β•β•β•β•β•β• +``` + +### Concepto 3: Hexagonal + +``` + ╱────────╲ + ╱──────────╲ + β”‚ ● β”‚ ← Core inteligente + ╲──────────╱ + ╲────────╱ +``` + +### Concepto 4: IsomΓ©trico + +``` + ▁▁▁▁▁▁▁ + β•± β•² + β–• ● ▏ ← Nodo + β•²_______β•± + β–”β–”β–”β–”β–”β–”β–” +``` + +--- + +*Documento generado: 2026-01-22* +*Proyecto: StratumIOps* +*Uso: GeneraciΓ³n de logo con IA o brief para diseΓ±ador* diff --git a/assets/logos/stratumiops-dark-h.svg b/assets/logos/stratumiops-dark-h.svg new file mode 100644 index 0000000..6c19ac7 --- /dev/null +++ b/assets/logos/stratumiops-dark-h.svg @@ -0,0 +1,77 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + diff --git a/assets/logos/stratumiops-dark-v.svg b/assets/logos/stratumiops-dark-v.svg new file mode 100644 index 0000000..e597833 --- /dev/null +++ b/assets/logos/stratumiops-dark-v.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + diff --git a/assets/logos/stratumiops-favicon-16.svg b/assets/logos/stratumiops-favicon-16.svg new file mode 100644 index 0000000..7e4a50e --- /dev/null +++ b/assets/logos/stratumiops-favicon-16.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/logos/stratumiops-favicon-32.svg b/assets/logos/stratumiops-favicon-32.svg new file mode 100644 index 0000000..2f94ec1 --- /dev/null +++ b/assets/logos/stratumiops-favicon-32.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/logos/stratumiops-h-static.svg b/assets/logos/stratumiops-h-static.svg new file mode 100644 index 0000000..515ce7d --- /dev/null +++ b/assets/logos/stratumiops-h-static.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + diff --git a/assets/logos/stratumiops-h.svg b/assets/logos/stratumiops-h.svg new file mode 100644 index 0000000..44e711e --- /dev/null +++ b/assets/logos/stratumiops-h.svg @@ -0,0 +1,191 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + + + + + + + + + + diff --git a/assets/logos/stratumiops-icon-dark-static.svg b/assets/logos/stratumiops-icon-dark-static.svg new file mode 100644 index 0000000..206f136 --- /dev/null +++ b/assets/logos/stratumiops-icon-dark-static.svg @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/logos/stratumiops-icon-dark.svg b/assets/logos/stratumiops-icon-dark.svg new file mode 100644 index 0000000..3656784 --- /dev/null +++ b/assets/logos/stratumiops-icon-dark.svg @@ -0,0 +1,176 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/logos/stratumiops-icon-static.svg b/assets/logos/stratumiops-icon-static.svg new file mode 100644 index 0000000..7b54ce1 --- /dev/null +++ b/assets/logos/stratumiops-icon-static.svg @@ -0,0 +1,61 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/logos/stratumiops-icon.svg b/assets/logos/stratumiops-icon.svg new file mode 100644 index 0000000..b232052 --- /dev/null +++ b/assets/logos/stratumiops-icon.svg @@ -0,0 +1,177 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/logos/stratumiops-mono-black-h.svg b/assets/logos/stratumiops-mono-black-h.svg new file mode 100644 index 0000000..32e9241 --- /dev/null +++ b/assets/logos/stratumiops-mono-black-h.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + diff --git a/assets/logos/stratumiops-mono-black-v.svg b/assets/logos/stratumiops-mono-black-v.svg new file mode 100644 index 0000000..2b02ed2 --- /dev/null +++ b/assets/logos/stratumiops-mono-black-v.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + diff --git a/assets/logos/stratumiops-mono-white-h.svg b/assets/logos/stratumiops-mono-white-h.svg new file mode 100644 index 0000000..0625063 --- /dev/null +++ b/assets/logos/stratumiops-mono-white-h.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + diff --git a/assets/logos/stratumiops-mono-white-v.svg b/assets/logos/stratumiops-mono-white-v.svg new file mode 100644 index 0000000..fac328c --- /dev/null +++ b/assets/logos/stratumiops-mono-white-v.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + diff --git a/assets/logos/stratumiops-social-square-dark.svg b/assets/logos/stratumiops-social-square-dark.svg new file mode 100644 index 0000000..09506f9 --- /dev/null +++ b/assets/logos/stratumiops-social-square-dark.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + diff --git a/assets/logos/stratumiops-social-square-light.svg b/assets/logos/stratumiops-social-square-light.svg new file mode 100644 index 0000000..8e5657f --- /dev/null +++ b/assets/logos/stratumiops-social-square-light.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + diff --git a/assets/logos/stratumiops-v-static.svg b/assets/logos/stratumiops-v-static.svg new file mode 100644 index 0000000..9a5a4a6 --- /dev/null +++ b/assets/logos/stratumiops-v-static.svg @@ -0,0 +1,77 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + diff --git a/assets/logos/stratumiops-v.svg b/assets/logos/stratumiops-v.svg new file mode 100644 index 0000000..b2407df --- /dev/null +++ b/assets/logos/stratumiops-v.svg @@ -0,0 +1,180 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + + + + diff --git a/assets/stratumiops-h.svg b/assets/stratumiops-h.svg new file mode 100644 index 0000000..ceab77b --- /dev/null +++ b/assets/stratumiops-h.svg @@ -0,0 +1,185 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + + + + + + + + + diff --git a/assets/web/README.md b/assets/web/README.md new file mode 100644 index 0000000..7aeabcf --- /dev/null +++ b/assets/web/README.md @@ -0,0 +1,265 @@ +# StratumIOps Web Assets + +Web-based landing page and static content for StratumIOps. + +## Directory Structure + +```text +assets/web/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ index.html # Source HTML (readable) +β”‚ └── stratumiops.svg # Logo for landing page +β”œβ”€β”€ index.html # Minified/Production HTML +β”œβ”€β”€ stratumiops.svg # Logo for landing page +└── README.md # This file +``` + +## Files + +### `src/index.html` - Source Version + +- **Purpose**: Development and maintenance +- **Content**: + - Full formatting and indentation + - Inline CSS and JavaScript + - Bilingual (English/Spanish) content + - Language-aware dynamic switching + - Infrastructure operations showcase + - Technology stack display + - Core components grid + +**Use for:** + +- Editing content +- Understanding structure +- Version control +- Making translation updates + +### `index.html` - Production Version + +- **Purpose**: Served to browsers (fast loading) +- **Optimizations**: + - Removed all comments + - Compressed CSS (removed spaces, combined rules) + - Minified JavaScript (single line) + - Removed whitespace between tags + - Preserved all functionality + +**Use for:** + +- Production web server +- CDN distribution +- Browser caching +- Fast load times + +### `stratumiops.svg` - Logo + +- **Purpose**: Landing page branding +- **Source**: Copy of `../logos/stratumiops-h.svg` (horizontal logo) +- **Dimensions**: 1200Γ—300px +- **Features**: Animated particles, flows, and processor + +## How to Use + +### Development + +Edit `src/index.html`: + +```bash +# Edit source file +nano assets/web/src/index.html + +# Regenerate minified version (script below) +``` + +### Update Minified Version + +When you update `src/index.html`, regenerate `index.html`: + +```bash +# Using Perl minification script +cd /path/to/stratumiops +perl -e ' +use strict; +use warnings; + +open(my $fh, "<", "assets/web/src/index.html") or die $!; +my $content = do { local $/; <$fh> }; +close($fh); + +# Remove comments +$content =~ s///gs; + +# Compress whitespace in style tags +$content =~ s/(]*>)(.*?)(<\/style>)/ + my $before = $1; + my $style = $2; + my $after = $3; + $style =~ s{\/\*.*?\*\/}{}gs; + $style =~ s{\s+}{ }gs; + $style =~ s{\s*([{}:;,>+~])\s*}{$1}gs; + $before . $style . $after; +/gies; + +# Compress whitespace in script tags +$content =~ s/(]*>)(.*?)(<\/script>)/ + my $before = $1; + my $script = $2; + my $after = $3; + $script =~ s{\/\/.*$}{}gm; + $script =~ s{\s+}{ }gs; + $script =~ s{\s*([{}();,])\s*}{$1}gs; + $before . $script . $after; +/gies; + +# Remove whitespace between tags +$content =~ s/>\s+", "assets/web/index.html") or die $!; +print $out $content; +close($out); + +print "βœ… Minified version created\n"; +' +``` + +### Deployment + +Serve `index.html` from your web server: + +```bash +# Using Rust +cargo install static-web-server +static-web-server -d assets/web/ + +# Using Python +python3 -m http.server --directory assets/web + +# Using Node.js +npx http-server assets/web + +# Using nginx +# Point root to assets/web/ +# Serve index.html as default +``` + +## Features + +βœ… **Responsive Design** + +- Mobile-first approach +- Flexbox and Grid layouts +- Media queries for mobile + +βœ… **Performance** + +- Inline CSS (no separate requests) +- Inline JavaScript (no blocking external scripts) +- Minimal dependencies (no frameworks) +- Optimized minified size + +βœ… **Bilingual** + +- English and Spanish +- LocalStorage persistence +- Data attributes for translations +- Dynamic language switching + +βœ… **Modern CSS** + +- CSS Gradients +- Animations (fadeInUp) +- Hover effects +- Grid and Flexbox layouts + +βœ… **Styling** + +- StratumIOps color scheme (Indigo/Cyan) +- Gradient backgrounds +- Inter font family +- Smooth transitions + +## Content Sections + +1. **Hero** - Title, tagline, logo, version badge +2. **Problems** - 4 infrastructure problems StratumIOps solves +3. **How It Works** - Feature overview (Configuration as Code, GitOps, Multi-Cloud) +4. **Technology Stack** - Tech badges (Rust, Nickel, KCL, Terraform, K8s, etc.) +5. **Core Components** - Component showcase (12 components) +6. **CTA** - Call-to-action button +7. **Footer** - Credits and tagline + +## Translations + +All text content is bilingual. Edit data attributes in `src/index.html`: + +```html + +Infrastructure +``` + +The JavaScript automatically updates based on selected language. + +## Color Scheme + +StratumIOps branding colors: + +- **Primary Indigo**: `#6366F1` - Main brand color +- **Secondary Indigo**: `#4F46E5` - Gradients and depth +- **Cyan Accent**: `#22D3EE` - Highlights and active states +- **Cyan Dark**: `#06B6D4` - Processor elements +- **Slate**: `#94a3b8` - Secondary text +- **Dark Background**: `#0F172A` - Main background + +## Maintenance + +- Source edits go in `src/index.html` +- Regenerate `index.html` when source changes +- Both files are versioned in git +- Keep them in sync + +## Git Workflow + +```bash +# Edit source +git add assets/web/src/index.html +git add assets/web/index.html +git commit -m "Update landing page content" +git push +``` + +## File Sizes + +Source and production versions: + +| File | Type | +|------|------| +| `src/index.html` | Source (readable, formatted) | +| `index.html` | Production (minified, optimized) | +| `stratumiops.svg` | 4-6KB (animated horizontal logo) | + +## Version Information + +- **Last Updated**: 2026-01-22 +- **Version**: 0.1.0 +- **Format**: HTML5 + CSS3 + ES6 +- **Compatibility**: All modern browsers +- **Languages**: English, Spanish + +## Technology Focus + +**StratumIOps** landing page emphasizes: + +- πŸ—οΈ Infrastructure as Code +- πŸ”„ GitOps workflows +- ☁️ Multi-cloud orchestration +- πŸ“‹ Configuration management +- πŸ”’ Policy enforcement +- πŸ“Š Observability and monitoring + +--- + +**Last Updated**: 2026-01-22 +**Version**: 0.1.0 (matches StratumIOps release) diff --git a/assets/web/index.html b/assets/web/index.html new file mode 100644 index 0000000..f2a29e9 --- /dev/null +++ b/assets/web/index.html @@ -0,0 +1 @@ + StratumIOps
βœ… v0.1.0
StratumIOps - Infrastructure Operations

Infrastructure Operations Ecosystem

Five Projects

Infrastructure operations, AI agent orchestration, knowledge management, secrets management, and configuration generation.
100% Rust. Zero compromises.

The 4 Problems It Solves

01

Scattered Knowledge

  • Decisions in Slack
  • Guidelines in wikis
  • Patterns in docsβ€”all disconnected
  • Kogral unifies with git-native markdown + MCP
02

Uncontrolled LLM Costs

  • No visibility on AI spending per team
  • No budget limits or controls
  • Vapora: real-time budgets
  • Automatic fallback to cheaper providers
  • Expertise-based agent routing
03

Fragile YAML Configuration

  • Runtime errors from untyped config
  • No validation before deployment
  • Provisioning: Nickel with pre-runtime validation
  • TypeDialog: forms with contract validation
04

Static Cryptography

  • No preparation for quantum threats
  • Locked into single crypto library
  • SecretumVault: production post-quantum crypto
  • ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204)
  • 4 pluggable backends (OpenSSL, OQS, AWS-LC, RustCrypto)

Ecosystem Projects

πŸ€–

Vapora

  • AI agent orchestration with learning
  • Agents improve from experience
  • Automatic budget fallback
  • NATS JetStream coordination
  • 13 crates, 218 tests, 50K LOC
🧠

Kogral

  • Knowledge graph with MCP for Claude Code
  • 6 node types: Notes, ADRs, Guidelines, Patterns, Journals, Executions
  • Git-native markdown storage
  • Semantic search with embeddings
  • 3 crates, 56 tests, 15K LOC
πŸ“‹

TypeDialog

  • 6 backends: CLI, TUI, Web, AI, Agent, Prov-gen
  • One TOML definition for all interfaces
  • Nickel contract validation
  • Conditional fields & repeating groups
  • 8 crates, 3,818 tests, 90K LOC
☁️

Provisioning

  • Declarative IaC with Nickel + AI-assisted generation
  • Multi-cloud: AWS, UpCloud, Local (LXD)
  • RAG with 1,200+ domain docs
  • MCP server for natural language queries
  • Orchestrator with automatic rollback
  • 15+ crates, 218 tests, 40K LOC
πŸ”’

SecretumVault

  • Post-quantum crypto: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204)
  • 4 crypto backends: OpenSSL, OQS, AWS-LC, RustCrypto
  • 4 storage backends: Filesystem, etcd, SurrealDB, PostgreSQL
  • 4 secrets engines: KV, Transit, PKI, Database
  • Shamir Secret Sharing for unsealing
  • 1 crate, 50+ tests, 11K LOC

Technology Stack

Rust Edition 2021NickelNushellSurrealDBNATS JetStreamAxumLeptos WASMRatatui TUIOpenTelemetryPrometheusetcdPostgreSQLOpenSSLOQS (Post-Quantum)Cedar Policy

Ecosystem Metrics

40+ Rust CratesModular architecture
4,360+ TestsQuality assurance
~206K LOCProduction-ready code
0 Clippy WarningsCode quality
0 Unsafe BlocksMemory safety
100% Doc CoveragePublic APIs documented
4 Crypto BackendsCryptographic agility
4 Storage BackendsFlexible persistence
6 TypeDialog BackendsMulti-interface forms
14+ MCP ToolsClaude Code integration
Multi-CloudAWS, UpCloud, Local
Post-Quantum ReadyML-KEM-768, ML-DSA-65

Ready for integrated operations?

5 Projects | 40+ Crates | 4,360+ Tests | 100% Rust πŸ¦€

Explore Ecosystem β†’

StratumIOps v0.1.0

Integrated ecosystem with Rust excellence ✨

Infrastructure Operations | AI Orchestration | Knowledge Management | Secrets & Configuration

\ No newline at end of file diff --git a/assets/web/minify.sh b/assets/web/minify.sh new file mode 100755 index 0000000..c42d733 --- /dev/null +++ b/assets/web/minify.sh @@ -0,0 +1,87 @@ +#!/bin/bash +# Minify index.html from src/ to production version +# Usage: ./minify.sh + +set -e + +SRC_FILE="$(dirname "$0")/src/index.html" +OUT_FILE="$(dirname "$0")/index.html" +TEMP_FILE="${OUT_FILE}.tmp" + +if [ ! -f "$SRC_FILE" ]; then + echo "❌ Source file not found: $SRC_FILE" + exit 1 +fi + +echo "πŸ”¨ Minifying HTML..." +echo " Input: $SRC_FILE" +echo " Output: $OUT_FILE" + +perl -e " +use strict; +use warnings; + +open(my \$fh, '<', '$SRC_FILE') or die \$!; +my \$content = do { local \$/; <\$fh> }; +close(\$fh); + +# Remove HTML comments +\$content =~ s///gs; + +# Compress CSS (remove spaces and comments) +\$content =~ s/(]*>)(.*?)(<\/style>)/ + my \$before = \$1; + my \$style = \$2; + my \$after = \$3; + \$style =~ s{\/\*.*?\*\/}{}gs; + \$style =~ s{\s+}{ }gs; + \$style =~ s{\s*([{}:;,>+~])\s*}{\$1}gs; + \$before . \$style . \$after; +/gies; + +# Compress JavaScript (remove comments and extra spaces) +\$content =~ s/(]*>)(.*?)(<\/script>)/ + my \$before = \$1; + my \$script = \$2; + my \$after = \$3; + \$script =~ s{\/\/.*\$}{}gm; + \$script =~ s{\s+}{ }gs; + \$script =~ s{\s*([{}();,])\s*}{\$1}gs; + \$before . \$script . \$after; +/gies; + +# Remove whitespace between tags +\$content =~ s/>\s+', '$TEMP_FILE') or die \$!; +print \$out \$content; +close(\$out); +" || { + echo "❌ Minification failed" + rm -f "$TEMP_FILE" + exit 1 +} + +mv "$TEMP_FILE" "$OUT_FILE" + +# Show statistics +original=$(wc -c < "$SRC_FILE") +minified=$(wc -c < "$OUT_FILE") +saved=$((original - minified)) +percent=$((saved * 100 / original)) + +echo "" +echo "βœ… Minification complete!" +echo "" +echo "πŸ“Š Compression statistics:" +printf " Original: %6d bytes\n" "$original" +printf " Minified: %6d bytes\n" "$minified" +printf " Saved: %6d bytes (%d%%)\n" "$saved" "$percent" +echo "" +echo "βœ… $OUT_FILE is ready for production" diff --git a/assets/web/src/index.html b/assets/web/src/index.html new file mode 100644 index 0000000..05b0afb --- /dev/null +++ b/assets/web/src/index.html @@ -0,0 +1,978 @@ + + + + + + + StratumIOps + + + + + +
+ +
+ + +
+ +
+
+ βœ… v0.1.0 +
+ StratumIOps - Infrastructure Operations +
+

Infrastructure Operations Ecosystem

+

+ Five Projects +

+

+ Infrastructure operations, AI agent orchestration, knowledge management, secrets management, and configuration generation. + +
100% Rust. Zero compromises. + +

+
+ +
+

+ The 4 Problems It Solves +

+
+
+
01
+

+ Scattered Knowledge +

+
    +
  • Decisions in Slack
    • +
  • Guidelines in wikis
    • +
  • Patterns in docsβ€”all disconnected
    • +
  • Kogral unifies with git-native markdown + MCP
    • +
+
+
+
02
+

+ Uncontrolled LLM Costs +

+
    +
  • No visibility on AI spending per team
    • +
  • No budget limits or controls
    • +
  • Vapora: real-time budgets
    • +
  • Automatic fallback to cheaper providers
    • +
  • Expertise-based agent routing
    • +
+
+
+
03
+

+ Fragile YAML Configuration +

+
    +
  • Runtime errors from untyped config
    • +
  • No validation before deployment
    • +
  • Provisioning: Nickel with pre-runtime validation
    • +
  • TypeDialog: forms with contract validation
    • +
+
+
+
04
+

+ Static Cryptography +

+
    +
  • No preparation for quantum threats
    • +
  • Locked into single crypto library
    • +
  • SecretumVault: production post-quantum crypto
    • +
  • ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204)
    • +
  • 4 pluggable backends (OpenSSL, OQS, AWS-LC, RustCrypto)
    • +
+
+
+
+ +
+

+ Ecosystem Projects +

+
+
+
πŸ€–
+

+ Vapora +

+
    +
  • AI agent orchestration with learning
    • +
  • Agents improve from experience
    • +
  • Automatic budget fallback
    • +
  • NATS JetStream coordination
    • +
  • 13 crates, 218 tests, 50K LOC
    • +
+
+
+
🧠
+

+ Kogral +

+
    +
  • Knowledge graph with MCP for Claude Code
    • +
  • 6 node types: Notes, ADRs, Guidelines, Patterns, Journals, Executions
    • +
  • Git-native markdown storage
    • +
  • Semantic search with embeddings
    • +
  • 3 crates, 56 tests, 15K LOC
    • +
+
+
+
πŸ“‹
+

+ TypeDialog +

+
    +
  • 6 backends: CLI, TUI, Web, AI, Agent, Prov-gen
    • +
  • One TOML definition for all interfaces
    • +
  • Nickel contract validation
    • +
  • Conditional fields & repeating groups
    • +
  • 8 crates, 3,818 tests, 90K LOC
    • +
+
+
+
☁️
+

+ Provisioning +

+
    +
  • Declarative IaC with Nickel + AI-assisted generation
    • +
  • Multi-cloud: AWS, UpCloud, Local (LXD)
    • +
  • RAG with 1,200+ domain docs
    • +
  • MCP server for natural language queries
    • +
  • Orchestrator with automatic rollback
    • +
  • 15+ crates, 218 tests, 40K LOC
    • +
+
+
+
πŸ”’
+

+ SecretumVault +

+
    +
  • Post-quantum crypto: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204)
    • +
  • 4 crypto backends: OpenSSL, OQS, AWS-LC, RustCrypto
    • +
  • 4 storage backends: Filesystem, etcd, SurrealDB, PostgreSQL
    • +
  • 4 secrets engines: KV, Transit, PKI, Database
    • +
  • Shamir Secret Sharing for unsealing
    • +
  • 1 crate, 50+ tests, 11K LOC
    • +
+
+
+
+ +
+

+ Technology Stack +

+
+ Rust Edition 2021 + Nickel + Nushell + SurrealDB + NATS JetStream + Axum + Leptos WASM + Ratatui TUI + OpenTelemetry + Prometheus + etcd + PostgreSQL + OpenSSL + OQS (Post-Quantum) + Cedar Policy +
+
+ +
+

+ Ecosystem Metrics +

+
+
+ 40+ Rust CratesModular architecture +
+
+ 4,360+ TestsQuality assurance +
+
+ ~206K LOCProduction-ready code +
+
+ 0 Clippy WarningsCode quality +
+
+ 0 Unsafe BlocksMemory safety +
+
+ 100% Doc CoveragePublic APIs documented +
+
+ 4 Crypto BackendsCryptographic agility +
+
+ 4 Storage BackendsFlexible persistence +
+
+ 6 TypeDialog BackendsMulti-interface forms +
+
+ 14+ MCP ToolsClaude Code integration +
+
+ Multi-CloudAWS, UpCloud, Local +
+
+ Post-Quantum ReadyML-KEM-768, ML-DSA-65 +
+
+
+ +
+

+ Ready for integrated operations? +

+

+ 5 Projects | 40+ Crates | 4,360+ Tests | 100% Rust πŸ¦€ +

+ Explore Ecosystem β†’ +
+ +
+

StratumIOps v0.1.0

+

+ Integrated ecosystem with Rust excellence ✨ +

+

+ Infrastructure Operations | AI Orchestration | Knowledge Management | Secrets & Configuration +

+
+
+ + + + diff --git a/assets/web/src/stratumiops.svg b/assets/web/src/stratumiops.svg new file mode 100644 index 0000000..44e711e --- /dev/null +++ b/assets/web/src/stratumiops.svg @@ -0,0 +1,191 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + + + + + + + + + + diff --git a/assets/web/stratumiops.svg b/assets/web/stratumiops.svg new file mode 100644 index 0000000..44e711e --- /dev/null +++ b/assets/web/stratumiops.svg @@ -0,0 +1,191 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + StratumIOps + + + + + + + + + + + + + + + diff --git a/deny.toml b/deny.toml new file mode 100644 index 0000000..a6a8652 --- /dev/null +++ b/deny.toml @@ -0,0 +1,74 @@ +# Generated by dev-system/ci +# Configuration for cargo-deny +# See: https://embarkstudios.github.io/cargo-deny/ + +[advisories] +# The path where the advisory database is cloned/fetched into +db-path = "~/.cargo/advisory-db" +# The url(s) of the advisory databases to use +db-urls = ["https://github.com/rustsec/advisory-db"] +# How to handle crates with security vulnerabilities +vulnerability = "deny" +# How to handle unmaintained crates +unmaintained = "warn" +# How to handle crates that have been yanked from crates.io +yanked = "warn" + +[licenses] +# The lint level for crates which do not have a detectable license +unlicensed = "deny" +# List of explicitly allowed licenses +allow = [ + "MIT", + "MIT-0", + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "Unicode-DFS-2016", +] +# List of explicitly disallowed licenses +deny = [ + "GPL-2.0", + "GPL-3.0", + "AGPL-3.0", +] +# Lint level for licenses considered copyleft +copyleft = "warn" +# Blanket approval or denial for OSI-approved or FSF Free/Libre licenses +allow-osi-fsf-free = "both" +# Lint level used when no other predicates are matched +default = "deny" + +[bans] +# Lint level for when multiple versions of the same crate are detected +multiple-versions = "warn" +# Lint level for when an allow-listed crate is detected without an exact version +allow = [ + # Each entry can be just the name and an optional wildcard version. + # This would ideally be pulled from Cargo.lock deps to keep up to date + # but that is more complex. It depends on the use case. +] +# Each entry must be a single version number +deny = [ + # Each entry is a crate name. Optionally with a version +] +# Certain crates/versions that will be skipped when doing duplicate detection +skip = [ + # { name = "ansi_term", version = "<= 0.11.0" } +] +# Similarly named crates that are allowed to coexist +skip-tree = [ + # { name = "windows", version = "<=0.46.0" } +] + +[sources] +# Lint level for what to happen when a crate from a crate registry that is not in the allow list is detected +unknown-registry = "deny" +# Lint level for what to happen when a crate from a Git repository that is not in the allow list is detected +unknown-git = "deny" +# The allow list of crate registries +allow-registry = ["https://github.com/rust-lang/crates.io-index"] +# The allow list of Git repositories +allow-git = [] diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f5d1c83 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,49 @@ +
+ StratumIOps Logo +
+ +# STRATUMIOPS Documentation + +Complete documentation for the STRATUMIOPS ecosystem of development and operations tools. + +## Languages + +- [English Documentation](en/) - Full documentation in English +- [DocumentaciΓ³n en EspaΓ±ol](es/) - DocumentaciΓ³n completa en espaΓ±ol + +## Structure + +### AI Portfolio + +AI-powered development tools and intelligent automation. + +- **Vapora**: Development hub with project management and AI agents +- **Kogral**: Knowledge graph and intelligent documentation +- **TypeDialog**: Configuration management and CI/CD orchestration + +See [AI Portfolio Docs](en/ia/) for technical details. + +### Operations Portfolio + +Infrastructure automation and deployment tools. + +- **Provisioning**: Multi-cloud infrastructure as code +- **SecretumVault**: Secure secrets management + +See [Operations Portfolio Docs](en/ops/) for technical details. + +## Quick Start + +1. Choose your language: [English](en/) | [EspaΓ±ol](es/) +2. Browse by category: [AI Tools](en/ia/) | [Ops Tools](en/ops/) +3. Review positioning and technical specifications + +## Project Organization + +Each language directory contains: + +- `stratiumiops_market.md` - Complete platform overview +- `stratiumiops_position.md` - Strategic positioning +- `stratiumiops-technical-specs.md` - Technical specifications +- `ia/` - AI portfolio documentation +- `ops/` - Operations portfolio documentation diff --git a/docs/en/README.md b/docs/en/README.md new file mode 100644 index 0000000..631cf1d --- /dev/null +++ b/docs/en/README.md @@ -0,0 +1,40 @@ +
+ StratumIOps Logo +
+ +# STRATUMIOPS Documentation + +Complete documentation for the STRATUMIOPS ecosystem in English. + +## Overview Documents + +- [**stratiumiops_market.md**](stratiumiops_market.md) - Complete platform overview and market positioning +- [**stratiumiops_position.md**](stratiumiops_position.md) - Strategic positioning and competitive analysis +- [**stratiumiops-technical-specs.md**](stratiumiops-technical-specs.md) - Comprehensive technical specifications + +## Portfolio Categories + +### AI Portfolio + +AI-powered development tools and intelligent automation. + +- [**AI Projects Overview**](ia/ia-stratumiops-projects.md) - Vapora, Kogral, TypeDialog +- [**AI Positioning**](ia/ia-stratumiops-projects-positioning.md) - Market strategy and differentiation +- [**AI Technical Specs**](ia/ia-stratumiops-projects-technical-specs.md) - API, architecture, and implementation details + +See [ia/](ia/) directory for full AI portfolio documentation. + +### Operations Portfolio + +Infrastructure automation and deployment tools. + +- [**Ops Projects Overview**](ops/ops-stratumiops-projects.md) - Provisioning, SecretumVault +- [**Ops Positioning**](ops/ops-stratumiops-projects-positioning.md) - Market strategy and differentiation +- [**Ops Technical Specs**](ops/ops-stratumiops-projects-technical-specs.md) - API, architecture, and implementation details + +See [ops/](ops/) directory for full operations portfolio documentation. + +## Navigation + +- [Back to root documentation](../) +- [Spanish version](../es/) diff --git a/docs/en/ia/README.md b/docs/en/ia/README.md new file mode 100644 index 0000000..aa8c544 --- /dev/null +++ b/docs/en/ia/README.md @@ -0,0 +1,44 @@ +# AI Portfolio Documentation + +Documentation for STRATUM's AI-powered development tools. + +## Projects + +### Vapora + +Development hub with project management and AI agents. + +- Project management with visual Kanban +- AI agents trained on team conventions +- Real-time collaboration +- Integrated knowledge base + +### Kogral + +Knowledge graph and intelligent documentation. + +- Multi-source knowledge aggregation +- AI-powered search and recommendations +- Version control integration +- Automated documentation generation + +### TypeDialog + +Configuration management and CI/CD orchestration. + +- Type-safe configuration with Nickel +- Multi-backend CI/CD generation +- Pre-commit integration +- Security scanning and quality gates + +## Documentation Files + +- [**ia-stratumiops-projects.md**](ia-stratumiops-projects.md) - Complete overview of AI portfolio projects +- [**ia-stratumiops-projects-positioning.md**](ia-stratumiops-projects-positioning.md) - Market positioning and competitive analysis +- [**ia-stratumiops-projects-technical-specs.md**](ia-stratumiops-projects-technical-specs.md) - Technical specifications, API documentation, and architecture + +## Navigation + +- [Back to English docs](../) +- [Back to root documentation](../../) +- [Operations portfolio](../ops/) diff --git a/docs/en/ia/ia-stratumiops-projects-positioning.md b/docs/en/ia/ia-stratumiops-projects-positioning.md new file mode 100644 index 0000000..167a816 --- /dev/null +++ b/docs/en/ia/ia-stratumiops-projects-positioning.md @@ -0,0 +1,554 @@ +# AI Portfolio: Strategic Positioning + +## Target Market + +### Primary Segments + +| Segment | Size | Key Need | Solution | +| --------- | ------ | ---------- | ---------- | +| **Development teams (10-50 devs)** | Mid-market | Manage LLM costs without losing quality | Vapora with budgets and intelligent routing | +| **Multi-project organizations** | Enterprise | Preserve knowledge across teams | Kogral with guideline inheritance | +| **DevOps with multi-cloud** | SMB/Enterprise | Typed IaC with AI assistance | Provisioning + MCP Server | +| **Teams using Claude Code** | Individual/Team | Project context for agents | Kogral + 7 native MCP tools | +| **Post-quantum adopters** | Enterprise/Gov | Production-ready PQC today | SecretumVault with ML-KEM-768/ML-DSA-65 | + +### Market Trends (2025-2026) + +- **LLM spending growth**: 340% year-over-year in development teams +- **Quantum threat timeline**: NIST recommends PQC adoption by 2030 +- **Agent adoption**: 67% of teams using 3+ LLM providers +- **Multi-cloud**: 89% of enterprises using 2+ cloud providers + +--- + +## Competitive Analysis + +### Vapora vs LangChain/LlamaIndex + +| Aspect | Vapora | LangChain | LlamaIndex | +| -------- | -------- | ----------- | ------------ | +| **Agent learning** | Execution profile with recency bias | Static chains | Static workflows | +| **Budget control** | Per-role budgets with automatic fallback | Manual | Manual | +| **Multi-provider** | 4 LLM providers with intelligent routing | Yes (via adapters) | Yes (via adapters) | +| **Cost tracking** | Real-time per agent/task/project | No native support | No native support | +| **Persistence** | SurrealDB with multi-tenant scopes | DIY | DIY | +| **Language** | Rust (performance, type-safe) | Python (GIL, optional typing) | Python | + +**Vapora differentiator**: **Agents that learn which provider is best for each task** based on historical performance. + +### Vapora vs CrewAI/AutoGen + +| Aspect | Vapora | CrewAI | AutoGen | +| -------- | -------- | -------- | --------- | +| **Orchestration** | NATS JetStream with retries | Sequential/hierarchical | Graph-based | +| **Agent roles** | 12 specialized (Architect, Developer, Reviewer...) | Generic roles | Generic agents | +| **Approval gates** | Configurable checkpoints in pipelines | No | No | +| **Multi-tenancy** | Native (SurrealDB scopes) | DIY | No | +| **Cost visibility** | Budget dashboard per role | No | No | +| **Language** | Rust | Python | Python | + +**Vapora differentiator**: **Production-grade orchestration** with NATS, not just sequential execution. + +--- + +### Kogral vs Obsidian/Notion + +| Aspect | Kogral | Obsidian | Notion | +| -------- | -------- | ---------- | -------- | +| **Node types** | 6 specialized (Note, Decision, Guideline, Pattern, Journal, Execution) | Generic markdown | Generic blocks | +| **Version control** | Git-native (everything in markdown) | Vault-based (no native git) | SaaS (no git) | +| **Guideline inheritance** | Organization β†’ Project β†’ Developer | No | No | +| **MCP integration** | 7 native tools for Claude Code | No | No | +| **Query language** | Cypher-like for knowledge graph | Dataview plugin (limited) | Database queries | +| **AI context** | Agents query guidelines before generating code | Manual copy-paste | Manual copy-paste | + +**Kogral differentiator**: **Knowledge that AI agents can query** before generating code, not just human-readable docs. + +### Kogral vs Confluence/Wiki.js + +| Aspect | Kogral | Confluence | Wiki.js | +| -------- | -------- | ------------ | --------- | +| **Storage** | Git-native markdown | Database/SaaS | Database | +| **Structured nodes** | 6 types with relationships | Pages with labels | Pages with tags | +| **ADR support** | Native (Decision node type) | Template-based | Template-based | +| **AI integration** | MCP Server for Claude Code | No | No | +| **Multi-tenancy** | Organization/Project isolation | Spaces | Spaces | +| **Backup** | Git clone | Database export | Database export | + +**Kogral differentiator**: **Git-native knowledge graph** with first-class AI integration. + +--- + +### TypeDialog vs Multiple Tools + +| Aspect | TypeDialog | Alternatives | +| -------- | ------------ | -------------- | +| **Backends** | 6 (CLI, TUI, Web, AI, Agent, Prov-gen) | 1 per tool | +| **Single definition** | TOML β†’ all backends | Duplicate logic | +| **Type validation** | Nickel contracts (pre-runtime) | Runtime errors (Pydantic, Joi) | +| **Agent execution** | .agent.mdx files with 4 LLM providers | Separate tools | +| **IaC generation** | Forms β†’ Nickel IaC β†’ 6 clouds | Manual | +| **i18n** | Fluent (Mozilla) | Per-backend | + +**TypeDialog differentiator**: **One definition, execute anywhere** including AI agents. + +### TypeDialog vs Streamlit/Gradio + +| Aspect | TypeDialog | Streamlit | Gradio | +| -------- | ------------ | ----------- | -------- | +| **Target** | Forms for automation + UI | Dashboards | ML demos | +| **Backends** | 6 (including CLI, Agent) | Web only | Web only | +| **Validation** | Nickel (pre-runtime) | Python (runtime) | Python (runtime) | +| **Language** | Rust | Python | Python | +| **Deployment** | CLI/TUI/Web/Agent | Web server | Web server | + +**TypeDialog differentiator**: **Configuration wizards** that work in terminal, web, and AI agents. + +--- + +### Provisioning vs Terraform/Pulumi + +| Aspect | Provisioning | Terraform | Pulumi | +| -------- | -------------- | ----------- | -------- | +| **Configuration** | Nickel (typed, lazy) | HCL (runtime errors) | Python/TypeScript/Go | +| **Validation** | Compile-time | Plan-time | Runtime | +| **Rollback** | Automatic on failure | Manual | Manual | +| **Checkpoints** | Built-in with recovery | No | No | +| **MCP Server** | Native (NLP queries) | No | No | +| **RAG integration** | 1,200+ docs for context | No | No | +| **Multi-cloud** | AWS, UpCloud, Local (LXD) | 300+ providers | 100+ providers | +| **Language** | Rust | Go | Go/Node | + +**Provisioning differentiator**: **Typed IaC with AI-assisted generation** and automatic rollback. + +### Provisioning vs Ansible/Chef + +| Aspect | Provisioning | Ansible | Chef | +| -------- | -------------- | --------- | ------ | +| **Paradigm** | Declarative IaC | Imperative playbooks | Declarative recipes | +| **Validation** | Nickel type system | YAML linting | Ruby syntax | +| **State** | Explicit (SurrealDB) | Implicit (no state) | Explicit (Chef Server) | +| **Orchestration** | Dependency graph with parallelism | Sequential tasks | Dependency graph | +| **Agent** | Agentless | Agentless | Agent-based | +| **AI integration** | MCP Server + RAG | No | No | + +**Provisioning differentiator**: **Declarative IaC** with validation before execution, not imperative scripts. + +--- + +### SecretumVault vs HashiCorp Vault + +| Aspect | SecretumVault | HashiCorp Vault | +| -------- | --------------- | ----------------- | +| **Post-quantum** | **Production (ML-KEM-768, ML-DSA-65)** | Experimental | +| **Crypto backends** | 4 (OpenSSL, OQS, AWS-LC, RustCrypto) | 1 (Go crypto) | +| **Storage backends** | 4 (Filesystem, etcd, SurrealDB, PostgreSQL) | 10+ | +| **Secrets engines** | 4 (KV, Transit, PKI, Database) | 10+ | +| **Language** | Rust (memory-safe) | Go | +| **License** | Proprietary/TBD | BSL 1.1 (non-commercial) | +| **Cedar policies** | Native ABAC | Sentinel (enterprise) | + +**SecretumVault differentiator**: **Production-ready post-quantum cryptography** today, not experimental. + +### SecretumVault vs AWS Secrets Manager/Azure Key Vault + +| Aspect | SecretumVault | AWS Secrets Manager | Azure Key Vault | +| -------- | --------------- | --------------------- | ----------------- | +| **Self-hosted** | Yes | No (SaaS only) | No (SaaS only) | +| **Post-quantum** | ML-KEM-768, ML-DSA-65 | No | No | +| **Multi-cloud** | Yes (portable) | AWS only | Azure only | +| **Crypto agility** | 4 backends | Fixed | Fixed | +| **Pricing** | Self-hosted (no per-secret cost) | $0.40/secret/month | $0.03/10K operations | + +**SecretumVault differentiator**: **Self-hosted with PQC**, no vendor lock-in. + +--- + +## Use Cases by Persona + +### AI Engineer + +**Problem**: Using Claude, OpenAI, and Gemini for different tasks. No visibility of which model is best for what. Monthly bill growing uncontrollably. + +**Solution**: +1. **Vapora** coordinates agents with budget per role +2. **Kogral** provides patterns and decisions to agents via MCP +3. **TypeDialog** captures agent configurations in .agent.mdx files +4. **SecretumVault** stores API keys securely + +**Result**: 40% cost reduction through intelligent routing. Agents query guidelines before generating code. + +--- + +### Tech Lead (Multi-Project) + +**Problem**: 5 projects with different conventions. New developers ask "how do we do X here?" repeatedly. Knowledge in Slack threads. + +**Solution**: +1. **Kogral** with guideline inheritance (Organization β†’ Project) +2. Capture decisions as ADRs in Decision nodes +3. **MCP integration** so Claude Code respects conventions +4. Git-native: all knowledge versioned and auditable + +**Result**: Onboarding time reduced from 3 weeks to 5 days. AI-generated code follows project conventions. + +--- + +### DevOps Engineer (Multi-Cloud) + +**Problem**: AWS + UpCloud infrastructure. YAML everywhere. Configuration errors discovered at runtime. No automatic rollback. + +**Solution**: +1. **Provisioning** with Nickel IaC (typed, validated) +2. **MCP Server** for NLP queries: "What's the VPC configuration for production?" +3. Orchestrator with checkpoints and automatic rollback +4. **SecretumVault** for credentials and cloud API keys + +**Result**: 80% reduction in runtime errors. Infrastructure changes with automatic rollback on failure. + +--- + +### Security Engineer + +**Problem**: Preparing for post-quantum threats. NIST recommends migration by 2030. Current vault (HashiCorp) without production-ready PQC. + +**Solution**: +1. **SecretumVault** with OQS backend (ML-KEM-768, ML-DSA-65) +2. Crypto agility: switch between OpenSSL/OQS without code changes +3. Multi-backend storage (etcd for HA, PostgreSQL for audit) +4. Cedar policies for fine-grained ABAC + +**Result**: PQC in production today. Gradual migration without downtime. + +--- + +## Integration Scenarios + +### Scenario 1: Feature Development with AI + +```text +Developer starts task "Add OAuth2 authentication" + ↓ + Kogral (MCP) β†’ "Are there auth guidelines?" + ↓ + Returns: "Use oauth2-rs crate + Cedar policies" + ↓ + Vapora assigns Architect agent β†’ Designs architecture + ↓ + Developer agent implements β†’ Queries Kogral for patterns + ↓ + Reviewer agent validates β†’ Checks Cedar policies + ↓ + TypeDialog captures OAuth2 config (client_id, scopes) + ↓ + SecretumVault stores client_secret with TTL + ↓ + Kogral records ADR: "Why OAuth2 over SAML" +``` + +**Benefit**: Agent-generated code respects conventions. Decisions documented. Secrets secured. + +--- + +### Scenario 2: Multi-Cloud Infrastructure + +```text +"Need a K8s cluster on AWS with 3 nodes and RDS PostgreSQL" + ↓ + Provisioning MCP Server (NLP query) + ↓ + RAG searches similar configurations + ↓ + Generates Nickel IaC + validates types + ↓ + TypeDialog wizard for cluster parameters (region, instance_type) + ↓ + Orchestrator deploys with checkpoints + ↓ + SecretumVault generates DB credentials with 30d TTL + ↓ + Kogral records infrastructure ADR + ↓ + Vapora Monitor agent tracks cluster health +``` + +**Benefit**: Infrastructure from NLP. Typed validation. Automatic rollback. Dynamic secrets. + +--- + +### Scenario 3: Team Onboarding + +```text +New developer joins project + ↓ + Kogral exports knowledge graph (Guidelines + Patterns + ADRs) + ↓ + TypeDialog interactive quiz on architecture + ↓ + Vapora assigns onboarding tasks (read ADRs β†’ small fix β†’ review code) + ↓ + Provisioning configures dev environment (local K8s + databases) + ↓ + SecretumVault provides temporary credentials (7d TTL) +``` + +**Benefit**: Structured onboarding. Knowledge accessible. Environment automated. + +--- + +## Ecosystem Synergies + +### Synergy 1: Kogral + Vapora + +- **Kogral** provides guidelines to agents via MCP +- **Vapora** records agent executions as Execution nodes in Kogral +- **Result**: Continuous learning loop (agents query β†’ execute β†’ record β†’ improve) + +### Synergy 2: TypeDialog + Provisioning + +- **TypeDialog** prov-gen backend generates Nickel IaC +- **Provisioning** executes and validates with MCP Server +- **Result**: Forms β†’ Infrastructure without manual config + +### Synergy 3: SecretumVault + All + +- **Vapora**: Stores LLM API keys +- **Kogral**: Encrypts sensitive ADRs +- **Provisioning**: Cloud credentials with rotation +- **Result**: Centralized secrets with PQC across ecosystem + +### Synergy 4: MCP Ecosystem + +| Project | MCP Tools | Purpose | +| --------- | ----------- | --------- | +| **Kogral** | 7 tools | Query guidelines, create ADRs, search patterns | +| **Provisioning** | 1 server | NLP queries, RAG over IaC docs | +| **SecretumVault** | Planned | Dynamic secret requests | + +**Result**: Claude Code with full project context. + +--- + +## Pricing Strategy (Future) + +### Kogral + +- **Free**: Single project, unlimited nodes +- **Team ($49/month)**: 10 projects, guideline inheritance +- **Enterprise**: Unlimited projects + audit + SSO + +### Vapora + +- **Free**: 100 agent executions/month, 1 LLM provider +- **Pro ($99/month)**: Unlimited executions, 4 providers, budget dashboard +- **Enterprise**: Multi-tenant + SLA + priority support + +### Provisioning + +- **Free**: Local provider (LXD), 50 resources +- **Team ($149/month)**: AWS + UpCloud, 500 resources, MCP Server +- **Enterprise**: Multi-cloud + audit + break-glass + +### SecretumVault + +- **Free**: Filesystem backend, KV engine +- **Pro ($79/month)**: etcd/PostgreSQL backend, all engines, PQC +- **Enterprise**: HA + HSM + compliance reports + +### TypeDialog + +- **Free**: CLI + TUI backends +- **Pro ($29/month)**: Web + Agent backends, 4 LLM providers +- **Enterprise**: Custom backends + white-label + +--- + +## Adoption Roadmap + +### Phase 1: Knowledge Foundation (Week 1-2) + +1. Deploy **Kogral** in one project +2. Migrate existing ADRs to Decision nodes +3. Define organization-level Guidelines +4. Configure MCP for Claude Code + +**Success criteria**: Agents query guidelines before generating code. + +--- + +### Phase 2: Agent Orchestration (Week 3-4) + +1. Deploy **Vapora** with 3 agent roles (Architect, Developer, Reviewer) +2. Configure budgets per role +3. Connect Kogral for context +4. Run first pipeline (design β†’ implement β†’ review) + +**Success criteria**: 30% cost reduction through intelligent routing. + +--- + +### Phase 3: Infrastructure Automation (Week 5-6) + +1. Deploy **Provisioning** with one cloud (AWS or UpCloud) +2. Migrate one service to Nickel IaC +3. Enable MCP Server for NLP queries +4. Configure **SecretumVault** for cloud credentials + +**Success criteria**: Infrastructure changes with automatic rollback. + +--- + +### Phase 4: Multi-Interface (Week 7-8) + +1. Deploy **TypeDialog** for configuration wizards +2. Create forms for common tasks (deploy service, create user, configure monitoring) +3. Enable prov-gen backend for IaC generation +4. Integrate with Vapora for agent-driven forms + +**Success criteria**: Single form definition for CLI, TUI, Web, Agent. + +--- + +### Phase 5: Post-Quantum Security (Week 9-10) + +1. Migrate to **SecretumVault** with OQS backend +2. Generate PQC certificates (ML-DSA-65) +3. Configure dynamic secrets with TTL +4. Enable audit logging with 7-year retention + +**Success criteria**: PQC in production without downtime. + +--- + +## Success Metrics + +### Cost Efficiency + +- **Baseline**: $2,400/month LLM costs (uncontrolled) +- **With Vapora**: $1,440/month (40% reduction through intelligent routing) +- **ROI**: 5 months + +### Development Velocity + +- **Baseline**: 3 weeks onboarding new developer +- **With Kogral**: 5 days (knowledge graph + Claude Code integration) +- **Baseline**: 2 days to deploy infrastructure change +- **With Provisioning**: 2 hours (Nickel IaC + automatic rollback) + +### Security Posture + +- **Baseline**: No PQC, manual secret rotation +- **With SecretumVault**: PQC in production, dynamic secrets with 30d TTL +- **Compliance**: 7-year audit log retention + +### Code Quality + +- **Baseline**: 30% of AI-generated code violates project conventions +- **With Kogral + Vapora**: 5% (agents query guidelines before generating) + +--- + +## Frequently Asked Questions + +### Can I use only one project + +**Yes**. Each project works independently: +- Only Kogral β†’ Knowledge graph with git +- Only TypeDialog β†’ Multi-backend forms +- Only SecretumVault β†’ PQC vault +- Only Vapora β†’ Agent orchestration +- Only Provisioning β†’ Typed IaC + +Synergies emerge when combining them. + +--- + +### How is this different from LangChain + Terraform + +| Aspect | stratumiops | LangChain + Terraform | +| -------- | ------------- | ------------------------ | +| **Agent learning** | Execution profiles | Static chains | +| **Budget control** | Per-role automatic fallback | Manual | +| **IaC validation** | Nickel (compile-time) | HCL (plan-time) | +| **Knowledge** | Git-native graph with MCP | Separate wiki | +| **Integration** | Native (same stack) | DIY glue code | +| **Language** | Rust end-to-end | Python + Go | + +**Main difference**: **Integrated ecosystem** vs disconnected tools. + +--- + +### Is post-quantum cryptography really necessary today + +**NIST recommendation**: Migrate by 2030. "Store now, decrypt later" attacks are already happening. + +**SecretumVault approach**: +- **Crypto agility**: Switch between OpenSSL/OQS without code changes +- **Production-ready**: ML-KEM-768 and ML-DSA-65 (NIST FIPS 203/204) +- **Gradual migration**: Run classic and PQC in parallel + +**Benefit**: Prepare today, avoid rushed migration in 2029. + +--- + +### What if I already use HashiCorp Vault + +**Migration path**: +1. Deploy SecretumVault in parallel +2. Migrate non-critical secrets first +3. Enable OQS backend for new secrets +4. Gradually migrate critical secrets +5. Decommission HashiCorp Vault + +**Benefit**: Zero downtime. Gradual PQC adoption. + +--- + +### How does guideline inheritance work in Kogral + +```text +Organization guidelines: + - Use Rust for services + - Cedar for authorization + - SurrealDB for persistence + + ↓ (inherited by) + +Project "API Gateway" overrides: + - Use Axum for HTTP + - Use JWT for auth + + ↓ (inherited by) + +Developer sees effective guidelines: + - Use Rust for services (from org) + - Cedar for authorization (from org) + - SurrealDB for persistence (from org) + - Use Axum for HTTP (from project) + - Use JWT for auth (from project) +``` + +**Benefit**: Organization standards + project flexibility. + +--- + +## Contact and Next Steps + +### Try the Ecosystem + +1. **Kogral**: Clone and run locally (git-native, no dependencies) +2. **TypeDialog**: Try CLI backend with example forms +3. **SecretumVault**: Deploy with filesystem backend (development mode) +4. **Provisioning**: Generate Nickel IaC from TypeDialog forms +5. **Vapora**: Run first agent pipeline (Architect β†’ Developer β†’ Reviewer) + +### Commercial Inquiries + +- **License**: Proprietary / To be defined +- **Support**: Enterprise SLA available +- **Custom integrations**: Additional LLM providers, cloud providers, storage backends + +--- + +*AI-assisted development shouldn't require 10 disconnected tools.* +*One ecosystem. Five projects. Real integration.* diff --git a/docs/en/ia/ia-stratumiops-projects-technical-specs.md b/docs/en/ia/ia-stratumiops-projects-technical-specs.md new file mode 100644 index 0000000..15f5b59 --- /dev/null +++ b/docs/en/ia/ia-stratumiops-projects-technical-specs.md @@ -0,0 +1,1319 @@ +# AI Portfolio: Technical Specifications for Developers + +## Ecosystem Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PRESENTATION LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Leptos WASM (Vapora UI) β”‚ Ratatui TUI β”‚ Axum REST β”‚ CLI (clap) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ ORCHESTRATION LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Vapora Coordinator β”‚ TypeDialog Backends β”‚ Provisioning Orchestrator β”‚ +β”‚ (NATS JetStream) β”‚ (BackendFactory) β”‚ (Rust/Nushell hybrid) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ KNOWLEDGE LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Kogral Knowledge Graph β”‚ Vapora Learning Profiles β”‚ Provisioning RAG β”‚ +β”‚ (6 node types) β”‚ (expertise + recency) β”‚ (1200+ docs) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PERSISTENCE LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SurrealDB (multi-tenant scopes) β”‚ Filesystem (git-native markdown) β”‚ +β”‚ NATS JetStream (messaging) β”‚ Redis (optional vector stores) β”‚ +β”‚ etcd (SecretumVault HA) β”‚ PostgreSQL (vault enterprise) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 1. Vapora: Specifications + +### Workspace Structure + +```text +crates/ +β”œβ”€β”€ vapora-shared/ # Core: models, errors, types +β”œβ”€β”€ vapora-backend/ # Axum REST API (40+ endpoints) +β”œβ”€β”€ vapora-agents/ # Agent orchestration + learning +β”œβ”€β”€ vapora-llm-router/ # Multi-provider routing + budget +β”œβ”€β”€ vapora-swarm/ # Swarm coordination + metrics +β”œβ”€β”€ vapora-knowledge-graph/# Temporal KG + learning curves +β”œβ”€β”€ vapora-frontend/ # Leptos WASM UI +β”œβ”€β”€ vapora-mcp-server/ # MCP protocol gateway +β”œβ”€β”€ vapora-tracking/ # Task/project storage +β”œβ”€β”€ vapora-telemetry/ # OpenTelemetry integration +β”œβ”€β”€ vapora-analytics/ # Event pipeline +β”œβ”€β”€ vapora-worktree/ # Git worktree management +└── vapora-doc-lifecycle/ # Documentation management +``` + +### Core Types + +```rust +// vapora-shared/src/models.rs +pub struct Agent { + pub id: String, + pub role: AgentRole, // 12 available roles + pub status: AgentStatus, // Ready | Busy | Offline + pub provider: LLMProvider, // Claude | OpenAI | Gemini | Ollama + pub last_heartbeat: DateTime, +} + +pub enum AgentRole { + Architect, Developer, CodeReviewer, Tester, + Documenter, Marketer, Presenter, DevOps, + Monitor, Security, ProjectManager, DecisionMaker, +} + +// vapora-agents/src/learning_profile.rs +pub struct ExpertiseProfile { + pub task_type: String, + pub success_rate: f64, + pub avg_duration: Duration, + pub execution_count: u32, + pub recent_weight: f64, // 3x for last 7 days + pub confidence: f64, // prevents overfitting on small samples +} + +// Scoring formula +fn calculate_score(load: f64, expertise: f64, confidence: f64) -> f64 { + 0.3 * load + 0.5 * expertise + 0.2 * confidence +} +``` + +### LLM Router Configuration + +```rust +// vapora-llm-router/src/config.rs +pub struct RoutingRule { + pub pattern: String, // regex for task type + pub provider: LLMProvider, + pub model: String, + pub fallback_chain: Vec, +} + +pub struct BudgetConfig { + pub role: AgentRole, + pub monthly_limit_cents: u32, + pub weekly_limit_cents: Option, + pub enforcement: BudgetEnforcement, // Normal | NearThreshold | Exceeded +} + +// Cost tracking per request +pub struct CostRecord { + pub provider: LLMProvider, + pub model: String, + pub input_tokens: u32, + pub output_tokens: u32, + pub cost_cents: f64, + pub task_type: String, + pub timestamp: DateTime, +} +``` + +### API Endpoints (Axum) + +```rust +// vapora-backend/src/api/mod.rs +Router::new() + // Projects + .route("/projects", get(list_projects).post(create_project)) + .route("/projects/:id", get(get_project).put(update_project).delete(delete_project)) + + // Tasks + .route("/tasks", get(list_tasks).post(create_task)) + .route("/tasks/:id/assign", post(assign_to_agent)) + + // Agents + .route("/agents", get(list_agents)) + .route("/agents/:id/health", get(agent_health)) + .route("/agents/:role/expertise", get(role_expertise)) + + // LLM Router + .route("/llm/route", post(route_request)) + .route("/llm/budget/:role", get(get_budget).put(set_budget)) + .route("/llm/costs", get(cost_report)) + + // Swarm + .route("/swarm/assign", post(assign_task)) + .route("/swarm/status", get(swarm_status)) + + // Metrics + .route("/metrics", get(prometheus_metrics)) +``` + +### NATS Message Types + +```rust +// vapora-agents/src/messages.rs +#[derive(Serialize, Deserialize)] +pub enum AgentMessage { + TaskAssignment { + task_id: String, + agent_id: String, + task_type: String, + payload: serde_json::Value, + }, + TaskResult { + task_id: String, + agent_id: String, + status: TaskStatus, + output: Option, + duration_ms: u64, + tokens_used: u32, + }, + Heartbeat { + agent_id: String, + status: AgentStatus, + current_load: f64, + }, +} + +// Subjects +const TASK_ASSIGNMENT: &str = "vapora.tasks.assign"; +const TASK_RESULTS: &str = "vapora.tasks.results"; +const AGENT_HEARTBEAT: &str = "vapora.agents.heartbeat"; +``` + +--- + +## 2. Kogral: Specifications + +### Workspace Structure + +``` +crates/ +β”œβ”€β”€ kogral-core/ # Core library (models, storage, query) +β”œβ”€β”€ kogral-cli/ # CLI (13 commands) +└── kogral-mcp/ # MCP server for Claude Code +``` + +### Node Types + +```rust +// kogral-core/src/models.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum NodeType { + Note, // General notes + Decision, // ADRs (Architectural Decision Records) + Guideline, // Team/org standards + Pattern, // Reusable solutions + Journal, // Daily development log + Execution, // Agent execution records +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum RelationType { + RelatesTo, + DependsOn, + Implements, + Extends, + Supersedes, + Explains, +} + +pub struct Node { + pub id: String, + pub node_type: NodeType, + pub title: String, + pub content: String, // Markdown body + pub metadata: HashMap, + pub tags: Vec, + pub created_at: DateTime, + pub updated_at: DateTime, +} + +pub struct Edge { + pub source: String, // Node ID + pub target: String, // Node ID + pub relation: RelationType, + pub weight: f64, // Relationship strength +} +``` + +### Storage Backends + +```rust +// kogral-core/src/storage/mod.rs +#[async_trait] +pub trait Storage: Send + Sync { + async fn create_node(&self, node: &Node) -> Result; + async fn get_node(&self, id: &str) -> Result>; + async fn update_node(&self, node: &Node) -> Result<()>; + async fn delete_node(&self, id: &str) -> Result<()>; + async fn list_nodes(&self, filter: NodeFilter) -> Result>; + + async fn create_edge(&self, edge: &Edge) -> Result<()>; + async fn get_edges(&self, node_id: &str) -> Result>; + async fn delete_edge(&self, source: &str, target: &str) -> Result<()>; + + async fn search(&self, query: &str, limit: usize) -> Result>; + async fn semantic_search(&self, embedding: &[f32], limit: usize) -> Result>; +} + +// Implementations +pub struct FilesystemStorage { /* .kogral/ directory */ } +pub struct SurrealDbStorage { /* SurrealDB connection */ } +pub struct MemoryStorage { /* DashMap for testing */ } +``` + +### Embedding Configuration + +```rust +// kogral-core/src/embeddings.rs +pub enum EmbeddingProvider { + FastEmbed { + model: String, // "BAAI/bge-small-en-v1.5" + dimensions: usize, // 384 + }, + OpenAI { + model: String, // "text-embedding-3-small" + api_key: String, + }, + Ollama { + model: String, + url: String, + }, +} + +#[async_trait] +pub trait Embedder: Send + Sync { + async fn embed(&self, text: &str) -> Result>; + async fn embed_batch(&self, texts: &[String]) -> Result>>; + fn dimensions(&self) -> usize; +} +``` + +### MCP Server Tools + +```rust +// kogral-mcp/src/tools.rs +pub const MCP_TOOLS: &[Tool] = &[ + Tool { + name: "search", + description: "Search knowledge graph by text or semantic similarity", + parameters: json!({ + "query": { "type": "string" }, + "node_type": { "type": "string", "optional": true }, + "limit": { "type": "integer", "default": 10 } + }), + }, + Tool { + name: "add_note", + description: "Add a new note to the knowledge graph", + parameters: json!({ + "title": { "type": "string" }, + "content": { "type": "string" }, + "tags": { "type": "array", "items": { "type": "string" } } + }), + }, + Tool { + name: "add_decision", + description: "Record an architectural decision (ADR)", + parameters: json!({ + "title": { "type": "string" }, + "context": { "type": "string" }, + "decision": { "type": "string" }, + "consequences": { "type": "string" } + }), + }, + Tool { + name: "link", + description: "Create relationship between nodes", + parameters: json!({ + "source_id": { "type": "string" }, + "target_id": { "type": "string" }, + "relation": { "type": "string", "enum": ["relates_to", "depends_on", "implements", "extends", "supersedes", "explains"] } + }), + }, + Tool { + name: "get_guidelines", + description: "Get applicable guidelines for a topic", + parameters: json!({ + "topic": { "type": "string" }, + "include_shared": { "type": "boolean", "default": true } + }), + }, + Tool { + name: "list_graphs", + description: "List available knowledge graphs", + parameters: json!({}), + }, + Tool { + name: "export", + description: "Export knowledge graph to format", + parameters: json!({ + "format": { "type": "string", "enum": ["markdown", "json", "yaml"] }, + "filter": { "type": "object", "optional": true } + }), + }, +]; +``` + +### CLI Commands + +```bash +# kogral-cli commands +kogral init # Initialize .kogral/ directory +kogral add note # Add note interactively +kogral add decision <title> # Add ADR with guided prompts +kogral search <query> # Text search +kogral search --semantic <q> # Semantic search +kogral link <src> <dst> <rel> # Create relationship +kogral list [--type <type>] # List nodes +kogral show <id> # Display node details +kogral delete <id> # Remove node +kogral graph # Visualize graph (DOT format) +kogral sync # Sync filesystem ↔ SurrealDB +kogral serve # Start MCP server +kogral import <path> # Import from Logseq/markdown +kogral export <format> # Export to markdown/json +kogral config # Show/edit configuration +``` + +--- + +## 3. TypeDialog: Specifications + +### Workspace Structure + +```text +crates/ +β”œβ”€β”€ typedialog-core/ # Core (forms, backends, validation) +β”œβ”€β”€ typedialog/ # CLI binary +β”œβ”€β”€ typedialog-tui/ # TUI binary (ratatui) +β”œβ”€β”€ typedialog-web/ # Web binary (axum) +β”œβ”€β”€ typedialog-ai/ # AI backend (RAG, embeddings) +β”œβ”€β”€ typedialog-agent/ +β”‚ β”œβ”€β”€ typedialog-ag-core/ # Agent runtime +β”‚ └── typedialog-ag/ # Agent CLI +└── typedialog-prov-gen/ # IaC generation +``` + +### Form Definition (TOML) + +```toml +# employee_onboarding.toml +[form] +id = "employee_onboarding" +version = "1.0.0" +title = "Employee Onboarding" +description = "New employee registration form" + +[[sections]] +id = "personal" +title = "Personal Information" + +[[sections.fields]] +id = "full_name" +type = "text" +label = "Full Name" +required = true +validation.min_length = 2 +validation.max_length = 100 + +[[sections.fields]] +id = "department" +type = "select" +label = "Department" +required = true +options = [ + { value = "engineering", label = "Engineering" }, + { value = "product", label = "Product" }, + { value = "design", label = "Design" }, +] + +[[sections.fields]] +id = "skills" +type = "multi-select" +label = "Skills" +display_mode = "grid" +options = [ + { value = "rust", label = "Rust" }, + { value = "typescript", label = "TypeScript" }, + { value = "python", label = "Python" }, +] + +[[sections.fields]] +id = "start_date" +type = "date" +label = "Start Date" +default = "today" + +[output] +format = "json" +validation = "nickel://schemas/employee.ncl" +``` + +### Backend Trait + +```rust +// typedialog-core/src/backend.rs +#[async_trait] +pub trait Backend: Send + Sync { + fn name(&self) -> &str; + + async fn execute(&self, form: &Form) -> Result<FormResponse>; + + async fn render_field(&self, field: &Field, value: Option<&Value>) -> Result<Value>; + + fn supports_streaming(&self) -> bool { false } +} + +pub struct BackendFactory; + +impl BackendFactory { + pub fn create(backend_type: BackendType) -> Box<dyn Backend> { + match backend_type { + BackendType::Cli => Box::new(CliBackend::new()), + BackendType::Tui => Box::new(TuiBackend::new()), + BackendType::Web => Box::new(WebBackend::new()), + BackendType::Ai => Box::new(AiBackend::new()), + BackendType::Agent => Box::new(AgentBackend::new()), + BackendType::ProvGen => Box::new(ProvGenBackend::new()), + } + } +} +``` + +### Agent MDX Format + +```mdx +--- +name: code_reviewer +version: "1.0" +provider: claude +model: claude-sonnet-4-20250514 +temperature: 0.3 +max_tokens: 4096 +--- + +# Code Review Agent + +## System Prompt + +You are an expert code reviewer. Review the following code for: + +- Security vulnerabilities +- Performance issues +- Code style and best practices +- Potential bugs + +## Template Variables + +- `{{language}}`: Programming language +- `{{code}}`: Code to review +- `{{guidelines}}`: Project-specific guidelines + +## User Prompt + +Review this {{language}} code: + +` ` `{{language}} +{{code}} +` ` ` + +Project guidelines: + +{{guidelines}} + +Provide a structured review with severity levels (critical, warning, info). + +## Output Validation + +format: json +schema: | + { + "issues": [{ + "severity": "critical | warning | info", + "line": number, + "message": string, + "suggestion": string + }], + "summary": string + } +``` + +### Nickel Contract Integration + +```rust +// typedialog-core/src/nickel.rs +pub struct NickelValidator { + runtime: nickel_lang_core::eval::Runtime, +} + +impl NickelValidator { + pub fn validate(&self, data: &Value, contract_path: &str) -> Result<ValidationResult> { + let contract = self.runtime.load(contract_path)?; + let result = self.runtime.eval_with_contract(data, contract)?; + Ok(result) + } + + pub fn extract_schema(&self, contract_path: &str) -> Result<FormSchema> { + // Parse Nickel contract and generate form schema + let contract = self.runtime.load(contract_path)?; + FormSchema::from_nickel_contract(&contract) + } +} +``` + +### Prov-Gen Output + +```rust +// typedialog-prov-gen/src/generator.rs +pub enum CloudProvider { + Aws, + Gcp, + Azure, + Hetzner, + UpCloud, + Lxd, +} + +pub struct InfrastructureConfig { + pub provider: CloudProvider, + pub region: String, + pub resources: Vec<Resource>, + pub networking: NetworkConfig, + pub security: SecurityConfig, +} + +pub struct Generator { + templates: tera::Tera, + validators: Vec<Box<dyn Validator>>, // 7-layer validation +} + +impl Generator { + pub async fn generate(&self, config: &InfrastructureConfig) -> Result<GeneratedIaC> { + // 1. Validate input config + self.validate_config(config)?; + + // 2. Load provider-specific templates + let template = self.templates.get_template(&format!("{}.ncl.tera", config.provider))?; + + // 3. Render Nickel configuration + let nickel_code = template.render(&config)?; + + // 4. Validate generated Nickel + self.validate_nickel(&nickel_code)?; + + Ok(GeneratedIaC { + provider: config.provider, + code: nickel_code, + files: self.split_to_files(&nickel_code)?, + }) + } +} +``` + +--- + +## 4. Provisioning: Specifications + +### Directory Structure + +```text +provisioning/ +β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ cli/ # Main CLI (211 lines) +β”‚ β”œβ”€β”€ nulib/ # Nushell libraries (476+ accessors) +β”‚ └── scripts/ # Utility scripts +β”œβ”€β”€ extensions/ +β”‚ β”œβ”€β”€ providers/ # AWS, UpCloud, Local +β”‚ β”œβ”€β”€ taskservs/ # 50+ infrastructure services +β”‚ β”œβ”€β”€ clusters/ # Deployment templates +β”‚ └── workflows/ # Automation workflows +β”œβ”€β”€ platform/ +β”‚ β”œβ”€β”€ orchestrator/ # Workflow execution (Rust) +β”‚ β”œβ”€β”€ control-center/ # Backend (Axum + RBAC) +β”‚ β”œβ”€β”€ control-center-ui/ # Web dashboard (Leptos) +β”‚ β”œβ”€β”€ installer/ # Multi-mode installer +β”‚ β”œβ”€β”€ mcp-server/ # MCP server (Rust) +β”‚ β”œβ”€β”€ ai-service/ # AI operations +β”‚ β”œβ”€β”€ rag/ # RAG system +β”‚ β”œβ”€β”€ vault-service/ # Secrets management +β”‚ └── detector/ # Anomaly detection +└── schemas/ # Nickel IaC schemas +``` + +### Nickel IaC Schema + +```nickel +# schemas/server.ncl +let Server = { + name | String, + provider | [ | 'aws, 'upcloud, 'local |], + + spec | { + cpu | Number | default = 2, + memory_gb | Number | default = 4, + disk_gb | Number | default = 50, + + os | { + family | [ | 'ubuntu, 'debian, 'rocky |], + version | String, + }, + }, + + networking | { + vpc | String | optional, + subnet | String | optional, + public_ip | Bool | default = false, + security_groups | Array String | default = [], + }, + + tags | { _ : String } | default = {}, +} +in Server +``` + +### Orchestrator API + +```rust +// platform/orchestrator/src/lib.rs +pub struct Orchestrator { + state: StateManager, + executor: WorkflowExecutor, + scheduler: Scheduler, +} + +impl Orchestrator { + pub async fn execute_workflow(&self, workflow: Workflow) -> Result<ExecutionResult> { + // 1. Resolve dependencies (topological sort) + let ordered_tasks = self.resolve_dependencies(&workflow)?; + + // 2. Create execution checkpoints + let checkpoint = self.state.create_checkpoint(&workflow)?; + + // 3. Execute tasks with retry logic + for task in ordered_tasks { + match self.executor.run(&task).await { + Ok(result) => { + self.state.record_success(&task, &result)?; + } + Err(e) => { + // Exponential backoff retry + if let Some(result) = self.retry_with_backoff(&task).await? { + self.state.record_success(&task, &result)?; + } else { + // Rollback to checkpoint + self.state.rollback(&checkpoint)?; + return Err(e); + } + } + } + } + + Ok(ExecutionResult::from_state(&self.state)) + } +} +``` + +### MCP Tools + +```rust +// platform/mcp-server/src/tools.rs +pub const MCP_TOOLS: &[Tool] = &[ + Tool { + name: "query_infrastructure", + description: "Query infrastructure state using natural language", + parameters: json!({ + "query": { "type": "string" }, + "provider": { "type": "string", "optional": true } + }), + }, + Tool { + name: "generate_config", + description: "Generate Nickel configuration from description", + parameters: json!({ + "description": { "type": "string" }, + "provider": { "type": "string" }, + "resource_type": { "type": "string" } + }), + }, + Tool { + name: "validate_config", + description: "Validate Nickel configuration", + parameters: json!({ + "config": { "type": "string" }, + "strict": { "type": "boolean", "default": true } + }), + }, + Tool { + name: "estimate_cost", + description: "Estimate monthly cost for configuration", + parameters: json!({ + "config": { "type": "string" }, + "region": { "type": "string", "optional": true } + }), + }, + Tool { + name: "check_compliance", + description: "Check configuration against compliance rules", + parameters: json!({ + "config": { "type": "string" }, + "framework": { "type": "string", "enum": ["soc2", "hipaa", "gdpr", "pci"] } + }), + }, + Tool { + name: "plan_migration", + description: "Generate migration plan between configurations", + parameters: json!({ + "current": { "type": "string" }, + "target": { "type": "string" } + }), + }, + Tool { + name: "execute_workflow", + description: "Execute provisioning workflow", + parameters: json!({ + "workflow_id": { "type": "string" }, + "dry_run": { "type": "boolean", "default": true } + }), + }, +]; +``` + +### RAG Configuration + +```rust +// platform/rag/src/config.rs +pub struct RagConfig { + pub embedding_model: String, // "text-embedding-3-small" + pub embedding_dimensions: usize, // 1536 + pub chunk_size: usize, // 512 tokens + pub chunk_overlap: usize, // 50 tokens + pub top_k: usize, // 5 results + pub min_similarity: f32, // 0.7 + pub reranker: Option<RerankerConfig>, +} + +pub struct RagService { + embedder: Box<dyn Embedder>, + vector_store: Box<dyn VectorStore>, + keyword_index: tantivy::Index, +} + +impl RagService { + pub async fn query(&self, question: &str) -> Result<Vec<Document>> { + // 1. Generate embedding for question + let embedding = self.embedder.embed(question).await?; + + // 2. Vector similarity search + let vector_results = self.vector_store.search(&embedding, self.config.top_k).await?; + + // 3. BM25 keyword search + let keyword_results = self.keyword_search(question)?; + + // 4. Hybrid ranking (RRF) + let merged = self.reciprocal_rank_fusion(vector_results, keyword_results); + + // 5. Optional reranking + if let Some(reranker) = &self.reranker { + return reranker.rerank(&merged, question).await; + } + + Ok(merged) + } +} +``` + +--- + +## 5. SecretumVault: Specifications + +### General Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault (~11K LOC, 50+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (clap) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Core Types + +```rust +// src/core/vault.rs +pub struct VaultCore { + pub engines: HashMap<String, Box<dyn Engine>>, + pub storage: Arc<dyn StorageBackend>, + pub crypto: Arc<dyn CryptoBackend>, + pub seal: Arc<tokio::sync::Mutex<SealMechanism>>, + pub token_manager: Arc<TokenManager>, + pub metrics: Arc<Metrics>, +} + +// src/crypto/mod.rs +#[async_trait] +pub trait CryptoBackend: Send + Sync { + async fn generate_keypair(&self, algorithm: KeyAlgorithm) -> CryptoResult<KeyPair>; + async fn sign(&self, key: &PrivateKey, data: &[u8]) -> CryptoResult<Vec<u8>>; + async fn verify(&self, key: &PublicKey, data: &[u8], sig: &[u8]) -> CryptoResult<bool>; + async fn encrypt(&self, plaintext: &[u8]) -> CryptoResult<Vec<u8>>; + async fn decrypt(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; + + // Post-Quantum (OQS backend) + async fn kem_encapsulate(&self, public_key: &[u8]) -> CryptoResult<KemResult>; + async fn kem_decapsulate(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; +} + +// src/storage/mod.rs +#[async_trait] +pub trait StorageBackend: Send + Sync { + async fn store_secret(&self, path: &str, data: &EncryptedData) -> StorageResult<()>; + async fn get_secret(&self, path: &str) -> StorageResult<EncryptedData>; + async fn delete_secret(&self, path: &str) -> StorageResult<()>; + async fn list_secrets(&self, prefix: &str) -> StorageResult<Vec<String>>; +} +``` + +### Crypto Backends + +```rust +// src/crypto/backends/ +pub enum CryptoBackendType { + OpenSSL, // RSA, ECDSA, AES-256-GCM + Oqs, // ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) + AwsLc, // RSA, ECDSA (experimental PQC) + RustCrypto, // AES-GCM, ChaCha20-Poly1305 (testing) +} + +// OQS Post-Quantum (production-ready) +pub struct OqsBackend { + kem_algorithm: oqs::kem::Algorithm, // MlKem768 + sig_algorithm: oqs::sig::Algorithm, // MlDsa65 +} + +impl OqsBackend { + pub async fn kem_keygen(&self) -> CryptoResult<KemKeyPair> { + // ML-KEM-768: 1088 bytes ciphertext, 32 bytes shared secret + let kem = oqs::kem::Kem::new(self.kem_algorithm)?; + let (pk, sk) = kem.keypair()?; + Ok(KemKeyPair { public_key: pk, secret_key: sk }) + } + + pub async fn sign(&self, sk: &[u8], message: &[u8]) -> CryptoResult<Vec<u8>> { + // ML-DSA-65 signatures + let sig = oqs::sig::Sig::new(self.sig_algorithm)?; + let signature = sig.sign(message, sk)?; + Ok(signature.into_vec()) + } +} +``` + +### Secrets Engines + +```rust +// src/engines/mod.rs +pub trait Engine: Send + Sync { + fn name(&self) -> &str; + fn engine_type(&self) -> &str; + async fn read(&self, path: &str) -> Result<Option<Value>>; + async fn write(&self, path: &str, data: &Value) -> Result<()>; + async fn delete(&self, path: &str) -> Result<()>; + async fn list(&self, prefix: &str) -> Result<Vec<String>>; +} + +// Available engines +pub struct KvEngine { /* Versioned secret storage */ } +pub struct TransitEngine { /* Encryption-as-a-service */ } +pub struct PkiEngine { /* X.509 certificates */ } +pub struct DatabaseEngine { /* Dynamic credentials */ } +``` + +### Seal Mechanism (Shamir) + +```rust +// src/core/seal.rs +pub struct SealMechanism { + state: SealState, + shares: Vec<SecretShare>, + threshold: u8, + total_shares: u8, +} + +pub enum SealState { + Sealed, + Unsealing { collected: usize }, + Unsealed { master_key: Vec<u8> }, +} + +impl SealMechanism { + pub fn init(&mut self, shares: u8, threshold: u8) -> Result<Vec<SecretShare>> { + // Generate master key and split with Shamir + let master_key = generate_random_bytes(32)?; + let sharks = Sharks(threshold); + let dealer = sharks.dealer(&master_key); + let shares: Vec<_> = dealer.take(shares as usize).collect(); + self.state = SealState::Sealed; + Ok(shares) + } + + pub fn unseal(&mut self, share: SecretShare) -> Result<UnsealProgress> { + // Collect shares until threshold met + self.shares.push(share); + if self.shares.len() >= self.threshold as usize { + let sharks = Sharks(self.threshold); + let master_key = sharks.recover(&self.shares)?; + self.state = SealState::Unsealed { master_key }; + return Ok(UnsealProgress::Complete); + } + Ok(UnsealProgress::NeedMore { collected: self.shares.len() }) + } +} +``` + +### Authorization (Cedar ABAC) + +```rust +// src/auth/cedar.rs +pub struct CedarAuthorizer { + engine: cedar_policy::Authorizer, + policies: cedar_policy::PolicySet, +} + +impl CedarAuthorizer { + pub fn authorize(&self, request: &AuthzRequest) -> Result<Decision> { + let principal = self.build_principal(&request.user)?; + let action = self.build_action(&request.action)?; + let resource = self.build_resource(&request.resource)?; + + let decision = self.engine.is_authorized( + &principal, + &action, + &resource, + &self.policies, + )?; + + Ok(decision) + } +} +``` + +### API Endpoints + +```rust +// src/api/routes.rs +Router::new() + // System + .route("/v1/sys/health", get(health_check)) + .route("/v1/sys/init", post(initialize_vault)) + .route("/v1/sys/seal", post(seal_vault)) + .route("/v1/sys/unseal", post(unseal_vault)) + .route("/v1/sys/mounts", get(list_mounts)) + + // Secrets (dynamic routing by engine) + .route("/v1/*path", get(read_secret) + .post(write_secret) + .delete(delete_secret)) + + // Metrics + .route("/metrics", get(prometheus_metrics)) +``` + +### Configuration (TOML) + +```toml +# svault.toml +[vault] +crypto_backend = "oqs" # openssl | oqs | aws-lc | rustcrypto + +[server] +address = "0.0.0.0:8200" +tls_cert = "/path/to/cert.pem" +tls_key = "/path/to/key.pem" + +[storage] +backend = "etcd" # filesystem | etcd | surrealdb | postgresql + +[storage.etcd] +endpoints = ["http://localhost:2379"] + +[seal.shamir] +shares = 5 +threshold = 3 + +[auth] +token_ttl = "24h" +``` + +### CLI Commands + +```bash +# Server +svault server --config svault.toml + +# Operator +svault operator init --shares 5 --threshold 3 +svault operator unseal --share <share> +svault operator seal +svault operator status + +# Secrets +svault secret read secret/myapp +svault secret write secret/myapp key=value +svault secret delete secret/myapp +svault secret list secret/ +``` + +### Feature Flags + +```toml +# Cargo.toml features +[features] +default = ["openssl", "filesystem", "server", "pqc"] + +# Crypto backends +openssl = ["dep:openssl"] +aws-lc = ["dep:aws-lc-rs"] +pqc = ["dep:oqs"] +rustcrypto = ["dep:aes-gcm", "dep:chacha20poly1305"] + +# Storage backends +filesystem = [] +surrealdb-storage = ["dep:surrealdb"] +etcd-storage = ["dep:etcd-client"] +postgresql-storage = ["dep:sqlx"] + +# Components +server = ["dep:axum", "dep:rustls"] +cli = ["dep:clap"] +cedar = ["dep:cedar-policy"] +``` + +--- + +## 6. Integration Between Projects + +### Dependency Diagram + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Knowledge Graph) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + MCP (guidelines, patterns, decisions) + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Vapora β”‚ β”‚ TypeDialog β”‚ β”‚ Provisioning β”‚ +β”‚(Orchestrate)β”‚ β”‚ (Forms/UI) β”‚ β”‚ (IaC) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ β”‚ β”‚ + β”‚ β–Ό β–Ό β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ SecretumVault β”‚ β”‚ + β”‚ β”‚ (Secrets + PQC Crypto) β”‚ β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ SurrealDB β”‚ + β”‚ (Shared State) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Shared Dependencies (Cargo.toml) + +```toml +# Common dependencies across all projects +[dependencies] +# Runtime +tokio = { version = "1.48", features = ["full"] } + +# Serialization +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" + +# Database +surrealdb = "2.3" + +# Web +axum = "0.8" + +# LLM +rig-core = "0.15" + +# Config +nickel-lang-core = "1.15" + +# Logging +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] } + +# Error handling +anyhow = "1.0" +thiserror = "2.0" +``` + +### Shared SurrealDB Schema + +```sql +-- Shared namespace for cross-project state +DEFINE NAMESPACE portfolio; + +-- Scope for each project +DEFINE DATABASE vapora; +DEFINE DATABASE kogral; +DEFINE DATABASE typedialog; +DEFINE DATABASE provisioning; +DEFINE DATABASE secretumvault; + +-- Shared table for execution records +DEFINE TABLE executions SCHEMAFULL; +DEFINE FIELD project ON executions TYPE string; +DEFINE FIELD task_type ON executions TYPE string; +DEFINE FIELD agent_id ON executions TYPE string; +DEFINE FIELD status ON executions TYPE string; +DEFINE FIELD duration_ms ON executions TYPE int; +DEFINE FIELD tokens_used ON executions TYPE int; +DEFINE FIELD cost_cents ON executions TYPE float; +DEFINE FIELD created_at ON executions TYPE datetime DEFAULT time::now(); + +-- Indexes for cross-project queries +DEFINE INDEX idx_executions_project ON executions FIELDS project; +DEFINE INDEX idx_executions_agent ON executions FIELDS agent_id; +``` + +### Integration Example: Feature Development + +```rust +// Integrated feature development flow +async fn develop_feature(feature_spec: &str) -> Result<FeatureResult> { + // 1. Kogral: Get project context + let kogral_client = KogralMcpClient::connect().await?; + let guidelines = kogral_client.call("get_guidelines", json!({ + "topic": feature_spec, + "include_shared": true + })).await?; + + let patterns = kogral_client.call("search", json!({ + "query": feature_spec, + "node_type": "pattern", + "limit": 5 + })).await?; + + // 2. TypeDialog: Capture additional configuration + let typedialog = TypeDialog::new(BackendType::Cli); + let config = typedialog.execute_form("feature_config.toml").await?; + + // 3. Vapora: Orchestrate agents + let vapora_client = VaporaClient::new("http://localhost:8001"); + + // Create task with context + let task = vapora_client.create_task(TaskRequest { + title: format!("Implement: {}", feature_spec), + context: json!({ + "guidelines": guidelines, + "patterns": patterns, + "config": config, + }), + task_type: "feature_implementation", + }).await?; + + // Execute pipeline + let pipeline = vec![ + ("architect", "Design feature architecture"), + ("developer", "Implement feature"), + ("reviewer", "Review implementation"), + ("tester", "Write and run tests"), + ]; + + for (role, description) in pipeline { + vapora_client.assign_task(&task.id, role, description).await?; + vapora_client.wait_for_completion(&task.id).await?; + } + + // 4. Kogral: Record decision + kogral_client.call("add_decision", json!({ + "title": format!("Feature: {}", feature_spec), + "context": &task.context, + "decision": &task.result, + "consequences": "Implementation completed" + })).await?; + + // 5. Provisioning: Deploy if necessary + if config.requires_infra { + let prov_client = ProvisioningMcpClient::connect().await?; + prov_client.call("execute_workflow", json!({ + "workflow_id": config.deployment_workflow, + "dry_run": false + })).await?; + } + + Ok(FeatureResult { + task_id: task.id, + status: task.status, + }) +} +``` + +--- + +## 7. Quality Metrics + +| Project | Tests | Coverage | Clippy | Unsafe | Doc Coverage | +| ---------- | ------- | ----------- | -------- | -------- | -------------- | +| Vapora | 218 | ~70% | 0 warnings | 0 | 100% public | +| Kogral | 56 | ~80% | 0 warnings | 0 | 100% public | +| TypeDialog | 3,818 | ~85% | 0 warnings | 0 | 100% public | +| Provisioning | 218 | ~65% | 0 warnings | 0 | 100% public | +| SecretumVault | 50+ | ~75% | 0 warnings | 0 | 100% public | + +### Verification Commands + +```bash +# Per project +cargo clippy --all-targets --all-features -- -D warnings +cargo test --workspace +cargo doc --no-deps + +# Coverage (requires tarpaulin) +cargo tarpaulin --workspace --out Html + +# Benchmarks +cargo bench --workspace +``` + +--- + +*Document generated: 2026-01-22* +*Type: info (technical specifications)* diff --git a/docs/en/ia/ia-stratumiops-projects.md b/docs/en/ia/ia-stratumiops-projects.md new file mode 100644 index 0000000..c3b8b28 --- /dev/null +++ b/docs/en/ia/ia-stratumiops-projects.md @@ -0,0 +1,313 @@ +# AI Portfolio: Intelligent Development from Start to Finish + +## The Problem + +Development teams face critical challenges when integrating AI into their workflows: + +- **Scattered knowledge**: Decisions in Slack, patterns in wikis, guidelines in separate docs +- **AI agents without context**: Generate code that ignores project conventions +- **Uncontrolled LLM costs**: No visibility or limits per team or task +- **Manual infrastructure**: Repetitive configuration consuming valuable time +- **Fragmented interfaces**: One tool for CLI, another for web, another for TUI + +## The Solution: An Integrated Ecosystem + +Five projects designed to work together, each solving a specific problem. + +--- + +## Vapora: Intelligent Agent Orchestration + +### Agents that Learn from Experience + +Vapora is not just another agent framework. It's a system that **learns which agent is best for each task** based on previous executions. + +**How it works**: + +- Each execution builds an expertise profile by task type +- Last 7 days weigh 3x more than historical data (recency bias) +- New agents don't override experienced ones (confidence weighting) + +**Real cost control**: + +- Budgets per role (monthly/weekly) +- Three levels: normal β†’ near limit β†’ exceeded +- Automatic fallback to cheaper providers without manual intervention + +**For whom**: + +- Teams using multiple AI agents for development +- Organizations needing to control LLM spending +- Projects with code pipelines (architect β†’ developer β†’ reviewer β†’ tester) + +**Expected results**: + +- LLM cost reduction through intelligent routing +- Improved output quality by assigning agents based on expertise +- Complete visibility of spending and performance per agent + +--- + +## Kogral: The Team's Knowledge, Queryable + +### Your AI-Integrated Knowledge Base + +Kogral captures your team's decisions, patterns, and guidelines in a format that both humans and AI agents can query. + +**What makes it different**: + +- **6 specialized node types**: Notes, Decisions (ADRs), Guidelines, Patterns, Journals, Executions +- **Git-native**: Everything in versioned markdown, not in an external SaaS +- **MCP for Claude Code**: Your agents query guidelines before generating code + +**The flow**: + +```text +Developer makes decision β†’ Captures in Kogral as ADR + ↓ + Claude Code queries via MCP β†’ "Are there auth guidelines?" + ↓ + Kogral responds with project context + ↓ + Generated code follows team conventions +``` + +**For whom**: + +- Teams losing knowledge when members rotate +- Organizations with multiple projects needing consistent guidelines +- Developers using Claude Code wanting project context + +**Expected results**: + +- Onboarding new members in days, not weeks +- AI-generated code respecting conventions +- Architectural decisions preserved and searchable + +--- + +## TypeDialog: One Definition, Six Interfaces + +### Forms that Work Everywhere + +Define a form once in TOML. Execute it in CLI, TUI, Web, or let an AI agent complete it. + +**Available backends**: + +| Backend | Typical use | +| --------- | ----------- | +| **CLI** | Automation scripts, CI/CD | +| **TUI** | Admin tools, terminal dashboards | +| **Web** | SaaS applications, public forms | +| **AI** | Semantic search, RAG over documentation | +| **Agent** | Agent execution from .agent.mdx files | +| **Prov-gen** | Multi-cloud infrastructure generation | + +**The flow**: + +```text +employee_onboarding.toml + ↓ + TypeDialog + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β” +CLI TUI Web Agent +β”‚ β”‚ β”‚ β”‚ +β–Ό β–Ό β–Ό β–Ό +Same validated result with Nickel contracts +``` + +**For whom**: + +- Teams maintaining the same logic in CLI and Web +- DevOps needing configuration wizards +- Organizations with multi-language forms + +**Expected results**: + +- Single definition for all interfaces +- Typed validation before runtime +- Forms that execute LLM agents directly + +--- + +## Provisioning: Infrastructure with AI + +### Declarative IaC + AI-Assisted Generation + +Provisioning combines the precision of typed configuration (Nickel) with AI assistance to generate and validate infrastructure. + +**Unique capabilities**: + +- **Nickel IaC**: Typed configuration with lazy evaluation, not YAML +- **MCP Server**: Natural language queries about infrastructure +- **Integrated RAG**: 1,200+ domain documents for contextual responses +- **Multi-cloud**: AWS, UpCloud, local from the same definition + +**Enterprise security**: + +- JWT + MFA (TOTP + WebAuthn) +- Cedar policy engine for RBAC +- 7-year audit log retention +- 5 KMS backends (RustyVault, Age, AWS KMS, Vault, Cosmian) + +**The flow**: + +```text +"I need a K8s cluster on AWS with 3 nodes" + ↓ + MCP Server (NLP) + ↓ + RAG searches similar configurations + ↓ + Generates Nickel + validates types + ↓ + Orchestrator deploys with rollback +``` + +**For whom**: + +- DevOps teams wanting typed IaC, not fragile YAML +- Multi-cloud organizations (AWS + others) +- Teams needing audit and compliance + +**Expected results**: + +- Configuration errors caught at compile time, not runtime +- Infrastructure generated from natural language +- Automatic rollback on failures + +--- + +## SECRETUMVAULT: Secrets with Post-Quantum Cryptography + +### The First Production-Ready Rust Vault with PQC + +SecretumVault is a secrets management system implementing **production-ready post-quantum cryptography** (ML-KEM-768, ML-DSA-65). + +**Crypto agnostic**: + +- **OpenSSL**: RSA, ECDSA, AES-256-GCM (classic compatibility) +- **OQS (Post-Quantum)**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) +- **Pluggable backends**: Change algorithms without modifying code + +**Secrets engines**: + +| Engine | Capability | +| ------- | ----------- | +| **KV** | Versioned secret storage | +| **Transit** | Encryption-as-a-service with key rotation | +| **PKI** | X.509 certificate generation | +| **Database** | Dynamic credentials with TTL | + +**Multi-backend storage**: + +- Filesystem (development, single-node) +- etcd (Kubernetes, high availability) +- SurrealDB (complex queries, time-series) +- PostgreSQL (enterprise, ACID) + +**Enterprise security**: + +- Shamir Secret Sharing for unsealing +- Cedar policy engine (ABAC) +- Native TLS/mTLS +- Complete audit logging + +**For whom**: + +- Teams deploying post-quantum cryptography today +- Organizations with cryptographic agility requirements +- Multi-cloud platforms needing Rust-native secrets management + +**Expected results**: + +- Preparation for quantum threats without architecture changes +- Secrets management with Rust memory guarantees +- Native integration with the ecosystem (Provisioning, Vapora) + +--- + +## The Ecosystem in Action + +### Scenario: New Feature with AI + +```text +1. Kogral provides guidelines and patterns to Claude Code via MCP +2. Vapora coordinates agents: Architect designs β†’ Developer implements β†’ Reviewer validates +3. TypeDialog captures necessary configurations with Nickel validation +4. SecretumVault manages credentials and feature secrets +5. Kogral records decisions made during development +6. Provisioning deploys required infrastructure changes +``` + +### Scenario: New Developer Onboarding + +```text +1. Kogral exports project knowledge graph +2. TypeDialog presents interactive architecture quiz +3. Vapora assigns progressive onboarding tasks +4. Provisioning automatically configures development environment +``` + +### Scenario: Multi-Cloud Migration + +```text +1. Kogral documents migration ADRs +2. TypeDialog validates configuration parameters +3. Provisioning executes migration with checkpoints +4. Vapora orchestrates agents for monitoring and reporting +``` + +--- + +## Why Choose This Ecosystem + +### Versus Alternatives + +| Us | Alternatives | +| ---------- | -------------- | +| **Rust native**: Performance, no GC, type-safe | Python: GIL, optional typing | +| **Nickel configs**: Pre-runtime validation | YAML/JSON: Runtime errors | +| **Execution learning**: Agents improve | LangChain: Static chains | +| **MCP integrated**: Context for Claude Code | No native integration | +| **Budget control**: Automatic fallback | Manual cost control | +| **Native multi-tenant**: SurrealDB scopes | Manual isolation | + +### Technical Investment + +| Metric | Value | +| --------- | ------- | +| Rust Crates | 40+ | +| Tests | 4,360+ | +| Lines of code | ~206K | +| LLM Providers | Claude, OpenAI, Gemini, Ollama | +| MCP Tools | 14+ | +| Crypto backends | OpenSSL, OQS (PQC), AWS-LC | + +--- + +## Getting Started + +### Recommended Progressive Adoption + +1. **Kogral**: Establish knowledge base (standalone, no dependencies) +2. **TypeDialog**: Enable structured inputs and validation +3. **SecretumVault**: Secrets management with modern cryptography +4. **Vapora**: Orchestrate agents with Kogral context +5. **Provisioning**: Infrastructure informed by the ecosystem + +Each project works independently. Synergies emerge when combining them. + +--- + +## Contact + +- **Repositories**: GitHub (private projects) +- **Stack**: Rust, Nickel, SurrealDB, Axum, Leptos +- **License**: Proprietary / To be defined + +--- + +*AI-assisted development shouldn't require 10 disconnected tools.* +*One ecosystem. Five projects. Real integration.* diff --git a/docs/en/ops/README.md b/docs/en/ops/README.md new file mode 100644 index 0000000..462da91 --- /dev/null +++ b/docs/en/ops/README.md @@ -0,0 +1,37 @@ +# Operations Portfolio Documentation + +Documentation for STRATUM's infrastructure automation and deployment tools. + +## Projects + +### Provisioning + +Multi-cloud infrastructure as code. + +- Declarative infrastructure definitions +- Multi-cloud support (AWS, Azure, GCP, bare metal) +- GitOps workflow integration +- State management and drift detection +- Rollback and validation + +### SecretumVault + +Secure secrets management. + +- Multi-tenant secret storage +- Fine-grained access control +- Audit logging and compliance +- Integration with CI/CD pipelines +- Encryption at rest and in transit + +## Documentation Files + +- [**ops-stratumiops-projects.md**](ops-stratumiops-projects.md) - Complete overview of operations portfolio projects +- [**ops-stratumiops-projects-positioning.md**](ops-stratumiops-projects-positioning.md) - Market positioning and competitive analysis +- [**ops-stratumiops-projects-technical-specs.md**](ops-stratumiops-projects-technical-specs.md) - Technical specifications, API documentation, and architecture + +## Navigation + +- [Back to English docs](../) +- [Back to root documentation](../../) +- [AI portfolio](../ia/) diff --git a/docs/en/ops/ops-stratumiops-projects-positioning.md b/docs/en/ops/ops-stratumiops-projects-positioning.md new file mode 100644 index 0000000..fb28ddb --- /dev/null +++ b/docs/en/ops/ops-stratumiops-projects-positioning.md @@ -0,0 +1,623 @@ +# Ops/DevOps Portfolio: Strategic Positioning + +## Executive Summary + +This document analyzes the five-project portfolio from the Ops/DevOps perspective, positioning them against established market tools: + +| Project | Domain | Competes With | +| --------- | -------- | --------------- | +| **Provisioning** | IaC + Orchestration | Terraform, Pulumi, Ansible, CloudFormation | +| **SecretumVault** | Secrets Management | HashiCorp Vault, AWS Secrets Manager, Azure Key Vault | +| **Vapora** | Agent Orchestration | Jenkins, GitHub Actions, Tekton, ArgoCD | +| **TypeDialog** | Configuration + IaC Gen | Terraform modules, Cookiecutter, Yeoman | +| **Kogral** | Knowledge Management | Confluence, Notion, Internal wikis | + +--- + +## 1. Ops Functionality Matrix + +### Capabilities per Project + +| Capability | Provisioning | SecretumVault | Vapora | TypeDialog | Kogral | +| ------------ | -------------- | --------------- | -------- | ------------ | -------- | +| **Multi-cloud** | AWS, UpCloud, Local | N/A (storage agnostic) | N/A | Yes (prov-gen) | N/A | +| **Declarative IaC** | Nickel (typed) | N/A | N/A | Generates Nickel | N/A | +| **Secrets management** | Integrates KMS | βœ… 4 engines | Uses vault | N/A | N/A | +| **Orchestration** | Rust orchestrator | N/A | NATS JetStream | N/A | N/A | +| **Post-Quantum Crypto** | Via SecretumVault | βœ… ML-KEM/ML-DSA | N/A | N/A | N/A | +| **Automatic rollback** | βœ… Checkpoints | N/A | Pipeline rollback | N/A | N/A | +| **Policy engine** | Cedar RBAC/ABAC | Cedar ABAC | Cedar multi-tenant | N/A | N/A | +| **Audit logging** | 7 years retention | βœ… Complete | βœ… SurrealDB | N/A | Git history | +| **AI-assisted** | MCP + RAG | N/A | LLM routing | Agent backend | MCP search | +| **REST API** | Axum control-center | Axum vault API | Axum backend | Axum web backend | N/A (MCP) | +| **Storage backends** | SurrealDB | FS/etcd/SurrealDB/PostgreSQL | SurrealDB + NATS | Multi-format | FS + SurrealDB | +| **CLI** | 80+ shortcuts | svault CLI | vapora CLI | typedialog CLI | kogral CLI | + +### Common Technology Stack (Ops Perspective) + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SHARED TECHNOLOGIES β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Language: Rust (performance, memory-safety) β”‚ +β”‚ Config: Nickel (pre-runtime validation, lazy eval) β”‚ +β”‚ DB: SurrealDB (multi-model, scopes, time-series) β”‚ +β”‚ Web: Axum (async, composable routing) β”‚ +β”‚ Messaging: NATS JetStream (at-least-once, persistence) β”‚ +β”‚ Policy: Cedar (ABAC, AWS-compatible) β”‚ +β”‚ Crypto: OpenSSL, OQS (PQC), AWS-LC, RustCrypto β”‚ +β”‚ Logging: tracing (structured, JSON output) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Positioning vs Competition (Ops Tools) + +### Provisioning vs Terraform + +| Aspect | Provisioning | Terraform | +| -------- | -------------- | ----------- | +| **IaC Language** | Nickel (typed, lazy) | HCL (untyped) | +| **Validation** | Pre-runtime (compilation) | Runtime (terraform plan) | +| **Multi-cloud** | AWS, UpCloud, Local | Yes (100+ providers) | +| **AI native** | MCP + RAG (1000x Python) | Terraform Cloud AI (limited) | +| **Orchestration** | Rust hybrid orchestrator | State file + lock | +| **Rollback** | Automatic with checkpoints | Manual (terraform destroy) | +| **Security** | 39K lines (12 components) | Vault plugin, external | +| **Ecosystem** | ⚠️ Small | βœ… Huge (Terraform Registry) | +| **Learning curve** | High (Nickel + Nushell) | Moderate (familiar HCL) | +| **Best For** | Rust teams, typed IaC, AI-assisted | General use, large ecosystem | + +**Key differentiator**: Provisioning combines typed declarative IaC (Nickel) with AI-assisted generation (MCP + RAG) and hybrid Rust/Nushell orchestration, eliminating configuration errors at compile time. + +### Provisioning vs Pulumi + +| Aspect | Provisioning | Pulumi | +| -------- | -------------- | -------- | +| **IaC Language** | Nickel (functional) | TypeScript/Python/Go | +| **Paradigm** | Declarative | Imperative (code) | +| **State management** | SurrealDB multi-model | Pulumi Cloud / self-hosted | +| **Secrets** | SecretumVault integrated | Pulumi ESC (SaaS) | +| **Multi-cloud** | AWS, UpCloud, Local | Yes (100+ providers) | +| **AI-assisted** | MCP + RAG native | Pulumi AI (experimental) | +| **Testing** | Nickel contracts | Unit tests in code | +| **Best For** | Pure declarative, typed IaC | Developers, imperative code | + +**Key differentiator**: Provisioning is pure declarative (Nickel) vs imperative (Pulumi code), with pre-runtime validation and Rust orchestrator for complex workflows. + +### Provisioning vs Ansible + +| Aspect | Provisioning | Ansible | +| -------- | -------------- | --------- | +| **Paradigm** | Declarative (Nickel IaC) | Imperative (playbooks) | +| **Agentless** | Yes (SSH) | Yes (SSH) | +| **Idempotence** | Nickel contracts | YAML tasks (depends on module) | +| **Performance** | Rust orchestrator (10-50x) | Python interpreter | +| **Multi-cloud** | AWS, UpCloud, Local | Yes (cloud modules) | +| **Dependency resolution** | Automatic topological sort | Manual (pre_tasks, post_tasks) | +| **Rollback** | Automatic with checkpoints | Manual (rescue blocks) | +| **Best For** | Typed IaC, critical performance | Configuration management, ad-hoc | + +**Key differentiator**: Provisioning is declarative IaC (not imperative playbooks) with Rust orchestrator 10-50x faster than Python, automatic rollback and topological dependency resolution. + +### SecretumVault vs HashiCorp Vault + +| Aspect | SecretumVault | HashiCorp Vault | +| -------- | --------------- | ----------------- | +| **Language** | Rust (memory-safe) | Go (CGO overhead) | +| **Post-Quantum** | βœ… **ML-KEM-768, ML-DSA-65** | ❌ No roadmap | +| **Crypto backends** | 4 (OpenSSL, **OQS**, AWS-LC, RustCrypto) | 1 (OpenSSL) | +| **Storage backends** | 4 (FS, etcd, SurrealDB, PostgreSQL) | 10+ (etcd, Consul, S3, etc) | +| **Policy engine** | Cedar ABAC (AWS-compatible) | HCL policies | +| **Shamir unsealing** | βœ… Native | βœ… Native | +| **Secrets engines** | 4 (KV, Transit, PKI, Database) | 10+ (includes cloud-specific) | +| **Ecosystem** | ⚠️ Small | βœ… Huge (plugins, integrations) | +| **License** | Apache-2.0 | BSL (Enterprise paywall) | +| **Best For** | **PQC today**, Rust stacks, data sovereignty | General use, mature ecosystem | + +**Key differentiator**: SecretumVault is the **only Rust vault with production-ready post-quantum cryptography** (ML-KEM-768, ML-DSA-65 NIST FIPS 203/204), providing cryptographic agility for organizations deploying today. + +### SecretumVault vs AWS Secrets Manager + +| Aspect | SecretumVault | AWS Secrets Manager | +| -------- | --------------- | --------------------- | +| **Multi-cloud** | βœ… Any cloud or on-premise | ❌ AWS-only | +| **Self-hosted** | βœ… Full control | ❌ SaaS only | +| **Post-Quantum** | βœ… **ML-KEM + ML-DSA** | ❌ None | +| **Crypto backends** | 4 pluggable | 1 (AWS KMS) | +| **Dynamic secrets** | βœ… Database engine | βœ… RDS integration | +| **Vendor lock-in** | βœ… Portable | ⚠️ High (AWS-specific) | +| **Cost** | Self-hosted (infra cost) | $0.40/secret/month + API calls | +| **Best For** | Multi-cloud, **PQC**, data sovereignty | AWS-native apps, managed service | + +**Key differentiator**: SecretumVault is multi-cloud and self-hosted with native PQC, vs AWS Secrets Manager cloud-only without post-quantum roadmap. + +### Vapora vs Jenkins + +| Aspect | Vapora | Jenkins | +| -------- | -------- | --------- | +| **Paradigm** | Agent orchestration (AI) | Pipeline orchestration (CI/CD) | +| **Agents** | LLM-powered (Claude, GPT, Gemini) | Build agents (workers) | +| **Orchestration** | NATS JetStream | Master-worker | +| **Learning** | Expertise profiles, recency bias | No (static) | +| **Budget control** | Per-role limits, fallback | N/A | +| **Pipeline definition** | Tasks + agent roles | Jenkinsfile (Groovy) | +| **UI** | Leptos WASM (Kanban) | Web UI (Java) | +| **Best For** | AI-assisted operations, LLM orchestration | Traditional CI/CD, build automation | + +**Key differentiator**: Vapora orchestrates **intelligent LLM agents** with learning and cost control, not traditional build agents. + +### Vapora vs GitHub Actions + +| Aspect | Vapora | GitHub Actions | +| -------- | -------- | ---------------- | +| **Self-hosted** | βœ… Kubernetes native | βœ… Self-hosted runners | +| **Agents** | LLM-powered with roles | Workflow runners | +| **Orchestration** | NATS JetStream | GitHub infrastructure | +| **Learning** | Expertise profiles | No (static) | +| **Budget control** | LLM cost limits | Minutes-based billing | +| **Multi-tenant** | SurrealDB scopes + Cedar | Repository-level | +| **Best For** | AI operations, agent coordination | GitHub-native CI/CD, simple workflows | + +**Key differentiator**: Vapora is an AI agent orchestration platform with learning, not a CI/CD workflow runner. + +### TypeDialog (prov-gen) vs Terraform Modules + +| Aspect | TypeDialog (prov-gen) | Terraform Modules | +| -------- | ----------------------- | ------------------- | +| **Input method** | TOML forms (CLI/TUI/Web) | Variables (.tfvars) | +| **Validation** | Nickel contracts (pre-runtime) | Variable validation (runtime) | +| **Output format** | Nickel IaC | HCL | +| **Multi-backend** | 6 (CLI/TUI/Web/AI/Agent/Prov-gen) | CLI only | +| **IaC generation** | Tera templates + validation | Module composition | +| **Best For** | Interactive wizards, self-service | Reusable modules, Terraform ecosystem | + +**Key differentiator**: TypeDialog unifies input capture (CLI/TUI/Web) with validated IaC generation (Nickel), not just reusable modules. + +### Kogral vs Confluence + +| Aspect | Kogral | Confluence | +| -------- | -------- | ------------ | +| **Target** | Development/ops teams | General teams | +| **Git-native** | βœ… Markdown + YAML frontmatter | ❌ Cloud/Server | +| **Node types** | 6 specialized (ADR, Pattern, etc) | Generic pages | +| **MCP Server** | βœ… Claude Code native | ❌ No | +| **Semantic search** | fastembed + cloud embeddings | Internal search | +| **Self-hosted** | βœ… Filesystem + SurrealDB | Cloud or Data Center | +| **Best For** | Dev/Ops knowledge, AI integration | General documentation, wikis | + +**Key differentiator**: Kogral is specifically designed for technical knowledge (runbooks, ADRs, postmortems) with native AI integration via MCP. + +--- + +## 3. Use Cases and Context (Ops Perspective) + +### When to Use Each Project + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ "I need to provision multi-cloud infrastructure with IaC" β”‚ +β”‚ β†’ Provisioning (Nickel IaC, multi-cloud, orchestrator) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "I want secrets management with post-quantum preparation" β”‚ +β”‚ β†’ SecretumVault (PQC ML-KEM/ML-DSA, 4 crypto backends) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "I need to orchestrate AI agents for operational tasks" β”‚ +β”‚ β†’ Vapora (DevOps/Monitor/Security agents, NATS, budget) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "I want configuration wizards that generate IaC" β”‚ +β”‚ β†’ TypeDialog (prov-gen backend, CLI/TUI/Web) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "I need to preserve runbooks and incident postmortems" β”‚ +β”‚ β†’ Kogral (6 node types, MCP, git-native) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Decision Matrix by Ops Context + +| Context | Main Project | Supporting Projects | +| --------- | -------------- | --------------------- | +| **Multi-cloud provisioning** | Provisioning | TypeDialog (wizards), SecretumVault (certs), Kogral (ADRs) | +| **PQC secrets management** | SecretumVault | Provisioning (infrastructure), Kogral (policies) | +| **Incident response** | Vapora (Monitor/DevOps agents) | Kogral (runbooks/postmortems), SecretumVault (credentials) | +| **CI/CD automation** | Vapora (DevOps agent) | Provisioning (deploy), SecretumVault (secrets), Kogral (guidelines) | +| **Infrastructure self-service** | TypeDialog (prov-gen) | Provisioning (apply IaC), Kogral (docs) | +| **Knowledge preservation** | Kogral | Vapora (execution tracking), TypeDialog (export) | +| **Disaster recovery** | Provisioning (rollback) | SecretumVault (backup), Kogral (procedures) | + +--- + +## 4. Why They Are Necessary (Ops Perspective) + +### Problems They Solve + +#### Provisioning: The Fragile YAML Problem + +``` +BEFORE AFTER (Provisioning) +───────────────────────────────── ───────────────────────────────── +Untyped YAML, runtime errors Typed Nickel, compile-time errors +Fragile imperative scripts Declarative workflows with rollback +Terraform state drift SurrealDB with time-series +No AI assistance MCP + RAG (1000x Python) +Manual dependency management Automatic topological sort +``` + +#### SecretumVault: The Quantum Cryptography Problem + +``` +BEFORE AFTER (SecretumVault) +───────────────────────────────── ───────────────────────────────── +Vault in Go (no memory-safety) Rust with memory guarantees +Classical crypto only (vulnerable) Post-quantum (ML-KEM, ML-DSA) +Fixed crypto backend Pluggable backends (agility) +SaaS lock-in (AWS, Azure) Complete self-hosted +No quantum threat preparation Deploy PQC today, gradual migration +``` + +#### Vapora: The Manual Ops Coordination Problem + +``` +BEFORE AFTER (Vapora) +───────────────────────────────── ───────────────────────────────── +Ad-hoc scripts without coordination NATS JetStream orchestration +LLMs without cost control Budget enforcement + fallback +Agents without historical context Expertise profiles + recency bias +Manual handoffs (deploy β†’ monitor) Automated pipelines with roles +No execution visibility Prometheus metrics + SurrealDB +``` + +#### TypeDialog (prov-gen): The Manual Configuration Problem + +``` +BEFORE AFTER (TypeDialog) +───────────────────────────────── ───────────────────────────────── +Error-prone manual configuration Validated forms (Nickel) +CLI β‰  Web β‰  TUI interfaces 1 TOML β†’ 6 backends +No IaC generation prov-gen β†’ multi-cloud Nickel +Runtime validation Pre-runtime validation (contracts) +``` + +#### Kogral: The Lost Ops Knowledge Problem + +``` +BEFORE AFTER (Kogral) +───────────────────────────────── ───────────────────────────────── +Scattered Confluence runbooks Git-native, versioned +Unsearchable postmortems Semantic search + MCP +Lost infrastructure ADRs Decision nodes with relationships +Incidents without historical context Execution nodes with timeline +SRE onboarding takes weeks Semantic search in days +``` + +--- + +## 5. What Makes Them Different (Ops Perspective) + +### Unique Features per Project + +#### Provisioning + +1. **Nickel IaC**: Only with lazy-eval typed language as primary (not HCL, not YAML) +2. **Hybrid orchestrator**: Rust (performance) + Nushell (flexibility) +3. **MCP 1000x faster**: Rust-native vs Python implementations +4. **39K lines security**: 12 enterprise components (JWT, Cedar, MFA, audit, KMS) +5. **80+ CLI shortcuts**: Optimized developer experience with guided wizards + +#### SecretumVault + +1. **Native Post-Quantum**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) **production-ready today** +2. **4 crypto backends**: OpenSSL, **OQS**, AWS-LC, RustCrypto (cryptographic agility without code changes) +3. **4 storage backends**: Filesystem, etcd, SurrealDB, PostgreSQL (deployment flexibility) +4. **Shamir Secret Sharing**: Distributed unsealing with configurable threshold (3-of-5, 5-of-7, etc) +5. **Cedar ABAC**: AWS-compatible authorization policies (portable, no vendor lock-in) + +#### Vapora + +1. **Learning-based selection**: Scoring `0.3*load + 0.5*expertise + 0.2*confidence` with 3x recency bias (last 7 days) +2. **Budget enforcement**: Per-role hard caps (monthly/weekly) with automatic fallback to cheaper providers +3. **NATS JetStream**: At-least-once coordination, message persistence, distributed +4. **12 agent roles**: Architect, Developer, CodeReviewer, Tester, Documenter, Marketer, Presenter, **DevOps**, **Monitor**, **Security**, ProjectManager, DecisionMaker +5. **Native multi-tenant**: SurrealDB scopes + Cedar RBAC, complete isolation + +#### TypeDialog + +1. **6 unified backends**: CLI/TUI/Web/AI/Agent/**Prov-gen** from same TOML +2. **Prov-gen IaC generation**: AWS/GCP/Azure/Hetzner/UpCloud from typed forms +3. **Nickel contracts**: Pre-runtime validation with type-safe schemas +4. **3,818 tests**: Exhaustive coverage (503% growth), production-ready +5. **Native multi-language**: Fluent bundles for i18n without reimplementing logic + +#### Kogral + +1. **6 specialized node types**: Note, Decision (ADR), Guideline, Pattern, Journal, **Execution** (for ops/incidents) +2. **Hybrid embeddings**: Local fastembed (privacy) + cloud (production) +3. **Native MCP**: 7 tools for Claude Code, no extra configuration required +4. **Git-native**: Everything versioned markdown, no external SaaS, full control +5. **Guideline inheritance**: Org β†’ Project with priority, cross-team consistency + +--- + +## 6. Synergies and Reuse (Ops Workflows) + +### Ops Integration Flow + +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Runbooks, ADRs) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ Operational knowledge + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TypeDialog │───▢│ Vapora │───▢│ Provisioning β”‚ +β”‚ (Wizards) β”‚ β”‚ (Ops Agents) β”‚ β”‚ (IaC Deploy) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ Configuration β”‚ Orchestration β”‚ Infrastructure + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SECRETUMVAULT β”‚ +β”‚ PKI certs β”‚ Dynamic DB creds β”‚ API keys β”‚ Encryption β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Reusable Components (Ops Stack) + +| Component | Origin | Reused In | +| ----------- | -------- | ----------- | +| **SurrealDB schemas** | Vapora | Kogral, Provisioning, SecretumVault (optional) | +| **Nickel contracts** | Provisioning | TypeDialog (prov-gen validation) | +| **Cedar policies** | Provisioning | SecretumVault, Vapora (multi-tenant) | +| **Axum API patterns** | Vapora | Provisioning (control-center), SecretumVault (vault API) | +| **tracing setup** | Vapora | All (structured logging) | +| **Crypto backends** | SecretumVault | Provisioning (KMS integration) | +| **NATS patterns** | Vapora | Provisioning (future messaging), SecretumVault (HA) | + +### Synergy Scenarios (Ops Workflows) + +#### Scenario 1: Zero-Touch Provisioning with AI + +``` +1. TypeDialog (prov-gen): SRE completes web wizard + - Cloud provider, region, cluster size, services + - Generates Nickel IaC validated with contracts + +2. Kogral: MCP provides deployment guidelines + - "What is our cluster naming policy?" + - "What security groups do we apply by default?" + +3. Provisioning: Orchestrator deploys infrastructure + - Servers β†’ networking β†’ storage β†’ services + - Checkpoints per step, automatic rollback if fails + +4. SecretumVault: Generates certificates and secrets + - PKI engine: etcd, kube-apiserver, kubelet certs (ML-DSA-65 PQC) + - Database engine: PostgreSQL dynamic credentials (TTL 1h) + +5. Vapora: Post-deployment automation + - Monitor Agent: Setup Prometheus alerts, health checks + - Security Agent: Vulnerability scan, compliance check + - DevOps Agent: Deploy baseline apps (Ingress, cert-manager) + +6. Kogral: Documents deployment + - Execution node with timestamp, created resources, configuration + - Links to architecture ADRs, maintenance runbooks +``` + +#### Scenario 2: Automated Incident Response + +``` +1. Vapora Monitor Agent: Detects anomaly (PostgreSQL down) + - Alert via NATS JetStream + - Trigger incident response pipeline + +2. Kogral: Claude Code queries runbooks via MCP + - search("postgresql outage troubleshooting") + - Returns 3 similar postmortems with resolutions + +3. Vapora DevOps Agent: Executes automated runbook + - Verify PostgreSQL process (systemctl status) + - Check logs (/var/log/postgresql) + - Restart if needed with adjusted parameters + +4. SecretumVault: Rotates compromised credentials + - Database engine generates new dynamic credentials + - Updates connected apps via secret injection + +5. Vapora Security Agent: Post-incident audit + - Review access logs, configuration changes + - Generate compliance report + +6. Kogral: Documents postmortem + - Execution node with root cause, timeline, resolution + - Links to PostgreSQL configuration ADRs + - Action items to prevent recurrence +``` + +#### Scenario 3: Gradual Post-Quantum Migration + +``` +1. Kogral: Documents strategic decision + - ADR: "Gradual migration to post-quantum cryptography" + - Rationale: Preparation for quantum threats (harvest now, decrypt later) + - Timeline: Q1 2026 testing, Q2 2026 staging, Q3 2026 production + +2. SecretumVault: Migrates secrets in staging + - Backend switch: openssl β†’ oqs (ML-KEM-768) + - Re-encrypts existing secrets with PQC + - Dual-stack: classical for legacy, PQC for new services + +3. Provisioning: Updates PKI infrastructure + - Generates new certificates with ML-DSA-65 (PQC signatures) + - Deploys certificates to services (etcd, K8s API, service mesh) + - Health checks: latency not degraded, handshakes correct + +4. Vapora: Orchestrates comprehensive validation + - Security Agent: Verifies correct cryptographic algorithms + - Monitor Agent: Benchmark latency (PQC vs classical) + - DevOps Agent: Integration tests with PQC certificates + +5. TypeDialog: Self-service portal for teams + - Form: "Migrate service to PQC" + - Input: service name, migration strategy (gradual/immediate) + - prov-gen: Generates updated configuration (Nickel) + +6. Kogral: Migration tracking + - Execution nodes per migrated service + - Metrics: services migrated, performance impact, issues + - Lessons learned: what worked, what to improve +``` + +#### Scenario 4: Multi-Cloud Disaster Recovery + +``` +1. Kogral: Disaster recovery runbook + - Procedure: "Failover from AWS to UpCloud in <1h" + - Prerequisites, detailed steps, validation + +2. Vapora: Automatic trigger (AWS region down) + - Monitor Agent detects regional outage + - ProjectManager Agent declares disaster recovery mode + - DevOps Agent executes Kogral runbook + +3. Provisioning: Deploys replica on UpCloud + - Multi-cloud Nickel IaC (change: provider = "upcloud") + - Orchestrator deploys: servers β†’ networking β†’ K8s β†’ apps + - Checkpoints: rollback to AWS if UpCloud also fails + +4. SecretumVault: Synchronizes secrets + - Cross-region etcd replication (AWS β†’ UpCloud) + - PKI engine generates certificates for UpCloud region + - Database engine: new DB dynamic credentials + +5. TypeDialog: DNS failover wizard + - Form: Update DNS records (Route53 β†’ NS1) + - Validation: TTL check, propagation time + +6. Kogral: Documents incident + - Execution node: timeline, decisions, metrics + - RTO achieved, RPO achieved, issues encountered + - Postmortem: what to improve in runbook +``` + +--- + +## 7. Dependencies and Adoption Order (Ops Teams) + +### Dependency Graph + +``` + SecretumVault (standalone) + β”‚ + β”‚ provides secrets to + β–Ό +Kogral ◄────────────────────────► Provisioning +(standalone) (can integrate vault) + β”‚ β”‚ + β”‚ provides runbooks to β”‚ deploys infrastructure for + β–Ό β–Ό + Vapora + (integrates all) + β”‚ + β”‚ uses wizards from + β–Ό + TypeDialog + (prov-gen β†’ Provisioning) +``` + +### Recommended Adoption Order (Ops Perspective) + +| Phase | Project | Reason | Dependencies | +| ------- | --------- | -------- | -------------- | +| 1 | **SecretumVault** | Critical secrets management, no dependencies | None (standalone) | +| 2 | **Kogral** | Operational knowledge base (runbooks, ADRs) | None (standalone) | +| 3 | **Provisioning** | Declarative IaC, can integrate SecretumVault (optional) | Optional: SecretumVault (KMS) | +| 4 | **TypeDialog** | Configuration wizards, prov-gen for Provisioning | Optional: Provisioning (IaC apply) | +| 5 | **Vapora** | Agent orchestration, integrates all previous | Kogral (runbooks), SecretumVault (creds), Provisioning (deploy) | + +**Note**: Each project is functional independently, but synergies emerge with progressive adoption. + +--- + +## 8. Ecosystem Comparison + +### STRATUMIOPS Ops vs HashiCorp Stack + +| Component | STRATUMIOPS | HashiCorp | +| ----------- | --------- | ----------- | +| **IaC** | Provisioning (typed Nickel) | Terraform (untyped HCL) | +| **Secrets** | SecretumVault (Rust, **PQC**) | Vault (Go, no PQC) | +| **Orchestration** | Vapora (LLM agents) | Nomad (workload scheduler) | +| **Service Mesh** | Integrates Istio | Consul Connect | +| **Policy** | Cedar (AWS-compatible) | Sentinel (HCL) | +| **Language** | Rust (memory-safe) | Go (garbage collector) | +| **AI-assisted** | MCP + RAG native | Terraform Cloud AI (limited) | +| **License** | Apache-2.0 | BSL (Enterprise paywall) | +| **Ecosystem** | ⚠️ Small | βœ… Huge | + +### STRATUMIOPS Ops vs AWS Native Stack + +| Component | STRATUMIOPS | AWS Native | +| ----------- | --------- | ------------ | +| **IaC** | Provisioning (multi-cloud) | CloudFormation (AWS-only) | +| **Secrets** | SecretumVault (**PQC**, self-hosted) | Secrets Manager (SaaS, no PQC) | +| **Orchestration** | Vapora (self-hosted K8s) | Step Functions (SaaS) | +| **CI/CD** | Vapora DevOps Agent | CodePipeline + CodeBuild | +| **Storage** | SurrealDB multi-model | DynamoDB + RDS | +| **Policy** | Cedar (portable) | IAM (AWS-specific) | +| **Multi-cloud** | βœ… AWS/UpCloud/Local | ❌ AWS-only | +| **Vendor lock-in** | βœ… Portable | ⚠️ High | +| **Cost** | Self-hosted (infra cost) | SaaS (per-use billing) | + +--- + +## 9. Portfolio Metrics (Ops Perspective) + +| Metric | Provisioning | SecretumVault | Vapora | TypeDialog | Kogral | **Total** | +| -------- | -------------- | --------------- | -------- | ------------ | -------- | ----------- | +| **Lines of Code** | ~40K | ~11K | ~50K | ~90K | ~15K | **~206K** | +| **Tests** | 218 | 50+ | 218 | 3,818 | 56 | **4,360+** | +| **CLI Commands** | 80+ shortcuts | 10+ (svault) | 10+ (vapora) | 6 backends | 13 commands | **100+** | +| **Storage Backends** | SurrealDB | 4 (FS/etcd/SurrealDB/PostgreSQL) | SurrealDB + NATS | Multi-format | FS + SurrealDB | **4 backends** | +| **API Endpoints** | 40+ (control-center) | 20+ (vault API) | 40+ (backend) | 10+ (web) | N/A (MCP) | **100+** | +| **Policy Engine** | Cedar RBAC/ABAC | Cedar ABAC | Cedar multi-tenant | N/A | N/A | **Cedar AWS-compatible** | +| **Crypto Backends** | 5 KMS | **4 (OpenSSL, OQS PQC, AWS-LC, RustCrypto)** | N/A | N/A | N/A | **4 backends** | +| **Multi-cloud** | AWS/UpCloud/Local | N/A | N/A | Yes (prov-gen) | N/A | **3 clouds** | + +--- + +## 10. Conclusion (Ops/DevOps Teams) + +This portfolio represents a cohesive ecosystem for modern operations: + +- **Provisioning** is the muscle: deploys multi-cloud infrastructure with typed IaC and automatic rollback +- **SecretumVault** is the vault: protects secrets with production-ready post-quantum cryptography +- **Vapora** is the brain: orchestrates Ops agents (DevOps, Monitor, Security) with learning and cost control +- **TypeDialog** is the interface: configuration wizards that generate validated multi-cloud IaC +- **Kogral** is the memory: preserves runbooks, postmortems and operational knowledge + +The **key differentiation** versus alternatives (Ops perspective): + +1. **Full Rust stack**: Performance (10-50x Python), memory-safety, zero-cost abstractions +2. **Typed Nickel IaC**: Configuration errors detected at compile time, not at runtime +3. **Post-Quantum ready**: SecretumVault with native ML-KEM-768/ML-DSA-65, deploy today +4. **AI-native from design**: MCP + RAG integrated, not retrofitted +5. **Unified multi-cloud**: One Nickel configuration for AWS/UpCloud/Local +6. **Enterprise security**: Cedar policies, audit logging, RBAC/ABAC, 7 years retention + +The **synergy** between projects enables addressing operations with: + +- Typed and validated infrastructure (Provisioning) +- Secrets with cryptographic agility (SecretumVault) +- Intelligent Ops agent orchestration (Vapora) +- Configuration wizards (TypeDialog) +- Preserved operational knowledge (Kogral) + +**Best for**: DevOps/SRE teams valuing type-safety, performance, PQC readiness, multi-cloud, and self-hosted infrastructure over mature ecosystems with vendor lock-in. + +--- + +*Document generated: 2026-01-22* +*Type: info (Ops/DevOps positioning)* diff --git a/docs/en/ops/ops-stratumiops-projects-technical-specs.md b/docs/en/ops/ops-stratumiops-projects-technical-specs.md new file mode 100644 index 0000000..56a08a0 --- /dev/null +++ b/docs/en/ops/ops-stratumiops-projects-technical-specs.md @@ -0,0 +1,1704 @@ +# Ops/DevOps Portfolio: Technical Specifications + +## Ops Ecosystem Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ INTERFACE LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Leptos WASM (Vapora Kanban) β”‚ Ratatui TUI β”‚ Axum REST β”‚ CLI (clap) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ ORCHESTRATION LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Vapora (NATS Agents) β”‚ Provisioning Orchestrator β”‚ TypeDialog Backends β”‚ +β”‚ DevOps/Monitor/Security β”‚ (Rust + Nushell hybrid) β”‚ (prov-gen IaC) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SECURITY LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SecretumVault (PQC) β”‚ Cedar Policies (ABAC) β”‚ JWT + MFA (Auth) β”‚ +β”‚ KV/Transit/PKI/DB β”‚ Audit Logging β”‚ TLS/mTLS (Transport) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PERSISTENCE LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SurrealDB (multi-tenant, time-series) β”‚ NATS JetStream (messaging) β”‚ +β”‚ etcd (distributed KV) β”‚ PostgreSQL (ACID, enterprise) β”‚ +β”‚ Filesystem (git-native markdown) β”‚ Kogral (.kogral/ directory) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 1. Provisioning: Ops Specifications + +### Directory Structure + +```text +provisioning/ +β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ cli/ # Main CLI (211 lines, 80+ shortcuts) +β”‚ β”œβ”€β”€ nulib/ # Nushell libraries (476+ config accessors) +β”‚ └── scripts/ # Utility scripts (Nushell) +β”œβ”€β”€ extensions/ +β”‚ β”œβ”€β”€ providers/ # AWS, UpCloud, Local (LXD) +β”‚ β”‚ β”œβ”€β”€ aws/ # EC2, VPC, S3, RDS provisioners +β”‚ β”‚ β”œβ”€β”€ upcloud/ # Servers, networking, storage +β”‚ β”‚ └── local/ # LXD containers, networking +β”‚ β”œβ”€β”€ taskservs/ # 50+ infrastructure services +β”‚ β”‚ β”œβ”€β”€ containerd/ # Container runtime +β”‚ β”‚ β”œβ”€β”€ etcd/ # Distributed KV store +β”‚ β”‚ β”œβ”€β”€ kubernetes/ # K8s control-plane + workers +β”‚ β”‚ β”œβ”€β”€ cilium/ # eBPF-based CNI +β”‚ β”‚ β”œβ”€β”€ postgresql/ # Database +β”‚ β”‚ β”œβ”€β”€ prometheus/ # Metrics +β”‚ β”‚ └── ... # 44 more services +β”‚ β”œβ”€β”€ clusters/ # Pre-configured cluster templates +β”‚ β”‚ β”œβ”€β”€ k8s-ha/ # HA Kubernetes (3 control-plane, N workers) +β”‚ β”‚ β”œβ”€β”€ k8s-dev/ # Dev Kubernetes (single-node) +β”‚ β”‚ └── db-cluster/ # PostgreSQL HA with Patroni +β”‚ └── workflows/ # Automation workflows +β”‚ β”œβ”€β”€ backup/ # Backup automation +β”‚ β”œβ”€β”€ monitoring/ # Observability setup +β”‚ └── security/ # Security hardening +β”œβ”€β”€ platform/ +β”‚ β”œβ”€β”€ orchestrator/ # Workflow execution engine (Rust) +β”‚ β”œβ”€β”€ control-center/ # Backend API (Axum + RBAC) +β”‚ β”œβ”€β”€ control-center-ui/ # Web dashboard (Leptos) +β”‚ β”œβ”€β”€ installer/ # Multi-mode installer +β”‚ β”œβ”€β”€ mcp-server/ # MCP server (Rust, 1000x Python) +β”‚ β”œβ”€β”€ ai-service/ # AI operations (LLM integration) +β”‚ β”œβ”€β”€ rag/ # RAG system (1200+ docs) +β”‚ β”œβ”€β”€ vault-service/ # Secrets management (integrates SecretumVault) +β”‚ └── detector/ # Anomaly detection +└── schemas/ # Nickel IaC schemas (typed) + β”œβ”€β”€ server.ncl # Server definition contract + β”œβ”€β”€ networking.ncl # VPC, subnets, security groups + β”œβ”€β”€ kubernetes.ncl # K8s cluster contract + └── ... # 20+ schemas +``` + +### Nickel IaC Schema Examples + +#### Server Schema + +```nickel +# schemas/server.ncl +let Server = { + name | String, + provider | [ | 'aws, 'upcloud, 'local |], + + spec | { + cpu | Number | default = 2, + memory_gb | Number | default = 4, + disk_gb | Number | default = 50, + + os | { + family | [ | 'ubuntu, 'debian, 'rocky, 'alpine |], + version | String, + }, + }, + + networking | { + vpc | String | optional, + subnet | String | optional, + public_ip | Bool | default = false, + security_groups | Array String | default = [], + }, + + tags | { _ : String } | default = {}, + + # Validation constraints +} | { + spec.cpu | Number + | std.number.is_positive + | doc "CPU cores must be positive", + + spec.memory_gb | Number + | std.number.is_positive + | doc "Memory must be positive GB", + + spec.disk_gb | Number + | std.number.greater_eq 20 + | doc "Disk must be at least 20GB", +} +in Server +``` + +#### Kubernetes Cluster Schema + +```nickel +# schemas/kubernetes.ncl +let KubernetesCluster = { + name | String, + provider | [ | 'aws, 'upcloud, 'local |], + region | String, + + control_plane | { + count | Number | default = 3, + plan | [ | 'small, 'medium, 'large |] | default = 'medium, + high_availability | Bool | default = true, + }, + + workers | { + count | Number | default = 3, + plan | [ | 'small, 'medium, 'large, 'xlarge |] | default = 'medium, + auto_scaling | { + enabled | Bool | default = false, + min | Number | default = 3, + max | Number | default = 10, + } | optional, + }, + + networking | { + vpc_cidr | String | default = "10.0.0.0/16", + pod_cidr | String | default = "10.244.0.0/16", + service_cidr | String | default = "10.96.0.0/12", + cni | [ | 'cilium, 'calico, 'flannel |] | default = 'cilium, + }, + + addons | { + ingress_nginx | Bool | default = true, + cert_manager | Bool | default = true, + metrics_server | Bool | default = true, + prometheus | Bool | default = false, + }, + + version | String | default = "1.28", +} +in KubernetesCluster +``` + +### Orchestrator API (Rust) + +```rust +// platform/orchestrator/src/lib.rs +use std::collections::HashMap; +use anyhow::Result; +use serde::{Deserialize, Serialize}; +use tokio::sync::RwLock; + +pub struct Orchestrator { + state: Arc<RwLock<StateManager>>, + executor: WorkflowExecutor, + scheduler: Scheduler, + checkpoint_store: CheckpointStore, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Workflow { + pub id: String, + pub name: String, + pub tasks: Vec<Task>, + pub dependencies: HashMap<String, Vec<String>>, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Task { + pub id: String, + pub task_type: TaskType, + pub provider: Provider, + pub config: serde_json::Value, + pub retry_policy: RetryPolicy, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum TaskType { + ProvisionServer, + ConfigureNetworking, + InstallService, + RunHealthCheck, + CreateBackup, +} + +impl Orchestrator { + pub async fn execute_workflow(&self, workflow: Workflow) -> Result<ExecutionResult> { + // 1. Resolve dependencies (topological sort) + let ordered_tasks = self.resolve_dependencies(&workflow)?; + tracing::info!("Resolved {} tasks", ordered_tasks.len()); + + // 2. Create execution checkpoint + let checkpoint = self.checkpoint_store.create(&workflow).await?; + tracing::info!("Created checkpoint: {}", checkpoint.id); + + // 3. Execute tasks with retry logic + for (index, task) in ordered_tasks.iter().enumerate() { + tracing::info!("Executing task {}/{}: {}", index + 1, ordered_tasks.len(), task.id); + + match self.executor.run(task).await { + Ok(result) => { + self.state.write().await.record_success(task, &result)?; + self.checkpoint_store.update_progress(&checkpoint.id, index + 1).await?; + } + Err(e) => { + tracing::error!("Task {} failed: {}", task.id, e); + + // Exponential backoff retry + if let Some(result) = self.retry_with_backoff(task).await? { + self.state.write().await.record_success(task, &result)?; + } else { + // Rollback to checkpoint + tracing::warn!("Rollback to checkpoint {}", checkpoint.id); + self.rollback(&checkpoint).await?; + return Err(e); + } + } + } + } + + Ok(ExecutionResult::from_state(&*self.state.read().await)) + } + + async fn retry_with_backoff(&self, task: &Task) -> Result<Option<TaskResult>> { + let mut delay_ms = task.retry_policy.initial_delay_ms; + + for attempt in 1..=task.retry_policy.max_retries { + tracing::info!("Retry attempt {}/{} for task {}", attempt, task.retry_policy.max_retries, task.id); + tokio::time::sleep(tokio::time::Duration::from_millis(delay_ms)).await; + + match self.executor.run(task).await { + Ok(result) => return Ok(Some(result)), + Err(e) => { + tracing::warn!("Retry {} failed: {}", attempt, e); + delay_ms = (delay_ms * task.retry_policy.backoff_multiplier).min(task.retry_policy.max_delay_ms); + } + } + } + + Ok(None) + } + + async fn rollback(&self, checkpoint: &Checkpoint) -> Result<()> { + let completed_tasks = self.state.read().await.get_completed_tasks(&checkpoint.workflow_id)?; + + // Reverse order rollback + for task in completed_tasks.iter().rev() { + tracing::info!("Rolling back task: {}", task.id); + self.executor.rollback(task).await?; + } + + self.checkpoint_store.delete(&checkpoint.id).await?; + Ok(()) + } + + fn resolve_dependencies(&self, workflow: &Workflow) -> Result<Vec<Task>> { + // Topological sort + let mut in_degree: HashMap<String, usize> = HashMap::new(); + let mut graph: HashMap<String, Vec<String>> = HashMap::new(); + + for task in &workflow.tasks { + in_degree.insert(task.id.clone(), 0); + graph.insert(task.id.clone(), vec![]); + } + + for (task_id, deps) in &workflow.dependencies { + for dep in deps { + graph.get_mut(dep).unwrap().push(task_id.clone()); + *in_degree.get_mut(task_id).unwrap() += 1; + } + } + + let mut queue: Vec<String> = in_degree + .iter() + .filter( | (_, °ree) | degree == 0) + .map( | (id, _) | id.clone()) + .collect(); + + let mut sorted = Vec::new(); + + while let Some(task_id) = queue.pop() { + sorted.push(task_id.clone()); + + for neighbor in &graph[&task_id] { + *in_degree.get_mut(neighbor).unwrap() -= 1; + if in_degree[neighbor] == 0 { + queue.push(neighbor.clone()); + } + } + } + + if sorted.len() != workflow.tasks.len() { + anyhow::bail!("Cyclic dependency detected"); + } + + Ok(sorted.into_iter().map( | id | workflow.tasks.iter().find( | t| t.id == id).unwrap().clone()).collect()) + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct RetryPolicy { + pub max_retries: u32, + pub initial_delay_ms: u64, + pub max_delay_ms: u64, + pub backoff_multiplier: u64, +} + +impl Default for RetryPolicy { + fn default() -> Self { + Self { + max_retries: 3, + initial_delay_ms: 1000, + max_delay_ms: 60000, + backoff_multiplier: 2, + } + } +} +``` + +### MCP Server Tools (Provisioning) + +```rust +// platform/mcp-server/src/tools.rs +use serde_json::json; + +pub const MCP_TOOLS: &[Tool] = &[ + Tool { + name: "query_infrastructure", + description: "Query infrastructure state using natural language (RAG-powered)", + parameters: json!({ + "query": { "type": "string", "description": "Natural language query" }, + "provider": { "type": "string", "optional": true, "enum": ["aws", "upcloud", "local"] } + }), + }, + Tool { + name: "generate_config", + description: "Generate Nickel configuration from natural language description", + parameters: json!({ + "description": { "type": "string", "description": "Infrastructure description" }, + "provider": { "type": "string", "enum": ["aws", "upcloud", "local"] }, + "resource_type": { "type": "string", "enum": ["server", "network", "cluster", "database"] } + }), + }, + Tool { + name: "validate_config", + description: "Validate Nickel configuration against schemas", + parameters: json!({ + "config": { "type": "string", "description": "Nickel configuration code" }, + "strict": { "type": "boolean", "default": true, "description": "Strict validation mode" } + }), + }, + Tool { + name: "estimate_cost", + description: "Estimate monthly cost for infrastructure configuration", + parameters: json!({ + "config": { "type": "string", "description": "Nickel configuration" }, + "region": { "type": "string", "optional": true } + }), + }, + Tool { + name: "check_compliance", + description: "Check configuration against compliance frameworks", + parameters: json!({ + "config": { "type": "string" }, + "framework": { "type": "string", "enum": ["soc2", "hipaa", "gdpr", "pci"] } + }), + }, + Tool { + name: "plan_migration", + description: "Generate migration plan between configurations", + parameters: json!({ + "current": { "type": "string", "description": "Current Nickel config" }, + "target": { "type": "string", "description": "Target Nickel config" } + }), + }, + Tool { + name: "execute_workflow", + description: "Execute provisioning workflow with rollback support", + parameters: json!({ + "workflow_id": { "type": "string" }, + "dry_run": { "type": "boolean", "default": true } + }), + }, +]; +``` + +### CLI Shortcuts (80+) + +```bash +# Core operations +prov init # Initialize provisioning workspace +prov plan <config.ncl> # Generate execution plan (dry-run) +prov apply <config.ncl> # Apply configuration with rollback +prov destroy <config.ncl> # Destroy infrastructure +prov state list # List resources in state +prov state show <id> # Show resource details + +# Provider management +prov provider add aws # Add AWS provider credentials +prov provider add upcloud # Add UpCloud provider credentials +prov provider list # List configured providers +prov provider test <name> # Test provider connectivity + +# Service installation (taskservs) +prov service install containerd --servers server-01,server-02 +prov service install kubernetes --cluster k8s-prod +prov service install cilium --cluster k8s-prod --version 1.14 +prov service list # List available services +prov service status <name> # Check service status + +# Cluster operations +prov cluster create k8s-ha --template extensions/clusters/k8s-ha/ +prov cluster scale k8s-prod --workers 10 +prov cluster upgrade k8s-prod --version 1.28 +prov cluster backup k8s-prod --output /backups/ +prov cluster restore k8s-prod --from /backups/2026-01-22/ + +# Workflow operations +prov workflow run backup --cluster k8s-prod +prov workflow run monitoring --cluster k8s-prod +prov workflow list # List available workflows +prov workflow status <id> # Check workflow status + +# Guided wizards +prov wizard cluster # Interactive cluster setup +prov wizard database # Interactive database setup +prov wizard monitoring # Interactive monitoring setup + +# AI-assisted operations (MCP) +prov mcp query "Show me all AWS servers in us-east-1" +prov mcp generate "Create a 3-node K8s cluster with Cilium on UpCloud" +prov mcp validate cluster.ncl +prov mcp estimate cluster.ncl + +# Security operations +prov vault init # Initialize SecretumVault integration +prov vault store secret/myapp key=value +prov vault read secret/myapp +prov cert generate --domain example.com --engine pki +prov cert rotate --cluster k8s-prod + +# Observability +prov logs <resource-id> # View resource logs +prov metrics <cluster> # View cluster metrics +prov health <cluster> # Health check +prov events <cluster> # View events + +# Configuration management +prov config get <key> # Get config value (476+ accessors) +prov config set <key> <value> +prov config list # List all configuration +prov config validate # Validate configuration +``` + +--- + +## 2. SecretumVault: Ops Specifications + +### Architecture Overview + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault (~11K LOC, 50+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (svault) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends (Pluggable) β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends (Pluggable) β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Core Types + +```rust +// src/core/vault.rs +use std::collections::HashMap; +use std::sync::Arc; +use tokio::sync::Mutex; + +pub struct VaultCore { + pub engines: HashMap<String, Box<dyn Engine>>, + pub storage: Arc<dyn StorageBackend>, + pub crypto: Arc<dyn CryptoBackend>, + pub seal: Arc<Mutex<SealMechanism>>, + pub token_manager: Arc<TokenManager>, + pub authorizer: Arc<CedarAuthorizer>, + pub metrics: Arc<Metrics>, +} + +impl VaultCore { + pub async fn init(&self, shares: u8, threshold: u8) -> Result<Vec<SecretShare>> { + // Initialize Shamir unsealing + let mut seal = self.seal.lock().await; + let shares = seal.init(shares, threshold)?; + + // Setup default engines + self.mount_engine("secret", Box::new(KvEngine::new(self.storage.clone()))).await?; + + Ok(shares) + } + + pub async fn unseal(&self, share: SecretShare) -> Result<UnsealProgress> { + let mut seal = self.seal.lock().await; + let progress = seal.unseal(share)?; + + if let UnsealProgress::Complete = progress { + tracing::info!("Vault unsealed successfully"); + self.metrics.record_unseal().await; + } + + Ok(progress) + } + + pub async fn mount_engine(&self, path: &str, engine: Box<dyn Engine>) -> Result<()> { + self.engines.insert(path.to_string(), engine); + tracing::info!("Mounted engine at path: {}", path); + Ok(()) + } +} +``` + +### Crypto Backends (Post-Quantum) + +```rust +// src/crypto/backends/oqs.rs (Post-Quantum) +use oqs::{kem, sig}; +use anyhow::Result; + +pub struct OqsBackend { + kem_algorithm: kem::Algorithm, // MlKem768 + sig_algorithm: sig::Algorithm, // MlDsa65 + kem_cache: Arc<Mutex<Option<kem::Kem>>>, + sig_cache: Arc<Mutex<Option<sig::Sig>>>, +} + +impl OqsBackend { + pub fn new() -> Result<Self> { + Ok(Self { + kem_algorithm: kem::Algorithm::MlKem768, + sig_algorithm: sig::Algorithm::MlDsa65, + kem_cache: Arc::new(Mutex::new(None)), + sig_cache: Arc::new(Mutex::new(None)), + }) + } + + pub async fn kem_keypair(&self) -> CryptoResult<KemKeyPair> { + let mut cache = self.kem_cache.lock().await; + + if cache.is_none() { + *cache = Some(kem::Kem::new(self.kem_algorithm)?); + } + + let kem = cache.as_ref().unwrap(); + let (pk, sk) = kem.keypair()?; + + // ML-KEM-768: 1184 bytes public key, 2400 bytes secret key + Ok(KemKeyPair { + public_key: pk.into_vec(), + secret_key: sk.into_vec(), + }) + } + + pub async fn kem_encapsulate(&self, public_key: &[u8]) -> CryptoResult<KemResult> { + let mut cache = self.kem_cache.lock().await; + + if cache.is_none() { + *cache = Some(kem::Kem::new(self.kem_algorithm)?); + } + + let kem = cache.as_ref().unwrap(); + let pk = kem::PublicKey::from_bytes(public_key)?; + let (ciphertext, shared_secret) = kem.encapsulate(&pk)?; + + // ML-KEM-768: 1088 bytes ciphertext, 32 bytes shared secret + Ok(KemResult { + ciphertext: ciphertext.into_vec(), + shared_secret: shared_secret.into_vec(), + }) + } + + pub async fn kem_decapsulate(&self, secret_key: &[u8], ciphertext: &[u8]) -> CryptoResult<Vec<u8>> { + let mut cache = self.kem_cache.lock().await; + + if cache.is_none() { + *cache = Some(kem::Kem::new(self.kem_algorithm)?); + } + + let kem = cache.as_ref().unwrap(); + let sk = kem::SecretKey::from_bytes(secret_key)?; + let ct = kem::Ciphertext::from_bytes(ciphertext)?; + let shared_secret = kem.decapsulate(&sk, &ct)?; + + Ok(shared_secret.into_vec()) + } + + pub async fn sign(&self, secret_key: &[u8], message: &[u8]) -> CryptoResult<Vec<u8>> { + let mut cache = self.sig_cache.lock().await; + + if cache.is_none() { + *cache = Some(sig::Sig::new(self.sig_algorithm)?); + } + + let sig_obj = cache.as_ref().unwrap(); + let sk = sig::SecretKey::from_bytes(secret_key)?; + let signature = sig_obj.sign(message, &sk)?; + + // ML-DSA-65: 3309 bytes signature + Ok(signature.into_vec()) + } + + pub async fn verify(&self, public_key: &[u8], message: &[u8], signature: &[u8]) -> CryptoResult<bool> { + let mut cache = self.sig_cache.lock().await; + + if cache.is_none() { + *cache = Some(sig::Sig::new(self.sig_algorithm)?); + } + + let sig_obj = cache.as_ref().unwrap(); + let pk = sig::PublicKey::from_bytes(public_key)?; + let sig_bytes = sig::Signature::from_bytes(signature)?; + + match sig_obj.verify(message, &sig_bytes, &pk) { + Ok(_) => Ok(true), + Err(_) => Ok(false), + } + } +} + +#[async_trait] +impl CryptoBackend for OqsBackend { + async fn generate_keypair(&self, algorithm: KeyAlgorithm) -> CryptoResult<KeyPair> { + match algorithm { + KeyAlgorithm::MlKem768 => { + let kem_pair = self.kem_keypair().await?; + Ok(KeyPair { + public_key: kem_pair.public_key, + private_key: kem_pair.secret_key, + }) + } + KeyAlgorithm::MlDsa65 => { + let mut cache = self.sig_cache.lock().await; + if cache.is_none() { + *cache = Some(sig::Sig::new(self.sig_algorithm)?); + } + let sig_obj = cache.as_ref().unwrap(); + let (pk, sk) = sig_obj.keypair()?; + Ok(KeyPair { + public_key: pk.into_vec(), + private_key: sk.into_vec(), + }) + } + _ => Err(CryptoError::UnsupportedAlgorithm), + } + } + + async fn encrypt(&self, plaintext: &[u8]) -> CryptoResult<Vec<u8>> { + // Generate ephemeral keypair + let kem_pair = self.kem_keypair().await?; + + // Encapsulate to get shared secret + let kem_result = self.kem_encapsulate(&kem_pair.public_key).await?; + + // Use shared secret for AES-256-GCM encryption + let cipher = Aes256Gcm::new_from_slice(&kem_result.shared_secret)?; + let nonce = Aes256Gcm::generate_nonce(&mut OsRng); + let ciphertext = cipher.encrypt(&nonce, plaintext)?; + + // Prepend ciphertext with KEM ciphertext and nonce + let mut result = Vec::new(); + result.extend_from_slice(&kem_result.ciphertext); + result.extend_from_slice(&nonce); + result.extend_from_slice(&ciphertext); + + Ok(result) + } + + async fn decrypt(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>> { + // Extract KEM ciphertext, nonce, and encrypted data + let kem_ct = &ciphertext[..1088]; // ML-KEM-768 ciphertext size + let nonce = &ciphertext[1088..1088+12]; + let encrypted = &ciphertext[1088+12..]; + + // Decapsulate to get shared secret (requires secret key, stored in vault) + // This is simplified - in practice, secret key would be retrieved securely + + // Use shared secret for AES-256-GCM decryption + // ... (implementation details) + + Ok(plaintext) + } +} +``` + +### Secrets Engines + +```rust +// src/engines/mod.rs +#[async_trait] +pub trait Engine: Send + Sync { + fn name(&self) -> &str; + fn engine_type(&self) -> &str; + async fn read(&self, path: &str) -> Result<Option<Value>>; + async fn write(&self, path: &str, data: &Value) -> Result<()>; + async fn delete(&self, path: &str) -> Result<()>; + async fn list(&self, prefix: &str) -> Result<Vec<String>>; +} + +// src/engines/kv.rs (Key-Value Engine) +pub struct KvEngine { + storage: Arc<dyn StorageBackend>, + max_versions: usize, +} + +impl KvEngine { + pub fn new(storage: Arc<dyn StorageBackend>) -> Self { + Self { + storage, + max_versions: 10, // Keep 10 versions by default + } + } +} + +#[async_trait] +impl Engine for KvEngine { + fn name(&self) -> &str { "kv" } + fn engine_type(&self) -> &str { "kv-v2" } + + async fn write(&self, path: &str, data: &Value) -> Result<()> { + let full_path = format!("secret/data/{}", path); + + // Get current version + let current_version = self.get_current_version(path).await?; + let new_version = current_version + 1; + + // Create versioned entry + let entry = VersionedSecret { + version: new_version, + created_time: Utc::now(), + data: data.clone(), + }; + + // Store + self.storage.store_secret(&full_path, &entry).await?; + + // Cleanup old versions + self.cleanup_old_versions(path, new_version).await?; + + Ok(()) + } + + async fn read(&self, path: &str) -> Result<Option<Value>> { + let full_path = format!("secret/data/{}", path); + + match self.storage.get_secret(&full_path).await? { + Some(entry) => Ok(Some(entry.data)), + None => Ok(None), + } + } +} + +// src/engines/database.rs (Dynamic Credentials) +pub struct DatabaseEngine { + storage: Arc<dyn StorageBackend>, + connections: Arc<RwLock<HashMap<String, DatabaseConnection>>>, +} + +#[async_trait] +impl Engine for DatabaseEngine { + fn name(&self) -> &str { "database" } + fn engine_type(&self) -> &str { "database" } + + async fn write(&self, path: &str, data: &Value) -> Result<()> { + // Configure database connection + let config: DatabaseConfig = serde_json::from_value(data.clone())?; + + let connection = DatabaseConnection::new(&config).await?; + self.connections.write().await.insert(path.to_string(), connection); + + Ok(()) + } + + async fn read(&self, path: &str) -> Result<Option<Value>> { + // Generate dynamic credentials + // path format: "database/creds/{role}" + + if !path.starts_with("creds/") { + return Ok(None); + } + + let role = path.strip_prefix("creds/").unwrap(); + let role_config: RoleConfig = self.get_role_config(role).await?; + + // Generate username/password + let username = format!("v-{}-{}", role, Uuid::new_v4()); + let password = generate_secure_password(32); + + // Create user in database + let connections = self.connections.read().await; + let db_conn = connections.get(&role_config.db_name) + .ok_or_else(|| anyhow!("Database connection not found"))?; + + db_conn.execute(&role_config.creation_statements + .replace("{{name}}", &username) + .replace("{{password}}", &password) + .replace("{{expiration}}", &format_expiration(role_config.default_ttl)) + ).await?; + + // Create lease for cleanup + let lease_id = format!("database/creds/{}/{}", role, Uuid::new_v4()); + self.create_lease(&lease_id, role_config.default_ttl, move |vault | { + // Revoke credentials on lease expiration + async move { + db_conn.execute(&format!("DROP USER '{}'", username)).await?; + Ok(()) + } + }).await?; + + Ok(Some(json!({ + "lease_id": lease_id, + "lease_duration": role_config.default_ttl.as_secs(), + "username": username, + "password": password, + }))) + } +} +``` + +### Configuration (TOML) + +```toml +# svault.toml +[vault] +# Crypto backend: openssl | oqs | aws-lc | rustcrypto +crypto_backend = "oqs" # Post-quantum by default + +[server] +address = "0.0.0.0:8200" +tls_cert = "/etc/svault/certs/server.pem" +tls_key = "/etc/svault/certs/server-key.pem" +# Client certificate verification (mTLS) +client_ca = "/etc/svault/certs/ca.pem" +require_client_cert = false + +[storage] +# Backend: filesystem | etcd | surrealdb | postgresql +backend = "etcd" + +[storage.etcd] +endpoints = ["http://etcd-01:2379", "http://etcd-02:2379", "http://etcd-03:2379"] +username = "svault" +password = "secret" +# TLS for etcd +ca_cert = "/etc/svault/etcd-ca.pem" +client_cert = "/etc/svault/etcd-client.pem" +client_key = "/etc/svault/etcd-client-key.pem" + +[seal.shamir] +# Shamir secret sharing configuration +shares = 5 +threshold = 3 + +[auth] +# Token TTL +token_ttl = "24h" +token_max_ttl = "720h" # 30 days + +[audit] +# Audit log retention +enabled = true +retention_days = 2555 # 7 years +backend = "file" +path = "/var/log/svault/audit.log" + +[engines] +# Default engines to mount on init +kv = { path = "secret", version = 2 } +transit = { path = "transit" } +pki = { path = "pki", max_lease_ttl = "87600h" } # 10 years +database = { path = "database" } + +[metrics] +# Prometheus metrics +enabled = true +address = "0.0.0.0:9090" +``` + +--- + +## 3. Vapora: Ops Agents Specifications + +### Agent Roles for Ops + +```rust +// crates/vapora-agents/src/roles.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum AgentRole { + // Development roles + Architect, + Developer, + CodeReviewer, + Tester, + Documenter, + + // Marketing/Communication + Marketer, + Presenter, + + // Ops/DevOps roles + DevOps, // CI/CD, deployment, automation + Monitor, // Health checks, alerting, metrics + Security, // Vulnerability scanning, compliance + + // Management + ProjectManager, + DecisionMaker, +} + +impl AgentRole { + pub fn default_provider(&self) -> LLMProvider { + match self { + // High-complexity ops tasks: Claude Opus + AgentRole::Security => LLMProvider::Claude { model: "claude-opus-4-20250514" }, + AgentRole::DecisionMaker => LLMProvider::Claude { model: "claude-opus-4-20250514" }, + + // Standard ops tasks: Claude Sonnet + AgentRole::DevOps => LLMProvider::Claude { model: "claude-sonnet-4-20250514" }, + AgentRole::ProjectManager => LLMProvider::Claude { model: "claude-sonnet-4-20250514" }, + + // Real-time monitoring: Gemini Flash (low latency) + AgentRole::Monitor => LLMProvider::Gemini { model: "gemini-2.0-flash-exp" }, + + _ => LLMProvider::Claude { model: "claude-sonnet-4-20250514" }, + } + } + + pub fn can_block_pipeline(&self) -> bool { + matches!(self, AgentRole::Security) + } + + pub fn requires_approval(&self) -> bool { + matches!(self, AgentRole::DevOps | AgentRole::Security) + } +} +``` + +### NATS Message Patterns (Ops) + +```rust +// crates/vapora-agents/src/messages.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum AgentMessage { + TaskAssignment { + task_id: String, + agent_id: String, + agent_role: AgentRole, + task_type: String, + payload: serde_json::Value, + priority: Priority, + }, + TaskResult { + task_id: String, + agent_id: String, + agent_role: AgentRole, + status: TaskStatus, + output: Option<String>, + duration_ms: u64, + tokens_used: u32, + cost_cents: f64, + }, + Heartbeat { + agent_id: String, + agent_role: AgentRole, + status: AgentStatus, + current_load: f64, + last_task_completed_at: Option<DateTime<Utc>>, + }, + Alert { + severity: AlertSeverity, + source: String, + message: String, + metadata: serde_json::Value, + }, + ApprovalRequest { + task_id: String, + requester: AgentRole, + action: String, + details: serde_json::Value, + }, + ApprovalResponse { + task_id: String, + approved: bool, + approver: String, + reason: Option<String>, + }, +} + +// NATS subjects +pub const TASK_ASSIGNMENT: &str = "vapora.tasks.assign"; +pub const TASK_RESULTS: &str = "vapora.tasks.results"; +pub const AGENT_HEARTBEAT: &str = "vapora.agents.heartbeat"; +pub const ALERTS: &str = "vapora.alerts"; +pub const APPROVALS_REQUEST: &str = "vapora.approvals.request"; +pub const APPROVALS_RESPONSE: &str = "vapora.approvals.response"; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum AlertSeverity { + Info, + Warning, + Error, + Critical, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum Priority { + Low = 1, + Normal = 2, + High = 3, + Critical = 4, +} +``` + +### Budget Control (Ops Agents) + +```rust +// crates/vapora-llm-router/src/budget.rs +use std::collections::HashMap; +use serde::{Deserialize, Serialize}; +use chrono::{DateTime, Utc}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct BudgetConfig { + pub role: AgentRole, + pub monthly_limit_cents: u32, + pub weekly_limit_cents: Option<u32>, + pub enforcement: BudgetEnforcement, + pub fallback_chain: Vec<LLMProvider>, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum BudgetEnforcement { + Normal, // Under 80% of limit + NearThreshold, // 80-100% of limit, use fallback + Exceeded, // Over limit, block or use cheapest fallback only +} + +pub struct BudgetTracker { + configs: HashMap<AgentRole, BudgetConfig>, + usage: Arc<RwLock<HashMap<AgentRole, UsageStats>>>, +} + +impl BudgetTracker { + pub async fn check_budget(&self, role: AgentRole, estimated_cost_cents: f64) -> BudgetEnforcement { + let config = self.configs.get(&role).unwrap(); + let usage = self.usage.read().await; + let stats = usage.get(&role).unwrap_or(&UsageStats::default()); + + let monthly_usage = stats.monthly_cost_cents; + let weekly_usage = stats.weekly_cost_cents; + + // Check weekly limit first (if set) + if let Some(weekly_limit) = config.weekly_limit_cents { + if weekly_usage + estimated_cost_cents > weekly_limit as f64 { + return BudgetEnforcement::Exceeded; + } else if weekly_usage + estimated_cost_cents > (weekly_limit as f64 * 0.8) { + return BudgetEnforcement::NearThreshold; + } + } + + // Check monthly limit + if monthly_usage + estimated_cost_cents > config.monthly_limit_cents as f64 { + BudgetEnforcement::Exceeded + } else if monthly_usage + estimated_cost_cents > (config.monthly_limit_cents as f64 * 0.8) { + BudgetEnforcement::NearThreshold + } else { + BudgetEnforcement::Normal + } + } + + pub async fn select_provider(&self, role: AgentRole, task_type: &str) -> LLMProvider { + let enforcement = self.check_budget(role, self.estimate_cost(task_type)).await; + let config = self.configs.get(&role).unwrap(); + + match enforcement { + BudgetEnforcement::Normal => { + // Use default provider for role + role.default_provider() + } + BudgetEnforcement::NearThreshold => { + // Use first fallback (cheaper) + config.fallback_chain.get(0) + .cloned() + .unwrap_or_else(|| role.default_provider()) + } + BudgetEnforcement::Exceeded => { + // Use cheapest fallback (typically Ollama local) + config.fallback_chain.last() + .cloned() + .unwrap_or_else(|| LLMProvider::Ollama { model: "llama3.1:8b" }) + } + } + } + + pub async fn record_usage(&self, role: AgentRole, cost_cents: f64) { + let mut usage = self.usage.write().await; + let stats = usage.entry(role).or_insert_with(UsageStats::default); + + stats.monthly_cost_cents += cost_cents; + stats.weekly_cost_cents += cost_cents; + stats.total_requests += 1; + stats.last_updated = Utc::now(); + } +} + +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +pub struct UsageStats { + pub monthly_cost_cents: f64, + pub weekly_cost_cents: f64, + pub total_requests: u64, + pub last_updated: DateTime<Utc>, +} +``` + +### Prometheus Metrics (Ops) + +```rust +// crates/vapora-telemetry/src/metrics.rs +use prometheus::{Encoder, Gauge, Counter, Histogram, Registry}; + +pub struct VaporaMetrics { + registry: Registry, + + // Budget metrics + budget_utilization: Gauge, + budget_exceeded_total: Counter, + fallback_triggers_total: Counter, + + // Agent metrics + active_agents: Gauge, + task_duration_seconds: Histogram, + task_status_total: Counter, + + // Cost metrics + llm_cost_cents_total: Counter, + tokens_used_total: Counter, +} + +impl VaporaMetrics { + pub fn new() -> Self { + let registry = Registry::new(); + + let budget_utilization = Gauge::new( + "vapora_budget_utilization_ratio", + "Budget utilization ratio (0.0-1.0) per agent role" + ).unwrap(); + + let budget_exceeded_total = Counter::new( + "vapora_budget_exceeded_total", + "Total number of budget exceeded events per agent role" + ).unwrap(); + + let fallback_triggers_total = Counter::new( + "vapora_fallback_triggers_total", + "Total number of fallback provider triggers due to budget" + ).unwrap(); + + let active_agents = Gauge::new( + "vapora_active_agents", + "Number of active agents by role and status" + ).unwrap(); + + let task_duration_seconds = Histogram::new( + "vapora_task_duration_seconds", + "Task execution duration in seconds" + ).unwrap(); + + let task_status_total = Counter::new( + "vapora_task_status_total", + "Total tasks by status (success, failed, timeout)" + ).unwrap(); + + let llm_cost_cents_total = Counter::new( + "vapora_llm_cost_cents_total", + "Total LLM cost in cents per provider and role" + ).unwrap(); + + let tokens_used_total = Counter::new( + "vapora_tokens_used_total", + "Total tokens used per provider and role" + ).unwrap(); + + registry.register(Box::new(budget_utilization.clone())).unwrap(); + registry.register(Box::new(budget_exceeded_total.clone())).unwrap(); + registry.register(Box::new(fallback_triggers_total.clone())).unwrap(); + registry.register(Box::new(active_agents.clone())).unwrap(); + registry.register(Box::new(task_duration_seconds.clone())).unwrap(); + registry.register(Box::new(task_status_total.clone())).unwrap(); + registry.register(Box::new(llm_cost_cents_total.clone())).unwrap(); + registry.register(Box::new(tokens_used_total.clone())).unwrap(); + + Self { + registry, + budget_utilization, + budget_exceeded_total, + fallback_triggers_total, + active_agents, + task_duration_seconds, + task_status_total, + llm_cost_cents_total, + tokens_used_total, + } + } + + pub fn export(&self) -> String { + let encoder = prometheus::TextEncoder::new(); + let metric_families = self.registry.gather(); + let mut buffer = Vec::new(); + encoder.encode(&metric_families, &mut buffer).unwrap(); + String::from_utf8(buffer).unwrap() + } +} +``` + +--- + +## 4. TypeDialog (prov-gen): IaC Generation Specifications + +### Prov-Gen Backend + +```rust +// crates/typedialog-prov-gen/src/lib.rs +use tera::{Tera, Context}; +use serde::{Deserialize, Serialize}; + +pub struct ProvGenBackend { + templates: Tera, + validators: Vec<Box<dyn Validator>>, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct InfrastructureConfig { + pub provider: CloudProvider, + pub region: String, + pub resources: Vec<Resource>, + pub networking: NetworkConfig, + pub security: SecurityConfig, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum CloudProvider { + Aws, + Gcp, + Azure, + Hetzner, + UpCloud, + Local, // LXD +} + +pub struct Generator { + templates: tera::Tera, + validators: Vec<Box<dyn Validator>>, +} + +impl Generator { + pub async fn generate(&self, config: &InfrastructureConfig) -> Result<GeneratedIaC> { + // 1. Validate input config (7-layer validation) + self.validate_config(config)?; + + // 2. Load provider-specific template + let template_name = format!("{}.ncl.tera", config.provider.as_str()); + let template = self.templates.get_template(&template_name)?; + + // 3. Create template context + let mut context = Context::new(); + context.insert("provider", &config.provider); + context.insert("region", &config.region); + context.insert("resources", &config.resources); + context.insert("networking", &config.networking); + context.insert("security", &config.security); + + // 4. Render Nickel configuration + let nickel_code = template.render(&context)?; + + // 5. Validate generated Nickel + self.validate_nickel(&nickel_code)?; + + // 6. Split into logical files + let files = self.split_to_files(&nickel_code)?; + + Ok(GeneratedIaC { + provider: config.provider.clone(), + main_file: nickel_code, + files, + validation_passed: true, + }) + } + + fn validate_config(&self, config: &InfrastructureConfig) -> Result<()> { + for validator in &self.validators { + validator.validate(config)?; + } + Ok(()) + } + + fn validate_nickel(&self, code: &str) -> Result<()> { + // Run nickel typecheck + let output = std::process::Command::new("nickel") + .arg("typecheck") + .arg("--stdin") + .stdin(std::process::Stdio::piped()) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn()? + .stdin.unwrap().write_all(code.as_bytes())?; + + // Check exit status + // ... (implementation details) + + Ok(()) + } +} +``` + +### Templates (Tera + Nickel) + +```tera +{# templates/aws.ncl.tera - AWS multi-cloud template #} +{# Generated by TypeDialog prov-gen backend #} + +{ + provider = "aws", + region = "{{ region }}", + + {% if resources.servers %} + servers = [ + {% for server in resources.servers %} + { + name = "{{ server.name }}", + plan = "{{ server.plan }}", + role = {% if server.role %}"{{ server.role }}"{% else %}null{% endif %}, + provider = "aws", + + spec = { + cpu = {{ server.cpu | default(value=2) }}, + memory_gb = {{ server.memory_gb | default(value=4) }}, + disk_gb = {{ server.disk_gb | default(value=50) }}, + + os = { + family = 'ubuntu, + version = "{{ server.os_version | default(value='22.04') }}", + }, + }, + + networking = { + vpc = "{{ networking.vpc_id }}", + subnet = "{{ networking.subnet_id }}", + public_ip = {{ server.public_ip | default(value=false) }}, + security_groups = {{ server.security_groups | default(value=[]) | json_encode }}, + }, + + tags = { + Environment = "{{ environment | default(value='production') }}", + ManagedBy = "provisioning", + {% for key, value in server.tags %} + "{{ key }}" = "{{ value }}", + {% endfor %} + }, + }, + {% endfor %} + ], + {% endif %} + + {% if resources.taskservs %} + taskservs = {{ resources.taskservs | json_encode }}, + {% endif %} + + networking = { + vpc_cidr = "{{ networking.vpc_cidr | default(value='10.0.0.0/16') }}", + {% if networking.pod_cidr %} + pod_cidr = "{{ networking.pod_cidr }}", + service_cidr = "{{ networking.service_cidr }}", + {% endif %} + }, + + {% if security %} + security = { + {% if security.enable_encryption %} + encryption_at_rest = true, + kms_key_id = "{{ security.kms_key_id }}", + {% endif %} + + {% if security.enable_audit_logging %} + audit_logging = { + enabled = true, + retention_days = {{ security.audit_retention_days | default(value=2555) }}, + }, + {% endif %} + }, + {% endif %} +} +``` + +--- + +## 5. Kogral: Knowledge Management Specifications + +### Node Types (Ops Focus) + +```rust +// kogral-core/src/models.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum NodeType { + Note, // General notes, documentation + Decision, // ADRs (Architectural Decision Records) + Guideline, // Team/org standards, policies + Pattern, // Reusable solutions, best practices + Journal, // Daily development/ops log + Execution, // Agent execution records, postmortems, incidents +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Node { + pub id: String, + pub node_type: NodeType, + pub title: String, + pub content: String, // Markdown body + pub metadata: HashMap<String, String>, + pub tags: Vec<String>, + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, + pub author: Option<String>, +} + +// Example: Execution node for incident postmortem +impl Node { + pub fn new_execution(title: &str, incident_details: IncidentDetails) -> Self { + let content = format!( + "# {}\n\n\ + ## Timeline\n\ + - **Started**: {}\n\ + - **Detected**: {}\n\ + - **Resolved**: {}\n\ + - **Duration**: {:?}\n\n\ + ## Root Cause\n\ + {}\n\n\ + ## Resolution\n\ + {}\n\n\ + ## Action Items\n\ + {}\n\n\ + ## Related Resources\n\ + {}", + title, + incident_details.started_at, + incident_details.detected_at, + incident_details.resolved_at, + incident_details.duration, + incident_details.root_cause, + incident_details.resolution, + incident_details.action_items.join("\n"), + incident_details.related_resources.join("\n"), + ); + + Self { + id: Uuid::new_v4().to_string(), + node_type: NodeType::Execution, + title: title.to_string(), + content, + metadata: incident_details.metadata, + tags: incident_details.tags, + created_at: Utc::now(), + updated_at: Utc::now(), + author: Some(incident_details.author), + } + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct IncidentDetails { + pub started_at: DateTime<Utc>, + pub detected_at: DateTime<Utc>, + pub resolved_at: DateTime<Utc>, + pub duration: std::time::Duration, + pub root_cause: String, + pub resolution: String, + pub action_items: Vec<String>, + pub related_resources: Vec<String>, + pub metadata: HashMap<String, String>, + pub tags: Vec<String>, + pub author: String, +} +``` + +### MCP Tools (Ops Workflows) + +```bash +# Search troubleshooting runbooks +kogral-mcp search "nginx 502 error troubleshooting" --type note + +# Add incident postmortem +kogral-mcp add-execution \ + --title "2026-01-22 PostgreSQL Connection Pool Exhaustion" \ + --context "Production database connections maxed out at 100/100" \ + --root-cause "Connection leak in application code, connections not released" \ + --resolution "Increased max_connections from 100 to 200, added PgBouncer pooler, fixed connection leak" \ + --action-items "Implement connection pool monitoring, add alerts at 80% utilization" \ + --tags "database,incident,postgresql,production" + +# Get deployment guidelines +kogral-mcp get-guidelines "kubernetes deployment" --include-shared true + +# Create infrastructure decision ADR +kogral-mcp add-decision \ + --title "Choose Cilium over Calico for CNI" \ + --context "Need Kubernetes CNI with eBPF support and service mesh capabilities" \ + --decision "Selected Cilium for better performance (eBPF) and built-in service mesh" \ + --consequences "Higher complexity initially, better performance long-term, requires Linux kernel 4.9+" + +# List all postmortems (Execution nodes) +kogral-mcp list --type execution --tags "incident" + +# Export knowledge graph to markdown +kogral-mcp export --format markdown --output /docs/ops-knowledge/ +``` + +--- + +## 6. Integration between Projects (Ops Stack) + +### Data Flow Diagram + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Runbooks, ADRs) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + MCP (operational knowledge) + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TypeDialog β”‚ β”‚ Vapora β”‚ β”‚ Provisioning β”‚ +β”‚ (Wizards) β”‚ β”‚ (Ops Agents) β”‚ β”‚ (IaC Deploy) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ SECRETUMVAULT β”‚ + β”‚ PKI certs β”‚ DB creds β”‚ API keys β”‚ Encryption β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ PERSISTENCE LAYER β”‚ + β”‚ SurrealDB β”‚ NATS JetStream β”‚ etcd β”‚ Git β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Shared Dependencies (Ops Stack) + +```toml +# Common dependencies (Cargo.toml) +[dependencies] +# Runtime +tokio = { version = "1.48", features = ["full"] } + +# Serialization +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +toml = "0.8" + +# Database +surrealdb = "2.3" +etcd-client = "0.14" + +# Web/API +axum = { version = "0.8", features = ["macros"] } +tower = "0.5" +tower-http = { version = "0.6", features = ["cors", "compression-gzip"] } + +# Config +nickel-lang-core = "1.15" + +# Logging/Tracing +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] } +tracing-opentelemetry = "0.27" + +# Metrics +prometheus = "0.13" + +# Security +cedar-policy = "4.3" +jsonwebtoken = "9.3" + +# Crypto +openssl = { version = "0.10", optional = true } +oqs = { version = "0.10", optional = true } # Post-Quantum + +# Error handling +anyhow = "1.0" +thiserror = "2.0" +``` + +--- + +## 7. Quality Metrics (Ops Perspective) + +| Project | Tests | Coverage | Clippy | Unsafe Blocks | Performance | +| --------- | ------- | ---------- | -------- | --------------- | ------------- | +| **Provisioning** | 218 | ~65% | 0 warnings | 0 | Rust orchestrator 10-50x Python | +| **SecretumVault** | 50+ | ~75% | 0 warnings | 0 | Crypto ops <10ms (classical), <20ms (PQC) | +| **Vapora** | 218 | ~70% | 0 warnings | 0 | NATS latency <5ms, task assignment <100ms | +| **TypeDialog** | 3,818 | ~85% | 0 warnings | 0 | Form validation <1ms, IaC gen <500ms | +| **Kogral** | 56 | ~80% | 0 warnings | 0 | Semantic search <200ms (fastembed local) | + +### Ops Verification Commands + +```bash +# Provisioning +cd provisioning +cargo clippy --all-targets --all-features -- -D warnings +cargo test --workspace +just ci-test # Run CI tests locally + +# SecretumVault +cd secretumvault +cargo test --all-features +cargo bench # Crypto benchmarks + +# Vapora +cd vapora +cargo test --workspace +docker-compose up -d # Integration tests with NATS + SurrealDB + +# TypeDialog +cd typedialog +cargo test --workspace --all-features +cargo run --example prov-gen # Test IaC generation + +# Kogral +cd kogral +cargo test +kogral serve & # Start MCP server +curl http://localhost:3100/health # Health check +``` + +--- + +*Document generated: 2026-01-22* +*Type: info (Ops/DevOps technical specifications)* diff --git a/docs/en/ops/ops-stratumiops-projects.md b/docs/en/ops/ops-stratumiops-projects.md new file mode 100644 index 0000000..e42ce0b --- /dev/null +++ b/docs/en/ops/ops-stratumiops-projects.md @@ -0,0 +1,735 @@ +# Ops/DevOps Portfolio: Modern Infrastructure End-to-End + +## The Problem + +DevOps and platform teams face critical challenges managing modern infrastructure: + +- **Fragmented tools**: Terraform for IaC, Ansible for configuration, Vault for secrets, all disconnected +- **Untyped YAML**: Configuration errors that explode at runtime, not at compile time +- **Static cryptography**: No preparation for future quantum threats +- **Manual orchestration**: Fragile imperative scripts without rollback or recovery +- **Hidden costs**: No visibility into LLM spending for infrastructure generation +- **Complex multi-cloud**: Different APIs, configurations and tools per provider + +## The Solution: An Integrated Ecosystem + +Five projects designed to work together, covering the complete operations cycle. + +--- + +## Provisioning: Declarative Infrastructure as Code + +### Typed IaC with AI-Assisted Generation + +Provisioning combines the precision of typed configuration (Nickel) with AI-assisted generation, eliminating fragile YAML and imperative scripts. + +**Unique capabilities**: + +- **Nickel IaC**: Typed configuration with lazy evaluation, pre-runtime validation +- **MCP Server**: Natural language queries about infrastructure +- **Integrated RAG**: 1,200+ domain documents for contextual responses +- **Multi-cloud**: AWS, UpCloud, local (LXD) from the same definition + +**Hybrid orchestration**: + +- Rust orchestrator for critical workflows (10-50x performance vs Python) +- Nushell scripts for flexibility and rapid prototyping +- Automatic dependency resolution (topological sorting) +- Checkpoints and automatic rollback on failures + +**The workflow**: + +```text +"I need a K8s cluster on AWS with 3 nodes and Cilium" + ↓ + MCP Server (NLP) + ↓ + RAG searches similar configurations + ↓ + Generates Nickel + validates types + ↓ + Orchestrator deploys: + 1. containerd (dependency) + 2. etcd (dependency) + 3. kubernetes (core) + 4. cilium (CNI) + With checkpoints and automatic rollback +``` + +**Enterprise security**: + +- JWT + MFA (TOTP + WebAuthn) +- Cedar policy engine for RBAC/ABAC +- 7 years audit log retention +- 5 KMS backends (RustyVault, Age, AWS KMS, Vault, Cosmian) +- SOPS/Age for configuration encryption at rest + +**For whom**: + +- DevOps teams wanting typed IaC, not fragile YAML +- Multi-cloud organizations (AWS + UpCloud + on-premise) +- Teams needing audit, compliance and enterprise security + +**Expected results**: + +- Configuration errors detected at compile time, not at runtime +- Infrastructure generated from natural language (MCP + RAG) +- Automatic rollback on failures with state management + +--- + +## SecretumVault: Secrets Management with Post-Quantum Crypto + +### Rust Vault with PQC in Production + +SecretumVault is a secrets management system that implements **production-ready post-quantum cryptography** (ML-KEM-768, ML-DSA-65), providing cryptographic agility for organizations deploying today. + +**Crypto-agnostic**: + +- **OpenSSL**: RSA, ECDSA, AES-256-GCM (classical compatibility) +- **OQS (Post-Quantum)**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) +- **AWS-LC**: Experimental PQC (testing) +- **RustCrypto**: Pure-Rust implementations (testing) +- **Pluggable backends**: Change algorithms without modifying code + +**Secrets engines**: + +| Engine | Capability | Use cases | +| -------- | ------------ | ----------- | +| **KV** | Versioned secret storage | Credentials, API keys, sensitive configurations | +| **Transit** | Encryption-as-a-service with key rotation | Application data encryption, key rotation | +| **PKI** | X.509 certificate generation | mTLS, service mesh, internal infrastructure | +| **Database** | Dynamic credentials with TTL | PostgreSQL, MySQL, MongoDB credentials on-demand | + +**Multi-backend storage**: + +- **Filesystem**: Development, single-node, rapid prototyping +- **etcd**: Kubernetes, high availability, strong consistency +- **SurrealDB**: Complex queries, time-series, multi-tenant scopes +- **PostgreSQL**: Enterprise, ACID, complete auditing + +**Enterprise security**: + +- Shamir Secret Sharing for unsealing (configurable threshold) +- Cedar policy engine (ABAC, AWS-compatible) +- Native TLS/mTLS with X.509 certificates +- Complete audit logging with configurable retention +- Token management with TTL and renewal + +**Ops/DevOps workflow**: + +```bash +# Initialize vault with Shamir (5 shares, threshold 3) +svault operator init --shares 5 --threshold 3 + +# Unseal with 3 shares +svault operator unseal --share <share-1> +svault operator unseal --share <share-2> +svault operator unseal --share <share-3> + +# Enable Database engine for PostgreSQL +svault secret engine enable database +svault secret database config postgres-prod \ + plugin_name=postgresql-database-plugin \ + connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb" \ + username="vault" password="vaultpass" + +# Create role for dynamic credentials +svault secret database role create myapp-role \ + db_name=postgres-prod \ + creation_statements="CREATE USER '{{name}}' WITH PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO '{{name}}';" \ + default_ttl=1h max_ttl=24h + +# Get dynamic credentials (generated on-demand) +svault secret read database/creds/myapp-role +# Key Value +# --- ----- +# lease_id database/creds/myapp-role/abc123 +# lease_duration 3600 +# username v-myapp-role-xyz789 +# password A1b2C3d4E5f6G7h8 + +# Credentials are automatically revoked after 1h TTL +``` + +**For whom**: + +- Teams deploying post-quantum cryptography today +- Organizations with cryptographic agility requirements +- Multi-cloud platforms needing Rust-native secrets management +- Security teams evaluating future quantum threats + +**Expected results**: + +- Preparation for quantum threats without changing architecture +- Secrets management with Rust memory guarantees +- Native integration with Provisioning (KMS) and Vapora (agent credentials) + +--- + +## Vapora: Agent Orchestration with Cost Control + +### Intelligent Agents for Operations + +Vapora is not just for feature development. It's an orchestration platform that can coordinate specialized agents for DevOps operations. + +**Available agents for Ops**: + +- **DevOps**: CI/CD, pipelines, deployment automation +- **Monitor**: Health checks, alerting, real-time metrics +- **Security**: Auditing, compliance, vulnerability scanning +- **ProjectManager**: Roadmap, tracking, task coordination + +**Real cost control for LLMs**: + +- Budgets per role (monthly/weekly) +- Three levels: normal β†’ near limit β†’ exceeded +- Automatic fallback to cheaper providers without manual intervention +- Prometheus metrics: `vapora_budget_utilization`, `vapora_fallback_triggers` + +**NATS JetStream coordination**: + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ NATS JetStream Messaging β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ vapora.tasks.assign β†’ Task assignment β”‚ +β”‚ vapora.tasks.results β†’ Execution results β”‚ +β”‚ vapora.agents.heartbeat β†’ Agent health check β”‚ +β”‚ β”‚ +β”‚ Persistence: JetStream streams β”‚ +β”‚ Delivery: At-least-once with acknowledgment β”‚ +β”‚ Ordering: Per-subject message ordering β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Ops pipeline orchestration**: + +```text +Pipeline: "Deploy microservice to K8s" + +1. Security Agent: Docker image vulnerability scan +2. DevOps Agent: Validate K8s manifests + Helm charts +3. Monitor Agent: Setup Prometheus metrics + alerts +4. DevOps Agent: Deploy with kubectl apply + health check +5. Monitor Agent: Validate health endpoints + smoke tests + +If any step fails: coordinated automatic rollback +``` + +**Metrics and observability**: + +- Prometheus metrics endpoint (`/metrics`) +- OpenTelemetry integration (traces, spans) +- SurrealDB for execution storage +- Grafana dashboards for visualization + +**For whom**: + +- DevOps teams coordinating multiple LLM agents for operations +- Organizations needing to control LLM spending in automation +- Platforms with complex pipelines (CI/CD, deployment, monitoring) + +**Expected results**: + +- LLM cost reduction through intelligent routing +- Automatic orchestration of complex operational tasks +- Complete visibility of spending and performance per agent + +--- + +## TypeDialog: Multi-Backend Forms for Configuration + +### One Definition, Six Interfaces (Includes prov-gen) + +TypeDialog unifies configuration capture in CLI, TUI, Web, and has a specialized backend for multi-cloud IaC generation. + +**Operational backends**: + +| Backend | Typical Ops/DevOps use | +| --------- | ------------------------ | +| **CLI** | Automation scripts, CI/CD pipelines | +| **TUI** | Admin tools, terminal dashboards | +| **Web** | Self-service portals, team forms | +| **Prov-gen** | **Multi-cloud infrastructure generation** | + +**Prov-gen Backend: IaC Generation** + +The `prov-gen` backend generates Nickel infrastructure configurations for multiple clouds from typed forms: + +```toml +# cluster-setup.toml +[form] +id = "k8s_cluster" +title = "Kubernetes Cluster Setup" + +[[sections]] +id = "cloud" +title = "Cloud Provider" + +[[sections.fields]] +id = "provider" +type = "select" +label = "Provider" +required = true +options = [ + { value = "aws", label = "AWS" }, + { value = "upcloud", label = "UpCloud" }, + { value = "local", label = "Local LXD" }, +] + +[[sections.fields]] +id = "region" +type = "text" +label = "Region" +required = true + +[[sections]] +id = "cluster" +title = "Cluster Configuration" + +[[sections.fields]] +id = "node_count" +type = "number" +label = "Node Count" +default = 3 +validation.min = 1 +validation.max = 20 + +[[sections.fields]] +id = "node_size" +type = "select" +label = "Node Size" +options = [ + { value = "small", label = "Small (2 CPU, 4GB RAM)" }, + { value = "medium", label = "Medium (4 CPU, 8GB RAM)" }, + { value = "large", label = "Large (8 CPU, 16GB RAM)" }, +] + +[output] +backend = "prov-gen" +format = "nickel" +validation = "nickel://schemas/kubernetes_cluster.ncl" +``` + +Execute with prov-gen: + +```bash +typedialog execute cluster-setup.toml --backend prov-gen --output k8s-cluster.ncl +``` + +Generates Nickel IaC: + +```nickel +# k8s-cluster.ncl (automatically generated) +{ + provider = "aws", + region = "us-east-1", + + servers = [ + { + name = "k8s-control-plane-01", + plan = "medium", + role = "control-plane", + provider = "aws", + }, + { + name = "k8s-worker-01", + plan = "medium", + role = "worker", + provider = "aws", + }, + { + name = "k8s-worker-02", + plan = "medium", + role = "worker", + provider = "aws", + }, + ], + + taskservs = [ + "containerd", + "etcd", + "kubernetes", + "cilium", + ], + + networking = { + vpc_cidr = "10.0.0.0/16", + pod_cidr = "10.244.0.0/16", + service_cidr = "10.96.0.0/12", + }, +} +``` + +**Nickel contracts validation**: + +```rust +// Automatic validation with Nickel schemas +let validator = NickelValidator::new(); +let result = validator.validate(&generated_iac, "schemas/kubernetes_cluster.ncl")?; + +if result.errors.is_empty() { + // Valid IaC, ready for Provisioning + provisioning_client.apply(&generated_iac).await?; +} else { + // Validation errors, show to user + eprintln!("Validation errors: {:?}", result.errors); +} +``` + +**For whom**: + +- DevOps teams maintaining configuration wizards in CLI and Web +- Organizations with self-service infrastructure portals +- Teams needing IaC generation from forms + +**Expected results**: + +- One TOML definition for CLI, TUI, Web and IaC generation +- Typed validation before runtime with Nickel contracts +- Reduction of manual configuration errors + +--- + +## Kogral: Knowledge Base for Platform Teams + +### Your Ops Knowledge Base, Queryable + +Kogral captures architectural decisions, runbooks, postmortems and operational procedures in a format that both humans and AI agents can query. + +**6 specialized node types for Ops**: + +| Type | Ops/DevOps use | +| ------ | ---------------- | +| **Note** | Runbooks, procedures, troubleshooting guides | +| **Decision** | Infrastructure ADRs (why AWS vs UpCloud, etcd vs Consul) | +| **Guideline** | Deployment standards, security policies | +| **Pattern** | Reusable infrastructure patterns (multi-AZ, HA) | +| **Journal** | Change logs, daily stand-up notes | +| **Execution** | Deployment history, rollbacks, incidents | + +**Git-native + MCP for Claude Code**: + +- Everything in versioned markdown (`.kogral/` directory) +- MCP server for Claude Code: agents query runbooks before executing +- Semantic search with fastembed (local) or cloud embeddings + +**The Ops flow**: + +```text +Production incident β†’ Capture postmortem in Kogral as Execution + ↓ + Claude Code queries via MCP β†’ "How did we resolve this error before?" + ↓ + Kogral responds with similar postmortems + runbooks + ↓ + Agent applies documented solution instead of guessing +``` + +**MCP Tools for Ops**: + +```bash +# Search troubleshooting runbooks +kogral-mcp search "nginx 502 error troubleshooting" + +# Add incident postmortem +kogral-mcp add-execution \ + --title "2026-01-22 PostgreSQL Connection Pool Exhaustion" \ + --context "Production database connections maxed out" \ + --resolution "Increased max_connections from 100 to 200, added PgBouncer" \ + --tags "database,incident,postgresql" + +# Get deployment guidelines +kogral-mcp get-guidelines "kubernetes deployment" --include-shared true +``` + +**For whom**: + +- Platform teams needing to preserve operational knowledge +- SRE teams with rotation losing context of previous incidents +- DevOps using Claude Code wanting contextualized runbooks + +**Expected results**: + +- New SRE onboarding in days, not weeks +- Incident resolution informed by previous postmortems +- Infrastructure decisions preserved and searchable + +--- + +## The Ecosystem in Action: Ops Scenarios + +### Scenario 1: New Multi-Cloud Kubernetes Cluster + +```text +1. TypeDialog (prov-gen): Configuration wizard for cluster + - Cloud provider, region, node count, node size + - Generates validated Nickel IaC + +2. Provisioning: Deploys infrastructure + - Creates servers on AWS/UpCloud + - Installs containerd, etcd, kubernetes, cilium + - Checkpoints per step, automatic rollback if fails + +3. SecretumVault: Generates PKI certificates + - Certificates for etcd, kube-apiserver, kubelet + - Automatic rotation every 90 days + +4. Kogral: Documents architecture decision + - ADR: "Why Cilium over Calico" + - Runbook: "How to scale cluster from 3 to 10 nodes" + +5. Vapora: Orchestrates post-deployment + - Monitor Agent: Setup Prometheus + Grafana + - Security Agent: Vulnerability scanning + - DevOps Agent: Deploy test applications +``` + +### Scenario 2: Production Incident (Database Outage) + +```text +1. Vapora Monitor Agent: Detects PostgreSQL down + - Alert via NATS JetStream + - Trigger incident response pipeline + +2. Kogral: Claude Code queries via MCP + - "PostgreSQL outage postmortems?" + - Returns 3 similar incidents with resolutions + +3. Vapora DevOps Agent: Executes runbook + - Restarts PostgreSQL with adjusted parameters + - Verifies health checks + +4. SecretumVault: Rotates DB credentials + - Generates new dynamic credentials + - Updates applications via Database engine + +5. Kogral: Documents postmortem + - Execution node with root cause, resolution, action items + - Linked to PostgreSQL configuration ADRs +``` + +### Scenario 3: Post-Quantum Cryptography Migration + +```text +1. Kogral: Documents migration decision + - ADR: "Migration to ML-KEM-768 for quantum threat preparation" + - Timeline, risks, mitigation strategies + +2. SecretumVault: Migrates secrets + - Backend change: openssl β†’ oqs + - Re-encrypts secrets with ML-KEM-768 + - Maintains compatibility with classical clients + +3. Provisioning: Updates infrastructure + - Generates new PKI certificates with ML-DSA-65 + - Deploys certificates to services (etcd, K8s API) + - Automatic rollback if health checks fail + +4. Vapora: Orchestrates validation + - Security Agent: Verifies correct cryptography + - Monitor Agent: Validates latency not degraded + - DevOps Agent: Executes integration tests + +5. TypeDialog: Self-service portal for teams + - Form: "Migrate service to PQC" + - prov-gen backend generates updated configuration +``` + +### Scenario 4: CI/CD with AI Validation + +```text +1. Developer: Push to Git repository (Gitea) + +2. Vapora DevOps Agent (trigger via webhook): + - Executes linting, unit tests + - Build Docker image + - Vulnerability scan with Security Agent + +3. TypeDialog: Deployment form + - Environment (staging/production) + - Canary rollout percentage + - Generates validated K8s configuration + +4. Provisioning: Deploys with Tekton + - Apply K8s manifests with kubectl + - Automatic health checks + - Rollback if health check fails + +5. SecretumVault: Injects secrets + - Dynamic DB credentials (TTL 1h) + - API keys from KV engine + - TLS certificates from PKI engine + +6. Kogral: Records deployment + - Execution node with version, timestamp, author + - Link to commit SHA, PR, changes +``` + +--- + +## Why Choose This Ecosystem (Ops Perspective) + +### Versus Alternatives + +| Us | Terraform + Ansible + Vault | +| ---- | ----------------------------- | +| **Typed configuration**: Nickel with pre-runtime validation | YAML/HCL without types, errors at runtime | +| **Integrated orchestration**: Provisioning orchestrator with rollback | Imperative scripts, no automatic recovery | +| **Post-Quantum crypto**: SecretumVault with ML-KEM/ML-DSA today | Vault without PQC roadmap | +| **Unified multi-cloud**: One Nickel configuration for AWS/UpCloud/Local | Separate configurations per cloud | +| **AI-native**: MCP + RAG for assisted generation | No AI assistance, manual configuration | +| **Full Rust stack**: Performance, memory-safety | Mixed Python/Go/Shell with overhead | + +### Technical Investment (Ops Focus) + +| Metric | Value | +| -------- | ------- | +| **Provisioning**: Nickel IaC, 80+ CLI shortcuts | ~40K LOC | +| **SecretumVault**: 4 crypto backends, 4 storage backends | ~11K LOC | +| **Vapora**: NATS JetStream, 12 agent roles | ~50K LOC | +| **TypeDialog**: 6 backends including prov-gen | ~90K LOC | +| **Kogral**: 6 node types, MCP server | ~15K LOC | +| **Total tests** | 4,360+ | +| **Crypto backends** | OpenSSL, OQS (PQC), AWS-LC, RustCrypto | +| **Storage backends** | FS, etcd, SurrealDB, PostgreSQL | + +--- + +## Getting Started (Adoption for Ops Teams) + +### Recommended Progressive Adoption + +1. **SecretumVault**: Secrets management with cryptographic agility (standalone) +2. **Kogral**: Establish operational knowledge base (runbooks, ADRs, postmortems) +3. **TypeDialog**: Configuration wizards for teams (CLI + Web + prov-gen) +4. **Provisioning**: Multi-cloud declarative IaC with orchestrator +5. **Vapora**: Orchestrate Ops agents with budget control (DevOps, Monitor, Security) + +Each project works independently. Synergies emerge when combining them. + +### Quick Start per Project + +**SecretumVault**: + +```bash +# Docker Compose with etcd +docker-compose -f deploy/docker/docker-compose.yml up -d + +# Initialize vault +curl -X POST http://localhost:8200/v1/sys/init -d '{"shares": 5, "threshold": 3}' + +# Unseal with 3 shares +curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-1>"}' +curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-2>"}' +curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-3>"}' + +# Enable PKI engine for certificates +svault secret engine enable pki +``` + +**Kogral**: + +```bash +# Initialize knowledge repository +kogral init + +# Add runbook +kogral add note "PostgreSQL Connection Pool Tuning" \ + --tags "database,postgresql,performance" + +# Add ADR +kogral add decision "Choose Cilium over Calico" \ + --context "Need CNI for K8s with eBPF" \ + --decision "Cilium for performance and observability" \ + --consequences "Higher initial complexity, better long-term performance" + +# Serve MCP server for Claude Code +kogral serve --port 3100 +``` + +**Provisioning**: + +```bash +# Clone repository +git clone https://repo.jesusperez.pro/jesus/provisioning +cd provisioning + +# Configure provider (UpCloud in this example) +cp config/providers/upcloud.example.toml config/providers/upcloud.toml +# Edit with UpCloud credentials + +# Create K8s cluster (Nickel definition) +cat > cluster.ncl <<EOF +{ + provider = "upcloud", + region = "de-fra1", + servers = [ + { name = "k8s-cp-01", plan = "medium", role = "control-plane" }, + { name = "k8s-worker-01", plan = "medium", role = "worker" }, + { name = "k8s-worker-02", plan = "medium", role = "worker" }, + ], + taskservs = ["containerd", "etcd", "kubernetes", "cilium"], +} +EOF + +# Validate configuration +nickel typecheck cluster.ncl + +# Apply (orchestrator with checkpoints) +prov apply cluster.ncl --with-rollback +``` + +**TypeDialog (prov-gen)**: + +```bash +# Execute cluster configuration wizard +typedialog execute examples/ops/cluster-setup.toml \ + --backend prov-gen \ + --output my-cluster.ncl + +# Generated configuration ready for Provisioning +nickel typecheck my-cluster.ncl +prov apply my-cluster.ncl +``` + +**Vapora**: + +```bash +# Deploy with Docker Compose (backend + NATS + SurrealDB) +docker-compose up -d + +# Create project +curl -X POST http://localhost:8001/projects \ + -H "Content-Type: application/json" \ + -d '{"name": "Infrastructure Automation", "description": "DevOps pipelines"}' + +# Create task for DevOps Agent +curl -X POST http://localhost:8001/tasks \ + -H "Content-Type: application/json" \ + -d '{ + "title": "Deploy Prometheus to K8s", + "task_type": "deployment", + "context": {"cluster": "prod-us-east-1", "namespace": "monitoring"} + }' + +# Assign to DevOps Agent +curl -X POST http://localhost:8001/tasks/<task-id>/assign \ + -H "Content-Type: application/json" \ + -d '{"agent_role": "DevOps"}' +``` + +--- + +## Contact + +- **Repositories**: GitHub (private projects) +- **Stack**: Rust, Nickel, Nushell, SurrealDB, Axum +- **License**: Proprietary / To be defined + +--- + +*Modern infrastructure shouldn't require 10 disconnected tools.* +*One ecosystem. Five projects. Real integration for Ops/DevOps.* diff --git a/docs/en/stratiumiops-technical-specs.md b/docs/en/stratiumiops-technical-specs.md new file mode 100644 index 0000000..8964c7e --- /dev/null +++ b/docs/en/stratiumiops-technical-specs.md @@ -0,0 +1,1784 @@ +# Portfolio: Complete Technical Specifications + +## Ecosystem Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ USER LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Leptos WASM β”‚ Ratatui TUI β”‚ CLI (clap) β”‚ MCP Protocol β”‚ +β”‚ (Vapora, Prov) β”‚ (TypeDialog, β”‚ (all) β”‚ (Kogral, Prov) β”‚ +β”‚ β”‚ Prov) β”‚ β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ API LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Axum REST β”‚ WebSocket β”‚ JSON-RPC 2.0 β”‚ NATS JetStream β”‚ +β”‚ (40+ endpoints) β”‚ (real-time) β”‚ (MCP) β”‚ (messaging) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DOMAIN LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Project Mgmt β”‚ Knowledge Graph β”‚ Form Engine β”‚ IaC Engine β”‚ Vault β”‚ +β”‚ (Vapora) β”‚ (Kogral) β”‚ (TypeDialog) β”‚ (Provisioning) β”‚ (SecretumV.)β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ Agent Coord β”‚ Embeddings β”‚ Agent Exec β”‚ Orchestrator β”‚ Seal/Unseal β”‚ +β”‚ (Vapora) β”‚ (Kogral) β”‚ (TypeDialog) β”‚ (Provisioning) β”‚ (SecretumV.)β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ LLM Router β”‚ MCP Server β”‚ Prov-gen β”‚ Security Layer β”‚ β”‚ +β”‚ (Vapora) β”‚ (Kogral) β”‚ (TypeDialog) β”‚ (Provisioning) β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PERSISTENCE LAYER β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SurrealDB β”‚ Filesystem β”‚ NATS JetStream β”‚ etcd β”‚ PG β”‚ +β”‚ (multi-tenant β”‚ (git-native β”‚ (durable β”‚ (SecretumVault β”‚(Vault β”‚ +β”‚ scopes) β”‚ markdown) β”‚ messaging) β”‚ HA) β”‚ ent.) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 1. Vapora: Complete Specifications + +### Workspace (13 crates) + +```text +crates/ +β”œβ”€β”€ vapora-shared/ # Core: models, errors, types +β”œβ”€β”€ vapora-backend/ # Axum REST API (40+ endpoints, 79 tests) +β”œβ”€β”€ vapora-agents/ # Agent orchestration + learning (67 tests) +β”œβ”€β”€ vapora-llm-router/ # Multi-provider routing + budget (53 tests) +β”œβ”€β”€ vapora-swarm/ # Swarm coordination + metrics (6 tests) +β”œβ”€β”€ vapora-knowledge-graph/# Temporal KG + learning curves (13 tests) +β”œβ”€β”€ vapora-frontend/ # Leptos WASM UI (Kanban) +β”œβ”€β”€ vapora-mcp-server/ # MCP protocol gateway +β”œβ”€β”€ vapora-tracking/ # Task/project storage +β”œβ”€β”€ vapora-telemetry/ # OpenTelemetry integration +β”œβ”€β”€ vapora-analytics/ # Event pipeline +β”œβ”€β”€ vapora-worktree/ # Git worktree management +└── vapora-doc-lifecycle/ # Documentation management +``` + +### Domain Models + +```rust +// vapora-shared/src/models.rs + +// ─── Project Management ─────────────────────────────────────── +pub struct Project { + pub id: String, + pub name: String, + pub description: Option<String>, + pub scope: String, // Multi-tenant scope + pub status: ProjectStatus, + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, +} + +pub enum ProjectStatus { + Active, + Archived, + OnHold, +} + +pub struct Task { + pub id: String, + pub project_id: String, + pub title: String, + pub description: Option<String>, + pub status: TaskStatus, + pub priority: TaskPriority, + pub assigned_agent: Option<String>, + pub tags: Vec<String>, + pub order: i32, + pub created_at: DateTime<Utc>, +} + +pub enum TaskStatus { + Todo, + Doing, + Review, + Done, +} + +pub enum TaskPriority { + Low, + Medium, + High, + Critical, +} + +// ─── Agent System ───────────────────────────────────────────── +pub struct Agent { + pub id: String, + pub role: AgentRole, + pub status: AgentStatus, + pub provider: LLMProvider, + pub current_load: f64, + pub last_heartbeat: DateTime<Utc>, +} + +pub enum AgentRole { + Architect, + Developer, + CodeReviewer, + Tester, + Documenter, + Marketer, + Presenter, + DevOps, + Monitor, + Security, + ProjectManager, + DecisionMaker, +} + +pub enum AgentStatus { + Ready, + Busy, + Offline, + Maintenance, +} + +// ─── Learning System ────────────────────────────────────────── +pub struct ExpertiseProfile { + pub agent_id: String, + pub task_type: String, + pub success_rate: f64, + pub avg_duration: Duration, + pub execution_count: u32, + pub recent_weight: f64, // 3x for last 7 days + pub confidence: f64, // Prevents overfitting + pub last_updated: DateTime<Utc>, +} + +// Scoring: 0.3*load + 0.5*expertise + 0.2*confidence + +// ─── LLM Router ─────────────────────────────────────────────── +pub enum LLMProvider { + Claude, + OpenAI, + Gemini, + Ollama, +} + +pub struct RoutingRule { + pub pattern: String, // Regex for task type + pub provider: LLMProvider, + pub model: String, + pub fallback_chain: Vec<LLMProvider>, +} + +pub struct BudgetConfig { + pub role: AgentRole, + pub monthly_limit_cents: u32, + pub weekly_limit_cents: Option<u32>, + pub enforcement: BudgetEnforcement, +} + +pub enum BudgetEnforcement { + Normal, + NearThreshold, // 80%+ + Exceeded, // 100%+ +} + +pub struct CostRecord { + pub provider: LLMProvider, + pub model: String, + pub input_tokens: u32, + pub output_tokens: u32, + pub cost_cents: f64, + pub task_type: String, + pub agent_id: String, + pub timestamp: DateTime<Utc>, +} +``` + +### API Endpoints + +```rust +// vapora-backend/src/api/mod.rs + +// ─── Projects ───────────────────────────────────────────────── +GET /projects // List projects (filtered by scope) +POST /projects // Create project +GET /projects/:id // Get project details +PUT /projects/:id // Update project +DELETE /projects/:id // Archive project + +// ─── Tasks ──────────────────────────────────────────────────── +GET /projects/:id/tasks // List tasks for project +POST /tasks // Create task +GET /tasks/:id // Get task details +PUT /tasks/:id // Update task +DELETE /tasks/:id // Delete task +POST /tasks/:id/assign // Assign to agent +PUT /tasks/:id/status // Update status (Kanban) +PUT /tasks/:id/order // Reorder task + +// ─── Agents ─────────────────────────────────────────────────── +GET /agents // List all agents +GET /agents/:id // Get agent details +GET /agents/:id/health // Health check +GET /agents/:role/expertise // Get expertise for role +POST /agents/register // Register new agent +DELETE /agents/:id // Unregister agent + +// ─── LLM Router ─────────────────────────────────────────────── +POST /llm/route // Route request to provider +GET /llm/providers // List available providers +GET /llm/budget/:role // Get budget status +PUT /llm/budget/:role // Set budget limits +GET /llm/costs // Cost report +GET /llm/costs/:role // Cost by role +GET /llm/costs/:provider // Cost by provider + +// ─── Swarm ──────────────────────────────────────────────────── +POST /swarm/assign // Assign task to swarm +GET /swarm/status // Swarm status +GET /swarm/agents // List swarm agents +POST /swarm/balance // Rebalance load + +// ─── Pipelines ──────────────────────────────────────────────── +POST /pipelines // Create pipeline +GET /pipelines/:id // Get pipeline status +POST /pipelines/:id/approve // Approve gate +POST /pipelines/:id/cancel // Cancel pipeline + +// ─── Knowledge Graph ────────────────────────────────────────── +POST /knowledge/query // Query knowledge graph +GET /knowledge/similar/:task_id // Find similar past tasks +GET /knowledge/learning/:agent // Get learning curve + +// ─── Observability ──────────────────────────────────────────── +GET /metrics // Prometheus metrics +GET /health // Health check +GET /health/ready // Readiness probe +GET /health/live // Liveness probe +``` + +### NATS Subjects + +```rust +// vapora-agents/src/messages.rs + +// ─── Task Assignment ────────────────────────────────────────── +const TASK_ASSIGN: &str = "vapora.tasks.assign"; +// Payload: TaskAssignment { task_id, agent_id, task_type, payload } + +const TASK_RESULT: &str = "vapora.tasks.results"; +// Payload: TaskResult { task_id, agent_id, status, output, duration_ms, tokens } + +// ─── Agent Coordination ─────────────────────────────────────── +const AGENT_HEARTBEAT: &str = "vapora.agents.heartbeat"; +// Payload: Heartbeat { agent_id, status, current_load } + +const AGENT_REGISTER: &str = "vapora.agents.register"; +// Payload: AgentRegistration { agent_id, role, capabilities } + +// ─── Pipeline Events ────────────────────────────────────────── +const PIPELINE_STAGE: &str = "vapora.pipelines.stage"; +// Payload: StageEvent { pipeline_id, stage, status } + +const PIPELINE_APPROVAL: &str = "vapora.pipelines.approval"; +// Payload: ApprovalRequest { pipeline_id, stage, requester } +``` + +### Frontend Components (Leptos) + +```rust +// vapora-frontend/src/components/ + +// ─── Kanban Board ───────────────────────────────────────────── +#[component] +pub fn KanbanBoard(project_id: String) -> impl IntoView { + // Columns: Todo, Doing, Review, Done + // Drag-and-drop with optimistic updates + // WebSocket subscription for real-time sync +} + +#[component] +pub fn KanbanColumn(status: TaskStatus, tasks: Vec<Task>) -> impl IntoView { + // Droppable zone + // Task cards with priority indicators +} + +#[component] +pub fn TaskCard(task: Task) -> impl IntoView { + // Draggable card + // Tags, priority, assignee display + // Click to open details +} + +// ─── Project Management ─────────────────────────────────────── +#[component] +pub fn ProjectList() -> impl IntoView { + // Grid/list view toggle + // Filter by status + // Create project modal +} + +#[component] +pub fn ProjectDetail(project_id: String) -> impl IntoView { + // Project info + // Kanban board + // Agent assignments + // Pipeline status +} + +// ─── Agent Dashboard ────────────────────────────────────────── +#[component] +pub fn AgentOverview() -> impl IntoView { + // Agent status grid + // Load indicators + // Expertise heatmap +} + +#[component] +pub fn CostDashboard() -> impl IntoView { + // Budget usage by role + // Cost trends charts + // Provider breakdown +} +``` + +--- + +## 2. Kogral: Complete Specifications + +### Workspace (3 crates) + +```text +crates/ +β”œβ”€β”€ kogral-core/ # Core library (48 tests) +β”‚ β”œβ”€β”€ models/ # Node, Edge, Graph types +β”‚ β”œβ”€β”€ storage/ # Multi-backend storage +β”‚ β”œβ”€β”€ parser/ # Markdown + YAML parser +β”‚ β”œβ”€β”€ block_parser/ # Logseq block support +β”‚ β”œβ”€β”€ query/ # Text + semantic search +β”‚ β”œβ”€β”€ embeddings/ # fastembed + rig-core +β”‚ β”œβ”€β”€ export/ # Tera templates +β”‚ β”œβ”€β”€ sync/ # Filesystem ↔ SurrealDB +β”‚ β”œβ”€β”€ config/ # Nickel config loader +β”‚ └── inheritance/ # Guideline inheritance +β”œβ”€β”€ kogral-cli/ # CLI (13 commands) +└── kogral-mcp/ # MCP server (7 tools) +``` + +### Domain Models + +```rust +// kogral-core/src/models.rs + +// ─── Node Types ─────────────────────────────────────────────── +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum NodeType { + Note, // General notes + Decision, // ADRs + Guideline, // Standards + Pattern, // Reusable solutions + Journal, // Daily logs + Execution, // Agent records +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Node { + pub id: String, + pub node_type: NodeType, + pub title: String, + pub content: String, // Markdown body + pub metadata: HashMap<String, Value>, + pub tags: Vec<String>, + pub graph_id: String, // Which graph this belongs to + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, +} + +// ─── Relationships ──────────────────────────────────────────── +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum RelationType { + RelatesTo, + DependsOn, + Implements, + Extends, + Supersedes, + Explains, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Edge { + pub source: String, + pub target: String, + pub relation: RelationType, + pub weight: f64, + pub metadata: HashMap<String, Value>, +} + +// ─── Graph ──────────────────────────────────────────────────── +#[derive(Debug, Clone)] +pub struct Graph { + pub id: String, + pub name: String, + pub graph_type: GraphType, + pub nodes: HashMap<String, Node>, + pub edges: Vec<Edge>, +} + +pub enum GraphType { + Project, // Local, in .kogral/ + Shared, // Organization-wide, in SurrealDB +} + +// ─── ADR Structure ──────────────────────────────────────────── +#[derive(Debug, Serialize, Deserialize)] +pub struct DecisionRecord { + pub title: String, + pub status: DecisionStatus, + pub context: String, + pub decision: String, + pub consequences: String, + pub alternatives: Vec<Alternative>, + pub related_decisions: Vec<String>, +} + +pub enum DecisionStatus { + Proposed, + Accepted, + Deprecated, + Superseded, +} + +// ─── Logseq Blocks ──────────────────────────────────────────── +#[derive(Debug, Clone)] +pub struct Block { + pub id: String, + pub content: String, + pub children: Vec<Block>, + pub properties: HashMap<String, String>, + pub task_status: Option<TaskStatus>, + pub tags: Vec<String>, + pub references: Vec<String>, // [[wikilinks]] +} + +pub enum TaskStatus { + TODO, + DOING, + DONE, + LATER, + NOW, + WAITING, + CANCELLED, +} +``` + +### Storage Trait + +```rust +// kogral-core/src/storage/mod.rs + +#[async_trait] +pub trait Storage: Send + Sync { + // ─── Node Operations ────────────────────────────────────── + async fn create_node(&self, node: &Node) -> Result<String>; + async fn get_node(&self, id: &str) -> Result<Option<Node>>; + async fn update_node(&self, node: &Node) -> Result<()>; + async fn delete_node(&self, id: &str) -> Result<()>; + async fn list_nodes(&self, filter: NodeFilter) -> Result<Vec<Node>>; + + // ─── Edge Operations ────────────────────────────────────── + async fn create_edge(&self, edge: &Edge) -> Result<()>; + async fn get_edges(&self, node_id: &str, direction: EdgeDirection) -> Result<Vec<Edge>>; + async fn delete_edge(&self, source: &str, target: &str) -> Result<()>; + + // ─── Search ─────────────────────────────────────────────── + async fn search_text(&self, query: &str, limit: usize) -> Result<Vec<Node>>; + async fn search_semantic(&self, embedding: &[f32], limit: usize) -> Result<Vec<Node>>; + + // ─── Graph Operations ───────────────────────────────────── + async fn get_connected(&self, node_id: &str, depth: usize) -> Result<Graph>; + async fn get_path(&self, from: &str, to: &str) -> Result<Option<Vec<Edge>>>; +} + +// Implementations +pub struct FilesystemStorage { + base_path: PathBuf, // .kogral/ +} + +pub struct SurrealDbStorage { + client: Surreal<Client>, + namespace: String, + database: String, +} + +pub struct MemoryStorage { + nodes: DashMap<String, Node>, + edges: DashMap<String, Vec<Edge>>, +} +``` + +### Embeddings + +```rust +// kogral-core/src/embeddings.rs + +pub enum EmbeddingProvider { + FastEmbed { + model: String, // "BAAI/bge-small-en-v1.5" + cache_dir: PathBuf, + }, + RigCore { + provider: RigProvider, // OpenAI, Anthropic, etc. + model: String, + }, +} + +#[async_trait] +pub trait Embedder: Send + Sync { + async fn embed(&self, text: &str) -> Result<Vec<f32>>; + async fn embed_batch(&self, texts: &[String]) -> Result<Vec<Vec<f32>>>; + fn dimensions(&self) -> usize; + fn model_name(&self) -> &str; +} + +// FastEmbed: 384 dimensions, local, offline +pub struct FastEmbedder { + model: fastembed::TextEmbedding, +} + +// RigCore: Cloud providers +pub struct RigEmbedder { + client: Box<dyn rig_core::Embedder>, +} +``` + +### CLI Commands + +```bash +# ─── Initialization ──────────────────────────────────────────── +kogral init # Create .kogral/ directory +kogral init --with-surreal # Also setup SurrealDB connection + +# ─── Adding Content ──────────────────────────────────────────── +kogral add note "Title" # Interactive note creation +kogral add decision "Title" # Guided ADR creation +kogral add guideline "Title" # Add team guideline +kogral add pattern "Title" # Document pattern +kogral add journal # Today's journal entry + +# ─── Querying ────────────────────────────────────────────────── +kogral search "query" # Text search +kogral search --semantic "query" # Semantic search +kogral search --type decision # Filter by type +kogral search --tag auth # Filter by tag + +# ─── Relationships ───────────────────────────────────────────── +kogral link <src> <dst> relates_to # Create relationship +kogral link <src> <dst> implements # Implementation link +kogral unlink <src> <dst> # Remove relationship + +# ─── Viewing ─────────────────────────────────────────────────── +kogral list # List all nodes +kogral list --type pattern # Filter by type +kogral show <id> # Display node details +kogral graph # Output DOT format +kogral graph --connected <id> # Subgraph from node + +# ─── Sync & Export ───────────────────────────────────────────── +kogral sync # Sync filesystem ↔ SurrealDB +kogral export markdown # Export to markdown +kogral export json # Export to JSON +kogral import <path> # Import from Logseq/markdown + +# ─── MCP Server ──────────────────────────────────────────────── +kogral serve # Start MCP server (stdio) +kogral serve --port 3000 # HTTP mode + +# ─── Configuration ───────────────────────────────────────────── +kogral config # Show current config +kogral config set <key> <value> # Set config value +``` + +### MCP Protocol + +```rust +// kogral-mcp/src/protocol.rs + +// ─── Tools ──────────────────────────────────────────────────── +pub const TOOLS: &[Tool] = &[ + Tool { + name: "search", + description: "Search knowledge graph", + input_schema: json!({ + "type": "object", + "properties": { + "query": { "type": "string" }, + "node_type": { "type": "string", "optional": true }, + "semantic": { "type": "boolean", "default": false }, + "limit": { "type": "integer", "default": 10 } + }, + "required": ["query"] + }), + }, + Tool { + name: "add_note", + description: "Add a note to the knowledge graph", + input_schema: json!({...}), + }, + Tool { + name: "add_decision", + description: "Record an architectural decision", + input_schema: json!({...}), + }, + Tool { + name: "link", + description: "Create relationship between nodes", + input_schema: json!({...}), + }, + Tool { + name: "get_guidelines", + description: "Get applicable guidelines", + input_schema: json!({...}), + }, + Tool { + name: "list_graphs", + description: "List available knowledge graphs", + input_schema: json!({}), + }, + Tool { + name: "export", + description: "Export knowledge graph", + input_schema: json!({...}), + }, +]; + +// ─── Resources ──────────────────────────────────────────────── +pub const RESOURCES: &[Resource] = &[ + Resource { + uri: "kogral://project/notes", + name: "Project Notes", + description: "All notes in current project", + }, + Resource { + uri: "kogral://project/decisions", + name: "Project Decisions", + description: "All ADRs in current project", + }, + Resource { + uri: "kogral://project/guidelines", + name: "Project Guidelines", + description: "Effective guidelines (with inheritance)", + }, + Resource { + uri: "kogral://project/patterns", + name: "Project Patterns", + description: "All patterns in current project", + }, + Resource { + uri: "kogral://shared/guidelines", + name: "Shared Guidelines", + description: "Organization-wide guidelines", + }, + Resource { + uri: "kogral://shared/patterns", + name: "Shared Patterns", + description: "Organization-wide patterns", + }, +]; + +// ─── Prompts ────────────────────────────────────────────────── +pub const PROMPTS: &[Prompt] = &[ + Prompt { + name: "summarize_project", + description: "Summarize project knowledge", + arguments: json!([]), + }, + Prompt { + name: "find_related", + description: "Find related knowledge for a topic", + arguments: json!([ + { "name": "topic", "required": true } + ]), + }, +]; +``` + +--- + +## 3. TypeDialog: Complete Specifications + +### Workspace (8 crates) + +```text +crates/ +β”œβ”€β”€ typedialog-core/ # Core library +β”‚ β”œβ”€β”€ form/ # Form models +β”‚ β”œβ”€β”€ field/ # Field types (8) +β”‚ β”œβ”€β”€ validation/ # Validators +β”‚ β”œβ”€β”€ backend/ # Backend trait +β”‚ β”œβ”€β”€ backends/ # 6 implementations +β”‚ β”œβ”€β”€ output/ # 4 output formats +β”‚ β”œβ”€β”€ i18n/ # Fluent integration +β”‚ └── nickel/ # Contract validation +β”œβ”€β”€ typedialog/ # CLI binary +β”œβ”€β”€ typedialog-tui/ # TUI binary +β”œβ”€β”€ typedialog-web/ # Web binary +β”œβ”€β”€ typedialog-ai/ # AI backend +β”œβ”€β”€ typedialog-agent/ +β”‚ β”œβ”€β”€ typedialog-ag-core/ # Agent runtime +β”‚ └── typedialog-ag/ # Agent CLI +└── typedialog-prov-gen/ # IaC generation +``` + +### Form Schema + +```toml +# Form definition (TOML) + +[form] +id = "example_form" +version = "1.0.0" +title = "Example Form" +description = "Demonstrates all features" + +# ─── Sections ────────────────────────────────────────────────── +[[sections]] +id = "basic" +title = "Basic Information" +description = "Required fields" + +[[sections.fields]] +id = "name" +type = "text" +label = "Full Name" +required = true +validation.min_length = 2 +validation.max_length = 100 +validation.pattern = "^[a-zA-Z\\s]+$" + +[[sections.fields]] +id = "email" +type = "text" +label = "Email Address" +required = true +validation.pattern = "^[^@]+@[^@]+\\.[^@]+$" + +[[sections.fields]] +id = "department" +type = "select" +label = "Department" +required = true +options = [ + { value = "engineering", label = "Engineering" }, + { value = "product", label = "Product" }, + { value = "design", label = "Design" }, +] + +# ─── Conditional Fields ──────────────────────────────────────── +[[sections.fields]] +id = "team_size" +type = "select" +label = "Team Size" +condition = { field = "department", equals = "engineering" } +options = [ + { value = "small", label = "1-5" }, + { value = "medium", label = "6-20" }, + { value = "large", label = "20+" }, +] + +# ─── Multi-select ────────────────────────────────────────────── +[[sections.fields]] +id = "skills" +type = "multi-select" +label = "Skills" +display_mode = "grid" # list, grid, dropdown +options = [ + { value = "rust", label = "Rust" }, + { value = "typescript", label = "TypeScript" }, + { value = "python", label = "Python" }, + { value = "go", label = "Go" }, +] + +# ─── Repeating Groups ────────────────────────────────────────── +[[sections.fields]] +id = "projects" +type = "group" +label = "Previous Projects" +repeatable = true +min_items = 1 +max_items = 5 + +[[sections.fields.fields]] +id = "project_name" +type = "text" +label = "Project Name" + +[[sections.fields.fields]] +id = "project_role" +type = "select" +label = "Role" +options = [...] + +# ─── Output ──────────────────────────────────────────────────── +[output] +format = "json" # json, yaml, toml, nickel +validation = "nickel://schemas/employee.ncl" +template = "templates/output.tera" +``` + +### Backend Trait + +```rust +// typedialog-core/src/backend/mod.rs + +#[async_trait] +pub trait Backend: Send + Sync { + fn name(&self) -> &str; + + async fn execute(&self, form: &Form) -> Result<FormResponse>; + + async fn render_field( + &self, + field: &Field, + value: Option<&Value>, + ) -> Result<Value>; + + fn supports_streaming(&self) -> bool { + false + } + + fn supports_validation(&self) -> bool { + true + } +} + +// ─── Backend Factory ────────────────────────────────────────── +pub enum BackendType { + Cli, + Tui, + Web, + Ai, + Agent, + ProvGen, +} + +pub struct BackendFactory; + +impl BackendFactory { + pub fn create(backend_type: BackendType, config: &Config) -> Box<dyn Backend> { + match backend_type { + BackendType::Cli => Box::new(CliBackend::new(config)), + BackendType::Tui => Box::new(TuiBackend::new(config)), + BackendType::Web => Box::new(WebBackend::new(config)), + BackendType::Ai => Box::new(AiBackend::new(config)), + BackendType::Agent => Box::new(AgentBackend::new(config)), + BackendType::ProvGen => Box::new(ProvGenBackend::new(config)), + } + } +} + +// ─── CLI Backend ────────────────────────────────────────────── +pub struct CliBackend { + theme: inquire::ui::RenderConfig, +} + +// ─── TUI Backend ────────────────────────────────────────────── +pub struct TuiBackend { + terminal: Terminal<CrosstermBackend<Stdout>>, +} + +// ─── Web Backend ────────────────────────────────────────────── +pub struct WebBackend { + port: u16, + templates: tera::Tera, +} + +// ─── AI Backend ─────────────────────────────────────────────── +pub struct AiBackend { + index: tantivy::Index, + embedder: Box<dyn Embedder>, + graph: petgraph::Graph<String, String>, +} + +// ─── Agent Backend ──────────────────────────────────────────── +pub struct AgentBackend { + providers: HashMap<String, Box<dyn LLMProvider>>, + templates: tera::Tera, +} + +// ─── ProvGen Backend ────────────────────────────────────────── +pub struct ProvGenBackend { + templates: HashMap<CloudProvider, tera::Tera>, + validators: Vec<Box<dyn Validator>>, +} +``` + +### Agent MDX Format + +```markdown +--- +name: code_reviewer +version: "1.0" +provider: claude +model: claude-sonnet-4-20250514 +temperature: 0.3 +max_tokens: 4096 +output_format: json +output_schema: | + { + "type": "object", + "properties": { + "issues": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { "enum": ["critical", "warning", "info"] }, + "line": { "type": "integer" }, + "message": { "type": "string" }, + "suggestion": { "type": "string" } + } + } + }, + "summary": { "type": "string" } + } + } +--- + +# Code Review Agent + +## System + +You are an expert code reviewer... + +## User + +Review this {{language}} code: + +```{{language}} +{{code}} +``` + +Guidelines: +{{guidelines}} +``` + +### IaC Generation + +```rust +// typedialog-prov-gen/src/lib.rs + +pub enum CloudProvider { + Aws, + Gcp, + Azure, + Hetzner, + UpCloud, + Lxd, +} + +pub struct InfraConfig { + pub provider: CloudProvider, + pub region: String, + pub environment: Environment, + pub resources: Vec<Resource>, + pub networking: NetworkConfig, + pub security: SecurityConfig, + pub tags: HashMap<String, String>, +} + +pub struct Generator { + templates: HashMap<CloudProvider, tera::Tera>, + validators: ValidationPipeline, // 7 layers +} + +impl Generator { + pub async fn generate(&self, config: &InfraConfig) -> Result<GeneratedIaC> { + // 1. Input validation + self.validators.validate_input(config)?; + + // 2. Load provider template + let template = self.templates + .get(&config.provider) + .ok_or(Error::UnsupportedProvider)?; + + // 3. Render Nickel + let nickel = template.render("main.ncl.tera", &config)?; + + // 4. Validate generated Nickel + self.validators.validate_nickel(&nickel)?; + + // 5. Split into files + let files = self.split_output(&nickel, config)?; + + Ok(GeneratedIaC { provider: config.provider, files }) + } +} + +// 7-Layer Validation Pipeline +pub struct ValidationPipeline { + layers: Vec<Box<dyn Validator>>, +} + +// Layers: +// 1. Schema validation (structure) +// 2. Type validation (Nickel contracts) +// 3. Provider validation (provider-specific rules) +// 4. Security validation (no exposed secrets) +// 5. Cost validation (budget limits) +// 6. Compliance validation (policy rules) +// 7. Integration validation (cross-resource refs) +``` + +--- + +## 4. Provisioning: Complete Specifications + +### Directory Structure + +```text +provisioning/ +β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ cli/ # Main CLI (211 lines) +β”‚ β”œβ”€β”€ nulib/ # Nushell libraries +β”‚ β”‚ β”œβ”€β”€ config.nu # 476+ accessors +β”‚ β”‚ β”œβ”€β”€ provider.nu # Provider abstraction +β”‚ β”‚ β”œβ”€β”€ workflow.nu # Workflow execution +β”‚ β”‚ └── utils.nu # Utilities +β”‚ └── scripts/ # Automation scripts +β”œβ”€β”€ extensions/ +β”‚ β”œβ”€β”€ providers/ +β”‚ β”‚ β”œβ”€β”€ aws/ # AWS provider +β”‚ β”‚ β”œβ”€β”€ upcloud/ # UpCloud provider +β”‚ β”‚ └── local/ # Local (LXD) provider +β”‚ β”œβ”€β”€ taskservs/ # 50+ services +β”‚ β”œβ”€β”€ clusters/ # Deployment templates +β”‚ └── workflows/ # Workflow definitions +β”œβ”€β”€ platform/ +β”‚ β”œβ”€β”€ orchestrator/ # Rust workflow engine +β”‚ β”œβ”€β”€ control-center/ # Axum backend +β”‚ β”œβ”€β”€ control-center-ui/ # Leptos frontend +β”‚ β”œβ”€β”€ installer/ # Multi-mode installer +β”‚ β”œβ”€β”€ mcp-server/ # MCP server +β”‚ β”œβ”€β”€ ai-service/ # AI operations +β”‚ β”œβ”€β”€ rag/ # RAG system +β”‚ β”œβ”€β”€ vault-service/ # Secrets management +β”‚ β”œβ”€β”€ detector/ # Anomaly detection +β”‚ β”œβ”€β”€ extension-registry/ # Extension catalog +β”‚ └── provisioning-daemon/ # Service daemon +β”œβ”€β”€ schemas/ # Nickel schemas +β”‚ β”œβ”€β”€ server.ncl +β”‚ β”œβ”€β”€ network.ncl +β”‚ β”œβ”€β”€ storage.ncl +β”‚ β”œβ”€β”€ kubernetes.ncl +β”‚ └── security.ncl +└── docs/ # Documentation +``` + +### Nickel Schemas + +```nickel +# schemas/server.ncl + +let Server = { + name + | String + | doc "Server hostname", + + provider + | [ | 'aws, 'upcloud, 'local |] + | doc "Cloud provider", + + spec + | { + cpu + | Number + | default = 2 + | doc "CPU cores", + memory_gb + | Number + | default = 4 + | doc "Memory in GB", + disk_gb + | Number + | default = 50 + | doc "Root disk in GB", + os + | { + family | [ | 'ubuntu, 'debian, 'rocky |], + version | String, + }, + }, + + networking + | { + vpc | String | optional, + subnet | String | optional, + public_ip | Bool | default = false, + security_groups | Array String | default = [], + private_ip | String | optional, + }, + + storage + | Array { + name | String, + size_gb | Number, + type | [ | 'ssd, 'hdd, 'nvme |] | default = 'ssd, + mount_point | String, + } + | default = [], + + tags + | { _ : String } + | default = {}, + + metadata + | { _ : Dyn } + | default = {}, +} +in Server +``` + +### Orchestrator + +```rust +// platform/orchestrator/src/lib.rs + +pub struct Orchestrator { + state: StateManager, + executor: WorkflowExecutor, + scheduler: Scheduler, + providers: HashMap<String, Box<dyn Provider>>, +} + +impl Orchestrator { + pub async fn execute(&self, workflow: Workflow) -> Result<ExecutionResult> { + // 1. Create checkpoint + let checkpoint = self.state.checkpoint(&workflow)?; + + // 2. Resolve dependencies (topological sort) + let tasks = self.resolve_dependencies(&workflow)?; + + // 3. Execute with retry + for task in tasks { + let result = self.execute_with_retry(&task).await; + + match result { + Ok(output) => { + self.state.record_success(&task, &output)?; + } + Err(e) => { + // Rollback to checkpoint + self.state.rollback(&checkpoint)?; + return Err(e); + } + } + } + + Ok(ExecutionResult::success()) + } + + async fn execute_with_retry(&self, task: &Task) -> Result<Output> { + let mut attempts = 0; + let max_attempts = task.retry_config.max_attempts; + + loop { + attempts += 1; + match self.executor.run(task).await { + Ok(output) => return Ok(output), + Err(e) if attempts < max_attempts => { + let delay = self.calculate_backoff(attempts); + tokio::time::sleep(delay).await; + } + Err(e) => return Err(e), + } + } + } + + fn calculate_backoff(&self, attempt: u32) -> Duration { + // Exponential backoff: 2^attempt * base_delay + Duration::from_secs(2u64.pow(attempt) * self.config.base_delay_secs) + } +} + +// ─── State Management ───────────────────────────────────────── +pub struct StateManager { + store: Box<dyn StateStore>, +} + +impl StateManager { + pub fn checkpoint(&self, workflow: &Workflow) -> Result<Checkpoint> { + let state = self.capture_current_state(workflow)?; + let id = self.store.save_checkpoint(&state)?; + Ok(Checkpoint { id, state }) + } + + pub fn rollback(&self, checkpoint: &Checkpoint) -> Result<()> { + self.restore_state(&checkpoint.state) + } +} +``` + +### Security Layer + +```rust +// platform/control-center/src/security/ + +// ─── Authentication ─────────────────────────────────────────── +pub struct AuthService { + jwt_secret: Secret<String>, + hasher: Argon2Config, + mfa: MfaService, +} + +impl AuthService { + pub async fn authenticate(&self, credentials: Credentials) -> Result<Token> { + // 1. Verify password + let user = self.verify_password(&credentials)?; + + // 2. Check MFA if enabled + if user.mfa_enabled { + self.mfa.verify(&user, &credentials.mfa_code)?; + } + + // 3. Generate JWT + let token = self.generate_jwt(&user)?; + + // 4. Audit log + self.audit.log_authentication(&user, AuthResult::Success)?; + + Ok(token) + } +} + +// ─── MFA Service ────────────────────────────────────────────── +pub struct MfaService { + totp: TotpProvider, + webauthn: WebAuthnProvider, +} + +impl MfaService { + pub fn verify(&self, user: &User, code: &MfaCode) -> Result<()> { + match &user.mfa_method { + MfaMethod::Totp => self.totp.verify(&user.totp_secret, code), + MfaMethod::WebAuthn => self.webauthn.verify(&user.credentials, code), + } + } +} + +// ─── Authorization (Cedar) ──────────────────────────────────── +pub struct AuthzService { + engine: cedar_policy::Authorizer, + policies: cedar_policy::PolicySet, +} + +impl AuthzService { + pub fn authorize(&self, request: &AuthzRequest) -> Result<Decision> { + let principal = self.build_principal(&request.user)?; + let action = self.build_action(&request.action)?; + let resource = self.build_resource(&request.resource)?; + + let decision = self.engine.is_authorized( + &principal, + &action, + &resource, + &self.policies, + )?; + + Ok(decision) + } +} + +// ─── KMS ────────────────────────────────────────────────────── +pub enum KmsBackend { + RustyVault(RustyVaultClient), + Age(AgeClient), + AwsKms(AwsKmsClient), + HashiVault(VaultClient), + Cosmian(CosmianClient), +} + +pub struct KmsService { + backend: KmsBackend, +} + +impl KmsService { + pub async fn encrypt(&self, plaintext: &[u8], key_id: &str) -> Result<Vec<u8>> { + // Envelope encryption + let dek = self.generate_dek()?; + let ciphertext = self.encrypt_with_dek(plaintext, &dek)?; + let encrypted_dek = self.wrap_key(&dek, key_id).await?; + + Ok(self.package(ciphertext, encrypted_dek)) + } + + pub async fn decrypt(&self, blob: &[u8], key_id: &str) -> Result<Vec<u8>> { + let (ciphertext, encrypted_dek) = self.unpackage(blob)?; + let dek = self.unwrap_key(&encrypted_dek, key_id).await?; + self.decrypt_with_dek(&ciphertext, &dek) + } +} + +// ─── Audit ──────────────────────────────────────────────────── +pub struct AuditService { + store: Box<dyn AuditStore>, + retention_years: u32, // 7 years +} + +impl AuditService { + pub fn log(&self, event: AuditEvent) -> Result<()> { + let record = AuditRecord { + id: Uuid::new_v4(), + timestamp: Utc::now(), + event, + user_id: current_user_id()?, + ip_address: current_ip()?, + user_agent: current_user_agent()?, + }; + + self.store.save(&record) + } + + pub fn export(&self, format: ExportFormat, range: DateRange) -> Result<Vec<u8>> { + let records = self.store.query(range)?; + + match format { + ExportFormat::Json => serde_json::to_vec(&records), + ExportFormat::Csv => self.to_csv(&records), + ExportFormat::Parquet => self.to_parquet(&records), + ExportFormat::Avro => self.to_avro(&records), + ExportFormat::Pdf => self.to_pdf(&records), + } + } +} +``` + +### MCP Server + +```rust +// platform/mcp-server/src/tools.rs + +pub const TOOLS: &[Tool] = &[ + // ─── Query Tools ────────────────────────────────────────── + Tool { + name: "query_infrastructure", + description: "Query infrastructure state using natural language", + input_schema: json!({ + "query": { "type": "string" }, + "provider": { "type": "string", "optional": true } + }), + }, + + // ─── Generation Tools ───────────────────────────────────── + Tool { + name: "generate_config", + description: "Generate Nickel configuration from description", + input_schema: json!({ + "description": { "type": "string" }, + "provider": { "type": "string" }, + "resource_type": { "type": "string" } + }), + }, + + // ─── Validation Tools ───────────────────────────────────── + Tool { + name: "validate_config", + description: "Validate Nickel configuration", + input_schema: json!({ + "config": { "type": "string" }, + "strict": { "type": "boolean", "default": true } + }), + }, + + // ─── Cost Tools ─────────────────────────────────────────── + Tool { + name: "estimate_cost", + description: "Estimate monthly cost for configuration", + input_schema: json!({ + "config": { "type": "string" }, + "region": { "type": "string", "optional": true } + }), + }, + + // ─── Compliance Tools ───────────────────────────────────── + Tool { + name: "check_compliance", + description: "Check configuration against compliance rules", + input_schema: json!({ + "config": { "type": "string" }, + "framework": { "enum": ["soc2", "hipaa", "gdpr", "pci"] } + }), + }, + + // ─── Migration Tools ────────────────────────────────────── + Tool { + name: "plan_migration", + description: "Generate migration plan between configurations", + input_schema: json!({ + "current": { "type": "string" }, + "target": { "type": "string" } + }), + }, + + // ─── Execution Tools ────────────────────────────────────── + Tool { + name: "execute_workflow", + description: "Execute provisioning workflow", + input_schema: json!({ + "workflow_id": { "type": "string" }, + "dry_run": { "type": "boolean", "default": true } + }), + }, +]; +``` + +--- + +## 5. SecretumVault: Complete Specifications + +### Architecture (~11K LOC, 50+ tests) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (clap) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Core Types + +```rust +// src/core/vault.rs +pub struct VaultCore { + pub engines: HashMap<String, Box<dyn Engine>>, + pub storage: Arc<dyn StorageBackend>, + pub crypto: Arc<dyn CryptoBackend>, + pub seal: Arc<tokio::sync::Mutex<SealMechanism>>, + pub token_manager: Arc<TokenManager>, + pub metrics: Arc<Metrics>, +} + +// src/crypto/mod.rs +#[async_trait] +pub trait CryptoBackend: Send + Sync { + async fn generate_keypair(&self, algorithm: KeyAlgorithm) -> CryptoResult<KeyPair>; + async fn sign(&self, key: &PrivateKey, data: &[u8]) -> CryptoResult<Vec<u8>>; + async fn verify(&self, key: &PublicKey, data: &[u8], sig: &[u8]) -> CryptoResult<bool>; + async fn encrypt(&self, plaintext: &[u8]) -> CryptoResult<Vec<u8>>; + async fn decrypt(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; + + // Post-Quantum (OQS backend) + async fn kem_encapsulate(&self, public_key: &[u8]) -> CryptoResult<KemResult>; + async fn kem_decapsulate(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; +} + +// src/storage/mod.rs +#[async_trait] +pub trait StorageBackend: Send + Sync { + async fn store_secret(&self, path: &str, data: &EncryptedData) -> StorageResult<()>; + async fn get_secret(&self, path: &str) -> StorageResult<EncryptedData>; + async fn delete_secret(&self, path: &str) -> StorageResult<()>; + async fn list_secrets(&self, prefix: &str) -> StorageResult<Vec<String>>; +} +``` + +### Crypto Backends + +| Backend | Algorithms | Status | +| --------- | ------------ | -------- | +| **OpenSSL** | RSA-2048/4096, ECDSA (P-256/384/521), AES-256-GCM | βœ… Production | +| **OQS** | ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) | βœ… **Production (PQC)** | +| **AWS-LC** | RSA, ECDSA (experimental PQC) | ⚠️ Experimental | +| **RustCrypto** | AES-256-GCM, ChaCha20-Poly1305 | ⚠️ Testing | + +### Secrets Engines + +```rust +// src/engines/mod.rs +pub trait Engine: Send + Sync { + fn name(&self) -> &str; + fn engine_type(&self) -> &str; + async fn read(&self, path: &str) -> Result<Option<Value>>; + async fn write(&self, path: &str, data: &Value) -> Result<()>; + async fn delete(&self, path: &str) -> Result<()>; + async fn list(&self, prefix: &str) -> Result<Vec<String>>; +} + +// Available engines +pub struct KvEngine { /* Versioned secret storage */ } +pub struct TransitEngine { /* Encryption-as-a-service */ } +pub struct PkiEngine { /* X.509 certificates */ } +pub struct DatabaseEngine { /* Dynamic credentials */ } +``` + +### Seal Mechanism (Shamir Secret Sharing) + +```rust +// src/core/seal.rs +pub struct SealMechanism { + state: SealState, + shares: Vec<SecretShare>, + threshold: u8, + total_shares: u8, +} + +pub enum SealState { + Sealed, + Unsealing { collected: usize }, + Unsealed { master_key: Vec<u8> }, +} +``` + +### API Endpoints + +```rust +// src/api/routes.rs +Router::new() + // System + .route("/v1/sys/health", get(health_check)) + .route("/v1/sys/init", post(initialize_vault)) + .route("/v1/sys/seal", post(seal_vault)) + .route("/v1/sys/unseal", post(unseal_vault)) + .route("/v1/sys/mounts", get(list_mounts)) + + // Secrets (dynamic routing by engine) + .route("/v1/*path", get(read_secret) + .post(write_secret) + .delete(delete_secret)) + + // Metrics + .route("/metrics", get(prometheus_metrics)) +``` + +### CLI Commands + +```bash +# Server +svault server --config svault.toml + +# Operator +svault operator init --shares 5 --threshold 3 +svault operator unseal --share <share> +svault operator seal +svault operator status + +# Secrets +svault secret read secret/myapp +svault secret write secret/myapp key=value +svault secret delete secret/myapp +svault secret list secret/ +``` + +### Feature Flags + +```toml +# Cargo.toml features +[features] +default = ["openssl", "filesystem", "server", "pqc"] + +# Crypto backends +openssl = ["dep:openssl"] +aws-lc = ["dep:aws-lc-rs"] +pqc = ["dep:oqs"] + +# Storage backends +filesystem = [] +surrealdb-storage = ["dep:surrealdb"] +etcd-storage = ["dep:etcd-client"] +postgresql-storage = ["dep:sqlx"] + +# Components +server = ["dep:axum", "dep:rustls"] +cli = ["dep:clap"] +cedar = ["dep:cedar-policy"] +``` + +--- + +## 6. Cross-Project Integration + +### Shared SurrealDB Schema + +```sql +-- ─── Namespace ──────────────────────────────────────────────── +DEFINE NAMESPACE portfolio; + +-- ─── Databases ──────────────────────────────────────────────── +DEFINE DATABASE vapora; +DEFINE DATABASE kogral; +DEFINE DATABASE typedialog; +DEFINE DATABASE provisioning; +DEFINE DATABASE secretumvault; + +-- ─── Shared Tables ──────────────────────────────────────────── + +-- Execution records (cross-project) +DEFINE TABLE executions SCHEMAFULL; +DEFINE FIELD project ON executions TYPE string; +DEFINE FIELD source ON executions TYPE string; -- vapora, kogral, etc. +DEFINE FIELD task_type ON executions TYPE string; +DEFINE FIELD agent_id ON executions TYPE option<string>; +DEFINE FIELD status ON executions TYPE string; +DEFINE FIELD duration_ms ON executions TYPE int; +DEFINE FIELD metadata ON executions FLEXIBLE TYPE object; +DEFINE FIELD created_at ON executions TYPE datetime DEFAULT time::now(); + +DEFINE INDEX idx_executions_project ON executions FIELDS project; +DEFINE INDEX idx_executions_source ON executions FIELDS source; +DEFINE INDEX idx_executions_created ON executions FIELDS created_at; + +-- Knowledge references (Kogral β†’ others) +DEFINE TABLE knowledge_refs SCHEMAFULL; +DEFINE FIELD source_project ON knowledge_refs TYPE string; +DEFINE FIELD node_id ON knowledge_refs TYPE string; +DEFINE FIELD target_project ON knowledge_refs TYPE string; +DEFINE FIELD target_id ON knowledge_refs TYPE string; +DEFINE FIELD ref_type ON knowledge_refs TYPE string; -- guideline, pattern, decision +DEFINE FIELD created_at ON knowledge_refs TYPE datetime DEFAULT time::now(); + +-- Configuration snapshots (TypeDialog β†’ Provisioning) +DEFINE TABLE config_snapshots SCHEMAFULL; +DEFINE FIELD form_id ON config_snapshots TYPE string; +DEFINE FIELD config_hash ON config_snapshots TYPE string; +DEFINE FIELD output ON config_snapshots FLEXIBLE TYPE object; +DEFINE FIELD target ON config_snapshots TYPE string; -- provisioning workflow +DEFINE FIELD created_at ON config_snapshots TYPE datetime DEFAULT time::now(); +``` + +### Integration Patterns + +```rust +// Example: Kogral β†’ Vapora integration + +// Vapora agent queries Kogral for guidelines before generating code +async fn get_project_context(task: &Task) -> Result<ProjectContext> { + let kogral = KogralMcpClient::connect().await?; + + // Get applicable guidelines + let guidelines = kogral.call("get_guidelines", json!({ + "topic": &task.task_type, + "include_shared": true, + })).await?; + + // Get relevant patterns + let patterns = kogral.call("search", json!({ + "query": &task.description, + "node_type": "pattern", + "semantic": true, + "limit": 5, + })).await?; + + // Get related decisions + let decisions = kogral.call("search", json!({ + "query": &task.description, + "node_type": "decision", + "limit": 3, + })).await?; + + Ok(ProjectContext { guidelines, patterns, decisions }) +} + +// Example: TypeDialog β†’ Provisioning integration + +// TypeDialog prov-gen backend generates Nickel for Provisioning +async fn generate_infrastructure(form_response: &FormResponse) -> Result<WorkflowId> { + // Generate Nickel config from form + let generator = ProvGenBackend::new(); + let iac = generator.generate(&form_response.into()).await?; + + // Submit to Provisioning + let provisioning = ProvisioningClient::connect().await?; + let workflow_id = provisioning.submit_workflow(iac).await?; + + // Record in shared DB + let db = SurrealClient::connect().await?; + db.create("config_snapshots", ConfigSnapshot { + form_id: form_response.form_id.clone(), + config_hash: hash(&iac), + output: form_response.values.clone(), + target: workflow_id.clone(), + }).await?; + + Ok(workflow_id) +} + +// Example: Vapora β†’ Kogral integration + +// Record agent execution as Kogral Execution node +async fn record_execution(result: &TaskResult) -> Result<()> { + let kogral = KogralMcpClient::connect().await?; + + kogral.call("add_execution", json!({ + "task_id": &result.task_id, + "agent_role": &result.agent_role, + "status": &result.status, + "duration_ms": result.duration_ms, + "tokens_used": result.tokens_used, + "output_summary": &result.summary, + })).await?; + + Ok(()) +} +``` + +--- + +## 7. Metrics and Quality + +| Project | Crates | Tests | LOC | Clippy | Unsafe | Doc | +| ---------- | -------- | ------- | ----- | -------- | -------- | ----- | +| Vapora | 13 | 218 | ~50K | 0 warn | 0 | 100% pub | +| Kogral | 3 | 56 | ~15K | 0 warn | 0 | 100% pub | +| TypeDialog | 8 | 3,818 | ~90K | 0 warn | 0 | 100% pub | +| Provisioning | 15+ | 218 | ~40K | 0 warn | 0 | 100% pub | +| SecretumVault | 1 | 50+ | ~11K | 0 warn | 0 | 100% pub | +| **Total** | **40+** | **4,360+** | **~206K** | **0** | **0** | **100%** | + +### Verification Commands + +```bash +# All projects +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace +cargo doc --workspace --no-deps + +# Coverage +cargo tarpaulin --workspace --out Html + +# Security audit +cargo audit + +# Benchmarks +cargo bench --workspace +``` + +--- + +*Document generated: 2026-01-22* +*Type: info (complete technical specifications)* diff --git a/docs/en/stratiumiops_market.md b/docs/en/stratiumiops_market.md new file mode 100644 index 0000000..b83099c --- /dev/null +++ b/docs/en/stratiumiops_market.md @@ -0,0 +1,410 @@ +# Development Portfolio: The Complete Platform + +## The Challenge of Modern Development + +Development teams face growing fragmentation: + +- **10+ tools** to manage a typical project +- **Scattered knowledge** in wikis, Slack, docs, and people's heads +- **Manual configuration** repeated project after project +- **Complex infrastructure** without validation or rollback +- **Disconnected AI** from team conventions + +## The Solution: An Integrated Ecosystem + +Five projects designed to work together, each solving a specific domain. + +--- + +## Vapora: Your Development Hub + +### One Platform, Full Workflow + +Vapora unifies project management, team coordination, and AI agents in a single platform. + +**Project Management** + +- **Visual Kanban**: Intuitive drag-and-drop with customizable columns +- **Real-time collaboration**: Instant updates, no refresh needed +- **Clear hierarchy**: Workspaces β†’ Projects β†’ Tasks with isolation +- **Complete tracking**: Change history with context + +**Intelligent Orchestration** + +- **12 agent roles**: Architect, Developer, Reviewer, Tester, Documenter... +- **Continuous learning**: Agents improve with each execution +- **Automated pipelines**: Sequences with approval gates +- **Cost control**: Budgets per role with automatic fallback + +**Native Multi-Tenant** + +- **Isolation by design**: Each tenant in their scope +- **Fine-grained RBAC**: Declarative policies with Cedar +- **Audit trail**: Everything is logged + +**For whom**: + +- Development teams wanting to unify tools +- Organizations using AI agents needing visibility +- Multi-tenant platforms serving multiple teams + +--- + +## Kogral: Your Team's Memory + +### Knowledge That Doesn't Get Lost + +Kogral captures your team's decisions, patterns, and guidelines in a format that endures. + +**6 Knowledge Types** + +| Type | Purpose | +| ------ | --------- | +| **Notes** | Observations and general notes | +| **Decisions** | ADRs with context, decision and consequences | +| **Guidelines** | Team and organization standards | +| **Patterns** | Proven and documented solutions | +| **Journals** | Day-to-day development diary | +| **Executions** | AI agent execution records | + +**Git-Native** + +- Everything in versioned markdown +- No dependency on external SaaS +- Trivial backup and restore +- Code review of knowledge + +**Guideline Inheritance** + +```text +Organization defines base standards + ↓ +Project specializes for its context + ↓ +Developer sees effective guidelines +``` + +**Integration with Claude Code** + +- 7 native MCP tools +- Query guidelines before generating code +- Automatically search for relevant patterns +- Record decisions during development + +**For whom**: + +- Teams losing knowledge with turnover +- Organizations with multiple projects +- Developers using Claude Code +- Teams with compliance/audit requirements + +--- + +## TypeDialog: Your Universal Interface + +### One Definition, All Platforms + +TypeDialog lets you define forms once and execute them in CLI, TUI, Web, or with AI agents. + +**6 Execution Backends** + +| Backend | Typical Use | +| --------- | ------------ | +| **CLI** | Automation scripts, CI/CD | +| **TUI** | Admin tools | +| **Web** | SaaS applications, public forms | +| **AI** | Semantic search, RAG | +| **Agent** | LLM agent execution | +| **Prov-gen** | Infrastructure generation | + +**Type-Safe Validation** + +- Nickel contracts for pre-runtime validation +- Errors detected before execution +- Reusable schemas across projects + +**Advanced Forms** + +- 8 field types (text, select, multi-select, date, password...) +- Conditional and dynamic fields +- Repeatable groups +- Reusable fragments with inheritance +- Internationalization with Fluent + +**Agents from Markdown** + +Define agents in `.agent.mdx` files: +- 4 LLM providers (Claude, OpenAI, Gemini, Ollama) +- Templates with variables +- Output validation +- Real-time streaming + +**Infrastructure Generation** + +- 6 supported clouds (AWS, GCP, Azure, Hetzner, UpCloud, LXD) +- Forms β†’ Validated configuration β†’ Ready IaC +- 7 validation layers + +**For whom**: + +- Teams maintaining CLI and Web in parallel +- DevOps needing configuration wizards +- Organizations with multi-language requirements +- Teams wanting to automate with agents + +--- + +## Provisioning: Your Controlled Infrastructure + +### Declarative IaC + Enterprise Security + +Provisioning combines typed configuration, advanced orchestration, and complete security. + +**Nickel IaC** + +- Typed language with lazy evaluation +- Validation at compile time, not runtime +- Composable and reusable schemas +- Better than YAML/HCL for complex configuration + +**True Multi-Cloud** + +| Provider | Capabilities | +| ---------- | -------------- | +| **AWS** | EC2, EKS, RDS, S3, IAM, VPC | +| **UpCloud** | Servers, networking, storage | +| **Local** | LXD containers, VMs | + +**Advanced Orchestrator** + +- Automatic dependency resolution +- Checkpoints with recovery +- Automatic rollback on failures +- Parallel execution with balancing +- Retry with exponential backoff + +**Enterprise Security** + +| Component | Capability | +| ----------- | ----------- | +| **Authentication** | JWT + Argon2id + MFA (TOTP + WebAuthn) | +| **Authorization** | Cedar policies (fine-grained RBAC) | +| **Secrets** | Dynamic secrets with TTL | +| **KMS** | 5 backends (RustyVault, Age, AWS, Vault, Cosmian) | +| **Audit** | 7-year retention, 5 export formats | +| **Break-glass** | Multi-party approval | + +**39,699 lines of security code** across 12 components. + +**Integrated AI** + +- Native MCP Server (1000x faster than Python) +- RAG with 1,200+ domain documents +- Natural language queries +- Validated Nickel generation + +**Developer Experience** + +- 211-line CLI (84% reduction) +- 80+ shortcuts (`s` β†’ server, `t` β†’ taskserv) +- Integrated interactive guides +- Configuration system with 476+ accessors + +**For whom**: + +- DevOps teams wanting typed IaC +- Multi-cloud organizations +- Teams with compliance requirements +- Organizations needing complete audit + +--- + +## SecretumVault: Your Post-Quantum Vault + +### Future Cryptography, Today + +SecretumVault is the first Rust vault with production-ready post-quantum cryptography. + +**Cryptography Agnostic** + +| Backend | Algorithms | Status | +| --------- | ------------ | -------- | +| **OpenSSL** | RSA, ECDSA, AES-256-GCM | Production | +| **OQS** | ML-KEM-768, ML-DSA-65 | **Production (PQC)** | +| **AWS-LC** | RSA, ECDSA | Experimental | +| **RustCrypto** | AES-GCM, ChaCha20 | Testing | + +**Secrets Engines** + +- **KV Engine**: Versioned storage with metadata +- **Transit Engine**: Encryption-as-a-service with rotation +- **PKI Engine**: X.509 certificates and CA management +- **Database Engine**: Dynamic credentials with TTL + +**Multi-Backend Storage** + +| Backend | Use | +| --------- | ----- | +| **Filesystem** | Development, single-node | +| **etcd** | Kubernetes, high availability | +| **SurrealDB** | Complex queries, time-series | +| **PostgreSQL** | Enterprise, ACID | + +**Enterprise Security** + +- **Shamir Secret Sharing**: Distributed unsealing (K of N) +- **Cedar ABAC**: AWS-compatible policies +- **TLS/mTLS**: Transport encryption with client verification +- **Audit Logging**: All events logged + +**For whom**: + +- Teams preparing for quantum threats +- Organizations with cryptographic agility requirements +- Platforms needing Rust-native vault +- Multi-cloud teams with self-hosting + +--- + +## The Ecosystem in Action + +### Scenario 1: Feature Development + +```text +1. Kogral provides guidelines and patterns to the team +2. TypeDialog captures requirements with validated forms +3. SecretumVault manages credentials and API keys +4. Vapora coordinates agents (Architect β†’ Developer β†’ Reviewer) +5. Kogral records decisions made +6. Provisioning deploys necessary infrastructure changes +``` + +### Scenario 2: Team Onboarding + +```text +1. Kogral exports project knowledge graph +2. TypeDialog presents interactive quizzes +3. Vapora assigns progressive onboarding tasks +4. Provisioning configures development environments +``` + +### Scenario 3: Infrastructure Migration + +```text +1. Kogral documents migration ADRs +2. TypeDialog validates configuration parameters +3. Provisioning executes with checkpoints and rollback +4. Vapora orchestrates monitoring and reports +``` + +### Scenario 4: New Project + +```text +1. TypeDialog wizard for initial configuration +2. Provisioning generates infrastructure +3. Kogral creates initial knowledge graph +4. Vapora configures development pipelines +``` + +--- + +## Why This Ecosystem + +### Against Fragmentation + +| Problem | Typical Solution | Our Solution | +| --------- | ------------------ | -------------- | +| Project management | Jira + Notion + ... | Vapora (all-in-one) | +| Knowledge | Wiki + Docs + Slack | Kogral (git-native) | +| Configuration | Scripts + YAML | TypeDialog (type-safe) | +| Secrets | HashiCorp Vault / SaaS | SecretumVault (PQC) | +| Infrastructure | Terraform + Ansible | Provisioning (Nickel) | +| AI | Separate tools | Integrated everywhere | + +### Technical Advantages + +| Aspect | Us | Alternatives | +| -------- | ----- | -------------- | +| **Stack** | Rust end-to-end | Python/JS/Go mix | +| **Config** | Nickel (typed) | YAML/JSON (runtime errors) | +| **Multi-tenant** | SurrealDB scopes | DIY isolation | +| **AI** | Native in all | Retrofitted | +| **Self-hosted** | Complete | SaaS lock-in | + +### Confidence Metrics + +| Metric | Value | +| -------- | ------- | +| Rust Crates | 40+ | +| Tests | 4,360+ | +| Lines of code | ~206K | +| Security lines | 39K | +| LLM Providers | 4 | +| Supported clouds | 6 | +| Crypto backends | 4 (incl. PQC) | + +--- + +## Getting Started + +### Flexible Adoption + +Each project works independently: + +1. **Need only knowledge management?** β†’ Kogral +2. **Need only multi-backend forms?** β†’ TypeDialog +3. **Need only post-quantum vault?** β†’ SecretumVault +4. **Need only development orchestration?** β†’ Vapora +5. **Need only enterprise IaC?** β†’ Provisioning + +### Progressive Adoption + +For maximum benefit: + +```text +1. Kogral β†’ Establish knowledge base +2. TypeDialog β†’ Enable structured inputs +3. SecretumVault β†’ Secure secrets management +4. Vapora β†’ Orchestrate development +5. Provisioning β†’ Complete infrastructure +``` + +### Natural Integration + +Projects connect automatically: + +- Share SurrealDB for state +- Use Nickel for configuration +- Speak the same MCP protocol +- Share Axum/Leptos patterns + +--- + +## Technology Stack + +The entire ecosystem built on: + +| Technology | Purpose | +| ------------ | --------- | +| **Rust** | Performance, type-safety, zero-cost abstractions | +| **Nickel** | Configuration language with validation | +| **SurrealDB** | Multi-model database with scopes | +| **Axum** | Composable async web framework | +| **Leptos** | Reactive WASM frontend | +| **Ratatui** | Terminal UI | +| **NATS** | Messaging with JetStream | +| **rig-core** | Multi-provider LLM abstraction | +| **OQS** | Post-quantum cryptography (ML-KEM, ML-DSA) | + +--- + +## Contact + +- **Repositories**: GitHub (private projects) +- **License**: Proprietary / To be defined +- **Stack**: 100% Rust + +--- + +*One ecosystem. Five projects. Real integration.* +*Modern development without fragmentation.* diff --git a/docs/en/stratiumiops_position.md b/docs/en/stratiumiops_position.md new file mode 100644 index 0000000..e41cbd2 --- /dev/null +++ b/docs/en/stratiumiops_position.md @@ -0,0 +1,910 @@ +# Project Portfolio: Complete Strategic Positioning + +## Executive Summary + +Portfolio of five Rust projects forming a complete ecosystem for modern software development: + +| Project | Primary Domain | Key Capabilities | +| ---------- | ------------------- | ------------------- | +| **Vapora** | Development Platform | Orchestration, Kanban, multi-tenant, LLM routing, knowledge graph | +| **Kogral** | Knowledge Management | Knowledge graph, ADRs, patterns, guidelines, semantic search | +| **TypeDialog** | Interaction and Automation | Multi-backend forms, agents, IaC generation, i18n, validation | +| **Provisioning** | Infrastructure | Declarative IaC, multi-cloud, enterprise security, orchestration | +| **SecretumVault** | Security | Secrets management, post-quantum cryptography, multi-backend | + +--- + +## 1. Vapora: Intelligent Development Platform + +### Overview + +Vapora is a **development orchestration platform** that unifies project management, AI agent coordination, and complete development lifecycle visibility. + +### Complete Capabilities + +#### Project Management + +| Functionality | Description | +| --------------- | ------------- | +| **Kanban Board** | Drag-and-drop with Todo β†’ Doing β†’ Review β†’ Done columns | +| **Real-time Collaboration** | Optimistic updates, WebSocket sync | +| **Task Tracking** | Priorities, tags, assignments, sorting | +| **Project Hierarchy** | Workspaces β†’ Projects β†’ Tasks with isolated scopes | +| **Change Tracking** | Change history with impact analysis | + +#### Multi-Tenancy and Security + +| Functionality | Description | +| --------------- | ------------- | +| **SurrealDB Scopes** | Native tenant isolation | +| **Cedar RBAC** | Fine-grained declarative policies | +| **JWT Auth** | Tokens with refresh rotation | +| **Audit Trail** | Logging of significant changes | + +#### Agent Orchestration + +| Functionality | Description | +| --------------- | ------------- | +| **12 Roles** | Architect, Developer, Reviewer, Tester, Documenter, etc. | +| **Learning Profiles** | Expertise per task type with recency bias (3x last 7 days) | +| **Pipeline Execution** | Sequences with approval gates | +| **NATS JetStream** | Async coordination with guaranteed delivery | + +#### LLM Router + +| Functionality | Description | +| --------------- | ------------- | +| **4 Providers** | Claude, OpenAI, Gemini, Ollama | +| **Budget Control** | Limits per role (monthly/weekly) | +| **Auto-Fallback** | Switch to cheaper provider when exceeding budget | +| **Cost Tracking** | Tokens and costs per request/role/provider | + +#### Temporal Knowledge Graph + +| Functionality | Description | +| --------------- | ------------- | +| **Execution History** | Nodes with causal relationships | +| **Learning Curves** | Daily aggregations for improvement tracking | +| **Similarity Search** | Recommendations based on past tasks | + +#### Frontend (Leptos WASM) + +| Functionality | Description | +| --------------- | ------------- | +| **Glassmorphism UI** | Modern vaporwave aesthetic | +| **Responsive** | Mobile to ultra-wide | +| **Optimistic Updates** | Smooth UX without waiting for server | +| **UnoCSS** | Atomic CSS Tailwind-compatible | + +#### Observability + +| Functionality | Description | +| --------------- | ------------- | +| **Prometheus Metrics** | Request latency, agent duration, token usage | +| **OpenTelemetry** | Distributed tracing | +| **Structured Logging** | JSON output with tracing | + +### Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Vapora (13 crates, 218+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Frontend β”‚ β”‚ Backend β”‚ β”‚ Agent System β”‚ β”‚ +β”‚ β”‚ (Leptos) │──│ (Axum) │──│ (Coordinator + NATS) β”‚ β”‚ +β”‚ β”‚ Kanban UI β”‚ β”‚ 40+ APIs β”‚ β”‚ Learning + Pipelines β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LLM Router β”‚ β”‚ +β”‚ β”‚ Claude β”‚ OpenAI β”‚ Gemini β”‚ Ollama β”‚ Budget β”‚ Fallback β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Persistence: SurrealDB (scopes) + NATS JetStream β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Kogral: Knowledge Management System + +### Overview + +Kogral is a **git-native knowledge graph** designed to capture, connect and query development team knowledge. + +### Complete Capabilities + +#### Knowledge Model + +| Node Type | Purpose | +| -------------- | ----------- | +| **Note** | General notes, observations | +| **Decision (ADR)** | Architectural Decision Records with context/decision/consequences | +| **Guideline** | Team/organization standards | +| **Pattern** | Documented reusable solutions | +| **Journal** | Development diary (progress, blockers, learnings) | +| **Execution** | Agent execution records | + +| Relation Type | Purpose | +| ------------------ | ----------- | +| **relates_to** | General connection | +| **depends_on** | Dependency | +| **implements** | Concept implementation | +| **extends** | Extension/specialization | +| **supersedes** | Replaces previous version | +| **explains** | Documentation/explanation | + +#### Multi-Backend Storage + +| Backend | Characteristics | +| --------- | ----------------- | +| **Filesystem** | Git-friendly, markdown + YAML frontmatter, `.kogral/` | +| **SurrealDB** | Scalable, graph queries, org-wide shared knowledge | +| **Memory** | Testing with DashMap | + +#### Search + +| Capability | Description | +| ----------- | ------------- | +| **Text Search** | Full-text search over content | +| **Semantic Search** | Embeddings with fastembed (local) or cloud providers | +| **Graph Traversal** | Navigation through relationships | +| **Filtering** | By type, tags, date, metadata | + +#### Guideline Inheritance + +```text +Org Guidelines (base) + β”‚ + β–Ό override +Project Guidelines (specific) + β”‚ + β–Ό merge with priority +Effective Guidelines (applied) +``` + +#### Logseq Compatibility + +| Feature | Support | +| --------- | --------- | +| **Outliner Blocks** | Preserved hierarchical structure | +| **Task Statuses** | TODO, DOING, DONE, LATER, NOW, WAITING, CANCELLED | +| **Wikilinks** | Bidirectional `[[references]]` | +| **Properties** | Metadata in frontmatter | +| **Tags** | Preserved #tags | + +#### MCP Server (Claude Code) + +| Tool | Function | +| ------ | --------- | +| `search` | Text/semantic search | +| `add_note` | Create note | +| `add_decision` | Create guided ADR | +| `link` | Establish relationship | +| `get_guidelines` | Get applicable guidelines | +| `list_graphs` | List available graphs | +| `export` | Export to format | + +#### Export and Templates + +| Format | Support | +| --------- | --------- | +| **Markdown** | With YAML frontmatter | +| **JSON** | Complete structure | +| **YAML** | Human-readable | +| **Tera Templates** | Custom generation | + +### Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Kogral (3 crates, 56 tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ MCP Server β”‚ β”‚ Core Library β”‚ β”‚ +β”‚ β”‚ 13 cmds β”‚ β”‚ Claude Codeβ”‚ β”‚ Models + Storage + β”‚ β”‚ +β”‚ β”‚ clap β”‚ β”‚ 7 tools β”‚ β”‚ Query + Embeddings β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem (.kogral/) β”‚ SurrealDB β”‚ Memory (test) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Embeddings: fastembed (local) β”‚ rig-core (cloud) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 3. TypeDialog: Unified Interaction Platform + +### Overview + +TypeDialog is a **forms and automation system** that unifies multiple interfaces (CLI, TUI, Web) with agent execution and infrastructure generation. + +### Complete Capabilities + +#### Execution Backends + +| Backend | Technology | Typical Use | +| --------- | ------------ | ------------ | +| **CLI** | inquire | Scripts, CI/CD, automation | +| **TUI** | ratatui | Terminal dashboards, admin tools | +| **Web** | axum + HTMX | SaaS, public forms | +| **AI** | tantivy + petgraph | RAG, semantic search | +| **Agent** | Tera + Nickel | LLM execution from .agent.mdx | +| **Prov-gen** | Nickel + Templates | Multi-cloud IaC | + +#### Field Types + +| Type | Characteristics | +| ------ | ----------------- | +| **text** | Regex validation, length, patterns | +| **confirm** | Yes/No boolean | +| **select** | Single choice with filtering | +| **multi-select** | Multiple choice (list/grid/dropdown) | +| **password** | Masked input | +| **custom** | User-defined types | +| **editor** | Multi-line with external editor support | +| **date** | Date/time picker | + +#### Validation and Contracts + +| Capability | Description | +| ----------- | ------------- | +| **Regex Patterns** | Regular expression validation | +| **Length Constraints** | min/max length | +| **Cross-field Logic** | Inter-field validation | +| **Nickel Contracts** | Type-safe pre/post validation | +| **Custom Validators** | Custom validation functions | + +#### Advanced Forms + +| Feature | Description | +| --------- | ------------- | +| **Sections** | Logical field grouping | +| **Conditional Fields** | Dynamic visibility based on values | +| **Smart Defaults** | Computed default values | +| **Repeating Groups** | Dynamically repeatable fields | +| **Fragment Composition** | Reusable templates with inheritance | +| **Includes** | Fragment imports | + +#### Internationalization (i18n) + +| Capability | Description | +| ----------- | ------------- | +| **Fluent Bundles** | .ftl files for translations | +| **Auto-Locale** | Automatic detection via sys-locale | +| **Form Translation** | Translated labels, hints, errors | +| **Extraction** | Auto-extraction of strings from schemas | + +#### Output Formats + +| Format | Support | +| --------- | --------- | +| **JSON** | Standard, universal compatible | +| **YAML** | Human-readable | +| **TOML** | Rust-friendly configuration | +| **Nickel** | Type-safe with contracts | + +#### Agent System + +| Capability | Description | +| ----------- | ------------- | +| **MDX Format** | Extended markdown with YAML frontmatter | +| **4 LLM Providers** | Claude, OpenAI, Gemini, Ollama | +| **Tera Templates** | Variables, imports, shell commands | +| **Output Validation** | Format, content, length checks | +| **Streaming** | Real-time token streaming | + +#### IaC Generation (Prov-gen) + +| Capability | Description | +| ----------- | ------------- | +| **6 Cloud Providers** | AWS, GCP, Azure, Hetzner, UpCloud, LXD | +| **7-Layer Validation** | Complete validation pipeline | +| **AI-Assisted** | Optional configuration with Claude/Ollama | +| **Template Fragments** | Provider-specific fragments | + +#### Security + +| Capability | Description | +| ----------- | ------------- | +| **Field Encryption** | Field-level encryption | +| **Password Masking** | Across all backends | +| **Validation Contracts** | Invalid data prevention | + +### Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TypeDialog (8 crates, 3,818 tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ Form Definition (TOML) β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”‚ +β”‚ β”‚ BackendFactory β”‚β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β–Ό β–Ό β–Ό β”‚ β”‚ +β”‚ CLI TUI Web AI Agent Prov-gen β”‚ β”‚ +β”‚(inquire)(ratatui)(axum)(tantivy)(Tera)(Nickel) β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Output: JSON β”‚ YAML β”‚ TOML β”‚ Nickel β”‚ β”‚ +β”‚ β”‚ Validation: Nickel Contracts β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 4. Provisioning: Infrastructure Platform + +### Overview + +Provisioning is an **enterprise IaC platform** that combines declarative configuration (Nickel), advanced orchestration, complete security, and AI assistance. + +### Complete Capabilities + +#### Modular CLI + +| Aspect | Detail | +| --------- | --------- | +| **Size** | 211 lines (84% reduction from 1,329) | +| **Shortcuts** | 80+ shortcuts (`s` β†’ server, `t` β†’ taskserv) | +| **Modules** | 7 domains (infra, orchestration, dev, workspace, config, utils, gen) | +| **Guides** | Interactive with glow/bat/less | + +#### Configuration System + +| Capability | Description | +| ----------- | ------------- | +| **476+ Accessors** | Replacement for 200+ environment variables | +| **Hierarchical Loading** | defaults β†’ user β†’ project β†’ infra β†’ env β†’ runtime | +| **Interpolation** | Dynamically expanded variables | +| **Multi-format** | TOML, YAML, Nickel | + +#### Multi-Cloud Support + +| Provider | Capabilities | +| ---------- | ------------- | +| **AWS** | EC2, EKS, RDS, S3, IAM, VPC | +| **UpCloud** | Servers, networking, storage | +| **Local** | LXD containers, local VMs | + +#### Batch Workflows + +| Capability | Description | +| ----------- | ------------- | +| **Mixed Providers** | AWS + UpCloud + local in same workflow | +| **Schema Integration** | KCL/Nickel type-safe | +| **Dependency Resolution** | Automatic topological sorting | +| **State Management** | Checkpoints with recovery | +| **Rollback** | Automatic on failures | +| **Token Efficiency** | 85-90% | + +#### Hybrid Orchestrator + +| Capability | Description | +| ----------- | ------------- | +| **Rust + Nushell** | Combines performance and flexibility | +| **File Persistence** | State persisted to filesystem | +| **Priority Processing** | Priority queues | +| **Retry Logic** | Exponential backoff | +| **REST API** | External integration | +| **Parallel Execution** | Load balancing | + +#### Workspace Management + +| Capability | Description | +| ----------- | ------------- | +| **Single-command Switch** | Instant environment switching | +| **Tracking** | Last-used timestamps | +| **Registry** | Centralized registry | +| **Preferences** | Per-user configuration | + +#### Test Environment Service + +| Type | Description | +| ------ | ------------- | +| **Single Taskserv** | Individual service test | +| **Server Simulation** | Complete server simulation | +| **Multi-node Clusters** | Clusters with topologies (K8s HA, etcd) | + +#### Platform Installer + +| Mode | Resources | +| ------ | ---------- | +| **Solo** | 2 CPU, 4GB RAM | +| **MultiUser** | 4 CPU, 8GB RAM | +| **CICD** | 8 CPU, 16GB RAM | +| **Enterprise** | 16 CPU, 32GB RAM | + +| Interface | Description | +| ----------- | ------------- | +| **TUI** | Interactive Ratatui | +| **CLI** | Headless automation | +| **Unattended** | No interaction | + +#### Version Management + +| Capability | Description | +| ----------- | ------------- | +| **Centralized** | All versions in Nickel | +| **Bash-compatible** | Sourceable file generation | +| **Auto-discovery** | Provider version detection | +| **Shell Integration** | `source /provisioning/core/versions` | + +#### Nushell Plugins + +| Plugin | Function | Improvement | +| -------- | --------- | -------- | +| **auth** | Authentication | 10-50x vs HTTP | +| **KMS** | Key management | Native OS keyring | +| **orchestrator** | Workflow coordination | Performance | + +#### Complete Security System + +| Component | Capabilities | +| ------------ | ------------- | +| **Authentication** | JWT + Argon2id hashing | +| **MFA** | TOTP + WebAuthn/FIDO2 | +| **Authorization** | Cedar policy engine (fine-grained RBAC) | +| **Secrets** | Dynamic secrets with TTL | +| **KMS** | 5 backends (RustyVault, Age, AWS KMS, Vault, Cosmian) | +| **Encryption** | Envelope encryption | +| **Audit** | 7-year retention, 5 export formats | +| **Break-glass** | Multi-party approval | + +**Security Metrics**: 39,699 lines, 12 components + +#### AI Integration + +| Capability | Description | +| ----------- | ------------- | +| **MCP Server** | Rust-native (1000x vs Python) | +| **RAG System** | 1,200+ domain docs | +| **NLP** | Intent recognition, entity extraction | +| **Multi-provider** | OpenAI, Claude, Ollama | +| **Nickel Generation** | With automatic validation | + +### Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Provisioning (v5.0.0-nickel, 218+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ Control β”‚ β”‚ Platform β”‚ β”‚ +β”‚ β”‚ 211 lines β”‚ β”‚ Center β”‚ β”‚ Orchestrator β”‚ β”‚ +β”‚ β”‚ 80+ shorts β”‚ β”‚ (Axum) β”‚ β”‚ (Rust/Nu hybrid) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Extensions β”‚ β”‚ +β”‚ β”‚ Providers: AWS β”‚ UpCloud β”‚ Local β”‚ β”‚ +β”‚ β”‚ Taskservs: 50+ infrastructure services β”‚ β”‚ +β”‚ β”‚ Clusters: K8s, etcd, etc. templates β”‚ β”‚ +β”‚ β”‚ Workflows: Automation definitions β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Security Layer (39K lines, 12 components) β”‚ β”‚ +β”‚ β”‚ JWT β”‚ Cedar β”‚ MFA β”‚ KMS β”‚ Audit β”‚ Secrets β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ AI Layer: MCP Server β”‚ RAG (1200+ docs) β”‚ LLM Providers β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ State: SurrealDB β”‚ Filesystem β”‚ Nickel Schemas β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 5. SecretumVault: Post-Quantum Secrets Management + +### Overview + +SecretumVault is a **secrets management system** written in Rust with **production-ready post-quantum cryptography** (ML-KEM-768, ML-DSA-65 per NIST FIPS 203/204). + +### Complete Capabilities + +#### Cryptographic Backends + +| Backend | Algorithms | Status | +| --------- | ------------ | -------- | +| **OpenSSL** | RSA-2048/4096, ECDSA (P-256/384/521), AES-256-GCM | βœ… Production | +| **OQS** | ML-KEM-768, ML-DSA-65 | βœ… **Production (PQC)** | +| **AWS-LC** | RSA, ECDSA (experimental PQC) | ⚠️ Experimental | +| **RustCrypto** | AES-256-GCM, ChaCha20-Poly1305 | ⚠️ Testing | + +#### Secrets Engines + +| Engine | Functionality | +| ------- | --------------- | +| **KV Engine** | Versioned secret storage | +| **Transit Engine** | Encryption-as-a-service with key rotation | +| **PKI Engine** | X.509 certificate generation, CA management | +| **Database Engine** | Dynamic credentials with TTL | + +#### Storage Backends + +| Backend | Typical Use | +| --------- | ------------ | +| **Filesystem** | Development, single-node | +| **etcd** | Kubernetes, high availability | +| **SurrealDB** | Complex queries, time-series | +| **PostgreSQL** | Enterprise, guaranteed ACID | + +#### Enterprise Security + +| Component | Capabilities | +| ------------ | ------------- | +| **Seal/Unseal** | Shamir Secret Sharing (K of N threshold) | +| **Authentication** | Token-based with configurable TTL | +| **Authorization** | Cedar ABAC (AWS-compatible policies) | +| **TLS/mTLS** | In-transit encryption + client verification | +| **Audit** | Structured logging of all events | + +### Architecture + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault (~11K LOC, 50+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (clap) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 6. Complete Functionality Matrix + +### Capabilities by Category + +#### Project Management + +| Capability | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Kanban Board | βœ… Leptos | - | - | - | - | +| Task Management | βœ… Full | - | - | - | - | +| Project Hierarchy | βœ… Scopes | βœ… Graphs | - | βœ… Workspaces | - | +| Real-time Collab | βœ… WebSocket | - | - | - | - | +| Change Tracking | βœ… History | βœ… Git | - | βœ… Audit | βœ… Audit | + +#### Knowledge and Documentation + +| Capability | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Knowledge Graph | βœ… Temporal | βœ… 6 types | - | - | - | +| ADRs | - | βœ… Native | - | - | - | +| Patterns Library | - | βœ… Native | - | - | - | +| Guidelines | - | βœ… Inheritance | - | βœ… Schemas | - | +| Semantic Search | βœ… KG | βœ… fastembed | βœ… Tantivy | βœ… RAG | - | + +#### User Interaction + +| Capability | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Web UI | βœ… Leptos | - | βœ… Axum | βœ… Leptos | - | +| CLI | - | βœ… 13 cmds | βœ… inquire | βœ… 80+ shorts | βœ… svault | +| TUI | - | - | βœ… ratatui | βœ… ratatui | - | +| Forms | - | - | βœ… 8 types | - | - | +| i18n | - | - | βœ… Fluent | - | - | + +#### Automation + +| Capability | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Pipelines | βœ… Agent | - | βœ… Agent MDX | βœ… Workflows | - | +| LLM Agents | βœ… 12 roles | - | βœ… Multi-prov | βœ… MCP | - | +| IaC Generation | - | - | βœ… 6 clouds | βœ… Nickel | - | +| CI/CD | - | - | βœ… Backend | βœ… Full | - | +| Orchestration | βœ… NATS | - | - | βœ… Hybrid | - | + +#### Infrastructure + +| Capability | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Multi-cloud | - | - | βœ… Prov-gen | βœ… AWS/UpCloud/Local | - | +| Kubernetes | βœ… Deploy | - | - | βœ… Full | βœ… etcd backend | +| Secrets Mgmt | - | - | βœ… Encrypt | βœ… 5 KMS | βœ… **4 engines** | +| Networking | - | - | - | βœ… VPC/Subnet | - | +| State Mgmt | - | - | - | βœ… Checkpoints | βœ… 4 backends | + +#### Security + +| Capability | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Authentication | βœ… JWT | - | - | βœ… JWT+MFA | βœ… Token-based | +| Authorization | βœ… Cedar | - | - | βœ… Cedar | βœ… Cedar ABAC | +| Multi-tenant | βœ… Scopes | - | - | βœ… Full | - | +| Audit | βœ… Logging | - | - | βœ… 7 years | βœ… Full audit | +| Encryption | - | - | βœ… Field | βœ… Envelope | βœ… **PQC native** | +| Post-Quantum | - | - | - | - | βœ… ML-KEM/ML-DSA | + +#### Observability + +| Capability | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Metrics | βœ… Prometheus | - | - | βœ… Full | βœ… Prometheus | +| Logging | βœ… tracing | βœ… tracing | - | βœ… tracing | βœ… tracing | +| Tracing | βœ… OTEL | - | - | βœ… OTEL | - | +| Dashboards | βœ… Grafana | - | - | βœ… Control Center | - | + +--- + +## 7. Technology Stack + +### Shared Dependencies + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ COMMON TECHNOLOGY STACK β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ LANGUAGE β”‚ +β”‚ └── Rust 2021/2024 edition (type-safe, zero-cost) β”‚ +β”‚ β”‚ +β”‚ CONFIGURATION β”‚ +β”‚ └── Nickel 1.15+ (typed schemas, lazy eval, validation) β”‚ +β”‚ β”‚ +β”‚ DATABASE β”‚ +β”‚ └── SurrealDB 2.3+ (multi-model, graph, scopes) β”‚ +β”‚ β”‚ +β”‚ WEB FRAMEWORK β”‚ +β”‚ └── Axum 0.8+ (async, composable, tower middleware) β”‚ +β”‚ β”‚ +β”‚ FRONTEND β”‚ +β”‚ └── Leptos 0.8+ (WASM, reactive, CSR) β”‚ +β”‚ β”‚ +β”‚ TUI β”‚ +β”‚ └── Ratatui 0.30+ (terminal UI, crossterm) β”‚ +β”‚ β”‚ +β”‚ CLI β”‚ +β”‚ └── clap 4+ (derive API, completions) β”‚ +β”‚ β”‚ +β”‚ LLM β”‚ +β”‚ └── rig-core 0.15+ (multi-provider, tools, streaming) β”‚ +β”‚ β”‚ +β”‚ MESSAGING β”‚ +β”‚ └── async-nats 0.45+ (JetStream, guaranteed delivery) β”‚ +β”‚ β”‚ +β”‚ SERIALIZATION β”‚ +β”‚ └── serde 1.0 (JSON, YAML, TOML) β”‚ +β”‚ β”‚ +β”‚ ASYNC β”‚ +β”‚ └── Tokio 1.48+ (runtime, spawn, timeouts) β”‚ +β”‚ β”‚ +β”‚ LOGGING β”‚ +β”‚ └── tracing 0.1 (structured, JSON, env-filter) β”‚ +β”‚ β”‚ +β”‚ ERRORS β”‚ +β”‚ └── anyhow + thiserror (ergonomic error handling) β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 8. Positioning vs Competition + +### By Domain + +#### Development Platforms (Vapora) + +| Aspect | Vapora | Jira | Linear | Notion | +| --------- | -------- | ------ | -------- | -------- | +| **Self-hosted** | βœ… | ❌ | ❌ | ❌ | +| **Multi-tenant** | βœ… Native | ❌ | ❌ | Partial | +| **Agent Orchestration** | βœ… Learning | ❌ | ❌ | ❌ | +| **LLM Integration** | βœ… 4 providers | AI features | ❌ | AI features | +| **Real-time** | βœ… WebSocket | βœ… | βœ… | βœ… | +| **Customizable** | βœ… Full | Limited | Limited | βœ… | + +#### Knowledge Management (Kogral) + +| Aspect | Kogral | Obsidian | Notion | Confluence | +| --------- | -------- | ---------- | -------- | ------------ | +| **Git-native** | βœ… | Plugins | ❌ | ❌ | +| **Developer-focused** | βœ… ADRs/Patterns | General | General | General | +| **MCP Integration** | βœ… Native | ❌ | ❌ | ❌ | +| **Semantic Search** | βœ… Local+Cloud | Plugins | Internal | Internal | +| **Guideline Inheritance** | βœ… | ❌ | ❌ | ❌ | +| **Offline** | βœ… | βœ… | ❌ | ❌ | + +#### Forms and Automation (TypeDialog) + +| Aspect | TypeDialog | Typeform | SurveyJS | Inquirer | +| --------- | ------------ | ---------- | ---------- | ---------- | +| **Multi-backend** | βœ… 6 | Web only | Web only | CLI only | +| **Type-safe** | βœ… Nickel | ❌ | Partial | ❌ | +| **Agent Execution** | βœ… Native | ❌ | ❌ | ❌ | +| **IaC Generation** | βœ… 6 clouds | ❌ | ❌ | ❌ | +| **i18n** | βœ… Fluent | βœ… | βœ… | ❌ | +| **Self-hosted** | βœ… | ❌ | βœ… | βœ… | + +#### IaC (Provisioning) + +| Aspect | Provisioning | Terraform | Pulumi | Ansible | +| --------- | -------------- | ----------- | -------- | --------- | +| **Language** | Nickel (typed) | HCL | TS/Py | YAML | +| **AI-native** | βœ… MCP+RAG | ❌ | ❌ | ❌ | +| **Security** | βœ… 39K lines | Basic | Basic | Vault plugin | +| **Orchestration** | βœ… Hybrid | State file | State | Playbooks | +| **Multi-cloud** | βœ… | βœ… | βœ… | βœ… | +| **DX** | βœ… 80+ shortcuts | Verbose | Standard | Standard | + +#### Secrets Management (SecretumVault) + +| Aspect | SecretumVault | HashiCorp Vault | AWS Secrets Manager | Azure Key Vault | +| --------- | --------------- | ----------------- | --------------------- | ----------------- | +| **Language** | Rust (memory-safe) | Go | SaaS | SaaS | +| **Post-Quantum** | βœ… ML-KEM/ML-DSA | ❌ | ❌ | ❌ | +| **Self-hosted** | βœ… Complete | βœ… | ❌ | ❌ | +| **Crypto backends** | 4 pluggable | 1 fixed | 1 fixed | 1 fixed | +| **Storage backends** | 4 (FS/etcd/Surreal/PG) | Multiple | Proprietary | Proprietary | +| **Authorization** | Cedar ABAC | ACL | IAM | RBAC | +| **Shamir unsealing** | βœ… Native | βœ… | ❌ | ❌ | +| **License** | Apache-2.0 | BSL/Enterprise | Proprietary | Proprietary | + +--- + +## 9. Integration Between Projects + +### Data Flow + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Knowledge) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + Guidelines, Patterns, ADRs, Decisions + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Vapora │◄───────▢│TypeDialog │◄───────▢│Provisioning β”‚ +β”‚(Development)β”‚ β”‚ (Forms) β”‚ β”‚ (IaC) β”‚ +β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ β”‚ β”‚ + β”‚ β–Ό β–Ό β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + └──▢│ SecretumVault β”‚β—„β”€β”€β”€β”˜ + β”‚ (Secrets + PQC Crypto) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ FINAL PRODUCT β”‚ +β”‚ Software developed, documented, configured, deployed β”‚ +β”‚ with protected secrets (PQC) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Specific Synergies + +| Integration | Benefit | +| ------------- | ----------- | +| Kogral β†’ Vapora | Agents query guidelines before generating code | +| Kogral β†’ TypeDialog | Forms for structured ADR capture | +| Kogral β†’ Provisioning | Automatic infrastructure ADRs | +| Vapora β†’ TypeDialog | Forms as input for pipelines | +| Vapora β†’ Provisioning | Deployment orchestration | +| TypeDialog β†’ Provisioning | prov-gen backend generates IaC from forms | + +### Reusable Components + +| Component | Origin | Used In | +| ------------ | -------- | ---------- | +| SurrealDB patterns | Vapora | Kogral, Provisioning | +| Nickel schemas | Provisioning | TypeDialog, Kogral | +| rig-core abstraction | Vapora | All | +| Axum patterns | Vapora | TypeDialog, Provisioning | +| tracing setup | Vapora | All | +| Cedar policies | Provisioning | Vapora | +| Leptos components | Vapora | Provisioning | + +--- + +## 10. Portfolio Metrics + +| Metric | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | **Total** | +| --------- | -------- | -------- | ------------ | -------------- | --------------- | ----------- | +| **Crates** | 13 | 3 | 8 | 15+ | 1 | **40+** | +| **Tests** | 218 | 56 | 3,818 | 218 | 50+ | **4,360+** | +| **LOC (approx)** | ~50K | ~15K | ~90K | ~40K | ~11K | **~206K** | +| **Backends** | 1 (Leptos) | 3 | 6 | 3 | 4 storage | **17** | +| **LLM Providers** | 4 | 4 | 4 | 3 | - | **4 unique** | +| **MCP Tools** | Gateway | 7 | - | 7 | - | **14+** | +| **Crypto backends** | - | - | - | 5 KMS | 4 | **4 unique** | + +--- + +## 11. Recommended Adoption Order + +### Optimal Sequence + +```text +Phase 1: Kogral + β”‚ Establishes knowledge base + β”‚ Guidelines, patterns, ADRs + β–Ό +Phase 2: TypeDialog + β”‚ Enables structured inputs + β”‚ Validation with Nickel contracts + β–Ό +Phase 3: SecretumVault + β”‚ Secure secrets management + β”‚ PQC cryptographic preparation + β–Ό +Phase 4: Vapora + β”‚ Orchestrates development with agents + β”‚ Leverages knowledge graph + β–Ό +Phase 5: Provisioning + β”‚ Infrastructure informed + β”‚ by all previous context +``` + +### Independent Adoption + +Each project works standalone: + +- **Kogral**: Knowledge management without external dependencies +- **TypeDialog**: Forms and agents without other projects +- **SecretumVault**: Rust-native secrets management +- **Vapora**: Complete development and orchestration +- **Provisioning**: Independent enterprise IaC + +Synergies emerge with combined adoption, but are not required. + +--- + +*Document generated: 2026-01-22* +*Type: info (complete strategic positioning)* diff --git a/docs/es/README.md b/docs/es/README.md new file mode 100644 index 0000000..2e04001 --- /dev/null +++ b/docs/es/README.md @@ -0,0 +1,40 @@ +<div align="center"> + <img src="../../assets/stratumiops-h.svg" alt="StratumIOps Logo" width="500" /> +</div> + +# DocumentaciΓ³n STRATUMIOPS + +DocumentaciΓ³n completa del ecosistema STRATUMIOPS en espaΓ±ol. + +## Documentos de VisiΓ³n General + +- [**stratiumiops_market.md**](stratiumiops_market.md) - VisiΓ³n general de la plataforma y posicionamiento de mercado +- [**stratiumiops_position.md**](stratiumiops_position.md) - Posicionamiento estratΓ©gico y anΓ‘lisis competitivo +- [**stratiumiops-technical-specs.md**](stratiumiops-technical-specs.md) - Especificaciones tΓ©cnicas completas + +## CategorΓ­as de Portfolio + +### Portfolio IA + +Herramientas de desarrollo potenciadas por IA y automatizaciΓ³n inteligente. + +- [**Proyectos IA - VisiΓ³n General**](ia/ia-stratumiops-projects.md) - Vapora, Kogral, TypeDialog +- [**Posicionamiento IA**](ia/ia-stratumiops-projects-positioning.md) - Estrategia de mercado y diferenciaciΓ³n +- [**Especificaciones TΓ©cnicas IA**](ia/ia-stratumiops-projects-technical-specs.md) - API, arquitectura y detalles de implementaciΓ³n + +Ver directorio [ia/](ia/) para documentaciΓ³n completa del portfolio IA. + +### Portfolio Operaciones + +Herramientas de automatizaciΓ³n de infraestructura y despliegue. + +- [**Proyectos Ops - VisiΓ³n General**](ops/ops-stratumiops-projects.md) - Provisioning, SecretumVault +- [**Posicionamiento Ops**](ops/ops-stratumiops-projects-positioning.md) - Estrategia de mercado y diferenciaciΓ³n +- [**Especificaciones TΓ©cnicas Ops**](ops/ops-stratumiops-projects-technical-specs.md) - API, arquitectura y detalles de implementaciΓ³n + +Ver directorio [ops/](ops/) para documentaciΓ³n completa del portfolio de operaciones. + +## NavegaciΓ³n + +- [Volver a documentaciΓ³n raΓ­z](../) +- [English version](../en/) diff --git a/docs/es/ia/README.md b/docs/es/ia/README.md new file mode 100644 index 0000000..9d71e29 --- /dev/null +++ b/docs/es/ia/README.md @@ -0,0 +1,44 @@ +# DocumentaciΓ³n Portfolio IA + +DocumentaciΓ³n de las herramientas de desarrollo potenciadas por IA de STRATUM. + +## Proyectos + +### Vapora + +Hub de desarrollo con gestiΓ³n de proyectos y agentes IA. + +- GestiΓ³n de proyectos con Kanban visual +- Agentes IA entrenados en convenciones del equipo +- ColaboraciΓ³n en tiempo real +- Base de conocimiento integrada + +### Kogral + +Grafo de conocimiento y documentaciΓ³n inteligente. + +- AgregaciΓ³n de conocimiento multi-fuente +- BΓΊsqueda y recomendaciones con IA +- IntegraciΓ³n con control de versiones +- GeneraciΓ³n automatizada de documentaciΓ³n + +### TypeDialog + +GestiΓ³n de configuraciΓ³n y orquestaciΓ³n CI/CD. + +- ConfiguraciΓ³n con tipos seguros (Nickel) +- GeneraciΓ³n multi-backend de CI/CD +- IntegraciΓ³n con pre-commit +- Escaneo de seguridad y quality gates + +## Archivos de DocumentaciΓ³n + +- [**ia-stratumiops-projects.md**](ia-stratumiops-projects.md) - VisiΓ³n general completa de proyectos del portfolio IA +- [**ia-stratumiops-projects-positioning.md**](ia-stratumiops-projects-positioning.md) - Posicionamiento de mercado y anΓ‘lisis competitivo +- [**ia-stratumiops-projects-technical-specs.md**](ia-stratumiops-projects-technical-specs.md) - Especificaciones tΓ©cnicas, documentaciΓ³n de API y arquitectura + +## NavegaciΓ³n + +- [Volver a docs en espaΓ±ol](../) +- [Volver a documentaciΓ³n raΓ­z](../../) +- [Portfolio operaciones](../ops/) diff --git a/docs/es/ia/ia-stratumiops-projects-positioning.md b/docs/es/ia/ia-stratumiops-projects-positioning.md new file mode 100644 index 0000000..7af1d47 --- /dev/null +++ b/docs/es/ia/ia-stratumiops-projects-positioning.md @@ -0,0 +1,450 @@ +# Portfolio de Proyectos IA: Posicionamiento EstratΓ©gico + +## Resumen Ejecutivo + +Este documento analiza el portfolio de cinco proyectos complementarios que conforman un ecosistema completo para desarrollo asistido por IA: + +| Proyecto | Dominio | PropΓ³sito Central | +| ---------- | --------- | ------------------- | +| **Vapora** | OrquestaciΓ³n | CoordinaciΓ³n de agentes IA con aprendizaje y routing LLM | +| **Kogral** | Conocimiento | Grafo de conocimiento git-native para equipos de desarrollo | +| **TypeDialog** | InteracciΓ³n | Sistema de formularios multi-backend con ejecuciΓ³n de agentes | +| **Provisioning** | Infraestructura | IaC declarativo con generaciΓ³n asistida por IA | +| **SecretumVault** | Seguridad | GestiΓ³n de secretos con criptografΓ­a post-cuΓ‘ntica | + +--- + +## 1. Matriz de Funcionalidades + +### Capacidades por Proyecto + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| **Multi-proveedor LLM** | Claude, OpenAI, Gemini, Ollama | rig-core + fastembed | Claude, OpenAI, Gemini, Ollama | OpenAI, Claude, Ollama | - | +| **MCP Server** | Gateway para plugins | 7 tools, 6 resources | - | 7 tools IA-powered | - | +| **RAG/BΓΊsqueda semΓ‘ntica** | Knowledge Graph temporal | fastembed + SurrealDB | Tantivy + petgraph | Rig + SurrealDB | - | +| **Persistencia** | SurrealDB multi-tenant | Filesystem + SurrealDB | Multi-formato | SurrealDB + estado | FS/etcd/SurrealDB/PostgreSQL | +| **Frontend** | Leptos WASM (Kanban) | CLI + MCP | CLI/TUI/Web (6 backends) | CLI/TUI/Web | CLI + API REST | +| **API REST** | Axum (40+ endpoints) | - | Axum (Web backend) | Axum (control-center) | Axum (vault API) | +| **ConfiguraciΓ³n tipada** | TOML | Nickel schemas | Nickel contracts | Nickel IaC | TOML | +| **Crypto backends** | - | - | - | 5 KMS | OpenSSL/OQS/AWS-LC | +| **Post-Quantum** | - | - | - | - | ML-KEM-768, ML-DSA-65 | +| **Tests** | 218+ | 56 | 3,818 | 218+ | 50+ | + +### Stack TecnolΓ³gico ComΓΊn + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TECNOLOGÍAS COMPARTIDAS β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Lenguaje: Rust (editions 2021/2024) β”‚ +β”‚ Config: Nickel (schemas tipados, validaciΓ³n pre-runtime) β”‚ +β”‚ DB: SurrealDB (multi-modelo, grafos, scopes) β”‚ +β”‚ Web: Axum (async, composable routing) β”‚ +β”‚ LLM: rig-core (abstracciΓ³n multi-proveedor) β”‚ +β”‚ SerializaciΓ³n: serde (JSON, YAML, TOML) β”‚ +β”‚ Async: Tokio (runtime, spawn, timeouts) β”‚ +β”‚ Logging: tracing (structured, JSON output) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Posicionamiento vs Competencia + +### Vapora vs Alternativas + +| Aspecto | Vapora | LangChain/LangGraph | CrewAI | AutoGPT | +| --------- | -------- | --------------------- | -------- | --------- | +| **Lenguaje** | Rust (rendimiento) | Python | Python | Python | +| **Aprendizaje** | Perfiles por ejecuciΓ³n con recency bias | Chains estΓ‘ticos | Role-based | Prompts fijos | +| **Costos** | Budget enforcement per-role, fallback automΓ‘tico | Manual | Manual | Sin control | +| **Routing LLM** | DinΓ‘mico (calidad/costo/latencia) | Fijo | Fijo | Fijo | +| **Persistencia** | SurrealDB nativo | Vectorstores externos | Memoria | Archivos | +| **Frontend** | Kanban integrado (Leptos) | Sin UI nativa | Sin UI nativa | WebUI bΓ‘sica | +| **Multi-tenant** | Scopes + Cedar RBAC | No nativo | No | No | + +**Diferenciador clave**: Vapora aprende de ejecuciones pasadas (3x peso ΓΊltimos 7 dΓ­as) y optimiza costos automΓ‘ticamente con fallback a proveedores mΓ‘s baratos. + +### Kogral vs Alternativas + +| Aspecto | Kogral | Obsidian | Notion | Logseq | Mem.ai | +| --------- | -------- | ---------- | -------- | -------- | -------- | +| **Target** | Equipos desarrollo | Personal | Equipos generales | Personal | Personal | +| **Git-native** | Markdown + YAML frontmatter | Plugins | No | Local-first | Cloud | +| **Tipos nodo** | 6 especializados (ADR, Pattern, etc) | Notas genΓ©ricas | Bases datos | Bloques | Notas | +| **MCP Server** | Nativo (Claude Code) | No | No | No | No | +| **Embeddings** | fastembed local + cloud | Plugins | Interno | No | Interno | +| **Herencia guidelines** | Org β†’ Proyecto con prioridad | No | No | No | No | + +**Diferenciador clave**: Kogral estΓ‘ diseΓ±ado especΓ­ficamente para conocimiento de desarrollo (ADRs, patterns, guidelines) con integraciΓ³n nativa Claude Code via MCP. + +### TypeDialog vs Alternativas + +| Aspecto | TypeDialog | Inquirer.js | Warp Forms | Typeform | SurveyJS | +| --------- | ------------ | ------------- | ------------ | ---------- | ---------- | +| **Backends** | 6 (CLI/TUI/Web/AI/Agent/Prov) | CLI only | CLI only | Web only | Web only | +| **Agentes LLM** | .agent.mdx nativo | No | No | No | No | +| **IaC Gen** | Multi-cloud integrado | No | No | No | No | +| **Type-safety** | Nickel contracts | No | No | No | Parcial | +| **Idioma** | Rust | JavaScript | Rust | SaaS | JavaScript | + +**Diferenciador clave**: TypeDialog es el ΓΊnico que unifica formularios interactivos con ejecuciΓ³n de agentes LLM y generaciΓ³n de infraestructura. + +### Provisioning vs Alternativas + +| Aspecto | Provisioning | Terraform | Pulumi | CDK | Ansible | +| --------- | -------------- | ----------- | -------- | ----- | --------- | +| **Lenguaje IaC** | Nickel (tipado, lazy) | HCL | TypeScript/Python | TypeScript | YAML | +| **IA nativa** | MCP + RAG (1000x vs Python) | No | No | No | No | +| **Multi-cloud** | AWS, UpCloud, Local | SΓ­ | SΓ­ | AWS-centric | SΓ­ | +| **Seguridad** | 39K lΓ­neas (12 componentes) | BΓ‘sica | BΓ‘sica | IAM | Vault plugin | +| **CLI** | 80+ shortcuts, guΓ­as interactivas | Verboso | EstΓ‘ndar | EstΓ‘ndar | Playbooks | +| **Orchestrator** | Rust hΓ­brido (retry, rollback) | State file | State | CloudFormation | No nativo | + +**Diferenciador clave**: Provisioning combina IaC declarativo (Nickel) con generaciΓ³n asistida por IA y seguridad enterprise-grade. + +### SecretumVault vs Alternativas + +| Aspecto | SecretumVault | HashiCorp Vault | AWS Secrets Manager | Azure Key Vault | +| --------- | --------------- | ----------------- | --------------------- | ----------------- | +| **Lenguaje** | Rust (memory-safe) | Go | SaaS | SaaS | +| **Post-Quantum** | βœ… ML-KEM-768, ML-DSA-65 | ❌ | ❌ | ❌ | +| **Self-hosted** | βœ… Completo | βœ… | ❌ | ❌ | +| **Backends crypto** | 4 (OpenSSL, OQS, AWS-LC, RustCrypto) | 1 | 1 | 1 | +| **Storage backends** | 4 (FS, etcd, SurrealDB, PostgreSQL) | MΓΊltiples | Propietario | Propietario | +| **AutorizaciΓ³n** | Cedar ABAC | ACL policies | IAM | RBAC | +| **Shamir unsealing** | βœ… Nativo | βœ… | ❌ | ❌ | +| **Licencia** | Apache-2.0 | BSL/Enterprise | Propietario | Propietario | + +**Diferenciador clave**: SecretumVault es el ΓΊnico vault Rust con criptografΓ­a post-cuΓ‘ntica lista para producciΓ³n (ML-KEM-768, ML-DSA-65 NIST FIPS 203/204). + +--- + +## 3. Casos de Uso y Contexto + +### CuΓ‘ndo Usar Cada Proyecto + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ "Necesito coordinar mΓΊltiples agentes IA para un proyecto" β”‚ +β”‚ β†’ Vapora (orquestaciΓ³n, learning, budget control) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Quiero capturar decisiones arquitectΓ³nicas y patterns" β”‚ +β”‚ β†’ Kogral (ADRs, knowledge graph, MCP para Claude Code) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Necesito formularios que funcionen en CLI, TUI y Web" β”‚ +β”‚ β†’ TypeDialog (multi-backend, agentes .mdx) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Quiero provisionar infraestructura multi-cloud con IA" β”‚ +β”‚ β†’ Provisioning (Nickel IaC, RAG, MCP) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Necesito gestiΓ³n de secretos con criptografΓ­a post-cuΓ‘ntica" β”‚ +β”‚ β†’ SecretumVault (PQC, multi-backend, Shamir unsealing) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Matriz de DecisiΓ³n por Contexto + +| Contexto | Proyecto Principal | Proyectos de Soporte | +| ---------- | ------------------- | --------------------- | +| **Desarrollo de features con IA** | Vapora | Kogral (contexto), TypeDialog (inputs), SecretumVault (credenciales) | +| **Onboarding de equipo** | Kogral | TypeDialog (formularios interactivos) | +| **Setup de infraestructura** | Provisioning | TypeDialog (wizards), Kogral (decisiones), SecretumVault (secretos) | +| **Code review automatizado** | Vapora | Kogral (guidelines), TypeDialog (reports) | +| **DocumentaciΓ³n tΓ©cnica** | Kogral | Vapora (agentes doc), TypeDialog (exports) | +| **CI/CD con validaciΓ³n IA** | Provisioning | Vapora (agentes), TypeDialog (configs), SecretumVault (credenciales CI) | +| **GestiΓ³n de secretos PQC** | SecretumVault | Provisioning (infraestructura), Kogral (polΓ­ticas) | + +--- + +## 4. Por QuΓ© Son Necesarios + +### Problemas que Resuelven + +#### Vapora: El Problema de la CoordinaciΓ³n + +``` +ANTES DESPUΓ‰S (Vapora) +───────────────────────────────── ───────────────────────────────── +Agentes ejecutan sin contexto Perfiles de expertise por tarea +LLM fijo sin optimizaciΓ³n Routing dinΓ‘mico calidad/costo +Sin control de costos Budget per-role con fallback +Resultados no se reutilizan Knowledge Graph temporal +Manual handoffs Pipelines automatizados +``` + +#### Kogral: El Problema del Conocimiento Fragmentado + +``` +ANTES DESPUΓ‰S (Kogral) +───────────────────────────────── ───────────────────────────────── +Decisiones en Slack perdidas ADRs versionados en git +Patterns redescubiertos Library de patterns queryable +Guidelines inconsistentes Herencia org β†’ proyecto +IA sin contexto proyecto MCP con knowledge graph +Onboarding semanas BΓΊsqueda semΓ‘ntica dΓ­as +``` + +#### TypeDialog: El Problema de Interfaces MΓΊltiples + +``` +ANTES DESPUΓ‰S (TypeDialog) +───────────────────────────────── ───────────────────────────────── +CLI form β‰  TUI form β‰  Web form 1 TOML β†’ 6 backends +Configs sin validaciΓ³n Nickel contracts +Agentes IA separados .agent.mdx integrado +IaC manual por cloud Generator multi-cloud +i18n reimplementado Fluent bundles nativos +``` + +#### Provisioning: El Problema de la Complejidad IaC + +``` +ANTES DESPUΓ‰S (Provisioning) +───────────────────────────────── ───────────────────────────────── +HCL/YAML sin tipos Nickel tipado + lazy eval +Scripts imperativos Workflows declarativos +Sin recuperaciΓ³n automΓ‘tica Checkpoints + rollback +200+ ENV variables 476+ config accessors +Sin asistencia IA MCP + RAG (1000x Python) +``` + +#### SecretumVault: El Problema de la CriptografΓ­a CuΓ‘ntica + +``` +ANTES DESPUΓ‰S (SecretumVault) +───────────────────────────────── ───────────────────────────────── +Vault en Go (sin memory-safety) Rust con garantΓ­as de memoria +Solo crypto clΓ‘sica Post-quantum (ML-KEM, ML-DSA) +Backend crypto fijo Backends conectables +SaaS lock-in Self-hosted completo +Sin agilidad criptogrΓ‘fica Cambio de algoritmos sin cΓ³digo +``` + +--- + +## 5. QuΓ© los Hace Diferentes + +### CaracterΓ­sticas Únicas por Proyecto + +#### Vapora + +1. **Learning-based selection**: Scoring `0.3*load + 0.5*expertise + 0.2*confidence` con 3x recency bias +2. **Cost-aware routing**: Fallback automΓ‘tico cuando budget excedido +3. **Full Rust stack**: Frontend (Leptos) β†’ Backend (Axum) β†’ Agents β†’ Router +4. **Multi-tenant nativo**: SurrealDB scopes + Cedar RBAC + +#### Kogral + +1. **6 tipos de nodo especializados**: Note, Decision (ADR), Guideline, Pattern, Journal, Execution +2. **Hybrid embeddings**: fastembed local (privacidad) + cloud (producciΓ³n) +3. **MCP nativo**: 7 tools para Claude Code, no requiere configuraciΓ³n extra +4. **Logseq compatible**: Import/export bidireccional preservando estructura + +#### TypeDialog + +1. **6 backends unificados**: CLI/TUI/Web/AI/Agent/Prov-gen desde mismo TOML +2. **Agent execution**: `.agent.mdx` con Tera templates + multi-provider +3. **IaC generation**: AWS/GCP/Azure/Hetzner/UpCloud desde formularios tipados +4. **3,818 tests**: Cobertura exhaustiva (503% growth) + +#### Provisioning + +1. **Nickel IaC**: Único con language tipado lazy-eval como primary +2. **39K lΓ­neas seguridad**: 12 componentes enterprise (JWT, Cedar, MFA, audit) +3. **MCP 1000x faster**: Rust-native vs Python implementations +4. **80+ CLI shortcuts**: Developer experience optimizada + +#### SecretumVault + +1. **Post-Quantum nativo**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) listos para producciΓ³n +2. **4 backends crypto**: OpenSSL, OQS, AWS-LC, RustCrypto (agilidad criptogrΓ‘fica) +3. **4 backends storage**: Filesystem, etcd, SurrealDB, PostgreSQL +4. **Shamir Secret Sharing**: Unsealing distribuido con threshold configurable +5. **Cedar ABAC**: PolΓ­ticas de autorizaciΓ³n AWS-compatible + +--- + +## 6. Sinergias y ReutilizaciΓ³n + +### Flujo de IntegraciΓ³n + +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Conocimiento) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ Guidelines, Patterns, ADRs + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TypeDialog │───▢│ Vapora │───▢│ Provisioning β”‚ +β”‚ (Inputs) β”‚ β”‚ (OrquestaciΓ³n) β”‚ β”‚ (IaC) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ Formularios β”‚ Agentes β”‚ Infraestructura + β”‚ configuraciΓ³n β”‚ ejecutan tareas β”‚ desplegada + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PRODUCTO FINAL β”‚ +β”‚ Software desarrollado con IA, documentado, desplegado β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Componentes Reutilizables + +| Componente | Origen | Reutilizado En | +| ------------ | -------- | ---------------- | +| **SurrealDB schemas** | Vapora | Kogral, Provisioning, SecretumVault | +| **Nickel contracts** | Provisioning | TypeDialog, Kogral | +| **rig-core abstraction** | Vapora | Kogral, TypeDialog, Provisioning | +| **MCP patterns** | Kogral | Provisioning | +| **Axum API patterns** | Vapora | TypeDialog, Provisioning, SecretumVault | +| **Leptos components** | Vapora | Provisioning (control-center-ui) | +| **tracing setup** | Vapora | Todos | +| **Cedar policies** | Provisioning | Vapora, SecretumVault | +| **Crypto backends** | SecretumVault | Provisioning (KMS) | + +### Escenarios de Sinergia + +#### Escenario 1: Nuevo Proyecto Full-Stack + +``` +1. TypeDialog: Wizard para configuraciΓ³n inicial (tech stack, cloud, CI/CD) +2. Provisioning: Genera infraestructura desde respuestas +3. Kogral: Crea knowledge graph inicial con ADRs del setup +4. Vapora: Orquesta agentes para scaffolding cΓ³digo +``` + +#### Escenario 2: Feature Development + +``` +1. Kogral: MCP proporciona guidelines y patterns a Claude Code +2. Vapora: Coordina agentes (Architect β†’ Developer β†’ Reviewer) +3. TypeDialog: Valida configuraciones con Nickel contracts +4. Kogral: Registra decisiones como Execution nodes +``` + +#### Escenario 3: MigraciΓ³n de Infraestructura + +``` +1. Kogral: Documenta decisiones de migraciΓ³n como ADRs +2. TypeDialog: Formularios para parΓ‘metros de migraciΓ³n +3. Provisioning: Ejecuta migraciΓ³n multi-cloud con rollback +4. Vapora: Agentes monitorizan y reportan estado +``` + +#### Escenario 4: Onboarding Acelerado + +``` +1. Kogral: Export de knowledge graph para nuevo miembro +2. TypeDialog: Quiz interactivo sobre arquitectura +3. Vapora: Agentes asignan tareas de onboarding progresivas +4. Provisioning: Setup automΓ‘tico de entorno desarrollo +``` + +#### Escenario 5: MigraciΓ³n a CriptografΓ­a Post-CuΓ‘ntica + +``` +1. Kogral: Documenta ADRs de la migraciΓ³n criptogrΓ‘fica +2. SecretumVault: Migra secretos a backend OQS (ML-KEM-768) +3. Provisioning: Actualiza infraestructura con nuevos certificados +4. Vapora: Orquesta validaciΓ³n de integraciones +``` + +--- + +## 7. Dependencias y Orden de AdopciΓ³n + +### Grafo de Dependencias + +``` + Kogral (standalone) + β”‚ + β”‚ provides context to + β–Ό +Vapora ◄────────────────────────► TypeDialog + β”‚ β”‚ + β”‚ orchestrates β”‚ generates configs for + β–Ό β–Ό + Provisioning + (puede operar standalone) +``` + +### Orden Recomendado de AdopciΓ³n + +| Fase | Proyecto | RazΓ³n | +| ------ | ---------- | ------- | +| 1 | **Kogral** | Establece base de conocimiento (guidelines, patterns) | +| 2 | **TypeDialog** | Habilita inputs estructurados y validaciΓ³n | +| 3 | **SecretumVault** | GestiΓ³n de secretos con agilidad criptogrΓ‘fica | +| 4 | **Vapora** | Aprovecha knowledge graph para agentes inteligentes | +| 5 | **Provisioning** | Infraestructura informada por todo el contexto previo | + +**Nota**: Cada proyecto es funcional de forma independiente, pero las sinergias emergen con adopciΓ³n progresiva. + +--- + +## 8. Roadmap de IntegraciΓ³n + +### Integraciones Existentes + +- [x] Kogral ↔ Vapora: Agentes consultan knowledge graph +- [x] TypeDialog ↔ Provisioning: prov-gen backend genera IaC +- [x] Vapora ↔ SurrealDB: Persistencia multi-tenant +- [x] Kogral ↔ Claude Code: MCP server nativo +- [x] SecretumVault ↔ Nushell: Plugin nativo para operaciones vault + +### Integraciones Pendientes + +- [ ] Vapora ↔ TypeDialog: Formularios como input para pipelines de agentes +- [ ] Kogral ↔ Provisioning: ADRs de infraestructura automΓ‘ticos +- [ ] TypeDialog ↔ Kogral: Forms para captura de decisions +- [ ] SecretumVault ↔ Provisioning: KMS backend compartido +- [ ] SecretumVault ↔ Vapora: Credenciales para agentes +- [ ] Unified MCP: Gateway ΓΊnico para los 5 proyectos + +--- + +## 9. MΓ©tricas del Portfolio + +| MΓ©trica | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | **Total** | +| --------- | -------- | -------- | ------------ | -------------- | --------------- | ----------- | +| **Crates** | 13 | 3 | 8 | 15+ | 1 | **40+** | +| **Tests** | 218 | 56 | 3,818 | 218 | 50+ | **4,360+** | +| **LΓ­neas cΓ³digo** | ~50K | ~15K | ~90K | ~40K | ~11K | **~206K** | +| **LLM Providers** | 4 | 4 | 4 | 3 | - | **4 ΓΊnicos** | +| **MCP Tools** | Gateway | 7 | - | 7 | - | **14+** | +| **Crypto backends** | - | - | - | 5 KMS | 4 | **4 backends** | + +--- + +## 10. ConclusiΓ³n + +Este portfolio representa un ecosistema cohesivo para desarrollo asistido por IA: + +- **Vapora** es el cerebro: orquesta, aprende, optimiza costos +- **Kogral** es la memoria: captura, conecta, recuerda conocimiento +- **TypeDialog** es la interfaz: unifica inputs, ejecuta agentes, genera configs +- **SecretumVault** es la bΓ³veda: protege secretos con criptografΓ­a post-cuΓ‘ntica +- **Provisioning** es el mΓΊsculo: despliega infraestructura con IA y seguridad + +La **diferenciaciΓ³n clave** frente a alternativas: + +1. **Full Rust stack**: Rendimiento, type-safety, zero-cost abstractions +2. **Nickel everywhere**: ConfiguraciΓ³n tipada con validaciΓ³n pre-runtime +3. **Post-Quantum ready**: SecretumVault con ML-KEM-768/ML-DSA-65 nativos +3. **AI-native desde diseΓ±o**: No retrofitted, MCP y RAG integrados +4. **Enterprise-ready**: Multi-tenant, RBAC, audit, budget control + +La **sinergia** entre proyectos permite abordar nuevos desarrollos con: + +- Conocimiento contextualizado (Kogral) +- Inputs validados (TypeDialog) +- Agentes inteligentes que aprenden (Vapora) +- Infraestructura declarativa y segura (Provisioning) + +--- + +*Documento generado: 2026-01-22* +*Tipo: info (anΓ‘lisis de portfolio)* diff --git a/docs/es/ia/ia-stratumiops-projects-technical-specs.md b/docs/es/ia/ia-stratumiops-projects-technical-specs.md new file mode 100644 index 0000000..b4722fe --- /dev/null +++ b/docs/es/ia/ia-stratumiops-projects-technical-specs.md @@ -0,0 +1,1319 @@ +# Portfolio IA: Especificaciones TΓ©cnicas para Desarrolladores + +## Arquitectura del Ecosistema + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE PRESENTACIΓ“N β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Leptos WASM (Vapora UI) β”‚ Ratatui TUI β”‚ Axum REST β”‚ CLI (clap) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE ORQUESTACIΓ“N β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Vapora Coordinator β”‚ TypeDialog Backends β”‚ Provisioning Orchestrator β”‚ +β”‚ (NATS JetStream) β”‚ (BackendFactory) β”‚ (Rust/Nushell hybrid) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE CONOCIMIENTO β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Kogral Knowledge Graph β”‚ Vapora Learning Profiles β”‚ Provisioning RAG β”‚ +β”‚ (6 node types) β”‚ (expertise + recency) β”‚ (1200+ docs) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE PERSISTENCIA β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SurrealDB (multi-tenant scopes) β”‚ Filesystem (git-native markdown) β”‚ +β”‚ NATS JetStream (mensajerΓ­a) β”‚ Redis (vector stores opcionales) β”‚ +β”‚ etcd (SecretumVault HA) β”‚ PostgreSQL (vault enterprise) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 1. Vapora: Especificaciones + +### Workspace Structure + +```text +crates/ +β”œβ”€β”€ vapora-shared/ # Core: models, errors, types +β”œβ”€β”€ vapora-backend/ # Axum REST API (40+ endpoints) +β”œβ”€β”€ vapora-agents/ # Agent orchestration + learning +β”œβ”€β”€ vapora-llm-router/ # Multi-provider routing + budget +β”œβ”€β”€ vapora-swarm/ # Swarm coordination + metrics +β”œβ”€β”€ vapora-knowledge-graph/# Temporal KG + learning curves +β”œβ”€β”€ vapora-frontend/ # Leptos WASM UI +β”œβ”€β”€ vapora-mcp-server/ # MCP protocol gateway +β”œβ”€β”€ vapora-tracking/ # Task/project storage +β”œβ”€β”€ vapora-telemetry/ # OpenTelemetry integration +β”œβ”€β”€ vapora-analytics/ # Event pipeline +β”œβ”€β”€ vapora-worktree/ # Git worktree management +└── vapora-doc-lifecycle/ # Documentation management +``` + +### Core Types + +```rust +// vapora-shared/src/models.rs +pub struct Agent { + pub id: String, + pub role: AgentRole, // 12 roles disponibles + pub status: AgentStatus, // Ready | Busy | Offline + pub provider: LLMProvider, // Claude | OpenAI | Gemini | Ollama + pub last_heartbeat: DateTime<Utc>, +} + +pub enum AgentRole { + Architect, Developer, CodeReviewer, Tester, + Documenter, Marketer, Presenter, DevOps, + Monitor, Security, ProjectManager, DecisionMaker, +} + +// vapora-agents/src/learning_profile.rs +pub struct ExpertiseProfile { + pub task_type: String, + pub success_rate: f64, + pub avg_duration: Duration, + pub execution_count: u32, + pub recent_weight: f64, // 3x for last 7 days + pub confidence: f64, // prevents overfitting on small samples +} + +// Scoring formula +fn calculate_score(load: f64, expertise: f64, confidence: f64) -> f64 { + 0.3 * load + 0.5 * expertise + 0.2 * confidence +} +``` + +### LLM Router Configuration + +```rust +// vapora-llm-router/src/config.rs +pub struct RoutingRule { + pub pattern: String, // regex para task type + pub provider: LLMProvider, + pub model: String, + pub fallback_chain: Vec<LLMProvider>, +} + +pub struct BudgetConfig { + pub role: AgentRole, + pub monthly_limit_cents: u32, + pub weekly_limit_cents: Option<u32>, + pub enforcement: BudgetEnforcement, // Normal | NearThreshold | Exceeded +} + +// Cost tracking per request +pub struct CostRecord { + pub provider: LLMProvider, + pub model: String, + pub input_tokens: u32, + pub output_tokens: u32, + pub cost_cents: f64, + pub task_type: String, + pub timestamp: DateTime<Utc>, +} +``` + +### API Endpoints (Axum) + +```rust +// vapora-backend/src/api/mod.rs +Router::new() + // Projects + .route("/projects", get(list_projects).post(create_project)) + .route("/projects/:id", get(get_project).put(update_project).delete(delete_project)) + + // Tasks + .route("/tasks", get(list_tasks).post(create_task)) + .route("/tasks/:id/assign", post(assign_to_agent)) + + // Agents + .route("/agents", get(list_agents)) + .route("/agents/:id/health", get(agent_health)) + .route("/agents/:role/expertise", get(role_expertise)) + + // LLM Router + .route("/llm/route", post(route_request)) + .route("/llm/budget/:role", get(get_budget).put(set_budget)) + .route("/llm/costs", get(cost_report)) + + // Swarm + .route("/swarm/assign", post(assign_task)) + .route("/swarm/status", get(swarm_status)) + + // Metrics + .route("/metrics", get(prometheus_metrics)) +``` + +### NATS Message Types + +```rust +// vapora-agents/src/messages.rs +#[derive(Serialize, Deserialize)] +pub enum AgentMessage { + TaskAssignment { + task_id: String, + agent_id: String, + task_type: String, + payload: serde_json::Value, + }, + TaskResult { + task_id: String, + agent_id: String, + status: TaskStatus, + output: Option<String>, + duration_ms: u64, + tokens_used: u32, + }, + Heartbeat { + agent_id: String, + status: AgentStatus, + current_load: f64, + }, +} + +// Subjects +const TASK_ASSIGNMENT: &str = "vapora.tasks.assign"; +const TASK_RESULTS: &str = "vapora.tasks.results"; +const AGENT_HEARTBEAT: &str = "vapora.agents.heartbeat"; +``` + +--- + +## 2. Kogral: Especificaciones + +### Workspace Structure + +``` +crates/ +β”œβ”€β”€ kogral-core/ # Core library (models, storage, query) +β”œβ”€β”€ kogral-cli/ # CLI (13 commands) +└── kogral-mcp/ # MCP server for Claude Code +``` + +### Node Types + +```rust +// kogral-core/src/models.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum NodeType { + Note, // General notes + Decision, // ADRs (Architectural Decision Records) + Guideline, // Team/org standards + Pattern, // Reusable solutions + Journal, // Daily development log + Execution, // Agent execution records +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum RelationType { + RelatesTo, + DependsOn, + Implements, + Extends, + Supersedes, + Explains, +} + +pub struct Node { + pub id: String, + pub node_type: NodeType, + pub title: String, + pub content: String, // Markdown body + pub metadata: HashMap<String, String>, + pub tags: Vec<String>, + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, +} + +pub struct Edge { + pub source: String, // Node ID + pub target: String, // Node ID + pub relation: RelationType, + pub weight: f64, // Relationship strength +} +``` + +### Storage Backends + +```rust +// kogral-core/src/storage/mod.rs +#[async_trait] +pub trait Storage: Send + Sync { + async fn create_node(&self, node: &Node) -> Result<String>; + async fn get_node(&self, id: &str) -> Result<Option<Node>>; + async fn update_node(&self, node: &Node) -> Result<()>; + async fn delete_node(&self, id: &str) -> Result<()>; + async fn list_nodes(&self, filter: NodeFilter) -> Result<Vec<Node>>; + + async fn create_edge(&self, edge: &Edge) -> Result<()>; + async fn get_edges(&self, node_id: &str) -> Result<Vec<Edge>>; + async fn delete_edge(&self, source: &str, target: &str) -> Result<()>; + + async fn search(&self, query: &str, limit: usize) -> Result<Vec<Node>>; + async fn semantic_search(&self, embedding: &[f32], limit: usize) -> Result<Vec<Node>>; +} + +// Implementations +pub struct FilesystemStorage { /* .kogral/ directory */ } +pub struct SurrealDbStorage { /* SurrealDB connection */ } +pub struct MemoryStorage { /* DashMap for testing */ } +``` + +### Embedding Configuration + +```rust +// kogral-core/src/embeddings.rs +pub enum EmbeddingProvider { + FastEmbed { + model: String, // "BAAI/bge-small-en-v1.5" + dimensions: usize, // 384 + }, + OpenAI { + model: String, // "text-embedding-3-small" + api_key: String, + }, + Ollama { + model: String, + url: String, + }, +} + +#[async_trait] +pub trait Embedder: Send + Sync { + async fn embed(&self, text: &str) -> Result<Vec<f32>>; + async fn embed_batch(&self, texts: &[String]) -> Result<Vec<Vec<f32>>>; + fn dimensions(&self) -> usize; +} +``` + +### MCP Server Tools + +```rust +// kogral-mcp/src/tools.rs +pub const MCP_TOOLS: &[Tool] = &[ + Tool { + name: "search", + description: "Search knowledge graph by text or semantic similarity", + parameters: json!({ + "query": { "type": "string" }, + "node_type": { "type": "string", "optional": true }, + "limit": { "type": "integer", "default": 10 } + }), + }, + Tool { + name: "add_note", + description: "Add a new note to the knowledge graph", + parameters: json!({ + "title": { "type": "string" }, + "content": { "type": "string" }, + "tags": { "type": "array", "items": { "type": "string" } } + }), + }, + Tool { + name: "add_decision", + description: "Record an architectural decision (ADR)", + parameters: json!({ + "title": { "type": "string" }, + "context": { "type": "string" }, + "decision": { "type": "string" }, + "consequences": { "type": "string" } + }), + }, + Tool { + name: "link", + description: "Create relationship between nodes", + parameters: json!({ + "source_id": { "type": "string" }, + "target_id": { "type": "string" }, + "relation": { "type": "string", "enum": ["relates_to", "depends_on", "implements", "extends", "supersedes", "explains"] } + }), + }, + Tool { + name: "get_guidelines", + description: "Get applicable guidelines for a topic", + parameters: json!({ + "topic": { "type": "string" }, + "include_shared": { "type": "boolean", "default": true } + }), + }, + Tool { + name: "list_graphs", + description: "List available knowledge graphs", + parameters: json!({}), + }, + Tool { + name: "export", + description: "Export knowledge graph to format", + parameters: json!({ + "format": { "type": "string", "enum": ["markdown", "json", "yaml"] }, + "filter": { "type": "object", "optional": true } + }), + }, +]; +``` + +### CLI Commands + +```bash +# kogral-cli commands +kogral init # Initialize .kogral/ directory +kogral add note <title> # Add note interactively +kogral add decision <title> # Add ADR with guided prompts +kogral search <query> # Text search +kogral search --semantic <q> # Semantic search +kogral link <src> <dst> <rel> # Create relationship +kogral list [--type <type>] # List nodes +kogral show <id> # Display node details +kogral delete <id> # Remove node +kogral graph # Visualize graph (DOT format) +kogral sync # Sync filesystem ↔ SurrealDB +kogral serve # Start MCP server +kogral import <path> # Import from Logseq/markdown +kogral export <format> # Export to markdown/json +kogral config # Show/edit configuration +``` + +--- + +## 3. TypeDialog: Especificaciones + +### Workspace Structure + +```text +crates/ +β”œβ”€β”€ typedialog-core/ # Core (forms, backends, validation) +β”œβ”€β”€ typedialog/ # CLI binary +β”œβ”€β”€ typedialog-tui/ # TUI binary (ratatui) +β”œβ”€β”€ typedialog-web/ # Web binary (axum) +β”œβ”€β”€ typedialog-ai/ # AI backend (RAG, embeddings) +β”œβ”€β”€ typedialog-agent/ +β”‚ β”œβ”€β”€ typedialog-ag-core/ # Agent runtime +β”‚ └── typedialog-ag/ # Agent CLI +└── typedialog-prov-gen/ # IaC generation +``` + +### Form Definition (TOML) + +```toml +# employee_onboarding.toml +[form] +id = "employee_onboarding" +version = "1.0.0" +title = "Employee Onboarding" +description = "New employee registration form" + +[[sections]] +id = "personal" +title = "Personal Information" + +[[sections.fields]] +id = "full_name" +type = "text" +label = "Full Name" +required = true +validation.min_length = 2 +validation.max_length = 100 + +[[sections.fields]] +id = "department" +type = "select" +label = "Department" +required = true +options = [ + { value = "engineering", label = "Engineering" }, + { value = "product", label = "Product" }, + { value = "design", label = "Design" }, +] + +[[sections.fields]] +id = "skills" +type = "multi-select" +label = "Skills" +display_mode = "grid" +options = [ + { value = "rust", label = "Rust" }, + { value = "typescript", label = "TypeScript" }, + { value = "python", label = "Python" }, +] + +[[sections.fields]] +id = "start_date" +type = "date" +label = "Start Date" +default = "today" + +[output] +format = "json" +validation = "nickel://schemas/employee.ncl" +``` + +### Backend Trait + +```rust +// typedialog-core/src/backend.rs +#[async_trait] +pub trait Backend: Send + Sync { + fn name(&self) -> &str; + + async fn execute(&self, form: &Form) -> Result<FormResponse>; + + async fn render_field(&self, field: &Field, value: Option<&Value>) -> Result<Value>; + + fn supports_streaming(&self) -> bool { false } +} + +pub struct BackendFactory; + +impl BackendFactory { + pub fn create(backend_type: BackendType) -> Box<dyn Backend> { + match backend_type { + BackendType::Cli => Box::new(CliBackend::new()), + BackendType::Tui => Box::new(TuiBackend::new()), + BackendType::Web => Box::new(WebBackend::new()), + BackendType::Ai => Box::new(AiBackend::new()), + BackendType::Agent => Box::new(AgentBackend::new()), + BackendType::ProvGen => Box::new(ProvGenBackend::new()), + } + } +} +``` + +### Agent MDX Format + +```mdx +--- +name: code_reviewer +version: "1.0" +provider: claude +model: claude-sonnet-4-20250514 +temperature: 0.3 +max_tokens: 4096 +--- + +# Code Review Agent + +## System Prompt + +You are an expert code reviewer. Review the following code for: + +- Security vulnerabilities +- Performance issues +- Code style and best practices +- Potential bugs + +## Template Variables + +- `{{language}}`: Programming language +- `{{code}}`: Code to review +- `{{guidelines}}`: Project-specific guidelines + +## User Prompt + +Review this {{language}} code: + +` ` `{{language}} +{{code}} +` ` ` + +Project guidelines: + +{{guidelines}} + +Provide a structured review with severity levels (critical, warning, info). + +## Output Validation + +format: json +schema: | + { + "issues": [{ + "severity": "critical | warning | info", + "line": number, + "message": string, + "suggestion": string + }], + "summary": string + } +``` + +### Nickel Contract Integration + +```rust +// typedialog-core/src/nickel.rs +pub struct NickelValidator { + runtime: nickel_lang_core::eval::Runtime, +} + +impl NickelValidator { + pub fn validate(&self, data: &Value, contract_path: &str) -> Result<ValidationResult> { + let contract = self.runtime.load(contract_path)?; + let result = self.runtime.eval_with_contract(data, contract)?; + Ok(result) + } + + pub fn extract_schema(&self, contract_path: &str) -> Result<FormSchema> { + // Parse Nickel contract and generate form schema + let contract = self.runtime.load(contract_path)?; + FormSchema::from_nickel_contract(&contract) + } +} +``` + +### Prov-Gen Output + +```rust +// typedialog-prov-gen/src/generator.rs +pub enum CloudProvider { + Aws, + Gcp, + Azure, + Hetzner, + UpCloud, + Lxd, +} + +pub struct InfrastructureConfig { + pub provider: CloudProvider, + pub region: String, + pub resources: Vec<Resource>, + pub networking: NetworkConfig, + pub security: SecurityConfig, +} + +pub struct Generator { + templates: tera::Tera, + validators: Vec<Box<dyn Validator>>, // 7-layer validation +} + +impl Generator { + pub async fn generate(&self, config: &InfrastructureConfig) -> Result<GeneratedIaC> { + // 1. Validate input config + self.validate_config(config)?; + + // 2. Load provider-specific templates + let template = self.templates.get_template(&format!("{}.ncl.tera", config.provider))?; + + // 3. Render Nickel configuration + let nickel_code = template.render(&config)?; + + // 4. Validate generated Nickel + self.validate_nickel(&nickel_code)?; + + Ok(GeneratedIaC { + provider: config.provider, + code: nickel_code, + files: self.split_to_files(&nickel_code)?, + }) + } +} +``` + +--- + +## 4. Provisioning: Especificaciones + +### Directory Structure + +```text +provisioning/ +β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ cli/ # Main CLI (211 lines) +β”‚ β”œβ”€β”€ nulib/ # Nushell libraries (476+ accessors) +β”‚ └── scripts/ # Utility scripts +β”œβ”€β”€ extensions/ +β”‚ β”œβ”€β”€ providers/ # AWS, UpCloud, Local +β”‚ β”œβ”€β”€ taskservs/ # 50+ infrastructure services +β”‚ β”œβ”€β”€ clusters/ # Deployment templates +β”‚ └── workflows/ # Automation workflows +β”œβ”€β”€ platform/ +β”‚ β”œβ”€β”€ orchestrator/ # Workflow execution (Rust) +β”‚ β”œβ”€β”€ control-center/ # Backend (Axum + RBAC) +β”‚ β”œβ”€β”€ control-center-ui/ # Web dashboard (Leptos) +β”‚ β”œβ”€β”€ installer/ # Multi-mode installer +β”‚ β”œβ”€β”€ mcp-server/ # MCP server (Rust) +β”‚ β”œβ”€β”€ ai-service/ # AI operations +β”‚ β”œβ”€β”€ rag/ # RAG system +β”‚ β”œβ”€β”€ vault-service/ # Secrets management +β”‚ └── detector/ # Anomaly detection +└── schemas/ # Nickel IaC schemas +``` + +### Nickel IaC Schema + +```nickel +# schemas/server.ncl +let Server = { + name | String, + provider | [ | 'aws, 'upcloud, 'local |], + + spec | { + cpu | Number | default = 2, + memory_gb | Number | default = 4, + disk_gb | Number | default = 50, + + os | { + family | [ | 'ubuntu, 'debian, 'rocky |], + version | String, + }, + }, + + networking | { + vpc | String | optional, + subnet | String | optional, + public_ip | Bool | default = false, + security_groups | Array String | default = [], + }, + + tags | { _ : String } | default = {}, +} +in Server +``` + +### Orchestrator API + +```rust +// platform/orchestrator/src/lib.rs +pub struct Orchestrator { + state: StateManager, + executor: WorkflowExecutor, + scheduler: Scheduler, +} + +impl Orchestrator { + pub async fn execute_workflow(&self, workflow: Workflow) -> Result<ExecutionResult> { + // 1. Resolve dependencies (topological sort) + let ordered_tasks = self.resolve_dependencies(&workflow)?; + + // 2. Create execution checkpoints + let checkpoint = self.state.create_checkpoint(&workflow)?; + + // 3. Execute tasks with retry logic + for task in ordered_tasks { + match self.executor.run(&task).await { + Ok(result) => { + self.state.record_success(&task, &result)?; + } + Err(e) => { + // Exponential backoff retry + if let Some(result) = self.retry_with_backoff(&task).await? { + self.state.record_success(&task, &result)?; + } else { + // Rollback to checkpoint + self.state.rollback(&checkpoint)?; + return Err(e); + } + } + } + } + + Ok(ExecutionResult::from_state(&self.state)) + } +} +``` + +### MCP Tools + +```rust +// platform/mcp-server/src/tools.rs +pub const MCP_TOOLS: &[Tool] = &[ + Tool { + name: "query_infrastructure", + description: "Query infrastructure state using natural language", + parameters: json!({ + "query": { "type": "string" }, + "provider": { "type": "string", "optional": true } + }), + }, + Tool { + name: "generate_config", + description: "Generate Nickel configuration from description", + parameters: json!({ + "description": { "type": "string" }, + "provider": { "type": "string" }, + "resource_type": { "type": "string" } + }), + }, + Tool { + name: "validate_config", + description: "Validate Nickel configuration", + parameters: json!({ + "config": { "type": "string" }, + "strict": { "type": "boolean", "default": true } + }), + }, + Tool { + name: "estimate_cost", + description: "Estimate monthly cost for configuration", + parameters: json!({ + "config": { "type": "string" }, + "region": { "type": "string", "optional": true } + }), + }, + Tool { + name: "check_compliance", + description: "Check configuration against compliance rules", + parameters: json!({ + "config": { "type": "string" }, + "framework": { "type": "string", "enum": ["soc2", "hipaa", "gdpr", "pci"] } + }), + }, + Tool { + name: "plan_migration", + description: "Generate migration plan between configurations", + parameters: json!({ + "current": { "type": "string" }, + "target": { "type": "string" } + }), + }, + Tool { + name: "execute_workflow", + description: "Execute provisioning workflow", + parameters: json!({ + "workflow_id": { "type": "string" }, + "dry_run": { "type": "boolean", "default": true } + }), + }, +]; +``` + +### RAG Configuration + +```rust +// platform/rag/src/config.rs +pub struct RagConfig { + pub embedding_model: String, // "text-embedding-3-small" + pub embedding_dimensions: usize, // 1536 + pub chunk_size: usize, // 512 tokens + pub chunk_overlap: usize, // 50 tokens + pub top_k: usize, // 5 results + pub min_similarity: f32, // 0.7 + pub reranker: Option<RerankerConfig>, +} + +pub struct RagService { + embedder: Box<dyn Embedder>, + vector_store: Box<dyn VectorStore>, + keyword_index: tantivy::Index, +} + +impl RagService { + pub async fn query(&self, question: &str) -> Result<Vec<Document>> { + // 1. Generate embedding for question + let embedding = self.embedder.embed(question).await?; + + // 2. Vector similarity search + let vector_results = self.vector_store.search(&embedding, self.config.top_k).await?; + + // 3. BM25 keyword search + let keyword_results = self.keyword_search(question)?; + + // 4. Hybrid ranking (RRF) + let merged = self.reciprocal_rank_fusion(vector_results, keyword_results); + + // 5. Optional reranking + if let Some(reranker) = &self.reranker { + return reranker.rerank(&merged, question).await; + } + + Ok(merged) + } +} +``` + +--- + +## 5. SecretumVault: Especificaciones + +### Arquitectura General + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault (~11K LOC, 50+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (clap) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Core Types + +```rust +// src/core/vault.rs +pub struct VaultCore { + pub engines: HashMap<String, Box<dyn Engine>>, + pub storage: Arc<dyn StorageBackend>, + pub crypto: Arc<dyn CryptoBackend>, + pub seal: Arc<tokio::sync::Mutex<SealMechanism>>, + pub token_manager: Arc<TokenManager>, + pub metrics: Arc<Metrics>, +} + +// src/crypto/mod.rs +#[async_trait] +pub trait CryptoBackend: Send + Sync { + async fn generate_keypair(&self, algorithm: KeyAlgorithm) -> CryptoResult<KeyPair>; + async fn sign(&self, key: &PrivateKey, data: &[u8]) -> CryptoResult<Vec<u8>>; + async fn verify(&self, key: &PublicKey, data: &[u8], sig: &[u8]) -> CryptoResult<bool>; + async fn encrypt(&self, plaintext: &[u8]) -> CryptoResult<Vec<u8>>; + async fn decrypt(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; + + // Post-Quantum (OQS backend) + async fn kem_encapsulate(&self, public_key: &[u8]) -> CryptoResult<KemResult>; + async fn kem_decapsulate(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; +} + +// src/storage/mod.rs +#[async_trait] +pub trait StorageBackend: Send + Sync { + async fn store_secret(&self, path: &str, data: &EncryptedData) -> StorageResult<()>; + async fn get_secret(&self, path: &str) -> StorageResult<EncryptedData>; + async fn delete_secret(&self, path: &str) -> StorageResult<()>; + async fn list_secrets(&self, prefix: &str) -> StorageResult<Vec<String>>; +} +``` + +### Crypto Backends + +```rust +// src/crypto/backends/ +pub enum CryptoBackendType { + OpenSSL, // RSA, ECDSA, AES-256-GCM + Oqs, // ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) + AwsLc, // RSA, ECDSA (experimental PQC) + RustCrypto, // AES-GCM, ChaCha20-Poly1305 (testing) +} + +// OQS Post-Quantum (production-ready) +pub struct OqsBackend { + kem_algorithm: oqs::kem::Algorithm, // MlKem768 + sig_algorithm: oqs::sig::Algorithm, // MlDsa65 +} + +impl OqsBackend { + pub async fn kem_keygen(&self) -> CryptoResult<KemKeyPair> { + // ML-KEM-768: 1088 bytes ciphertext, 32 bytes shared secret + let kem = oqs::kem::Kem::new(self.kem_algorithm)?; + let (pk, sk) = kem.keypair()?; + Ok(KemKeyPair { public_key: pk, secret_key: sk }) + } + + pub async fn sign(&self, sk: &[u8], message: &[u8]) -> CryptoResult<Vec<u8>> { + // ML-DSA-65 signatures + let sig = oqs::sig::Sig::new(self.sig_algorithm)?; + let signature = sig.sign(message, sk)?; + Ok(signature.into_vec()) + } +} +``` + +### Secrets Engines + +```rust +// src/engines/mod.rs +pub trait Engine: Send + Sync { + fn name(&self) -> &str; + fn engine_type(&self) -> &str; + async fn read(&self, path: &str) -> Result<Option<Value>>; + async fn write(&self, path: &str, data: &Value) -> Result<()>; + async fn delete(&self, path: &str) -> Result<()>; + async fn list(&self, prefix: &str) -> Result<Vec<String>>; +} + +// Engines disponibles +pub struct KvEngine { /* Versioned secret storage */ } +pub struct TransitEngine { /* Encryption-as-a-service */ } +pub struct PkiEngine { /* X.509 certificates */ } +pub struct DatabaseEngine { /* Dynamic credentials */ } +``` + +### Seal Mechanism (Shamir) + +```rust +// src/core/seal.rs +pub struct SealMechanism { + state: SealState, + shares: Vec<SecretShare>, + threshold: u8, + total_shares: u8, +} + +pub enum SealState { + Sealed, + Unsealing { collected: usize }, + Unsealed { master_key: Vec<u8> }, +} + +impl SealMechanism { + pub fn init(&mut self, shares: u8, threshold: u8) -> Result<Vec<SecretShare>> { + // Generate master key and split with Shamir + let master_key = generate_random_bytes(32)?; + let sharks = Sharks(threshold); + let dealer = sharks.dealer(&master_key); + let shares: Vec<_> = dealer.take(shares as usize).collect(); + self.state = SealState::Sealed; + Ok(shares) + } + + pub fn unseal(&mut self, share: SecretShare) -> Result<UnsealProgress> { + // Collect shares until threshold met + self.shares.push(share); + if self.shares.len() >= self.threshold as usize { + let sharks = Sharks(self.threshold); + let master_key = sharks.recover(&self.shares)?; + self.state = SealState::Unsealed { master_key }; + return Ok(UnsealProgress::Complete); + } + Ok(UnsealProgress::NeedMore { collected: self.shares.len() }) + } +} +``` + +### Authorization (Cedar ABAC) + +```rust +// src/auth/cedar.rs +pub struct CedarAuthorizer { + engine: cedar_policy::Authorizer, + policies: cedar_policy::PolicySet, +} + +impl CedarAuthorizer { + pub fn authorize(&self, request: &AuthzRequest) -> Result<Decision> { + let principal = self.build_principal(&request.user)?; + let action = self.build_action(&request.action)?; + let resource = self.build_resource(&request.resource)?; + + let decision = self.engine.is_authorized( + &principal, + &action, + &resource, + &self.policies, + )?; + + Ok(decision) + } +} +``` + +### API Endpoints + +```rust +// src/api/routes.rs +Router::new() + // System + .route("/v1/sys/health", get(health_check)) + .route("/v1/sys/init", post(initialize_vault)) + .route("/v1/sys/seal", post(seal_vault)) + .route("/v1/sys/unseal", post(unseal_vault)) + .route("/v1/sys/mounts", get(list_mounts)) + + // Secrets (dynamic routing by engine) + .route("/v1/*path", get(read_secret) + .post(write_secret) + .delete(delete_secret)) + + // Metrics + .route("/metrics", get(prometheus_metrics)) +``` + +### Configuration (TOML) + +```toml +# svault.toml +[vault] +crypto_backend = "oqs" # openssl | oqs | aws-lc | rustcrypto + +[server] +address = "0.0.0.0:8200" +tls_cert = "/path/to/cert.pem" +tls_key = "/path/to/key.pem" + +[storage] +backend = "etcd" # filesystem | etcd | surrealdb | postgresql + +[storage.etcd] +endpoints = ["http://localhost:2379"] + +[seal.shamir] +shares = 5 +threshold = 3 + +[auth] +token_ttl = "24h" +``` + +### CLI Commands + +```bash +# Server +svault server --config svault.toml + +# Operator +svault operator init --shares 5 --threshold 3 +svault operator unseal --share <share> +svault operator seal +svault operator status + +# Secrets +svault secret read secret/myapp +svault secret write secret/myapp key=value +svault secret delete secret/myapp +svault secret list secret/ +``` + +### Feature Flags + +```toml +# Cargo.toml features +[features] +default = ["openssl", "filesystem", "server", "pqc"] + +# Crypto backends +openssl = ["dep:openssl"] +aws-lc = ["dep:aws-lc-rs"] +pqc = ["dep:oqs"] +rustcrypto = ["dep:aes-gcm", "dep:chacha20poly1305"] + +# Storage backends +filesystem = [] +surrealdb-storage = ["dep:surrealdb"] +etcd-storage = ["dep:etcd-client"] +postgresql-storage = ["dep:sqlx"] + +# Components +server = ["dep:axum", "dep:rustls"] +cli = ["dep:clap"] +cedar = ["dep:cedar-policy"] +``` + +--- + +## 6. IntegraciΓ³n entre Proyectos + +### Diagrama de Dependencias + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Knowledge Graph) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + MCP (guidelines, patterns, decisions) + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Vapora β”‚ β”‚ TypeDialog β”‚ β”‚ Provisioning β”‚ +β”‚(Orchestrate)β”‚ β”‚ (Forms/UI) β”‚ β”‚ (IaC) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ β”‚ β”‚ + β”‚ β–Ό β–Ό β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ SecretumVault β”‚ β”‚ + β”‚ β”‚ (Secrets + PQC Crypto) β”‚ β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ SurrealDB β”‚ + β”‚ (Shared State) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Shared Dependencies (Cargo.toml) + +```toml +# Dependencias comunes a todos los proyectos +[dependencies] +# Runtime +tokio = { version = "1.48", features = ["full"] } + +# Serialization +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" + +# Database +surrealdb = "2.3" + +# Web +axum = "0.8" + +# LLM +rig-core = "0.15" + +# Config +nickel-lang-core = "1.15" + +# Logging +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] } + +# Error handling +anyhow = "1.0" +thiserror = "2.0" +``` + +### SurrealDB Schema Compartido + +```sql +-- Namespace compartido para cross-project state +DEFINE NAMESPACE portfolio; + +-- Scope para cada proyecto +DEFINE DATABASE vapora; +DEFINE DATABASE kogral; +DEFINE DATABASE typedialog; +DEFINE DATABASE provisioning; +DEFINE DATABASE secretumvault; + +-- Tabla compartida para execution records +DEFINE TABLE executions SCHEMAFULL; +DEFINE FIELD project ON executions TYPE string; +DEFINE FIELD task_type ON executions TYPE string; +DEFINE FIELD agent_id ON executions TYPE string; +DEFINE FIELD status ON executions TYPE string; +DEFINE FIELD duration_ms ON executions TYPE int; +DEFINE FIELD tokens_used ON executions TYPE int; +DEFINE FIELD cost_cents ON executions TYPE float; +DEFINE FIELD created_at ON executions TYPE datetime DEFAULT time::now(); + +-- Índices para queries cross-project +DEFINE INDEX idx_executions_project ON executions FIELDS project; +DEFINE INDEX idx_executions_agent ON executions FIELDS agent_id; +``` + +### Ejemplo de IntegraciΓ³n: Feature Development + +```rust +// Flujo integrado de desarrollo de feature +async fn develop_feature(feature_spec: &str) -> Result<FeatureResult> { + // 1. Kogral: Obtener contexto del proyecto + let kogral_client = KogralMcpClient::connect().await?; + let guidelines = kogral_client.call("get_guidelines", json!({ + "topic": feature_spec, + "include_shared": true + })).await?; + + let patterns = kogral_client.call("search", json!({ + "query": feature_spec, + "node_type": "pattern", + "limit": 5 + })).await?; + + // 2. TypeDialog: Capturar configuraciΓ³n adicional + let typedialog = TypeDialog::new(BackendType::Cli); + let config = typedialog.execute_form("feature_config.toml").await?; + + // 3. Vapora: Orquestar agentes + let vapora_client = VaporaClient::new("http://localhost:8001"); + + // Crear tarea con contexto + let task = vapora_client.create_task(TaskRequest { + title: format!("Implement: {}", feature_spec), + context: json!({ + "guidelines": guidelines, + "patterns": patterns, + "config": config, + }), + task_type: "feature_implementation", + }).await?; + + // Ejecutar pipeline + let pipeline = vec![ + ("architect", "Design feature architecture"), + ("developer", "Implement feature"), + ("reviewer", "Review implementation"), + ("tester", "Write and run tests"), + ]; + + for (role, description) in pipeline { + vapora_client.assign_task(&task.id, role, description).await?; + vapora_client.wait_for_completion(&task.id).await?; + } + + // 4. Kogral: Registrar decisiΓ³n + kogral_client.call("add_decision", json!({ + "title": format!("Feature: {}", feature_spec), + "context": &task.context, + "decision": &task.result, + "consequences": "Implementation completed" + })).await?; + + // 5. Provisioning: Desplegar si es necesario + if config.requires_infra { + let prov_client = ProvisioningMcpClient::connect().await?; + prov_client.call("execute_workflow", json!({ + "workflow_id": config.deployment_workflow, + "dry_run": false + })).await?; + } + + Ok(FeatureResult { + task_id: task.id, + status: task.status, + }) +} +``` + +--- + +## 7. MΓ©tricas de Calidad + +| Proyecto | Tests | Cobertura | Clippy | Unsafe | Doc Coverage | +| ---------- | ------- | ----------- | -------- | -------- | -------------- | +| Vapora | 218 | ~70% | 0 warnings | 0 | 100% public | +| Kogral | 56 | ~80% | 0 warnings | 0 | 100% public | +| TypeDialog | 3,818 | ~85% | 0 warnings | 0 | 100% public | +| Provisioning | 218 | ~65% | 0 warnings | 0 | 100% public | +| SecretumVault | 50+ | ~75% | 0 warnings | 0 | 100% public | + +### Comandos de VerificaciΓ³n + +```bash +# Por proyecto +cargo clippy --all-targets --all-features -- -D warnings +cargo test --workspace +cargo doc --no-deps + +# Coverage (requiere tarpaulin) +cargo tarpaulin --workspace --out Html + +# Benchmarks +cargo bench --workspace +``` + +--- + +*Documento generado: 2026-01-22* +*Tipo: info (especificaciones tΓ©cnicas)* diff --git a/docs/es/ia/ia-stratumiops-projects.md b/docs/es/ia/ia-stratumiops-projects.md new file mode 100644 index 0000000..7dbc3c5 --- /dev/null +++ b/docs/es/ia/ia-stratumiops-projects.md @@ -0,0 +1,312 @@ +# Portfolio IA: Desarrollo Inteligente de Principio a Fin + +## El Problema + +Los equipos de desarrollo enfrentan desafΓ­os crΓ­ticos al integrar IA en sus flujos de trabajo: + +- **Conocimiento disperso**: Decisiones en Slack, patterns en wikis, guidelines en docs separados +- **Agentes IA sin contexto**: Generan cΓ³digo que ignora las convenciones del proyecto +- **Costos LLM descontrolados**: Sin visibilidad ni lΓ­mites por equipo o tarea +- **Infraestructura manual**: ConfiguraciΓ³n repetitiva que consume tiempo valioso +- **Interfaces fragmentadas**: Una herramienta para CLI, otra para web, otra para TUI + +## La SoluciΓ³n: Un Ecosistema Integrado + +Cinco proyectos diseΓ±ados para trabajar juntos, cada uno resolviendo un problema especΓ­fico. + +--- + +## Vapora: OrquestaciΓ³n Inteligente de Agentes + +### Agentes que Aprenden de la Experiencia + +Vapora no es otro framework de agentes. Es un sistema que **aprende quΓ© agente es mejor para cada tarea** basΓ‘ndose en ejecuciones previas. + +**CΓ³mo funciona**: + +- Cada ejecuciΓ³n construye un perfil de expertise por tipo de tarea +- Las ΓΊltimas 7 dΓ­as pesan 3x mΓ‘s que el histΓ³rico (recency bias) +- Los agentes nuevos no se sobreponen a los experimentados (confidence weighting) + +**Control de costos real**: + +- Presupuestos por rol (mensual/semanal) +- Tres niveles: normal β†’ cerca del lΓ­mite β†’ excedido +- Fallback automΓ‘tico a proveedores mΓ‘s baratos sin intervenciΓ³n manual + +**Para quiΓ©n**: + +- Equipos que usan mΓΊltiples agentes IA para desarrollo +- Organizaciones que necesitan controlar gastos LLM +- Proyectos con pipelines de cΓ³digo (architect β†’ developer β†’ reviewer β†’ tester) + +**Resultados esperados**: + +- ReducciΓ³n de costos LLM mediante routing inteligente +- Mejora en calidad de outputs al asignar agentes segΓΊn expertise +- Visibilidad completa de gastos y rendimiento por agente + +--- + +## Kogral: El Conocimiento del Equipo, Queryable + +### Tu Base de Conocimiento con IA Integrada + +Kogral captura las decisiones, patterns y guidelines de tu equipo en un formato que tanto humanos como agentes IA pueden consultar. + +**QuΓ© lo hace diferente**: + +- **6 tipos de nodo especializados**: Notes, Decisions (ADRs), Guidelines, Patterns, Journals, Executions +- **Git-native**: Todo en markdown versionado, no en un SaaS externo +- **MCP para Claude Code**: Tus agentes consultan guidelines antes de generar cΓ³digo + +**El flujo**: +```text +Desarrollador toma decisiΓ³n β†’ Captura en Kogral como ADR + ↓ + Claude Code consulta via MCP β†’ "ΒΏHay guidelines para auth?" + ↓ + Kogral responde con contexto del proyecto + ↓ + CΓ³digo generado sigue convenciones del equipo +``` + +**Para quiΓ©n**: + +- Equipos que pierden conocimiento cuando rotan miembros +- Organizaciones con multiple proyectos que necesitan guidelines consistentes +- Desarrolladores usando Claude Code que quieren contexto del proyecto + +**Resultados esperados**: + +- Onboarding de nuevos miembros en dΓ­as, no semanas +- CΓ³digo generado por IA que respeta convenciones +- Decisiones arquitectΓ³nicas preservadas y buscables + +--- + +## TypeDialog: Una DefiniciΓ³n, Seis Interfaces + +### Formularios que Funcionan en Todas Partes + +Define un formulario una vez en TOML. EjecΓΊtalo en CLI, TUI, Web, o deja que un agente IA lo complete. + +**Backends disponibles**: + +| Backend | Uso tΓ­pico | +| --------- | ----------- | +| **CLI** | Scripts de automatizaciΓ³n, CI/CD | +| **TUI** | Herramientas de administraciΓ³n, dashboards terminal | +| **Web** | Aplicaciones SaaS, formularios pΓΊblicos | +| **AI** | BΓΊsqueda semΓ‘ntica, RAG sobre documentaciΓ³n | +| **Agent** | EjecuciΓ³n de agentes desde archivos .agent.mdx | +| **Prov-gen** | GeneraciΓ³n de infraestructura multi-cloud | + +**El flujo**: + +```text +employee_onboarding.toml + ↓ + TypeDialog + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β” +CLI TUI Web Agent +β”‚ β”‚ β”‚ β”‚ +β–Ό β–Ό β–Ό β–Ό +Mismo resultado validado con Nickel contracts + +``` + +**Para quiΓ©n**: + +- Equipos que mantienen la misma lΓ³gica en CLI y Web +- DevOps que necesitan wizards de configuraciΓ³n +- Organizaciones con formularios multi-idioma + +**Resultados esperados**: + +- Una sola definiciΓ³n para todas las interfaces +- ValidaciΓ³n tipada antes de runtime +- Formularios que ejecutan agentes LLM directamente + +--- + +## Provisioning: Infraestructura con IA + +### IaC Declarativo + GeneraciΓ³n Asistida + +Provisioning combina la precisiΓ³n de configuraciΓ³n tipada (Nickel) con asistencia IA para generar y validar infraestructura. + +**Capacidades ΓΊnicas**: + +- **Nickel IaC**: ConfiguraciΓ³n tipada con lazy evaluation, no YAML +- **MCP Server**: Consultas en lenguaje natural sobre infraestructura +- **RAG integrado**: 1,200+ documentos de dominio para respuestas contextuales +- **Multi-cloud**: AWS, UpCloud, local desde la misma definiciΓ³n + +**Seguridad enterprise**: + +- JWT + MFA (TOTP + WebAuthn) +- Cedar policy engine para RBAC +- 7 aΓ±os retenciΓ³n de audit logs +- 5 backends KMS (RustyVault, Age, AWS KMS, Vault, Cosmian) + +**El flujo**: +```text +"Necesito un cluster K8s en AWS con 3 nodos" + ↓ + MCP Server (NLP) + ↓ + RAG busca configuraciones similares + ↓ + Genera Nickel + valida tipos + ↓ + Orchestrator despliega con rollback +``` + +**Para quiΓ©n**: + +- Equipos DevOps que quieren IaC tipado, no YAML frΓ‘gil +- Organizaciones multi-cloud (AWS + otros) +- Equipos que necesitan audit y compliance + +**Resultados esperados**: + +- Errores de configuraciΓ³n detectados en compilaciΓ³n, no en runtime +- Infraestructura generada desde lenguaje natural +- Rollback automΓ‘tico ante fallos + +--- + +## SECRETUMVAULT: Secretos con CriptografΓ­a Post-CuΓ‘ntica + +### El Primer Vault Rust con PQC en ProducciΓ³n + +SecretumVault es un sistema de gestiΓ³n de secretos que implementa **criptografΓ­a post-cuΓ‘ntica lista para producciΓ³n** (ML-KEM-768, ML-DSA-65). + +**CriptografΓ­a agnΓ³stica**: + +- **OpenSSL**: RSA, ECDSA, AES-256-GCM (compatibilidad clΓ‘sica) +- **OQS (Post-Quantum)**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) +- **Backends conectables**: Cambia algoritmos sin modificar cΓ³digo + +**Motores de secretos**: + +| Motor | Capacidad | +| ------- | ----------- | +| **KV** | Almacenamiento versionado de secretos | +| **Transit** | Encryption-as-a-service con rotaciΓ³n de claves | +| **PKI** | GeneraciΓ³n de certificados X.509 | +| **Database** | Credenciales dinΓ‘micas con TTL | + +**Storage multi-backend**: + +- Filesystem (desarrollo, single-node) +- etcd (Kubernetes, alta disponibilidad) +- SurrealDB (queries complejas, time-series) +- PostgreSQL (enterprise, ACID) + +**Seguridad enterprise**: + +- Shamir Secret Sharing para unsealing +- Cedar policy engine (ABAC) +- TLS/mTLS nativo +- Audit logging completo + +**Para quiΓ©n**: + +- Equipos desplegando criptografΓ­a post-cuΓ‘ntica hoy +- Organizaciones con requisitos de agilidad criptogrΓ‘fica +- Plataformas multi-cloud que necesitan gestiΓ³n de secretos Rust-native + +**Resultados esperados**: + +- PreparaciΓ³n para amenazas cuΓ‘nticas sin cambiar arquitectura +- GestiΓ³n de secretos con garantΓ­as de memoria de Rust +- IntegraciΓ³n nativa con el ecosistema (Provisioning, Vapora) + +--- + +## El Ecosistema en AcciΓ³n + +### Escenario: Nuevo Feature con IA + +```text +1. Kogral proporciona guidelines y patterns a Claude Code via MCP +2. Vapora coordina agentes: Architect diseΓ±a β†’ Developer implementa β†’ Reviewer valida +3. TypeDialog captura configuraciones necesarias con validaciΓ³n Nickel +4. SecretumVault gestiona credenciales y secretos del feature +5. Kogral registra decisiones tomadas durante el desarrollo +6. Provisioning despliega cambios de infraestructura requeridos +``` + +### Escenario: Onboarding de Nuevo Desarrollador + +```text +1. Kogral exporta knowledge graph del proyecto +2. TypeDialog presenta quiz interactivo sobre arquitectura +3. Vapora asigna tareas de onboarding progresivas +4. Provisioning configura entorno de desarrollo automΓ‘ticamente +``` + +### Escenario: MigraciΓ³n Multi-Cloud + +```text +1. Kogral documenta ADRs de la migraciΓ³n +2. TypeDialog valida parΓ‘metros de configuraciΓ³n +3. Provisioning ejecuta migraciΓ³n con checkpoints +4. Vapora orquesta agentes para monitoreo y reportes +``` + +--- + +## Por QuΓ© Elegir Este Ecosistema + +### Frente a Alternativas + +| Nosotros | Alternativas | +| ---------- | -------------- | +| **Rust nativo**: Rendimiento, sin GC, type-safe | Python: GIL, typing opcional | +| **Nickel configs**: ValidaciΓ³n pre-runtime | YAML/JSON: Errores en runtime | +| **Aprendizaje de ejecuciones**: Agentes mejoran | LangChain: Chains estΓ‘ticos | +| **MCP integrado**: Contexto para Claude Code | Sin integraciΓ³n nativa | +| **Budget control**: Fallback automΓ‘tico | Control manual de costos | +| **Multi-tenant nativo**: SurrealDB scopes | Aislamiento manual | + +### InversiΓ³n TΓ©cnica + +| MΓ©trica | Valor | +| --------- | ------- | +| Crates Rust | 40+ | +| Tests | 4,360+ | +| LΓ­neas de cΓ³digo | ~206K | +| Proveedores LLM | Claude, OpenAI, Gemini, Ollama | +| MCP Tools | 14+ | +| Backends crypto | OpenSSL, OQS (PQC), AWS-LC | + +--- + +## Comenzar + +### AdopciΓ³n Progresiva Recomendada + +1. **Kogral**: Establece base de conocimiento (standalone, sin dependencias) +2. **TypeDialog**: Habilita inputs estructurados y validaciΓ³n +3. **SecretumVault**: GestiΓ³n de secretos con criptografΓ­a moderna +4. **Vapora**: Orquesta agentes con contexto de Kogral +5. **Provisioning**: Infraestructura informada por el ecosistema + +Cada proyecto funciona de forma independiente. Las sinergias emergen al combinarlos. + +--- + +## Contacto + +- **Repositorios**: GitHub (proyectos privados) +- **Stack**: Rust, Nickel, SurrealDB, Axum, Leptos +- **Licencia**: Propietaria / Por definir + +--- + +*El desarrollo asistido por IA no deberΓ­a requerir 10 herramientas desconectadas.* +*Un ecosistema. Cinco proyectos. IntegraciΓ³n real.* diff --git a/docs/es/ops/README.md b/docs/es/ops/README.md new file mode 100644 index 0000000..4ddd7a2 --- /dev/null +++ b/docs/es/ops/README.md @@ -0,0 +1,37 @@ +# DocumentaciΓ³n Portfolio Operaciones + +DocumentaciΓ³n de las herramientas de automatizaciΓ³n de infraestructura y despliegue de STRATUM. + +## Proyectos + +### Provisioning + +Infraestructura como cΓ³digo multi-nube. + +- Definiciones declarativas de infraestructura +- Soporte multi-nube (AWS, Azure, GCP, bare metal) +- IntegraciΓ³n con flujos GitOps +- GestiΓ³n de estado y detecciΓ³n de drift +- Rollback y validaciΓ³n + +### SecretumVault + +GestiΓ³n segura de secretos. + +- Almacenamiento multi-tenant de secretos +- Control de acceso granular +- Logging de auditorΓ­a y cumplimiento +- IntegraciΓ³n con pipelines CI/CD +- EncriptaciΓ³n en reposo y en trΓ‘nsito + +## Archivos de DocumentaciΓ³n + +- [**ops-stratumiops-projects.md**](ops-stratumiops-projects.md) - VisiΓ³n general completa de proyectos del portfolio ops +- [**ops-stratumiops-projects-positioning.md**](ops-stratumiops-projects-positioning.md) - Posicionamiento de mercado y anΓ‘lisis competitivo +- [**ops-stratumiops-projects-technical-specs.md**](ops-stratumiops-projects-technical-specs.md) - Especificaciones tΓ©cnicas, documentaciΓ³n de API y arquitectura + +## NavegaciΓ³n + +- [Volver a docs en espaΓ±ol](../) +- [Volver a documentaciΓ³n raΓ­z](../../) +- [Portfolio IA](../ia/) diff --git a/docs/es/ops/ops-stratumiops-projects-positioning.md b/docs/es/ops/ops-stratumiops-projects-positioning.md new file mode 100644 index 0000000..ba67c9b --- /dev/null +++ b/docs/es/ops/ops-stratumiops-projects-positioning.md @@ -0,0 +1,623 @@ +# Portfolio Ops/DevOps: Posicionamiento EstratΓ©gico + +## Resumen Ejecutivo + +Este documento analiza el portfolio de cinco proyectos desde la perspectiva Ops/DevOps, posicionΓ‘ndolos frente a herramientas establecidas del mercado: + +| Proyecto | Dominio | Compite Con | +| ---------- | --------- | ------------- | +| **Provisioning** | IaC + OrquestaciΓ³n | Terraform, Pulumi, Ansible, CloudFormation | +| **SecretumVault** | GestiΓ³n de Secretos | HashiCorp Vault, AWS Secrets Manager, Azure Key Vault | +| **Vapora** | OrquestaciΓ³n de Agentes | Jenkins, GitHub Actions, Tekton, ArgoCD | +| **TypeDialog** | ConfiguraciΓ³n + IaC Gen | Terraform modules, Cookiecutter, Yeoman | +| **Kogral** | Knowledge Management | Confluence, Notion, Internal wikis | + +--- + +## 1. Matriz de Funcionalidades Ops + +### Capacidades por Proyecto + +| Capacidad | Provisioning | SecretumVault | Vapora | TypeDialog | Kogral | +| ----------- | -------------- | --------------- | -------- | ------------ | -------- | +| **Multi-cloud** | AWS, UpCloud, Local | N/A (storage agnostic) | N/A | SΓ­ (prov-gen) | N/A | +| **IaC declarativo** | Nickel (tipado) | N/A | N/A | Genera Nickel | N/A | +| **Secrets management** | Integra KMS | βœ… 4 engines | Usa vault | N/A | N/A | +| **OrquestaciΓ³n** | Rust orchestrator | N/A | NATS JetStream | N/A | N/A | +| **Post-Quantum Crypto** | Via SecretumVault | βœ… ML-KEM/ML-DSA | N/A | N/A | N/A | +| **Rollback automΓ‘tico** | βœ… Checkpoints | N/A | Pipeline rollback | N/A | N/A | +| **Policy engine** | Cedar RBAC/ABAC | Cedar ABAC | Cedar multi-tenant | N/A | N/A | +| **Audit logging** | 7 aΓ±os retenciΓ³n | βœ… Completo | βœ… SurrealDB | N/A | Git history | +| **IA-assisted** | MCP + RAG | N/A | LLM routing | Agent backend | MCP search | +| **API REST** | Axum control-center | Axum vault API | Axum backend | Axum web backend | N/A (MCP) | +| **Storage backends** | SurrealDB | FS/etcd/SurrealDB/PostgreSQL | SurrealDB + NATS | Multi-formato | FS + SurrealDB | +| **CLI** | 80+ shortcuts | svault CLI | vapora CLI | typedialog CLI | kogral CLI | + +### Stack TecnolΓ³gico ComΓΊn (Ops Perspective) + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TECNOLOGÍAS COMPARTIDAS β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Lenguaje: Rust (performance, memory-safety) β”‚ +β”‚ Config: Nickel (validaciΓ³n pre-runtime, lazy eval) β”‚ +β”‚ DB: SurrealDB (multi-modelo, scopes, time-series) β”‚ +β”‚ Web: Axum (async, composable routing) β”‚ +β”‚ Messaging: NATS JetStream (at-least-once, persistence) β”‚ +β”‚ Policy: Cedar (ABAC, AWS-compatible) β”‚ +β”‚ Crypto: OpenSSL, OQS (PQC), AWS-LC, RustCrypto β”‚ +β”‚ Logging: tracing (structured, JSON output) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Posicionamiento vs Competencia (Ops Tools) + +### Provisioning vs Terraform + +| Aspecto | Provisioning | Terraform | +| --------- | -------------- | ----------- | +| **Lenguaje IaC** | Nickel (tipado, lazy) | HCL (sin tipos) | +| **ValidaciΓ³n** | Pre-runtime (compilaciΓ³n) | Runtime (terraform plan) | +| **Multi-cloud** | AWS, UpCloud, Local | SΓ­ (100+ providers) | +| **IA nativa** | MCP + RAG (1000x Python) | Terraform Cloud AI (limitado) | +| **OrquestaciΓ³n** | Rust orchestrator hΓ­brido | State file + lock | +| **Rollback** | AutomΓ‘tico con checkpoints | Manual (terraform destroy) | +| **Seguridad** | 39K lΓ­neas (12 componentes) | Vault plugin, externos | +| **Ecosystem** | ⚠️ PequeΓ±o | βœ… Enorme (Terraform Registry) | +| **Learning curve** | Alta (Nickel + Nushell) | Moderada (HCL familiar) | +| **Best For** | Equipos Rust, IaC tipado, IA-assisted | General use, large ecosystem | + +**Diferenciador clave**: Provisioning combina IaC declarativo tipado (Nickel) con generaciΓ³n asistida por IA (MCP + RAG) y orquestaciΓ³n hΓ­brida Rust/Nushell, eliminando errores de configuraciΓ³n en compilaciΓ³n. + +### Provisioning vs Pulumi + +| Aspecto | Provisioning | Pulumi | +| --------- | -------------- | -------- | +| **Lenguaje IaC** | Nickel (functional) | TypeScript/Python/Go | +| **Paradigma** | Declarativo | Imperativo (cΓ³digo) | +| **State management** | SurrealDB multi-modelo | Pulumi Cloud / self-hosted | +| **Secrets** | SecretumVault integrado | Pulumi ESC (SaaS) | +| **Multi-cloud** | AWS, UpCloud, Local | SΓ­ (100+ providers) | +| **IA-assisted** | MCP + RAG nativo | Pulumi AI (experimental) | +| **Testing** | Nickel contracts | Unit tests en cΓ³digo | +| **Best For** | Declarativo puro, IaC tipado | Developers, cΓ³digo imperativo | + +**Diferenciador clave**: Provisioning es declarativo puro (Nickel) vs imperativo (Pulumi cΓ³digo), con validaciΓ³n pre-runtime y orquestador Rust para workflows complejos. + +### Provisioning vs Ansible + +| Aspecto | Provisioning | Ansible | +| --------- | -------------- | --------- | +| **Paradigma** | Declarativo (Nickel IaC) | Imperatativo (playbooks) | +| **Agentless** | SΓ­ (SSH) | SΓ­ (SSH) | +| **Idempotencia** | Nickel contracts | YAML tasks (depende mΓ³dulo) | +| **Performance** | Rust orchestrator (10-50x) | Python interpreter | +| **Multi-cloud** | AWS, UpCloud, Local | SΓ­ (mΓ³dulos cloud) | +| **Dependency resolution** | Topological sort automΓ‘tico | Manual (pre_tasks, post_tasks) | +| **Rollback** | AutomΓ‘tico con checkpoints | Manual (rescue blocks) | +| **Best For** | IaC tipado, performance crΓ­tica | Configuration management, ad-hoc | + +**Diferenciador clave**: Provisioning es IaC declarativo (no playbooks imperativos) con orquestador Rust 10-50x mΓ‘s rΓ‘pido que Python, rollback automΓ‘tico y resoluciΓ³n de dependencias topolΓ³gica. + +### SecretumVault vs HashiCorp Vault + +| Aspecto | SecretumVault | HashiCorp Vault | +| --------- | --------------- | ----------------- | +| **Lenguaje** | Rust (memory-safe) | Go (CGO overhead) | +| **Post-Quantum** | βœ… **ML-KEM-768, ML-DSA-65** | ❌ Sin roadmap | +| **Crypto backends** | 4 (OpenSSL, **OQS**, AWS-LC, RustCrypto) | 1 (OpenSSL) | +| **Storage backends** | 4 (FS, etcd, SurrealDB, PostgreSQL) | 10+ (etcd, Consul, S3, etc) | +| **Policy engine** | Cedar ABAC (AWS-compatible) | HCL policies | +| **Shamir unsealing** | βœ… Nativo | βœ… Nativo | +| **Secrets engines** | 4 (KV, Transit, PKI, Database) | 10+ (incluye cloud-specific) | +| **Ecosystem** | ⚠️ PequeΓ±o | βœ… Enorme (plugins, integrations) | +| **Licencia** | Apache-2.0 | BSL (Enterprise paywall) | +| **Best For** | **PQC hoy**, Rust stacks, data sovereignty | General use, mature ecosystem | + +**Diferenciador clave**: SecretumVault es el **ΓΊnico vault Rust con criptografΓ­a post-cuΓ‘ntica lista para producciΓ³n** (ML-KEM-768, ML-DSA-65 NIST FIPS 203/204), proporcionando agilidad criptogrΓ‘fica para organizaciones que despliegan hoy. + +### SecretumVault vs AWS Secrets Manager + +| Aspecto | SecretumVault | AWS Secrets Manager | +| --------- | --------------- | --------------------- | +| **Multi-cloud** | βœ… Cualquier cloud o on-premise | ❌ AWS-only | +| **Self-hosted** | βœ… Full control | ❌ SaaS only | +| **Post-Quantum** | βœ… **ML-KEM + ML-DSA** | ❌ None | +| **Crypto backends** | 4 conectables | 1 (AWS KMS) | +| **Dynamic secrets** | βœ… Database engine | βœ… RDS integration | +| **Vendor lock-in** | βœ… Portable | ⚠️ High (AWS-specific) | +| **Cost** | Self-hosted (infra cost) | $0.40/secret/month + API calls | +| **Best For** | Multi-cloud, **PQC**, data sovereignty | AWS-native apps, managed service | + +**Diferenciador clave**: SecretumVault es multi-cloud y self-hosted con PQC nativo, vs AWS Secrets Manager cloud-only sin roadmap post-quantum. + +### Vapora vs Jenkins + +| Aspecto | Vapora | Jenkins | +| --------- | -------- | --------- | +| **Paradigma** | Agent orchestration (IA) | Pipeline orchestration (CI/CD) | +| **Agentes** | LLM-powered (Claude, GPT, Gemini) | Build agents (workers) | +| **OrquestaciΓ³n** | NATS JetStream | Master-worker | +| **Learning** | Expertise profiles, recency bias | No (estΓ‘tico) | +| **Budget control** | Per-role limits, fallback | No aplica | +| **Pipeline definition** | Tasks + agent roles | Jenkinsfile (Groovy) | +| **UI** | Leptos WASM (Kanban) | Web UI (Java) | +| **Best For** | IA-assisted operations, LLM orchestration | Traditional CI/CD, build automation | + +**Diferenciador clave**: Vapora orquesta agentes **LLM inteligentes** con aprendizaje y control de costos, no build agents tradicionales. + +### Vapora vs GitHub Actions + +| Aspecto | Vapora | GitHub Actions | +| --------- | -------- | ---------------- | +| **Self-hosted** | βœ… Kubernetes native | βœ… Self-hosted runners | +| **Agentes** | LLM-powered con roles | Workflow runners | +| **OrquestaciΓ³n** | NATS JetStream | GitHub infrastructure | +| **Learning** | Expertise profiles | No (estΓ‘tico) | +| **Budget control** | LLM cost limits | Minutes-based billing | +| **Multi-tenant** | SurrealDB scopes + Cedar | Repository-level | +| **Best For** | IA operations, agent coordination | GitHub-native CI/CD, simple workflows | + +**Diferenciador clave**: Vapora es una plataforma de orquestaciΓ³n de agentes IA con aprendizaje, no un runner de workflows CI/CD. + +### TypeDialog (prov-gen) vs Terraform Modules + +| Aspecto | TypeDialog (prov-gen) | Terraform Modules | +| --------- | ---------------------- | ------------------- | +| **Input method** | Formularios TOML (CLI/TUI/Web) | Variables (.tfvars) | +| **Validation** | Nickel contracts (pre-runtime) | Variable validation (runtime) | +| **Output format** | Nickel IaC | HCL | +| **Multi-backend** | 6 (CLI/TUI/Web/AI/Agent/Prov-gen) | CLI only | +| **IaC generation** | Templates Tera + validation | Module composition | +| **Best For** | Wizards interactivos, self-service | Reusable modules, Terraform ecosystem | + +**Diferenciador clave**: TypeDialog unifica captura de inputs (CLI/TUI/Web) con generaciΓ³n de IaC validado (Nickel), no solo modules reutilizables. + +### Kogral vs Confluence + +| Aspecto | Kogral | Confluence | +| --------- | -------- | ------------ | +| **Target** | Equipos desarrollo/ops | Equipos generales | +| **Git-native** | βœ… Markdown + YAML frontmatter | ❌ Cloud/Server | +| **Tipos de nodo** | 6 especializados (ADR, Pattern, etc) | Pages genΓ©ricas | +| **MCP Server** | βœ… Claude Code native | ❌ No | +| **BΓΊsqueda semΓ‘ntica** | fastembed + cloud embeddings | Search interno | +| **Self-hosted** | βœ… Filesystem + SurrealDB | Cloud o Data Center | +| **Best For** | Dev/Ops knowledge, IA integration | General documentation, wikis | + +**Diferenciador clave**: Kogral estΓ‘ diseΓ±ado especΓ­ficamente para conocimiento tΓ©cnico (runbooks, ADRs, postmortems) con integraciΓ³n IA nativa vΓ­a MCP. + +--- + +## 3. Casos de Uso y Contexto (Ops Perspective) + +### CuΓ‘ndo Usar Cada Proyecto + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ "Necesito provisionar infraestructura multi-cloud con IaC" β”‚ +β”‚ β†’ Provisioning (Nickel IaC, multi-cloud, orchestrator) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Quiero gestiΓ³n de secretos con preparaciΓ³n post-cuΓ‘ntica" β”‚ +β”‚ β†’ SecretumVault (PQC ML-KEM/ML-DSA, 4 backends crypto) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Necesito orquestar agentes IA para tareas operativas" β”‚ +β”‚ β†’ Vapora (DevOps/Monitor/Security agents, NATS, budget) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Quiero wizards de configuraciΓ³n que generen IaC" β”‚ +β”‚ β†’ TypeDialog (prov-gen backend, CLI/TUI/Web) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ "Necesito preservar runbooks y postmortems de incidentes" β”‚ +β”‚ β†’ Kogral (6 node types, MCP, git-native) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Matriz de DecisiΓ³n por Contexto Ops + +| Contexto | Proyecto Principal | Proyectos de Soporte | +| ---------- | ------------------- | ---------------------- | +| **ProvisiΓ³n multi-cloud** | Provisioning | TypeDialog (wizards), SecretumVault (certs), Kogral (ADRs) | +| **GestiΓ³n de secretos PQC** | SecretumVault | Provisioning (infraestructura), Kogral (policies) | +| **Incident response** | Vapora (Monitor/DevOps agents) | Kogral (runbooks/postmortems), SecretumVault (credentials) | +| **CI/CD automation** | Vapora (DevOps agent) | Provisioning (deploy), SecretumVault (secrets), Kogral (guidelines) | +| **Infrastructure self-service** | TypeDialog (prov-gen) | Provisioning (apply IaC), Kogral (docs) | +| **Knowledge preservation** | Kogral | Vapora (execution tracking), TypeDialog (export) | +| **Disaster recovery** | Provisioning (rollback) | SecretumVault (backup), Kogral (procedures) | + +--- + +## 4. Por QuΓ© Son Necesarios (Ops Perspective) + +### Problemas que Resuelven + +#### Provisioning: El Problema del YAML FrΓ‘gil + +``` +ANTES DESPUΓ‰S (Provisioning) +───────────────────────────────── ───────────────────────────────── +YAML sin tipos, errores runtime Nickel tipado, errores compilaciΓ³n +Scripts imperativos frΓ‘giles Workflows declarativos con rollback +Terraform state drift SurrealDB con time-series +Sin asistencia IA MCP + RAG (1000x Python) +Manual dependency management Topological sort automΓ‘tico +``` + +#### SecretumVault: El Problema de la CriptografΓ­a CuΓ‘ntica + +``` +ANTES DESPUΓ‰S (SecretumVault) +───────────────────────────────── ───────────────────────────────── +Vault en Go (sin memory-safety) Rust con garantΓ­as de memoria +Solo crypto clΓ‘sica (vulnerable) Post-quantum (ML-KEM, ML-DSA) +Backend crypto fijo Backends conectables (agilidad) +SaaS lock-in (AWS, Azure) Self-hosted completo +Sin preparaciΓ³n amenazas cuΓ‘nticas Despliega PQC hoy, migra gradual +``` + +#### Vapora: El Problema de la CoordinaciΓ³n Ops Manual + +``` +ANTES DESPUΓ‰S (Vapora) +───────────────────────────────── ───────────────────────────────── +Scripts ad-hoc sin coordinaciΓ³n NATS JetStream orchestration +LLMs sin control de costos Budget enforcement + fallback +Agentes sin contexto histΓ³rico Expertise profiles + recency bias +Manual handoffs (deploy β†’ monitor) Pipelines automatizados con roles +Sin visibilidad de ejecuciones Prometheus metrics + SurrealDB +``` + +#### TypeDialog (prov-gen): El Problema de ConfiguraciΓ³n Manual + +``` +ANTES DESPUΓ‰S (TypeDialog) +───────────────────────────────── ───────────────────────────────── +ConfiguraciΓ³n manual error-prone Formularios validados (Nickel) +CLI β‰  Web β‰  TUI interfaces 1 TOML β†’ 6 backends +Sin generaciΓ³n de IaC prov-gen β†’ Nickel multi-cloud +ValidaciΓ³n en runtime ValidaciΓ³n pre-runtime (contracts) +``` + +#### Kogral: El Problema del Conocimiento Ops Perdido + +``` +ANTES DESPUΓ‰S (Kogral) +───────────────────────────────── ───────────────────────────────── +Runbooks en Confluence dispersos Git-native, versionados +Postmortems no buscables Semantic search + MCP +ADRs de infra perdidos Decision nodes con relaciones +Incidentes sin contexto histΓ³rico Execution nodes con timeline +Onboarding de SREs semanas BΓΊsqueda semΓ‘ntica dΓ­as +``` + +--- + +## 5. QuΓ© los Hace Diferentes (Ops Perspective) + +### CaracterΓ­sticas Únicas por Proyecto + +#### Provisioning + +1. **Nickel IaC**: Único con language tipado lazy-eval como primary (no HCL, no YAML) +2. **Orquestador hΓ­brido**: Rust (performance) + Nushell (flexibilidad) +3. **MCP 1000x faster**: Rust-native vs Python implementations +4. **39K lΓ­neas seguridad**: 12 componentes enterprise (JWT, Cedar, MFA, audit, KMS) +5. **80+ CLI shortcuts**: Developer experience optimizada con guided wizards + +#### SecretumVault + +1. **Post-Quantum nativo**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) **listos para producciΓ³n hoy** +2. **4 backends crypto**: OpenSSL, **OQS**, AWS-LC, RustCrypto (agilidad criptogrΓ‘fica sin cambiar cΓ³digo) +3. **4 backends storage**: Filesystem, etcd, SurrealDB, PostgreSQL (flexibilidad deployment) +4. **Shamir Secret Sharing**: Unsealing distribuido con threshold configurable (3-of-5, 5-of-7, etc) +5. **Cedar ABAC**: PolΓ­ticas de autorizaciΓ³n AWS-compatible (portable, no vendor lock-in) + +#### Vapora + +1. **Learning-based selection**: Scoring `0.3*load + 0.5*expertise + 0.2*confidence` con 3x recency bias (ΓΊltimos 7 dΓ­as) +2. **Budget enforcement**: Hard caps per-role (monthly/weekly) con fallback automΓ‘tico a proveedores mΓ‘s baratos +3. **NATS JetStream**: CoordinaciΓ³n at-least-once, message persistence, distributed +4. **12 agent roles**: Architect, Developer, CodeReviewer, Tester, Documenter, Marketer, Presenter, **DevOps**, **Monitor**, **Security**, ProjectManager, DecisionMaker +5. **Multi-tenant nativo**: SurrealDB scopes + Cedar RBAC, completo aislamiento + +#### TypeDialog + +1. **6 backends unificados**: CLI/TUI/Web/AI/Agent/**Prov-gen** desde mismo TOML +2. **Prov-gen IaC generation**: AWS/GCP/Azure/Hetzner/UpCloud desde formularios tipados +3. **Nickel contracts**: ValidaciΓ³n pre-runtime con type-safe schemas +4. **3,818 tests**: Cobertura exhaustiva (503% growth), producciΓ³n-ready +5. **Multi-idioma nativo**: Fluent bundles para i18n sin reimplementar lΓ³gica + +#### Kogral + +1. **6 tipos de nodo especializados**: Note, Decision (ADR), Guideline, Pattern, Journal, **Execution** (para ops/incidents) +2. **Hybrid embeddings**: fastembed local (privacidad) + cloud (producciΓ³n) +3. **MCP nativo**: 7 tools para Claude Code, no requiere configuraciΓ³n extra +4. **Git-native**: Todo markdown versionado, no SaaS externo, full control +5. **Herencia de guidelines**: Org β†’ Proyecto con prioridad, consistency cross-team + +--- + +## 6. Sinergias y ReutilizaciΓ³n (Ops Workflows) + +### Flujo de IntegraciΓ³n Ops + +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Runbooks, ADRs) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ Operational knowledge + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TypeDialog │───▢│ Vapora │───▢│ Provisioning β”‚ +β”‚ (Wizards) β”‚ β”‚ (Ops Agents) β”‚ β”‚ (IaC Deploy) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ Configuration β”‚ Orchestration β”‚ Infrastructure + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SECRETUMVAULT β”‚ +β”‚ PKI certs β”‚ Dynamic DB creds β”‚ API keys β”‚ Encryption β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Componentes Reutilizables (Ops Stack) + +| Componente | Origen | Reutilizado En | +| ------------ | -------- | ---------------- | +| **SurrealDB schemas** | Vapora | Kogral, Provisioning, SecretumVault (optional) | +| **Nickel contracts** | Provisioning | TypeDialog (prov-gen validation) | +| **Cedar policies** | Provisioning | SecretumVault, Vapora (multi-tenant) | +| **Axum API patterns** | Vapora | Provisioning (control-center), SecretumVault (vault API) | +| **tracing setup** | Vapora | Todos (structured logging) | +| **Crypto backends** | SecretumVault | Provisioning (KMS integration) | +| **NATS patterns** | Vapora | Provisioning (future messaging), SecretumVault (HA) | + +### Escenarios de Sinergia (Ops Workflows) + +#### Escenario 1: Zero-Touch Provisioning con IA + +``` +1. TypeDialog (prov-gen): SRE completa wizard web + - Cloud provider, regiΓ³n, cluster size, services + - Genera Nickel IaC validado con contracts + +2. Kogral: MCP proporciona guidelines de deployment + - "ΒΏCuΓ‘l es nuestra polΓ­tica de naming para clusters?" + - "ΒΏQuΓ© security groups aplicamos por defecto?" + +3. Provisioning: Orquestador despliega infraestructura + - Servidores β†’ networking β†’ storage β†’ services + - Checkpoints por paso, rollback automΓ‘tico si falla + +4. SecretumVault: Genera certificados y secretos + - PKI engine: certs etcd, kube-apiserver, kubelet (ML-DSA-65 PQC) + - Database engine: credenciales dinΓ‘micas PostgreSQL (TTL 1h) + +5. Vapora: Post-deployment automation + - Monitor Agent: Setup Prometheus alerts, health checks + - Security Agent: Vulnerability scan, compliance check + - DevOps Agent: Deploy baseline apps (Ingress, cert-manager) + +6. Kogral: Documenta deployment + - Execution node con timestamp, recursos creados, configuraciΓ³n + - Links a ADRs de arquitectura, runbooks de mantenimiento +``` + +#### Escenario 2: Incident Response Automatizado + +``` +1. Vapora Monitor Agent: Detecta anomalΓ­a (PostgreSQL down) + - Alerta vΓ­a NATS JetStream + - Trigger incident response pipeline + +2. Kogral: Claude Code consulta runbooks vΓ­a MCP + - search("postgresql outage troubleshooting") + - Retorna 3 postmortems similares con resoluciones + +3. Vapora DevOps Agent: Ejecuta runbook automatizado + - Verificar proceso PostgreSQL (systemctl status) + - Check logs (/var/log/postgresql) + - Restart si necesario con parΓ‘metros ajustados + +4. SecretumVault: Rota credenciales comprometidas + - Database engine genera nuevas credenciales dinΓ‘micas + - Actualiza apps conectadas vΓ­a secret injection + +5. Vapora Security Agent: Post-incident audit + - Review logs de acceso, cambios de configuraciΓ³n + - Genera reporte de compliance + +6. Kogral: Documenta postmortem + - Execution node con root cause, timeline, resoluciΓ³n + - Links a ADRs de configuraciΓ³n PostgreSQL + - Action items para prevenir recurrencia +``` + +#### Escenario 3: MigraciΓ³n Post-Quantum Gradual + +``` +1. Kogral: Documenta decisiΓ³n estratΓ©gica + - ADR: "MigraciΓ³n gradual a criptografΓ­a post-cuΓ‘ntica" + - Rationale: PreparaciΓ³n para amenazas cuΓ‘nticas (harvest now, decrypt later) + - Timeline: Q1 2026 testing, Q2 2026 staging, Q3 2026 production + +2. SecretumVault: Migra secretos en staging + - Backend switch: openssl β†’ oqs (ML-KEM-768) + - Re-encripta secretos existentes con PQC + - Dual-stack: classical para legacy, PQC para nuevos servicios + +3. Provisioning: Actualiza infraestructura PKI + - Genera nuevos certificados con ML-DSA-65 (PQC signatures) + - Deploy certificados a servicios (etcd, K8s API, service mesh) + - Health checks: latency no degradada, handshakes correctos + +4. Vapora: Orquesta validaciΓ³n integral + - Security Agent: Verifica algoritmos criptogrΓ‘ficos correctos + - Monitor Agent: Benchmark latency (PQC vs classical) + - DevOps Agent: Integration tests con certificados PQC + +5. TypeDialog: Portal self-service para teams + - Formulario: "Migrar servicio a PQC" + - Input: service name, migration strategy (gradual/immediate) + - prov-gen: Genera configuraciΓ³n actualizada (Nickel) + +6. Kogral: Tracking de migraciΓ³n + - Execution nodes por servicio migrado + - MΓ©tricas: services migrated, performance impact, issues + - Lessons learned: quΓ© funcionΓ³, quΓ© mejorar +``` + +#### Escenario 4: Multi-Cloud Disaster Recovery + +``` +1. Kogral: Runbook de disaster recovery + - Procedure: "Failover de AWS a UpCloud en <1h" + - Prerequisites, pasos detallados, validaciΓ³n + +2. Vapora: Trigger automΓ‘tico (regiΓ³n AWS down) + - Monitor Agent detecta outage regional + - ProjectManager Agent declara disaster recovery mode + - DevOps Agent ejecuta runbook Kogral + +3. Provisioning: Despliega rΓ©plica en UpCloud + - Nickel IaC multi-cloud (cambio: provider = "upcloud") + - Orquestador despliega: servers β†’ networking β†’ K8s β†’ apps + - Checkpoints: rollback a AWS si UpCloud falla tambiΓ©n + +4. SecretumVault: Sincroniza secretos + - ReplicaciΓ³n etcd cross-region (AWS β†’ UpCloud) + - PKI engine genera certificados para UpCloud region + - Database engine: credenciales dinΓ‘micas nueva DB + +5. TypeDialog: Wizard de DNS failover + - Formulario: Update DNS records (Route53 β†’ NS1) + - ValidaciΓ³n: TTL check, propagation time + +6. Kogral: Documenta incident + - Execution node: timeline, decisiones, mΓ©tricas + - RTO achieved, RPO achieved, issues encountered + - Postmortem: quΓ© mejorar en runbook +``` + +--- + +## 7. Dependencias y Orden de AdopciΓ³n (Ops Teams) + +### Grafo de Dependencias + +``` + SecretumVault (standalone) + β”‚ + β”‚ provides secrets to + β–Ό +Kogral ◄────────────────────────► Provisioning +(standalone) (puede integrar vault) + β”‚ β”‚ + β”‚ provides runbooks to β”‚ deploys infrastructure for + β–Ό β–Ό + Vapora + (integra todos) + β”‚ + β”‚ uses wizards from + β–Ό + TypeDialog + (prov-gen β†’ Provisioning) +``` + +### Orden Recomendado de AdopciΓ³n (Ops Perspective) + +| Fase | Proyecto | RazΓ³n | Dependencias | +| ------ | ---------- | ------- | -------------- | +| 1 | **SecretumVault** | GestiΓ³n de secretos crΓ­tica, sin dependencias | Ninguna (standalone) | +| 2 | **Kogral** | Base de conocimiento operativo (runbooks, ADRs) | Ninguna (standalone) | +| 3 | **Provisioning** | IaC declarativo, puede integrar SecretumVault (opcional) | Opcional: SecretumVault (KMS) | +| 4 | **TypeDialog** | Wizards de configuraciΓ³n, prov-gen para Provisioning | Opcional: Provisioning (IaC apply) | +| 5 | **Vapora** | OrquestaciΓ³n de agentes, integra todos los anteriores | Kogral (runbooks), SecretumVault (creds), Provisioning (deploy) | + +**Nota**: Cada proyecto es funcional de forma independiente, pero las sinergias emergen con adopciΓ³n progresiva. + +--- + +## 8. ComparaciΓ³n de Ecosistemas + +### STRATUMIOPS Ops vs HashiCorp Stack + +| Componente | STRATUMIOPS | HashiCorp | +| ------------ | --------- | ----------- | +| **IaC** | Provisioning (Nickel tipado) | Terraform (HCL sin tipos) | +| **Secrets** | SecretumVault (Rust, **PQC**) | Vault (Go, sin PQC) | +| **OrquestaciΓ³n** | Vapora (LLM agents) | Nomad (workload scheduler) | +| **Service Mesh** | Integra Istio | Consul Connect | +| **Policy** | Cedar (AWS-compatible) | Sentinel (HCL) | +| **Lenguaje** | Rust (memory-safe) | Go (garbage collector) | +| **IA-assisted** | MCP + RAG nativo | Terraform Cloud AI (limitado) | +| **Licencia** | Apache-2.0 | BSL (Enterprise paywall) | +| **Ecosystem** | ⚠️ PequeΓ±o | βœ… Enorme | + +### STRATUMIOPS Ops vs AWS Native Stack + +| Componente | STRATUMIOPS | AWS Native | +| ------------ | --------- | ------------ | +| **IaC** | Provisioning (multi-cloud) | CloudFormation (AWS-only) | +| **Secrets** | SecretumVault (**PQC**, self-hosted) | Secrets Manager (SaaS, sin PQC) | +| **OrquestaciΓ³n** | Vapora (self-hosted K8s) | Step Functions (SaaS) | +| **CI/CD** | Vapora DevOps Agent | CodePipeline + CodeBuild | +| **Storage** | SurrealDB multi-modelo | DynamoDB + RDS | +| **Policy** | Cedar (portable) | IAM (AWS-specific) | +| **Multi-cloud** | βœ… AWS/UpCloud/Local | ❌ AWS-only | +| **Vendor lock-in** | βœ… Portable | ⚠️ High | +| **Cost** | Self-hosted (infra cost) | SaaS (per-use billing) | + +--- + +## 9. MΓ©tricas del Portfolio (Ops Perspective) + +| MΓ©trica | Provisioning | SecretumVault | Vapora | TypeDialog | Kogral | **Total** | +| --------- | -------------- | --------------- | -------- | ------------ | -------- | ----------- | +| **Lines of Code** | ~40K | ~11K | ~50K | ~90K | ~15K | **~206K** | +| **Tests** | 218 | 50+ | 218 | 3,818 | 56 | **4,360+** | +| **CLI Commands** | 80+ shortcuts | 10+ (svault) | 10+ (vapora) | 6 backends | 13 commands | **100+** | +| **Storage Backends** | SurrealDB | 4 (FS/etcd/SurrealDB/PostgreSQL) | SurrealDB + NATS | Multi-formato | FS + SurrealDB | **4 backends** | +| **API Endpoints** | 40+ (control-center) | 20+ (vault API) | 40+ (backend) | 10+ (web) | N/A (MCP) | **100+** | +| **Policy Engine** | Cedar RBAC/ABAC | Cedar ABAC | Cedar multi-tenant | N/A | N/A | **Cedar AWS-compatible** | +| **Crypto Backends** | 5 KMS | **4 (OpenSSL, OQS PQC, AWS-LC, RustCrypto)** | N/A | N/A | N/A | **4 backends** | +| **Multi-cloud** | AWS/UpCloud/Local | N/A | N/A | SΓ­ (prov-gen) | N/A | **3 clouds** | + +--- + +## 10. ConclusiΓ³n (Ops/DevOps Teams) + +Este portfolio representa un ecosistema cohesivo para operaciones modernas: + +- **Provisioning** es el mΓΊsculo: despliega infraestructura multi-cloud con IaC tipado y rollback automΓ‘tico +- **SecretumVault** es la bΓ³veda: protege secretos con criptografΓ­a post-cuΓ‘ntica lista para producciΓ³n +- **Vapora** es el cerebro: orquesta agentes Ops (DevOps, Monitor, Security) con aprendizaje y control de costos +- **TypeDialog** es la interfaz: wizards de configuraciΓ³n que generan IaC validado multi-cloud +- **Kogral** es la memoria: preserva runbooks, postmortems y conocimiento operativo + +La **diferenciaciΓ³n clave** frente a alternativas (Ops perspective): + +1. **Full Rust stack**: Performance (10-50x Python), memory-safety, zero-cost abstractions +2. **Nickel IaC tipado**: Errores de configuraciΓ³n detectados en compilaciΓ³n, no en runtime +3. **Post-Quantum ready**: SecretumVault con ML-KEM-768/ML-DSA-65 nativos, despliega hoy +4. **IA-native desde diseΓ±o**: MCP + RAG integrados, no retrofitted +5. **Multi-cloud unificado**: Una configuraciΓ³n Nickel para AWS/UpCloud/Local +6. **Enterprise security**: Cedar policies, audit logging, RBAC/ABAC, 7 aΓ±os retenciΓ³n + +La **sinergia** entre proyectos permite abordar operaciones con: + +- Infraestructura tipada y validada (Provisioning) +- Secretos con agilidad criptogrΓ‘fica (SecretumVault) +- OrquestaciΓ³n inteligente de agentes Ops (Vapora) +- Wizards de configuraciΓ³n (TypeDialog) +- Conocimiento operativo preservado (Kogral) + +**Mejor para**: Equipos DevOps/SRE que valoran type-safety, performance, PQC readiness, multi-cloud, y self-hosted infrastructure sobre ecosistemas maduros con vendor lock-in. + +--- + +*Documento generado: 2026-01-22* +*Tipo: info (posicionamiento Ops/DevOps)* diff --git a/docs/es/ops/ops-stratumiops-projects-technical-specs.md b/docs/es/ops/ops-stratumiops-projects-technical-specs.md new file mode 100644 index 0000000..3e87dd8 --- /dev/null +++ b/docs/es/ops/ops-stratumiops-projects-technical-specs.md @@ -0,0 +1,1812 @@ +# Portfolio Ops/DevOps: Especificaciones TΓ©cnicas + +## Arquitectura del Ecosistema Ops + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE INTERFACES β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Leptos WASM (Vapora Kanban) β”‚ Ratatui TUI β”‚ Axum REST β”‚ CLI (clap) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE ORQUESTACIΓ“N β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Vapora (NATS Agents) β”‚ Provisioning Orchestrator β”‚ TypeDialog Backends β”‚ +β”‚ DevOps/Monitor/Security β”‚ (Rust + Nushell hybrid) β”‚ (prov-gen IaC) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE SEGURIDAD β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SecretumVault (PQC) β”‚ Cedar Policies (ABAC) β”‚ JWT + MFA (Auth) β”‚ +β”‚ KV/Transit/PKI/DB β”‚ Audit Logging β”‚ TLS/mTLS (Transport) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE PERSISTENCIA β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SurrealDB (multi-tenant, time-series) β”‚ NATS JetStream (messaging) β”‚ +β”‚ etcd (distributed KV) β”‚ PostgreSQL (ACID, enterprise) β”‚ +β”‚ Filesystem (git-native markdown) β”‚ Kogral (.kogral/ directory) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 1. Provisioning: Especificaciones Ops + +### Directory Structure + +```text +provisioning/ +β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ cli/ # Main CLI (211 lines, 80+ shortcuts) +β”‚ β”œβ”€β”€ nulib/ # Nushell libraries (476+ config accessors) +β”‚ └── scripts/ # Utility scripts (Nushell) +β”œβ”€β”€ extensions/ +β”‚ β”œβ”€β”€ providers/ # AWS, UpCloud, Local (LXD) +β”‚ β”‚ β”œβ”€β”€ aws/ # EC2, VPC, S3, RDS provisioners +β”‚ β”‚ β”œβ”€β”€ upcloud/ # Servers, networking, storage +β”‚ β”‚ └── local/ # LXD containers, networking +β”‚ β”œβ”€β”€ taskservs/ # 50+ infrastructure services +β”‚ β”‚ β”œβ”€β”€ containerd/ # Container runtime +β”‚ β”‚ β”œβ”€β”€ etcd/ # Distributed KV store +β”‚ β”‚ β”œβ”€β”€ kubernetes/ # K8s control-plane + workers +β”‚ β”‚ β”œβ”€β”€ cilium/ # eBPF-based CNI +β”‚ β”‚ β”œβ”€β”€ postgresql/ # Database +β”‚ β”‚ β”œβ”€β”€ prometheus/ # Metrics +β”‚ β”‚ └── ... # 44 more services +β”‚ β”œβ”€β”€ clusters/ # Pre-configured cluster templates +β”‚ β”‚ β”œβ”€β”€ k8s-ha/ # HA Kubernetes (3 control-plane, N workers) +β”‚ β”‚ β”œβ”€β”€ k8s-dev/ # Dev Kubernetes (single-node) +β”‚ β”‚ └── db-cluster/ # PostgreSQL HA with Patroni +β”‚ └── workflows/ # Automation workflows +β”‚ β”œβ”€β”€ backup/ # Backup automation +β”‚ β”œβ”€β”€ monitoring/ # Observability setup +β”‚ └── security/ # Security hardening +β”œβ”€β”€ platform/ +β”‚ β”œβ”€β”€ orchestrator/ # Workflow execution engine (Rust) +β”‚ β”œβ”€β”€ control-center/ # Backend API (Axum + RBAC) +β”‚ β”œβ”€β”€ control-center-ui/ # Web dashboard (Leptos) +β”‚ β”œβ”€β”€ installer/ # Multi-mode installer +β”‚ β”œβ”€β”€ mcp-server/ # MCP server (Rust, 1000x Python) +β”‚ β”œβ”€β”€ ai-service/ # AI operations (LLM integration) +β”‚ β”œβ”€β”€ rag/ # RAG system (1200+ docs) +β”‚ β”œβ”€β”€ vault-service/ # Secrets management (integra SecretumVault) +β”‚ └── detector/ # Anomaly detection +└── schemas/ # Nickel IaC schemas (typed) + β”œβ”€β”€ server.ncl # Server definition contract + β”œβ”€β”€ networking.ncl # VPC, subnets, security groups + β”œβ”€β”€ kubernetes.ncl # K8s cluster contract + └── ... # 20+ schemas +``` + +### Nickel IaC Schema Examples + +#### Server Schema + +```nickel +# schemas/server.ncl +let Server = { + name | String, + provider | [ | 'aws, 'upcloud, 'local |], + + spec | { + cpu | Number | default = 2, + memory_gb | Number | default = 4, + disk_gb | Number | default = 50, + + os | { + family | [ | 'ubuntu, 'debian, 'rocky, 'alpine |], + version | String, + }, + }, + + networking | { + vpc | String | optional, + subnet | String | optional, + public_ip | Bool | default = false, + security_groups | Array String | default = [], + }, + + tags | { _ : String } | default = {}, + + # Validation constraints +} | { + spec.cpu | Number + | std.number.is_positive + | doc "CPU cores must be positive", + + spec.memory_gb | Number + | std.number.is_positive + | doc "Memory must be positive GB", + + spec.disk_gb | Number + | std.number.greater_eq 20 + | doc "Disk must be at least 20GB", +} +in Server +``` + +#### Kubernetes Cluster Schema + +```nickel +# schemas/kubernetes.ncl +let KubernetesCluster = { + name | String, + provider | [ | 'aws, 'upcloud, 'local |], + region | String, + + control_plane | { + count | Number | default = 3, + plan | [ | 'small, 'medium, 'large |] | default = 'medium, + high_availability | Bool | default = true, + }, + + workers | { + count | Number | default = 3, + plan | [ | 'small, 'medium, 'large, 'xlarge |] | default = 'medium, + auto_scaling | { + enabled | Bool | default = false, + min | Number | default = 3, + max | Number | default = 10, + } | optional, + }, + + networking | { + vpc_cidr | String | default = "10.0.0.0/16", + pod_cidr | String | default = "10.244.0.0/16", + service_cidr | String | default = "10.96.0.0/12", + cni | [ | 'cilium, 'calico, 'flannel |] | default = 'cilium, + }, + + addons | { + ingress_nginx | Bool | default = true, + cert_manager | Bool | default = true, + metrics_server | Bool | default = true, + prometheus | Bool | default = false, + }, + + version | String | default = "1.28", +} +in KubernetesCluster +``` + +### Orchestrator API (Rust) + +```rust +// platform/orchestrator/src/lib.rs +use std::collections::HashMap; +use anyhow::Result; +use serde::{Deserialize, Serialize}; +use tokio::sync::RwLock; + +pub struct Orchestrator { + state: Arc<RwLock<StateManager>>, + executor: WorkflowExecutor, + scheduler: Scheduler, + checkpoint_store: CheckpointStore, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Workflow { + pub id: String, + pub name: String, + pub tasks: Vec<Task>, + pub dependencies: HashMap<String, Vec<String>>, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Task { + pub id: String, + pub task_type: TaskType, + pub provider: Provider, + pub config: serde_json::Value, + pub retry_policy: RetryPolicy, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum TaskType { + ProvisionServer, + ConfigureNetworking, + InstallService, + RunHealthCheck, + CreateBackup, +} + +impl Orchestrator { + pub async fn execute_workflow(&self, workflow: Workflow) -> Result<ExecutionResult> { + // 1. Resolve dependencies (topological sort) + let ordered_tasks = self.resolve_dependencies(&workflow)?; + tracing::info!("Resolved {} tasks", ordered_tasks.len()); + + // 2. Create execution checkpoint + let checkpoint = self.checkpoint_store.create(&workflow).await?; + tracing::info!("Created checkpoint: {}", checkpoint.id); + + // 3. Execute tasks with retry logic + for (index, task) in ordered_tasks.iter().enumerate() { + tracing::info!("Executing task {}/{}: {}", index + 1, ordered_tasks.len(), task.id); + + match self.executor.run(task).await { + Ok(result) => { + self.state.write().await.record_success(task, &result)?; + self.checkpoint_store.update_progress(&checkpoint.id, index + 1).await?; + } + Err(e) => { + tracing::error!("Task {} failed: {}", task.id, e); + + // Exponential backoff retry + if let Some(result) = self.retry_with_backoff(task).await? { + self.state.write().await.record_success(task, &result)?; + } else { + // Rollback to checkpoint + tracing::warn!("Rollback to checkpoint {}", checkpoint.id); + self.rollback(&checkpoint).await?; + return Err(e); + } + } + } + } + + Ok(ExecutionResult::from_state(&*self.state.read().await)) + } + + async fn retry_with_backoff(&self, task: &Task) -> Result<Option<TaskResult>> { + let mut delay_ms = task.retry_policy.initial_delay_ms; + + for attempt in 1..=task.retry_policy.max_retries { + tracing::info!("Retry attempt {}/{} for task {}", attempt, task.retry_policy.max_retries, task.id); + tokio::time::sleep(tokio::time::Duration::from_millis(delay_ms)).await; + + match self.executor.run(task).await { + Ok(result) => return Ok(Some(result)), + Err(e) => { + tracing::warn!("Retry {} failed: {}", attempt, e); + delay_ms = (delay_ms * task.retry_policy.backoff_multiplier).min(task.retry_policy.max_delay_ms); + } + } + } + + Ok(None) + } + + async fn rollback(&self, checkpoint: &Checkpoint) -> Result<()> { + let completed_tasks = self.state.read().await.get_completed_tasks(&checkpoint.workflow_id)?; + + // Reverse order rollback + for task in completed_tasks.iter().rev() { + tracing::info!("Rolling back task: {}", task.id); + self.executor.rollback(task).await?; + } + + self.checkpoint_store.delete(&checkpoint.id).await?; + Ok(()) + } + + fn resolve_dependencies(&self, workflow: &Workflow) -> Result<Vec<Task>> { + // Topological sort + let mut in_degree: HashMap<String, usize> = HashMap::new(); + let mut graph: HashMap<String, Vec<String>> = HashMap::new(); + + for task in &workflow.tasks { + in_degree.insert(task.id.clone(), 0); + graph.insert(task.id.clone(), vec![]); + } + + for (task_id, deps) in &workflow.dependencies { + for dep in deps { + graph.get_mut(dep).unwrap().push(task_id.clone()); + *in_degree.get_mut(task_id).unwrap() += 1; + } + } + + let mut queue: Vec<String> = in_degree + .iter() + .filter( | (_, °ree) | degree == 0) + .map( | (id, _) | id.clone()) + .collect(); + + let mut sorted = Vec::new(); + + while let Some(task_id) = queue.pop() { + sorted.push(task_id.clone()); + + for neighbor in &graph[&task_id] { + *in_degree.get_mut(neighbor).unwrap() -= 1; + if in_degree[neighbor] == 0 { + queue.push(neighbor.clone()); + } + } + } + + if sorted.len() != workflow.tasks.len() { + anyhow::bail!("Cyclic dependency detected"); + } + + Ok(sorted.into_iter().map( | id | workflow.tasks.iter().find( | t| t.id == id).unwrap().clone()).collect()) + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct RetryPolicy { + pub max_retries: u32, + pub initial_delay_ms: u64, + pub max_delay_ms: u64, + pub backoff_multiplier: u64, +} + +impl Default for RetryPolicy { + fn default() -> Self { + Self { + max_retries: 3, + initial_delay_ms: 1000, + max_delay_ms: 60000, + backoff_multiplier: 2, + } + } +} +``` + +### MCP Server Tools (Provisioning) + +```rust +// platform/mcp-server/src/tools.rs +use serde_json::json; + +pub const MCP_TOOLS: &[Tool] = &[ + Tool { + name: "query_infrastructure", + description: "Query infrastructure state using natural language (RAG-powered)", + parameters: json!({ + "query": { "type": "string", "description": "Natural language query" }, + "provider": { "type": "string", "optional": true, "enum": ["aws", "upcloud", "local"] } + }), + }, + Tool { + name: "generate_config", + description: "Generate Nickel configuration from natural language description", + parameters: json!({ + "description": { "type": "string", "description": "Infrastructure description" }, + "provider": { "type": "string", "enum": ["aws", "upcloud", "local"] }, + "resource_type": { "type": "string", "enum": ["server", "network", "cluster", "database"] } + }), + }, + Tool { + name: "validate_config", + description: "Validate Nickel configuration against schemas", + parameters: json!({ + "config": { "type": "string", "description": "Nickel configuration code" }, + "strict": { "type": "boolean", "default": true, "description": "Strict validation mode" } + }), + }, + Tool { + name: "estimate_cost", + description: "Estimate monthly cost for infrastructure configuration", + parameters: json!({ + "config": { "type": "string", "description": "Nickel configuration" }, + "region": { "type": "string", "optional": true } + }), + }, + Tool { + name: "check_compliance", + description: "Check configuration against compliance frameworks", + parameters: json!({ + "config": { "type": "string" }, + "framework": { "type": "string", "enum": ["soc2", "hipaa", "gdpr", "pci"] } + }), + }, + Tool { + name: "plan_migration", + description: "Generate migration plan between configurations", + parameters: json!({ + "current": { "type": "string", "description": "Current Nickel config" }, + "target": { "type": "string", "description": "Target Nickel config" } + }), + }, + Tool { + name: "execute_workflow", + description: "Execute provisioning workflow with rollback support", + parameters: json!({ + "workflow_id": { "type": "string" }, + "dry_run": { "type": "boolean", "default": true } + }), + }, +]; +``` + +### CLI Shortcuts (80+) + +```bash +# Core operations +prov init # Initialize provisioning workspace +prov plan <config.ncl> # Generate execution plan (dry-run) +prov apply <config.ncl> # Apply configuration with rollback +prov destroy <config.ncl> # Destroy infrastructure +prov state list # List resources in state +prov state show <id> # Show resource details + +# Provider management +prov provider add aws # Add AWS provider credentials +prov provider add upcloud # Add UpCloud provider credentials +prov provider list # List configured providers +prov provider test <name> # Test provider connectivity + +# Service installation (taskservs) +prov service install containerd --servers server-01,server-02 +prov service install kubernetes --cluster k8s-prod +prov service install cilium --cluster k8s-prod --version 1.14 +prov service list # List available services +prov service status <name> # Check service status + +# Cluster operations +prov cluster create k8s-ha --template extensions/clusters/k8s-ha/ +prov cluster scale k8s-prod --workers 10 +prov cluster upgrade k8s-prod --version 1.28 +prov cluster backup k8s-prod --output /backups/ +prov cluster restore k8s-prod --from /backups/2026-01-22/ + +# Workflow operations +prov workflow run backup --cluster k8s-prod +prov workflow run monitoring --cluster k8s-prod +prov workflow list # List available workflows +prov workflow status <id> # Check workflow status + +# Guided wizards +prov wizard cluster # Interactive cluster setup +prov wizard database # Interactive database setup +prov wizard monitoring # Interactive monitoring setup + +# AI-assisted operations (MCP) +prov mcp query "Show me all AWS servers in us-east-1" +prov mcp generate "Create a 3-node K8s cluster with Cilium on UpCloud" +prov mcp validate cluster.ncl +prov mcp estimate cluster.ncl + +# Security operations +prov vault init # Initialize SecretumVault integration +prov vault store secret/myapp key=value +prov vault read secret/myapp +prov cert generate --domain example.com --engine pki +prov cert rotate --cluster k8s-prod + +# Observability +prov logs <resource-id> # View resource logs +prov metrics <cluster> # View cluster metrics +prov health <cluster> # Health check +prov events <cluster> # View events + +# Configuration management +prov config get <key> # Get config value (476+ accessors) +prov config set <key> <value> +prov config list # List all configuration +prov config validate # Validate configuration +``` + +--- + +## 2. SecretumVault: Especificaciones Ops + +### Architecture Overview + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault (~11K LOC, 50+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (svault) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends (Pluggable) β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends (Pluggable) β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Core Types + +```rust +// src/core/vault.rs +use std::collections::HashMap; +use std::sync::Arc; +use tokio::sync::Mutex; + +pub struct VaultCore { + pub engines: HashMap<String, Box<dyn Engine>>, + pub storage: Arc<dyn StorageBackend>, + pub crypto: Arc<dyn CryptoBackend>, + pub seal: Arc<Mutex<SealMechanism>>, + pub token_manager: Arc<TokenManager>, + pub authorizer: Arc<CedarAuthorizer>, + pub metrics: Arc<Metrics>, +} + +impl VaultCore { + pub async fn init(&self, shares: u8, threshold: u8) -> Result<Vec<SecretShare>> { + // Initialize Shamir unsealing + let mut seal = self.seal.lock().await; + let shares = seal.init(shares, threshold)?; + + // Setup default engines + self.mount_engine("secret", Box::new(KvEngine::new(self.storage.clone()))).await?; + + Ok(shares) + } + + pub async fn unseal(&self, share: SecretShare) -> Result<UnsealProgress> { + let mut seal = self.seal.lock().await; + let progress = seal.unseal(share)?; + + if let UnsealProgress::Complete = progress { + tracing::info!("Vault unsealed successfully"); + self.metrics.record_unseal().await; + } + + Ok(progress) + } + + pub async fn mount_engine(&self, path: &str, engine: Box<dyn Engine>) -> Result<()> { + self.engines.insert(path.to_string(), engine); + tracing::info!("Mounted engine at path: {}", path); + Ok(()) + } +} +``` + +### Crypto Backends (Post-Quantum) + +```rust +// src/crypto/backends/oqs.rs (Post-Quantum) +use oqs::{kem, sig}; +use anyhow::Result; + +pub struct OqsBackend { + kem_algorithm: kem::Algorithm, // MlKem768 + sig_algorithm: sig::Algorithm, // MlDsa65 + kem_cache: Arc<Mutex<Option<kem::Kem>>>, + sig_cache: Arc<Mutex<Option<sig::Sig>>>, +} + +impl OqsBackend { + pub fn new() -> Result<Self> { + Ok(Self { + kem_algorithm: kem::Algorithm::MlKem768, + sig_algorithm: sig::Algorithm::MlDsa65, + kem_cache: Arc::new(Mutex::new(None)), + sig_cache: Arc::new(Mutex::new(None)), + }) + } + + pub async fn kem_keypair(&self) -> CryptoResult<KemKeyPair> { + let mut cache = self.kem_cache.lock().await; + + if cache.is_none() { + *cache = Some(kem::Kem::new(self.kem_algorithm)?); + } + + let kem = cache.as_ref().unwrap(); + let (pk, sk) = kem.keypair()?; + + // ML-KEM-768: 1184 bytes public key, 2400 bytes secret key + Ok(KemKeyPair { + public_key: pk.into_vec(), + secret_key: sk.into_vec(), + }) + } + + pub async fn kem_encapsulate(&self, public_key: &[u8]) -> CryptoResult<KemResult> { + let mut cache = self.kem_cache.lock().await; + + if cache.is_none() { + *cache = Some(kem::Kem::new(self.kem_algorithm)?); + } + + let kem = cache.as_ref().unwrap(); + let pk = kem::PublicKey::from_bytes(public_key)?; + let (ciphertext, shared_secret) = kem.encapsulate(&pk)?; + + // ML-KEM-768: 1088 bytes ciphertext, 32 bytes shared secret + Ok(KemResult { + ciphertext: ciphertext.into_vec(), + shared_secret: shared_secret.into_vec(), + }) + } + + pub async fn kem_decapsulate(&self, secret_key: &[u8], ciphertext: &[u8]) -> CryptoResult<Vec<u8>> { + let mut cache = self.kem_cache.lock().await; + + if cache.is_none() { + *cache = Some(kem::Kem::new(self.kem_algorithm)?); + } + + let kem = cache.as_ref().unwrap(); + let sk = kem::SecretKey::from_bytes(secret_key)?; + let ct = kem::Ciphertext::from_bytes(ciphertext)?; + let shared_secret = kem.decapsulate(&sk, &ct)?; + + Ok(shared_secret.into_vec()) + } + + pub async fn sign(&self, secret_key: &[u8], message: &[u8]) -> CryptoResult<Vec<u8>> { + let mut cache = self.sig_cache.lock().await; + + if cache.is_none() { + *cache = Some(sig::Sig::new(self.sig_algorithm)?); + } + + let sig_obj = cache.as_ref().unwrap(); + let sk = sig::SecretKey::from_bytes(secret_key)?; + let signature = sig_obj.sign(message, &sk)?; + + // ML-DSA-65: 3309 bytes signature + Ok(signature.into_vec()) + } + + pub async fn verify(&self, public_key: &[u8], message: &[u8], signature: &[u8]) -> CryptoResult<bool> { + let mut cache = self.sig_cache.lock().await; + + if cache.is_none() { + *cache = Some(sig::Sig::new(self.sig_algorithm)?); + } + + let sig_obj = cache.as_ref().unwrap(); + let pk = sig::PublicKey::from_bytes(public_key)?; + let sig_bytes = sig::Signature::from_bytes(signature)?; + + match sig_obj.verify(message, &sig_bytes, &pk) { + Ok(_) => Ok(true), + Err(_) => Ok(false), + } + } +} + +#[async_trait] +impl CryptoBackend for OqsBackend { + async fn generate_keypair(&self, algorithm: KeyAlgorithm) -> CryptoResult<KeyPair> { + match algorithm { + KeyAlgorithm::MlKem768 => { + let kem_pair = self.kem_keypair().await?; + Ok(KeyPair { + public_key: kem_pair.public_key, + private_key: kem_pair.secret_key, + }) + } + KeyAlgorithm::MlDsa65 => { + let mut cache = self.sig_cache.lock().await; + if cache.is_none() { + *cache = Some(sig::Sig::new(self.sig_algorithm)?); + } + let sig_obj = cache.as_ref().unwrap(); + let (pk, sk) = sig_obj.keypair()?; + Ok(KeyPair { + public_key: pk.into_vec(), + private_key: sk.into_vec(), + }) + } + _ => Err(CryptoError::UnsupportedAlgorithm), + } + } + + async fn encrypt(&self, plaintext: &[u8]) -> CryptoResult<Vec<u8>> { + // Generate ephemeral keypair + let kem_pair = self.kem_keypair().await?; + + // Encapsulate to get shared secret + let kem_result = self.kem_encapsulate(&kem_pair.public_key).await?; + + // Use shared secret for AES-256-GCM encryption + let cipher = Aes256Gcm::new_from_slice(&kem_result.shared_secret)?; + let nonce = Aes256Gcm::generate_nonce(&mut OsRng); + let ciphertext = cipher.encrypt(&nonce, plaintext)?; + + // Prepend ciphertext with KEM ciphertext and nonce + let mut result = Vec::new(); + result.extend_from_slice(&kem_result.ciphertext); + result.extend_from_slice(&nonce); + result.extend_from_slice(&ciphertext); + + Ok(result) + } + + async fn decrypt(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>> { + // Extract KEM ciphertext, nonce, and encrypted data + let kem_ct = &ciphertext[..1088]; // ML-KEM-768 ciphertext size + let nonce = &ciphertext[1088..1088+12]; + let encrypted = &ciphertext[1088+12..]; + + // Decapsulate to get shared secret (requires secret key, stored in vault) + // This is simplified - in practice, secret key would be retrieved securely + + // Use shared secret for AES-256-GCM decryption + // ... (implementation details) + + Ok(plaintext) + } +} +``` + +### Secrets Engines + +```rust +// src/engines/mod.rs +#[async_trait] +pub trait Engine: Send + Sync { + fn name(&self) -> &str; + fn engine_type(&self) -> &str; + async fn read(&self, path: &str) -> Result<Option<Value>>; + async fn write(&self, path: &str, data: &Value) -> Result<()>; + async fn delete(&self, path: &str) -> Result<()>; + async fn list(&self, prefix: &str) -> Result<Vec<String>>; +} + +// src/engines/kv.rs (Key-Value Engine) +pub struct KvEngine { + storage: Arc<dyn StorageBackend>, + max_versions: usize, +} + +impl KvEngine { + pub fn new(storage: Arc<dyn StorageBackend>) -> Self { + Self { + storage, + max_versions: 10, // Keep 10 versions by default + } + } +} + +#[async_trait] +impl Engine for KvEngine { + fn name(&self) -> &str { "kv" } + fn engine_type(&self) -> &str { "kv-v2" } + + async fn write(&self, path: &str, data: &Value) -> Result<()> { + let full_path = format!("secret/data/{}", path); + + // Get current version + let current_version = self.get_current_version(path).await?; + let new_version = current_version + 1; + + // Create versioned entry + let entry = VersionedSecret { + version: new_version, + created_time: Utc::now(), + data: data.clone(), + }; + + // Store + self.storage.store_secret(&full_path, &entry).await?; + + // Cleanup old versions + self.cleanup_old_versions(path, new_version).await?; + + Ok(()) + } + + async fn read(&self, path: &str) -> Result<Option<Value>> { + let full_path = format!("secret/data/{}", path); + + match self.storage.get_secret(&full_path).await? { + Some(entry) => Ok(Some(entry.data)), + None => Ok(None), + } + } +} + +// src/engines/database.rs (Dynamic Credentials) +pub struct DatabaseEngine { + storage: Arc<dyn StorageBackend>, + connections: Arc<RwLock<HashMap<String, DatabaseConnection>>>, +} + +#[async_trait] +impl Engine for DatabaseEngine { + fn name(&self) -> &str { "database" } + fn engine_type(&self) -> &str { "database" } + + async fn write(&self, path: &str, data: &Value) -> Result<()> { + // Configure database connection + let config: DatabaseConfig = serde_json::from_value(data.clone())?; + + let connection = DatabaseConnection::new(&config).await?; + self.connections.write().await.insert(path.to_string(), connection); + + Ok(()) + } + + async fn read(&self, path: &str) -> Result<Option<Value>> { + // Generate dynamic credentials + // path format: "database/creds/{role}" + + if !path.starts_with("creds/") { + return Ok(None); + } + + let role = path.strip_prefix("creds/").unwrap(); + let role_config: RoleConfig = self.get_role_config(role).await?; + + // Generate username/password + let username = format!("v-{}-{}", role, Uuid::new_v4()); + let password = generate_secure_password(32); + + // Create user in database + let connections = self.connections.read().await; + let db_conn = connections.get(&role_config.db_name) + .ok_or_else(|| anyhow!("Database connection not found"))?; + + db_conn.execute(&role_config.creation_statements + .replace("{{name}}", &username) + .replace("{{password}}", &password) + .replace("{{expiration}}", &format_expiration(role_config.default_ttl)) + ).await?; + + // Create lease for cleanup + let lease_id = format!("database/creds/{}/{}", role, Uuid::new_v4()); + self.create_lease(&lease_id, role_config.default_ttl, move |vault | { + // Revoke credentials on lease expiration + async move { + db_conn.execute(&format!("DROP USER '{}'", username)).await?; + Ok(()) + } + }).await?; + + Ok(Some(json!({ + "lease_id": lease_id, + "lease_duration": role_config.default_ttl.as_secs(), + "username": username, + "password": password, + }))) + } +} +``` + +### Configuration (TOML) + +```toml +# svault.toml +[vault] +# Crypto backend: openssl | oqs | aws-lc | rustcrypto +crypto_backend = "oqs" # Post-quantum by default + +[server] +address = "0.0.0.0:8200" +tls_cert = "/etc/svault/certs/server.pem" +tls_key = "/etc/svault/certs/server-key.pem" +# Client certificate verification (mTLS) +client_ca = "/etc/svault/certs/ca.pem" +require_client_cert = false + +[storage] +# Backend: filesystem | etcd | surrealdb | postgresql +backend = "etcd" + +[storage.etcd] +endpoints = ["http://etcd-01:2379", "http://etcd-02:2379", "http://etcd-03:2379"] +username = "svault" +password = "secret" +# TLS for etcd +ca_cert = "/etc/svault/etcd-ca.pem" +client_cert = "/etc/svault/etcd-client.pem" +client_key = "/etc/svault/etcd-client-key.pem" + +[seal.shamir] +# Shamir secret sharing configuration +shares = 5 +threshold = 3 + +[auth] +# Token TTL +token_ttl = "24h" +token_max_ttl = "720h" # 30 days + +[audit] +# Audit log retention +enabled = true +retention_days = 2555 # 7 years +backend = "file" +path = "/var/log/svault/audit.log" + +[engines] +# Default engines to mount on init +kv = { path = "secret", version = 2 } +transit = { path = "transit" } +pki = { path = "pki", max_lease_ttl = "87600h" } # 10 years +database = { path = "database" } + +[metrics] +# Prometheus metrics +enabled = true +address = "0.0.0.0:9090" +``` + +--- + +## 3. Vapora: Especificaciones Ops Agents + +### Agent Roles for Ops + +```rust +// crates/vapora-agents/src/roles.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum AgentRole { + // Development roles + Architect, + Developer, + CodeReviewer, + Tester, + Documenter, + + // Marketing/Communication + Marketer, + Presenter, + + // Ops/DevOps roles + DevOps, // CI/CD, deployment, automation + Monitor, // Health checks, alerting, metrics + Security, // Vulnerability scanning, compliance + + // Management + ProjectManager, + DecisionMaker, +} + +impl AgentRole { + pub fn default_provider(&self) -> LLMProvider { + match self { + // High-complexity ops tasks: Claude Opus + AgentRole::Security => LLMProvider::Claude { model: "claude-opus-4-20250514" }, + AgentRole::DecisionMaker => LLMProvider::Claude { model: "claude-opus-4-20250514" }, + + // Standard ops tasks: Claude Sonnet + AgentRole::DevOps => LLMProvider::Claude { model: "claude-sonnet-4-20250514" }, + AgentRole::ProjectManager => LLMProvider::Claude { model: "claude-sonnet-4-20250514" }, + + // Real-time monitoring: Gemini Flash (low latency) + AgentRole::Monitor => LLMProvider::Gemini { model: "gemini-2.0-flash-exp" }, + + _ => LLMProvider::Claude { model: "claude-sonnet-4-20250514" }, + } + } + + pub fn can_block_pipeline(&self) -> bool { + matches!(self, AgentRole::Security) + } + + pub fn requires_approval(&self) -> bool { + matches!(self, AgentRole::DevOps | AgentRole::Security) + } +} +``` + +### NATS Message Patterns (Ops) + +```rust +// crates/vapora-agents/src/messages.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum AgentMessage { + TaskAssignment { + task_id: String, + agent_id: String, + agent_role: AgentRole, + task_type: String, + payload: serde_json::Value, + priority: Priority, + }, + TaskResult { + task_id: String, + agent_id: String, + agent_role: AgentRole, + status: TaskStatus, + output: Option<String>, + duration_ms: u64, + tokens_used: u32, + cost_cents: f64, + }, + Heartbeat { + agent_id: String, + agent_role: AgentRole, + status: AgentStatus, + current_load: f64, + last_task_completed_at: Option<DateTime<Utc>>, + }, + Alert { + severity: AlertSeverity, + source: String, + message: String, + metadata: serde_json::Value, + }, + ApprovalRequest { + task_id: String, + requester: AgentRole, + action: String, + details: serde_json::Value, + }, + ApprovalResponse { + task_id: String, + approved: bool, + approver: String, + reason: Option<String>, + }, +} + +// NATS subjects +pub const TASK_ASSIGNMENT: &str = "vapora.tasks.assign"; +pub const TASK_RESULTS: &str = "vapora.tasks.results"; +pub const AGENT_HEARTBEAT: &str = "vapora.agents.heartbeat"; +pub const ALERTS: &str = "vapora.alerts"; +pub const APPROVALS_REQUEST: &str = "vapora.approvals.request"; +pub const APPROVALS_RESPONSE: &str = "vapora.approvals.response"; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum AlertSeverity { + Info, + Warning, + Error, + Critical, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum Priority { + Low = 1, + Normal = 2, + High = 3, + Critical = 4, +} +``` + +### Budget Control (Ops Agents) + +```rust +// crates/vapora-llm-router/src/budget.rs +use std::collections::HashMap; +use serde::{Deserialize, Serialize}; +use chrono::{DateTime, Utc}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct BudgetConfig { + pub role: AgentRole, + pub monthly_limit_cents: u32, + pub weekly_limit_cents: Option<u32>, + pub enforcement: BudgetEnforcement, + pub fallback_chain: Vec<LLMProvider>, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum BudgetEnforcement { + Normal, // Under 80% of limit + NearThreshold, // 80-100% of limit, use fallback + Exceeded, // Over limit, block or use cheapest fallback only +} + +pub struct BudgetTracker { + configs: HashMap<AgentRole, BudgetConfig>, + usage: Arc<RwLock<HashMap<AgentRole, UsageStats>>>, +} + +impl BudgetTracker { + pub async fn check_budget(&self, role: AgentRole, estimated_cost_cents: f64) -> BudgetEnforcement { + let config = self.configs.get(&role).unwrap(); + let usage = self.usage.read().await; + let stats = usage.get(&role).unwrap_or(&UsageStats::default()); + + let monthly_usage = stats.monthly_cost_cents; + let weekly_usage = stats.weekly_cost_cents; + + // Check weekly limit first (if set) + if let Some(weekly_limit) = config.weekly_limit_cents { + if weekly_usage + estimated_cost_cents > weekly_limit as f64 { + return BudgetEnforcement::Exceeded; + } else if weekly_usage + estimated_cost_cents > (weekly_limit as f64 * 0.8) { + return BudgetEnforcement::NearThreshold; + } + } + + // Check monthly limit + if monthly_usage + estimated_cost_cents > config.monthly_limit_cents as f64 { + BudgetEnforcement::Exceeded + } else if monthly_usage + estimated_cost_cents > (config.monthly_limit_cents as f64 * 0.8) { + BudgetEnforcement::NearThreshold + } else { + BudgetEnforcement::Normal + } + } + + pub async fn select_provider(&self, role: AgentRole, task_type: &str) -> LLMProvider { + let enforcement = self.check_budget(role, self.estimate_cost(task_type)).await; + let config = self.configs.get(&role).unwrap(); + + match enforcement { + BudgetEnforcement::Normal => { + // Use default provider for role + role.default_provider() + } + BudgetEnforcement::NearThreshold => { + // Use first fallback (cheaper) + config.fallback_chain.get(0) + .cloned() + .unwrap_or_else(|| role.default_provider()) + } + BudgetEnforcement::Exceeded => { + // Use cheapest fallback (typically Ollama local) + config.fallback_chain.last() + .cloned() + .unwrap_or_else(|| LLMProvider::Ollama { model: "llama3.1:8b" }) + } + } + } + + pub async fn record_usage(&self, role: AgentRole, cost_cents: f64) { + let mut usage = self.usage.write().await; + let stats = usage.entry(role).or_insert_with(UsageStats::default); + + stats.monthly_cost_cents += cost_cents; + stats.weekly_cost_cents += cost_cents; + stats.total_requests += 1; + stats.last_updated = Utc::now(); + } +} + +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +pub struct UsageStats { + pub monthly_cost_cents: f64, + pub weekly_cost_cents: f64, + pub total_requests: u64, + pub last_updated: DateTime<Utc>, +} +``` + +### Prometheus Metrics (Ops) + +```rust +// crates/vapora-telemetry/src/metrics.rs +use prometheus::{Encoder, Gauge, Counter, Histogram, Registry}; + +pub struct VaporaMetrics { + registry: Registry, + + // Budget metrics + budget_utilization: Gauge, + budget_exceeded_total: Counter, + fallback_triggers_total: Counter, + + // Agent metrics + active_agents: Gauge, + task_duration_seconds: Histogram, + task_status_total: Counter, + + // Cost metrics + llm_cost_cents_total: Counter, + tokens_used_total: Counter, +} + +impl VaporaMetrics { + pub fn new() -> Self { + let registry = Registry::new(); + + let budget_utilization = Gauge::new( + "vapora_budget_utilization_ratio", + "Budget utilization ratio (0.0-1.0) per agent role" + ).unwrap(); + + let budget_exceeded_total = Counter::new( + "vapora_budget_exceeded_total", + "Total number of budget exceeded events per agent role" + ).unwrap(); + + let fallback_triggers_total = Counter::new( + "vapora_fallback_triggers_total", + "Total number of fallback provider triggers due to budget" + ).unwrap(); + + let active_agents = Gauge::new( + "vapora_active_agents", + "Number of active agents by role and status" + ).unwrap(); + + let task_duration_seconds = Histogram::new( + "vapora_task_duration_seconds", + "Task execution duration in seconds" + ).unwrap(); + + let task_status_total = Counter::new( + "vapora_task_status_total", + "Total tasks by status (success, failed, timeout)" + ).unwrap(); + + let llm_cost_cents_total = Counter::new( + "vapora_llm_cost_cents_total", + "Total LLM cost in cents per provider and role" + ).unwrap(); + + let tokens_used_total = Counter::new( + "vapora_tokens_used_total", + "Total tokens used per provider and role" + ).unwrap(); + + registry.register(Box::new(budget_utilization.clone())).unwrap(); + registry.register(Box::new(budget_exceeded_total.clone())).unwrap(); + registry.register(Box::new(fallback_triggers_total.clone())).unwrap(); + registry.register(Box::new(active_agents.clone())).unwrap(); + registry.register(Box::new(task_duration_seconds.clone())).unwrap(); + registry.register(Box::new(task_status_total.clone())).unwrap(); + registry.register(Box::new(llm_cost_cents_total.clone())).unwrap(); + registry.register(Box::new(tokens_used_total.clone())).unwrap(); + + Self { + registry, + budget_utilization, + budget_exceeded_total, + fallback_triggers_total, + active_agents, + task_duration_seconds, + task_status_total, + llm_cost_cents_total, + tokens_used_total, + } + } + + pub fn export(&self) -> String { + let encoder = prometheus::TextEncoder::new(); + let metric_families = self.registry.gather(); + let mut buffer = Vec::new(); + encoder.encode(&metric_families, &mut buffer).unwrap(); + String::from_utf8(buffer).unwrap() + } +} +``` + +--- + +## 4. TypeDialog (prov-gen): Especificaciones IaC Generation + +### Prov-Gen Backend + +```rust +// crates/typedialog-prov-gen/src/lib.rs +use tera::{Tera, Context}; +use serde::{Deserialize, Serialize}; + +pub struct ProvGenBackend { + templates: Tera, + validators: Vec<Box<dyn Validator>>, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct InfrastructureConfig { + pub provider: CloudProvider, + pub region: String, + pub resources: Vec<Resource>, + pub networking: NetworkConfig, + pub security: SecurityConfig, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum CloudProvider { + Aws, + Gcp, + Azure, + Hetzner, + UpCloud, + Local, // LXD +} + +pub struct Generator { + templates: tera::Tera, + validators: Vec<Box<dyn Validator>>, +} + +impl Generator { + pub async fn generate(&self, config: &InfrastructureConfig) -> Result<GeneratedIaC> { + // 1. Validate input config (7-layer validation) + self.validate_config(config)?; + + // 2. Load provider-specific template + let template_name = format!("{}.ncl.tera", config.provider.as_str()); + let template = self.templates.get_template(&template_name)?; + + // 3. Create template context + let mut context = Context::new(); + context.insert("provider", &config.provider); + context.insert("region", &config.region); + context.insert("resources", &config.resources); + context.insert("networking", &config.networking); + context.insert("security", &config.security); + + // 4. Render Nickel configuration + let nickel_code = template.render(&context)?; + + // 5. Validate generated Nickel + self.validate_nickel(&nickel_code)?; + + // 6. Split into logical files + let files = self.split_to_files(&nickel_code)?; + + Ok(GeneratedIaC { + provider: config.provider.clone(), + main_file: nickel_code, + files, + validation_passed: true, + }) + } + + fn validate_config(&self, config: &InfrastructureConfig) -> Result<()> { + for validator in &self.validators { + validator.validate(config)?; + } + Ok(()) + } + + fn validate_nickel(&self, code: &str) -> Result<()> { + // Run nickel typecheck + let output = std::process::Command::new("nickel") + .arg("typecheck") + .arg("--stdin") + .stdin(std::process::Stdio::piped()) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn()? + .stdin.unwrap().write_all(code.as_bytes())?; + + // Check exit status + // ... (implementation details) + + Ok(()) + } +} +``` + +### Templates (Tera + Nickel) + +```tera +{# templates/aws.ncl.tera - AWS multi-cloud template #} +{# Generated by TypeDialog prov-gen backend #} + +{ + provider = "aws", + region = "{{ region }}", + + {% if resources.servers %} + servers = [ + {% for server in resources.servers %} + { + name = "{{ server.name }}", + plan = "{{ server.plan }}", + role = {% if server.role %}"{{ server.role }}"{% else %}null{% endif %}, + provider = "aws", + + spec = { + cpu = {{ server.cpu | default(value=2) }}, + memory_gb = {{ server.memory_gb | default(value=4) }}, + disk_gb = {{ server.disk_gb | default(value=50) }}, + + os = { + family = 'ubuntu, + version = "{{ server.os_version | default(value='22.04') }}", + }, + }, + + networking = { + vpc = "{{ networking.vpc_id }}", + subnet = "{{ networking.subnet_id }}", + public_ip = {{ server.public_ip | default(value=false) }}, + security_groups = {{ server.security_groups | default(value=[]) | json_encode }}, + }, + + tags = { + Environment = "{{ environment | default(value='production') }}", + ManagedBy = "provisioning", + {% for key, value in server.tags %} + "{{ key }}" = "{{ value }}", + {% endfor %} + }, + }, + {% endfor %} + ], + {% endif %} + + {% if resources.taskservs %} + taskservs = {{ resources.taskservs | json_encode }}, + {% endif %} + + networking = { + vpc_cidr = "{{ networking.vpc_cidr | default(value='10.0.0.0/16') }}", + {% if networking.pod_cidr %} + pod_cidr = "{{ networking.pod_cidr }}", + service_cidr = "{{ networking.service_cidr }}", + {% endif %} + }, + + {% if security %} + security = { + {% if security.enable_encryption %} + encryption_at_rest = true, + kms_key_id = "{{ security.kms_key_id }}", + {% endif %} + + {% if security.enable_audit_logging %} + audit_logging = { + enabled = true, + retention_days = {{ security.audit_retention_days | default(value=2555) }}, + }, + {% endif %} + }, + {% endif %} +} +``` + +--- + +## 5. Kogral: Especificaciones Knowledge Management + +### Node Types (Ops Focus) + +```rust +// kogral-core/src/models.rs +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum NodeType { + Note, // General notes, documentation + Decision, // ADRs (Architectural Decision Records) + Guideline, // Team/org standards, policies + Pattern, // Reusable solutions, best practices + Journal, // Daily development/ops log + Execution, // Agent execution records, postmortems, incidents +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Node { + pub id: String, + pub node_type: NodeType, + pub title: String, + pub content: String, // Markdown body + pub metadata: HashMap<String, String>, + pub tags: Vec<String>, + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, + pub author: Option<String>, +} + +// Example: Execution node for incident postmortem +impl Node { + pub fn new_execution(title: &str, incident_details: IncidentDetails) -> Self { + let content = format!( + "# {}\n\n\ + ## Timeline\n\ + - **Started**: {}\n\ + - **Detected**: {}\n\ + - **Resolved**: {}\n\ + - **Duration**: {:?}\n\n\ + ## Root Cause\n\ + {}\n\n\ + ## Resolution\n\ + {}\n\n\ + ## Action Items\n\ + {}\n\n\ + ## Related Resources\n\ + {}", + title, + incident_details.started_at, + incident_details.detected_at, + incident_details.resolved_at, + incident_details.duration, + incident_details.root_cause, + incident_details.resolution, + incident_details.action_items.join("\n"), + incident_details.related_resources.join("\n"), + ); + + Self { + id: Uuid::new_v4().to_string(), + node_type: NodeType::Execution, + title: title.to_string(), + content, + metadata: incident_details.metadata, + tags: incident_details.tags, + created_at: Utc::now(), + updated_at: Utc::now(), + author: Some(incident_details.author), + } + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct IncidentDetails { + pub started_at: DateTime<Utc>, + pub detected_at: DateTime<Utc>, + pub resolved_at: DateTime<Utc>, + pub duration: std::time::Duration, + pub root_cause: String, + pub resolution: String, + pub action_items: Vec<String>, + pub related_resources: Vec<String>, + pub metadata: HashMap<String, String>, + pub tags: Vec<String>, + pub author: String, +} +``` + +### MCP Tools (Ops Workflows) + +```bash +# Buscar runbooks de troubleshooting +kogral-mcp search "nginx 502 error troubleshooting" --type note + +# AΓ±adir postmortem de incidente +kogral-mcp add-execution \ + --title "2026-01-22 PostgreSQL Connection Pool Exhaustion" \ + --context "Production database connections maxed out at 100/100" \ + --root-cause "Connection leak in application code, connections not released" \ + --resolution "Increased max_connections from 100 to 200, added PgBouncer pooler, fixed connection leak" \ + --action-items "Implement connection pool monitoring, add alerts at 80% utilization" \ + --tags "database,incident,postgresql,production" + +# Obtener guidelines de deployment +kogral-mcp get-guidelines "kubernetes deployment" --include-shared true + +# Crear ADR de decisiΓ³n de infraestructura +kogral-mcp add-decision \ + --title "Choose Cilium over Calico for CNI" \ + --context "Need Kubernetes CNI with eBPF support and service mesh capabilities" \ + --decision "Selected Cilium for better performance (eBPF) and built-in service mesh" \ + --consequences "Higher complexity initially, better performance long-term, requires Linux kernel 4.9+" + +# Listar todos los postmortems (Execution nodes) +kogral-mcp list --type execution --tags "incident" + +# Exportar knowledge graph a markdown +kogral-mcp export --format markdown --output /docs/ops-knowledge/ +``` + +--- + +## 6. IntegraciΓ³n entre Proyectos (Ops Stack) + +### Diagrama de Flujo de Datos + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Runbooks, ADRs) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + MCP (operational knowledge) + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TypeDialog β”‚ β”‚ Vapora β”‚ β”‚ Provisioning β”‚ +β”‚ (Wizards) β”‚ β”‚ (Ops Agents) β”‚ β”‚ (IaC Deploy) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ SECRETUMVAULT β”‚ + β”‚ PKI certs β”‚ DB creds β”‚ API keys β”‚ Encryption β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ PERSISTENCE LAYER β”‚ + β”‚ SurrealDB β”‚ NATS JetStream β”‚ etcd β”‚ Git β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Shared Dependencies (Ops Stack) + +```toml +# Dependencias comunes (Cargo.toml) +[dependencies] +# Runtime +tokio = { version = "1.48", features = ["full"] } + +# Serialization +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +toml = "0.8" + +# Database +surrealdb = "2.3" +etcd-client = "0.14" + +# Web/API +axum = { version = "0.8", features = ["macros"] } +tower = "0.5" +tower-http = { version = "0.6", features = ["cors", "compression-gzip"] } + +# Config +nickel-lang-core = "1.15" + +# Logging/Tracing +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] } +tracing-opentelemetry = "0.27" + +# Metrics +prometheus = "0.13" + +# Security +cedar-policy = "4.3" +jsonwebtoken = "9.3" + +# Crypto +openssl = { version = "0.10", optional = true } +oqs = { version = "0.10", optional = true } # Post-Quantum + +# Error handling +anyhow = "1.0" +thiserror = "2.0" +``` + +### Ejemplo de IntegraciΓ³n: CI/CD Pipeline con IA + +```rust +// Ejemplo de pipeline Ops integrado +use vapora_client::VaporaClient; +use provisioning_client::ProvisioningClient; +use secretumvault_client::VaultClient; +use kogral_mcp::KogralMcpClient; + +async fn deploy_microservice(config: DeploymentConfig) -> Result<DeploymentResult> { + // 1. Kogral: Obtener guidelines de deployment + let kogral = KogralMcpClient::connect("http://localhost:3100").await?; + let guidelines = kogral.call("get_guidelines", json!({ + "topic": "kubernetes deployment", + "include_shared": true + })).await?; + + // 2. Vapora: Orquestar pipeline con agentes + let vapora = VaporaClient::new("http://localhost:8001"); + + // Security Agent: Vulnerability scan + let scan_task = vapora.create_task(TaskRequest { + title: "Scan Docker image", + task_type: "security_scan", + context: json!({ + "image": config.docker_image, + "guidelines": guidelines, + }), + }).await?; + vapora.assign_task(&scan_task.id, AgentRole::Security).await?; + let scan_result = vapora.wait_for_completion(&scan_task.id).await?; + + if !scan_result.passed { + return Err(anyhow!("Security scan failed: {}", scan_result.issues)); + } + + // DevOps Agent: Validate manifests + let validate_task = vapora.create_task(TaskRequest { + title: "Validate K8s manifests", + task_type: "manifest_validation", + context: json!({ + "manifests_path": config.manifests_path, + "cluster": config.cluster, + }), + }).await?; + vapora.assign_task(&validate_task.id, AgentRole::DevOps).await?; + vapora.wait_for_completion(&validate_task.id).await?; + + // 3. SecretumVault: Obtener secretos para deployment + let vault = VaultClient::new("http://localhost:8200", &config.vault_token); + + // Database credentials (dynamic) + let db_creds = vault.read("database/creds/myapp-role").await?; + + // API keys (KV engine) + let api_keys = vault.read("secret/data/myapp/api-keys").await?; + + // 4. Provisioning: Deploy con kubectl + let prov = ProvisioningClient::new("http://localhost:8002"); + let deploy_result = prov.execute_workflow(WorkflowRequest { + workflow_type: "kubernetes_deploy", + config: json!({ + "cluster": config.cluster, + "namespace": config.namespace, + "manifests": config.manifests_path, + "secrets": { + "db_username": db_creds["username"], + "db_password": db_creds["password"], + "api_key": api_keys["data"]["api_key"], + }, + }), + }).await?; + + // 5. Vapora Monitor Agent: Setup health checks + let monitor_task = vapora.create_task(TaskRequest { + title: "Setup Prometheus alerts", + task_type: "monitoring_setup", + context: json!({ + "service": config.service_name, + "namespace": config.namespace, + "endpoints": config.health_endpoints, + }), + }).await?; + vapora.assign_task(&monitor_task.id, AgentRole::Monitor).await?; + + // 6. Kogral: Documentar deployment + kogral.call("add_execution", json!({ + "title": format!("Deploy {} v{}", config.service_name, config.version), + "context": format!("Deployed to {}/{}", config.cluster, config.namespace), + "resolution": "Deployment successful", + "metadata": { + "service": config.service_name, + "version": config.version, + "cluster": config.cluster, + "namespace": config.namespace, + "commit_sha": config.commit_sha, + }, + "tags": vec!["deployment", "kubernetes", config.service_name.as_str()], + })).await?; + + Ok(DeploymentResult { + status: "success", + deployed_at: Utc::now(), + health_checks_passed: true, + }) +} +``` + +--- + +## 7. MΓ©tricas de Calidad (Ops Perspective) + +| Proyecto | Tests | Cobertura | Clippy | Unsafe Blocks | Performance | +| ---------- | ------- | ----------- | -------- | --------------- | ------------- | +| **Provisioning** | 218 | ~65% | 0 warnings | 0 | Rust orchestrator 10-50x Python | +| **SecretumVault** | 50+ | ~75% | 0 warnings | 0 | Crypto ops <10ms (classical), <20ms (PQC) | +| **Vapora** | 218 | ~70% | 0 warnings | 0 | NATS latency <5ms, task assignment <100ms | +| **TypeDialog** | 3,818 | ~85% | 0 warnings | 0 | Form validation <1ms, IaC gen <500ms | +| **Kogral** | 56 | ~80% | 0 warnings | 0 | Semantic search <200ms (fastembed local) | + +### Comandos de VerificaciΓ³n Ops + +```bash +# Provisioning +cd provisioning +cargo clippy --all-targets --all-features -- -D warnings +cargo test --workspace +just ci-test # Run CI tests locally + +# SecretumVault +cd secretumvault +cargo test --all-features +cargo bench # Crypto benchmarks + +# Vapora +cd vapora +cargo test --workspace +docker-compose up -d # Integration tests con NATS + SurrealDB + +# TypeDialog +cd typedialog +cargo test --workspace --all-features +cargo run --example prov-gen # Test IaC generation + +# Kogral +cd kogral +cargo test +kogral serve & # Start MCP server +curl http://localhost:3100/health # Health check +``` + +--- + +*Documento generado: 2026-01-22* +*Tipo: info (especificaciones tΓ©cnicas Ops/DevOps)* diff --git a/docs/es/ops/ops-stratumiops-projects.md b/docs/es/ops/ops-stratumiops-projects.md new file mode 100644 index 0000000..14476cd --- /dev/null +++ b/docs/es/ops/ops-stratumiops-projects.md @@ -0,0 +1,735 @@ +# Portfolio Ops/DevOps: Infraestructura Moderna de Principio a Fin + +## El Problema + +Los equipos de DevOps y plataformas enfrentan desafΓ­os crΓ­ticos al gestionar infraestructura moderna: + +- **Herramientas fragmentadas**: Terraform para IaC, Ansible para configuraciΓ³n, Vault para secretos, todo desconectado +- **YAML sin tipos**: Errores de configuraciΓ³n que explotan en runtime, no en compilaciΓ³n +- **CriptografΓ­a estΓ‘tica**: Sin preparaciΓ³n para amenazas cuΓ‘nticas futuras +- **OrquestaciΓ³n manual**: Scripts imperativos frΓ‘giles sin rollback ni recuperaciΓ³n +- **Costos ocultos**: Sin visibilidad de gastos en LLMs para generaciΓ³n de infraestructura +- **Multi-cloud complejo**: Diferentes APIs, configuraciones y herramientas por proveedor + +## La SoluciΓ³n: Un Ecosistema Integrado + +Cinco proyectos diseΓ±ados para trabajar juntos, cubriendo el ciclo completo de operaciones. + +--- + +## Provisioning: Infraestructura como CΓ³digo Declarativa + +### IaC Tipado con GeneraciΓ³n Asistida por IA + +Provisioning combina la precisiΓ³n de configuraciΓ³n tipada (Nickel) con generaciΓ³n asistida por IA, eliminando el YAML frΓ‘gil y los scripts imperativos. + +**Capacidades ΓΊnicas**: + +- **Nickel IaC**: ConfiguraciΓ³n tipada con lazy evaluation, validaciΓ³n pre-runtime +- **MCP Server**: Consultas en lenguaje natural sobre infraestructura +- **RAG integrado**: 1,200+ documentos de dominio para respuestas contextuales +- **Multi-cloud**: AWS, UpCloud, local (LXD) desde la misma definiciΓ³n + +**OrquestaciΓ³n hΓ­brida**: + +- Orquestador Rust para workflows crΓ­ticos (performance 10-50x vs Python) +- Scripts Nushell para flexibilidad y prototipado rΓ‘pido +- ResoluciΓ³n automΓ‘tica de dependencias (topological sorting) +- Checkpoints y rollback automΓ‘tico ante fallos + +**El flujo de trabajo**: + +```text +"Necesito un cluster K8s en AWS con 3 nodos y Cilium" + ↓ + MCP Server (NLP) + ↓ + RAG busca configuraciones similares + ↓ + Genera Nickel + valida tipos + ↓ + Orchestrator despliega: + 1. containerd (dependency) + 2. etcd (dependency) + 3. kubernetes (core) + 4. cilium (CNI) + Con checkpoints y rollback automΓ‘tico +``` + +**Seguridad enterprise**: + +- JWT + MFA (TOTP + WebAuthn) +- Cedar policy engine para RBAC/ABAC +- 7 aΓ±os retenciΓ³n de audit logs +- 5 backends KMS (RustyVault, Age, AWS KMS, Vault, Cosmian) +- SOPS/Age para cifrado de configuraciΓ³n en reposo + +**Para quiΓ©n**: + +- Equipos DevOps que quieren IaC tipado, no YAML frΓ‘gil +- Organizaciones multi-cloud (AWS + UpCloud + on-premise) +- Equipos que necesitan audit, compliance y seguridad enterprise + +**Resultados esperados**: + +- Errores de configuraciΓ³n detectados en compilaciΓ³n, no en runtime +- Infraestructura generada desde lenguaje natural (MCP + RAG) +- Rollback automΓ‘tico ante fallos con state management + +--- + +## SecretumVault: GestiΓ³n de Secretos con Post-Quantum Crypto + +### Vault Rust con PQC en ProducciΓ³n + +SecretumVault es un sistema de gestiΓ³n de secretos que implementa **criptografΓ­a post-cuΓ‘ntica lista para producciΓ³n** (ML-KEM-768, ML-DSA-65), proporcionando agilidad criptogrΓ‘fica para organizaciones que despliegan hoy. + +**CriptografΓ­a agnΓ³stica**: + +- **OpenSSL**: RSA, ECDSA, AES-256-GCM (compatibilidad clΓ‘sica) +- **OQS (Post-Quantum)**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) +- **AWS-LC**: Experimental PQC (testing) +- **RustCrypto**: Pure-Rust implementations (testing) +- **Backends conectables**: Cambia algoritmos sin modificar cΓ³digo + +**Motores de secretos**: + +| Motor | Capacidad | Casos de uso | +| ------- | ----------- | -------------- | +| **KV** | Almacenamiento versionado de secretos | Credenciales, API keys, configuraciones sensibles | +| **Transit** | Encryption-as-a-service con rotaciΓ³n de claves | Cifrado de datos en aplicaciones, key rotation | +| **PKI** | GeneraciΓ³n de certificados X.509 | mTLS, service mesh, infraestructura interna | +| **Database** | Credenciales dinΓ‘micas con TTL | PostgreSQL, MySQL, MongoDB credentials on-demand | + +**Storage multi-backend**: + +- **Filesystem**: Desarrollo, single-node, rΓ‘pido prototipado +- **etcd**: Kubernetes, alta disponibilidad, consistencia fuerte +- **SurrealDB**: Queries complejas, time-series, multi-tenant scopes +- **PostgreSQL**: Enterprise, ACID, auditorΓ­a completa + +**Seguridad enterprise**: + +- Shamir Secret Sharing para unsealing (threshold configurable) +- Cedar policy engine (ABAC, compatible AWS) +- TLS/mTLS nativo con certificados X.509 +- Audit logging completo con retenciΓ³n configurable +- Token management con TTL y renovaciΓ³n + +**Ops/DevOps workflow**: + +```bash +# Inicializar vault con Shamir (5 shares, threshold 3) +svault operator init --shares 5 --threshold 3 + +# Unseal con 3 shares +svault operator unseal --share <share-1> +svault operator unseal --share <share-2> +svault operator unseal --share <share-3> + +# Habilitar motor Database para PostgreSQL +svault secret engine enable database +svault secret database config postgres-prod \ + plugin_name=postgresql-database-plugin \ + connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb" \ + username="vault" password="vaultpass" + +# Crear rol para credenciales dinΓ‘micas +svault secret database role create myapp-role \ + db_name=postgres-prod \ + creation_statements="CREATE USER '{{name}}' WITH PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO '{{name}}';" \ + default_ttl=1h max_ttl=24h + +# Obtener credenciales dinΓ‘micas (se generan on-demand) +svault secret read database/creds/myapp-role +# Key Value +# --- ----- +# lease_id database/creds/myapp-role/abc123 +# lease_duration 3600 +# username v-myapp-role-xyz789 +# password A1b2C3d4E5f6G7h8 + +# Credenciales se revocan automΓ‘ticamente tras 1h TTL +``` + +**Para quiΓ©n**: + +- Equipos desplegando criptografΓ­a post-cuΓ‘ntica hoy +- Organizaciones con requisitos de agilidad criptogrΓ‘fica +- Plataformas multi-cloud que necesitan gestiΓ³n de secretos Rust-native +- Equipos de seguridad evaluando amenazas cuΓ‘nticas futuras + +**Resultados esperados**: + +- PreparaciΓ³n para amenazas cuΓ‘nticas sin cambiar arquitectura +- GestiΓ³n de secretos con garantΓ­as de memoria de Rust +- IntegraciΓ³n nativa con Provisioning (KMS) y Vapora (credenciales de agentes) + +--- + +## Vapora: OrquestaciΓ³n de Agentes con Control de Costos + +### Agentes Inteligentes para Operaciones + +Vapora no es solo para desarrollo de features. Es una plataforma de orquestaciΓ³n que puede coordinar agentes especializados para operaciones DevOps. + +**Agentes disponibles para Ops**: + +- **DevOps**: CI/CD, pipelines, deployment automation +- **Monitor**: Health checks, alerting, mΓ©tricas en tiempo real +- **Security**: AuditorΓ­a, compliance, vulnerability scanning +- **ProjectManager**: Roadmap, tracking, coordinaciΓ³n de tareas + +**Control de costos real para LLMs**: + +- Presupuestos por rol (mensual/semanal) +- Tres niveles: normal β†’ cerca del lΓ­mite β†’ excedido +- Fallback automΓ‘tico a proveedores mΓ‘s baratos sin intervenciΓ³n manual +- MΓ©tricas Prometheus: `vapora_budget_utilization`, `vapora_fallback_triggers` + +**CoordinaciΓ³n NATS JetStream**: + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ NATS JetStream Messaging β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ vapora.tasks.assign β†’ AsignaciΓ³n de tareas β”‚ +β”‚ vapora.tasks.results β†’ Resultados de ejecuciΓ³n β”‚ +β”‚ vapora.agents.heartbeat β†’ Health check de agentes β”‚ +β”‚ β”‚ +β”‚ Persistencia: JetStream streams β”‚ +β”‚ Delivery: At-least-once con acknowledgment β”‚ +β”‚ Ordering: Per-subject message ordering β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**OrquestaciΓ³n de pipelines Ops**: + +```text +Pipeline: "Deploy microservice to K8s" + +1. Security Agent: Scan de vulnerabilidades en imagen Docker +2. DevOps Agent: Validar manifests K8s + Helm charts +3. Monitor Agent: Setup de mΓ©tricas Prometheus + alertas +4. DevOps Agent: Deploy con kubectl apply + health check +5. Monitor Agent: Validar health endpoints + smoke tests + +Si falla cualquier paso: rollback automΓ‘tico coordinado +``` + +**MΓ©tricas y observabilidad**: + +- Prometheus metrics endpoint (`/metrics`) +- OpenTelemetry integration (traces, spans) +- SurrealDB para almacenamiento de ejecuciones +- Grafana dashboards para visualizaciΓ³n + +**Para quiΓ©n**: + +- Equipos DevOps que coordinan mΓΊltiples agentes LLM para operaciones +- Organizaciones que necesitan controlar gastos LLM en automation +- Plataformas con pipelines complejos (CI/CD, deployment, monitoring) + +**Resultados esperados**: + +- ReducciΓ³n de costos LLM mediante routing inteligente +- OrquestaciΓ³n automΓ‘tica de tareas operativas complejas +- Visibilidad completa de gastos y rendimiento por agente + +--- + +## TypeDialog: Formularios Multi-Backend para ConfiguraciΓ³n + +### Una DefiniciΓ³n, Seis Interfaces (Incluye prov-gen) + +TypeDialog unifica la captura de configuraciΓ³n en CLI, TUI, Web, y tiene un backend especializado para generaciΓ³n de IaC multi-cloud. + +**Backends operacionales**: + +| Backend | Uso tΓ­pico en Ops/DevOps | +| --------- | -------------------------- | +| **CLI** | Scripts de automatizaciΓ³n, CI/CD pipelines | +| **TUI** | Herramientas de administraciΓ³n, dashboards terminal | +| **Web** | Portales de self-service, formularios para equipos | +| **Prov-gen** | **GeneraciΓ³n de infraestructura multi-cloud** | + +**Prov-gen Backend: IaC Generation** + +El backend `prov-gen` genera configuraciones de infraestructura Nickel para mΓΊltiples clouds desde formularios tipados: + +```toml +# cluster-setup.toml +[form] +id = "k8s_cluster" +title = "Kubernetes Cluster Setup" + +[[sections]] +id = "cloud" +title = "Cloud Provider" + +[[sections.fields]] +id = "provider" +type = "select" +label = "Provider" +required = true +options = [ + { value = "aws", label = "AWS" }, + { value = "upcloud", label = "UpCloud" }, + { value = "local", label = "Local LXD" }, +] + +[[sections.fields]] +id = "region" +type = "text" +label = "Region" +required = true + +[[sections]] +id = "cluster" +title = "Cluster Configuration" + +[[sections.fields]] +id = "node_count" +type = "number" +label = "Node Count" +default = 3 +validation.min = 1 +validation.max = 20 + +[[sections.fields]] +id = "node_size" +type = "select" +label = "Node Size" +options = [ + { value = "small", label = "Small (2 CPU, 4GB RAM)" }, + { value = "medium", label = "Medium (4 CPU, 8GB RAM)" }, + { value = "large", label = "Large (8 CPU, 16GB RAM)" }, +] + +[output] +backend = "prov-gen" +format = "nickel" +validation = "nickel://schemas/kubernetes_cluster.ncl" +``` + +Ejecutar con prov-gen: + +```bash +typedialog execute cluster-setup.toml --backend prov-gen --output k8s-cluster.ncl +``` + +Genera Nickel IaC: + +```nickel +# k8s-cluster.ncl (generado automΓ‘ticamente) +{ + provider = "aws", + region = "us-east-1", + + servers = [ + { + name = "k8s-control-plane-01", + plan = "medium", + role = "control-plane", + provider = "aws", + }, + { + name = "k8s-worker-01", + plan = "medium", + role = "worker", + provider = "aws", + }, + { + name = "k8s-worker-02", + plan = "medium", + role = "worker", + provider = "aws", + }, + ], + + taskservs = [ + "containerd", + "etcd", + "kubernetes", + "cilium", + ], + + networking = { + vpc_cidr = "10.0.0.0/16", + pod_cidr = "10.244.0.0/16", + service_cidr = "10.96.0.0/12", + }, +} +``` + +**ValidaciΓ³n Nickel contracts**: + +```rust +// ValidaciΓ³n automΓ‘tica con Nickel schemas +let validator = NickelValidator::new(); +let result = validator.validate(&generated_iac, "schemas/kubernetes_cluster.ncl")?; + +if result.errors.is_empty() { + // IaC vΓ‘lido, listo para Provisioning + provisioning_client.apply(&generated_iac).await?; +} else { + // Errores de validaciΓ³n, mostrar al usuario + eprintln!("Validation errors: {:?}", result.errors); +} +``` + +**Para quiΓ©n**: + +- Equipos DevOps que mantienen wizards de configuraciΓ³n en CLI y Web +- Organizaciones con self-service infrastructure portals +- Equipos que necesitan generaciΓ³n de IaC desde formularios + +**Resultados esperados**: + +- Una sola definiciΓ³n TOML para CLI, TUI, Web y generaciΓ³n de IaC +- ValidaciΓ³n tipada antes de runtime con Nickel contracts +- ReducciΓ³n de errores de configuraciΓ³n manual + +--- + +## Kogral: Base de Conocimiento para Equipos de Plataforma + +### Tu Base de Conocimiento Ops, Queryable + +Kogral captura decisiones arquitectΓ³nicas, runbooks, postmortems y procedimientos operativos en un formato que tanto humanos como agentes IA pueden consultar. + +**6 tipos de nodo especializados para Ops**: + +| Tipo | Uso en Ops/DevOps | +| ------ | ------------------- | +| **Note** | Runbooks, procedimientos, guΓ­as de troubleshooting | +| **Decision** | ADRs de infraestructura (por quΓ© AWS vs UpCloud, etcd vs Consul) | +| **Guideline** | Standards de deployment, polΓ­ticas de seguridad | +| **Pattern** | Patrones de infraestructura reutilizables (multi-AZ, HA) | +| **Journal** | Logs de cambios, daily stand-up notes | +| **Execution** | Historial de deployments, rollbacks, incidentes | + +**Git-native + MCP para Claude Code**: + +- Todo en markdown versionado (`.kogral/` directory) +- MCP server para Claude Code: agentes consultan runbooks antes de ejecutar +- BΓΊsqueda semΓ‘ntica con fastembed (local) o embeddings cloud + +**El flujo Ops**: + +```text +Incidente de producciΓ³n β†’ Captura postmortem en Kogral como Execution + ↓ + Claude Code consulta via MCP β†’ "ΒΏCΓ³mo resolvimos este error antes?" + ↓ + Kogral responde con postmortems similares + runbooks + ↓ + Agente aplica soluciΓ³n documentada en lugar de adivinar +``` + +**MCP Tools para Ops**: + +```bash +# Buscar runbooks de troubleshooting +kogral-mcp search "nginx 502 error troubleshooting" + +# AΓ±adir postmortem de incidente +kogral-mcp add-execution \ + --title "2026-01-22 PostgreSQL Connection Pool Exhaustion" \ + --context "Production database connections maxed out" \ + --resolution "Increased max_connections from 100 to 200, added PgBouncer" \ + --tags "database,incident,postgresql" + +# Obtener guidelines de deployment +kogral-mcp get-guidelines "kubernetes deployment" --include-shared true +``` + +**Para quiΓ©n**: + +- Equipos de plataforma que necesitan preservar conocimiento operativo +- SRE teams con rotaciΓ³n que pierden contexto de incidentes previos +- DevOps usando Claude Code que quieren runbooks contextualizados + +**Resultados esperados**: + +- Onboarding de nuevos SREs en dΓ­as, no semanas +- ResoluciΓ³n de incidentes informada por postmortems previos +- Decisiones de infraestructura preservadas y buscables + +--- + +## El Ecosistema en AcciΓ³n: Escenarios Ops + +### Escenario 1: Nuevo Cluster Kubernetes Multi-Cloud + +```text +1. TypeDialog (prov-gen): Wizard para configuraciΓ³n de cluster + - Cloud provider, regiΓ³n, node count, tamaΓ±o de nodos + - Genera Nickel IaC validado + +2. Provisioning: Despliega infraestructura + - Crea servidores en AWS/UpCloud + - Instala containerd, etcd, kubernetes, cilium + - Checkpoints por paso, rollback automΓ‘tico si falla + +3. SecretumVault: Genera certificados PKI + - Certificados etcd, kube-apiserver, kubelet + - RotaciΓ³n automΓ‘tica cada 90 dΓ­as + +4. Kogral: Documenta decisiΓ³n de arquitectura + - ADR: "Por quΓ© Cilium sobre Calico" + - Runbook: "CΓ³mo escalar cluster de 3 a 10 nodos" + +5. Vapora: Orquesta post-deployment + - Monitor Agent: Setup Prometheus + Grafana + - Security Agent: Escaneo de vulnerabilidades + - DevOps Agent: Deploy aplicaciones de prueba +``` + +### Escenario 2: Incidente de ProducciΓ³n (Database Outage) + +```text +1. Vapora Monitor Agent: Detecta PostgreSQL down + - Alerta vΓ­a NATS JetStream + - Trigger pipeline de incident response + +2. Kogral: Claude Code consulta vΓ­a MCP + - "ΒΏPostmortems de PostgreSQL outages?" + - Retorna 3 incidentes similares con resoluciones + +3. Vapora DevOps Agent: Ejecuta runbook + - Reinicia PostgreSQL con parΓ‘metros ajustados + - Verifica health checks + +4. SecretumVault: Rota credenciales de DB + - Genera nuevas credenciales dinΓ‘micas + - Actualiza aplicaciones vΓ­a Database engine + +5. Kogral: Documenta postmortem + - Execution node con root cause, resoluciΓ³n, action items + - Linked a ADRs de configuraciΓ³n de PostgreSQL +``` + +### Escenario 3: MigraciΓ³n a CriptografΓ­a Post-CuΓ‘ntica + +```text +1. Kogral: Documenta decisiΓ³n de migraciΓ³n + - ADR: "MigraciΓ³n a ML-KEM-768 para preparar amenazas cuΓ‘nticas" + - Timeline, risks, mitigation strategies + +2. SecretumVault: Migra secretos + - Cambio de backend: openssl β†’ oqs + - Re-encripta secretos con ML-KEM-768 + - Mantiene compatibilidad con clientes clΓ‘sicos + +3. Provisioning: Actualiza infraestructura + - Genera nuevos certificados PKI con ML-DSA-65 + - Despliega certificados a servicios (etcd, K8s API) + - Rollback automΓ‘tico si fallan health checks + +4. Vapora: Orquesta validaciΓ³n + - Security Agent: Verifica criptografΓ­a correcta + - Monitor Agent: Valida latencia no degradada + - DevOps Agent: Ejecuta integration tests + +5. TypeDialog: Portal self-service para equipos + - Formulario: "Migrar servicio a PQC" + - Backend prov-gen genera configuraciΓ³n actualizada +``` + +### Escenario 4: CI/CD con ValidaciΓ³n IA + +```text +1. Developer: Push a repositorio Git (Gitea) + +2. Vapora DevOps Agent (trigger via webhook): + - Ejecuta linting, tests unitarios + - Build de imagen Docker + - Scan de vulnerabilidades con Security Agent + +3. TypeDialog: Formulario de deployment + - Environment (staging/production) + - Canary rollout percentage + - Genera configuraciΓ³n K8s validada + +4. Provisioning: Despliega con Tekton + - Apply manifests K8s con kubectl + - Health checks automΓ‘ticos + - Rollback si health check falla + +5. SecretumVault: Inyecta secretos + - Credenciales de DB dinΓ‘micas (TTL 1h) + - API keys desde KV engine + - Certificados TLS desde PKI engine + +6. Kogral: Registra deployment + - Execution node con versiΓ³n, timestamp, autor + - Link a commit SHA, PR, cambios +``` + +--- + +## Por QuΓ© Elegir Este Ecosistema (Perspectiva Ops) + +### Frente a Alternativas + +| Nosotros | Terraform + Ansible + Vault | +| ---------- | ---------------------------- | +| **ConfiguraciΓ³n tipada**: Nickel con validaciΓ³n pre-runtime | YAML/HCL sin tipos, errores en runtime | +| **OrquestaciΓ³n integrada**: Provisioning orchestrator con rollback | Scripts imperativos, sin recuperaciΓ³n automΓ‘tica | +| **Post-Quantum crypto**: SecretumVault con ML-KEM/ML-DSA hoy | Vault sin roadmap PQC | +| **Multi-cloud unificado**: Una configuraciΓ³n Nickel para AWS/UpCloud/Local | Configuraciones separadas por cloud | +| **IA-native**: MCP + RAG para generaciΓ³n asistida | Sin asistencia IA, configuraciΓ³n manual | +| **Full Rust stack**: Performance, memory-safety | Mix Python/Go/Shell con overhead | + +### InversiΓ³n TΓ©cnica (Ops Focus) + +| MΓ©trica | Valor | +| --------- | ------- | +| **Provisioning**: Nickel IaC, 80+ CLI shortcuts | ~40K LOC | +| **SecretumVault**: 4 crypto backends, 4 storage backends | ~11K LOC | +| **Vapora**: NATS JetStream, 12 agent roles | ~50K LOC | +| **TypeDialog**: 6 backends incluido prov-gen | ~90K LOC | +| **Kogral**: 6 node types, MCP server | ~15K LOC | +| **Tests totales** | 4,360+ | +| **Backends crypto** | OpenSSL, OQS (PQC), AWS-LC, RustCrypto | +| **Storage backends** | FS, etcd, SurrealDB, PostgreSQL | + +--- + +## Comenzar (AdopciΓ³n para Equipos Ops) + +### AdopciΓ³n Progresiva Recomendada + +1. **SecretumVault**: GestiΓ³n de secretos con agilidad criptogrΓ‘fica (standalone) +2. **Kogral**: Establece base de conocimiento operativo (runbooks, ADRs, postmortems) +3. **TypeDialog**: Wizards de configuraciΓ³n para teams (CLI + Web + prov-gen) +4. **Provisioning**: IaC declarativo multi-cloud con orchestrator +5. **Vapora**: Orquesta agentes Ops con budget control (DevOps, Monitor, Security) + +Cada proyecto funciona de forma independiente. Las sinergias emergen al combinarlos. + +### Quick Start por Proyecto + +**SecretumVault**: + +```bash +# Docker Compose con etcd +docker-compose -f deploy/docker/docker-compose.yml up -d + +# Inicializar vault +curl -X POST http://localhost:8200/v1/sys/init -d '{"shares": 5, "threshold": 3}' + +# Unseal con 3 shares +curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-1>"}' +curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-2>"}' +curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-3>"}' + +# Habilitar motor PKI para certificados +svault secret engine enable pki +``` + +**Kogral**: + +```bash +# Inicializar repositorio de conocimiento +kogral init + +# AΓ±adir runbook +kogral add note "PostgreSQL Connection Pool Tuning" \ + --tags "database,postgresql,performance" + +# AΓ±adir ADR +kogral add decision "Elegir Cilium sobre Calico" \ + --context "Necesitamos CNI para K8s con eBPF" \ + --decision "Cilium por performance y observability" \ + --consequences "Mayor complejidad inicial, mejor performance a largo plazo" + +# Servir MCP server para Claude Code +kogral serve --port 3100 +``` + +**Provisioning**: + +```bash +# Clonar repositorio +git clone https://repo.jesusperez.pro/jesus/provisioning +cd provisioning + +# Configurar provider (UpCloud en este ejemplo) +cp config/providers/upcloud.example.toml config/providers/upcloud.toml +# Editar con credenciales de UpCloud + +# Crear cluster K8s (definiciΓ³n Nickel) +cat > cluster.ncl <<EOF +{ + provider = "upcloud", + region = "de-fra1", + servers = [ + { name = "k8s-cp-01", plan = "medium", role = "control-plane" }, + { name = "k8s-worker-01", plan = "medium", role = "worker" }, + { name = "k8s-worker-02", plan = "medium", role = "worker" }, + ], + taskservs = ["containerd", "etcd", "kubernetes", "cilium"], +} +EOF + +# Validar configuraciΓ³n +nickel typecheck cluster.ncl + +# Aplicar (orchestrator con checkpoints) +prov apply cluster.ncl --with-rollback +``` + +**TypeDialog (prov-gen)**: + +```bash +# Ejecutar wizard de configuraciΓ³n de cluster +typedialog execute examples/ops/cluster-setup.toml \ + --backend prov-gen \ + --output my-cluster.ncl + +# ConfiguraciΓ³n generada lista para Provisioning +nickel typecheck my-cluster.ncl +prov apply my-cluster.ncl +``` + +**Vapora**: + +```bash +# Desplegar con Docker Compose (backend + NATS + SurrealDB) +docker-compose up -d + +# Crear proyecto +curl -X POST http://localhost:8001/projects \ + -H "Content-Type: application/json" \ + -d '{"name": "Infrastructure Automation", "description": "DevOps pipelines"}' + +# Crear tarea para DevOps Agent +curl -X POST http://localhost:8001/tasks \ + -H "Content-Type: application/json" \ + -d '{ + "title": "Deploy Prometheus to K8s", + "task_type": "deployment", + "context": {"cluster": "prod-us-east-1", "namespace": "monitoring"} + }' + +# Asignar a DevOps Agent +curl -X POST http://localhost:8001/tasks/<task-id>/assign \ + -H "Content-Type: application/json" \ + -d '{"agent_role": "DevOps"}' +``` + +--- + +## Contacto + +- **Repositorios**: GitHub (proyectos privados) +- **Stack**: Rust, Nickel, Nushell, SurrealDB, Axum +- **Licencia**: Propietaria / Por definir + +--- + +*La infraestructura moderna no deberΓ­a requerir 10 herramientas desconectadas.* +*Un ecosistema. Cinco proyectos. IntegraciΓ³n real para Ops/DevOps.* diff --git a/docs/es/stratiumiops-technical-specs.md b/docs/es/stratiumiops-technical-specs.md new file mode 100644 index 0000000..a1ab0fc --- /dev/null +++ b/docs/es/stratiumiops-technical-specs.md @@ -0,0 +1,1784 @@ +# Portfolio: Especificaciones TΓ©cnicas Completas + +## Arquitectura del Ecosistema + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE USUARIO β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Leptos WASM β”‚ Ratatui TUI β”‚ CLI (clap) β”‚ MCP Protocol β”‚ +β”‚ (Vapora, Prov) β”‚ (TypeDialog, β”‚ (todos) β”‚ (Kogral, Prov) β”‚ +β”‚ β”‚ Prov) β”‚ β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE API β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Axum REST β”‚ WebSocket β”‚ JSON-RPC 2.0 β”‚ NATS JetStream β”‚ +β”‚ (40+ endpoints) β”‚ (real-time) β”‚ (MCP) β”‚ (messaging) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE DOMINIO β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Project Mgmt β”‚ Knowledge Graph β”‚ Form Engine β”‚ IaC Engine β”‚ Vault β”‚ +β”‚ (Vapora) β”‚ (Kogral) β”‚ (TypeDialog) β”‚ (Provisioning) β”‚ (SecretumV.)β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ Agent Coord β”‚ Embeddings β”‚ Agent Exec β”‚ Orchestrator β”‚ Seal/Unseal β”‚ +β”‚ (Vapora) β”‚ (Kogral) β”‚ (TypeDialog) β”‚ (Provisioning) β”‚ (SecretumV.)β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ LLM Router β”‚ MCP Server β”‚ Prov-gen β”‚ Security Layer β”‚ β”‚ +β”‚ (Vapora) β”‚ (Kogral) β”‚ (TypeDialog) β”‚ (Provisioning) β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA DE PERSISTENCIA β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ SurrealDB β”‚ Filesystem β”‚ NATS JetStream β”‚ etcd β”‚ PG β”‚ +β”‚ (multi-tenant β”‚ (git-native β”‚ (mensajerΓ­a β”‚ (SecretumVault β”‚(Vaultβ”‚ +β”‚ scopes) β”‚ markdown) β”‚ durable) β”‚ HA) β”‚ ent.)β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 1. Vapora: Especificaciones Completas + +### Workspace (13 crates) + +```text +crates/ +β”œβ”€β”€ vapora-shared/ # Core: models, errors, types +β”œβ”€β”€ vapora-backend/ # Axum REST API (40+ endpoints, 79 tests) +β”œβ”€β”€ vapora-agents/ # Agent orchestration + learning (67 tests) +β”œβ”€β”€ vapora-llm-router/ # Multi-provider routing + budget (53 tests) +β”œβ”€β”€ vapora-swarm/ # Swarm coordination + metrics (6 tests) +β”œβ”€β”€ vapora-knowledge-graph/# Temporal KG + learning curves (13 tests) +β”œβ”€β”€ vapora-frontend/ # Leptos WASM UI (Kanban) +β”œβ”€β”€ vapora-mcp-server/ # MCP protocol gateway +β”œβ”€β”€ vapora-tracking/ # Task/project storage +β”œβ”€β”€ vapora-telemetry/ # OpenTelemetry integration +β”œβ”€β”€ vapora-analytics/ # Event pipeline +β”œβ”€β”€ vapora-worktree/ # Git worktree management +└── vapora-doc-lifecycle/ # Documentation management +``` + +### Domain Models + +```rust +// vapora-shared/src/models.rs + +// ─── Project Management ─────────────────────────────────────── +pub struct Project { + pub id: String, + pub name: String, + pub description: Option<String>, + pub scope: String, // Multi-tenant scope + pub status: ProjectStatus, + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, +} + +pub enum ProjectStatus { + Active, + Archived, + OnHold, +} + +pub struct Task { + pub id: String, + pub project_id: String, + pub title: String, + pub description: Option<String>, + pub status: TaskStatus, + pub priority: TaskPriority, + pub assigned_agent: Option<String>, + pub tags: Vec<String>, + pub order: i32, + pub created_at: DateTime<Utc>, +} + +pub enum TaskStatus { + Todo, + Doing, + Review, + Done, +} + +pub enum TaskPriority { + Low, + Medium, + High, + Critical, +} + +// ─── Agent System ───────────────────────────────────────────── +pub struct Agent { + pub id: String, + pub role: AgentRole, + pub status: AgentStatus, + pub provider: LLMProvider, + pub current_load: f64, + pub last_heartbeat: DateTime<Utc>, +} + +pub enum AgentRole { + Architect, + Developer, + CodeReviewer, + Tester, + Documenter, + Marketer, + Presenter, + DevOps, + Monitor, + Security, + ProjectManager, + DecisionMaker, +} + +pub enum AgentStatus { + Ready, + Busy, + Offline, + Maintenance, +} + +// ─── Learning System ────────────────────────────────────────── +pub struct ExpertiseProfile { + pub agent_id: String, + pub task_type: String, + pub success_rate: f64, + pub avg_duration: Duration, + pub execution_count: u32, + pub recent_weight: f64, // 3x for last 7 days + pub confidence: f64, // Prevents overfitting + pub last_updated: DateTime<Utc>, +} + +// Scoring: 0.3*load + 0.5*expertise + 0.2*confidence + +// ─── LLM Router ─────────────────────────────────────────────── +pub enum LLMProvider { + Claude, + OpenAI, + Gemini, + Ollama, +} + +pub struct RoutingRule { + pub pattern: String, // Regex for task type + pub provider: LLMProvider, + pub model: String, + pub fallback_chain: Vec<LLMProvider>, +} + +pub struct BudgetConfig { + pub role: AgentRole, + pub monthly_limit_cents: u32, + pub weekly_limit_cents: Option<u32>, + pub enforcement: BudgetEnforcement, +} + +pub enum BudgetEnforcement { + Normal, + NearThreshold, // 80%+ + Exceeded, // 100%+ +} + +pub struct CostRecord { + pub provider: LLMProvider, + pub model: String, + pub input_tokens: u32, + pub output_tokens: u32, + pub cost_cents: f64, + pub task_type: String, + pub agent_id: String, + pub timestamp: DateTime<Utc>, +} +``` + +### API Endpoints + +```rust +// vapora-backend/src/api/mod.rs + +// ─── Projects ───────────────────────────────────────────────── +GET /projects // List projects (filtered by scope) +POST /projects // Create project +GET /projects/:id // Get project details +PUT /projects/:id // Update project +DELETE /projects/:id // Archive project + +// ─── Tasks ──────────────────────────────────────────────────── +GET /projects/:id/tasks // List tasks for project +POST /tasks // Create task +GET /tasks/:id // Get task details +PUT /tasks/:id // Update task +DELETE /tasks/:id // Delete task +POST /tasks/:id/assign // Assign to agent +PUT /tasks/:id/status // Update status (Kanban) +PUT /tasks/:id/order // Reorder task + +// ─── Agents ─────────────────────────────────────────────────── +GET /agents // List all agents +GET /agents/:id // Get agent details +GET /agents/:id/health // Health check +GET /agents/:role/expertise // Get expertise for role +POST /agents/register // Register new agent +DELETE /agents/:id // Unregister agent + +// ─── LLM Router ─────────────────────────────────────────────── +POST /llm/route // Route request to provider +GET /llm/providers // List available providers +GET /llm/budget/:role // Get budget status +PUT /llm/budget/:role // Set budget limits +GET /llm/costs // Cost report +GET /llm/costs/:role // Cost by role +GET /llm/costs/:provider // Cost by provider + +// ─── Swarm ──────────────────────────────────────────────────── +POST /swarm/assign // Assign task to swarm +GET /swarm/status // Swarm status +GET /swarm/agents // List swarm agents +POST /swarm/balance // Rebalance load + +// ─── Pipelines ──────────────────────────────────────────────── +POST /pipelines // Create pipeline +GET /pipelines/:id // Get pipeline status +POST /pipelines/:id/approve // Approve gate +POST /pipelines/:id/cancel // Cancel pipeline + +// ─── Knowledge Graph ────────────────────────────────────────── +POST /knowledge/query // Query knowledge graph +GET /knowledge/similar/:task_id // Find similar past tasks +GET /knowledge/learning/:agent // Get learning curve + +// ─── Observability ──────────────────────────────────────────── +GET /metrics // Prometheus metrics +GET /health // Health check +GET /health/ready // Readiness probe +GET /health/live // Liveness probe +``` + +### NATS Subjects + +```rust +// vapora-agents/src/messages.rs + +// ─── Task Assignment ────────────────────────────────────────── +const TASK_ASSIGN: &str = "vapora.tasks.assign"; +// Payload: TaskAssignment { task_id, agent_id, task_type, payload } + +const TASK_RESULT: &str = "vapora.tasks.results"; +// Payload: TaskResult { task_id, agent_id, status, output, duration_ms, tokens } + +// ─── Agent Coordination ─────────────────────────────────────── +const AGENT_HEARTBEAT: &str = "vapora.agents.heartbeat"; +// Payload: Heartbeat { agent_id, status, current_load } + +const AGENT_REGISTER: &str = "vapora.agents.register"; +// Payload: AgentRegistration { agent_id, role, capabilities } + +// ─── Pipeline Events ────────────────────────────────────────── +const PIPELINE_STAGE: &str = "vapora.pipelines.stage"; +// Payload: StageEvent { pipeline_id, stage, status } + +const PIPELINE_APPROVAL: &str = "vapora.pipelines.approval"; +// Payload: ApprovalRequest { pipeline_id, stage, requester } +``` + +### Frontend Components (Leptos) + +```rust +// vapora-frontend/src/components/ + +// ─── Kanban Board ───────────────────────────────────────────── +#[component] +pub fn KanbanBoard(project_id: String) -> impl IntoView { + // Columns: Todo, Doing, Review, Done + // Drag-and-drop with optimistic updates + // WebSocket subscription for real-time sync +} + +#[component] +pub fn KanbanColumn(status: TaskStatus, tasks: Vec<Task>) -> impl IntoView { + // Droppable zone + // Task cards with priority indicators +} + +#[component] +pub fn TaskCard(task: Task) -> impl IntoView { + // Draggable card + // Tags, priority, assignee display + // Click to open details +} + +// ─── Project Management ─────────────────────────────────────── +#[component] +pub fn ProjectList() -> impl IntoView { + // Grid/list view toggle + // Filter by status + // Create project modal +} + +#[component] +pub fn ProjectDetail(project_id: String) -> impl IntoView { + // Project info + // Kanban board + // Agent assignments + // Pipeline status +} + +// ─── Agent Dashboard ────────────────────────────────────────── +#[component] +pub fn AgentOverview() -> impl IntoView { + // Agent status grid + // Load indicators + // Expertise heatmap +} + +#[component] +pub fn CostDashboard() -> impl IntoView { + // Budget usage by role + // Cost trends charts + // Provider breakdown +} +``` + +--- + +## 2. Kogral: Especificaciones Completas + +### Workspace (3 crates) + +```text +crates/ +β”œβ”€β”€ kogral-core/ # Core library (48 tests) +β”‚ β”œβ”€β”€ models/ # Node, Edge, Graph types +β”‚ β”œβ”€β”€ storage/ # Multi-backend storage +β”‚ β”œβ”€β”€ parser/ # Markdown + YAML parser +β”‚ β”œβ”€β”€ block_parser/ # Logseq block support +β”‚ β”œβ”€β”€ query/ # Text + semantic search +β”‚ β”œβ”€β”€ embeddings/ # fastembed + rig-core +β”‚ β”œβ”€β”€ export/ # Tera templates +β”‚ β”œβ”€β”€ sync/ # Filesystem ↔ SurrealDB +β”‚ β”œβ”€β”€ config/ # Nickel config loader +β”‚ └── inheritance/ # Guideline inheritance +β”œβ”€β”€ kogral-cli/ # CLI (13 commands) +└── kogral-mcp/ # MCP server (7 tools) +``` + +### Domain Models + +```rust +// kogral-core/src/models.rs + +// ─── Node Types ─────────────────────────────────────────────── +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum NodeType { + Note, // General notes + Decision, // ADRs + Guideline, // Standards + Pattern, // Reusable solutions + Journal, // Daily logs + Execution, // Agent records +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Node { + pub id: String, + pub node_type: NodeType, + pub title: String, + pub content: String, // Markdown body + pub metadata: HashMap<String, Value>, + pub tags: Vec<String>, + pub graph_id: String, // Which graph this belongs to + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, +} + +// ─── Relationships ──────────────────────────────────────────── +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum RelationType { + RelatesTo, + DependsOn, + Implements, + Extends, + Supersedes, + Explains, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Edge { + pub source: String, + pub target: String, + pub relation: RelationType, + pub weight: f64, + pub metadata: HashMap<String, Value>, +} + +// ─── Graph ──────────────────────────────────────────────────── +#[derive(Debug, Clone)] +pub struct Graph { + pub id: String, + pub name: String, + pub graph_type: GraphType, + pub nodes: HashMap<String, Node>, + pub edges: Vec<Edge>, +} + +pub enum GraphType { + Project, // Local, in .kogral/ + Shared, // Organization-wide, in SurrealDB +} + +// ─── ADR Structure ──────────────────────────────────────────── +#[derive(Debug, Serialize, Deserialize)] +pub struct DecisionRecord { + pub title: String, + pub status: DecisionStatus, + pub context: String, + pub decision: String, + pub consequences: String, + pub alternatives: Vec<Alternative>, + pub related_decisions: Vec<String>, +} + +pub enum DecisionStatus { + Proposed, + Accepted, + Deprecated, + Superseded, +} + +// ─── Logseq Blocks ──────────────────────────────────────────── +#[derive(Debug, Clone)] +pub struct Block { + pub id: String, + pub content: String, + pub children: Vec<Block>, + pub properties: HashMap<String, String>, + pub task_status: Option<TaskStatus>, + pub tags: Vec<String>, + pub references: Vec<String>, // [[wikilinks]] +} + +pub enum TaskStatus { + TODO, + DOING, + DONE, + LATER, + NOW, + WAITING, + CANCELLED, +} +``` + +### Storage Trait + +```rust +// kogral-core/src/storage/mod.rs + +#[async_trait] +pub trait Storage: Send + Sync { + // ─── Node Operations ────────────────────────────────────── + async fn create_node(&self, node: &Node) -> Result<String>; + async fn get_node(&self, id: &str) -> Result<Option<Node>>; + async fn update_node(&self, node: &Node) -> Result<()>; + async fn delete_node(&self, id: &str) -> Result<()>; + async fn list_nodes(&self, filter: NodeFilter) -> Result<Vec<Node>>; + + // ─── Edge Operations ────────────────────────────────────── + async fn create_edge(&self, edge: &Edge) -> Result<()>; + async fn get_edges(&self, node_id: &str, direction: EdgeDirection) -> Result<Vec<Edge>>; + async fn delete_edge(&self, source: &str, target: &str) -> Result<()>; + + // ─── Search ─────────────────────────────────────────────── + async fn search_text(&self, query: &str, limit: usize) -> Result<Vec<Node>>; + async fn search_semantic(&self, embedding: &[f32], limit: usize) -> Result<Vec<Node>>; + + // ─── Graph Operations ───────────────────────────────────── + async fn get_connected(&self, node_id: &str, depth: usize) -> Result<Graph>; + async fn get_path(&self, from: &str, to: &str) -> Result<Option<Vec<Edge>>>; +} + +// Implementations +pub struct FilesystemStorage { + base_path: PathBuf, // .kogral/ +} + +pub struct SurrealDbStorage { + client: Surreal<Client>, + namespace: String, + database: String, +} + +pub struct MemoryStorage { + nodes: DashMap<String, Node>, + edges: DashMap<String, Vec<Edge>>, +} +``` + +### Embeddings + +```rust +// kogral-core/src/embeddings.rs + +pub enum EmbeddingProvider { + FastEmbed { + model: String, // "BAAI/bge-small-en-v1.5" + cache_dir: PathBuf, + }, + RigCore { + provider: RigProvider, // OpenAI, Anthropic, etc. + model: String, + }, +} + +#[async_trait] +pub trait Embedder: Send + Sync { + async fn embed(&self, text: &str) -> Result<Vec<f32>>; + async fn embed_batch(&self, texts: &[String]) -> Result<Vec<Vec<f32>>>; + fn dimensions(&self) -> usize; + fn model_name(&self) -> &str; +} + +// FastEmbed: 384 dimensions, local, offline +pub struct FastEmbedder { + model: fastembed::TextEmbedding, +} + +// RigCore: Cloud providers +pub struct RigEmbedder { + client: Box<dyn rig_core::Embedder>, +} +``` + +### CLI Commands + +```bash +# ─── Initialization ──────────────────────────────────────────── +kogral init # Create .kogral/ directory +kogral init --with-surreal # Also setup SurrealDB connection + +# ─── Adding Content ──────────────────────────────────────────── +kogral add note "Title" # Interactive note creation +kogral add decision "Title" # Guided ADR creation +kogral add guideline "Title" # Add team guideline +kogral add pattern "Title" # Document pattern +kogral add journal # Today's journal entry + +# ─── Querying ────────────────────────────────────────────────── +kogral search "query" # Text search +kogral search --semantic "query" # Semantic search +kogral search --type decision # Filter by type +kogral search --tag auth # Filter by tag + +# ─── Relationships ───────────────────────────────────────────── +kogral link <src> <dst> relates_to # Create relationship +kogral link <src> <dst> implements # Implementation link +kogral unlink <src> <dst> # Remove relationship + +# ─── Viewing ─────────────────────────────────────────────────── +kogral list # List all nodes +kogral list --type pattern # Filter by type +kogral show <id> # Display node details +kogral graph # Output DOT format +kogral graph --connected <id> # Subgraph from node + +# ─── Sync & Export ───────────────────────────────────────────── +kogral sync # Sync filesystem ↔ SurrealDB +kogral export markdown # Export to markdown +kogral export json # Export to JSON +kogral import <path> # Import from Logseq/markdown + +# ─── MCP Server ──────────────────────────────────────────────── +kogral serve # Start MCP server (stdio) +kogral serve --port 3000 # HTTP mode + +# ─── Configuration ───────────────────────────────────────────── +kogral config # Show current config +kogral config set <key> <value> # Set config value +``` + +### MCP Protocol + +```rust +// kogral-mcp/src/protocol.rs + +// ─── Tools ──────────────────────────────────────────────────── +pub const TOOLS: &[Tool] = &[ + Tool { + name: "search", + description: "Search knowledge graph", + input_schema: json!({ + "type": "object", + "properties": { + "query": { "type": "string" }, + "node_type": { "type": "string", "optional": true }, + "semantic": { "type": "boolean", "default": false }, + "limit": { "type": "integer", "default": 10 } + }, + "required": ["query"] + }), + }, + Tool { + name: "add_note", + description: "Add a note to the knowledge graph", + input_schema: json!({...}), + }, + Tool { + name: "add_decision", + description: "Record an architectural decision", + input_schema: json!({...}), + }, + Tool { + name: "link", + description: "Create relationship between nodes", + input_schema: json!({...}), + }, + Tool { + name: "get_guidelines", + description: "Get applicable guidelines", + input_schema: json!({...}), + }, + Tool { + name: "list_graphs", + description: "List available knowledge graphs", + input_schema: json!({}), + }, + Tool { + name: "export", + description: "Export knowledge graph", + input_schema: json!({...}), + }, +]; + +// ─── Resources ──────────────────────────────────────────────── +pub const RESOURCES: &[Resource] = &[ + Resource { + uri: "kogral://project/notes", + name: "Project Notes", + description: "All notes in current project", + }, + Resource { + uri: "kogral://project/decisions", + name: "Project Decisions", + description: "All ADRs in current project", + }, + Resource { + uri: "kogral://project/guidelines", + name: "Project Guidelines", + description: "Effective guidelines (with inheritance)", + }, + Resource { + uri: "kogral://project/patterns", + name: "Project Patterns", + description: "All patterns in current project", + }, + Resource { + uri: "kogral://shared/guidelines", + name: "Shared Guidelines", + description: "Organization-wide guidelines", + }, + Resource { + uri: "kogral://shared/patterns", + name: "Shared Patterns", + description: "Organization-wide patterns", + }, +]; + +// ─── Prompts ────────────────────────────────────────────────── +pub const PROMPTS: &[Prompt] = &[ + Prompt { + name: "summarize_project", + description: "Summarize project knowledge", + arguments: json!([]), + }, + Prompt { + name: "find_related", + description: "Find related knowledge for a topic", + arguments: json!([ + { "name": "topic", "required": true } + ]), + }, +]; +``` + +--- + +## 3. TypeDialog: Especificaciones Completas + +### Workspace (8 crates) + +```text +crates/ +β”œβ”€β”€ typedialog-core/ # Core library +β”‚ β”œβ”€β”€ form/ # Form models +β”‚ β”œβ”€β”€ field/ # Field types (8) +β”‚ β”œβ”€β”€ validation/ # Validators +β”‚ β”œβ”€β”€ backend/ # Backend trait +β”‚ β”œβ”€β”€ backends/ # 6 implementations +β”‚ β”œβ”€β”€ output/ # 4 output formats +β”‚ β”œβ”€β”€ i18n/ # Fluent integration +β”‚ └── nickel/ # Contract validation +β”œβ”€β”€ typedialog/ # CLI binary +β”œβ”€β”€ typedialog-tui/ # TUI binary +β”œβ”€β”€ typedialog-web/ # Web binary +β”œβ”€β”€ typedialog-ai/ # AI backend +β”œβ”€β”€ typedialog-agent/ +β”‚ β”œβ”€β”€ typedialog-ag-core/ # Agent runtime +β”‚ └── typedialog-ag/ # Agent CLI +└── typedialog-prov-gen/ # IaC generation +``` + +### Form Schema + +```toml +# Form definition (TOML) + +[form] +id = "example_form" +version = "1.0.0" +title = "Example Form" +description = "Demonstrates all features" + +# ─── Sections ────────────────────────────────────────────────── +[[sections]] +id = "basic" +title = "Basic Information" +description = "Required fields" + +[[sections.fields]] +id = "name" +type = "text" +label = "Full Name" +required = true +validation.min_length = 2 +validation.max_length = 100 +validation.pattern = "^[a-zA-Z\\s]+$" + +[[sections.fields]] +id = "email" +type = "text" +label = "Email Address" +required = true +validation.pattern = "^[^@]+@[^@]+\\.[^@]+$" + +[[sections.fields]] +id = "department" +type = "select" +label = "Department" +required = true +options = [ + { value = "engineering", label = "Engineering" }, + { value = "product", label = "Product" }, + { value = "design", label = "Design" }, +] + +# ─── Conditional Fields ──────────────────────────────────────── +[[sections.fields]] +id = "team_size" +type = "select" +label = "Team Size" +condition = { field = "department", equals = "engineering" } +options = [ + { value = "small", label = "1-5" }, + { value = "medium", label = "6-20" }, + { value = "large", label = "20+" }, +] + +# ─── Multi-select ────────────────────────────────────────────── +[[sections.fields]] +id = "skills" +type = "multi-select" +label = "Skills" +display_mode = "grid" # list, grid, dropdown +options = [ + { value = "rust", label = "Rust" }, + { value = "typescript", label = "TypeScript" }, + { value = "python", label = "Python" }, + { value = "go", label = "Go" }, +] + +# ─── Repeating Groups ────────────────────────────────────────── +[[sections.fields]] +id = "projects" +type = "group" +label = "Previous Projects" +repeatable = true +min_items = 1 +max_items = 5 + +[[sections.fields.fields]] +id = "project_name" +type = "text" +label = "Project Name" + +[[sections.fields.fields]] +id = "project_role" +type = "select" +label = "Role" +options = [...] + +# ─── Output ──────────────────────────────────────────────────── +[output] +format = "json" # json, yaml, toml, nickel +validation = "nickel://schemas/employee.ncl" +template = "templates/output.tera" +``` + +### Backend Trait + +```rust +// typedialog-core/src/backend/mod.rs + +#[async_trait] +pub trait Backend: Send + Sync { + fn name(&self) -> &str; + + async fn execute(&self, form: &Form) -> Result<FormResponse>; + + async fn render_field( + &self, + field: &Field, + value: Option<&Value>, + ) -> Result<Value>; + + fn supports_streaming(&self) -> bool { + false + } + + fn supports_validation(&self) -> bool { + true + } +} + +// ─── Backend Factory ────────────────────────────────────────── +pub enum BackendType { + Cli, + Tui, + Web, + Ai, + Agent, + ProvGen, +} + +pub struct BackendFactory; + +impl BackendFactory { + pub fn create(backend_type: BackendType, config: &Config) -> Box<dyn Backend> { + match backend_type { + BackendType::Cli => Box::new(CliBackend::new(config)), + BackendType::Tui => Box::new(TuiBackend::new(config)), + BackendType::Web => Box::new(WebBackend::new(config)), + BackendType::Ai => Box::new(AiBackend::new(config)), + BackendType::Agent => Box::new(AgentBackend::new(config)), + BackendType::ProvGen => Box::new(ProvGenBackend::new(config)), + } + } +} + +// ─── CLI Backend ────────────────────────────────────────────── +pub struct CliBackend { + theme: inquire::ui::RenderConfig, +} + +// ─── TUI Backend ────────────────────────────────────────────── +pub struct TuiBackend { + terminal: Terminal<CrosstermBackend<Stdout>>, +} + +// ─── Web Backend ────────────────────────────────────────────── +pub struct WebBackend { + port: u16, + templates: tera::Tera, +} + +// ─── AI Backend ─────────────────────────────────────────────── +pub struct AiBackend { + index: tantivy::Index, + embedder: Box<dyn Embedder>, + graph: petgraph::Graph<String, String>, +} + +// ─── Agent Backend ──────────────────────────────────────────── +pub struct AgentBackend { + providers: HashMap<String, Box<dyn LLMProvider>>, + templates: tera::Tera, +} + +// ─── ProvGen Backend ────────────────────────────────────────── +pub struct ProvGenBackend { + templates: HashMap<CloudProvider, tera::Tera>, + validators: Vec<Box<dyn Validator>>, +} +``` + +### Agent MDX Format + +```markdown +--- +name: code_reviewer +version: "1.0" +provider: claude +model: claude-sonnet-4-20250514 +temperature: 0.3 +max_tokens: 4096 +output_format: json +output_schema: | + { + "type": "object", + "properties": { + "issues": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { "enum": ["critical", "warning", "info"] }, + "line": { "type": "integer" }, + "message": { "type": "string" }, + "suggestion": { "type": "string" } + } + } + }, + "summary": { "type": "string" } + } + } +--- + +# Code Review Agent + +## System + +You are an expert code reviewer... + +## User + +Review this {{language}} code: + +```{{language}} +{{code}} +``` + +Guidelines: +{{guidelines}} +``` + +### IaC Generation + +```rust +// typedialog-prov-gen/src/lib.rs + +pub enum CloudProvider { + Aws, + Gcp, + Azure, + Hetzner, + UpCloud, + Lxd, +} + +pub struct InfraConfig { + pub provider: CloudProvider, + pub region: String, + pub environment: Environment, + pub resources: Vec<Resource>, + pub networking: NetworkConfig, + pub security: SecurityConfig, + pub tags: HashMap<String, String>, +} + +pub struct Generator { + templates: HashMap<CloudProvider, tera::Tera>, + validators: ValidationPipeline, // 7 layers +} + +impl Generator { + pub async fn generate(&self, config: &InfraConfig) -> Result<GeneratedIaC> { + // 1. Input validation + self.validators.validate_input(config)?; + + // 2. Load provider template + let template = self.templates + .get(&config.provider) + .ok_or(Error::UnsupportedProvider)?; + + // 3. Render Nickel + let nickel = template.render("main.ncl.tera", &config)?; + + // 4. Validate generated Nickel + self.validators.validate_nickel(&nickel)?; + + // 5. Split into files + let files = self.split_output(&nickel, config)?; + + Ok(GeneratedIaC { provider: config.provider, files }) + } +} + +// 7-Layer Validation Pipeline +pub struct ValidationPipeline { + layers: Vec<Box<dyn Validator>>, +} + +// Layers: +// 1. Schema validation (structure) +// 2. Type validation (Nickel contracts) +// 3. Provider validation (provider-specific rules) +// 4. Security validation (no exposed secrets) +// 5. Cost validation (budget limits) +// 6. Compliance validation (policy rules) +// 7. Integration validation (cross-resource refs) +``` + +--- + +## 4. Provisioning: Especificaciones Completas + +### Directory Structure + +```text +provisioning/ +β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ cli/ # Main CLI (211 lines) +β”‚ β”œβ”€β”€ nulib/ # Nushell libraries +β”‚ β”‚ β”œβ”€β”€ config.nu # 476+ accessors +β”‚ β”‚ β”œβ”€β”€ provider.nu # Provider abstraction +β”‚ β”‚ β”œβ”€β”€ workflow.nu # Workflow execution +β”‚ β”‚ └── utils.nu # Utilities +β”‚ └── scripts/ # Automation scripts +β”œβ”€β”€ extensions/ +β”‚ β”œβ”€β”€ providers/ +β”‚ β”‚ β”œβ”€β”€ aws/ # AWS provider +β”‚ β”‚ β”œβ”€β”€ upcloud/ # UpCloud provider +β”‚ β”‚ └── local/ # Local (LXD) provider +β”‚ β”œβ”€β”€ taskservs/ # 50+ services +β”‚ β”œβ”€β”€ clusters/ # Deployment templates +β”‚ └── workflows/ # Workflow definitions +β”œβ”€β”€ platform/ +β”‚ β”œβ”€β”€ orchestrator/ # Rust workflow engine +β”‚ β”œβ”€β”€ control-center/ # Axum backend +β”‚ β”œβ”€β”€ control-center-ui/ # Leptos frontend +β”‚ β”œβ”€β”€ installer/ # Multi-mode installer +β”‚ β”œβ”€β”€ mcp-server/ # MCP server +β”‚ β”œβ”€β”€ ai-service/ # AI operations +β”‚ β”œβ”€β”€ rag/ # RAG system +β”‚ β”œβ”€β”€ vault-service/ # Secrets management +β”‚ β”œβ”€β”€ detector/ # Anomaly detection +β”‚ β”œβ”€β”€ extension-registry/ # Extension catalog +β”‚ └── provisioning-daemon/ # Service daemon +β”œβ”€β”€ schemas/ # Nickel schemas +β”‚ β”œβ”€β”€ server.ncl +β”‚ β”œβ”€β”€ network.ncl +β”‚ β”œβ”€β”€ storage.ncl +β”‚ β”œβ”€β”€ kubernetes.ncl +β”‚ └── security.ncl +└── docs/ # Documentation +``` + +### Nickel Schemas + +```nickel +# schemas/server.ncl + +let Server = { + name + | String + | doc "Server hostname", + + provider + | [ | 'aws, 'upcloud, 'local |] + | doc "Cloud provider", + + spec + | { + cpu + | Number + | default = 2 + | doc "CPU cores", + memory_gb + | Number + | default = 4 + | doc "Memory in GB", + disk_gb + | Number + | default = 50 + | doc "Root disk in GB", + os + | { + family | [ | 'ubuntu, 'debian, 'rocky |], + version | String, + }, + }, + + networking + | { + vpc | String | optional, + subnet | String | optional, + public_ip | Bool | default = false, + security_groups | Array String | default = [], + private_ip | String | optional, + }, + + storage + | Array { + name | String, + size_gb | Number, + type | [ | 'ssd, 'hdd, 'nvme |] | default = 'ssd, + mount_point | String, + } + | default = [], + + tags + | { _ : String } + | default = {}, + + metadata + | { _ : Dyn } + | default = {}, +} +in Server +``` + +### Orchestrator + +```rust +// platform/orchestrator/src/lib.rs + +pub struct Orchestrator { + state: StateManager, + executor: WorkflowExecutor, + scheduler: Scheduler, + providers: HashMap<String, Box<dyn Provider>>, +} + +impl Orchestrator { + pub async fn execute(&self, workflow: Workflow) -> Result<ExecutionResult> { + // 1. Create checkpoint + let checkpoint = self.state.checkpoint(&workflow)?; + + // 2. Resolve dependencies (topological sort) + let tasks = self.resolve_dependencies(&workflow)?; + + // 3. Execute with retry + for task in tasks { + let result = self.execute_with_retry(&task).await; + + match result { + Ok(output) => { + self.state.record_success(&task, &output)?; + } + Err(e) => { + // Rollback to checkpoint + self.state.rollback(&checkpoint)?; + return Err(e); + } + } + } + + Ok(ExecutionResult::success()) + } + + async fn execute_with_retry(&self, task: &Task) -> Result<Output> { + let mut attempts = 0; + let max_attempts = task.retry_config.max_attempts; + + loop { + attempts += 1; + match self.executor.run(task).await { + Ok(output) => return Ok(output), + Err(e) if attempts < max_attempts => { + let delay = self.calculate_backoff(attempts); + tokio::time::sleep(delay).await; + } + Err(e) => return Err(e), + } + } + } + + fn calculate_backoff(&self, attempt: u32) -> Duration { + // Exponential backoff: 2^attempt * base_delay + Duration::from_secs(2u64.pow(attempt) * self.config.base_delay_secs) + } +} + +// ─── State Management ───────────────────────────────────────── +pub struct StateManager { + store: Box<dyn StateStore>, +} + +impl StateManager { + pub fn checkpoint(&self, workflow: &Workflow) -> Result<Checkpoint> { + let state = self.capture_current_state(workflow)?; + let id = self.store.save_checkpoint(&state)?; + Ok(Checkpoint { id, state }) + } + + pub fn rollback(&self, checkpoint: &Checkpoint) -> Result<()> { + self.restore_state(&checkpoint.state) + } +} +``` + +### Security Layer + +```rust +// platform/control-center/src/security/ + +// ─── Authentication ─────────────────────────────────────────── +pub struct AuthService { + jwt_secret: Secret<String>, + hasher: Argon2Config, + mfa: MfaService, +} + +impl AuthService { + pub async fn authenticate(&self, credentials: Credentials) -> Result<Token> { + // 1. Verify password + let user = self.verify_password(&credentials)?; + + // 2. Check MFA if enabled + if user.mfa_enabled { + self.mfa.verify(&user, &credentials.mfa_code)?; + } + + // 3. Generate JWT + let token = self.generate_jwt(&user)?; + + // 4. Audit log + self.audit.log_authentication(&user, AuthResult::Success)?; + + Ok(token) + } +} + +// ─── MFA Service ────────────────────────────────────────────── +pub struct MfaService { + totp: TotpProvider, + webauthn: WebAuthnProvider, +} + +impl MfaService { + pub fn verify(&self, user: &User, code: &MfaCode) -> Result<()> { + match &user.mfa_method { + MfaMethod::Totp => self.totp.verify(&user.totp_secret, code), + MfaMethod::WebAuthn => self.webauthn.verify(&user.credentials, code), + } + } +} + +// ─── Authorization (Cedar) ──────────────────────────────────── +pub struct AuthzService { + engine: cedar_policy::Authorizer, + policies: cedar_policy::PolicySet, +} + +impl AuthzService { + pub fn authorize(&self, request: &AuthzRequest) -> Result<Decision> { + let principal = self.build_principal(&request.user)?; + let action = self.build_action(&request.action)?; + let resource = self.build_resource(&request.resource)?; + + let decision = self.engine.is_authorized( + &principal, + &action, + &resource, + &self.policies, + )?; + + Ok(decision) + } +} + +// ─── KMS ────────────────────────────────────────────────────── +pub enum KmsBackend { + RustyVault(RustyVaultClient), + Age(AgeClient), + AwsKms(AwsKmsClient), + HashiVault(VaultClient), + Cosmian(CosmianClient), +} + +pub struct KmsService { + backend: KmsBackend, +} + +impl KmsService { + pub async fn encrypt(&self, plaintext: &[u8], key_id: &str) -> Result<Vec<u8>> { + // Envelope encryption + let dek = self.generate_dek()?; + let ciphertext = self.encrypt_with_dek(plaintext, &dek)?; + let encrypted_dek = self.wrap_key(&dek, key_id).await?; + + Ok(self.package(ciphertext, encrypted_dek)) + } + + pub async fn decrypt(&self, blob: &[u8], key_id: &str) -> Result<Vec<u8>> { + let (ciphertext, encrypted_dek) = self.unpackage(blob)?; + let dek = self.unwrap_key(&encrypted_dek, key_id).await?; + self.decrypt_with_dek(&ciphertext, &dek) + } +} + +// ─── Audit ──────────────────────────────────────────────────── +pub struct AuditService { + store: Box<dyn AuditStore>, + retention_years: u32, // 7 years +} + +impl AuditService { + pub fn log(&self, event: AuditEvent) -> Result<()> { + let record = AuditRecord { + id: Uuid::new_v4(), + timestamp: Utc::now(), + event, + user_id: current_user_id()?, + ip_address: current_ip()?, + user_agent: current_user_agent()?, + }; + + self.store.save(&record) + } + + pub fn export(&self, format: ExportFormat, range: DateRange) -> Result<Vec<u8>> { + let records = self.store.query(range)?; + + match format { + ExportFormat::Json => serde_json::to_vec(&records), + ExportFormat::Csv => self.to_csv(&records), + ExportFormat::Parquet => self.to_parquet(&records), + ExportFormat::Avro => self.to_avro(&records), + ExportFormat::Pdf => self.to_pdf(&records), + } + } +} +``` + +### MCP Server + +```rust +// platform/mcp-server/src/tools.rs + +pub const TOOLS: &[Tool] = &[ + // ─── Query Tools ────────────────────────────────────────── + Tool { + name: "query_infrastructure", + description: "Query infrastructure state using natural language", + input_schema: json!({ + "query": { "type": "string" }, + "provider": { "type": "string", "optional": true } + }), + }, + + // ─── Generation Tools ───────────────────────────────────── + Tool { + name: "generate_config", + description: "Generate Nickel configuration from description", + input_schema: json!({ + "description": { "type": "string" }, + "provider": { "type": "string" }, + "resource_type": { "type": "string" } + }), + }, + + // ─── Validation Tools ───────────────────────────────────── + Tool { + name: "validate_config", + description: "Validate Nickel configuration", + input_schema: json!({ + "config": { "type": "string" }, + "strict": { "type": "boolean", "default": true } + }), + }, + + // ─── Cost Tools ─────────────────────────────────────────── + Tool { + name: "estimate_cost", + description: "Estimate monthly cost for configuration", + input_schema: json!({ + "config": { "type": "string" }, + "region": { "type": "string", "optional": true } + }), + }, + + // ─── Compliance Tools ───────────────────────────────────── + Tool { + name: "check_compliance", + description: "Check configuration against compliance rules", + input_schema: json!({ + "config": { "type": "string" }, + "framework": { "enum": ["soc2", "hipaa", "gdpr", "pci"] } + }), + }, + + // ─── Migration Tools ────────────────────────────────────── + Tool { + name: "plan_migration", + description: "Generate migration plan between configurations", + input_schema: json!({ + "current": { "type": "string" }, + "target": { "type": "string" } + }), + }, + + // ─── Execution Tools ────────────────────────────────────── + Tool { + name: "execute_workflow", + description: "Execute provisioning workflow", + input_schema: json!({ + "workflow_id": { "type": "string" }, + "dry_run": { "type": "boolean", "default": true } + }), + }, +]; +``` + +--- + +## 5. SecretumVault: Especificaciones Completas + +### Arquitectura (~11K LOC, 50+ tests) + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (clap) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Core Types + +```rust +// src/core/vault.rs +pub struct VaultCore { + pub engines: HashMap<String, Box<dyn Engine>>, + pub storage: Arc<dyn StorageBackend>, + pub crypto: Arc<dyn CryptoBackend>, + pub seal: Arc<tokio::sync::Mutex<SealMechanism>>, + pub token_manager: Arc<TokenManager>, + pub metrics: Arc<Metrics>, +} + +// src/crypto/mod.rs +#[async_trait] +pub trait CryptoBackend: Send + Sync { + async fn generate_keypair(&self, algorithm: KeyAlgorithm) -> CryptoResult<KeyPair>; + async fn sign(&self, key: &PrivateKey, data: &[u8]) -> CryptoResult<Vec<u8>>; + async fn verify(&self, key: &PublicKey, data: &[u8], sig: &[u8]) -> CryptoResult<bool>; + async fn encrypt(&self, plaintext: &[u8]) -> CryptoResult<Vec<u8>>; + async fn decrypt(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; + + // Post-Quantum (OQS backend) + async fn kem_encapsulate(&self, public_key: &[u8]) -> CryptoResult<KemResult>; + async fn kem_decapsulate(&self, ciphertext: &[u8]) -> CryptoResult<Vec<u8>>; +} + +// src/storage/mod.rs +#[async_trait] +pub trait StorageBackend: Send + Sync { + async fn store_secret(&self, path: &str, data: &EncryptedData) -> StorageResult<()>; + async fn get_secret(&self, path: &str) -> StorageResult<EncryptedData>; + async fn delete_secret(&self, path: &str) -> StorageResult<()>; + async fn list_secrets(&self, prefix: &str) -> StorageResult<Vec<String>>; +} +``` + +### Crypto Backends + +| Backend | Algoritmos | Estado | +| --------- | ------------ | -------- | +| **OpenSSL** | RSA-2048/4096, ECDSA (P-256/384/521), AES-256-GCM | βœ… ProducciΓ³n | +| **OQS** | ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204) | βœ… **ProducciΓ³n (PQC)** | +| **AWS-LC** | RSA, ECDSA (PQC experimental) | ⚠️ Experimental | +| **RustCrypto** | AES-256-GCM, ChaCha20-Poly1305 | ⚠️ Testing | + +### Secrets Engines + +```rust +// src/engines/mod.rs +pub trait Engine: Send + Sync { + fn name(&self) -> &str; + fn engine_type(&self) -> &str; + async fn read(&self, path: &str) -> Result<Option<Value>>; + async fn write(&self, path: &str, data: &Value) -> Result<()>; + async fn delete(&self, path: &str) -> Result<()>; + async fn list(&self, prefix: &str) -> Result<Vec<String>>; +} + +// Engines disponibles +pub struct KvEngine { /* Versioned secret storage */ } +pub struct TransitEngine { /* Encryption-as-a-service */ } +pub struct PkiEngine { /* X.509 certificates */ } +pub struct DatabaseEngine { /* Dynamic credentials */ } +``` + +### Seal Mechanism (Shamir Secret Sharing) + +```rust +// src/core/seal.rs +pub struct SealMechanism { + state: SealState, + shares: Vec<SecretShare>, + threshold: u8, + total_shares: u8, +} + +pub enum SealState { + Sealed, + Unsealing { collected: usize }, + Unsealed { master_key: Vec<u8> }, +} +``` + +### API Endpoints + +```rust +// src/api/routes.rs +Router::new() + // System + .route("/v1/sys/health", get(health_check)) + .route("/v1/sys/init", post(initialize_vault)) + .route("/v1/sys/seal", post(seal_vault)) + .route("/v1/sys/unseal", post(unseal_vault)) + .route("/v1/sys/mounts", get(list_mounts)) + + // Secrets (dynamic routing by engine) + .route("/v1/*path", get(read_secret) + .post(write_secret) + .delete(delete_secret)) + + // Metrics + .route("/metrics", get(prometheus_metrics)) +``` + +### CLI Commands + +```bash +# Server +svault server --config svault.toml + +# Operator +svault operator init --shares 5 --threshold 3 +svault operator unseal --share <share> +svault operator seal +svault operator status + +# Secrets +svault secret read secret/myapp +svault secret write secret/myapp key=value +svault secret delete secret/myapp +svault secret list secret/ +``` + +### Feature Flags + +```toml +# Cargo.toml features +[features] +default = ["openssl", "filesystem", "server", "pqc"] + +# Crypto backends +openssl = ["dep:openssl"] +aws-lc = ["dep:aws-lc-rs"] +pqc = ["dep:oqs"] + +# Storage backends +filesystem = [] +surrealdb-storage = ["dep:surrealdb"] +etcd-storage = ["dep:etcd-client"] +postgresql-storage = ["dep:sqlx"] + +# Components +server = ["dep:axum", "dep:rustls"] +cli = ["dep:clap"] +cedar = ["dep:cedar-policy"] +``` + +--- + +## 6. IntegraciΓ³n Cross-Project + +### SurrealDB Schema Compartido + +```sql +-- ─── Namespace ──────────────────────────────────────────────── +DEFINE NAMESPACE portfolio; + +-- ─── Databases ──────────────────────────────────────────────── +DEFINE DATABASE vapora; +DEFINE DATABASE kogral; +DEFINE DATABASE typedialog; +DEFINE DATABASE provisioning; +DEFINE DATABASE secretumvault; + +-- ─── Shared Tables ──────────────────────────────────────────── + +-- Execution records (cross-project) +DEFINE TABLE executions SCHEMAFULL; +DEFINE FIELD project ON executions TYPE string; +DEFINE FIELD source ON executions TYPE string; -- vapora, kogral, etc. +DEFINE FIELD task_type ON executions TYPE string; +DEFINE FIELD agent_id ON executions TYPE option<string>; +DEFINE FIELD status ON executions TYPE string; +DEFINE FIELD duration_ms ON executions TYPE int; +DEFINE FIELD metadata ON executions FLEXIBLE TYPE object; +DEFINE FIELD created_at ON executions TYPE datetime DEFAULT time::now(); + +DEFINE INDEX idx_executions_project ON executions FIELDS project; +DEFINE INDEX idx_executions_source ON executions FIELDS source; +DEFINE INDEX idx_executions_created ON executions FIELDS created_at; + +-- Knowledge references (Kogral β†’ others) +DEFINE TABLE knowledge_refs SCHEMAFULL; +DEFINE FIELD source_project ON knowledge_refs TYPE string; +DEFINE FIELD node_id ON knowledge_refs TYPE string; +DEFINE FIELD target_project ON knowledge_refs TYPE string; +DEFINE FIELD target_id ON knowledge_refs TYPE string; +DEFINE FIELD ref_type ON knowledge_refs TYPE string; -- guideline, pattern, decision +DEFINE FIELD created_at ON knowledge_refs TYPE datetime DEFAULT time::now(); + +-- Configuration snapshots (TypeDialog β†’ Provisioning) +DEFINE TABLE config_snapshots SCHEMAFULL; +DEFINE FIELD form_id ON config_snapshots TYPE string; +DEFINE FIELD config_hash ON config_snapshots TYPE string; +DEFINE FIELD output ON config_snapshots FLEXIBLE TYPE object; +DEFINE FIELD target ON config_snapshots TYPE string; -- provisioning workflow +DEFINE FIELD created_at ON config_snapshots TYPE datetime DEFAULT time::now(); +``` + +### Integration Patterns + +```rust +// Example: Kogral β†’ Vapora integration + +// Vapora agent queries Kogral for guidelines before generating code +async fn get_project_context(task: &Task) -> Result<ProjectContext> { + let kogral = KogralMcpClient::connect().await?; + + // Get applicable guidelines + let guidelines = kogral.call("get_guidelines", json!({ + "topic": &task.task_type, + "include_shared": true, + })).await?; + + // Get relevant patterns + let patterns = kogral.call("search", json!({ + "query": &task.description, + "node_type": "pattern", + "semantic": true, + "limit": 5, + })).await?; + + // Get related decisions + let decisions = kogral.call("search", json!({ + "query": &task.description, + "node_type": "decision", + "limit": 3, + })).await?; + + Ok(ProjectContext { guidelines, patterns, decisions }) +} + +// Example: TypeDialog β†’ Provisioning integration + +// TypeDialog prov-gen backend generates Nickel for Provisioning +async fn generate_infrastructure(form_response: &FormResponse) -> Result<WorkflowId> { + // Generate Nickel config from form + let generator = ProvGenBackend::new(); + let iac = generator.generate(&form_response.into()).await?; + + // Submit to Provisioning + let provisioning = ProvisioningClient::connect().await?; + let workflow_id = provisioning.submit_workflow(iac).await?; + + // Record in shared DB + let db = SurrealClient::connect().await?; + db.create("config_snapshots", ConfigSnapshot { + form_id: form_response.form_id.clone(), + config_hash: hash(&iac), + output: form_response.values.clone(), + target: workflow_id.clone(), + }).await?; + + Ok(workflow_id) +} + +// Example: Vapora β†’ Kogral integration + +// Record agent execution as Kogral Execution node +async fn record_execution(result: &TaskResult) -> Result<()> { + let kogral = KogralMcpClient::connect().await?; + + kogral.call("add_execution", json!({ + "task_id": &result.task_id, + "agent_role": &result.agent_role, + "status": &result.status, + "duration_ms": result.duration_ms, + "tokens_used": result.tokens_used, + "output_summary": &result.summary, + })).await?; + + Ok(()) +} +``` + +--- + +## 7. MΓ©tricas y Calidad + +| Proyecto | Crates | Tests | LOC | Clippy | Unsafe | Doc | +| ---------- | -------- | ------- | ----- | -------- | -------- | ----- | +| Vapora | 13 | 218 | ~50K | 0 warn | 0 | 100% pub | +| Kogral | 3 | 56 | ~15K | 0 warn | 0 | 100% pub | +| TypeDialog | 8 | 3,818 | ~90K | 0 warn | 0 | 100% pub | +| Provisioning | 15+ | 218 | ~40K | 0 warn | 0 | 100% pub | +| SecretumVault | 1 | 50+ | ~11K | 0 warn | 0 | 100% pub | +| **Total** | **40+** | **4,360+** | **~206K** | **0** | **0** | **100%** | + +### Verification Commands + +```bash +# All projects +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace +cargo doc --workspace --no-deps + +# Coverage +cargo tarpaulin --workspace --out Html + +# Security audit +cargo audit + +# Benchmarks +cargo bench --workspace +``` + +--- + +*Documento generado: 2026-01-22* +*Tipo: info (especificaciones tΓ©cnicas completas)* diff --git a/docs/es/stratiumiops_market.md b/docs/es/stratiumiops_market.md new file mode 100644 index 0000000..faf2b62 --- /dev/null +++ b/docs/es/stratiumiops_market.md @@ -0,0 +1,410 @@ +# Portfolio de Desarrollo: La Plataforma Completa + +## El DesafΓ­o del Desarrollo Moderno + +Los equipos de desarrollo enfrentan una fragmentaciΓ³n creciente: + +- **10+ herramientas** para gestionar un proyecto tΓ­pico +- **Conocimiento disperso** en wikis, Slack, docs, cabezas +- **ConfiguraciΓ³n manual** repetida proyecto tras proyecto +- **Infraestructura compleja** sin validaciΓ³n ni rollback +- **IA desconectada** de las convenciones del equipo + +## La SoluciΓ³n: Un Ecosistema Integrado + +Cinco proyectos diseΓ±ados para trabajar juntos, cada uno resolviendo un dominio especΓ­fico. + +--- + +## Vapora: Tu Centro de Desarrollo + +### Una Plataforma, Todo el Flujo + +Vapora unifica la gestiΓ³n de proyectos, coordinaciΓ³n de equipos y agentes IA en una sola plataforma. + +**GestiΓ³n de Proyectos** + +- **Kanban visual**: Drag-and-drop intuitivo con columnas personalizables +- **ColaboraciΓ³n real-time**: Updates instantΓ‘neos, sin refresh +- **JerarquΓ­a clara**: Workspaces β†’ Projects β†’ Tasks con aislamiento +- **Tracking completo**: Historial de cambios con context + +**OrquestaciΓ³n Inteligente** + +- **12 roles de agente**: Architect, Developer, Reviewer, Tester, Documenter... +- **Aprendizaje continuo**: Los agentes mejoran con cada ejecuciΓ³n +- **Pipelines automatizados**: Secuencias con approval gates +- **Control de costos**: Presupuestos por rol con fallback automΓ‘tico + +**Multi-Tenant Nativo** + +- **Aislamiento por diseΓ±o**: Cada tenant en su scope +- **RBAC fine-grained**: PolΓ­ticas declarativas con Cedar +- **Audit trail**: Todo queda registrado + +**Para quiΓ©n es**: + +- Equipos de desarrollo que quieren unificar herramientas +- Organizaciones que usan agentes IA y necesitan visibilidad +- Plataformas multi-tenant que sirven a mΓΊltiples equipos + +--- + +## Kogral: Tu Memoria de Equipo + +### El Conocimiento que No se Pierde + +Kogral captura las decisiones, patterns y guidelines de tu equipo en un formato que perdura. + +**6 Tipos de Conocimiento** + +| Tipo | PropΓ³sito | +| ------ | ----------- | +| **Notes** | Observaciones y notas generales | +| **Decisions** | ADRs con contexto, decisiΓ³n y consecuencias | +| **Guidelines** | EstΓ‘ndares del equipo y organizaciΓ³n | +| **Patterns** | Soluciones probadas y documentadas | +| **Journals** | Diario de desarrollo dΓ­a a dΓ­a | +| **Executions** | Registros de agentes IA | + +**Git-Native** + +- Todo en markdown versionado +- Sin dependencia de SaaS externos +- Backup y restore triviales +- Code review de conocimiento + +**Herencia de Guidelines** + +```text +OrganizaciΓ³n define estΓ‘ndares base + ↓ +Proyecto especializa para su contexto + ↓ +Desarrollador ve guidelines efectivos +``` + +**IntegraciΓ³n con Claude Code** + +- 7 herramientas MCP nativas +- Consulta guidelines antes de generar cΓ³digo +- Busca patterns relevantes automΓ‘ticamente +- Registra decisiones durante el desarrollo + +**Para quiΓ©n es**: + +- Equipos que pierden conocimiento con rotaciΓ³n +- Organizaciones con mΓΊltiples proyectos +- Desarrolladores que usan Claude Code +- Equipos con requisitos de compliance/audit + +--- + +## TypeDialog: Tu Interfaz Universal + +### Una DefiniciΓ³n, Todas las Plataformas + +TypeDialog te permite definir formularios una vez y ejecutarlos en CLI, TUI, Web o con agentes IA. + +**6 Backends de EjecuciΓ³n** + +| Backend | Uso TΓ­pico | +| --------- | ----------- | +| **CLI** | Scripts de automatizaciΓ³n, CI/CD | +| **TUI** | Herramientas de administraciΓ³n | +| **Web** | Aplicaciones SaaS, formularios pΓΊblicos | +| **AI** | BΓΊsqueda semΓ‘ntica, RAG | +| **Agent** | EjecuciΓ³n de agentes LLM | +| **Prov-gen** | GeneraciΓ³n de infraestructura | + +**ValidaciΓ³n Type-Safe** + +- Contratos Nickel para validaciΓ³n pre-runtime +- Errores detectados antes de ejecutar +- Schemas reutilizables entre proyectos + +**Formularios Avanzados** + +- 8 tipos de campo (text, select, multi-select, date, password...) +- Campos condicionales y dinΓ‘micos +- Grupos repetibles +- Fragments reutilizables con herencia +- InternacionalizaciΓ³n con Fluent + +**Agentes desde Markdown** + +Define agentes en archivos `.agent.mdx`: +- 4 proveedores LLM (Claude, OpenAI, Gemini, Ollama) +- Templates con variables +- ValidaciΓ³n de output +- Streaming en tiempo real + +**GeneraciΓ³n de Infraestructura** + +- 6 clouds soportados (AWS, GCP, Azure, Hetzner, UpCloud, LXD) +- Formularios β†’ ConfiguraciΓ³n validada β†’ IaC listo +- 7 capas de validaciΓ³n + +**Para quiΓ©n es**: + +- Equipos que mantienen CLI y Web en paralelo +- DevOps que necesitan wizards de configuraciΓ³n +- Organizaciones con requisitos multi-idioma +- Equipos que quieren automatizar con agentes + +--- + +## Provisioning: Tu Infraestructura Controlada + +### IaC Declarativo + Seguridad Enterprise + +Provisioning combina configuraciΓ³n tipada, orquestaciΓ³n avanzada y seguridad completa. + +**Nickel IaC** + +- Lenguaje tipado con lazy evaluation +- ValidaciΓ³n en compilaciΓ³n, no en runtime +- Schemas componibles y reutilizables +- Mejor que YAML/HCL para configuraciΓ³n compleja + +**Multi-Cloud Real** + +| Provider | Capacidades | +| ---------- | ------------- | +| **AWS** | EC2, EKS, RDS, S3, IAM, VPC | +| **UpCloud** | Servers, networking, storage | +| **Local** | LXD containers, VMs | + +**Orchestrator Avanzado** + +- ResoluciΓ³n automΓ‘tica de dependencias +- Checkpoints con recovery +- Rollback automΓ‘tico ante fallos +- EjecuciΓ³n paralela con balanceo +- Retry con exponential backoff + +**Seguridad Enterprise** + +| Componente | Capacidad | +| ------------ | ----------- | +| **AutenticaciΓ³n** | JWT + Argon2id + MFA (TOTP + WebAuthn) | +| **AutorizaciΓ³n** | Cedar policies (RBAC fine-grained) | +| **Secrets** | Dynamic secrets con TTL | +| **KMS** | 5 backends (RustyVault, Age, AWS, Vault, Cosmian) | +| **Audit** | 7 aΓ±os retenciΓ³n, 5 formatos export | +| **Break-glass** | Multi-party approval | + +**39,699 lΓ­neas de cΓ³digo de seguridad** en 12 componentes. + +**IA Integrada** + +- MCP Server nativo (1000x mΓ‘s rΓ‘pido que Python) +- RAG con 1,200+ documentos de dominio +- Consultas en lenguaje natural +- GeneraciΓ³n de Nickel validado + +**Developer Experience** + +- CLI de 211 lΓ­neas (84% reducciΓ³n) +- 80+ shortcuts (`s` β†’ server, `t` β†’ taskserv) +- GuΓ­as interactivas integradas +- Sistema de configuraciΓ³n con 476+ accessors + +**Para quiΓ©n es**: + +- Equipos DevOps que quieren IaC tipado +- Organizaciones multi-cloud +- Equipos con requisitos de compliance +- Organizaciones que necesitan audit completo + +--- + +## SecretumVault: Tu BΓ³veda Post-CuΓ‘ntica + +### CriptografΓ­a del Futuro, Hoy + +SecretumVault es el primer vault Rust con criptografΓ­a post-cuΓ‘ntica lista para producciΓ³n. + +**CriptografΓ­a AgnΓ³stica** + +| Backend | Algoritmos | Estado | +| --------- | ------------ | -------- | +| **OpenSSL** | RSA, ECDSA, AES-256-GCM | ProducciΓ³n | +| **OQS** | ML-KEM-768, ML-DSA-65 | **ProducciΓ³n (PQC)** | +| **AWS-LC** | RSA, ECDSA | Experimental | +| **RustCrypto** | AES-GCM, ChaCha20 | Testing | + +**Motores de Secretos** + +- **KV Engine**: Almacenamiento versionado con metadata +- **Transit Engine**: Encryption-as-a-service con rotaciΓ³n +- **PKI Engine**: Certificados X.509 y gestiΓ³n de CA +- **Database Engine**: Credenciales dinΓ‘micas con TTL + +**Storage Multi-Backend** + +| Backend | Uso | +| --------- | ----- | +| **Filesystem** | Desarrollo, single-node | +| **etcd** | Kubernetes, alta disponibilidad | +| **SurrealDB** | Queries complejas, time-series | +| **PostgreSQL** | Enterprise, ACID | + +**Seguridad Enterprise** + +- **Shamir Secret Sharing**: Unsealing distribuido (K de N) +- **Cedar ABAC**: PolΓ­ticas AWS-compatible +- **TLS/mTLS**: Cifrado en trΓ‘nsito con verificaciΓ³n cliente +- **Audit Logging**: Todos los eventos registrados + +**Para quiΓ©n es**: + +- Equipos preparΓ‘ndose para amenazas cuΓ‘nticas +- Organizaciones con requisitos de agilidad criptogrΓ‘fica +- Plataformas que necesitan vault Rust-native +- Equipos multi-cloud con self-hosting + +--- + +## El Ecosistema en AcciΓ³n + +### Escenario 1: Desarrollo de Feature + +```text +1. Kogral proporciona guidelines y patterns al equipo +2. TypeDialog captura requisitos con formularios validados +3. SecretumVault gestiona credenciales y API keys +4. Vapora coordina agentes (Architect β†’ Developer β†’ Reviewer) +5. Kogral registra decisiones tomadas +6. Provisioning despliega cambios de infra necesarios +``` + +### Escenario 2: Onboarding de Equipo + +```text +1. Kogral exporta knowledge graph del proyecto +2. TypeDialog presenta quizzes interactivos +3. Vapora asigna tareas de onboarding progresivas +4. Provisioning configura entornos de desarrollo +``` + +### Escenario 3: MigraciΓ³n de Infraestructura + +```text +1. Kogral documenta ADRs de la migraciΓ³n +2. TypeDialog valida parΓ‘metros de configuraciΓ³n +3. Provisioning ejecuta con checkpoints y rollback +4. Vapora orquesta monitoreo y reportes +``` + +### Escenario 4: Nuevo Proyecto + +```text +1. TypeDialog wizard para configuraciΓ³n inicial +2. Provisioning genera infraestructura +3. Kogral crea knowledge graph inicial +4. Vapora configura pipelines de desarrollo +``` + +--- + +## Por QuΓ© Este Ecosistema + +### Frente a FragmentaciΓ³n + +| Problema | SoluciΓ³n TΓ­pica | Nuestra SoluciΓ³n | +| ---------- | ----------------- | ------------------ | +| GestiΓ³n proyectos | Jira + Notion + ... | Vapora (todo en uno) | +| Conocimiento | Wiki + Docs + Slack | Kogral (git-native) | +| ConfiguraciΓ³n | Scripts + YAML | TypeDialog (type-safe) | +| Secretos | HashiCorp Vault / SaaS | SecretumVault (PQC) | +| Infraestructura | Terraform + Ansible | Provisioning (Nickel) | +| IA | Herramientas separadas | Integrada en todo | + +### Ventajas TΓ©cnicas + +| Aspecto | Nosotros | Alternativas | +| --------- | ---------- | -------------- | +| **Stack** | Rust end-to-end | Python/JS/Go mix | +| **Config** | Nickel (typed) | YAML/JSON (runtime errors) | +| **Multi-tenant** | SurrealDB scopes | DIY isolation | +| **IA** | Nativa en todos | Retrofitted | +| **Self-hosted** | Completo | SaaS lock-in | + +### MΓ©tricas de Confianza + +| MΓ©trica | Valor | +| --------- | ------- | +| Crates Rust | 40+ | +| Tests | 4,360+ | +| LΓ­neas de cΓ³digo | ~206K | +| LΓ­neas de seguridad | 39K | +| Proveedores LLM | 4 | +| Clouds soportados | 6 | +| Backends crypto | 4 (incl. PQC) | + +--- + +## Comenzar + +### AdopciΓ³n Flexible + +Cada proyecto funciona de forma independiente: + +1. **Solo necesitas knowledge management?** β†’ Kogral +2. **Solo necesitas forms multi-backend?** β†’ TypeDialog +3. **Solo necesitas vault post-cuΓ‘ntico?** β†’ SecretumVault +4. **Solo necesitas orquestaciΓ³n de desarrollo?** β†’ Vapora +5. **Solo necesitas IaC enterprise?** β†’ Provisioning + +### AdopciΓ³n Progresiva + +Para mΓ‘ximo beneficio: + +```text +1. Kogral β†’ Establece base de conocimiento +2. TypeDialog β†’ Habilita inputs estructurados +3. SecretumVault β†’ GestiΓ³n segura de secretos +4. Vapora β†’ Orquesta desarrollo +5. Provisioning β†’ Infraestructura completa +``` + +### IntegraciΓ³n Natural + +Los proyectos se conectan automΓ‘ticamente: + +- Comparten SurrealDB para estado +- Usan Nickel para configuraciΓ³n +- Hablan el mismo protocolo MCP +- Comparten patterns de Axum/Leptos + +--- + +## Stack TecnolΓ³gico + +Todo el ecosistema construido sobre: + +| TecnologΓ­a | PropΓ³sito | +| ------------ | ----------- | +| **Rust** | Performance, type-safety, zero-cost abstractions | +| **Nickel** | Configuration language con validaciΓ³n | +| **SurrealDB** | Multi-model database con scopes | +| **Axum** | Web framework async composable | +| **Leptos** | Frontend WASM reactivo | +| **Ratatui** | Terminal UI | +| **NATS** | Messaging con JetStream | +| **rig-core** | LLM abstraction multi-provider | +| **OQS** | Post-quantum cryptography (ML-KEM, ML-DSA) | + +--- + +## Contacto + +- **Repositorios**: GitHub (proyectos privados) +- **Licencia**: Propietaria / Por definir +- **Stack**: 100% Rust + +--- + +*Un ecosistema. Cinco proyectos. IntegraciΓ³n real.* +*Desarrollo moderno sin fragmentaciΓ³n.* diff --git a/docs/es/stratiumiops_position.md b/docs/es/stratiumiops_position.md new file mode 100644 index 0000000..8dee921 --- /dev/null +++ b/docs/es/stratiumiops_position.md @@ -0,0 +1,910 @@ +# Portfolio de Proyectos: Posicionamiento EstratΓ©gico Completo + +## Resumen Ejecutivo + +Portfolio de cinco proyectos Rust que conforman un ecosistema completo para desarrollo de software moderno: + +| Proyecto | Dominio Principal | Capacidades Clave | +| ---------- | ------------------- | ------------------- | +| **Vapora** | Plataforma de Desarrollo | OrquestaciΓ³n, Kanban, multi-tenant, LLM routing, knowledge graph | +| **Kogral** | GestiΓ³n de Conocimiento | Knowledge graph, ADRs, patterns, guidelines, bΓΊsqueda semΓ‘ntica | +| **TypeDialog** | InteracciΓ³n y AutomatizaciΓ³n | Forms multi-backend, agentes, IaC generation, i18n, validaciΓ³n | +| **Provisioning** | Infraestructura | IaC declarativo, multi-cloud, seguridad enterprise, orquestaciΓ³n | +| **SecretumVault** | Seguridad | GestiΓ³n de secretos, criptografΓ­a post-cuΓ‘ntica, multi-backend | + +--- + +## 1. Vapora: Plataforma de Desarrollo Inteligente + +### VisiΓ³n General + +Vapora es una **plataforma de orquestaciΓ³n de desarrollo** que unifica gestiΓ³n de proyectos, coordinaciΓ³n de agentes IA, y visibilidad completa del ciclo de desarrollo. + +### Capacidades Completas + +#### GestiΓ³n de Proyectos + +| Funcionalidad | DescripciΓ³n | +| --------------- | ------------- | +| **Kanban Board** | Drag-and-drop con columnas Todo β†’ Doing β†’ Review β†’ Done | +| **Real-time Collaboration** | Updates optimistas, WebSocket sync | +| **Task Tracking** | Prioridades, tags, asignaciones, ordenamiento | +| **Project Hierarchy** | Workspaces β†’ Projects β†’ Tasks con scopes aislados | +| **Change Tracking** | Historial de cambios con impact analysis | + +#### Multi-Tenancy y Seguridad + +| Funcionalidad | DescripciΓ³n | +| --------------- | ------------- | +| **SurrealDB Scopes** | Aislamiento nativo por tenant | +| **Cedar RBAC** | PolΓ­ticas fine-grained declarativas | +| **JWT Auth** | Tokens con refresh rotation | +| **Audit Trail** | Logging de cambios significativos | + +#### OrquestaciΓ³n de Agentes + +| Funcionalidad | DescripciΓ³n | +| --------------- | ------------- | +| **12 Roles** | Architect, Developer, Reviewer, Tester, Documenter, etc. | +| **Learning Profiles** | Expertise por tipo de tarea con recency bias (3x ΓΊltimos 7 dΓ­as) | +| **Pipeline Execution** | Secuencias con approval gates | +| **NATS JetStream** | CoordinaciΓ³n async con delivery garantizado | + +#### LLM Router + +| Funcionalidad | DescripciΓ³n | +| --------------- | ------------- | +| **4 Providers** | Claude, OpenAI, Gemini, Ollama | +| **Budget Control** | LΓ­mites por rol (mensual/semanal) | +| **Auto-Fallback** | Cambio a provider mΓ‘s barato cuando excede budget | +| **Cost Tracking** | Tokens y costos por request/rol/provider | + +#### Knowledge Graph Temporal + +| Funcionalidad | DescripciΓ³n | +| --------------- | ------------- | +| **Execution History** | Nodos con relaciones causales | +| **Learning Curves** | Agregaciones diarias para tracking de mejora | +| **Similarity Search** | Recomendaciones basadas en tareas pasadas | + +#### Frontend (Leptos WASM) + +| Funcionalidad | DescripciΓ³n | +| --------------- | ------------- | +| **Glassmorphism UI** | EstΓ©tica vaporwave moderna | +| **Responsive** | Mobile a ultra-wide | +| **Optimistic Updates** | UX fluida sin esperar server | +| **UnoCSS** | Atomic CSS Tailwind-compatible | + +#### Observabilidad + +| Funcionalidad | DescripciΓ³n | +| --------------- | ------------- | +| **Prometheus Metrics** | Request latency, agent duration, token usage | +| **OpenTelemetry** | Tracing distribuido | +| **Structured Logging** | JSON output con tracing | + +### Arquitectura + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Vapora (13 crates, 218+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Frontend β”‚ β”‚ Backend β”‚ β”‚ Agent System β”‚ β”‚ +β”‚ β”‚ (Leptos) │──│ (Axum) │──│ (Coordinator + NATS) β”‚ β”‚ +β”‚ β”‚ Kanban UI β”‚ β”‚ 40+ APIs β”‚ β”‚ Learning + Pipelines β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LLM Router β”‚ β”‚ +β”‚ β”‚ Claude β”‚ OpenAI β”‚ Gemini β”‚ Ollama β”‚ Budget β”‚ Fallback β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Persistence: SurrealDB (scopes) + NATS JetStream β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Kogral: Sistema de GestiΓ³n de Conocimiento + +### VisiΓ³n General + +Kogral es un **knowledge graph git-native** diseΓ±ado para capturar, conectar y consultar el conocimiento de equipos de desarrollo. + +### Capacidades Completas + +#### Modelo de Conocimiento + +| Tipo de Nodo | PropΓ³sito | +| -------------- | ----------- | +| **Note** | Notas generales, observaciones | +| **Decision (ADR)** | Architectural Decision Records con context/decision/consequences | +| **Guideline** | EstΓ‘ndares de equipo/organizaciΓ³n | +| **Pattern** | Soluciones reutilizables documentadas | +| **Journal** | Diario de desarrollo (progreso, blockers, learnings) | +| **Execution** | Registros de ejecuciΓ³n de agentes | + +| Tipo de RelaciΓ³n | PropΓ³sito | +| ------------------ | ----------- | +| **relates_to** | ConexiΓ³n general | +| **depends_on** | Dependencia | +| **implements** | ImplementaciΓ³n de concepto | +| **extends** | ExtensiΓ³n/especializaciΓ³n | +| **supersedes** | Reemplaza versiΓ³n anterior | +| **explains** | DocumentaciΓ³n/explicaciΓ³n | + +#### Storage Multi-Backend + +| Backend | CaracterΓ­sticas | +| --------- | ----------------- | +| **Filesystem** | Git-friendly, markdown + YAML frontmatter, `.kogral/` | +| **SurrealDB** | Escalable, queries de grafo, conocimiento compartido org | +| **Memory** | Testing con DashMap | + +#### BΓΊsqueda + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Text Search** | BΓΊsqueda full-text sobre contenido | +| **Semantic Search** | Embeddings con fastembed (local) o cloud providers | +| **Graph Traversal** | NavegaciΓ³n por relaciones | +| **Filtering** | Por tipo, tags, fecha, metadata | + +#### Herencia de Guidelines + +```text +Org Guidelines (base) + β”‚ + β–Ό override +Project Guidelines (especΓ­ficas) + β”‚ + β–Ό merge con prioridad +Effective Guidelines (aplicadas) +``` + +#### Logseq Compatibility + +| Feature | Soporte | +| --------- | --------- | +| **Outliner Blocks** | Estructura jerΓ‘rquica preservada | +| **Task Statuses** | TODO, DOING, DONE, LATER, NOW, WAITING, CANCELLED | +| **Wikilinks** | `[[referencias]]` bidireccionales | +| **Properties** | Metadata en frontmatter | +| **Tags** | #tags preservados | + +#### MCP Server (Claude Code) + +| Tool | FunciΓ³n | +| ------ | --------- | +| `search` | BΓΊsqueda text/semΓ‘ntica | +| `add_note` | Crear nota | +| `add_decision` | Crear ADR guiado | +| `link` | Establecer relaciΓ³n | +| `get_guidelines` | Obtener guidelines aplicables | +| `list_graphs` | Listar grafos disponibles | +| `export` | Exportar a formato | + +#### Export y Templates + +| Formato | Soporte | +| --------- | --------- | +| **Markdown** | Con frontmatter YAML | +| **JSON** | Estructura completa | +| **YAML** | Human-readable | +| **Tera Templates** | GeneraciΓ³n personalizada | + +### Arquitectura + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Kogral (3 crates, 56 tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ MCP Server β”‚ β”‚ Core Library β”‚ β”‚ +β”‚ β”‚ 13 cmds β”‚ β”‚ Claude Codeβ”‚ β”‚ Models + Storage + β”‚ β”‚ +β”‚ β”‚ clap β”‚ β”‚ 7 tools β”‚ β”‚ Query + Embeddings β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem (.kogral/) β”‚ SurrealDB β”‚ Memory (test) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Embeddings: fastembed (local) β”‚ rig-core (cloud) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 3. TypeDialog: Plataforma de InteracciΓ³n Unificada + +### VisiΓ³n General + +TypeDialog es un **sistema de formularios y automatizaciΓ³n** que unifica mΓΊltiples interfaces (CLI, TUI, Web) con ejecuciΓ³n de agentes y generaciΓ³n de infraestructura. + +### Capacidades Completas + +#### Backends de EjecuciΓ³n + +| Backend | TecnologΓ­a | Uso TΓ­pico | +| --------- | ------------ | ------------ | +| **CLI** | inquire | Scripts, CI/CD, automatizaciΓ³n | +| **TUI** | ratatui | Dashboards terminal, admin tools | +| **Web** | axum + HTMX | SaaS, formularios pΓΊblicos | +| **AI** | tantivy + petgraph | RAG, bΓΊsqueda semΓ‘ntica | +| **Agent** | Tera + Nickel | EjecuciΓ³n LLM desde .agent.mdx | +| **Prov-gen** | Nickel + Templates | IaC multi-cloud | + +#### Tipos de Campo + +| Tipo | CaracterΓ­sticas | +| ------ | ----------------- | +| **text** | ValidaciΓ³n regex, longitud, patterns | +| **confirm** | Yes/No boolean | +| **select** | Single choice con filtrado | +| **multi-select** | Multiple choice (list/grid/dropdown) | +| **password** | Masked input | +| **custom** | Tipos definidos por usuario | +| **editor** | Multi-line con soporte editor externo | +| **date** | Date/time picker | + +#### ValidaciΓ³n y Contratos + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Regex Patterns** | ValidaciΓ³n por expresiΓ³n regular | +| **Length Constraints** | min/max length | +| **Cross-field Logic** | ValidaciΓ³n entre campos | +| **Nickel Contracts** | Type-safe pre/post validaciΓ³n | +| **Custom Validators** | Funciones de validaciΓ³n personalizadas | + +#### Forms Avanzados + +| Feature | DescripciΓ³n | +| --------- | ------------- | +| **Sections** | AgrupaciΓ³n lΓ³gica de campos | +| **Conditional Fields** | Visibilidad dinΓ‘mica basada en valores | +| **Smart Defaults** | Valores por defecto computados | +| **Repeating Groups** | Campos repetibles dinΓ‘micamente | +| **Fragment Composition** | Templates reutilizables con herencia | +| **Includes** | ImportaciΓ³n de fragmentos | + +#### InternacionalizaciΓ³n (i18n) + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Fluent Bundles** | Archivos .ftl para traducciones | +| **Auto-Locale** | DetecciΓ³n automΓ‘tica via sys-locale | +| **Form Translation** | Labels, hints, errors traducidos | +| **Extraction** | Auto-extracciΓ³n de strings desde schemas | + +#### Output Formats + +| Formato | Soporte | +| --------- | --------- | +| **JSON** | EstΓ‘ndar, compatible universal | +| **YAML** | Human-readable | +| **TOML** | ConfiguraciΓ³n Rust-friendly | +| **Nickel** | Type-safe con contratos | + +#### Agent System + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **MDX Format** | Markdown extendido con frontmatter YAML | +| **4 LLM Providers** | Claude, OpenAI, Gemini, Ollama | +| **Tera Templates** | Variables, imports, shell commands | +| **Output Validation** | Format, content, length checks | +| **Streaming** | Real-time token streaming | + +#### IaC Generation (Prov-gen) + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **6 Cloud Providers** | AWS, GCP, Azure, Hetzner, UpCloud, LXD | +| **7-Layer Validation** | Pipeline de validaciΓ³n completo | +| **AI-Assisted** | ConfiguraciΓ³n opcional con Claude/Ollama | +| **Template Fragments** | Fragmentos especΓ­ficos por provider | + +#### Seguridad + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Field Encryption** | Cifrado a nivel de campo | +| **Password Masking** | En todos los backends | +| **Validation Contracts** | PrevenciΓ³n de datos invΓ‘lidos | + +### Arquitectura + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TypeDialog (8 crates, 3,818 tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ Form Definition (TOML) β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”‚ +β”‚ β”‚ BackendFactory β”‚β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β–Ό β–Ό β–Ό β”‚ β”‚ +β”‚ CLI TUI Web AI Agent Prov-gen β”‚ β”‚ +β”‚(inquire)(ratatui)(axum)(tantivy)(Tera)(Nickel) β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Output: JSON β”‚ YAML β”‚ TOML β”‚ Nickel β”‚ β”‚ +β”‚ β”‚ Validation: Nickel Contracts β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 4. Provisioning: Plataforma de Infraestructura + +### VisiΓ³n General + +Provisioning es una **plataforma IaC enterprise** que combina configuraciΓ³n declarativa (Nickel), orquestaciΓ³n avanzada, seguridad completa, y asistencia IA. + +### Capacidades Completas + +#### CLI Modular + +| Aspecto | Detalle | +| --------- | --------- | +| **TamaΓ±o** | 211 lΓ­neas (84% reducciΓ³n desde 1,329) | +| **Shortcuts** | 80+ atajos (`s` β†’ server, `t` β†’ taskserv) | +| **MΓ³dulos** | 7 dominios (infra, orchestration, dev, workspace, config, utils, gen) | +| **GuΓ­as** | Interactivas con glow/bat/less | + +#### Sistema de ConfiguraciΓ³n + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **476+ Accessors** | Reemplazo de 200+ variables de entorno | +| **Hierarchical Loading** | defaults β†’ user β†’ project β†’ infra β†’ env β†’ runtime | +| **Interpolation** | Variables expandidas dinΓ‘micamente | +| **Multi-format** | TOML, YAML, Nickel | + +#### Multi-Cloud Support + +| Provider | Capacidades | +| ---------- | ------------- | +| **AWS** | EC2, EKS, RDS, S3, IAM, VPC | +| **UpCloud** | Servers, networking, storage | +| **Local** | LXD containers, local VMs | + +#### Batch Workflows + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Mixed Providers** | AWS + UpCloud + local en mismo workflow | +| **Schema Integration** | KCL/Nickel type-safe | +| **Dependency Resolution** | Topological sorting automΓ‘tico | +| **State Management** | Checkpoints con recovery | +| **Rollback** | AutomΓ‘tico ante fallos | +| **Token Efficiency** | 85-90% | + +#### Orchestrator HΓ­brido + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Rust + Nushell** | Combina rendimiento y flexibilidad | +| **File Persistence** | Estado persistido en filesystem | +| **Priority Processing** | Colas con prioridad | +| **Retry Logic** | Exponential backoff | +| **REST API** | IntegraciΓ³n externa | +| **Parallel Execution** | Load balancing | + +#### Workspace Management + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Single-command Switch** | Cambio instantΓ‘neo entre entornos | +| **Tracking** | Last-used timestamps | +| **Registry** | Registro centralizado | +| **Preferences** | ConfiguraciΓ³n por usuario | + +#### Test Environment Service + +| Tipo | DescripciΓ³n | +| ------ | ------------- | +| **Single Taskserv** | Test de servicio individual | +| **Server Simulation** | SimulaciΓ³n de servidor completo | +| **Multi-node Clusters** | Clusters con topologΓ­as (K8s HA, etcd) | + +#### Platform Installer + +| Modo | Recursos | +| ------ | ---------- | +| **Solo** | 2 CPU, 4GB RAM | +| **MultiUser** | 4 CPU, 8GB RAM | +| **CICD** | 8 CPU, 16GB RAM | +| **Enterprise** | 16 CPU, 32GB RAM | + +| Interface | DescripciΓ³n | +| ----------- | ------------- | +| **TUI** | Ratatui interactivo | +| **CLI** | Headless automation | +| **Unattended** | Sin interacciΓ³n | + +#### Version Management + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **Centralized** | Todas las versiones en Nickel | +| **Bash-compatible** | GeneraciΓ³n de archivo sourceable | +| **Auto-discovery** | DetecciΓ³n de versiones de providers | +| **Shell Integration** | `source /provisioning/core/versions` | + +#### Nushell Plugins + +| Plugin | FunciΓ³n | Mejora | +| -------- | --------- | -------- | +| **auth** | AutenticaciΓ³n | 10-50x vs HTTP | +| **KMS** | GestiΓ³n de claves | Nativo OS keyring | +| **orchestrator** | CoordinaciΓ³n workflows | Performance | + +#### Sistema de Seguridad Completo + +| Componente | Capacidades | +| ------------ | ------------- | +| **AutenticaciΓ³n** | JWT + Argon2id hashing | +| **MFA** | TOTP + WebAuthn/FIDO2 | +| **AutorizaciΓ³n** | Cedar policy engine (RBAC fine-grained) | +| **Secrets** | Dynamic secrets con TTL | +| **KMS** | 5 backends (RustyVault, Age, AWS KMS, Vault, Cosmian) | +| **Encryption** | Envelope encryption | +| **Audit** | 7 aΓ±os retenciΓ³n, 5 formatos export | +| **Break-glass** | Multi-party approval | + +**MΓ©tricas de Seguridad**: 39,699 lΓ­neas, 12 componentes + +#### IA Integration + +| Capacidad | DescripciΓ³n | +| ----------- | ------------- | +| **MCP Server** | Rust-native (1000x vs Python) | +| **RAG System** | 1,200+ docs de dominio | +| **NLP** | Intent recognition, entity extraction | +| **Multi-provider** | OpenAI, Claude, Ollama | +| **Nickel Generation** | Con validaciΓ³n automΓ‘tica | + +### Arquitectura + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Provisioning (v5.0.0-nickel, 218+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ Control β”‚ β”‚ Platform β”‚ β”‚ +β”‚ β”‚ 211 lines β”‚ β”‚ Center β”‚ β”‚ Orchestrator β”‚ β”‚ +β”‚ β”‚ 80+ shorts β”‚ β”‚ (Axum) β”‚ β”‚ (Rust/Nu hybrid) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Extensions β”‚ β”‚ +β”‚ β”‚ Providers: AWS β”‚ UpCloud β”‚ Local β”‚ β”‚ +β”‚ β”‚ Taskservs: 50+ infrastructure services β”‚ β”‚ +β”‚ β”‚ Clusters: K8s, etcd, etc. templates β”‚ β”‚ +β”‚ β”‚ Workflows: Automation definitions β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Security Layer (39K lines, 12 components) β”‚ β”‚ +β”‚ β”‚ JWT β”‚ Cedar β”‚ MFA β”‚ KMS β”‚ Audit β”‚ Secrets β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ AI Layer: MCP Server β”‚ RAG (1200+ docs) β”‚ LLM Providers β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ State: SurrealDB β”‚ Filesystem β”‚ Nickel Schemas β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 5. SecretumVault: GestiΓ³n de Secretos Post-CuΓ‘ntica + +### VisiΓ³n General + +SecretumVault es un **sistema de gestiΓ³n de secretos** escrito en Rust con **criptografΓ­a post-cuΓ‘ntica lista para producciΓ³n** (ML-KEM-768, ML-DSA-65 segΓΊn NIST FIPS 203/204). + +### Capacidades Completas + +#### Backends CriptogrΓ‘ficos + +| Backend | Algoritmos | Estado | +| --------- | ------------ | -------- | +| **OpenSSL** | RSA-2048/4096, ECDSA (P-256/384/521), AES-256-GCM | βœ… ProducciΓ³n | +| **OQS** | ML-KEM-768, ML-DSA-65 | βœ… **ProducciΓ³n (PQC)** | +| **AWS-LC** | RSA, ECDSA (PQC experimental) | ⚠️ Experimental | +| **RustCrypto** | AES-256-GCM, ChaCha20-Poly1305 | ⚠️ Testing | + +#### Motores de Secretos + +| Motor | Funcionalidad | +| ------- | --------------- | +| **KV Engine** | Almacenamiento versionado de secretos | +| **Transit Engine** | Encryption-as-a-service con rotaciΓ³n de claves | +| **PKI Engine** | GeneraciΓ³n de certificados X.509, CA management | +| **Database Engine** | Credenciales dinΓ‘micas con TTL | + +#### Backends de Storage + +| Backend | Uso TΓ­pico | +| --------- | ------------ | +| **Filesystem** | Desarrollo, single-node | +| **etcd** | Kubernetes, alta disponibilidad | +| **SurrealDB** | Queries complejas, time-series | +| **PostgreSQL** | Enterprise, ACID garantizado | + +#### Seguridad Enterprise + +| Componente | Capacidades | +| ------------ | ------------- | +| **Seal/Unseal** | Shamir Secret Sharing (K de N threshold) | +| **AutenticaciΓ³n** | Token-based con TTL configurable | +| **AutorizaciΓ³n** | Cedar ABAC (AWS-compatible policies) | +| **TLS/mTLS** | Cifrado en trΓ‘nsito + verificaciΓ³n cliente | +| **Audit** | Logging estructurado de todos los eventos | + +### Arquitectura + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SecretumVault (~11K LOC, 50+ tests) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CLI β”‚ β”‚ REST API β”‚ β”‚ Secrets Engines β”‚ β”‚ +β”‚ β”‚ (clap) β”‚ β”‚ (Axum) β”‚ β”‚ KV/Transit/PKI/DB β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VaultCore β”‚ β”‚ +β”‚ β”‚ Seal (Shamir) β”‚ TokenManager β”‚ Cedar ABAC β”‚ Metrics β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Crypto Backends β”‚ β”‚ +β”‚ β”‚ OpenSSL β”‚ OQS (PQC) β”‚ AWS-LC β”‚ RustCrypto β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Backends β”‚ β”‚ +β”‚ β”‚ Filesystem β”‚ etcd β”‚ SurrealDB β”‚ PostgreSQL β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 6. Matriz de Funcionalidades Completa + +### Capacidades por CategorΓ­a + +#### GestiΓ³n de Proyectos + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Kanban Board | βœ… Leptos | - | - | - | - | +| Task Management | βœ… Full | - | - | - | - | +| Project Hierarchy | βœ… Scopes | βœ… Graphs | - | βœ… Workspaces | - | +| Real-time Collab | βœ… WebSocket | - | - | - | - | +| Change Tracking | βœ… History | βœ… Git | - | βœ… Audit | βœ… Audit | + +#### Conocimiento y DocumentaciΓ³n + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Knowledge Graph | βœ… Temporal | βœ… 6 tipos | - | - | - | +| ADRs | - | βœ… Nativo | - | - | - | +| Patterns Library | - | βœ… Nativo | - | - | - | +| Guidelines | - | βœ… Herencia | - | βœ… Schemas | - | +| Semantic Search | βœ… KG | βœ… fastembed | βœ… Tantivy | βœ… RAG | - | + +#### InteracciΓ³n Usuario + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Web UI | βœ… Leptos | - | βœ… Axum | βœ… Leptos | - | +| CLI | - | βœ… 13 cmds | βœ… inquire | βœ… 80+ shorts | βœ… svault | +| TUI | - | - | βœ… ratatui | βœ… ratatui | - | +| Forms | - | - | βœ… 8 tipos | - | - | +| i18n | - | - | βœ… Fluent | - | - | + +#### AutomatizaciΓ³n + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Pipelines | βœ… Agent | - | βœ… Agent MDX | βœ… Workflows | - | +| LLM Agents | βœ… 12 roles | - | βœ… Multi-prov | βœ… MCP | - | +| IaC Generation | - | - | βœ… 6 clouds | βœ… Nickel | - | +| CI/CD | - | - | βœ… Backend | βœ… Full | - | +| Orchestration | βœ… NATS | - | - | βœ… Hybrid | - | + +#### Infraestructura + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Multi-cloud | - | - | βœ… Prov-gen | βœ… AWS/UpCloud/Local | - | +| Kubernetes | βœ… Deploy | - | - | βœ… Full | βœ… etcd backend | +| Secrets Mgmt | - | - | βœ… Encrypt | βœ… 5 KMS | βœ… **4 engines** | +| Networking | - | - | - | βœ… VPC/Subnet | - | +| State Mgmt | - | - | - | βœ… Checkpoints | βœ… 4 backends | + +#### Seguridad + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Authentication | βœ… JWT | - | - | βœ… JWT+MFA | βœ… Token-based | +| Authorization | βœ… Cedar | - | - | βœ… Cedar | βœ… Cedar ABAC | +| Multi-tenant | βœ… Scopes | - | - | βœ… Full | - | +| Audit | βœ… Logging | - | - | βœ… 7 aΓ±os | βœ… Full audit | +| Encryption | - | - | βœ… Field | βœ… Envelope | βœ… **PQC native** | +| Post-Quantum | - | - | - | - | βœ… ML-KEM/ML-DSA | + +#### Observabilidad + +| Capacidad | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | +| ----------- | -------- | -------- | ------------ | -------------- | --------------- | +| Metrics | βœ… Prometheus | - | - | βœ… Full | βœ… Prometheus | +| Logging | βœ… tracing | βœ… tracing | - | βœ… tracing | βœ… tracing | +| Tracing | βœ… OTEL | - | - | βœ… OTEL | - | +| Dashboards | βœ… Grafana | - | - | βœ… Control Center | - | + +--- + +## 7. Stack TecnolΓ³gico + +### Dependencias Compartidas + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ STACK TECNOLΓ“GICO COMÚN β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ LENGUAJE β”‚ +β”‚ └── Rust 2021/2024 edition (type-safe, zero-cost) β”‚ +β”‚ β”‚ +β”‚ CONFIGURACIΓ“N β”‚ +β”‚ └── Nickel 1.15+ (schemas tipados, lazy eval, validaciΓ³n) β”‚ +β”‚ β”‚ +β”‚ BASE DE DATOS β”‚ +β”‚ └── SurrealDB 2.3+ (multi-model, graph, scopes) β”‚ +β”‚ β”‚ +β”‚ WEB FRAMEWORK β”‚ +β”‚ └── Axum 0.8+ (async, composable, tower middleware) β”‚ +β”‚ β”‚ +β”‚ FRONTEND β”‚ +β”‚ └── Leptos 0.8+ (WASM, reactive, CSR) β”‚ +β”‚ β”‚ +β”‚ TUI β”‚ +β”‚ └── Ratatui 0.30+ (terminal UI, crossterm) β”‚ +β”‚ β”‚ +β”‚ CLI β”‚ +β”‚ └── clap 4+ (derive API, completions) β”‚ +β”‚ β”‚ +β”‚ LLM β”‚ +β”‚ └── rig-core 0.15+ (multi-provider, tools, streaming) β”‚ +β”‚ β”‚ +β”‚ MENSAJERÍA β”‚ +β”‚ └── async-nats 0.45+ (JetStream, delivery garantizado) β”‚ +β”‚ β”‚ +β”‚ SERIALIZACIΓ“N β”‚ +β”‚ └── serde 1.0 (JSON, YAML, TOML) β”‚ +β”‚ β”‚ +β”‚ ASYNC β”‚ +β”‚ └── Tokio 1.48+ (runtime, spawn, timeouts) β”‚ +β”‚ β”‚ +β”‚ LOGGING β”‚ +β”‚ └── tracing 0.1 (structured, JSON, env-filter) β”‚ +β”‚ β”‚ +β”‚ ERRORES β”‚ +β”‚ └── anyhow + thiserror (ergonomic error handling) β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 8. Posicionamiento vs Competencia + +### Por Dominio + +#### Plataformas de Desarrollo (Vapora) + +| Aspecto | Vapora | Jira | Linear | Notion | +| --------- | -------- | ------ | -------- | -------- | +| **Self-hosted** | βœ… | ❌ | ❌ | ❌ | +| **Multi-tenant** | βœ… Native | ❌ | ❌ | Partial | +| **Agent Orchestration** | βœ… Learning | ❌ | ❌ | ❌ | +| **LLM Integration** | βœ… 4 providers | AI features | ❌ | AI features | +| **Real-time** | βœ… WebSocket | βœ… | βœ… | βœ… | +| **Customizable** | βœ… Full | Limited | Limited | βœ… | + +#### Knowledge Management (Kogral) + +| Aspecto | Kogral | Obsidian | Notion | Confluence | +| --------- | -------- | ---------- | -------- | ------------ | +| **Git-native** | βœ… | Plugins | ❌ | ❌ | +| **Developer-focused** | βœ… ADRs/Patterns | General | General | General | +| **MCP Integration** | βœ… Native | ❌ | ❌ | ❌ | +| **Semantic Search** | βœ… Local+Cloud | Plugins | Internal | Internal | +| **Guideline Inheritance** | βœ… | ❌ | ❌ | ❌ | +| **Offline** | βœ… | βœ… | ❌ | ❌ | + +#### Forms y AutomatizaciΓ³n (TypeDialog) + +| Aspecto | TypeDialog | Typeform | SurveyJS | Inquirer | +| --------- | ------------ | ---------- | ---------- | ---------- | +| **Multi-backend** | βœ… 6 | Web only | Web only | CLI only | +| **Type-safe** | βœ… Nickel | ❌ | Partial | ❌ | +| **Agent Execution** | βœ… Native | ❌ | ❌ | ❌ | +| **IaC Generation** | βœ… 6 clouds | ❌ | ❌ | ❌ | +| **i18n** | βœ… Fluent | βœ… | βœ… | ❌ | +| **Self-hosted** | βœ… | ❌ | βœ… | βœ… | + +#### IaC (Provisioning) + +| Aspecto | Provisioning | Terraform | Pulumi | Ansible | +| --------- | -------------- | ----------- | -------- | --------- | +| **Language** | Nickel (typed) | HCL | TS/Py | YAML | +| **AI-native** | βœ… MCP+RAG | ❌ | ❌ | ❌ | +| **Security** | βœ… 39K lines | Basic | Basic | Vault plugin | +| **Orchestration** | βœ… Hybrid | State file | State | Playbooks | +| **Multi-cloud** | βœ… | βœ… | βœ… | βœ… | +| **DX** | βœ… 80+ shortcuts | Verbose | Standard | Standard | + +#### Secrets Management (SecretumVault) + +| Aspecto | SecretumVault | HashiCorp Vault | AWS Secrets Manager | Azure Key Vault | +| --------- | --------------- | ----------------- | --------------------- | ----------------- | +| **Language** | Rust (memory-safe) | Go | SaaS | SaaS | +| **Post-Quantum** | βœ… ML-KEM/ML-DSA | ❌ | ❌ | ❌ | +| **Self-hosted** | βœ… Complete | βœ… | ❌ | ❌ | +| **Crypto backends** | 4 pluggable | 1 fixed | 1 fixed | 1 fixed | +| **Storage backends** | 4 (FS/etcd/Surreal/PG) | Multiple | Proprietary | Proprietary | +| **Authorization** | Cedar ABAC | ACL | IAM | RBAC | +| **Shamir unsealing** | βœ… Native | βœ… | ❌ | ❌ | +| **License** | Apache-2.0 | BSL/Enterprise | Proprietary | Proprietary | + +--- + +## 9. IntegraciΓ³n entre Proyectos + +### Flujo de Datos + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Kogral β”‚ + β”‚ (Conocimiento) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + Guidelines, Patterns, ADRs, Decisions + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Vapora │◄───────▢│TypeDialog │◄───────▢│Provisioning β”‚ +β”‚(Desarrollo)β”‚ β”‚ (Forms) β”‚ β”‚ (IaC) β”‚ +β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ β”‚ β”‚ + β”‚ β–Ό β–Ό β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + └──▢│ SecretumVault β”‚β—„β”€β”€β”€β”˜ + β”‚ (Secrets + PQC Crypto) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PRODUCTO FINAL β”‚ +β”‚ Software desarrollado, documentado, configurado, desplegado β”‚ +β”‚ con secretos protegidos (PQC) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Sinergias EspecΓ­ficas + +| IntegraciΓ³n | Beneficio | +| ------------- | ----------- | +| Kogral β†’ Vapora | Agentes consultan guidelines antes de generar cΓ³digo | +| Kogral β†’ TypeDialog | Forms para captura estructurada de ADRs | +| Kogral β†’ Provisioning | ADRs de infraestructura automΓ‘ticos | +| Vapora β†’ TypeDialog | Formularios como input para pipelines | +| Vapora β†’ Provisioning | OrquestaciΓ³n de deployments | +| TypeDialog β†’ Provisioning | prov-gen backend genera IaC desde forms | + +### Componentes Reutilizables + +| Componente | Origen | Usado En | +| ------------ | -------- | ---------- | +| SurrealDB patterns | Vapora | Kogral, Provisioning | +| Nickel schemas | Provisioning | TypeDialog, Kogral | +| rig-core abstraction | Vapora | Todos | +| Axum patterns | Vapora | TypeDialog, Provisioning | +| tracing setup | Vapora | Todos | +| Cedar policies | Provisioning | Vapora | +| Leptos components | Vapora | Provisioning | + +--- + +## 10. MΓ©tricas del Portfolio + +| MΓ©trica | Vapora | Kogral | TypeDialog | Provisioning | SecretumVault | **Total** | +| --------- | -------- | -------- | ------------ | -------------- | --------------- | ----------- | +| **Crates** | 13 | 3 | 8 | 15+ | 1 | **40+** | +| **Tests** | 218 | 56 | 3,818 | 218 | 50+ | **4,360+** | +| **LOC (aprox)** | ~50K | ~15K | ~90K | ~40K | ~11K | **~206K** | +| **Backends** | 1 (Leptos) | 3 | 6 | 3 | 4 storage | **17** | +| **LLM Providers** | 4 | 4 | 4 | 3 | - | **4 ΓΊnicos** | +| **MCP Tools** | Gateway | 7 | - | 7 | - | **14+** | +| **Crypto backends** | - | - | - | 5 KMS | 4 | **4 ΓΊnicos** | + +--- + +## 11. Orden de AdopciΓ³n Recomendado + +### Secuencia Γ“ptima + +```text +Fase 1: Kogral + β”‚ Establece base de conocimiento + β”‚ Guidelines, patterns, ADRs + β–Ό +Fase 2: TypeDialog + β”‚ Habilita inputs estructurados + β”‚ ValidaciΓ³n con Nickel contracts + β–Ό +Fase 3: SecretumVault + β”‚ GestiΓ³n segura de secretos + β”‚ PreparaciΓ³n criptogrΓ‘fica PQC + β–Ό +Fase 4: Vapora + β”‚ Orquesta desarrollo con agentes + β”‚ Aprovecha knowledge graph + β–Ό +Fase 5: Provisioning + β”‚ Infraestructura informada + β”‚ por todo el contexto previo +``` + +### AdopciΓ³n Independiente + +Cada proyecto funciona de forma standalone: + +- **Kogral**: Knowledge management sin dependencias externas +- **TypeDialog**: Forms y agentes sin otros proyectos +- **SecretumVault**: GestiΓ³n de secretos Rust-native +- **Vapora**: Desarrollo y orquestaciΓ³n completa +- **Provisioning**: IaC enterprise independiente + +Las sinergias emergen con adopciΓ³n combinada, pero no son requisito. + +--- + +*Documento generado: 2026-01-22* +*Tipo: info (posicionamiento estratΓ©gico completo)*