fix(v3): run root Taskfile for build/package/dev so customisations are honoured (#5615)

[leaanthony]

Description

Fixes #5615.

wails3 build / dev / package were silently bypassing the project's root Taskfile.yml. In task_wrapper.go, the CLI rewrote the verb to a platform-namespaced task (build → linux:build) unconditionally — because the target OS defaults to runtime.GOOS, which is always a valid platform. So every invocation jumped straight into the platform namespace, and any customisation a user made to the root build/package/run task never ran. Editing the root Taskfile (the file users are meant to customise) appeared to have no effect, which is what triggered the report.

Fix

The root tasks now dispatch to the platform Taskfile via a {{.GOOS}} variable instead of the {{OS}} built-in:

vars:
  GOOS: '{{.GOOS | default OS}}'   # host OS by default, overridden by `wails3 build GOOS=...`
tasks:
  build:
    cmds:
      - task: "{{.GOOS}}:build"

The CLI now runs the root task (build/package) and passes GOOS/ARCH through as variables, rather than targeting the platform-prefixed task directly. This means root-Taskfile customisations are honoured for both native and cross-compilation builds:

• wails3 build → root build → {{.GOOS}} = host → darwin:build (root task runs)
• wails3 build GOOS=windows → root build (with GOOS=windows) → windows:build (root task still runs)

sign, which has no root task, still targets the platform-specific task directly. The experimental wake runner keeps using the concrete platform task name (unchanged).

Verification

• New/updated unit tests in task_wrapper_test.go (host & cross dispatch, sign, GOOS arg/env precedence — host-relative so they pass on any platform) and a template regression test TestCommonTaskfileDispatchesViaGOOS.
• End-to-end on macOS and Linux with a fresh wails3 init -t react: a marker added to the root build task now runs for both wails3 build and wails3 build GOOS=windows, then dispatches to the correct platform task. (Confirmed via the literal wails3 dev path on Linux too.)

⚠️ Backward compatibility

Projects generated before this change have a root Taskfile that still uses {{OS}}:build and no GOOS var. With the new CLI:

• Native builds work as before.
• Cross-compilation (wails3 build GOOS=…) on such projects will build for the host OS, because the old root task ignores the passed GOOS var. Those projects need to update their root Taskfile.yml to use {{.GOOS}} (or be re-initialised) to cross-compile. Since this targets v3 alpha, calling this out for awareness.

Note on the original report

I could not reproduce the reporter's literal symptom — a fresh wails3 init -t react + wails3 dev built successfully on both Linux and macOS. This PR fixes the root-Taskfile bypass identified during triage (the behaviour @leaanthony pointed to). If @its-ernest hit an actual compile/task error, that may be separate — worth confirming with their exact task output before closing.

Summary by CodeRabbit

• Bug Fixes
  • Fixed an issue where custom build, package, and run task configurations defined in the root Taskfile were not being executed. Build, package, and dev commands now properly dispatch to root-level Taskfile tasks, ensuring your custom configurations are respected in both native and cross-compilation scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f4ab821e-e10f-4957-b4cd-3eb7024c9237

📥 Commits

Reviewing files that changed from the base of the PR and between a076f8a and 9a88d97.

📒 Files selected for processing (5)

• v3/UNRELEASED_CHANGELOG.md
• v3/internal/commands/task_wrapper.go
• v3/internal/commands/task_wrapper_test.go
• v3/internal/templates/_common/Taskfile.tmpl.yml
• v3/internal/templates/taskfile_template_test.go

---

Walkthrough

The PR adds a GOOS variable to the common Taskfile template and routes build, package, and run tasks through it instead of the hardcoded {{OS}} form. The CLI task wrapper gains a rootDispatchTasks map so that build and package verbs dispatch via root tasks (honoring user customizations) while always forwarding GOOS and ARCH as Taskfile variables.

Changes

Root Taskfile GOOS dispatch

Layer / File(s)	Summary
Common Taskfile GOOS variable and dispatch routing v3/internal/templates/_common/Taskfile.tmpl.yml	Adds a GOOS variable defaulting to OS and updates build, package, and run task cmds to dispatch via {{.GOOS}} instead of the built-in {{OS}} form.
CLI task wrapper rootDispatchTasks and wrapTask refactor v3/internal/commands/task_wrapper.go	Introduces rootDispatchTasks map for build/package verbs; refactors wrapTask to always append GOOS/ARCH to Taskfile variable args, compute platformTaskName unconditionally, and route the Wake path through platformTaskName while conditionally setting taskName to root verb or platform-prefixed form.
Updated wrapper and template tests v3/internal/commands/task_wrapper_test.go, v3/internal/templates/taskfile_template_test.go	Adds foreignOS derivation, rewrites TestWrapTask table for root build/package dispatch with GOOS/ARCH args, updates all command-level test assertions, and adds TestCommonTaskfileDispatchesViaGOOS to validate template GOOS routing.
Changelog entry v3/UNRELEASED_CHANGELOG.md	Adds a Fixed entry describing root task dispatch via GOOS variable, referencing #5615.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• wailsapp/wails#4488: Modifies the same task_wrapper.go file to forward CLI variables into task execution, directly overlapping with this PR's wrapper refactor.
• wailsapp/wails#5126: Modifies the common Taskfile template's platform-specific dispatch for build/package/run, the same routing logic changed here.
• wailsapp/wails#3748: Refactors task routing in _common/Taskfile.tmpl.yml, the same file updated to use the new GOOS variable routing.

Suggested labels

cli, v3-alpha

🐇 A task once ran straight to the OS's door,
Now it asks "What GOOS?" before it sets off.
Root tasks are honored, no bypassing more,
Cross-compile with ease — no more custom code scoffed!
The rabbit hops freely, on any platform it likes. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: running root Taskfile for build/package commands to honor customizations, directly addressing the core issue.
Description check	✅ Passed	The description comprehensively covers the issue, root cause, fix implementation, verification steps, and backward compatibility considerations, exceeding template requirements.
Linked Issues check	✅ Passed	The PR fully addresses issue #5615 by fixing the broken Taskfile behavior, enabling successful builds and customization of root tasks for both native and cross-compilation scenarios.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the root Taskfile dispatch mechanism: task wrapper logic, template updates, and corresponding comprehensive unit tests.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/v3-taskfile-root-dispatch-5615

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain modules listed in go.work or their selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR adjusts the v3 CLI’s task dispatch so wails3 build and wails3 package execute the project’s root Taskfile.yml tasks (allowing user customisations there to run), while still dispatching into platform-specific Taskfiles via a new GOOS variable in the scaffolded Taskfile template.

Changes:

• Update the root Taskfile template to dispatch build/package/run via {{.GOOS}} (with a default to host OS).
• Change the CLI task wrapper to run root tasks for build/package and pass GOOS/ARCH through as Task variables.
• Add/adjust unit tests to cover host vs cross dispatch, and template regression coverage.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
v3/UNRELEASED_CHANGELOG.md	Adds a changelog entry describing the task dispatch fix (currently mentions dev, which appears inaccurate).
v3/internal/templates/taskfile_template_test.go	Adds a regression test ensuring the Taskfile template dispatches via {{.GOOS}}.
v3/internal/templates/_common/Taskfile.tmpl.yml	Introduces a GOOS var and updates root tasks to dispatch to {{.GOOS}}:<verb>.
v3/internal/commands/task_wrapper.go	Routes build/package through root tasks and forwards GOOS/ARCH as variables.
v3/internal/commands/task_wrapper_test.go	Updates/extends tests to validate new wrapper behavior and variable passthrough.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.