cricinfo-cli-go 0.1.0

package/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+Guidance for coding agents working in `cricinfo-cli`.
+
+## Purpose
+
+This repository ships the `cricinfo` Go CLI through npm. Treat the npm package, the Go binary, and the release workflow as one contract.
+
+## Architecture
+
+- `cmd/cricinfo/main.go`: process entrypoint and exit handling.
+- `internal/app/app.go`: command parsing and top-level dispatch.
+- `internal/cli/`: command families, help text, and flag wiring.
+- `internal/cricinfo/`: transport, normalization, rendering, and analysis logic.
+- `bin/cricinfo.js`: npm shim that launches the installed native binary.
+- `scripts/postinstall.js`: downloads the tagged binary or falls back to `go build`.
+- `Makefile`: local build, test, smoke, and release helpers.
+- `.github/workflows/release.yml`: tag-driven build and publish pipeline.
+
+## Local Commands
+
+Prefer the checked-in `Makefile` targets:
+
+- `make fmt`
+- `make test`
+- `make vet`
+- `make lint`
+- `make check`
+- `make build`
+- `make build-all`
+- `make npm-smoke`
+- `make acceptance`
+- `make test-live`
+- `make test-live-smoke`
+- `make fixtures-refresh`
+- `make install-local`
+
+Direct commands that are also safe to use:
+
+- `go test ./...`
+- `go vet ./...`
+- `npm run test`
+- `npm run lint`
+
+When running Node or npm commands through background helpers on this machine, prefer `zsh -lc '<command>'` so the login shell initializes the expected `PATH`.
+
+## Release Contract
+
+Releases trigger on `v*` tags and expect:
+
+- `NPM_TOKEN` to be configured in GitHub Actions.
+- `package.json` to keep the published npm package name and `config.cliBinaryName` aligned with the CLI install contract.
+- release assets to follow `<cli>_<goos>_<goarch>[.exe]`.
+- `scripts/postinstall.js` to be able to fetch the matching GitHub release asset or build from source.
+
+If you touch release artifacts or the binary name, update `package.json`, `bin/cricinfo.js`, `scripts/postinstall.js`, `Makefile`, and `.github/workflows/release.yml` in the same change.
+
+## Guardrails
+
+- Prefer additive changes and keep the existing CLI naming contract intact.
+- Do not rewrite user changes in unrelated files.
+- Keep help output concrete and command-local so `<command> --help` explains the next step.
+- If you add dependencies, commit the updated `go.sum` and verify the release workflow still builds cleanly.

package/CONTRIBUTORS.md

@@ -0,0 +1,75 @@
+# CONTRIBUTORS.md
+
+Maintainer notes for this template repository.
+
+## Prerequisites
+
+- Go `1.26+`
+- Node `18+`
+- npm account with publish rights for the package name in `package.json`
+- GitHub repo admin access
+
+## Local development
+
+```bash
+make check
+make build
+./dist/cricinfo --help
+```
+
+Install command locally:
+
+```bash
+make install-local
+cricinfo --help
+```
+
+## Release process
+
+1. Ensure `main` is green:
+
+```bash
+make check
+```
+
+2. Prepare release tag:
+
+```bash
+make release-tag VERSION=0.1.0
+```
+
+3. GitHub Actions `release` workflow runs automatically:
+- quality checks
+- cross-platform binary build
+- GitHub release publish
+- npm publish
+
+## Required GitHub secret
+
+- `NPM_TOKEN`: npm automation token with publish rights for your package.
+
+Set via GitHub CLI:
+
+```bash
+gh secret set NPM_TOKEN --repo amxv/cricinfo-cli
+```
+
+## npm token setup
+
+Create token at npm:
+
+- Profile -> Access Tokens -> Create New Token
+- Use an automation/granular token scoped to required package/org
+
+Validate auth locally:
+
+```bash
+npm whoami
+```
+
+## Notes on package naming
+
+Before first publish, set a package name you control in `package.json`.
+
+- Example unscoped: `"name": "your-cli-name"`
+- Example scoped: `"name": "@your-scope/your-cli-name"`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amxv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,131 @@
+SHELL := /bin/bash
+NODE_SHELL ?= /bin/zsh -lc
+
+GO ?= go
+GOFMT ?= gofmt
+BIN_NAME ?= cricinfo
+CMD_PATH ?= ./cmd/$(BIN_NAME)
+DIST_DIR ?= dist
+BIN_PATH ?= $(DIST_DIR)/$(BIN_NAME)
+VERSION ?= $(shell node -p "require('./package.json').version" 2>/dev/null)
+LDFLAGS ?= -s -w -X github.com/amxv/cricinfo-cli/internal/buildinfo.Version=$(if $(VERSION),$(VERSION),dev)
+ACCEPTANCE_LEAGUE ?= 11132
+ACCEPTANCE_MATCH ?= 1527689
+ACCEPTANCE_PLAYER ?= Virat Kohli
+ACCEPTANCE_TEAM ?= rr
+
+.PHONY: help fmt test test-live test-live-smoke fixtures-refresh vet lint check build build-all npm-smoke acceptance install-local clean release-tag
+
+help:
+	@echo "cricinfo command runner"
+	@echo ""
+	@echo "Targets:"
+	@echo "  make fmt          - format Go files"
+	@echo "  make test         - run go test ./..."
+	@echo "  make test-live    - run opt-in live Cricinfo matrix tests"
+	@echo "  make test-live-smoke - run opt-in live smoke coverage tests"
+	@echo "  make fixtures-refresh - refresh curated live fixtures into testdata"
+	@echo "  make vet          - run go vet ./..."
+	@echo "  make lint         - run Node script checks"
+	@echo "  make check        - fmt + test + vet + lint"
+	@echo "  make build        - build local binary to dist/cricinfo"
+	@echo "  make build-all    - build release binaries for 5 target platforms"
+	@echo "  make npm-smoke    - pack + install npm tarball in a temp prefix and run cricinfo --help"
+	@echo "  make acceptance   - run live end-to-end CLI acceptance checks over key command families"
+	@echo "  make install-local- install CLI to ~/.local/bin/cricinfo"
+	@echo "  make clean        - remove dist artifacts"
+	@echo "  make release-tag  - create and push git tag (requires VERSION=x.y.z)"
+
+fmt:
+	@$(GOFMT) -w $$(find . -type f -name '*.go' -not -path './dist/*')
+
+test:
+	@$(GO) test ./...
+
+test-live:
+	@CRICINFO_LIVE_MATRIX=1 $(GO) test ./internal/cricinfo -run 'TestLive' -count=1
+
+test-live-smoke:
+	@CRICINFO_LIVE_SMOKE=1 $(GO) test ./internal/cricinfo -run 'TestLiveSmoke' -count=1
+
+fixtures-refresh:
+	@$(GO) run ./internal/cricinfo/cmd/fixture-refresh --write
+
+vet:
+	@$(GO) vet ./...
+
+lint:
+	@$(NODE_SHELL) 'npm run lint'
+
+check: fmt test vet lint
+
+build:
+	@mkdir -p $(DIST_DIR)
+	@$(GO) build -trimpath -ldflags="$(LDFLAGS)" -o $(BIN_PATH) $(CMD_PATH)
+
+build-all:
+	@mkdir -p $(DIST_DIR)
+	@for target in "darwin amd64" "darwin arm64" "linux amd64" "linux arm64" "windows amd64"; do \
+		set -- $$target; \
+		GOOS=$$1; GOARCH=$$2; \
+		EXT=""; \
+		if [ "$$GOOS" = "windows" ]; then EXT=".exe"; fi; \
+		echo "Building $(BIN_NAME) for $$GOOS/$$GOARCH"; \
+		CGO_ENABLED=0 GOOS=$$GOOS GOARCH=$$GOARCH $(GO) build -trimpath -ldflags="$(LDFLAGS)" -o "$(DIST_DIR)/$(BIN_NAME)_$$GOOS_$$GOARCH$$EXT" $(CMD_PATH); \
+	done
+
+npm-smoke:
+	@set -euo pipefail; \
+	PACK_NAME="$$( $(NODE_SHELL) "npm pack --silent" )"; \
+	TMP_DIR="tmp/npm-smoke.$$"; \
+	/bin/rm -rf "$$TMP_DIR"; \
+	mkdir -p "$$TMP_DIR"; \
+	trap '/bin/rm -rf "$$TMP_DIR" "$$PACK_NAME"' EXIT; \
+	$(NODE_SHELL) "npm install --prefix '$$TMP_DIR/prefix' './$$PACK_NAME' >/dev/null"; \
+	$(NODE_SHELL) "'$$TMP_DIR/prefix/node_modules/.bin/$(BIN_NAME)' --help >/dev/null"; \
+	echo "npm smoke ok: $$PACK_NAME"
+
+acceptance: build
+	@set -euo pipefail; \
+	$(MAKE) npm-smoke; \
+	BIN="$(BIN_PATH)"; \
+	"$$BIN" --help >/dev/null; \
+	"$$BIN" matches --help >/dev/null; \
+	"$$BIN" players --help >/dev/null; \
+	"$$BIN" teams --help >/dev/null; \
+	"$$BIN" leagues --help >/dev/null; \
+	"$$BIN" analysis --help >/dev/null; \
+	"$$BIN" matches list --limit 5 --format json >/dev/null; \
+	"$$BIN" matches live --limit 5 --format json >/dev/null; \
+	"$$BIN" matches show "$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" matches scorecard "$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" matches innings "$(ACCEPTANCE_MATCH)" --team "$(ACCEPTANCE_TEAM)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" players search "$(ACCEPTANCE_PLAYER)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" players profile "$(ACCEPTANCE_PLAYER)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" players match-stats "$(ACCEPTANCE_PLAYER)" --match "$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" players deliveries "$(ACCEPTANCE_PLAYER)" --match "$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" teams show "$(ACCEPTANCE_TEAM)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" teams roster "$(ACCEPTANCE_TEAM)" --match "$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" teams leaders "$(ACCEPTANCE_TEAM)" --match "$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" leagues show "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" leagues seasons "$(ACCEPTANCE_LEAGUE)" --format json >/dev/null; \
+	"$$BIN" seasons show "$(ACCEPTANCE_LEAGUE)" --season 2025 --format json >/dev/null; \
+	"$$BIN" analysis bowling --metric economy --scope "match:$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --top 10 --format json >/dev/null; \
+	"$$BIN" analysis dismissals --league "$(ACCEPTANCE_LEAGUE)" --seasons 2025 --top 5 --format json >/dev/null; \
+	"$$BIN" analysis partnerships --scope "match:$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --top 5 --format json >/dev/null; \
+	! "$$BIN" analysis bowling --metric economy --scope "match:$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --top 10 --format text | grep -E '(https?://|/v2/sports/cricket)'; \
+	! "$$BIN" teams leaders "$(ACCEPTANCE_TEAM)" --match "$(ACCEPTANCE_MATCH)" --league "$(ACCEPTANCE_LEAGUE)" --format text | grep -E '(https?://|/v2/sports/cricket)'; \
+	echo "acceptance ok: live command traversal and json rendering"
+
+install-local: build
+	@mkdir -p $$HOME/.local/bin
+	@install -m 755 $(BIN_PATH) $$HOME/.local/bin/$(BIN_NAME)
+	@echo "Installed $(BIN_NAME) to $$HOME/.local/bin/$(BIN_NAME)"
+
+clean:
+	@rm -rf $(DIST_DIR)
+
+release-tag:
+	@test -n "$(VERSION)" || (echo "Usage: make release-tag VERSION=x.y.z" && exit 1)
+	@git tag "v$(VERSION)"
+	@git push origin "v$(VERSION)"

package/README.md

@@ -0,0 +1,130 @@
+# cricinfo
+
+`cricinfo` is a Go-powered Cricinfo CLI published on npm as `cricinfo-cli-go`. It is designed for both human workflows and agent workflows, with readable text output by default and structured JSON or JSONL for automation.
+
+## Install
+
+Install the latest published package globally:
+
+```bash
+npm i -g cricinfo-cli-go
+cricinfo --version
+cricinfo --help
+```
+
+If you are working from source, the repo also ships local build targets:
+
+```bash
+make build
+make install-local
+```
+
+The npm package installs a platform-specific binary when available and falls back to a local Go build during `postinstall` if needed.
+
+## Usage
+
+Start at the root help, then drill into the family you need:
+
+```bash
+cricinfo --help
+cricinfo matches --help
+cricinfo players --help
+cricinfo teams --help
+cricinfo leagues --help
+cricinfo analysis --help
+```
+
+Common command families include:
+
+```text
+matches
+players
+teams
+leagues
+seasons
+standings
+competitions
+search
+analysis
+```
+
+Typical workflows:
+
+```bash
+# Discover current or recent match data
+cricinfo matches list
+cricinfo matches live
+cricinfo matches show 1529474
+cricinfo matches scorecard 1529474
+
+# Explore players and teams
+cricinfo players profile 1361257
+cricinfo players match-stats 1361257 --match 1529474
+cricinfo teams roster 789643 --match 1529474
+
+# Traverse leagues and seasons
+cricinfo leagues show 19138
+cricinfo leagues seasons 19138
+cricinfo seasons show 19138 --season 2025
+
+# Derived analysis
+cricinfo analysis dismissals --league 19138 --seasons 2025
+cricinfo analysis bowling --metric economy --scope match:1529474
+cricinfo analysis batting --metric strike-rate --scope season:2025 --league 19138
+cricinfo analysis partnerships --scope season:2025 --league 19138
+```
+
+## Output Modes
+
+Use `--format text|json|jsonl` to match the consumer:
+
+```bash
+cricinfo matches show 1529474 --format json
+cricinfo matches list --format jsonl
+cricinfo players profile 1361257 --format json
+```
+
+Helpful global flags:
+
+- `--verbose` for richer summaries
+- `--all-fields` to retain extended entity data in structured output
+- `--format jsonl` for list-oriented machine processing
+
+## Development
+
+Use the checked-in `Makefile` targets whenever possible:
+
+```bash
+make fmt
+make test
+make vet
+make lint
+make check
+make build
+make build-all
+make npm-smoke
+make acceptance
+make test-live
+make test-live-smoke
+make fixtures-refresh
+```
+
+`make check` runs format, tests, vet, and lint. `make acceptance` performs a live end-to-end traversal across install/help, matches, players, teams, leagues, analysis, and JSON rendering.
+
+## Release
+
+Releases are tag-driven. Push a `vX.Y.Z` tag and GitHub Actions will:
+
+1. run Go and Node quality checks
+2. build release binaries for the supported platforms
+3. publish the GitHub release assets
+4. publish the npm package at the tag version
+
+Release artifact conventions:
+
+- binary name: `cricinfo`
+- GitHub release assets: `cricinfo_<goos>_<goarch>[.exe]`
+- npm shim: `bin/cricinfo.js`
+- install fallback: `scripts/postinstall.js`
+
+If you change the CLI name or release artifact layout, update `package.json`, `bin/cricinfo.js`, `scripts/postinstall.js`, `Makefile`, and `.github/workflows/release.yml` together.

package/bin/cricinfo.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pkg = require("../package.json");
+const cliName = resolveCLIName(pkg);
+const executableName = process.platform === "win32" ? `${cliName}.exe` : `${cliName}-bin`;
+const executablePath = path.join(__dirname, executableName);
+
+if (!fs.existsSync(executablePath)) {
+  console.error(`${cliName} binary is not installed. Re-run: npm rebuild -g ${pkg.name}`);
+  process.exit(1);
+}
+
+const child = spawnSync(executablePath, process.argv.slice(2), { stdio: "inherit" });
+
+if (child.error) {
+  console.error(child.error.message);
+  process.exit(1);
+}
+
+if (child.signal) {
+  process.kill(process.pid, child.signal);
+}
+
+process.exit(child.status ?? 1);
+
+function resolveCLIName(packageJSON) {
+  const configured = `${packageJSON?.config?.cliBinaryName || ""}`.trim();
+  if (configured) {
+    return configured;
+  }
+
+  if (packageJSON?.bin && typeof packageJSON.bin === "object") {
+    const names = Object.keys(packageJSON.bin);
+    if (names.length > 0 && `${names[0]}`.trim()) {
+      return `${names[0]}`.trim();
+    }
+  }
+
+  return "cricinfo";
+}

package/cmd/cricinfo/main.go

@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/amxv/cricinfo-cli/internal/app"
+)
+
+func main() {
+	if err := app.Run(os.Args[1:], os.Stdout, os.Stderr); err != nil {
+		fmt.Fprintln(os.Stderr, "Error:", err)
+		os.Exit(1)
+	}
+}

package/go.mod

@@ -0,0 +1,10 @@
+module github.com/amxv/cricinfo-cli
+
+go 1.26
+
+require github.com/spf13/cobra v1.8.1
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+)

package/go.sum

@@ -0,0 +1,10 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=
+github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package/internal/app/app.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"io"
+
+	"github.com/amxv/cricinfo-cli/internal/cli"
+)
+
+func Run(args []string, stdout, stderr io.Writer) error {
+	return cli.Run(args, stdout, stderr)
+}

package/internal/app/app_test.go

@@ -0,0 +1,122 @@
+package app
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestRunRootHelp(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"--help"}, &out, &errBuf)
+	if err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+
+	help := out.String()
+	if !strings.Contains(help, "Usage:") {
+		t.Fatalf("expected help output, got: %q", out.String())
+	}
+	if !strings.Contains(help, "--version") {
+		t.Fatalf("expected --version in help output, got: %q", out.String())
+	}
+	if !strings.Contains(help, "matches") || !strings.Contains(help, "players") {
+		t.Fatalf("expected placeholder groups in root help, got: %q", help)
+	}
+}
+
+func TestRunVersion(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"--version"}, &out, &errBuf)
+	if err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+
+	if !strings.Contains(out.String(), "cricinfo ") {
+		t.Fatalf("unexpected version output: %q", out.String())
+	}
+}
+
+func TestRunMatchesGroupHelp(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"matches", "--help"}, &out, &errBuf)
+	if err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+
+	help := out.String()
+	if !strings.Contains(help, "Next steps:") {
+		t.Fatalf("expected next-step guidance in help output, got: %q", help)
+	}
+	if !strings.Contains(help, "cricinfo matches live") || !strings.Contains(help, "cricinfo matches show <match>") {
+		t.Fatalf("expected matches drill-down commands in help output, got: %q", help)
+	}
+}
+
+func TestRunUnknownCommand(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"unknown"}, &out, &errBuf)
+	if err == nil {
+		t.Fatal("expected error for unknown command")
+	}
+	if !strings.Contains(err.Error(), `unknown command "unknown"`) {
+		t.Fatalf("expected unknown command error, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "run `cricinfo --help`") {
+		t.Fatalf("expected unknown command help hint, got: %v", err)
+	}
+}
+
+func TestRunGlobalFlagsPropagateToSubcommands(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"players", "--format", "json", "--verbose", "--all-fields", "--help"}, &out, &errBuf)
+	if err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+
+	help := out.String()
+	if !strings.Contains(help, "--format") || !strings.Contains(help, "--verbose") || !strings.Contains(help, "--all-fields") {
+		t.Fatalf("expected global flags in subcommand help output, got: %q", help)
+	}
+}
+
+func TestRunRejectsUnknownFormat(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"players", "--format", "yaml"}, &out, &errBuf)
+	if err == nil {
+		t.Fatal("expected error for invalid --format value")
+	}
+	if !strings.Contains(err.Error(), `invalid value "yaml" for --format`) {
+		t.Fatalf("unexpected invalid format error: %v", err)
+	}
+}
+
+func TestRunSearchGroupHelp(t *testing.T) {
+	var out bytes.Buffer
+	var errBuf bytes.Buffer
+
+	err := Run([]string{"search", "--help"}, &out, &errBuf)
+	if err != nil {
+		t.Fatalf("Run returned error: %v", err)
+	}
+
+	help := out.String()
+	if !strings.Contains(help, "players") || !strings.Contains(help, "teams") || !strings.Contains(help, "leagues") || !strings.Contains(help, "matches") {
+		t.Fatalf("expected entity search subcommands in help output, got: %q", help)
+	}
+	if !strings.Contains(help, "--league") || !strings.Contains(help, "--match") {
+		t.Fatalf("expected search context flags in help output, got: %q", help)
+	}
+}

package/internal/buildinfo/buildinfo.go

@@ -0,0 +1,16 @@
+package buildinfo
+
+import "strings"
+
+const defaultVersion = "dev"
+
+// Version is overridden at build time via linker flags.
+var Version = defaultVersion
+
+func CurrentVersion() string {
+	trimmed := strings.TrimSpace(Version)
+	if trimmed == "" {
+		return defaultVersion
+	}
+	return trimmed
+}