Spotlight Testing
Relevant source files
The following files were used as context for generating this wiki page:
Spotlight Testing is a specialized runtime mode within Linux Archductor designed for projects that must execute from the repository root rather than isolated worktrees. It enables the application to checkpoint, apply, sync, switch, and restore tracked workspace patches against a clean repository root while maintaining strict safety checks against "dirty" roots (roots with unstaged edits outside the active patch).
Sources: README.md:144-147, progress.md:139-142
Architecture and Components
The Spotlight Testing system operates by managing workspace patches as discrete slices of state that can be applied to the primary repository. It is integrated into the core runtime model and exposed through the GTK interface via the Runtime panel.
State Management
Spotlight status is tracked via active sessions that record the started timestamp and the path to the active patch file. The system continuously monitors for root conflicts—files in the repository root that have been modified but are not part of the current Spotlight patch.
Sources: crates/gtk-app/src/workspace_command_center.rs:1364-1377
Key Functions and Logic
- Spotlight Start: Initializes a Spotlight session for a specific workspace, tracking its patch against the root.
- Spotlight Sync: Synchronizes the current state of the root back into the workspace patch.
- Spotlight Repair: A recovery action that discards edits in the root that exist outside the active patch and reapplies the patch to ensure consistency.
- Spotlight Stop: Terminates the active session and cleans up the root state.
Sources: crates/gtk-app/src/workspace_command_center.rs:1052-1145
Operational Flow
The following diagram illustrates the lifecycle of a Spotlight session and how it interacts with the repository root.
The flow ensures that any operation (Sync, Stop, or Switch) is blocked if the repository root contains changes not accounted for by the active Spotlight patch, preventing accidental data loss or corruption of the base repository.
Sources: crates/gtk-app/src/workspace_command_center.rs:1052-1145, crates/gtk-app/src/workspace_command_center.rs:1416-1433
Configuration
Spotlight Testing is configured at the repository level through .archductor/settings.toml. It is disabled by default and must be explicitly enabled.
Configuration Parameters
| Option | Type | Default | Description |
|---|---|---|---|
spotlight_testing | Boolean | false | Enables spotlight state tracking for root-relative runtime flows. |
Sources: crates/core/src/settings.rs:434-436, README.md:154-156
Runtime Error Handling
The system employs strict validation to ensure the repository root remains in a known state. If a "dirty root" is detected, specific feedback is provided to the user, identifying the conflicting paths.
// Logic for detecting dirty root errors
fn is_spotlight_dirty_root_error(err: &anyhow::Error) -> bool {
err.to_string()
.contains("repository root has changes outside the active Spotlight patch")
}
// Logic for extracting conflicting paths for user feedback
fn spotlight_dirty_root_paths(err: &anyhow::Error) -> Option<Vec<String>> {
let detail = spotlight_dirty_root_detail(err)?;
let paths = detail
.split(',')
.map(str::trim)
.filter(|path| !path.is_empty())
.map(ToOwned::to_owned)
.collect::<Vec<_>>();
(!paths.is_empty()).then_some(paths)
}
Sources: crates/gtk-app/src/workspace_command_center.rs:1416-1442
UI Integration
In the GTK application, the Spotlight controls are located in the Runtime panel of the Workspace Command Center. The UI provides real-time status updates, including the time since the session started and the path to the active patch.
UI Action Feedback
| Action | Success Message | Failure/Block Message |
|---|---|---|
| Spotlight On | "Spotlight active for {workspace_name}" | "Spotlight failed: {error}" |
| Sync | "Spotlight synced for {workspace_name}" | "Spotlight sync blocked: repository root has extra edits..." |
| Repair | "Spotlight root repaired for {workspace_name}" | "Spotlight repair failed: {error}" |
| Spotlight Off | "Spotlight stopped for {workspace_name}" | "Spotlight stop failed: {error}" |
Sources: crates/gtk-app/src/workspace_command_center.rs:1052-1145, crates/gtk-app/src/workspace_command_center.rs:1416-1433
Conclusion
Spotlight Testing provides a bridge for legacy or highly coupled projects that cannot leverage isolated worktrees. By enforcing a strict patch-and-repair cycle on the repository root, it allows users to utilize Archductor's agent workflows while maintaining the integrity of their primary checkout.