tmux client library for Go

// Command control-mode-subscribe watches a persistent tmux control client
// receive changes without polling.
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/libtmux/libtmux-go/tmux"
)

func main() {
	if err := start(); err != nil {
		log.Fatal(err)
	}
}

// start owns cleanup because log.Fatal skips deferred calls in main.
func start() error {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	// Choose an unused socket name: cleanup kills the server selected here.
	// The empty config keeps personal settings out of a new server.
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: "libtmux-control-mode-subscribe",
		ConfigFile: os.DevNull,
	})
	if err != nil {
		return fmt.Errorf("configure tmux server: %w", err)
	}
	return run(ctx, server)
}

// run accepts injected server state so tests can isolate the example.
func run(ctx context.Context, server tmux.Server) (err error) {
	session, err := server.NewSession(ctx, tmux.NewSessionRequest{Name: "libtmux-control"})
	if err != nil {
		return fmt.Errorf("create session: %w", err)
	}
	defer func() {
		cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
		defer cleanupCancel()
		err = errors.Join(err, session.Kill(cleanupCtx))
	}()

	// docs:watching given:ctx context.Context; session tmux.Session
	stream, err := session.OpenNotifications(ctx, tmux.NotificationOptions{})
	if err != nil {
		return fmt.Errorf("open notification stream: %w", err)
	}
	defer func() { err = errors.Join(err, stream.Close()) }()

	// Rename after subscribing; notifications do not include earlier changes.
	if _, err := session.Rename(ctx, "control-example"); err != nil {
		return fmt.Errorf("rename session: %w", err)
	}

	for {
		notification, err := stream.Next(ctx)
		if err != nil {
			return fmt.Errorf("read notification: %w", err)
		}
		fmt.Printf("notification: %s\n", notification.Kind())
		if notification.Kind() == tmux.ControlNotificationSessionRenamed {
			fmt.Println("heard the rename")
			break
		}
	}
	// docs:end

	// docs:subscribing given:ctx context.Context; session tmux.Session; stream *tmux.NotificationStream
	// A subscription is a format tmux evaluates for you: it reports the value
	// when it first looks, about a second later, and then each time it changes.
	if err := stream.Subscribe(ctx, tmux.SubscriptionRequest{
		Name: "windows", Format: "#{session_windows}",
	}); err != nil {
		return fmt.Errorf("subscribe: %w", err)
	}
	if _, err := session.NewWindow(ctx, tmux.NewWindowRequest{}); err != nil {
		return fmt.Errorf("open window: %w", err)
	}
	for {
		notification, err := stream.Next(ctx)
		if err != nil {
			return fmt.Errorf("read notification: %w", err)
		}
		if change, ok := notification.Subscription(); ok && change.Value == "2" {
			fmt.Println("session has", change.Value, "windows")
			return nil
		}
	}
	// docs:end
}

// Command run-to-completion runs a program in a tmux pane and reads its exit
// status and screen back, the way os/exec would if the program had a terminal.
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/libtmux/libtmux-go/tmux"
)

func main() {
	if err := start(); err != nil {
		log.Fatal(err)
	}
}

// start owns cleanup because log.Fatal skips deferred calls in main.
func start() error {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	// Choose an unused socket name: cleanup kills the server selected here.
	// The empty config keeps personal settings out of a new server.
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: "libtmux-run-to-completion",
		ConfigFile: os.DevNull,
	})
	if err != nil {
		return fmt.Errorf("configure tmux server: %w", err)
	}
	return run(ctx, server)
}

// run accepts injected server state so tests can isolate the example.
func run(ctx context.Context, server tmux.Server) (err error) {
	session, err := server.NewSession(ctx, tmux.NewSessionRequest{Name: "libtmux-run"})
	if err != nil {
		return fmt.Errorf("create session: %w", err)
	}
	defer func() {
		cleanupCtx, cleanupCancel := context.WithTimeout(context.WithoutCancel(ctx), time.Second)
		defer cleanupCancel()
		err = errors.Join(err, session.Kill(cleanupCtx))
	}()

	// docs:run-to-completion given:ctx context.Context; session tmux.Session
	// The command runs with a terminal, so test -t holds where a pipe fails.
	command := "test -t 1 && echo stdout is a terminal; exit 3"
	result, err := session.Run(ctx, command, tmux.RunOptions{})
	if err != nil {
		return fmt.Errorf("run command: %w", err)
	}
	for _, line := range result.Lines {
		fmt.Println("screen:", line)
	}
	fmt.Println("exited", result.Status)
	// docs:end

	// docs:run-streaming given:ctx context.Context; session tmux.Session
	// Start returns while the command is still running, so its output can be
	// followed and it can be stopped from another goroutine. The stream begins
	// where StreamTo opens it, so this command waits before its first line;
	// result.Lines holds the screen either way.
	running, err := session.Start(ctx, "sleep 1; seq 1 3; sleep 30", tmux.RunOptions{})
	if err != nil {
		return fmt.Errorf("start command: %w", err)
	}
	stopped := make(chan error, 1)
	go func() {
		time.Sleep(2 * time.Second)
		stopped <- running.Kill(ctx)
	}()
	streamed, err := running.StreamTo(ctx, os.Stdout)
	if err != nil {
		return fmt.Errorf("stream command: %w", err)
	}
	if err := <-stopped; err != nil {
		return fmt.Errorf("stop command: %w", err)
	}
	fmt.Println("stopped:", streamed.Signal)
	// docs:end
	return nil
}