fix: per-command :HELP filtering, sort by name, clarify README

- :HELP <command> now shows help for a single command (case-insensitive)
- Unknown command names fall through to the full help listing
- Sort help entries by help text (stable: all start with command name)
- README: clarify :perftrace requires -p flag for timing data
- Add tests for per-command help, case-insensitive lookup, and
  unknown command fallback

Author: dlevy-msft-sql

README.md

@@ -164,7 +164,7 @@ client_interface_name go-mssqldb
 program_name          sqlcmd
 ```
 
-- `:perftrace` redirects performance statistics output to a file, stderr, or stdout. Use in conjunction with `-p` flag.
+- `:perftrace` redirects performance statistics output to a file, stderr, or stdout. Requires the `-p` flag (print statistics) to produce timing data.
 
 ```
 1> :perftrace c:/logs/perf.txt

pkg/sqlcmd/commands.go

@@ -618,16 +618,33 @@ func xmlCommand(s *Sqlcmd, args []string, line uint) error {
 }
 
 func helpCommand(s *Sqlcmd, args []string, line uint) error {
-	entries := make([]string, 0, len(s.Cmd))
+	// :HELP <command> shows help for a single command
+	if len(args) > 0 && strings.TrimSpace(args[0]) != "" {
+		key := strings.ToUpper(strings.TrimSpace(args[0]))
+		if cmd, ok := s.Cmd[key]; ok && cmd.help != "" {
+			_, err := s.GetOutput().Write([]byte(cmd.help))
+			return err
+		}
+		// Unknown command name -- fall through to full listing
+	}
+
+	// Collect and sort by command name for stable output order
+	type entry struct {
+		name string
+		help string
+	}
+	entries := make([]entry, 0, len(s.Cmd))
 	for _, cmd := range s.Cmd {
 		if cmd.help != "" {
-			entries = append(entries, cmd.help)
+			entries = append(entries, entry{cmd.name, cmd.help})
 		}
 	}
-	sort.Strings(entries)
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].help < entries[j].help
+	})
 	var b strings.Builder
-	for _, entry := range entries {
-		b.WriteString(entry)
+	for _, e := range entries {
+		b.WriteString(e.help)
 	}
 	_, err := s.GetOutput().Write([]byte(b.String()))
 	return err

pkg/sqlcmd/commands_test.go

@@ -56,6 +56,8 @@ func TestCommandParsing(t *testing.T) {
 		{`RESET`, "RESET", []string{""}},
 		{`:HELP`, "HELP", []string{""}},
 		{`:help`, "HELP", []string{""}},
+		{`:HELP CONNECT`, "HELP", []string{"CONNECT"}},
+		{`:help exit`, "HELP", []string{"exit"}},
 		{`:PERFTRACE stderr`, "PERFTRACE", []string{"stderr"}},
 		{`:perftrace c:/logs/perf.txt`, "PERFTRACE", []string{"c:/logs/perf.txt"}},
 	}
@@ -480,6 +482,34 @@ func TestHelpCommand(t *testing.T) {
 				"help output missing text for command %s", name)
 		}
 	}
+
+	// :HELP <command> should show only that command's help
+	buf.buf.Reset()
+	err = helpCommand(s, []string{"CONNECT"}, 1)
+	assert.NoError(t, err, "helpCommand CONNECT should not error")
+	output = buf.buf.String()
+	assert.Contains(t, output, ":connect", "HELP CONNECT should show connect help")
+	assert.NotContains(t, output, ":exit", "HELP CONNECT should not show exit help")
+
+	// Case-insensitive lookup
+	buf.buf.Reset()
+	err = helpCommand(s, []string{"exit"}, 1)
+	assert.NoError(t, err, "helpCommand exit should not error")
+	output = buf.buf.String()
+	assert.Contains(t, output, ":exit", "HELP exit should show exit help")
+	assert.NotContains(t, output, ":connect", "HELP exit should not show connect help")
+
+	// Unknown command falls through to full listing
+	buf.buf.Reset()
+	err = helpCommand(s, []string{"NOSUCHCMD"}, 1)
+	assert.NoError(t, err, "helpCommand unknown should not error")
+	output = buf.buf.String()
+	for name, cmd := range s.Cmd {
+		if cmd.help != "" {
+			assert.Contains(t, output, cmd.help,
+				"unknown command should show full help, missing %s", name)
+		}
+	}
 }
 
 func TestAllCommandsHaveHelp(t *testing.T) {