Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Tusk Drift CLI is a Go-based command-line tool designed to orchestrate API test recording and replay. It interacts with a language-specific Tusk Drift SDK embedded in a user's service and the Tusk Drift Cloud platform. The CLI's architecture is centered around a few key functionalities: interactive user onboarding, AI-powered automated setup, and local/cloud test execution.
The primary commands are tusk init for guided local setup, tusk cloud-init for cloud integration, tusk run for executing replay tests, and tusk list for viewing available traces. The core logic is housed within the internal/ directory, which contains distinct packages for the AI agent, terminal UI (TUI), test runner, and API communication.
Sources: README.md, CONTRIBUTING.md
High-Level Component Diagram
The following diagram illustrates the main components of the Tusk Drift CLI and their interactions.
This diagram shows that CLI commands trigger one of three main internal modules: the AI Agent, the TUI, or the Test Runner. The Agent uses the Claude API for its logic, while the Runner and API client interact with the user's service and Tusk Drift Cloud, respectively.
Sources: internal/agent/README.md, CONTRIBUTING.md
Code Structure
The project is organized into cmd/ for command definitions and internal/ for all core logic, ensuring a clear separation of concerns.
| Directory | Description |
|---|---|
cmd/ | Contains Cobra command definitions (e.g., run, init, list). |
internal/agent/ | Implements the AI-powered setup agent using the Claude API. |
internal/api/ | A protobuf-over-HTTP client for communicating with the Tusk Drift Cloud backend. |
internal/auth/ | Manages the Auth0 device code flow and token persistence for cloud authentication. |
internal/config/ | Handles loading and managing the .tusk/config.yaml file using Koanf. |
internal/runner/ | Contains the core test execution logic, including the executor, Unix socket server, and response comparison. |
internal/tui/ | Contains all interactive Terminal UI components built with Bubble Tea, including the tusk init and tusk run interfaces. |
internal/utils/ | Shared helper functions. |
docs/ | Contains architecture, configuration, and troubleshooting documentation. |
Sources: CONTRIBUTING.md
AI-Powered Setup Agent (internal/agent)
A key feature is the AI-powered setup agent, triggered by tusk exp init. This system uses the Claude API to automate the process of installing and configuring the Tusk Drift SDK in a user's project. It operates as a state machine, moving through a series of predefined phases.
Sources: internal/agent/README.md, internal/agent/agent.go
Agent Architecture
The agent's architecture is composed of a main loop, a phase manager, a tool executor, and a Claude API client.
- Agent (
agent.go): The main control loop that orchestrates the entire process. It iterates through phases, assembles prompts, sends them to the Claude API, and dispatches tool execution requests. - Phase Manager (
phases.go): Defines the sequence of steps (phases) the agent must complete. It manages state transitions and provides the instructions for the current phase. - Tool Executor (
executor.go): A registry of functions (tools) that the AI can invoke to interact with the local environment. This includes reading/writing files, running commands, and making HTTP requests. - Claude Client (
api.go): Handles communication with the Claude API. - Prompts (
prompts/*.md): Markdown files containing the system prompt and specific instructions for the AI for each phase.
Sources: internal/agent/README.md, internal/agent/agent.go, internal/agent/phases.go, internal/agent/executor.go
Agent Execution Flow
The agent executes a loop for each phase, continuing until the transition_phase tool is called or an error occurs.
Sources: internal/agent/agent.go:318-459
Agent Phases
The setup process is broken down into a series of distinct, ordered phases. Each phase has a clear objective, a set of available tools, and specific instructions for the AI.
| Phase ID | Name | Description | Required |
|---|---|---|---|
detect_language | Detect Language | Identify the project's language/runtime | Yes |
check_compatibility | Check Compatibility | Verify project dependencies are compatible with the SDK | Yes |
gather_info | Gather Project Info | Collect project details for SDK setup | Yes |
confirm_app_starts | Confirm App Starts | Verify the service starts without Tusk Drift | Yes |
instrument_sdk | Instrument SDK | Install and configure the Tusk Drift SDK | Yes |
create_config | Create Config | Create the .tusk/config.yaml file | Yes |
simple_test | Simple Test | Record and replay a simple health check | Yes |
complex_test | Complex Test | Test an endpoint that makes external calls | No |
summary | Summary | Generate the setup report | Yes |
Sources: internal/agent/phases.go:260-394
Agent Tools
The AI interacts with the user's system via a predefined set of tools. This provides a safe and controlled execution environment. Critical tools that modify the filesystem or run commands require user confirmation by default.
| Tool Name | Description |
|---|---|
read_file | Read the contents of a file. |
write_file | Write content to a file. |
run_command | Run a one-shot shell command and wait for it to complete. |
start_background_process | Start a long-running process (e.g., a server). |
ask_user | Ask the user a question and wait for their response. |
tusk_run | Run 'tusk run' to replay recorded traces. |
transition_phase | Complete the current phase and move to the next one. |
abort_setup | Abort the setup process gracefully. |
Sources: internal/agent/executor.go:10-47
TUI Onboarding Wizards (internal/tui)
For users who prefer a guided experience, the CLI provides interactive Terminal UIs for tusk init and tusk cloud-init. These wizards are built using the Bubble Tea framework.
The core of the wizard architecture is the Step interface, which defines a single screen or prompt in the onboarding flow.
Sources: internal/tui/onboard/README.md
The Step Interface
Each step in the wizard implements the Step interface, which dictates its behavior, appearance, and logic.
type Step interface {
ID() onboardStep
InputIndex() int
Question(*Model) string
Description(*Model) string
Default(*Model) string
Validate(*Model, string) error
Apply(*Model, string)
Help(*Model) string
ShouldSkip(*Model) bool
Clear(*Model)
}
Most steps embed a BaseStep struct that provides default implementations for these methods, allowing developers to override only what is necessary.
Sources: internal/tui/onboard/README.md
Onboarding Flow
The wizard is managed by a Flow controller that progresses through a predefined list of Step implementations. The main application Model holds the state, and the Update function handles user input (key presses) to transition between steps or update state.
The flow for the tusk init command is defined in internal/tui/onboard/steps.go.
This diagram shows the sequence of steps for the tusk init wizard. Some steps, like DockerTypeStep, are conditional based on previous answers.
Sources: internal/tui/onboard/steps.go:4-21, internal/tui/onboard/README.md
Release Process
Releases are automated using GoReleaser via GitHub Actions. A new release is created by running the scripts/release.sh script, which performs several preflight checks before tagging a new version.
The script's workflow is as follows:
- Validate Bump Type: Ensures the argument is
patchorminor. - Preflight Checks:
- Verifies the repository is clean and on the
mainbranch. - Fetches the latest changes from
origin. - Ensures the local branch is up-to-date.
- Checks that tests (
make test-ci) and linting (make lint) pass.
- Verifies the repository is clean and on the
- Calculate New Version: Bumps the version from the last git tag.
- Confirm and Tag: Prompts the user for confirmation, then creates and pushes an annotated git tag.
Once the tag is pushed, a GitHub Action builds and publishes the binaries for Linux, macOS, and Windows (amd64, arm64).
Sources: scripts/release.sh, CONTRIBUTING.md