clienv

type Backend interface {
	LoadConfig() (home string, cfg config.Config, err error)
	KeyManager(home string, cfg config.Config) *keys.Manager
	// ResolveBaseURL resolves the REST base URL by the documented precedence
	// (flag > env > per-key > config > prod default).
	ResolveBaseURL(cmd *cobra.Command, cfg config.Config, keyBaseURL string) string
	// ResolveURLs resolves the REST base URL and its paired WebSocket base URL in
	// one step (the WS precedence guards against pairing a stale stored WS host
	// with a higher REST override).
	ResolveURLs(cmd *cobra.Command, cfg config.Config, keyBaseURL, keyWSBaseURL string) (rest, ws string, err error)
	// BuildClient is the one korbit.Client construction site (logger, retry
	// trace, journaling closure, Origin, User-Agent, shared clock, resync hook).
	BuildClient(ClientSpec) *korbit.Client
	// NewClockSyncer builds the process-wide clock Syncer for a surface over a
	// shared State.
	NewClockSyncer(state *clock.State, baseURL string, timeoutMs int, surface, detail string) *clock.Syncer
	// MeasureOffset probes /v2/time and returns the measured server-clock offset
	// (doctor's skew check signs against a raw clock, so it measures directly).
	MeasureOffset(baseURL string, timeoutMs int) (korbit.ClockOffset, error)
	// NewRecorder builds the journal-backed recorder with a caller-chosen
	// post-write-failure sink.
	NewRecorder(home string, log *slog.Logger, onFail func(callrec.FailMode, error)) *callrec.Recorder
	// LogRecorder is NewRecorder with the common sink: a post-call journal-write
	// failure is logged and the command continues.
	LogRecorder(home string, log *slog.Logger) *callrec.Recorder
}

type ClientSpec struct {
	Surface, Detail string              // korbit.Origin + the useragent component/detail
	BaseURL         string              //
	Creds           *korbit.Credentials // nil = public-only
	KeyName         string              // the named signing key (recorded into CallInfo; "" for public)
	// Clock is the shared server-clock estimate to sign against: a syncer's
	// State for normal surfaces, a raw never-resynced clock for doctor (so skew
	// surfaces), or nil for a pure-public read.
	Clock korbit.Clock
	// Resync is the ONE clock-resync primitive (a syncer's Sync) for
	// auto-correcting EXCEED_TIME_WINDOW; nil = no auto-correct.
	Resync    func() error
	TimeoutMs int
	// Rec is the surface's journal recorder; nil = never journaled.
	Rec *callrec.Recorder
	// Log is the surface's operational logger; nil = silent.
	Log *slog.Logger
}

type Cmd struct {
	Env
	Backend
	Console
}

type Confirm func(question string, defaultYes bool) (bool, error)

type Console interface {
	// Emit writes a command's success result through the mode-aware emitter —
	// JSON under --json/--compact, otherwise the command's human formatter.
	Emit(commandKey string, value any) error
	// CommandHelp renders focused per-command help for a command id (folding in
	// the experimental opt-in), reporting false when no such command exists.
	CommandHelp(id ...string) (string, bool)
}

type Env struct {
	// Getenv reads the process environment (injectable so tests can stub it).
	Getenv func(string) string
	// Doer is the HTTP client public/signed calls run through.
	Doer korbit.Doer
	// Now is the local clock in unix-ms (injectable for tests).
	Now func() int64
	// Sleep delays for a duration (injectable for tests); the streaming commands
	// thread it into the stream session and bot retry budgets.
	Sleep func(time.Duration)
	// IO is the stdout/stderr output contract sink. IO.Err is the one locked
	// stderr sink shared by program output and (when not diverted) the logs.
	IO output.IO
	// Log is the one operational logger for this invocation (already resolved
	// for level/destination/format). A command needing a logger at a different
	// level builds one over the same sink via the logging package.
	Log *slog.Logger
	// LogSink is the writer Log writes to — the locked stderr sink, or the
	// --log-file writer. A streaming command builds its own leveled stream/state/
	// notice loggers over it with logging.NewStyled(LogSink, level, LogStyle).
	LogSink io.Writer
	// LogStyle is the resolved log line shape (text/json, timestamped under
	// --log-file), shared so a command's extra loggers match the operational one.
	LogStyle logging.Style
	// LogLevel is the resolved operational threshold, the level a streaming
	// command gives its stream/state loggers.
	LogLevel slog.Level
	// LogToFile is true when --log-file diverts the operational logs to a file
	// (else they share the stderr sink). The tui logs only in that case — under
	// its alt-screen stderr is unusable.
	LogToFile bool

	// Modes carries the resolved global mode flags (CLI flag / env), so a command
	// subpackage reads them without reaching into cli's runtime.
	Modes Modes

	// Key is the --key selection (empty = the default / env / inline rules).
	Key string
	// IPProbe fetches the public IP over a TCP family (doctor / setup).
	IPProbe korbit.IPProber
	// FamilyDoer returns a Doer pinned to a TCP family ("tcp4"/"tcp6"); doctor
	// uses it to replay a signed request per family to diagnose an IP-allowlist
	// rejection.
	FamilyDoer func(network string, timeoutMs int) korbit.Doer
	// Family is the effective outbound IP family (after any --bind narrowing). The
	// ip/doctor probes cap to Family.Networks() so they never reach out a family
	// --family excluded, and doctor warns when it is not dualstack (a single
	// family means a narrower diagnosis). The zero value is dualstack (both).
	Family netbind.Family
	// WSDial opens the WebSocket connections the streaming commands and doctor's
	// reachability check use.
	WSDial stream.Dialer
	// Confirm asks the user a yes/no question, for a command that is interactive by
	// nature (self uninstall). nil means no interactive confirmer is available
	// (stdin is not a terminal, or a machine-output mode is active) — such a
	// command must refuse to run rather than proceed non-interactively.
	Confirm Confirm
}

type ExitError struct{ Code int }

type Modes struct {
	// DryRun is --dry-run: build and show the plan, sign/send nothing.
	DryRun bool
	// JSONMode is the effective machine-output mode (--json or --compact).
	JSONMode bool
	// TimeSync is --time-sync / KORBIT_CLI_TIME_SYNC: the server-clock sync mode
	// (auto default, on, or off).
	TimeSync TimeSyncMode
	// NoFsync is --no-fsync / KORBIT_CLI_NO_FSYNC: open the journal and bot DB
	// with synchronous=OFF.
	NoFsync bool
	// Experimental is --enable-experimental / KORBIT_CLI_ENABLE_EXPERIMENTAL: the
	// opt-in gate for not-yet-stable features (the monitor JS bot runtime).
	Experimental bool
}

type TimeSyncMode string