feat(cli): standardize version conventions (F110)

[pocky]

Summary

• BREAKING: Standardize version CLI conventions across all commands — awf version subcommand is removed in favour of awf --version, the -v shorthand for --verbose is dropped, --version flags on plugin install, workflow install, and upgrade are replaced with inline owner/repo@version syntax and a positional argument respectively
• Replace constraint-based version resolution (>=1.0.0 <2.0.0) with strict exact SemVer only — both bare (1.2.3) and v-prefixed (v1.2.3) are accepted; ranges, latest, and partial versions are rejected before any network call
• Extract a shared exactReleaseTarget type and selectExactRelease function to unify version parsing and release resolution across plugin install, workflow install, and upgrade
• Fix effectiveCLIVersion to treat dirty git-describe builds (v0.8.1-dirty) as dev builds, so pack version constraints behave correctly outside production releases

Changes

Core CLI

• internal/interfaces/cli/root.go: Remove newVersionCommand; wire Cobra's built-in Version field and SetVersionTemplate for awf --version; drop -v shorthand from --verbose
• internal/interfaces/cli/doc.go: Update package-level comment to reflect --version flag instead of newVersionCommand
• internal/interfaces/cli/release_target.go: New file — exactReleaseTarget, parseExactReleaseTarget, parseInstallReleaseTarget, selectExactRelease shared across all install/upgrade paths

Plugin Command

• internal/interfaces/cli/plugin_cmd.go: Remove --version flag and constraint-based selectRelease; parse version from owner/repo@version inline arg via parsePluginInstallSource; delegate release selection to selectExactRelease

Workflow Command

• internal/interfaces/cli/workflow_cmd.go: Remove --version flag and parseOwnerRepoAndVersion; delegate to parseInstallReleaseTarget and selectExactRelease; fix effectiveCLIVersion to cover dirty builds

Upgrade Command

• internal/interfaces/cli/upgrade.go: Replace --version flag with [version] positional argument; remove selectTargetRelease in favour of selectExactRelease; validate exact SemVer before any release lookup

Tests — Unit

• internal/interfaces/cli/release_target_test.go: New file — comprehensive unit tests for parseExactReleaseTarget, parseInstallReleaseTarget, and selectExactRelease
• internal/interfaces/cli/plugin_cmd_unit_test.go: Replace constraint-based test cases with @version syntax tests; verify --version flag is unknown and invalid targets fail before network calls
• internal/interfaces/cli/root_test.go: Replace TestVersionCommand / TestRootCommandHasVersionSubcommand with --version flag assertions; add tests confirming -v is no longer assigned
• internal/interfaces/cli/root_nohints_test.go: Update all test args from version subcommand to --version; remove stale inline comments
• internal/interfaces/cli/upgrade_test.go: Replace selectTargetRelease tests with selectExactRelease; add tests for positional arg, removed flag rejection, and pre-lookup validation
• internal/interfaces/cli/workflow_cmd_test.go: Update callers to owner/repo@version inline syntax; fix effectiveCLIVersion dirty-build expectation

Tests — Integration

• tests/integration/cli/release_target_syntax_test.go: New file — end-to-end integration tests validating @version syntax parsing for both plugin and workflow install commands
• tests/integration/cli/plugin_install_test.go: Update TestPluginInstall_VersionConstraints to TestPluginInstall_Version using @version inline syntax; add readPluginSourceData helper
• tests/integration/cli/workflow_install_test.go: Migrate all version tests from --version flag to @version inline arg
• tests/integration/features/cli_test.go: Update feature-level CLI tests for new conventions

Documentation

• README.md: Update command table and add breaking-change callout
• docs/getting-started/installation.md: Change awf version to awf --version; fix AWF_VERSION env var placement in install script example
• docs/getting-started/quickstart.md: Remove -v shorthand from --verbose flag table
• docs/user-guide/commands.md: Update all command signatures, flag tables, and examples; replace awf version section with awf --version
• docs/user-guide/plugins.md: Update plugin install argument format and examples to @version syntax; remove --version flag row
• docs/user-guide/tracing.md: Replace -v with --verbose in example
• docs/user-guide/upgrade.md: Replace --version <tag> with positional [version] argument
• docs/user-guide/workflow-packs.md: Update workflow install examples to @version syntax; remove constraint examples

Repo

• .gitignore: Track Tower workspace config (!.tower/config.toml) while ignoring generated index and extension binaries

Test plan

• awf --version prints awf version X.Y.Z, commit: …, built: … on three lines; awf version returns unknown command "version"
• awf plugin install owner/[email protected] resolves and installs exactly v1.2.3; --version 1.2.3 is rejected as unknown flag
• awf workflow install owner/[email protected] resolves and installs exactly v1.2.0; --version >=1.0.0 is rejected as unknown flag; range syntax owner/repo@>=1.0.0 fails before any network call
• awf upgrade v0.5.0 installs v0.5.0; awf upgrade --version v0.5.0 fails as unknown flag; awf upgrade latest fails before any release lookup with format error
• Unit and integration test suites pass: go test ./internal/interfaces/cli/... ./tests/integration/cli/...

Closes #378

---

Generated with awf commit workflow