wagoe.platform.shell.interfaces.cli.middleware — com.wagoe/wagoe-platform 1.0.0-beta-5

CLI middleware for command execution with enhanced error context (imperative shell).

This namespace provides reusable CLI middleware that can be used across different modules and applications for consistent observability and error handling in command-line interfaces.

Middleware functions handle CLI boundaries: command execution interception, context generation, logging, and exception handling with enhanced context preservation for debugging.

Features:

• Command correlation ID generation
• Tenant and user context extraction from config/environment
• Structured command execution logging with observability context
• Command timing and error reporting with enhanced context
• Error reporting breadcrumb integration

build-cli-context clj

(build-cli-context command subcommand cli-opts config)

Builds observability context for CLI command execution.

Args: command: Command name string subcommand: Subcommand name string (optional) cli-opts: Parsed CLI options map config: Application config map (optional)

Returns: Observability context map

extract-tenant-context clj

(extract-tenant-context cli-opts config)

Extracts tenant context from CLI options, config, or environment.

Extraction priority:

1. --tenant-id CLI option (explicit override)
2. WAGOE_TENANT_ID environment variable
3. :tenant-id from config map (if provided)

Args: cli-opts: Parsed CLI options map config: Application config map (optional)

Returns: Tenant ID string or nil

extract-user-context clj

(extract-user-context cli-opts config)

Extracts user context from CLI options, config, or environment.

For CLI commands, user context typically comes from:

1. --user-id CLI option (for admin operations)
2. WAGOE_USER_ID environment variable
3. Current authenticated user from config

Args: cli-opts: Parsed CLI options map config: Application config map (optional)

Returns: User ID string or nil

generate-correlation-id clj

(generate-correlation-id)

Generates a new correlation ID for CLI command execution.

Returns: UUID string for request correlation

with-cli-context clj

(with-cli-context command f)

(with-cli-context command subcommand f)

(with-cli-context command subcommand config f)

Higher-order function that wraps CLI command execution with observability context.

This middleware:

1. Generates correlation ID for command execution
2. Extracts tenant/user context from CLI args and environment
3. Builds observability context for logging and metrics
4. Makes context available to the wrapped function

Args: command: Command name string subcommand: Subcommand name string (optional) config: Application config map (optional) f: Function to execute with context (receives: service, opts, context)

Returns: Function that takes (service, cli-opts) and executes with context

with-cli-error-reporting clj

(with-cli-error-reporting context operation-fn)

Execute CLI command with enhanced error reporting.

Captures unexpected exceptions and reports them to the error reporting system with comprehensive error context while preserving CLI exit code behavior. Uses enhanced error context utilities for better debugging information.

Args: context: CLI context map containing user, operation, and additional context operation-fn: Function to execute with error reporting (takes context as arg)

Returns: Result of operation-fn, or throws enhanced exception with CLI context

with-cli-logging clj

(with-cli-logging f)

(with-cli-logging logger f)

Higher-order function that wraps CLI command execution with structured logging.

Logs command start/completion with timing and context information, plus error reporting breadcrumbs for command lifecycle tracking. Should be used together with with-cli-context.

Args: logger: ILogger instance (optional, uses tools.logging if not provided) f: Function to execute with logging (receives same args as passed)

Returns: Function that logs around execution

wrap-cli-command clj

(wrap-cli-command command f)

(wrap-cli-command command subcommand f)

(wrap-cli-command command subcommand config logger f)

Convenience function that applies all CLI middleware to a command function.

Creates a higher-order function that applies logging, context generation, and error reporting middleware when called.

Args: command: Command name string subcommand: Subcommand name string (optional) config: Application config map (optional) logger: ILogger instance (optional) f: Command function to wrap (will receive [service cli-opts context])

Returns: Function that takes [service cli-opts] and executes with full middleware stack