TUI: Onboarding Wizard
Relevant source files
The following files were used as context for generating this wiki page:
The Onboarding Wizard is a Terminal User Interface (TUI) that guides users through the initial configuration of Tusk Drift for their service. Invoked via the tusk init command, its primary purpose is to interactively collect necessary project details and generate a .tusk/config.yaml file. The wizard is built using the Bubble Tea framework, providing a step-by-step, user-friendly experience.
This system is distinct from the AI-powered setup agent (invoked by tusk exp init) and the cloud-specific wizard (tusk init-cloud), which handle more advanced and specific setup scenarios. The standard onboarding wizard is the primary entry point for most users setting up Tusk Drift locally for the first time.
Sources: internal/tui/onboard/README.md, README.md:92-96
Architecture
The wizard's architecture is centered around the Bubble Tea Model-View-Update pattern and a custom Step interface that defines the behavior of each screen in the wizard.
Sources: internal/tui/onboard/README.md:7-10
Core Components
The main components of the wizard are organized within the internal/tui/onboard/ directory.
| File | Description |
|---|---|
run.go | The entry point that initializes the Bubble Tea program, model, and input fields. |
model.go | Defines the Model struct, which holds the entire state of the wizard, including user inputs and configuration choices. |
steps.go | Contains the concrete implementations for each step in the wizard flow. |
flow.go | Defines the Step interface and flow control logic. |
update.go | Implements the Update function, handling user input (key presses) and state transitions. |
view.go | Implements the View function, responsible for rendering the UI for each step. |
config.go | Defines the Config struct and logic for generating the final YAML output. |
Sources: internal/tui/onboard/README.md:12-23
This diagram shows the interaction between the core components of the onboarding TUI.
Sources: internal/tui/onboard/README.md:7-23
The Step Interface
Each screen in the wizard is a "step" that implements the Step interface. This interface dictates the behavior, appearance, and logic for each part of the configuration process. Most steps embed the BaseStep struct to inherit default method implementations.
Sources: internal/tui/onboard/README.md:25-27, internal/tui/onboard/README.md:49-55
| Method | Description |
|---|---|
ID() | Returns a unique identifier for the step (e.g., stepServiceName). |
InputIndex() | Returns the index of the textinput.Model to use for this step, or -1 if it doesn't require text input. |
Question(*Model) | The primary question or prompt displayed to the user. |
Description(*Model) | Additional explanatory text shown below the question. |
Default(*Model) | Provides a default value for the input field. |
Validate(*Model, string) | Validates the user's input, returning an error if invalid. |
Apply(*Model, string) | Updates the main Model with the validated user input. |
Help(*Model) | Returns the help text to be displayed in the footer. |
ShouldSkip(*Model) | A boolean check to determine if this step should be skipped based on the current state. |
Clear(*Model) | Resets the state associated with this step, used when navigating backward. |
Sources: internal/tui/onboard/README.md:29-47
Wizard Flow
The wizard proceeds through a predefined list of steps. Some steps are conditional and may be skipped based on previous user answers.
Sources: internal/tui/onboard/steps.go:3-19
Step Sequence
The following diagram illustrates the typical flow through the onboarding wizard.
Sources: internal/tui/onboard/steps.go:3-19
Key Steps
| Step Constant | Purpose | Implementation |
|---|---|---|
stepValidateRepo | Checks if the current directory is a supported project type (e.g., has package.json). | ValidateRepoStep |
stepIntro | Displays a welcome message. | IntroStep |
stepSDKCompatibility | Asks the user to confirm SDK compatibility. | SDKCompatibilityStep |
stepDockerSetup | Asks if the user will run their service with Docker. | DockerSetupStep |
stepDockerType | If both Dockerfile and docker-compose.yml exist, asks the user to choose. | DockerTypeStep |
stepServiceName | Collects the service name. | ServiceNameStep |
stepServicePort | Collects the service port. | ServicePortStep |
stepStartCommand | Collects the command to start the service. | StartCommandStep |
stepConfirm | Shows a preview of the generated config.yaml and asks for confirmation. | ConfirmStep |
stepDone | Displays a final message with next steps. | DoneStep |
Sources: internal/tui/onboard/steps.go, internal/tui/onboard/view.go:15-46
State Management and Navigation
The wizard's state is managed within the Model struct. User interactions trigger messages that are handled by the Update function, which in turn calls methods on the current Step to validate and apply changes to the model.
User Input and State Update Flow
This sequence diagram shows what happens when a user provides input and presses Enter.
Navigation
- Forward Navigation: Pressing
Enteron a valid step ory/non a confirmation step triggersadvance(), which moves to the next step. Steps whereShouldSkip()returnstrueare automatically bypassed. - Backward Navigation: Pressing
ctrl+bor the left arrow key pops the previous step from a history stack. TheclearValuesFromStep()helper is called to reset the state of the current step and all subsequent steps, preventing stale data from persisting.
Sources: internal/tui/onboard/README.md:121-133, internal/tui/onboard/view.go:211-215
View Rendering
The View() function in view.go is responsible for rendering the entire TUI. It uses a large switch statement based on the current step's ID to determine what to display.
- Default Steps: For most input steps, it displays a summary of previously entered data, the current question, description, default value, and the text input component.
- Validation Errors: If
m.ValidationErris notnil, the error message is rendered below the input field. - Confirmation Step (
stepConfirm): This step has custom rendering logic. It marshals the current configuration into a YAML string, formats it, and displays it within a scrollableviewportcomponent for the user to review before saving. - Done Step (
stepDone): This step displays a success message, the path to the saved configuration file, and a list of recommended next steps for the user.
Sources: internal/tui/onboard/view.go:11-208
Related Onboarding Tools
The tusk-drift-cli provides multiple ways to initialize a project, each with its own TUI.
Cloud Onboarding Wizard (tusk init-cloud)
This wizard is dedicated to configuring Tusk Drift Cloud features. It handles:
- Connecting a GitHub/GitLab repository.
- Registering the service with Tusk Drift Cloud.
- Creating an API key.
- Configuring cloud recording parameters.
Like the local wizard, it follows a step-based flow defined in internal/tui/onboard-cloud/steps.go.
Sources: internal/tui/onboard-cloud/steps.go:10-28, README.md:125-129
AI-Powered Setup Agent (tusk exp init)
This is an experimental, advanced alternative that uses an AI agent (Claude) to automate the setup process. The agent interacts with the user through a different TUI defined in internal/agent/tui.go. Instead of a rigid step-by-step wizard, it uses a phase-based approach where the AI determines which actions to take (e.g., read files, run commands) to gather information and configure the project.
The agent's goal is to automatically determine information like start_command, port, and entry_point by inspecting the codebase, which the user would otherwise provide manually in the standard wizard.
Sources: internal/agent/agent.go:1-19, internal/agent/tui.go, internal/agent/prompts/phase_gather_info_nodejs.md
Conclusion
The Onboarding Wizard (tusk init) is a foundational feature of the Tusk Drift CLI, providing a structured and interactive TUI for initial project configuration. Its step-based architecture, built on Bubble Tea, ensures a guided and error-resistant setup process. While more advanced wizards exist for cloud and AI-driven setup, this standard wizard remains the primary and most straightforward method for users to create their initial .tusk/config.yaml file.