/**
 * Types for the system update orchestrator (CELILO_UPDATE Phase 4).
 *
 * The orchestrator's job is to take a `SystemAuditReport` plus a
 * dependency graph and walk every drifting module through a small
 * state machine: backup → upgrade → deploy → health-check. Each
 * module's outcome is recorded as a `ModuleUpdateState`; the
 * aggregate is reported as a `SystemUpdateResult`.
 *
 * Stable JSON-friendly shapes — version-bumped if the schema
 * changes incompatibly.
 */

import type { SystemAuditReport } from '../audit';

/** Per-module step in the update state machine. */
export type UpdateStep =
  | 'pending'
  | 'backup'
  | 'upgrade'
  | 'deploy'
  | 'health'
  | 'done'
  | 'failed'
  | 'skipped';

export interface ModuleUpdateState {
  moduleId: string;
  /** Version installed at the start of the run. */
  fromVersion: string;
  /** Version we're attempting to upgrade to (may equal `fromVersion` if no version drift, but other drift triggered the update). */
  toVersion: string;
  /** Where the state machine stopped. */
  step: UpdateStep;
  /** Step-specific error message (if `step === 'failed'`). */
  error?: string;
  /** Reason for skip (if `step === 'skipped'`), e.g., "blocked by old provider X@Y". */
  skipReason?: string;
  /** ISO timestamp when this module's run started. */
  startedAt?: string;
  /** ISO timestamp when this module's run finished. */
  finishedAt?: string;
}

export type SelfUpdateResult =
  | { performed: false; reason: 'already-current' | 'dev-mode' | 'no-network' }
  | { performed: true; from: string; to: string };

export interface SystemUpdateResult {
  version: 1;
  /** Run identifier — same uuid that ties together all the pre-update backups. */
  updateId: string;
  startedAt: string;
  finishedAt: string;
  /** The audit that drove this run. Carried through so the JSON output is self-contained. */
  audit: SystemAuditReport;
  /** CLI self-update outcome. */
  selfUpdate: SelfUpdateResult;
  /**
   * Whether per-module backups were created. False on `--no-backup` runs
   * (the user accepted the rollback risk).
   */
  backupsCreated: boolean;
  /** Per-module results, in the order the orchestrator walked them. */
  modules: ModuleUpdateState[];
  /** True iff every module reached `done` (or had nothing to do). */
  ok: boolean;
}

/**
 * Non-destructive preview produced by `system update --dry-run`.
 * Describes what the orchestrator *would* do without running anything.
 */
export interface UpdatePlan {
  version: 1;
  updateId: string;
  audit: SystemAuditReport;
  /** Whether the CLI would self-update before module work. */
  willSelfUpdate: boolean;
  selfUpdateFromVersion?: string;
  selfUpdateToVersion?: string;
  /** Modules that will be upgraded, in topological order. */
  modules: Array<{
    moduleId: string;
    fromVersion: string;
    toVersion: string;
    /** Capability provider this module depends on, for the tree rendering. */
    dependsOn: string[];
  }>;
  /** Whether backups will be taken before mutations. */
  willBackup: boolean;
  /** Whether the destructive-terraform gate is in effect. */
  destructiveTerraformBlocked: boolean;
}