[Experiment] Focused Wails v3 build system to reduce build complexity

[!IMPORTANT] This is an experiment, not an approved roadmap item or a commitment to replace the current build system. The design, syntax, and implementation may change or be discarded. Existing Taskfile-based projects remain supported while this is evaluated.

Problem

Community feedback has highlighted that Wails' build experience can be difficult to understand and customise. Configuration and behaviour are spread across config.yml, root and platform Taskfiles, generated assets, CLI flags, and external tools. Projects needing only light customisation must still understand a general-purpose task pipeline.

The recurring pain points are:

• no single place to understand effective build configuration;
• uncertainty about which files are Wails-owned, generated, or safe to edit;
• simple target, packaging, or frontend changes requiring Taskfile knowledge;
• stock, lightly customised, and heavily customised Taskfiles being difficult to distinguish and migrate safely;
• platform-specific behaviour and defaults being hard to inspect before a build.

Experimental hypothesis and current prototype

Explore a focused, Wails-owned build engine for the common pipeline, driven by one declarative wails.yaml manifest. The prototype began in HCL and later pivoted to a strict YAML subset after the complete configuration surface became clear. The branch name retains its historical HCL wording.

The current prototype includes:

• central project, frontend, target, package, platform, signing, association, protocol, and profile configuration;
• profiles that select targets and formats for the normal wails3 build command;
• user-owned source assets/templates, with disposable generated state under .wails/;
• a deterministic build plan with incremental caching, artifact receipts, and inspectable --plan / --plan --json output;
• lifecycle hooks calling external scripts with a protected JSON context file;
• reviewed Taskfile migration that reports unsupported customisation instead of silently dropping it;
• wails3 config check, wails3 eject, generated JSON Schema, and improved source-line diagnostics;
• an experimental CLI gate, WAILS_EXP_USE_WAKE, plus an active v3 wails.yaml manifest as the per-project opt-in;
• compatibility handling for the older setup-wizard info: metadata file that also used the wails.yaml name.

Prototype PR: #6131 (draft). Prototype branch: https://github.com/wailsapp/wails/tree/codex/hcl-build-system

Compatibility boundary

• Existing projects do not change simply because the prototype exists. Taskfiles remain the supported path unless the experimental CLI is enabled and a v3 build manifest is activated.
• Once a v3 build manifest is active, Wails build/dev commands use its pipeline rather than mixing in Taskfile tasks.
• Migration must recognise stock Taskfiles, preserve supported customisation, and report manual work.
• A customised Taskfile that cannot be migrated completely remains active while a reviewable wails.migrated.yaml is produced.
• The experiment must not silently overwrite the legacy info:-style wails.yaml or other user-owned files.

What we need to learn

• Does one focused configuration file materially reduce build-system cognitive load?
• Is strict YAML readable and predictable for the customisation Wails projects need?
• Do profiles make multi-target and multi-format builds easier to express and invoke?
• Are compiled defaults plus wails3 eject a good balance between concise configuration and inspectability?
• Can stock and lightly customised Taskfiles be migrated safely enough to make adoption practical?
• Which real customisations cannot be represented through typed settings and script hooks?
• Is performance and cache behaviour at least as good as the existing path across Linux, Windows, macOS, iOS, and Android?

Experiment success criteria

• A default project and common light customisations are understandable from a short wails.yaml without reading pipeline internals.
• Existing Taskfile projects remain unchanged until explicit opt-in.
• Migration never silently drops custom behaviour and produces actionable diagnostics for unsupported cases.
• Development, production, package, signing, wizard, and mobile-device flows pass native platform testing.
• Warm builds are deterministic, verify artifact receipts, and perform no unnecessary work.
• User feedback shows that the reduction in complexity outweighs the new configuration format.

Linux automated verification has passed for the YAML conversion. Manual setup-wizard and native macOS/Windows acceptance after that conversion are still required. This issue tracks evaluation of the experiment; a decision to adopt it should be separate and based on real-project and multi-platform evidence.