/**
 * CLI types
 */

/**
 * Parsed command-line arguments
 */
export interface ParsedCommand {
  command: string;
  subcommand?: string;
  args: string[];
  flags: Record<string, string | boolean>;
}

/**
 * Command result
 */
export interface CommandSuccess {
  success: true;
  message: string;
  data?: unknown;
  /**
   * Marks a command whose `message` is a machine-readable payload (JSON, a
   * unit file, a secret) rather than prose for a human.
   *
   * Every successful message now reaches stdout verbatim, so this no longer
   * selects a different destination. It is kept as the contract: these are the
   * commands a script parses, and nothing may ever decorate them (celilo#698,
   * where ten JSON payloads were rendered unparseable by the formatter).
   */
  rawOutput?: boolean;
}

export interface CommandError {
  success: false;
  error: string;
  details?: unknown;
  /**
   * Marks a refusal that is not a failure: the action was skipped BEFORE any
   * state changed and will be retried when its precondition holds (the
   * registry poll defers a consumer upgrade whose capability requirements the
   * deployed providers cannot serve — celilo#1361). Callers that read only
   * `success` still see a non-deploy; the poll uses this to report deferrals
   * separately from failures instead of counting them as red.
   */
  deferred?: boolean;
}

export type CommandResult = CommandSuccess | CommandError;

/**
 * Command handler function
 */
export type CommandHandler = (
  args: string[],
  flags: Record<string, string | boolean>,
) => Promise<CommandResult>;