refactor: code organization cleanup (#35)

* chore: fix gitignore + decisions doc after web->inspect-ui rename

Update web/ references to inspect-ui/ in .gitignore and Makefile. Add
decisions.md tracking architectural decisions from code-org discussion.

* refactor: rename pkg/spec-api to pkg/spec

Aligns the directory name with the npm package name @sanderling/spec.
Updates Makefile, package.json directory field, and resolveSpecAPIPath.

* refactor(verifier): split bindings.go into types.go + bindings.go

Move shared public types (Action, ActionKind, LogEntry, Exception) to
types.go. bindings.go retains internal JS runtime wiring only.

* refactor(inspect): split runs.go into runs.go, runs_cache.go, runs_decode.go

runs.go: types (RunSummary, StepSummary, RunDetail, Run) and Scan.
runs_cache.go: Cache type, Open/Step/Detail methods, parseRun, scanSteps.
runs_decode.go: readMeta, tallyTrace, decodeStepSummary, validRunID.

* refactor: move android_env.go to internal/android/

Extracts Android device/AVD/adb logic into internal/android package.
Exports EnsureDevice, AdbReverse, AdbReverseRemove, EnvWithAndroidPlatformTools, AdbBinary.
Moves tests to internal/android/android_test.go. cmd/sanderling becomes a thin caller.

* refactor: extract test pipeline to internal/testrun/

runTestPipeline logic moves to testrun.Execute. buildDriver, resolveSpecAPIPath,
pickFreePort, and the progress logger move to internal/testrun/. cmd/sanderling/test_run.go
becomes a thin adapter. Tests follow their code.

* ci: update workflow paths after pkg/spec-api -> pkg/spec rename

internal/testrun/driver.go

@@ -0,0 +1,72 @@
+package testrun
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"strconv"
+
+	"github.com/priyanshujain/sanderling/internal/android"
+	"github.com/priyanshujain/sanderling/internal/driver"
+	"github.com/priyanshujain/sanderling/internal/driver/chrome"
+	driverSidecar "github.com/priyanshujain/sanderling/internal/driver/sidecar"
+	"github.com/priyanshujain/sanderling/internal/sidecar"
+)
+
+// buildDriver creates the appropriate DeviceDriver for the platform and returns
+// a cleanup function. For web, ChromeDriver is used directly; for android/ios
+// the JVM sidecar is extracted, spawned, and dialed.
+func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver.DeviceDriver, func(), error) {
+	if options.Platform == "web" {
+		d := chrome.New()
+		return d, func() { _ = d.Terminate(context.Background()) }, nil
+	}
+
+	sidecarDirectory := os.TempDir() + "/sanderling-sidecar"
+	jarPath, err := sidecar.Extract(sidecarDirectory)
+	if err != nil {
+		return nil, nil, fmt.Errorf("extract sidecar: %w", err)
+	}
+	fmt.Fprintf(stdout, "sidecar JAR: %s (size=%d)\n", jarPath, sidecar.EmbeddedSize())
+
+	sidecarPort, err := pickFreePort()
+	if err != nil {
+		return nil, nil, err
+	}
+	sidecarCommand := exec.CommandContext(ctx, "java", "-jar", jarPath,
+		"--port", strconv.Itoa(sidecarPort),
+		"--platform", options.Platform,
+	)
+	sidecarCommand.Stdout = stdout
+	sidecarCommand.Stderr = stdout
+	sidecarCommand.Env = android.EnvWithAndroidPlatformTools(os.Environ())
+	if err := sidecarCommand.Start(); err != nil {
+		return nil, nil, fmt.Errorf("spawn sidecar: %w", err)
+	}
+	fmt.Fprintf(stdout, "sidecar pid=%d listening on 127.0.0.1:%d\n", sidecarCommand.Process.Pid, sidecarPort)
+
+	driverClient, err := driverSidecar.Dial(fmt.Sprintf("127.0.0.1:%d", sidecarPort))
+	if err != nil {
+		_ = sidecarCommand.Process.Kill()
+		return nil, nil, fmt.Errorf("dial sidecar: %w", err)
+	}
+	healthCtx, healthCancel := context.WithTimeout(ctx, sidecarStartupTimeout)
+	if err := driverClient.WaitForHealth(healthCtx, 250e6); err != nil {
+		healthCancel()
+		_ = sidecarCommand.Process.Kill()
+		_ = driverClient.Close()
+		return nil, nil, fmt.Errorf("sidecar health check: %w", err)
+	}
+	healthCancel()
+	fmt.Fprintln(stdout, "sidecar is healthy")
+
+	cleanup := func() {
+		_ = driverClient.Close()
+		if sidecarCommand.Process != nil {
+			_ = sidecarCommand.Process.Kill()
+		}
+	}
+	return driverClient, cleanup, nil
+}

internal/testrun/progress.go

@@ -0,0 +1,47 @@
+package testrun
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"strings"
+)
+
+func newProgressLogger(writer io.Writer) *slog.Logger {
+	return slog.New(&progressHandler{writer: writer, level: slog.LevelInfo})
+}
+
+type progressHandler struct {
+	writer io.Writer
+	level  slog.Level
+}
+
+func (h *progressHandler) Enabled(_ context.Context, level slog.Level) bool {
+	return level >= h.level
+}
+
+func (h *progressHandler) Handle(_ context.Context, record slog.Record) error {
+	var builder strings.Builder
+	if record.Level >= slog.LevelWarn {
+		fmt.Fprintf(&builder, "%s: ", strings.ToLower(record.Level.String()))
+	}
+	builder.WriteString(record.Message)
+	record.Attrs(func(attr slog.Attr) bool {
+		fmt.Fprintf(&builder, " %s=%s", attr.Key, formatAttrValue(attr.Value))
+		return true
+	})
+	builder.WriteByte('\n')
+	_, err := io.WriteString(h.writer, builder.String())
+	return err
+}
+
+func (h *progressHandler) WithAttrs(_ []slog.Attr) slog.Handler { return h }
+func (h *progressHandler) WithGroup(_ string) slog.Handler      { return h }
+
+func formatAttrValue(value slog.Value) string {
+	if value.Kind() == slog.KindString {
+		return fmt.Sprintf("%q", value.String())
+	}
+	return value.String()
+}

internal/testrun/testrun.go

@@ -0,0 +1,223 @@
+package testrun
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"math/rand/v2"
+	"net"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/priyanshujain/sanderling/internal/agent"
+	"github.com/priyanshujain/sanderling/internal/android"
+	"github.com/priyanshujain/sanderling/internal/bundler"
+	"github.com/priyanshujain/sanderling/internal/runner"
+	"github.com/priyanshujain/sanderling/internal/trace"
+	"github.com/priyanshujain/sanderling/internal/verifier"
+)
+
+const (
+	socketName            = "sanderling-agent"
+	sidecarStartupTimeout = 30 * time.Second
+	sdkAcceptTimeout      = 60 * time.Second
+)
+
+// Options are the parameters for a single test pipeline run.
+type Options struct {
+	Spec     string
+	BundleID string
+	Platform string
+	AVD      string
+	Duration time.Duration
+	Seed     int64
+	Output   string
+}
+
+// Execute runs the full test pipeline: bundle, connect SDK, verify properties.
+func Execute(ctx context.Context, options Options, stdout io.Writer) error {
+	if options.Platform == "android" || options.Platform == "ios" {
+		if err := android.EnsureDevice(ctx, options.AVD, stdout); err != nil {
+			return err
+		}
+	}
+	aliases := map[string]string{}
+	if specAPIPath := resolveSpecAPIPath(options.Spec); specAPIPath != "" {
+		aliases["@sanderling/spec"] = specAPIPath
+		base := filepath.Dir(specAPIPath)
+		aliases["@sanderling/spec/defaults/properties"] = filepath.Join(base, "defaults/properties.ts")
+	}
+	bundle, err := bundler.Bundle(bundler.Options{
+		EntryFile: options.Spec,
+		Defines: map[string]string{
+			"SANDERLING_TEST_PHONE": os.Getenv("SANDERLING_TEST_PHONE"),
+			"SANDERLING_TEST_OTP":   os.Getenv("SANDERLING_TEST_OTP"),
+		},
+		Aliases: aliases,
+	})
+	if err != nil {
+		return fmt.Errorf("bundle spec: %w", err)
+	}
+	fmt.Fprintf(stdout, "bundled spec: %d bytes (sha256=%s)\n", len(bundle.JavaScript), bundle.SHA256[:12])
+
+	activeDriver, cleanup, err := buildDriver(ctx, options, stdout)
+	if err != nil {
+		return err
+	}
+	defer cleanup()
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return fmt.Errorf("agent listener: %w", err)
+	}
+	defer listener.Close()
+	agentPort := listener.Addr().(*net.TCPAddr).Port
+
+	if options.Platform != "web" {
+		if err := android.AdbReverse(socketName, agentPort); err != nil {
+			return fmt.Errorf("adb reverse: %w", err)
+		}
+		defer func() {
+			if err := android.AdbReverseRemove(socketName); err != nil {
+				fmt.Fprintf(stdout, "warning: adb reverse cleanup: %v\n", err)
+			}
+		}()
+		fmt.Fprintf(stdout, "forwarded localabstract:%s -> tcp:%d\n", socketName, agentPort)
+	}
+
+	agentServer := agent.NewServer(listener)
+
+	type acceptResult struct {
+		connection *agent.Conn
+		err        error
+	}
+	acceptChannel := make(chan acceptResult, 1)
+	go func() {
+		acceptCtx, cancel := context.WithTimeout(ctx, sdkAcceptTimeout)
+		defer cancel()
+		connection, acceptErr := agentServer.Accept(acceptCtx)
+		acceptChannel <- acceptResult{connection: connection, err: acceptErr}
+	}()
+
+	if err := activeDriver.Launch(ctx, options.BundleID, false); err != nil {
+		return fmt.Errorf("launch app: %w", err)
+	}
+	fmt.Fprintf(stdout, "launched %s; waiting for SDK to connect (%.0fs timeout)\n", options.BundleID, sdkAcceptTimeout.Seconds())
+
+	result := <-acceptChannel
+	if result.err != nil {
+		return fmt.Errorf("accept SDK: %w", result.err)
+	}
+	connection := result.connection
+	defer connection.Close()
+	hello := connection.Hello()
+	fmt.Fprintf(stdout, "SDK connected: platform=%s app=%s sdk=%s\n", hello.Platform, hello.AppPackage, hello.Version)
+
+	seed := options.Seed
+	if seed == 0 {
+		seed = time.Now().UnixNano()
+	}
+	verifierInstance, err := verifier.New(verifier.WithRand(rand.New(rand.NewPCG(uint64(seed), 0))))
+	if err != nil {
+		return fmt.Errorf("verifier: %w", err)
+	}
+	if err := verifierInstance.Load(string(bundle.JavaScript)); err != nil {
+		return fmt.Errorf("load spec: %w", err)
+	}
+	fmt.Fprintln(stdout, "spec loaded into verifier")
+
+	runDirectory := filepath.Join(options.Output, time.Now().UTC().Format("20060102-150405"))
+	traceWriter, err := trace.NewWriter(runDirectory)
+	if err != nil {
+		return fmt.Errorf("trace writer: %w", err)
+	}
+	defer traceWriter.Close()
+	meta := trace.Meta{
+		Seed:              seed,
+		SpecPath:          options.Spec,
+		BundleSHA256:      bundle.SHA256,
+		Platform:          options.Platform,
+		BundleID:          options.BundleID,
+		StartedAt:         time.Now().UTC(),
+		SanderlingVersion: "0.0.1",
+	}
+	if err := traceWriter.WriteMeta(meta); err != nil {
+		return fmt.Errorf("trace meta: %w", err)
+	}
+	defer func() {
+		endedAt := time.Now().UTC()
+		meta.EndedAt = &endedAt
+		_ = traceWriter.WriteMeta(meta)
+	}()
+	fmt.Fprintf(stdout, "trace dir: %s\n", runDirectory)
+
+	fmt.Fprintf(stdout, "running for %s (seed=%d)\n", options.Duration, seed)
+	summary, err := runner.Run(ctx, runner.Options{
+		Duration:        options.Duration,
+		SnapshotTimeout: 5 * time.Second,
+		IdleTimeout:     1 * time.Second,
+		BundleID:        options.BundleID,
+		Connection:      connection,
+		Driver:          activeDriver,
+		Verifier:        verifierInstance,
+		TraceWriter:     traceWriter,
+		Logger:          newProgressLogger(stdout),
+	})
+
+	terminateCtx, terminateCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	_ = activeDriver.Terminate(terminateCtx)
+	terminateCancel()
+
+	if err != nil {
+		return fmt.Errorf("runner: %w", err)
+	}
+
+	fmt.Fprintf(stdout, "\nrun complete: %d steps in %s\n", summary.Steps, summary.EndTime.Sub(summary.StartTime).Round(time.Millisecond))
+	if len(summary.Violations) == 0 {
+		fmt.Fprintln(stdout, "no violations.")
+	} else {
+		fmt.Fprintf(stdout, "%d violation record(s):\n", len(summary.Violations))
+		for _, violation := range summary.Violations {
+			fmt.Fprintf(stdout, "  step %d: %v\n", violation.StepIndex, violation.Properties)
+		}
+	}
+	return nil
+}
+
+// resolveSpecAPIPath returns the path to pkg/spec/src/index.ts inside
+// a sanderling source checkout, searched upward from the spec file and the cwd.
+// Returns "" when not found, in which case esbuild resolves @sanderling/spec via
+// node_modules the way a downstream user's project would.
+func resolveSpecAPIPath(specPath string) string {
+	var candidates []string
+	if absoluteSpec, err := filepath.Abs(specPath); err == nil {
+		directory := filepath.Dir(absoluteSpec)
+		for {
+			candidates = append(candidates, filepath.Join(directory, "pkg/spec/src/index.ts"))
+			parent := filepath.Dir(directory)
+			if parent == directory {
+				break
+			}
+			directory = parent
+		}
+	}
+	if cwd, err := os.Getwd(); err == nil {
+		candidates = append(candidates, filepath.Join(cwd, "pkg/spec/src/index.ts"))
+	}
+	for _, candidate := range candidates {
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+	}
+	return ""
+}
+
+func pickFreePort() (int, error) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return 0, err
+	}
+	defer listener.Close()
+	return listener.Addr().(*net.TCPAddr).Port, nil
+}

internal/testrun/testrun_test.go

@@ -0,0 +1,52 @@
+package testrun
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestResolveSpecAPIPath_FindsUpwardSibling(t *testing.T) {
+	root := t.TempDir()
+	apiPath := filepath.Join(root, "pkg", "spec", "src", "index.ts")
+	if err := os.MkdirAll(filepath.Dir(apiPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(apiPath, []byte("export {}"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	specPath := filepath.Join(root, "examples", "app", "spec.ts")
+	if err := os.MkdirAll(filepath.Dir(specPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(specPath, []byte(""), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got := resolveSpecAPIPath(specPath)
+	if got != apiPath {
+		t.Fatalf("got %q, want %q", got, apiPath)
+	}
+}
+
+func TestResolveSpecAPIPath_ReturnsEmptyWhenMissing(t *testing.T) {
+	root := t.TempDir()
+	specPath := filepath.Join(root, "spec.ts")
+	if err := os.WriteFile(specPath, []byte(""), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(cwd) })
+	if err := os.Chdir(root); err != nil {
+		t.Fatal(err)
+	}
+
+	got := resolveSpecAPIPath(specPath)
+	if got != "" {
+		t.Fatalf("got %q, want empty (no sanderling source tree reachable)", got)
+	}
+}