feat(projectdriver): dispatch class projects through verified drivers

[joeykchen]

Summary

Supersedes goplus/xgo#2847, which GitHub closed when its fork head branch was renamed.

This PR implements generic XGo Project Driver v1 dispatch for xgo run, xgo build, and xgo install. XGo discovers a framework-declared driver from the application's effective Go graph and delegates through the driver-neutral contract in goplus/mod#165.

XGo owns discovery, identity validation, process supervision, and output publication. It contains no SPX, Godot, Engine, PCK, or resource-format special cases.

Dispatch and protocol

• Dispatch driver-backed class projects before GenGo for directory, single-file, and package targets.
• Resolve class metadata and driver source from one effective module/workspace graph while honoring GOWORK, -mod, -modfile, and supported graph flags.
• Use Project.Driver, driverprotocol, the xgo-driver-v1 preamble, DriverPackage, and DriverOrigin throughout cmd/internal/projectdriver.
• Preserve application argv boundaries, standard streams, exit status, cancellation, and platform signal semantics.
• Use ErrNotHandled as the only result that permits ordinary-project fallback; every error after a driver match is terminal.
• Keep the driver protocol floor independent from the declaring module's general xgo requirement and enforce the higher effective minimum.

Trust and execution boundaries

• Preserve selected-module provenance separately from replacement source identity and revalidate declaration and driver origins.
• Validate driver package shape and containment, protocol version, recursion, host-only GOOS/GOARCH, pack metadata, and argv/environment budgets.
• Reject unsupported target forms, vendor-backed driver provenance, unsafe overlays, and unsupported build flags explicitly after a driver match.
• Supervise driver process trees on Unix and Windows.
• Publish build/install executables transactionally through private staging, executable validation, and atomic replacement while preserving an existing target on failure.
• Resolve install output from effective GOBIN, falling back to bin under the first GOPATH entry.
• Allow XGO_DRIVER=off to disable project-driver dispatch.

Compatibility

Ordinary projects continue through the existing GenGo implementation. Existing public tool.RunDir, tool.BuildDir, and tool.InstallDir behavior is unchanged; Project Driver dispatch is currently a CLI capability.

Driver v1 is host-only. Multi-file targets, recursive patterns, pkg@version, cross-compilation, and unsupported graph/build modes fail explicitly once a driver-backed target is identified.

Verification

A local go.work containing the Mod, XGo, and SPX checkouts was used until the companion Mod APIs are released.

go test -race ./cmd/internal/projectdriver
go test ./cmd/internal/run ./cmd/internal/build ./cmd/internal/install
go vet ./cmd/internal/projectdriver ./cmd/internal/run ./cmd/internal/build ./cmd/internal/install

# Full suite: test cl outside the coordinated workspace.
go list ./... | rg -v '^github.com/goplus/xgo/cl$' | xargs go test
GOWORK=off go test ./cl
go vet ./...

Host XGo and CGO_ENABLED=0 Linux/Windows amd64 builds also pass.

Dependency and release order

This PR depends on goplus/mod#165. Mod must merge and release first, then this branch must update its github.com/goplus/mod requirement before XGo is released; the current v0.21.2 requirement does not contain driverprotocol.

Part of goplus/spx#1741.