iterm2

type AgentResolveFixture struct {
	Kind      string // grok | codex | none
	SessionID string
	Title     string // optional GrokTitle
	Tree      []AgentTreeNode
}

type AgentTreeNode struct {
	PID  int    `json:"pid"`
	PPID int    `json:"ppid"`
	Role string `json:"role,omitempty"` // input | agent-run | … | grok | codex | other
	Cmd  string `json:"cmd"`
}

type CaptureOpts struct {
	// NoEnrich skips procresolve agent attach (CLI --no-enrich).
	NoEnrich bool
	// SpaceAllow, when non-empty, enables space-first filtering: resolve each
	// window's Space from WindowID/FixedSpace and skip ListTabsAndSessions +
	// enrich when the index is not in the allowlist (go-best-practice: cheap
	// gate before expensive work). Used by sessions save --spaces.
	SpaceAllow []int
	// SpaceSkipped, when non-nil, receives the count of window headers skipped
	// by SpaceAllow (not deep-captured).
	SpaceSkipped *int
}

type FocusCandidate struct {
	WindowID      string
	WindowTitle   string
	TabIndex      int
	SessionID     string
	Path          string
	KoolTargetDir string
}

type FocusFake struct {
	Candidates    []FocusCandidate
	Focused       []string
	DiscoverCalls int
}

type FormatFlags struct {
	JSON     bool
	Markdown bool
	HTML     bool
}

type MultiAppPreflight struct {
	// AsApp is the canonical app that bare `tell application "iTerm2"` targets.
	AsApp string
	// RunningApps is the set of canonical installs with a live process
	// (home and/or system). Order is not significant.
	RunningApps []string
}

type MultiAppPreflightFn func() (MultiAppPreflight, error)

type OutputFormat string

type PhasedFixtureOpts struct {
	Windows       []SnapshotWindow
	ITermRunning  bool
	OnListWindows func()
	OnListTabs    func(windowIndex int)
	// IdleTTYs are short tty names (e.g. "ttys001") classified idle (shell only).
	IdleTTYs []string
	// BusyTTYs are short tty names classified busy (non-shell foreground work).
	BusyTTYs []string
	// BusyLeafByTTY overrides the default busy leaf command (python train.py)
	// for that short tty. Use e.g. "mark still waiting" for mark fixtures.
	BusyLeafByTTY map[string]string
	// CwdByTTY sets the cwd returned for processes on that short tty (default /tmp).
	CwdByTTY map[string]string
	Now      time.Time
	Hostname string
	// AgentResolveByTTY injects procresolve results keyed by short tty (e.g. "ttys002").
	// Applied after process enrich for busy sessions when enrich is on.
	AgentResolveByTTY map[string]AgentResolveFixture
}

type RenderOptions struct {
	Format  OutputFormat
	NoColor bool
	// NoTree omits FormatTree process-tree lines while keeping agent session id.
	NoTree bool
	// ForceColor forces ANSI even when stdout is not a TTY (tests).
	ForceColor bool
	// ColorWriter is checked for TTY (defaults to os.Stdout).
	ColorWriter *os.File
}

type RestoreAppTarget struct {
	// Canonical is ~/Applications/iTerm.app or /Applications/iTerm.app, or empty when Bare.
	Canonical string
	// Bare means fall back to tell application "iTerm2" (no path).
	Bare bool
	// Warning is optional user message without the "warning:" prefix.
	Warning string
}

type SaveDocument struct {
	Version    int          `json:"version"`
	SavedAt    string       `json:"saved_at"`
	RestoredAt *string      `json:"restored_at"` // null until restore succeeds
	Host       string       `json:"host"`
	Source     string       `json:"source"`
	Filter     *SaveFilter  `json:"filter,omitempty"` // present when save used --spaces
	Summary    SaveSummary  `json:"summary"`
	Windows    []SaveWindow `json:"windows"`
}

type SaveFilter struct {
	// Spaces is the sorted, deduped 0-based allowlist from --spaces.
	Spaces []int `json:"spaces,omitempty"`
}

type SaveSummary struct {
	Windows  int            `json:"windows"`
	Tabs     int            `json:"tabs"`
	Sessions int            `json:"sessions"`
	ByKind   map[string]int `json:"by_kind"`
}

type SaveTab struct {
	SourceTabIndex  int    `json:"source_tab_index,omitempty"`
	SourcePaneIndex int    `json:"source_pane_index,omitempty"`
	Name            string `json:"name,omitempty"`
	Cwd             string `json:"cwd"`
	Kind            string `json:"kind"` // grok | codex | mark
	SessionID       string `json:"session_id,omitempty"`
	Message         string `json:"message,omitempty"` // mark only
	Title           string `json:"title,omitempty"`
	ResumeCmd       string `json:"resume_cmd"`
	ItermSessionID  string `json:"iterm_session_id,omitempty"`
	SourceCmdLine   string `json:"source_command_line,omitempty"`
}

type SaveWindow struct {
	SourceIndex   int       `json:"source_index"`
	Name          string    `json:"name,omitempty"`
	App           string    `json:"app,omitempty"`             // canonical install; restore prefer-home or --same-app
	Space         int       `json:"space"`                     // 0-based Desktop; always emitted when not ignore
	ItermWindowID int64     `json:"iterm_window_id,omitempty"` // info only at save; restore never uses it
	Tabs          []SaveTab `json:"tabs"`
	// contains filtered or unexported fields
}

type SessionAgent struct {
	Kind      string          `json:"kind"`
	SessionID string          `json:"session_id"`
	Title     string          `json:"title,omitempty"`
	Tree      []AgentTreeNode `json:"tree,omitempty"`
}

type Snapshot struct {
	CapturedAt string           `json:"captured_at"`
	Host       string           `json:"host"`
	Source     string           `json:"source"`
	Summary    SnapshotSummary  `json:"summary"`
	Windows    []SnapshotWindow `json:"windows"`
}

type SnapshotCollector struct {
	// RunAppleScript runs an AppleScript body and returns stdout.
	RunAppleScript func(script string) (string, error)
	// ListProcs returns processes on a short tty name (e.g. "ttys003").
	ListProcs func(ttyShort string) ([]rawProc, error)
	// ListCwds returns cwd paths keyed by pid for the given pids.
	ListCwds func(pids []int) (map[int]string, error)
	// ITermRunning reports whether iTerm2 appears to be running.
	ITermRunning func() bool
	// Now is the clock (defaults to time.Now).
	Now func() time.Time
	// Hostname defaults to os.Hostname.
	Hostname func() (string, error)

	// OnListWindows is an optional test hook invoked at the start of ListWindows.
	OnListWindows func()
	// OnListTabs is an optional test hook invoked at the start of ListTabsAndSessions.
	OnListTabs func(windowIndex int)

	// ResolveFromPID optionally overrides live procresolve (production default).
	ResolveFromPID func(pid int) (*procresolve.Result, error)

	// AppTell is the AppleScript application target for live capture.
	// Empty → "iTerm2". Absolute path → tell that .app (second dual-install instance).
	// Canonical App tags are set separately via AppTag / multi-app merge.
	AppTell string
	// AppTag is stamped on every window from this collector (canonical app path).
	// Empty leaves window.App unset (fixtures may set App per window).
	AppTag string
	// contains filtered or unexported fields
}

type SnapshotProc struct {
	PID             int     `json:"pid"`
	PPID            int     `json:"ppid"`
	Stat            string  `json:"stat"`
	Etime           string  `json:"etime"`
	DurationSeconds int64   `json:"duration_seconds"`
	Duration        string  `json:"duration"`
	StartTime       *string `json:"start_time"`
	StartTimeUnix   *int64  `json:"start_time_unix"`
	RSSKB           int64   `json:"rss_kb"`
	Command         string  `json:"command"`
}

type SnapshotSession struct {
	Index             int            `json:"index"`
	ID                string         `json:"id"`
	Name              string         `json:"name"`
	TTY               string         `json:"tty"`
	Profile           string         `json:"profile"`
	ItermIsProcessing bool           `json:"iterm_is_processing"`
	Idle              *bool          `json:"idle"` // nil = unknown
	Cwd               *string        `json:"cwd"`
	ShellPID          *int           `json:"shell_pid"`
	PID               *int           `json:"pid"`
	PPID              *int           `json:"ppid"`
	Stat              *string        `json:"stat"`
	Command           *string        `json:"command"`
	CommandLine       *string        `json:"command_line"`
	StartTime         *string        `json:"start_time"`
	StartTimeUnix     *int64         `json:"start_time_unix"`
	DurationSeconds   *int64         `json:"duration_seconds"`
	Duration          *string        `json:"duration"`
	Etime             *string        `json:"etime"`
	RSSKB             *int64         `json:"rss_kb"`
	Processes         []SnapshotProc `json:"processes"`
	// Agent is set when procresolve finds a grok/codex session on a busy pane.
	Agent *SessionAgent `json:"agent,omitempty"`
	// Layout hints (not required for id resolution).
	WindowIndex int `json:"window_index,omitempty"`
	TabIndex    int `json:"tab_index,omitempty"`
}

type SnapshotSummary struct {
	Windows  int `json:"windows"`
	Tabs     int `json:"tabs"`
	Sessions int `json:"sessions"`
	Idle     int `json:"idle"`
	Busy     int `json:"busy"`
	Unknown  int `json:"unknown"`
}

type SnapshotTab struct {
	Index    int               `json:"index"`
	Name     string            `json:"name"`
	Sessions []SnapshotSession `json:"sessions"`
}

type SnapshotWindow struct {
	Index int    `json:"index"`
	Name  string `json:"name"`
	// WindowID is the iTerm/AppleScript window id (CG window number when available).
	// Used to resolve macOS Space on sessions save; zero means unknown.
	WindowID uint64 `json:"window_id,omitempty"`
	// FixedSpace, when non-nil, is the resolved 0-based Space for tests/fixtures.
	// Prefer this over SpaceIndexForWindow so parallel tests need no global hook.
	FixedSpace *int `json:"-"`
	// App is the canonical iTerm install that owns this window (fixture tag or
	// multi-app save source). Only "~/Applications/iTerm.app" or
	// "/Applications/iTerm.app". Not emitted on sessions snapshot JSON.
	App  string        `json:"-"`
	Tabs []SnapshotTab `json:"tabs"`
}

type SpaceBackend = space.Backend

type SpaceIndexResolver func(windowID uint64) (int, error)

type TestRun struct {
	TabSetDir string
	GOOS      string
	Installed func() bool
	Osascript func(script string) error
	// Contents overrides lib.Contents (tests).
	Contents func(sessionID string, cfg *lib.ContentsConfig) (lib.ContentsResult, error)
}