polish: tighten CLI UX and strengthen CI

Author: corruptmem

.github/workflows/ci.yml

@@ -27,7 +27,21 @@ jobs:
         shell: bash
         run: |
           test -z "$(gofmt -l .)"
+      - name: go vet
+        run: go vet ./...
       - name: go test
         run: go test ./...
       - name: go build
         run: go build ./cmd/msx
+
+  race:
+    name: race (ubuntu-latest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+          cache: true
+      - name: go test -race
+        run: go test -race ./...

README.md

@@ -133,6 +133,7 @@ msx mail --profile personal --top 10
 msx mail --profile personal --sender noreply@example.com --since 2026-03-01T00:00:00Z
 msx mail --profile personal --folder inbox --unread --top 25
 msx mail --profile personal --query invoice --top 20
+msx mail --profile personal --subject invoice --top 50
 ```
 
 ### Calendar lookup
@@ -148,6 +149,7 @@ msx agenda --profile personal --query dentist
 msx files --profile personal --top 20
 msx files --profile personal --path Documents
 msx files --profile personal --query passport --top 20
+msx files --profile personal --path Documents --kind folders
 ```
 
 ### Contacts
@@ -188,7 +190,8 @@ Current choices made for agent use:
 - profile selection is explicit and cheap
 - read-only operations for safe automation
 - globals can appear before or after subcommands
-- basic input validation for common footguns (`--top > 0`, valid RFC3339 timestamps, `--end` after `--start`)
+- basic input validation for common footguns (`--top > 0`, valid RFC3339 timestamps, `--end` after `--start`, constrained enums like `--kind`)
+- client-side narrowing where it improves ergonomics without hiding Graph data (`mail --subject`, `files --kind`)
 
 ## Safety
 
@@ -211,15 +214,17 @@ Covered areas now include:
 - token JSON parsing and refresh-token preservation
 - store durability/serialization behavior
 - forced refresh persistence
-- Graph `401` retry behavior
-- CLI global flag parsing and event filtering helpers
+- Graph `401` retry behavior and search headers
+- CLI global flag parsing, help-path behavior, and filtering helpers for mail/events/files
 
 ## CI
 
 GitHub Actions now runs on push and pull request:
 - `gofmt -l .` to catch formatting drift
+- `go vet ./...`
 - `go test ./...`
 - `go build ./cmd/msx`
+- `go test -race ./...` on Ubuntu for the concurrency-sensitive auth/store path
 - matrix coverage on Ubuntu, macOS, and Windows
 
 ## Verified non-destructive flows

cmd/msx/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
 	"flag"
 	"fmt"
 	"os"
@@ -19,23 +20,28 @@ type globalFlags struct {
 	format  string
 }
 
+var errHelpShown = errors.New("help shown")
+
 const usageText = `usage: msx [--profile name] [--format text|json] <command> [flags]
 
 commands:
-  login       Start device-code login and save tokens locally
-  import-op   Import an existing Microsoft account from 1Password
-  profiles    List configured profiles
-  whoami      Show the current Graph account
-  mail        List mail with optional filters
-  agenda      List calendar events in a time range
-  files       List or search OneDrive files
-  contacts    List or search contacts
-  sites       Search SharePoint / org sites
-  help        Show this message
+  login         Start device-code login and save tokens locally
+  import-op     Import an existing Microsoft account from 1Password
+  profiles      List configured profiles
+  whoami        Show the current Graph account
+  mail          List mail with optional filters
+  agenda        List calendar events in a time range
+  files         List or search OneDrive files
+  contacts      List or search contacts
+  sites         Search SharePoint / org sites
+  help          Show this message
 `
 
 func main() {
 	if err := run(os.Args[1:]); err != nil {
+		if errors.Is(err, errHelpShown) {
+			os.Exit(0)
+		}
 		fmt.Fprintln(os.Stderr, "error:", err)
 		os.Exit(1)
 	}
@@ -47,10 +53,10 @@ func run(args []string) error {
 		return err
 	}
 	if len(rest) == 0 {
-		return usage()
+		return showUsage(true, "")
 	}
 	if rest[0] == "help" || rest[0] == "--help" || rest[0] == "-h" {
-		return usage()
+		return showUsage(false, "")
 	}
 
 	s, err := store.Open("")
@@ -81,7 +87,7 @@ func run(args []string) error {
 	case "sites":
 		return cmdSites(s, g, rest)
 	default:
-		return usage()
+		return showUsage(true, fmt.Sprintf("unknown command %q", cmd))
 	}
 }
 
@@ -117,8 +123,19 @@ func parseGlobals(args []string) (globalFlags, []string, error) {
 	return g, out, nil
 }
 
-func usage() error {
-	return fmt.Errorf(usageText)
+func showUsage(asError bool, prefix string) error {
+	if asError {
+		if prefix != "" {
+			return fmt.Errorf("%s\n\n%s", prefix, usageText)
+		}
+		return fmt.Errorf(usageText)
+	}
+	if prefix != "" {
+		fmt.Fprintln(os.Stdout, prefix)
+		fmt.Fprintln(os.Stdout)
+	}
+	_, _ = fmt.Fprint(os.Stdout, usageText)
+	return errHelpShown
 }
 
 func cmdLogin(s *store.Store, g globalFlags, args []string) error {
@@ -200,6 +217,7 @@ func cmdMail(s *store.Store, g globalFlags, args []string) error {
 	top := fs.Int("top", 10, "maximum number of messages")
 	sender := fs.String("sender", "", "exact sender email filter")
 	query := fs.String("query", "", "Graph search expression text")
+	subject := fs.String("subject", "", "case-insensitive subject substring filter applied client-side")
 	since := fs.String("since", "", "received since RFC3339 timestamp")
 	folder := fs.String("folder", "inbox", "well-known mail folder or folder id")
 	unread := fs.Bool("unread", false, "only include unread messages")
@@ -236,6 +254,9 @@ func cmdMail(s *store.Store, g globalFlags, args []string) error {
 	if err != nil {
 		return err
 	}
+	if *subject != "" {
+		data["value"] = filterMailBySubject(data["value"], *subject)
+	}
 	return emit(g, data)
 }
 
@@ -283,12 +304,16 @@ func cmdFiles(s *store.Store, g globalFlags, args []string) error {
 	top := fs.Int("top", 25, "maximum number of items")
 	path := fs.String("path", "", "folder path to list")
 	query := fs.String("query", "", "search query")
+	kind := fs.String("kind", "all", "all|files|folders")
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
 	if err := requirePositive("--top", *top); err != nil {
 		return err
 	}
+	if *kind != "all" && *kind != "files" && *kind != "folders" {
+		return fmt.Errorf("--kind must be all, files, or folders")
+	}
 	endpoint := "/me/drive/root/children"
 	params := map[string]string{"$top": fmt.Sprint(*top), "$select": "id,name,webUrl,file,folder,size,lastModifiedDateTime,parentReference"}
 	if *query != "" {
@@ -300,6 +325,9 @@ func cmdFiles(s *store.Store, g globalFlags, args []string) error {
 	if err != nil {
 		return err
 	}
+	if *kind != "all" {
+		data["value"] = filterDriveItems(data["value"], *kind)
+	}
 	return emit(g, data)
 }
 
@@ -375,20 +403,48 @@ func escapePathSegment(v string) string {
 	return strings.ReplaceAll(v, "'", "''")
 }
 
+func filterMailBySubject(v any, q string) []map[string]any {
+	return filterRows(v, func(row map[string]any) bool {
+		subject, _ := row["subject"].(string)
+		return strings.Contains(strings.ToLower(subject), strings.ToLower(q))
+	})
+}
+
 func filterEvents(v any, q string) []map[string]any {
+	q = strings.ToLower(q)
+	return filterRows(v, func(row map[string]any) bool {
+		blob, _ := json.Marshal(row)
+		return strings.Contains(strings.ToLower(string(blob)), q)
+	})
+}
+
+func filterDriveItems(v any, kind string) []map[string]any {
+	return filterRows(v, func(row map[string]any) bool {
+		_, hasFile := row["file"]
+		_, hasFolder := row["folder"]
+		switch kind {
+		case "files":
+			return hasFile && !hasFolder
+		case "folders":
+			return hasFolder
+		default:
+			return true
+		}
+	})
+}
+
+func filterRows(v any, keep func(map[string]any) bool) []map[string]any {
 	items, ok := v.([]any)
 	if !ok {
 		return nil
 	}
-	q = strings.ToLower(q)
 	out := []map[string]any{}
 	for _, item := range items {
 		row, ok := item.(map[string]any)
 		if !ok {
 			continue
 		}
-		blob, _ := json.Marshal(row)
-		if strings.Contains(strings.ToLower(string(blob)), q) {
+		if keep(row) {
 			out = append(out, row)
 		}
 	}

cmd/msx/main_test.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
 	"reflect"
 	"testing"
 )
@@ -25,6 +26,12 @@ func TestParseGlobalsRejectsInvalidFormat(t *testing.T) {
 	}
 }
 
+func TestShowUsageHelpPath(t *testing.T) {
+	if err := showUsage(false, ""); !errors.Is(err, errHelpShown) {
+		t.Fatalf("expected errHelpShown, got %v", err)
+	}
+}
+
 func TestFilterEventsMatchesNestedFieldsCaseInsensitively(t *testing.T) {
 	in := []any{
 		map[string]any{"subject": "Dentist", "location": map[string]any{"displayName": "Main Street"}},
@@ -40,6 +47,32 @@ func TestFilterEventsMatchesNestedFieldsCaseInsensitively(t *testing.T) {
 	}
 }
 
+func TestFilterMailBySubject(t *testing.T) {
+	in := []any{
+		map[string]any{"subject": "Monthly Invoice"},
+		map[string]any{"subject": "Dinner"},
+	}
+	out := filterMailBySubject(in, "invoice")
+	if len(out) != 1 || out[0]["subject"] != "Monthly Invoice" {
+		t.Fatalf("unexpected filtered mail: %#v", out)
+	}
+}
+
+func TestFilterDriveItems(t *testing.T) {
+	in := []any{
+		map[string]any{"name": "notes.txt", "file": map[string]any{}},
+		map[string]any{"name": "docs", "folder": map[string]any{}},
+	}
+	files := filterDriveItems(in, "files")
+	folders := filterDriveItems(in, "folders")
+	if len(files) != 1 || files[0]["name"] != "notes.txt" {
+		t.Fatalf("unexpected files filter result: %#v", files)
+	}
+	if len(folders) != 1 || folders[0]["name"] != "docs" {
+		t.Fatalf("unexpected folders filter result: %#v", folders)
+	}
+}
+
 func TestSplitCSVTrimsAndDropsEmptyValues(t *testing.T) {
 	got := splitCSV(" User.Read, , Mail.Read ,")
 	want := []string{"User.Read", "Mail.Read"}