Newbranchnotify01

[canicefavour]

Implemented a standalone command-line utility, open-audit-cli, to simplify and accelerate translation registry development by enabling contributors to test contract translation mappings entirely offline. This eliminates the need to run the full application stack, provision databases, or generate mock blockchain activity simply to validate translation output.

Overview

This enhancement introduces a lightweight developer-focused workflow that allows raw contract payloads and draft translation specifications to be executed directly from the command line. Contributors can now validate parser behavior, translation mappings, and output formatting using only local files and input data.

The CLI is intentionally isolated from runtime infrastructure, providing a fast and deterministic testing experience with no external dependencies.

Features Implemented

Standalone CLI Application

Created an executable CLI module embedded within the repository.

The utility operates independently from the main application and can be invoked directly from a terminal to perform translation validation tasks.

Key characteristics include:

• Lightweight execution
• No service dependencies
• Local-only operation
• Fast startup time
• Contributor-friendly workflow

Command Interface & Help System

Implemented a self-documenting command structure with built-in help support.

Features include:

• Global help output
• Command descriptions
• Usage examples
• Parameter documentation
• Error guidance

Running the CLI without arguments or with help flags provides clear instructions for usage and available functionality.

Translation Testing Command

Added a dedicated testing command for validating translation specifications against raw payload data.

Supported workflow:

open-audit-cli test --hex <raw_hex_data> --spec <path_to_specification>

The command executes the translation pipeline and immediately displays the resulting human-readable output.

Supported Specification Formats

The CLI supports local translation definitions stored as:

• JSON files
• YAML files

This enables contributors to validate draft registry entries before submitting changes to the project.

Parser Engine Decoupling

Refactored parser execution to support a pure-function runtime mode.

The CLI execution path bypasses all non-essential infrastructure components, including:

• Database connections
• Network services
• External APIs
• Runtime configuration services
• Application bootstrapping logic

This allows translation testing to occur entirely within a local execution context.

Offline Execution Workflow

Translation processing now relies exclusively on:

• Raw hexadecimal payload input
• Local specification files
• Embedded parser and translation logic

No internet connection, running services, or backend infrastructure are required.

This significantly reduces setup complexity for contributors and maintainers.

Standard Output Formatting

Implemented direct console output for successful executions.

When translation succeeds:

• The parsed result is compiled.
• The final English sentence is generated.
• The output is written directly to stdout.

This provides immediate feedback and supports integration into shell scripts and automated workflows.

Error Handling & Validation

Added comprehensive validation and failure handling.

The CLI detects and reports:

Invalid Input Data

• Malformed hexadecimal strings
• Unsupported payload formats
• Corrupted contract data

Specification Errors

• Invalid JSON syntax
• Invalid YAML syntax
• Missing specification files
• Unsupported schema structures

Runtime Parsing Failures

• Translation mismatches
• Parser execution errors
• Invalid mapping definitions

Errors are written to stderr and return appropriate non-zero exit codes to support CI/CD and automation workflows.

Side-Effect Free Execution

Designed the tool to operate as a read-only validation environment.

CLI execution does not:

• Create database records
• Modify registry data
• Generate telemetry events
• Write cache files
• Persist metadata
• Contact external services

This guarantees predictable execution and safe experimentation.

Developer Experience Improvements

The new workflow significantly improves contributor productivity by removing the need for a full local environment when validating translation mappings.

Benefits include:

• Faster feedback cycles
• Reduced onboarding complexity
• Simplified testing workflow
• Easier registry development
• Lower infrastructure requirements
• Improved local debugging experience

Contributors can now iterate rapidly on translation specifications and immediately verify output from the command line.

Documentation & Examples

Added documentation covering:

• CLI installation and setup
• Command syntax
• Supported file formats
• Example executions
• Error handling behavior
• Local development workflows

This provides a complete reference for contributors using the tool.

Result

The project now includes a dedicated offline testing utility that enables contributors to validate translation registry mappings without requiring databases, running services, or external infrastructure. By decoupling parser execution from the broader application environment and providing a simple command-line workflow, the CLI dramatically improves the developer experience while making translation development faster, easier, and more accessible.

Closes #33