Saving and Uploading Results

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/run.go
• internal/agent/agent.go
• internal/agent/prompts/phase_cloud_summary.md
• internal/agent/prompts/phase_summary.md
• internal/tui/onboard-cloud/save_test.go
• internal/tui/onboard-cloud/steps.go
• internal/tui/onboard/config.go

The tusk-drift-cli provides several mechanisms for saving and uploading results, which are crucial for local debugging, CI/CD integration, and cloud-based analysis. These mechanisms handle test run outcomes, configuration files generated by interactive wizards, and progress reports from the AI setup agent.

Results can be saved locally to the filesystem or uploaded to the Tusk Drift Cloud backend. The behavior is determined by the command being run (e.g., tusk run, tusk init, tusk exp init) and the flags provided (e.g., --save-results, --cloud, --ci).

Test Run Results

The primary form of results is the outcome of test runs executed via the tusk run command.

Local Saving

Test results can be saved locally to files. This is controlled by flags in the tusk run command.

Flag	Description	Default
--save-results	A boolean flag that enables the saving of replay results to a file.	false
--results-dir	Specifies the directory where results will be saved. If not provided, it defaults to the path in the config file or .tusk/results.	.tusk/results

When --save-results is enabled, the Executor is configured with the output directory.

Sources: cmd/run.go:121-122, cmd/run.go:193-201

Cloud Uploading

In cloud-integrated modes (--cloud --ci or --cloud --validate-suite-if-default-branch), test results are uploaded to the Tusk Drift Cloud backend on a per-test basis.

This process involves:

1. Creating a "Drift Run" on the Tusk Cloud backend, which generates a driftRunID.
2. Setting an OnTestCompleted callback on the test Executor.
3. This callback is triggered after each test finishes, and it calls runner.UploadSingleTestResult to send the individual result to the cloud.
4. After all tests are complete, a final status update is sent to the backend to finalize the run.

Sources: cmd/run.go:171-189, cmd/run.go:242-273

The following diagram illustrates the sequence for uploading a single test result in CI mode.

Sources: cmd/run.go:171-189, cmd/run.go:242-273, cmd/run.go:498-509

Configuration Saving

The interactive wizards (tusk init and tusk init-cloud) save user-provided settings to configuration files.

Local Onboarding (tusk init)

The tusk init command uses an onboarding wizard to generate the primary .tusk/config.yaml file.

The saveConfig function is responsible for this:

1. It creates the .tusk directory if it doesn't exist.
2. It marshals the configuration struct into YAML format.
3. It formats the YAML to include blank lines between top-level sections for readability.
4. It prepends a header comment with a link to the configuration documentation.
5. It writes the final content to .tusk/config.yaml.
6. If using Docker Compose, it also attempts to create a docker-compose.tusk-override.yml file.

Sources: internal/tui/onboard/config.go:132-167

Cloud Onboarding (tusk init-cloud)

The tusk init-cloud command updates the existing .tusk/config.yaml with cloud-specific settings, such as the service ID and recording parameters. It is designed to modify the file while preserving existing content, comments, and structure.

The process is as follows:

1. The YAML file is parsed into an abstract syntax tree (AST) of yaml.Node.
2. The updateYAMLNode function traverses this tree to find and update specific fields (e.g., recording.sampling_rate) or create them if they don't exist.
3. The modified AST is then encoded back into a YAML string, preserving comments and spacing.
4. Blank lines are added between top-level sections to maintain readability.

This careful update process is demonstrated in the unit tests for the saving logic.

Sources: internal/tui/onboard-cloud/save_test.go:17-23, internal/tui/onboard-cloud/save_test.go:101-107, [internal/tui/onboard-cloud/steps.go:413-416]

The following diagram shows the YAML update flow.

Sources: internal/tui/onboard-cloud/save_test.go

AI Agent Artifacts (tusk exp init)

The experimental AI agent (tusk exp init) saves its own set of artifacts to track progress and provide a final summary.

Agent Progress

To allow the agent to resume after an interruption, it continuously saves its state to .tusk/PROGRESS.md.

• Saving: The saveProgress function is called after each phase transition or before exiting on interruption. It writes a detailed markdown file containing discovered project information, setup progress checklist, completed phases, and any errors or warnings.
• Resuming: On startup, the agent reads this file to restore its state and skip already completed phases.
• Deletion: The PROGRESS.md file is automatically deleted by deleteProgress upon successful completion of the entire setup process.

Sources: internal/agent/agent.go:1115-1258, internal/agent/agent.go:1261-1266

Final Reports

At the end of the setup process (for both local and cloud setup), the AI agent is instructed to generate and save a final report.

• Local Setup: The phase_summary.md prompt instructs the agent to generate a report and save it to .tusk/SETUP_REPORT.md using the write_file tool.
• Cloud Setup: Similarly, the phase_cloud_summary.md prompt directs the agent to save a cloud-specific report to .tusk/CLOUD_SETUP_REPORT.md.

This ensures that even after the temporary PROGRESS.md file is deleted, a persistent summary of the agent's work remains.

Sources: internal/agent/prompts/phase_summary.md:14-16, internal/agent/prompts/phase_cloud_summary.md:29-31