Debug Tuist Project Issue

Quick Start

1. Ask the user to describe the issue and the project setup (targets, dependencies, configurations, platform).
2. Confirm the issue exists with the latest release by running mise exec tuist@latest -- tuist generate against a reproduction project.
3. If confirmed, clone the Tuist repository and build from source to test against main.
4. Triage: fix the bug and open a PR, advise on misconfiguration, or recommend the user files an issue with a reproduction.

Step 1: Gather Context

Ask the user for:

• What command they ran (e.g. tuist generate)
• The error message or unexpected behavior
• When the issue happens: generation time, compile time, or runtime (app launch or later)
• Their project structure: targets, platforms, dependencies (SwiftPM, XCFrameworks, local packages)
• Their Project.swift and Tuist.swift content (or relevant excerpts)
• Their Tuist version (tuist version)

The answer to "when" determines the verification strategy:

• Generation time: the issue might be a Tuist bug or a project misconfiguration. Reproduce with tuist generate.
• Compile time: the generated project has incorrect build settings, missing sources, or wrong dependency wiring. Reproduce with xcodebuild build after generation.
• Runtime: the app builds but crashes or misbehaves on launch or during use. Reproduce by installing and launching on a simulator.

Step 2: Reproduce with the latest release

Before investigating the source code, confirm the issue is not already fixed in the latest release.

Set up a temporary reproduction project

REPRO_DIR=$(mktemp -d)
cd "$REPRO_DIR"

Create minimal Tuist.swift, Project.swift, and source files that reproduce the user's scenario. Keep it as small as possible while still triggering the issue.

Run generation with the latest Tuist release

mise exec tuist@latest -- tuist generate --no-open --path "$REPRO_DIR"