feat(cli): Add privacy-first Sentry telemetry

.github/workflows/build-binaries.yml

@@ -25,6 +25,9 @@ on:
       APPLE_NOTARIZATION_APP_STORE_CONNECT_API_KEY_P8_BASE64:
         description: "Base64-encoded App Store Connect API key (.p8 PEM file) used for notarization"
         required: false
+      SENTRY_AUTH_TOKEN:
+        description: "Organization token used to upload Sentry debug symbols"
+        required: false
 
 jobs:
   build:
@@ -70,15 +73,51 @@ jobs:
 
               static let formatted =
                   "\\(version) (commit: \\(commit), built: \\(buildDate), environment: \\(environment))"
+              static let sentryRelease = "apple-docs@\\(version)+\\(commit)"
           }
           EOF
 
       - name: Build CLI
+        id: build
         run: |
           swift build -c release --arch "${{ matrix.architecture }}"
           BIN_DIR=$(swift build -c release --arch "${{ matrix.architecture }}" --show-bin-path)
+          test -d "$BIN_DIR/apple-docs.dSYM"
           mkdir -p dist
           cp "$BIN_DIR/apple-docs" "dist/apple-docs-${{ matrix.platform }}"
+          echo "bin_dir=$BIN_DIR" >> "$GITHUB_OUTPUT"
+
+      - name: Install sentry-cli
+        if: github.event_name != 'pull_request'
+        env:
+          SENTRY_CLI_VERSION: "3.7.0"
+          SENTRY_CLI_SHA256: "10ccaaa39e6eee2b52034546f5f617533fdc76c64aa75c3038887045da1a367d"
+        run: |
+          curl --fail --silent --show-error --location \
+            "https://github.com/getsentry/sentry-cli/releases/download/${SENTRY_CLI_VERSION}/sentry-cli-Darwin-universal" \
+            --output "$RUNNER_TEMP/sentry-cli"
+          echo "$SENTRY_CLI_SHA256  $RUNNER_TEMP/sentry-cli" | shasum -a 256 --check
+          chmod +x "$RUNNER_TEMP/sentry-cli"
+
+      - name: Upload dSYM to Sentry
+        if: github.event_name != 'pull_request'
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          SENTRY_ORG: techprimate
+          SENTRY_PROJECT: apple-docs-cli
+        run: |
+          if [ -z "$SENTRY_AUTH_TOKEN" ]; then
+            echo "::error::SENTRY_AUTH_TOKEN is not configured."
+            exit 1
+          fi
+
+          DSYM_PATH="${{ steps.build.outputs.bin_dir }}/apple-docs.dSYM"
+          "$RUNNER_TEMP/sentry-cli" debug-files check \
+            "$DSYM_PATH/Contents/Resources/DWARF/apple-docs"
+          "$RUNNER_TEMP/sentry-cli" debug-files upload \
+            --include-sources \
+            --wait \
+            "$DSYM_PATH"
 
       - name: Upload artifact
         uses: actions/upload-artifact@v7

Package.swift

@@ -9,13 +9,27 @@ let package = Package(
         .executable(name: "apple-docs", targets: ["CLI"])
     ],
     dependencies: [
-        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.8.2")
+        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.8.2"),
+        .package(url: "https://github.com/apple/swift-log.git", exact: "1.15.0"),
+        .package(
+            url: "https://github.com/getsentry/sentry-apple-swift-log.git",
+            exact: "9.27.0",
+            traits: ["SentryFromSource"]
+        ),
+        .package(
+            url: "https://github.com/getsentry/sentry-cocoa.git",
+            exact: "9.27.0",
+            traits: ["NoUIFramework"]
+        ),
     ],
     targets: [
         .executableTarget(
             name: "CLI",
             dependencies: [
-                .product(name: "ArgumentParser", package: "swift-argument-parser")
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "SentrySwiftLog", package: "sentry-apple-swift-log"),
+                .product(name: "SentrySPM", package: "sentry-cocoa"),
             ]),
         .testTarget(name: "CLITests", dependencies: ["CLI"]),
         .testTarget(name: "CLIIntegrationTests"),

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

@@ -1,6 +1,12 @@
 import ArgumentParser
+import Logging
+@preconcurrency import SentrySwift
 
 struct AgentSkillsGetCommand: ParsableCommand {
+    private static let logger = Logger(
+        label: "com.techprimate.apple-docs.agent-skills-get"
+    )
+
     static let configuration = CommandConfiguration(
         commandName: "get",
         abstract: "Print a bundled Agent Skill."
@@ -10,6 +16,35 @@ struct AgentSkillsGetCommand: ParsableCommand {
     var name: String
 
     mutating func run() throws {
+        if SentrySDK.isEnabled {
+            let context = SentryCommandContext.agentSkillsGet
+            let transaction = SentrySDK.startTransaction(
+                name: context.transactionName,
+                operation: "console.command",
+                bindToScope: true
+            )
+            for (key, value) in context.attributes {
+                transaction.setData(value: value, key: key)
+            }
+            SentrySDK.configureScope { scope in
+                scope.setContext(value: context.attributes, key: "cli")
+            }
+            let breadcrumb = Breadcrumb(
+                level: .info,
+                category: SentryConfiguration.breadcrumbCategory
+            )
+            breadcrumb.type = "user"
+            breadcrumb.message = "CLI command invoked"
+            for (key, value) in context.attributes {
+                breadcrumb.setData(value: value, key: key)
+            }
+            SentrySDK.addBreadcrumb(breadcrumb)
+            Self.logger.info(
+                "CLI command started",
+                metadata: context.logMetadata
+            )
+        }
+
         guard let skill = BundledAgentSkills.skill(named: name) else {
             throw ValidationError("Unknown bundled Agent Skill '\(name)'.")
         }

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

@@ -1,12 +1,47 @@
 import ArgumentParser
+import Logging
+@preconcurrency import SentrySwift
 
 struct AgentSkillsListCommand: ParsableCommand {
+    private static let logger = Logger(
+        label: "com.techprimate.apple-docs.agent-skills-list"
+    )
+
     static let configuration = CommandConfiguration(
         commandName: "list",
         abstract: "List Agent Skills bundled with apple-docs."
     )
 
     mutating func run() throws {
+        if SentrySDK.isEnabled {
+            let context = SentryCommandContext.agentSkillsList
+            let transaction = SentrySDK.startTransaction(
+                name: context.transactionName,
+                operation: "console.command",
+                bindToScope: true
+            )
+            for (key, value) in context.attributes {
+                transaction.setData(value: value, key: key)
+            }
+            SentrySDK.configureScope { scope in
+                scope.setContext(value: context.attributes, key: "cli")
+            }
+            let breadcrumb = Breadcrumb(
+                level: .info,
+                category: SentryConfiguration.breadcrumbCategory
+            )
+            breadcrumb.type = "user"
+            breadcrumb.message = "CLI command invoked"
+            for (key, value) in context.attributes {
+                breadcrumb.setData(value: value, key: key)
+            }
+            SentrySDK.addBreadcrumb(breadcrumb)
+            Self.logger.info(
+                "CLI command started",
+                metadata: context.logMetadata
+            )
+        }
+
         for skill in BundledAgentSkills.all {
             print("\(skill.name)\t\(skill.shortDescription)")
         }

Sources/CLI/cmd/technologies/TechnologiesListCommand.swift

@@ -1,6 +1,12 @@
 import ArgumentParser
+import Logging
+@preconcurrency import SentrySwift
 
 struct TechnologiesListCommand: AsyncParsableCommand {
+    private static let logger = Logger(
+        label: "com.techprimate.apple-docs.technologies-list"
+    )
+
     static let configuration = CommandConfiguration(
         commandName: "list",
         abstract: "List Apple documentation technologies."
@@ -10,10 +16,46 @@ struct TechnologiesListCommand: AsyncParsableCommand {
     var json = false
 
     mutating func run() async throws {
-        let output = try await TechnologiesListCommandRunner(
+        let context = SentryCommandContext.technologiesList(json: json)
+        if SentrySDK.isEnabled {
+            let transaction = SentrySDK.startTransaction(
+                name: context.transactionName,
+                operation: "console.command",
+                bindToScope: true
+            )
+            for (key, value) in context.attributes {
+                transaction.setData(value: value, key: key)
+            }
+            SentrySDK.configureScope { scope in
+                scope.setContext(value: context.attributes, key: "cli")
+            }
+            let breadcrumb = Breadcrumb(
+                level: .info,
+                category: SentryConfiguration.breadcrumbCategory
+            )
+            breadcrumb.type = "user"
+            breadcrumb.message = "CLI command invoked"
+            for (key, value) in context.attributes {
+                breadcrumb.setData(value: value, key: key)
+            }
+            SentrySDK.addBreadcrumb(breadcrumb)
+            Self.logger.info(
+                "CLI command started",
+                metadata: context.logMetadata
+            )
+        }
+
+        let result = try await TechnologiesListCommandRunner(
             client: Dependencies.documentationClient,
             renderer: Dependencies.technologyListRenderer(json: json)
         ).run()
-        print(output)
+        if SentrySDK.isEnabled {
+            SentrySDK.metrics.gauge(
+                key: "apple_docs.technology.catalog.count",
+                value: Double(result.technologyCount),
+                attributes: context.metricAttributes
+            )
+        }
+        print(result.output)
     }
 }

Sources/CLI/cmd/technologies/TechnologiesListCommandRunner.swift

@@ -1,6 +1,11 @@
 import Foundation
 
 struct TechnologiesListCommandRunner: Sendable {
+    struct Result: Sendable {
+        let output: String
+        let technologyCount: Int
+    }
+
     private let client: TechnologyCatalogClient
     private let renderer: TechnologyListRenderer
 
@@ -12,10 +17,13 @@ struct TechnologiesListCommandRunner: Sendable {
         self.renderer = renderer
     }
 
-    func run() async throws -> String {
+    func run() async throws -> Result {
         let technologies = try await client.fetchTechnologies().sorted {
             $0.name.compare($1.name, options: .caseInsensitive) == .orderedAscending
         }
-        return try renderer.render(technologies)
+        return Result(
+            output: try renderer.render(technologies),
+            technologyCount: technologies.count
+        )
     }
 }