Show file argument in plt help and resolve relative paths under bazel run

Add an Examples section and a descriptive Use string so 'vbs plt --help'
makes clear each subcommand takes a playlist file. Resolve relative input
paths against BUILD_WORKING_DIRECTORY so 'bazel run' works from the
directory the user invoked it in, not the runfiles tree.

Author: statik

cmd/plt.go

@@ -19,6 +19,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"text/tabwriter"
 
 	"github.com/muesli/coral"
@@ -28,23 +29,27 @@ import (
 var pltPrintJSON bool
 
 var pltCmd = &coral.Command{
-	Use:   "plt",
+	Use:   "plt <command> <playlist-file>",
 	Short: "Work with purple playlists.",
 	Long: `Parse, build, and prepare media for purple playlist exports from the
-source app for use in live meetings.`,
+source app for use in live meetings. Each subcommand takes the path to a
+playlist export file.`,
+	Example: `  vbs plt print meeting.playlist
+  vbs plt build meeting.playlist`,
 }
 
 var pltPrintCmd = &coral.Command{
-	Use:   "print <playlist>",
+	Use:   "print <playlist-file>",
 	Short: "Parse and pretty-print a purple playlist.",
 	Long: `Parse a purple playlist export and print its cues. Works entirely
 offline; no media is downloaded.`,
-	Run:  runPltPrint,
-	Args: coral.ExactArgs(1),
+	Example: "  vbs plt print meeting.playlist",
+	Run:     runPltPrint,
+	Args:    coral.ExactArgs(1),
 }
 
-func runPltPrint(cmd *coral.Command, args []string) {
-	path := args[0]
+func runPltPrint(_ *coral.Command, args []string) {
+	path := resolveInputPath(args[0])
 
 	arc, err := sniffPlaylist(path)
 	if err != nil {
@@ -74,6 +79,20 @@ func runPltPrint(cmd *coral.Command, args []string) {
 	}
 }
 
+// resolveInputPath makes a user-supplied path usable regardless of how the
+// binary was launched. Relative paths are resolved against the directory the
+// command was invoked from; under `bazel run` that is reported via
+// BUILD_WORKING_DIRECTORY, since the process itself starts in the runfiles tree.
+func resolveInputPath(p string) string {
+	if p == "" || filepath.IsAbs(p) {
+		return p
+	}
+	if wd := os.Getenv("BUILD_WORKING_DIRECTORY"); wd != "" {
+		return filepath.Join(wd, p)
+	}
+	return p
+}
+
 // printView is the offline summary rendered by plt print, shared by the text
 // and JSON outputs so both show the same data.
 type printView struct {

cmd/plt_print_test.go

@@ -17,10 +17,38 @@ package cmd
 import (
 	"encoding/json"
 	"math"
+	"path/filepath"
 	"strings"
 	"testing"
 )
 
+func TestResolveInputPath(t *testing.T) {
+	abs := filepath.Join(t.TempDir(), "meeting.playlist")
+
+	t.Run("absolute path is unchanged", func(t *testing.T) {
+		t.Setenv("BUILD_WORKING_DIRECTORY", "/some/where")
+		if got := resolveInputPath(abs); got != abs {
+			t.Errorf("resolveInputPath(%q) = %q, want unchanged", abs, got)
+		}
+	})
+
+	t.Run("relative path joins BUILD_WORKING_DIRECTORY", func(t *testing.T) {
+		t.Setenv("BUILD_WORKING_DIRECTORY", "/launch/dir")
+		got := resolveInputPath("../export/meeting.playlist")
+		want := filepath.Join("/launch/dir", "../export/meeting.playlist")
+		if got != want {
+			t.Errorf("resolveInputPath = %q, want %q", got, want)
+		}
+	})
+
+	t.Run("relative path unchanged when env unset", func(t *testing.T) {
+		t.Setenv("BUILD_WORKING_DIRECTORY", "")
+		if got := resolveInputPath("rel/meeting.playlist"); got != "rel/meeting.playlist" {
+			t.Errorf("resolveInputPath = %q, want unchanged relative path", got)
+		}
+	})
+}
+
 func TestDescribeSource(t *testing.T) {
 	cases := []struct {
 		name string