Make the first contact work: usage, and honest sidecar resolution

`devicedeck --help` printed the version and nothing else. That is the
first command anyone types against a tarball, and it told them neither
what the binary does nor that `serve` exists. It now prints usage — on
--help, on no arguments, and on an unknown command, which exits 2 with
the message on stderr.

Testing the first-run paths also turned up a quieter problem: a sidecar
path given explicitly, by flag or environment variable, was treated as a
hint. If it did not exist, discovery carried on and found a different
binary, so a typo ran a build nobody asked for and said nothing. A named
path is now honoured or refused, and the refusal names both the source
and the path.

CI runs build, vet, gofmt and the race suite on macOS, plus the Swift
sidecar build and its tests. It deliberately excludes the device suites:
those need a booted simulator and an emulator, which no hosted runner
has, and pretending otherwise would produce a green tick that means
less than it appears to.

Author: omnarayan

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+# Go build, vet, format and tests. Deliberately not the device suites:
+# those need a booted simulator and an emulator, which no hosted runner
+# has — so this covers what can honestly be checked without hardware,
+# and the device work stays a local gate.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  go:
+    # macOS because the sidecars and the simulator paths are macOS-only,
+    # even though this job does not boot a device.
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Format
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "these files need gofmt:"; echo "$unformatted"; exit 1
+          fi
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test ./... -race -coverprofile=coverage.out
+
+      - name: Coverage
+        run: go tool cover -func=coverage.out | tail -1
+
+  sidecar:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build the Swift sidecars
+        run: make sidecar
+      - name: Sidecar tests
+        run: make sidecar-test

cmd/devicedeck/main.go

@@ -5,6 +5,7 @@ package main
 
 import (
 	"fmt"
+	"io"
 	"os"
 
 	"github.com/devicelab-dev/DeviceDeck/internal/version"
@@ -28,5 +29,45 @@ func main() {
 		}
 		return
 	}
-	fmt.Fprintln(os.Stdout, version.Line())
+	switch arg(1) {
+	case "version", "--version", "-version", "-v":
+		fmt.Fprintln(os.Stdout, version.Line())
+	case "", "help", "--help", "-help", "-h":
+		usage(os.Stdout)
+	default:
+		fmt.Fprintf(os.Stderr, "devicedeck: unknown command %q\n\n", os.Args[1])
+		usage(os.Stderr)
+		os.Exit(2)
+	}
+}
+
+// arg returns os.Args[i], or "" when it was not given, so the dispatch
+// reads the same whether or not a command was typed.
+func arg(i int) string {
+	if len(os.Args) > i {
+		return os.Args[i]
+	}
+	return ""
+}
+
+// usage is what someone sees when they run the binary with no idea what
+// it does — which, for a tool distributed as a tarball, is most first
+// contacts. It names the one command that matters and where to go next.
+func usage(w io.Writer) {
+	fmt.Fprintf(w, `%s
+
+Streams iOS Simulators and Android emulators to a browser, and turns a
+session driven by hand into a replayable test.
+
+Usage:
+  devicedeck serve [flags]    start the server and console
+  devicedeck version          print the version
+  devicedeck help             print this message
+
+Run "devicedeck serve --help" for the server's flags.
+
+Once running, open the console at the address it prints (by default
+http://127.0.0.1:8787) to pick a device. Point your own tests at
+/device/{udid} and drive it with ordinary web selectors.
+`, version.Line())
 }

cmd/devicedeck/serve.go

@@ -118,7 +118,24 @@ func defaultRunnerHome() {
 // Swift build output (developer setup).
 func resolveBinary(name, explicit string) (string, error) {
 	envVar := strings.ToUpper(strings.ReplaceAll(name, "-", "_")) // devicedeck-hid → DEVICEDECK_HID
-	candidates := []string{explicit, os.Getenv(envVar)}
+	// A path given deliberately must be honoured or refused, never
+	// quietly replaced: falling through to a different binary than the
+	// one someone named turns a typo into a mystery, and it would run
+	// the wrong build without ever saying so.
+	for _, named := range []struct{ source, path string }{
+		{"--sidecar/--video-sidecar", explicit},
+		{envVar, os.Getenv(envVar)},
+	} {
+		if named.path == "" {
+			continue
+		}
+		if info, err := os.Stat(named.path); err != nil || info.IsDir() {
+			return "", fmt.Errorf("%s points at %q, which is not an executable file (%s)",
+				named.source, named.path, name)
+		}
+		return named.path, nil
+	}
+	var candidates []string
 	if exe, err := os.Executable(); err == nil {
 		candidates = append(candidates, filepath.Join(filepath.Dir(exe), name))
 	}

cmd/devicedeck/serve_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -90,3 +91,52 @@ func TestDefaultRunnerHome(t *testing.T) {
 		}
 	})
 }
+
+// A path someone named explicitly must be honoured or refused. Falling
+// through to a different binary would run a build they did not ask for
+// and never mention it — a typo becomes a mystery.
+func TestResolveBinaryRefusesBadExplicitPath(t *testing.T) {
+	// A working discovery path exists, so a fallthrough would silently
+	// succeed and hide the mistake.
+	root := t.TempDir()
+	release := filepath.Join(root, "sidecar/.build/release")
+	if err := os.MkdirAll(release, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writeStub(t, release, "devicedeck-hid")
+	t.Chdir(root)
+
+	_, err := resolveBinary("devicedeck-hid", "/nonexistent/hid")
+	if err == nil {
+		t.Fatal("a named path that does not exist must be refused")
+	}
+	if !strings.Contains(err.Error(), "/nonexistent/hid") {
+		t.Errorf("error should name the offending path: %v", err)
+	}
+
+	t.Setenv("DEVICEDECK_HID", "/also/missing")
+	if _, err := resolveBinary("devicedeck-hid", ""); err == nil ||
+		!strings.Contains(err.Error(), "DEVICEDECK_HID") {
+		t.Errorf("a bad env path should be refused and named: %v", err)
+	}
+}
+
+// A directory is not an executable, however real the path is.
+func TestResolveBinaryRefusesDirectory(t *testing.T) {
+	dir := t.TempDir()
+	if _, err := resolveBinary("devicedeck-hid", dir); err == nil {
+		t.Fatal("a directory must not resolve as the sidecar")
+	}
+}
+
+// The usage text is what a first contact sees; it has to name the
+// command that matters and where the console appears.
+func TestUsageNamesTheEssentials(t *testing.T) {
+	var b strings.Builder
+	usage(&b)
+	for _, want := range []string{"devicedeck serve", "127.0.0.1:8787", "/device/", "version"} {
+		if !strings.Contains(b.String(), want) {
+			t.Errorf("usage does not mention %q:\n%s", want, b.String())
+		}
+	}
+}