feat(v3/cli): add wails3 migrate to assist v2 project migration

[taliesin-ai]

Summary

Adds a wails3 migrate command that assists migrating a Wails v2 project to v3, plus a new docs page with a side-by-side v2 vs v3 comparison. Requested as part of making the v2 to v3 path easier: convert declarative to programmatic, bindings to services, config to config.

The tool is an assistant, not a transpiler: it automates the mechanical parts and produces a precise report for everything that needs a human.

What it does

wails3 migrate -d path/to/v2/project

Refuses politely unless the directory has a wails.json and a go.mod requiring github.com/wailsapp/wails/v2. Non-destructive by design: it never modifies or deletes existing files.

Automated

• Config to config: renders the root Taskfile.yml (same template wails3 init uses, package manager detected from frontend:install) and generates the build/ assets, copying only files the project does not already have (existing v2 icons, Info.plist, installer files are preserved and listed in the report). Product info from wails.json (info.*) is written into build/config.yml.
• Declarative to programmatic: parses main.go with go/ast, extracts the wails.Run(&options.App{...}) literal and generates main_v3.go.example (never touches main.go): application.New(application.Options{...}) + app.Window.NewWithOptions(...) with Title/Width/Height/Min-Max/Frameless/BackgroundColour/StartState/SingleInstance mapped, the //go:embed directive and constructor statements (app := NewApp()) carried over, and asset serving converted to application.AssetFileServerFS. Output is gofmt-formatted and parse-checked before it is written.
• Bindings to services: every Bind entry becomes application.NewService(...) in the generated options.

Report-only (MIGRATION_REPORT.md)

• Unmappable wails.json keys, each with guidance on where the setting lives in v3.
• OnStartup/OnDomReady/OnShutdown/OnBeforeClose (also surfaced as TODO(migrate) comments in the generated bootstrap), menus, platform-specific options, non-literal option values.
• Every v2 runtime.* call found in the project, with file:line references, plus a verified v2-to-v3 runtime API mapping table (EventsEmit -> app.Event.Emit, WindowSetTitle -> window.SetTitle, dialogs, clipboard, browser, logging, ...).
• Service conversion checklist (drop stored ctx, ServiceStartup/ServiceShutdown, constructor injection) and frontend changes (wailsjs -> frontend/bindings, @wailsio/runtime).

Docs

• New page: docs/src/content/docs/migration/comparison.mdx (side-by-side concept/API/config tables + wails3 migrate usage), added to the sidebar and cross-linked with the existing step-by-step guide.

Testing

• Unit tests with a realistic v2 fixture project (v3/internal/commands/testdata/migrate/basic): detection/refusal, config mapping, preservation of existing files across repeat runs, generated-code validity (parses, gofmt-clean, all options asserted), report contents. go test ./internal/commands/ ./internal/templates/ ./internal/flags/ passes.
• End-to-end: ran the built CLI against a scaffolded v2 project; the generated main_v3.go.example (with the fixture services adapted to v3 as a user would) compiles to a working binary in a module requiring wails/v3 via a replace directive.

To try it: build the CLI (go build ./cmd/wails3 in v3/), then run wails3 migrate -d <v2 project> and open MIGRATION_REPORT.md.

Notes for review

• writeProjectConfigYML in init.go was refactored (behaviour-preserving) to share the comment-preserving config.yml rewrite with the migrator.
• templates.RootTaskfile is a new small exported helper so the migrator reuses the exact init Taskfile template.
• Menus and exotic options intentionally degrade to report entries rather than risking broken codegen.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 79fd6afc-1bed-4309-b2f8-16559081bc17

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/wails3-migrate

---

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.}