docs: improve install version constraint guidance (#332)

Closes #331.

## Summary
- make `dbc install -h` explicitly mention version constraints and link
to the detailed docs
- add a regression test for the install help output
- add a visible version-constraint callout on the docs home page
- make the CLI reference point directly to the version-constraints guide

## Validation
- `go test ./...`
- `go run ./cmd/dbc install -h`

---------

Co-authored-by: Bryce Mecum <petridish@gmail.com>

Author: dataders

cmd/dbc/install.go

@@ -23,11 +23,11 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/Masterminds/semver/v3"
 	"charm.land/bubbles/v2/progress"
 	"charm.land/bubbles/v2/spinner"
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+	"github.com/Masterminds/semver/v3"
 	"github.com/columnar-tech/dbc"
 	"github.com/columnar-tech/dbc/config"
 )
@@ -50,13 +50,19 @@ func parseDriverConstraint(driver string) (string, *semver.Constraints, error) {
 
 type InstallCmd struct {
 	// URI    url.URL `arg:"-u" placeholder:"URL" help:"Base URL for fetching drivers"`
-	Driver   string             `arg:"positional,required" help:"Driver to install"`
+	Driver   string             `arg:"positional,required" help:"Driver to install, optionally with a version constraint (for example: mysql, mysql=0.1.0, mysql>=1,<2)"`
 	Level    config.ConfigLevel `arg:"-l" help:"Config level to install to (user, system)"`
 	Json     bool               `arg:"--json" help:"Output JSON instead of plaintext"`
 	NoVerify bool               `arg:"--no-verify" help:"Allow installation of drivers without a signature file"`
 	Pre      bool               `arg:"--pre" help:"Allow implicit installation of pre-release versions"`
 }
 
+func (InstallCmd) Description() string {
+	return "Install a driver.\n\n" +
+		"`DRIVER` may include a version constraint, for example `dbc install mysql`, `dbc install \"mysql=0.1.0\"`, or `dbc install \"mysql>=1,<2\"`.\n" +
+		"See https://docs.columnar.tech/dbc/guides/installing/#version-constraints for more on version constraint syntax."
+}
+
 func (c InstallCmd) GetModelCustom(baseModel baseModel) tea.Model {
 	s := spinner.New()
 	s.Spinner = spinner.MiniDot

cmd/dbc/main.go

@@ -20,9 +20,9 @@ import (
 	"os"
 	"slices"
 
-	"github.com/alexflint/go-arg"
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+	"github.com/alexflint/go-arg"
 	"github.com/columnar-tech/dbc"
 	"github.com/columnar-tech/dbc/auth"
 	"github.com/columnar-tech/dbc/cmd/dbc/completions"
@@ -177,7 +177,7 @@ func main() {
 		args cmds
 	)
 
-	p, err := arg.NewParser(arg.Config{Program: "dbc", EnvPrefix: "DBC_"}, &args)
+	p, err := newParser(&args)
 	if err != nil {
 		fmt.Println("Error creating argument parser:", err)
 		os.Exit(1)
@@ -260,3 +260,7 @@ func main() {
 		os.Exit(h.Status())
 	}
 }
+
+func newParser(args *cmds) (*arg.Parser, error) {
+	return arg.NewParser(arg.Config{Program: "dbc", EnvPrefix: "DBC_"}, args)
+}

cmd/dbc/main_test.go

@@ -23,10 +23,29 @@ import (
 	"time"
 
 	tea "charm.land/bubbletea/v2"
+	"github.com/alexflint/go-arg"
 	"github.com/columnar-tech/dbc"
 	"github.com/stretchr/testify/require"
 )
 
+func renderSubcommandHelp(t *testing.T, argv ...string) string {
+	t.Helper()
+
+	var args cmds
+	p, err := newParser(&args)
+	require.NoError(t, err)
+
+	err = p.Parse(argv)
+	require.ErrorIs(t, err, arg.ErrHelp)
+
+	var out bytes.Buffer
+	if d, ok := p.Subcommand().(arg.Described); ok {
+		fmt.Fprintln(&out, d.Description())
+	}
+	p.WriteHelpForSubcommand(&out, p.SubcommandNames()...)
+	return out.String()
+}
+
 func TestFormatErr(t *testing.T) {
 	tests := []struct {
 		name          string
@@ -106,3 +125,12 @@ func TestCmdStatus(t *testing.T) {
 		})
 	}
 }
+
+func TestInstallHelpMentionsVersionConstraints(t *testing.T) {
+	out := renderSubcommandHelp(t, "install", "-h")
+
+	require.Contains(t, out, "Driver to install, optionally with a version constraint")
+	require.Contains(t, out, `dbc install "mysql=0.1.0"`)
+	require.Contains(t, out, `dbc install "mysql>=1,<2"`)
+	require.Contains(t, out, "https://docs.columnar.tech/dbc/guides/installing/#version-constraints")
+}

docs/reference/cli.md

@@ -99,7 +99,9 @@ $ dbc install [OPTIONS] <DRIVER>
 
 `DRIVER`
 
-:   Name of the driver to install. Can be a short driver name or a driver name with version requirement. Examples: `bigquery`, `bigquery=1.0.0`, `bigquery>1`. Can also be a path to a local driver archive, see [Installing Drivers: From Local Archive](../guides/installing.md#from-local-archive) for more information.
+:   Name of the driver to install. This can be a plain driver name like `bigquery`, a driver name with a version constraint like `bigquery=1.0.0` or `bigquery>=1,<2`, or a path to a local driver archive.
+
+    For the full version-constraint syntax and more examples, see [Installing Drivers: Version Constraints](../guides/installing.md#version-constraints). For local archives, see [Installing Drivers: From Local Archive](../guides/installing.md#from-local-archive).
 
 <h3>Options</h3>