/**
 * Parsed flags from a command's parse() call.
 * The exact structure depends on the command's flag definitions.
 */
type ParsedFlags = Record<string, unknown>;
/**
 * Minimal interface for commands that can be wrapped with debug logging.
 *
 * This interface represents the essential shape of an SfCommand that the
 * debug proxy needs to intercept. Commands must have a run() method that
 * returns a Promise.
 *
 * @template T - The result type returned by the command's run() method
 */
export type DebugWrappableCommand<T> = {
    /** Executes the command and returns a result */
    run(): Promise<T>;
};
/**
 * Result of wrapping a command with debug logging.
 *
 * Contains the wrapped command and a cleanup function that should be
 * called after command execution completes (success or failure).
 *
 * @template T - The result type returned by the command's run() method
 */
export type CommandDebugResult<T> = {
    /** The command instance, wrapped with debug logging if debug=true */
    command: DebugWrappableCommand<T>;
    /** Cleanup function to restore debug state after execution */
    cleanup: () => void;
};
/**
 * Wraps a command's run() method with debug logging for CLI layer visibility.
 *
 * When debug is enabled, creates a Proxy that intercepts the run() method and:
 * - Logs command start with flags: `[DEBUG] [CLI] commandName: flags → {...}`
 * - Logs command completion with timing: `[DEBUG] [CLI] commandName: complete → duration=Xms`
 * - Logs errors: `[DEBUG] [CLI] commandName: error → message`
 *
 * When debug is disabled (default), returns the original command unchanged
 * with zero overhead.
 *
 * @template T - The result type returned by the command's run() method
 * @param command - The command instance to wrap
 * @param commandName - Name used in log output (e.g., 'cuneiform:org:details')
 * @param debug - Whether to enable debug logging (default: false)
 * @param flags - Optional parsed flags to log at command start
 * @returns Object containing the wrapped command and cleanup function
 *
 * @example
 * ```typescript
 * // In a hook or command infrastructure
 * const { command: wrapped, cleanup } = withCommandDebugLogging(
 *   commandInstance,
 *   'cuneiform:org:details',
 *   flags.debug,
 *   flags
 * );
 *
 * try {
 *   const result = await wrapped.run();
 *   return result;
 * } finally {
 *   cleanup();
 * }
 *
 * // Output when debug=true:
 * // [DEBUG] [CLI] cuneiform:org:details: flags → {"target-org":"myOrg","verbose":true}
 * // [DEBUG] [CLI] cuneiform:org:details: complete → duration=150ms
 * ```
 */
export declare function withCommandDebugLogging<T>(command: DebugWrappableCommand<T>, commandName: string, debug?: boolean, flags?: ParsedFlags): CommandDebugResult<T>;
/**
 * Convenience function to execute a command with debug logging.
 *
 * This is a higher-level wrapper that handles the full lifecycle:
 * 1. Wraps the command with debug logging
 * 2. Executes the command
 * 3. Cleans up debug state
 *
 * @template T - The result type returned by the command's run() method
 * @param command - The command instance to execute
 * @param commandName - Name used in log output
 * @param debug - Whether to enable debug logging
 * @param flags - Optional parsed flags to log
 * @returns Promise resolving to the command result
 *
 * @example
 * ```typescript
 * // Instead of managing wrap/cleanup manually:
 * const result = await executeWithDebugLogging(
 *   commandInstance,
 *   'cuneiform:org:details',
 *   flags.debug,
 *   flags
 * );
 * ```
 */
export declare function executeWithDebugLogging<T>(command: DebugWrappableCommand<T>, commandName: string, debug?: boolean, flags?: ParsedFlags): Promise<T>;
export {};