vfa-tui

Enterprise-grade terminal UI for the Vanguard Frontier Agentic marketplace catalog.

Status: v0.1.0 — Functional, secure, and tested. APIs and UI may change before 1.0.

Installation

cargo install vfa-tui

Requires Rust 1.75 or later.

Important Limitations

vfa-tui is designed for use inside the vanguard-frontier-agentic monorepo. The binary auto-detects the workspace root by walking up from the current directory and looking for the catalog/ directory and package.json. Running it outside a checked-out copy of the repository will produce an error at startup.

Library API stability: The vfa_tui library crate is an internal implementation detail. All modules are marked pub only to allow integration and property tests in sibling crates to import them directly. The library API is not covered by semver guarantees — it may change between any releases.

Pre-built Binaries

Tagged releases publish pre-compiled binaries for all supported platforms via GitHub Releases. Download from Releases and place the binary on your $PATH.

Available targets per release:

Each release also includes a checksums.sha256 file and an SPDX 2.3 SBOM (vfa-tui.spdx.json).

Overview

vfa-tui provides a fast, keyboard-driven terminal interface for browsing the VFA catalog of 300+ security agents across 30+ providers. It supports fuzzy search, provider/harness filtering, role-based views, validation gate execution with real-time streaming output, export command building with dry-run preview, and structured audit logging.

Key capabilities:

• Browse agents, skills, roles, providers, MCP references, and rules interactively
• Fuzzy search across all catalog entities (powered by nucleo-matcher)
• Run any of the 17+ validation gates with streaming output
• Build and preview export commands before execution
• Manage per-harness model/reasoning-effort policy for providers, roles, and agents — batch assignment with dry-run preview and automatic integrity refresh
• View asset integrity manifests with SHA-256 hashes
• Full audit trail via structured tracing logs

The TUI is a read-first interface — it parses catalog JSON files directly for browsing and wraps existing Node.js/Python validation and export scripts via subprocess execution. Write operations (exports) require explicit operator confirmation with dry-run as the default.

Usage

Run from anywhere inside the checked-out repository (workspace is auto-detected):

vfa-tui

Or specify the workspace explicitly:

vfa-tui --workspace /path/to/vanguard-frontier-agentic

CLI Flags

Keyboard Navigation

Examples

# Basic launch — auto-detects workspace
vfa-tui

# Headless report (no TUI, exits immediately)
vfa-tui --report summary

# Run with debug logging to a file
vfa-tui --log-level debug --log-file /tmp/vfa-tui.log

# Run without color (useful for piping or screen readers)
vfa-tui --no-color

# Validate configuration files and exit
vfa-tui --validate-config

# Export audit log to JSON
vfa-tui --export-audit json /tmp/audit.json

Model Policy

The Model Policy sidebar section and the Model Policy Builder manage per-harness model and reasoning-effort assignments for agents — batch scope changes across providers, roles, or individual agents without hand-editing codex.toml keys or .agent.md frontmatter. Agent detail views show a Models section with the resolved model/reasoning per harness and the rule that won.

Press m from anywhere to open the builder. Scope is prefilled from context — an agent detail or list view targets that agent, a provider view targets that provider, a role view targets that role, and any other view defaults to all. Consistent with the "no business logic duplication" design principle above, the builder never re-implements policy resolution: it shells out to scripts/model-policy.mjs for validation and apply, and on a successful non-dry-run apply it automatically chains npm run asset-integrity:write.

Builder flow:

• Scope — Space/Enter cycles kind (All → Provider → Role → Agent); type the ID
• Harness — cycles codex → claude-code → cursor
• Model — free text; auto clears the managed field, empty leaves it untouched
• Reasoning — cycles (unchanged) / auto / minimal / low / medium / high (codex only)
• Dry Run — defaults to on; previews changes before writing
• Refresh Integrity — defaults to on; runs npm run asset-integrity:write after a successful apply
• [ Continue ] shows the exact command to be run, then the output view streams the subprocess

Every value entered here is validated against the verified model registry (catalog/model-registry.json) before any file changes — an unknown model name or a reasoning effort the resolved model doesn't support is rejected up front, not discovered later as a provider-side failure. For codex, the builder accepts local Ollama models (name:tag) and OpenRouter models (author/model) in addition to OpenAI slugs, projecting the matching model_provider line automatically. See docs/model-policy-matrix.md for the full per-harness matrix.

Supported Platforms

WSL Notes

Build with --target x86_64-unknown-linux-musl for a fully static binary. Windows Terminal provides the best experience (true color, proper resize events). Use --no-color for terminals with limited color support.

Architecture

┌─────────────────────────────────────────────────────┐
│              Presentation Layer                       │
│  Terminal Manager (crossterm) ← UI Renderer (ratatui)│
│  Navigation State Machine ← Keybinding Dispatcher   │
├─────────────────────────────────────────────────────┤
│              Application Layer                        │
│  Browse Controller │ Validation Controller           │
│  Export Controller │ Search Engine (nucleo-matcher)  │
├─────────────────────────────────────────────────────┤
│              Domain Layer                             │
│  Catalog Store (in-memory, read-only)                │
│  Data Models (serde structs, deny_unknown_fields)    │
│  Security Module (sanitize + validate + redact)      │
├─────────────────────────────────────────────────────┤
│              Infrastructure Layer                     │
│  Subprocess Manager (tokio::process)                 │
│  Workspace Detector │ Audit Logger (tracing)         │
│  Terminal Manager (setup/restore/panic hook)          │
└─────────────────────────────────────────────────────┘

Design Principles

1. No business logic duplication — wraps existing scripts via subprocess; never re-implements validation or export logic.
2. Read-first, confirm-before-write — catalog access is read-only. Exports require explicit confirmation with dry-run default.
3. Security by construction — no shell interpolation, no network access, no credential exposure, terminal escape sanitization on all rendered content.
4. Deterministic rendering — same inputs produce same outputs.
5. Graceful degradation — partial catalog loading on file errors; never panics on recoverable errors.

Technology Stack

Development

Prerequisites

• Rust 1.75+
• A checkout of the vanguard-frontier-agentic repository
• Node.js 18+ (for validation gate and export command execution)

Build

cd tools/vfa-tui
cargo build --release

For a statically-linked binary:

cargo build --release --target x86_64-unknown-linux-musl

Running Tests

cd tools/vfa-tui
cargo test

Property tests live in tests/property/ and cover catalog loading, search invariants, security sanitization, workspace detection, and deterministic rendering across randomized inputs:

PROPTEST_CASES=1000 cargo test

Linting and Formatting

cargo fmt --check   # Check only
cargo fmt           # Auto-format
cargo clippy -- -D warnings

Full CI Check (local)

cd tools/vfa-tui
cargo fmt --check
cargo clippy -- -D warnings
cargo test
cargo build --release
cargo publish --dry-run

Security

The TUI enforces several security invariants:

• No shell interpolation — all subprocesses are spawned with arguments as arrays, never concatenated strings
• No network access — the binary makes zero network requests under any circumstance
• No credential exposure — secret environment variables are stripped before subprocess spawning and redacted from all output
• Terminal escape sanitization — all catalog data and subprocess output is sanitized against terminal injection attacks
• Path validation — all user-provided paths are canonicalized and checked for directory traversal

See SECURITY.md for the vulnerability disclosure policy.

License

Licensed under either of:

• MIT License (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.