### Basic HTTP Artifact Installation

Source: https://github.com/shopify/tophat/blob/main/README.md

Use the built-in HTTP provider to install an application from a public URL.

```text
tophat://install/http?url=<full_public_url>
```

--------------------------------

### Tophatctl CLI - Install Applications

Source: https://context7.com/shopify/tophat/llms.txt

Use the tophatctl command-line utility to install applications from local paths, URLs, Quick Launch entries, or JSON configuration files. Supports passing launch arguments.

```bash
tophatctl --help
```

```bash
tophatctl install /path/to/app.ipa
```

```bash
tophatctl install https://example.com/app.apk --launch-arguments --debug --env staging
```

```bash
tophatctl install my-app-id
```

```bash
tophatctl install /path/to/config.json
```

--------------------------------

### JSON Configuration - Basic Install Recipe

Source: https://context7.com/shopify/tophat/llms.txt

Define basic installation recipes in JSON format. Each recipe specifies an artifact provider, its parameters, launch arguments, and platform/destination hints.

```json
[
  {
    "artifactProviderID": "http",
    "artifactProviderParameters": {
      "url": "https://example.com/builds/app-device.ipa"
    },
    "launchArguments": ["--debug", "--api-url=https://staging.example.com"],
    "platformHint": "ios",
    "destinationHint": "device"
  },
  {
    "artifactProviderID": "http",
    "artifactProviderParameters": {
      "url": "https://example.com/builds/app-simulator.app.zip"
    },
    "launchArguments": [],
    "platformHint": "ios",
    "destinationHint": "simulator"
  }
]
```

--------------------------------

### Install Mint via Homebrew

Source: https://github.com/shopify/tophat/blob/main/CONTRIBUTING.md

Use this command to install the Mint package manager on macOS.

```bash
brew install mint
```

--------------------------------

### Constructing Tophat Installation URLs

Source: https://github.com/shopify/tophat/blob/main/README.md

Use these URL patterns to trigger app installations. The tophat:// scheme is preferred over http:// to prevent page navigation.

```text
tophat://install/gcs?bucket=<bucket>&object=<object>
```

```text
tophat://install/gcs?bucket=<bucket>&object=<object>&platform=ios&destination=device
```

```text
tophat://install/gcs?bucket=<bucket>&object=<object>&platform=ios&destination=device&bucket=<bucket>&object=<object>&platform=ios&destination=simulator
```

```text
tophat://install/gcs?bucket=<bucket>&object=<object>&arguments=one,two,three
```

--------------------------------

### Bootstrap Mint Dependencies

Source: https://github.com/shopify/tophat/blob/main/CONTRIBUTING.md

Run this command to install project dependencies defined in the Mintfile.

```bash
mint bootstrap
```

--------------------------------

### Make Script Executable and Install via URL/tophatctl

Source: https://context7.com/shopify/tophat/llms.txt

Commands to make the custom artifact download script executable and then install it using Tophat. This can be done via the `open` command with a URL or using the `tophatctl` command-line tool.

```bash
# Make script executable
chmod +x ~/Library/Application\ Scripts/com.shopify.Tophat.TophatCoreExtension/download-artifact.sh

# Use via URL
open "tophat://install/shell?script=download-artifact.sh"

# Or via tophatctl
tophatctl install "tophat://install/shell?script=download-artifact.sh"

```

--------------------------------

### Install Applications via URL Schemes

Source: https://context7.com/shopify/tophat/llms.txt

Use Tophat's URL schemes to install applications directly to devices or simulators. Supports various artifact providers like HTTP, Bitrise, GitHub Actions, and shell scripts. Can specify platform, destination, and launch arguments.

```bash
tophat://install/http?url=https://example.com/builds/app-release.apk
```

```bash
tophat://install/http?url=https://example.com/builds/app.ipa&platform=ios&destination=device
```

```bash
tophat://install/http?url=https://example.com/device.ipa&platform=ios&destination=device&url=https://example.com/sim.app&platform=ios&destination=simulator
```

```bash
tophat://install/http?url=https://example.com/app.ipa&arguments=--debug,--env=staging
```

```bash
tophat://install/bitrise?app_slug=abc123&build_slug=def456&artifact_slug=ghi789
```

```bash
tophat://install/bitrise-branch?app_slug=abc123&branch=main&workflow=build&artifact_name=app-release.apk
```

```bash
tophat://install/gha?owner=shopify&repo=my-app&artifact_id=123456789
```

```bash
tophat://install/shell?script=download-artifact.sh
```

--------------------------------

### Configure Quick Launch Entry (JSON)

Source: https://context7.com/shopify/tophat/llms.txt

Define app identity, display name, and installation recipes for different platforms and destinations. This JSON file configures a persistent app entry for Quick Launch.

```json
// Quick Launch entry configuration (my-app.json)
{
  "id": "my-app",
  "name": "My Application",
  "recipes": [
    {
      "artifactProviderID": "bitrise-branch",
      "artifactProviderParameters": {
        "app_slug": "abc123",
        "branch": "main",
        "workflow": "ios-release",
        "artifact_name": "MyApp.ipa"
      },
      "launchArguments": [],
      "platformHint": "ios",
      "destinationHint": "device"
    },
    {
      "artifactProviderID": "bitrise-branch",
      "artifactProviderParameters": {
        "app_slug": "abc123",
        "branch": "main",
        "workflow": "ios-simulator",
        "artifact_name": "MyApp.app.zip"
      },
      "launchArguments": [],
      "platformHint": "ios",
      "destinationHint": "simulator"
    },
    {
      "artifactProviderID": "bitrise-branch",
      "artifactProviderParameters": {
        "app_slug": "xyz789",
        "branch": "main",
        "workflow": "android-release",
        "artifact_name": "app-release.apk"
      },
      "launchArguments": [],
      "platformHint": "android",
      "destinationHint": null
    }
  ]
}
```

--------------------------------

### iOS - Retrieving Launch Arguments

Source: https://context7.com/shopify/tophat/llms.txt

Example of how to access launch arguments passed from Tophat within an iOS application using `ProcessInfo.processInfo.arguments`.

```swift
// iOS - Retrieving launch arguments in your app
import Foundation

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Access arguments passed from Tophat
        let arguments = ProcessInfo.processInfo.arguments

        if arguments.contains("--debug") {
            enableDebugMode()
        }

        if let envIndex = arguments.firstIndex(of: "--env"),
           envIndex + 1 < arguments.count {
            let environment = arguments[envIndex + 1]
            configureEnvironment(environment)
        }

        return true
    }
}
```

--------------------------------

### Android - Retrieving Launch Arguments

Source: https://context7.com/shopify/tophat/llms.txt

Example of how to access launch arguments passed from Tophat within an Android application via intent extras.

```kotlin
// Android - Retrieving launch arguments in your app
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Access arguments passed from Tophat via intent extras
        val tophatArguments = intent.getStringArrayExtra("TOPHAT_ARGUMENTS")

        tophatArguments?.let { args ->
            if (args.contains("--debug")) {
                enableDebugMode()
            }

            val envIndex = args.indexOf("--env")
            if (envIndex >= 0 && envIndex + 1 < args.size) {
                val environment = args[envIndex + 1]
                configureEnvironment(environment)
            }
        }
    }
}
```

--------------------------------

### JSON Configuration - Specific Device Targeting

Source: https://context7.com/shopify/tophat/llms.txt

Create install recipes with specific device targeting. This allows precise selection of devices based on name, platform, and runtime version.

```json
[
  {
    "artifactProviderID": "bitrise-branch",
    "artifactProviderParameters": {
      "app_slug": "abc123def456",
      "branch": "feature/new-ui",
      "workflow": "ios-build",
      "artifact_name": "MyApp.ipa"
    },
    "launchArguments": [],
    "device": {
      "name": "iPhone 16 Pro",
      "platform": "ios",
      "runtimeVersion": "18.2"
    }
  }
]
```

--------------------------------

### Implement Google Cloud Storage Artifact Provider

Source: https://github.com/shopify/tophat/blob/main/TophatKit/README.md

An example of an artifact provider conforming to the `ArtifactProvider` protocol. It defines parameters for bucket and object, and implements `retrieve` and `cleanUp` functions. The `id` is used for identification, and `title` for UI display.

```swift
// GoogleCloudStorageArtifactProvider.swift

import TophatKit

struct GoogleCloudStorageArtifactProvider: ArtifactProvider {
  static let id = "gcs"
  static let title: LocalizedStringResource = "Google Cloud Storage"

  @Parameter(key: "bucket", title: "Bucket")
  var bucket: String

  @Parameter(key: "object", title: "Object")
  var object: String

  func retrieve() async throws -> some ArtifactProviderResult {
    let downloadedFileURL = // Your logic for downloading the build.

    return .result(localURL: downloadedFileURL)
  }

  func cleanUp(localURL: URL) async throws {
    // Perform clean up.
  }
}
```

--------------------------------

### Tophat Built-in Artifact Providers

Source: https://context7.com/shopify/tophat/llms.txt

Reference for Tophat's built-in artifact providers, including their IDs, required parameters, and URL formats for installation.

```swift
// HTTP Provider (id: "http")
// Parameters: url (required)
// URL: tophat://install/http?url=<full_public_url>
```

```swift
// Shell Script Provider (id: "shell")
// Parameters: script (required) - filename in Application Scripts folder
// URL: tophat://install/shell?script=<filename>
```

```swift
// Bitrise Provider (id: "bitrise")
// Parameters: app_slug, build_slug, artifact_slug (all required)
// Requires: Personal Access Token configured in extension settings
// URL: tophat://install/bitrise?app_slug=<slug>&build_slug=<slug>&artifact_slug=<slug>
```

```swift
// Bitrise Branch Provider (id: "bitrise-branch")
// Parameters: app_slug, branch, workflow, artifact_name (all required)
// Requires: Personal Access Token configured in extension settings
// URL: tophat://install/bitrise-branch?app_slug=<slug>&branch=<branch>&workflow=<workflow>&artifact_name=<name>
```

```swift
// GitHub Actions Provider (id: "gha")
// Parameters: owner, repo, artifact_id (all required)
// Requires: Personal Access Token configured in extension settings
// URL: tophat://install/gha?owner=<owner>&repo=<repo>&artifact_id=<id>
```

--------------------------------

### Invoke a custom shell script for artifact installation

Source: https://github.com/shopify/tophat/blob/main/README.md

Use this URL scheme to trigger a shell script located in the TophatCoreExtension directory. The script receives staging and output directory paths as positional arguments.

```text
tophat://install/shell?script=filename
```

--------------------------------

### Tophatctl CLI - Manage Quick Launch and Providers

Source: https://context7.com/shopify/tophat/llms.txt

Manage Quick Launch entries and list available artifact providers and devices using the tophatctl CLI. Supports JSON output for scripting.

```bash
tophatctl list providers
```

```bash
tophatctl list providers --json
```

```bash
tophatctl list apps
```

```bash
tophatctl list devices
```

```bash
tophatctl list devices --json
```

```bash
tophatctl apps add /path/to/quick-launch-config.json
```

```bash
tophatctl apps remove my-app-id
```

--------------------------------

### Access tophatctl command line help

Source: https://github.com/shopify/tophat/blob/main/README.md

Display available commands and usage information for the tophatctl companion tool.

```sh
tophatctl --help
```

--------------------------------

### Basic Extension Entry Point

Source: https://context7.com/shopify/tophat/llms.txt

Defines the main entry point for a Tophat extension, conforming to TophatExtension and ArtifactProviding. Requires a title and can optionally provide a description and artifact providers.

```swift
// MyExtension.swift - Basic extension entry point
import TophatKit

@main
struct MyExtension: TophatExtension, ArtifactProviding {
    static let title: LocalizedStringResource = "My Custom Extension"
    static let description: LocalizedStringResource? = "Downloads artifacts from our internal build system"

    static var artifactProviders: some ArtifactProviders {
        InternalBuildArtifactProvider()
    }
}
```

--------------------------------

### Implement SettingsProviding for Configurable Extension

Source: https://github.com/shopify/tophat/blob/main/TophatKit/README.md

Conform your Tophat extension to the SettingsProviding protocol to enable user configuration. The `settings` property should return a SwiftUI view that represents the extension's settings interface. Users can access this view through Tophat's extension settings menu.

```swift
// GoogleCloudExtension.swift

import SwiftUI
import TophatKit

@main
struct MyExtension: TophatExtension, ArtifactProviding, SettingsProviding {
  // ...

  static var settings: some View {
    Text("Settings")
  }
}
```

--------------------------------

### Custom Artifact Provider Implementation

Source: https://context7.com/shopify/tophat/llms.txt

Implements a custom artifact provider for downloading specific build artifacts. It defines parameters for project, build number, and variant, and handles authentication and downloading via URLSession.

```swift
// InternalBuildArtifactProvider.swift - Custom artifact provider
import Foundation
import TophatKit

struct InternalBuildArtifactProvider: ArtifactProvider {
    static let id = "internal-builds"
    static let title: LocalizedStringResource = "Internal Build System"

    @Parameter(key: "project", title: "Project")
    var project: String

    @Parameter(key: "build_number", title: "Build Number")
    var buildNumber: String

    @Parameter(
        key: "variant",
        title: "Variant",
        description: "The build variant to download",
        prompt: "e.g., debug, release"
    )
    var variant: String

    func retrieve() async throws -> some ArtifactProviderResult {
        // Build the download URL from parameters
        let downloadURL = URL(string: "https://builds.internal.example.com/\(project)/\(buildNumber)/\(variant).ipa")!

        // Authenticate and download
        var request = URLRequest(url: downloadURL)
        request.setValue("Bearer \(getAPIToken())", forHTTPHeaderField: "Authorization")

        let (downloadedFileURL, response) = try await URLSession.shared.download(for: request)

        // Move to destination
        let destinationDir: URL = .temporaryDirectory.appending(path: UUID().uuidString)
        try FileManager.default.createDirectory(at: destinationDir, withIntermediateDirectories: true)

        let destinationURL = destinationDir.appending(
            component: response.suggestedFilename ?? downloadedFileURL.lastPathComponent
        )
        try FileManager.default.moveItem(at: downloadedFileURL, to: destinationURL)

        return .result(localURL: destinationURL)
    }

    func cleanUp(localURL: URL) async throws {
        try FileManager.default.removeItem(at: localURL)
    }

    private func getAPIToken() -> String {
        // Retrieve from Keychain or secure storage
        return "your-api-token"
    }
}
```

--------------------------------

### Custom Shell Script for Artifact Download

Source: https://context7.com/shopify/tophat/llms.txt

Implement custom artifact retrieval logic using a bash script. Place scripts in `~/Library/Application Scripts/com.shopify.Tophat.TophatCoreExtension/` and ensure they are executable. The script receives staging and output directories as arguments.

```bash
#!/bin/bash
# download-artifact.sh - Custom artifact download script
# $1 = staging directory (for temporary files during download)
# $2 = output directory (final artifact must be placed here)

STAGING_DIR="$1"
OUTPUT_DIR="$2"

# Example: Download from authenticated S3 bucket
aws s3 cp s3://my-builds-bucket/latest/app-release.ipa "$STAGING_DIR/app.ipa"

# Unzip if needed
# unzip "$STAGING_DIR/app.zip" -d "$STAGING_DIR"

# Move final artifact to output directory
mv "$STAGING_DIR/app.ipa" "$OUTPUT_DIR/"

# Tophat will find and install the artifact from OUTPUT_DIR

```

--------------------------------

### Extension with Settings Interface

Source: https://context7.com/shopify/tophat/llms.txt

An extension that provides both artifact providing and a SwiftUI settings interface. The settings view is displayed in Tophat's Settings window under Extensions.

```swift
// ConfigurableExtension.swift - Extension with settings
import SwiftUI
import TophatKit

@main
struct ConfigurableExtension: TophatExtension, ArtifactProviding, SettingsProviding {
    static let title: LocalizedStringResource = "Cloud Storage Extension"

    static var artifactProviders: some ArtifactProviders {
        CloudStorageArtifactProvider()
    }

    static var settings: some View {
        ExtensionSettingsView()
    }
}
```

--------------------------------

### Register Artifact Provider in Extension

Source: https://github.com/shopify/tophat/blob/main/TophatKit/README.md

Register the created artifact provider by conforming the main extension struct to `ArtifactProviding` and providing an implementation for the `artifactProviders` static property.

```swift
// MyExtension.swift

import TophatKit

@main
struct MyExtension: TophatExtension, ArtifactProviding {
  static let title: LocalizedStringResource = "My Extension"

  static var artifactProviders: some ArtifactProviders {
    GoogleCloudStorageArtifactProvider()
  }
}
```

--------------------------------

### SwiftUI Settings Interface for Extension

Source: https://context7.com/shopify/tophat/llms.txt

A SwiftUI view for configuring extension settings, including API keys and preferences like region and default bucket. Uses @AppStorage for persistent settings and SecureField for sensitive information.

```swift
// ExtensionSettingsView.swift - SwiftUI settings interface
import SwiftUI

struct ExtensionSettingsView: View {
    @AppStorage("cloudStorageRegion") private var region = "us-east-1"
    @AppStorage("cloudStorageBucket") private var defaultBucket = ""
    @State private var apiKey = ""

    var body: some View {
        Form {
            Section("Authentication") {
                SecureField("API Key", text: $apiKey)
                    .onSubmit { saveAPIKey() }

                Button("Save API Key") { saveAPIKey() }
            }

            Section("Defaults") {
                TextField("Default Bucket", text: $defaultBucket)

                Picker("Region", selection: $region) {
                    Text("US East").tag("us-east-1")
                    Text("US West").tag("us-west-2")
                    Text("EU West").tag("eu-west-1")
                }
            }
        }
        .formStyle(.grouped)
    }

    private func saveAPIKey() {
        // Save to Keychain
        KeychainHelper.save(key: "cloud-storage-api-key", value: apiKey)
    }
}
```

--------------------------------

### Basic Tophat Extension Structure

Source: https://github.com/shopify/tophat/blob/main/TophatKit/README.md

This is the default structure for a Tophat extension. It must conform to the `TophatExtension` protocol. Additional functionality can be added by conforming to other protocols like `ArtifactProviding`.

```swift
// MyExtension.swift

import TophatKit

@main
struct MyExtension: TophatExtension {
  static let title: LocalizedStringResource = "My Extension"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.