ref(cli): Inject instance-based command dependencies

Sources/CLI/cache/DocumentationCache.swift

@@ -12,6 +12,13 @@ import Foundation
     }
 
     extension URLCache: DocumentationCache {}
+
+    protocol DocumentationCacheProvider {
+        associatedtype Cache: DocumentationCache
+        var documentationCache: Cache? { get }
+    }
+
+    extension Dependencies: DocumentationCacheProvider {}
 #else
     typealias DocumentationCache = URLCache
 #endif

Sources/CLI/client/AppleDocumentationClient.swift

@@ -10,6 +10,13 @@ import Logging
         func fetchType(named name: String, technology: String) async throws -> TypeDocumentationDocument
     }
     extension DefaultAppleDocumentationClient: AppleDocumentationClient {}
+
+    protocol AppleDocumentationClientProvider {
+        associatedtype Client: AppleDocumentationClient
+        var documentationClient: Client { get }
+    }
+
+    extension Dependencies: AppleDocumentationClientProvider {}
 #else
     typealias AppleDocumentationClient = DefaultAppleDocumentationClient<URLSession>
 #endif

Sources/CLI/client/DocumentationTypeCatalogClient.swift

@@ -10,6 +10,13 @@ import Foundation
     }
 
     extension DefaultAppleDocumentationClient: DocumentationTypeCatalogClient {}
+
+    protocol DocumentationTypeCatalogClientProvider {
+        associatedtype Client: DocumentationTypeCatalogClient
+        var documentationClient: Client { get }
+    }
+
+    extension Dependencies: DocumentationTypeCatalogClientProvider {}
 #else
     typealias DocumentationTypeCatalogClient = DefaultAppleDocumentationClient<URLSession>
 #endif

Sources/CLI/client/DocumentationTypeSearchClient.swift

@@ -15,6 +15,13 @@ struct DocumentationSearchResult: Equatable, Sendable {
     }
 
     extension DefaultAppleDocumentationClient: DocumentationTypeSearchClient {}
+
+    protocol DocumentationTypeSearchClientProvider {
+        associatedtype Client: DocumentationTypeSearchClient
+        var documentationClient: Client { get }
+    }
+
+    extension Dependencies: DocumentationTypeSearchClientProvider {}
 #else
     typealias DocumentationTypeSearchClient = DefaultAppleDocumentationClient<URLSession>
 #endif

Sources/CLI/client/TechnologyCatalogClient.swift

@@ -10,6 +10,13 @@ import Foundation
     }
 
     extension DefaultAppleDocumentationClient: TechnologyCatalogClient {}
+
+    protocol TechnologyCatalogClientProvider {
+        associatedtype Client: TechnologyCatalogClient
+        var documentationClient: Client { get }
+    }
+
+    extension Dependencies: TechnologyCatalogClientProvider {}
 #else
     typealias TechnologyCatalogClient = DefaultAppleDocumentationClient<URLSession>
 #endif

Sources/CLI/cmd/agent/skills/AgentSkillsGetCommand.swift

@@ -1,6 +1,12 @@
 import ArgumentParser
 
 struct AgentSkillsGetCommand: ParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any TelemetryProvider
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
 
     static let configuration = CommandConfiguration(
@@ -12,11 +18,11 @@ struct AgentSkillsGetCommand: ParsableCommand, GlobalOptionsProviding {
     var name: String
 
     mutating func run() throws {
-        try run(telemetry: Dependencies.telemetry)
+        try run(deps: Dependencies.shared)
     }
 
-    func run(telemetry: Telemetry) throws {
-        telemetry.startCommand(.agentSkillsGet)
+    func run(deps: Deps) throws {
+        deps.telemetry.startCommand(.agentSkillsGet)
         guard let skill = BundledAgentSkills.skill(named: name) else {
             throw ValidationError("Unknown bundled Agent Skill '\(name)'.")
         }

Sources/CLI/cmd/agent/skills/AgentSkillsInstallCommand.swift

@@ -1,6 +1,12 @@
 import ArgumentParser
 
 struct AgentSkillsInstallCommand: ParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any AgentSkillInstallerProvider
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
 
     static let configuration = CommandConfiguration(
@@ -28,7 +34,11 @@ struct AgentSkillsInstallCommand: ParsableCommand, GlobalOptionsProviding {
     }
 
     mutating func run() throws {
-        let output = try Dependencies.agentSkillInstaller().install(
+        try run(deps: Dependencies.shared)
+    }
+
+    func run(deps: Deps) throws {
+        let output = try deps.agentSkillInstaller().install(
             selection.selectedSkills(), root: selection.dir, dryRun: selection.dryRun, force: force
         )
         print(output)

Sources/CLI/cmd/agent/skills/AgentSkillsListCommand.swift

@@ -1,6 +1,12 @@
 import ArgumentParser
 
 struct AgentSkillsListCommand: ParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any TelemetryProvider
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
 
     static let configuration = CommandConfiguration(
@@ -9,11 +15,11 @@ struct AgentSkillsListCommand: ParsableCommand, GlobalOptionsProviding {
     )
 
     mutating func run() throws {
-        run(telemetry: Dependencies.telemetry)
+        run(deps: Dependencies.shared)
     }
 
-    func run(telemetry: Telemetry) {
-        telemetry.startCommand(.agentSkillsList)
+    func run(deps: Deps) {
+        deps.telemetry.startCommand(.agentSkillsList)
         for skill in BundledAgentSkills.all {
             print("\(skill.name)\t\(skill.shortDescription)")
         }

Sources/CLI/cmd/agent/skills/AgentSkillsUninstallCommand.swift

@@ -1,6 +1,12 @@
 import ArgumentParser
 
 struct AgentSkillsUninstallCommand: ParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any AgentSkillInstallerProvider
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
 
     static let configuration = CommandConfiguration(
@@ -31,7 +37,11 @@ struct AgentSkillsUninstallCommand: ParsableCommand, GlobalOptionsProviding {
     }
 
     mutating func run() throws {
-        let output = try Dependencies.agentSkillInstaller().uninstall(
+        try run(deps: Dependencies.shared)
+    }
+
+    func run(deps: Deps) throws {
+        let output = try deps.agentSkillInstaller().uninstall(
             selection.selectedSkills(), root: selection.dir, dryRun: selection.dryRun
         )
         print(output)

Sources/CLI/cmd/cache/CacheCleanCommand.swift

@@ -1,6 +1,12 @@
 import ArgumentParser
 
 struct CacheCleanCommand: ParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any (TelemetryProvider & DocumentationCacheProvider)
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
 
     static let configuration = CommandConfiguration(
@@ -9,14 +15,15 @@ struct CacheCleanCommand: ParsableCommand, GlobalOptionsProviding {
     )
 
     mutating func run() throws {
-        run(telemetry: Dependencies.telemetry)
+        run(deps: Dependencies.shared)
     }
 
-    func run(telemetry: Telemetry) {
-        telemetry.startCommand(.cacheClean)
-        let result = CacheCleanCommandRunner(
-            cache: Dependencies.documentationCache
-        ).run()
+    func run(deps: Deps) {
+        deps.telemetry.startCommand(.cacheClean)
+        let runner = CacheCleanCommandRunner(
+            cache: deps.documentationCache
+        )
+        let result = runner.run()
         print(result.output)
     }
 }

Sources/CLI/cmd/technologies/TechnologiesListCommand.swift

@@ -1,6 +1,15 @@
 import ArgumentParser
 
 struct TechnologiesListCommand: AsyncParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any (
+            TelemetryProvider & TerminalCapabilitiesProvider & TechnologyCatalogClientProvider
+                & TechnologyListRendererProvider
+        )
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
     @OptionGroup var output: OutputOptions
 
@@ -10,17 +19,18 @@ struct TechnologiesListCommand: AsyncParsableCommand, GlobalOptionsProviding {
     )
 
     mutating func run() async throws {
-        try await run(telemetry: Dependencies.telemetry)
+        try await run(deps: Dependencies.shared)
     }
 
-    func run(telemetry: Telemetry) async throws {
+    func run(deps: Deps) async throws {
         let context = TelemetryCommandContext.technologiesList(json: output.json)
-        telemetry.startCommand(context)
-        let result = try await TechnologiesListCommandRunner(
-            client: Dependencies.documentationClient,
-            renderer: Dependencies.technologyListRenderer(output: output)
-        ).run()
-        telemetry.record(.technologyCatalog(count: result.technologyCount), context: context)
+        deps.telemetry.startCommand(context)
+        let runner = TechnologiesListCommandRunner(
+            client: deps.documentationClient,
+            renderer: deps.technologyListRenderer(output: output)
+        )
+        let result = try await runner.run(mode: deps.terminalCapabilities.mode(for: output))
+        deps.telemetry.record(.technologyCatalog(count: result.technologyCount), context: context)
         print(result.output)
     }
 }

Sources/CLI/cmd/technologies/TechnologiesListCommandRunner.swift

@@ -17,7 +17,7 @@ struct TechnologiesListCommandRunner: Sendable {
         self.renderer = renderer
     }
 
-    func run() async throws -> Result {
+    func run(mode: OutputMode) async throws -> Result {
         let technologies = try await client.fetchTechnologies().sorted {
             $0.name.compare($1.name, options: .caseInsensitive) == .orderedAscending
         }

Sources/CLI/cmd/types/TypesListCommand.swift

@@ -1,6 +1,15 @@
 import ArgumentParser
 
 struct TypesListCommand: AsyncParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any (
+            TelemetryProvider & TerminalCapabilitiesProvider & DocumentationTypeCatalogClientProvider
+                & DocumentationTypeListRendererProvider
+        )
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
     @OptionGroup var output: OutputOptions
 
@@ -13,17 +22,18 @@ struct TypesListCommand: AsyncParsableCommand, GlobalOptionsProviding {
     var technology: String
 
     mutating func run() async throws {
-        try await run(telemetry: Dependencies.telemetry)
+        try await run(deps: Dependencies.shared)
     }
 
-    func run(telemetry: Telemetry) async throws {
+    func run(deps: Deps) async throws {
         let context = TelemetryCommandContext.typesList(technology: technology, json: output.json)
-        telemetry.startCommand(context)
-        let result = try await TypesListCommandRunner(
-            client: Dependencies.documentationClient,
-            renderer: Dependencies.documentationTypeListRenderer(output: output, technology: technology)
-        ).run(technology: technology)
-        telemetry.record(.typeCatalog(count: result.typeCount), context: context)
+        deps.telemetry.startCommand(context)
+        let runner = TypesListCommandRunner(
+            client: deps.documentationClient,
+            renderer: deps.documentationTypeListRenderer(output: output, technology: technology)
+        )
+        let result = try await runner.run(technology: technology, mode: deps.terminalCapabilities.mode(for: output))
+        deps.telemetry.record(.typeCatalog(count: result.typeCount), context: context)
         print(result.output)
     }
 }

Sources/CLI/cmd/types/TypesListCommandRunner.swift

@@ -15,7 +15,7 @@ struct TypesListCommandRunner: Sendable {
         self.renderer = renderer
     }
 
-    func run(technology: String) async throws -> Result {
+    func run(technology: String, mode: OutputMode) async throws -> Result {
         let types = try await client.fetchTypes(technology: technology)
         return Result(
             output: try renderer.render(types),

Sources/CLI/cmd/types/TypesSearchCommand.swift

@@ -2,6 +2,15 @@ import ArgumentParser
 import Foundation
 
 struct TypesSearchCommand: AsyncParsableCommand, GlobalOptionsProviding {
+    #if DEBUG
+        typealias Deps = any (
+            TelemetryProvider & TerminalCapabilitiesProvider & DocumentationTypeSearchClientProvider
+                & DocumentationTypeListRendererProvider
+        )
+    #else
+        typealias Deps = Dependencies
+    #endif
+
     @OptionGroup var global: GlobalOptions
     @OptionGroup var output: OutputOptions
 
@@ -17,18 +26,20 @@ struct TypesSearchCommand: AsyncParsableCommand, GlobalOptionsProviding {
     var technology: String
 
     mutating func run() async throws {
-        try await run(telemetry: Dependencies.telemetry)
+        try await run(deps: Dependencies.shared)
     }
 
-    func run(telemetry: Telemetry) async throws {
+    func run(deps: Deps) async throws {
         // Search text can be user-authored, so it is deliberately excluded from telemetry context.
         let context = TelemetryCommandContext.typesSearch(technology: technology, json: output.json)
-        telemetry.startCommand(context)
-        let result = try await TypesSearchCommandRunner(
-            client: Dependencies.documentationClient,
-            renderer: Dependencies.documentationTypeListRenderer(output: output, technology: technology)
-        ).run(query: query, technology: technology)
-        telemetry.record(.typeSearch(matches: result.matchCount), context: context)
+        deps.telemetry.startCommand(context)
+        let runner = TypesSearchCommandRunner(
+            client: deps.documentationClient,
+            renderer: deps.documentationTypeListRenderer(output: output, technology: technology)
+        )
+        let result = try await runner.run(
+            query: query, technology: technology, mode: deps.terminalCapabilities.mode(for: output))
+        deps.telemetry.record(.typeSearch(matches: result.matchCount), context: context)
         if result.unavailableCollectionCount > 0 {
             let warning =
                 "Warning: search results are incomplete. "

Sources/CLI/cmd/types/TypesSearchCommandRunner.swift

@@ -16,7 +16,7 @@ struct TypesSearchCommandRunner: Sendable {
         self.renderer = renderer
     }
 
-    func run(query: String, technology: String) async throws -> Result {
+    func run(query: String, technology: String, mode: OutputMode) async throws -> Result {
         let result = try await client.searchTypes(query: query, technology: technology)
         return Result(
             output: try renderer.render(result.types),