AirCoding/packages/contracts/src/platform.ts

// contracts §19 + cross-platform matrix — Platform Contracts
// File: platform.ts — DoctorService, DoctorRunInput/Output, DoctorIssue, cross-platform tier enums
// Implements: interface-contracts-v1.md §19, cross-platform-matrix-v1.md
// Merged: doctor.ts symbols per DD §3

import type { CapabilityID, ArtifactID } from "./ids.js"

// =============================================================================
// contracts §19 — Doctor Contracts
// =============================================================================

/**
 * Doctor run mode determines what actions the doctor service can perform.
 */
export type DoctorRunMode = "read_only" | "fix"

/**
 * Doctor run scope determines which capabilities/subsystems to check.
 */
export type DoctorRunScope = "startup" | "project" | "toolchain" | "release_gate"

export interface DoctorRunInput {
  mode: DoctorRunMode
  scope?: DoctorRunScope
  capabilities?: CapabilityID[]
  bundle?: boolean
}

export interface DoctorRunOutput {
  run_id: string
  status: "passed" | "issues_found" | "fixed" | "failed"
  issue_count: number
  blocking_issue_count: number
  report_artifact_id?: ArtifactID
  bundle_artifact_id?: ArtifactID
}

/**
 * Severity level for doctor issues.
 */
export type DoctorIssueSeverity = "blocking" | "warning" | "info"

/**
 * Category for doctor issues, mapping to different subsystems.
 */
export type DoctorIssueCategory =
  | "runtime"       // Bun runtime, SQLite, basic shell
  | "project"       // Project initialization, .air directory
  | "toolchain"     // C++ toolchain (CMake, Ninja, gcc/clang, etc.)
  | "permission"    // Permission engine, path policy
  | "provider"      // LLM provider configuration
  | "workspace"     // Workspace management, git worktree
  | "capability"    // Capability registry, tool registration

/**
 * A single issue discovered by the doctor service.
 */
export interface DoctorIssue {
  id: string
  severity: DoctorIssueSeverity
  category: DoctorIssueCategory
  title: string
  description: string
  fix_suggestion?: string
  evidence_refs?: string[]
}

/**
 * DoctorService interface for running diagnostic checks.
 */
export interface DoctorService {
  run(input: DoctorRunInput): Promise<DoctorRunOutput>
}

// =============================================================================
// contracts §19 — Logging Contracts
// =============================================================================

export interface Logger {
  debug(message: string, data?: unknown): void
  info(message: string, data?: unknown): void
  warn(message: string, data?: unknown): void
  error(message: string, data?: unknown): void
}

export interface DeveloperLogEncryptor {
  encrypt_log_chunk(chunk: Uint8Array): Promise<Uint8Array>
}

// =============================================================================
// cross-platform-matrix-v1.md — Platform Tier Enums
// =============================================================================

/**
 * Platform support levels from cross-platform-matrix-v1.md §1.
 */
export type PlatformSupportLevel =
  | "tier_1"       // Release-blocking support; tested before release
  | "tier_2"       // Intended support; best-effort validation
  | "experimental" // May work; no compatibility promise
  | "unsupported"  // Explicit non-target

/**
 * Operating system type for platform detection.
 */
export type PlatformOS = "linux" | "darwin" | "windows" | "unknown"

/**
 * CPU architecture type for platform detection.
 */
export type PlatformArch = "x64" | "arm64" | "arm" | "unknown"

/**
 * Libc type for platform detection.
 */
export type PlatformLibc = "glibc" | "musl" | "unknown"

/**
 * Display backend types for GUI evidence collection.
 */
export interface PlatformDisplayBackend {
  wayland?: boolean
  x11?: boolean
  xvfb?: boolean
  wslg?: boolean
}

/**
 * Platform information contract from cross-platform-matrix-v1.md §10.
 */
export interface PlatformInfo {
  os: PlatformOS
  arch: PlatformArch
  libc?: PlatformLibc
  shell?: string
  is_wsl?: boolean
  display?: PlatformDisplayBackend
  package_managers?: string[]
  path_case_sensitive?: boolean
}

/**
 * Runtime feature support levels for different platforms.
 */
export type RuntimeFeature =
  | "bun_runtime"
  | "cli"
  | "tui"
  | "sqlite_session_db"
  | "ndjson_child_processes"
  | "tool_registry"
  | "permission_engine_path_policy"
  | "doctor_read_only"
  | "doctor_fix"

/**
 * C++ toolchain feature support levels.
 */
export type ToolchainFeature =
  | "cmake"
  | "ninja"
  | "make_fallback"
  | "gcc_clang"
  | "clangd_cli"
  | "cppcheck"
  | "ctest_googletest"
  | "core_dumps_backtrace"

/**
 * Filesystem capability support.
 */
export type FilesystemCapability =
  | "posix_paths"
  | "symlink_realpath"
  | "chmod_exec_bits"
  | "case_sensitivity"
  | "project_local_air"
  | "git_worktree"
  | "project_outside_backup_repo"

/**
 * Shell behavior support.
 */
export type ShellBehavior =
  | "bash_sh_commands"
  | "process_signals"
  | "sudo"
  | "package_manager_commands"
  | "timeout_kill"

/**
 * GUI/Debug/Network evidence support.
 */
export type EvidenceCapability =
  | "screenshots"
  | "gui_automation"
  | "pcaps"
  | "core_dumps"
  | "debugger_integration"

/**
 * Feature tier mapping for runtime features.
 * Maps runtime feature to support level per platform.
 */
export interface RuntimeFeatureTier {
  feature: RuntimeFeature
  linux_x86_64: PlatformSupportLevel
  linux_arm64: PlatformSupportLevel
  macOS: PlatformSupportLevel
  windows_native: PlatformSupportLevel
  wsl2: PlatformSupportLevel
}

/**
 * Toolchain feature tier mapping.
 */
export interface ToolchainFeatureTier {
  feature: ToolchainFeature
  linux_x86_64: PlatformSupportLevel
  linux_arm64: PlatformSupportLevel
  macOS: PlatformSupportLevel
  windows_native: PlatformSupportLevel
  wsl2: PlatformSupportLevel
}