desktop

Documentation

Overview

Package desktop gives the agent hands on the graphical session: listing and controlling windows, taking screenshots, moving the mouse, typing, the clipboard, notifications, and opening files or URLs.

Everything is done through the desktop's own helper programs (xdotool, wmctrl, scrot, xclip, notify-send on X11; grim/wl-clipboard/wtype on Wayland; osascript/screencapture on macOS; PowerShell on Windows) rather than CGO bindings, which keeps Factor a single static binary that still runs on an old Puppy Linux box. Missing helpers are reported as actionable errors ("install xdotool"), never as silent no-ops.

Index

• func HasDisplay(env Env) bool
• func MachineHasDisplay(env Env) bool
• func NewTools(env Env, guard *tools.PathGuard, screenshotDir string) []tools.Tool
• func PackagesFor(helpers []Helper, manager string) []string
• type Controller
  • func NewController(env Env) Controller
• type Env
  • func DefaultEnv() Env
• type Geometry
• type Helper
  • func MissingHelpers(env Env, c Controller) []Helper
  • func (h Helper) Package(manager string) string
• type Point
• type Runner
• type Shot
• type Window
  • func (w Window) String() string

Functions

func HasDisplay

func HasDisplay(env Env) bool

HasDisplay reports whether a graphical session is reachable. Factor runs on headless boxes too; there the desktop tools are pure prompt weight, so the composition root skips registering them (config can force them on).

func MachineHasDisplay

func MachineHasDisplay(env Env) bool

MachineHasDisplay reports whether this machine drives a screen, which is not the same question as whether this process can reach it. A setup run over ssh has no DISPLAY of its own while the box in front of the user is running X the whole time — and deciding from the environment alone is how `factor init` came to skip the desktop step, and its dependencies, on exactly the desktop machines that needed them.

func NewTools

func NewTools(env Env, guard *tools.PathGuard, screenshotDir string) []tools.Tool

NewTools builds the desktop arsenal. screenshotDir receives screenshots when the caller does not name a path; guard keeps written files inside the workspace like every other file-producing tool.

func PackagesFor

func PackagesFor(helpers []Helper, manager string) []string

PackagesFor maps helpers to package names for one package manager, de-duplicated and sorted so install commands are stable.

Types

type Controller

type Controller interface {
	Backend() string
	Helpers() []Helper // in preference order; the tools report what's missing
	ListWindows(ctx context.Context) ([]Window, error)
	ActiveWindow(ctx context.Context) (Window, error)
	Focus(ctx context.Context, w Window) error
	CloseWindow(ctx context.Context, w Window) error
	SetState(ctx context.Context, w Window, state string) error
	MoveResize(ctx context.Context, w Window, g Geometry) error
	Screenshot(ctx context.Context, path string, shot Shot) error
	MoveMouse(ctx context.Context, x, y int) error
	Click(ctx context.Context, button string, count int, at *Point) error
	TypeText(ctx context.Context, text string, delayMs int) error
	PressKey(ctx context.Context, keys string, repeat int) error
	ClipboardGet(ctx context.Context) (string, error)
	ClipboardSet(ctx context.Context, text string) error
	Notify(ctx context.Context, title, body, urgency string) error
	Open(ctx context.Context, target string) error
	ScreenSize(ctx context.Context) (int, int, error)
}

Controller is the per-platform implementation seam.

func NewController

func NewController(env Env) Controller

NewController picks the controller for the environment's platform.

type Env

type Env struct {
	Run    Runner
	Has    func(bin string) bool
	Getenv func(key string) string
	Glob   func(pattern string) ([]string, error)
	GOOS   string
}

Env is the seam between the controllers and the machine.

func DefaultEnv

func DefaultEnv() Env

DefaultEnv wires Env to the real machine.

type Geometry

type Geometry struct {
	X, Y, W, H      int
	HasPos, HasSize bool
}

Geometry is a position/size pair; the Has* flags distinguish "0" from unset.

type Helper

type Helper struct {
	Bin      string
	Purpose  string
	Packages map[string]string // package manager -> package name (default: Bin)
}

Helper is an external program the desktop tools rely on.

func MissingHelpers

func MissingHelpers(env Env, c Controller) []Helper

MissingHelpers lists helpers the controller wants but cannot find.

func (Helper) Package

func (h Helper) Package(manager string) string

Package returns the package to install for the given manager.

type Point

type Point struct{ X, Y int }

Point is an absolute screen coordinate.

type Runner

type Runner func(ctx context.Context, stdin string, argv ...string) (string, error)

Runner executes one helper program with optional stdin and returns its standard output. Tests substitute a scripted runner.

type Shot

type Shot struct {
	Mode   string // screen | window | region
	Window Window
	Region Geometry
}

Shot describes a screenshot request.

type Window

type Window struct {
	ID      string
	PID     int
	App     string
	Title   string
	Desktop string
	X, Y    int
	W, H    int
	HasGeom bool
}

Window is one on-screen window.

func (Window) String

func (w Window) String() string