/**
 * desktop/src/types.ts — frozen shared contract for the Electron desktop shell.
 *
 * This is the single source of truth for cross-module data shapes (mirrors the
 * backend's src/types.ts role). Modules own disjoint files but all agree here.
 * All shapes are readonly (immutability — coding-style CRITICAL rule).
 *
 * Status/gate string unions are kept in sync with the backend (src/types.ts):
 *   ClaudeStatus = 'working' | 'waiting' | 'idle' | 'unknown' | 'stuck'
 *   PermissionGate = 'tool' | 'plan'
 * They are re-declared (not imported) so the desktop package stays decoupled;
 * notify-policy references these literals directly.
 */

/** Host platform (subset of NodeJS.Platform we branch on). */
export type Platform = 'darwin' | 'win32' | 'linux'

/** Claude activity, mirrored from backend ClaudeStatus (src/types.ts:97). */
export type DesktopClaudeStatus = 'working' | 'waiting' | 'idle' | 'unknown' | 'stuck'

/** Approval gate kind, mirrored from backend PermissionGate (src/types.ts:101). */
export type DesktopPermissionGate = 'tool' | 'plan'

/**
 * A remote web-terminal host reachable over the mTLS reverse tunnel
 * (Track C-Desktop, PLAN_NATIVE_TUNNEL §"C-Desktop / D-1"). `url` is the https
 * origin the BrowserWindow loads, e.g. `https://t1.terminal.yaojia.wang/`; the
 * device client certificate (D-2, sourced from the OS keychain) is the only auth
 * gate. `id` is a stable opaque handle used by the tray host-picker + prefs.
 */
export interface RemoteHost {
  /** Stable opaque id (uuid); the tray/prefs key, never shown to the user. */
  readonly id: string
  /** Human label shown in the tray host-picker. */
  readonly name: string
  /** The https origin URL to load, normalized to `https://<host>/`. */
  readonly url: string
}

/**
 * User preferences, persisted as JSON in the app's userData dir (hand-rolled
 * store — matches the project's minimal-deps convention; no electron-store).
 */
export interface DesktopPrefs {
  /** Preferred listen port; null → default (3000, with free-port fallback). */
  readonly port: number | null
  /** true → bind 0.0.0.0 (LAN sharing, no auth); false → 127.0.0.1 (private). */
  readonly lanSharing: boolean
  /** Shell override; null → platform default (see shell.ts). */
  readonly shellPath: string | null
  /** Launch the app on OS login. */
  readonly openAtLogin: boolean
  /** Fire a native notification when a session holds a pending approval. */
  readonly notifyOnApproval: boolean
  /** Fire a native notification when a session's Claude status changes. */
  readonly notifyOnStatusChange: boolean
  /** Configured remote tunnel hosts (D-1); empty on a fresh install. */
  readonly remoteHosts: readonly RemoteHost[]
  /** Selected host id, or null → "This machine (local)" (the embedded server). */
  readonly selectedHostId: string | null
}

/** Handle returned by the embedded server, for lifecycle + window wiring. */
export interface EmbeddedServer {
  /** The concrete port the server bound to (already free-checked). */
  readonly port: number
  /** The host it bound to ('0.0.0.0' or '127.0.0.1'). */
  readonly bindHost: string
  /** Origins the server will accept (derived by the backend from port + NICs). */
  readonly allowedOrigins: readonly string[]
  /** Graceful shutdown: closes HTTP + WS and kills all PTYs. */
  close(): Promise<void>
}

/** A single session's status snapshot, fed to the notification policy. */
export interface SessionStatusSnapshot {
  readonly sessionId: string
  readonly claudeStatus: DesktopClaudeStatus
  readonly pendingApproval: boolean
  /** Gate kind when an approval is held (for a richer notification body). */
  readonly gate: DesktopPermissionGate | null
  /** Human label for the session (folder/process), if known. */
  readonly title: string | undefined
}

/** The decision produced by notify-policy for one status transition. */
export interface NotifyDecision {
  readonly notify: boolean
  readonly title: string
  readonly body: string
}

/** Parsed `terminalapp://` deep link. */
export interface DeepLink {
  /** Session id to join (from terminalapp://join/<id>). */
  readonly join: string
}