feat: add platform availability filtering for all Apple platforms

Author: mihaelamj

CHANGELOG.md

@@ -1,3 +1,35 @@
+## 0.6.0 (2025-12-12)
+
+### Added
+- **Platform Availability Support** (#99)
+  - `cupertino fetch --type availability` - Fetch platform version data for all docs
+  - Availability tracked for all sources: apple-docs, sample-code, archive, swift-evolution, swift-book, hig
+  - Search filtering by `--min-ios`, `--min-macos`, `--min-tvos`, `--min-watchos`, `--min-visionos` (CLI and MCP `search_docs` tool)
+  - `save` command now warns if docs don't have availability data
+  - Schema v7: availability columns in docs_metadata and sample_code_metadata
+
+### Availability Sources
+| Source | Strategy |
+|--------|----------|
+| apple-docs | API fetch + fallbacks |
+| sample-code | Derives from framework |
+| apple-archive | Derives from framework |
+| swift-evolution | Swift version mapping |
+| swift-book/hig | Universal (all platforms) |
+
+### Documentation
+- Added `docs/commands/search/option (--)/min-ios.md`
+- Added `docs/commands/search/option (--)/min-macos.md`
+- Added `docs/commands/search/option (--)/min-tvos.md`
+- Added `docs/commands/search/option (--)/min-watchos.md`
+- Added `docs/commands/search/option (--)/min-visionos.md`
+- Updated search command docs with availability filtering options
+
+### Related Issues
+- Closes #99
+
+---
+
 ## 0.5.0 (2025-12-11)
 
 **Why minor bump?** The `cupertino release` command was removed from the public CLI. Users who had scripts calling `cupertino release` will need to update them. This is a breaking change for maintainer workflows.

Packages/Package.swift

@@ -24,6 +24,7 @@ let macOSOnlyProducts: [Product] = [
     .singleTargetLibrary("SampleIndex"),
     .singleTargetLibrary("Services"),
     .singleTargetLibrary("Resources"),
+    .singleTargetLibrary("Availability"),
     .singleTargetLibrary("MCPSupport"),
     .singleTargetLibrary("SearchToolProvider"),
     .singleTargetLibrary("MCPClient"),
@@ -178,6 +179,15 @@ let targets: [Target] = {
         dependencies: ["RemoteSync", "TestSupport"]
     )
 
+    let availabilityTarget = Target.target(
+        name: "Availability",
+        dependencies: []
+    )
+    let availabilityTestsTarget = Target.testTarget(
+        name: "AvailabilityTests",
+        dependencies: ["Availability", "TestSupport"]
+    )
+
     let cliTarget = Target.executableTarget(
         name: "CLI",
         dependencies: [
@@ -189,6 +199,7 @@ let targets: [Target] = {
             "Services",
             "Logging",
             "RemoteSync",
+            "Availability",
             // MCP dependencies (for mcp serve command)
             "MCP",
             "MCPSupport",
@@ -296,6 +307,8 @@ let targets: [Target] = {
         mcpClientTestsTarget,
         remoteSyncTarget,
         remoteSyncTestsTarget,
+        availabilityTarget,
+        availabilityTestsTarget,
         testSupportTarget,
         cliTarget,
         tuiTarget,

Packages/Sources/Availability/Availability.swift

@@ -0,0 +1,6 @@
+import Foundation
+
+/// Namespace for availability-related types
+public enum Availability {
+    // Namespace root - types defined in extensions
+}

Packages/Sources/Availability/AvailabilityError.swift

@@ -0,0 +1,51 @@
+import Foundation
+
+// MARK: - Availability Errors
+
+/// Errors that can occur during availability fetching
+public enum AvailabilityError: Error, LocalizedError, Sendable {
+    /// Network request failed
+    case networkError(Error)
+
+    /// Request timed out
+    case timeout
+
+    /// API returned 404 (symbol not found)
+    case notFound(String)
+
+    /// Invalid response from API
+    case invalidResponse
+
+    /// Rate limited by API
+    case rateLimited
+
+    /// No documentation directory found
+    case noDocumentationFound
+
+    /// Failed to parse JSON
+    case jsonParseError(Error)
+
+    /// Failed to write updated file
+    case writeError(Error)
+
+    public var errorDescription: String? {
+        switch self {
+        case .networkError(let error):
+            return "Network error: \(error.localizedDescription)"
+        case .timeout:
+            return "Request timed out"
+        case .notFound(let symbol):
+            return "Symbol not found: \(symbol)"
+        case .invalidResponse:
+            return "Invalid response from Apple API"
+        case .rateLimited:
+            return "Rate limited by Apple API"
+        case .noDocumentationFound:
+            return "No documentation directory found"
+        case .jsonParseError(let error):
+            return "JSON parse error: \(error.localizedDescription)"
+        case .writeError(let error):
+            return "Failed to write file: \(error.localizedDescription)"
+        }
+    }
+}