sandbox

type Config struct {
	// Home is the CLI home (KORBIT_CLI_HOME); mutable state lives under it.
	Home string
	// CacheDir is the shared artifact cache root (os.UserCacheDir()/korbit-cli,
	// or KORBIT_CLI_SANDBOX_CACHE).
	CacheDir string
	// URL overrides the bundle source (Official Source by default; a local path
	// or file:// is read from disk).
	URL string
	// RuntimePref is "", "deno", or "managed-deno".
	RuntimePref string
	// Port is the requested fixed port (0 ⇒ DefaultPort with ephemeral fallback;
	// a non-zero value forces that exact port with no fallback).
	Port int
	// DB overrides the database path (default <home>/sandbox/korbit-sandbox.db).
	DB string
	// KeyName overrides the imported key's name (default DefaultKeyName).
	KeyName string
	// Reimport replaces the imported key's material even if it already exists.
	Reimport bool
	// Paper enables paper trading: a fresh database is initialized with its
	// seeded pairs' market data mirrored LIVE from production Korbit (the
	// bundle's `init-db --source live`, which verifies each pair's production
	// status and needs network); fills stay simulated locally. The seeded set is
	// the bundle's fixture pairs by default, or every LAUNCHED production pair
	// (the tradable universe) when AllPairs is set. On an existing database the
	// flag only VERIFIES the pairs
	// are already in live mode — it never flips a database in place (see
	// ensurePaperDB); combine with Fresh to switch modes.
	Paper bool
	// AllPairs seeds a fresh database from a live production snapshot (the
	// bundle's `init-db --mode korbit-api`) so every LAUNCHED production pair
	// exists (the tradable universe), instead of the bundle's built-in fixture
	// pairs. Orthogonal to Paper: with Paper it mirrors those pairs LIVE, without
	// it they are on the simulated market. The snapshot is cached beside the db
	// (see marketCachePath), so a repeated (re)seed reuses it instead of
	// refetching. Affects initialization only — an existing database keeps its
	// pairs; combine with Fresh to reseed. Needs network.
	AllPairs bool
	// Fresh starts from a brand-new database: any running server for it is
	// stopped first, then the database and its sidecars are deleted before the
	// normal bring-up initializes a new one (in the mode Paper selects).
	// Destructive by design — balances, orders, and trades are discarded; the
	// seeded keys are deterministic, so the imported key stays valid.
	Fresh bool
	// PassThrough are extra args forwarded to the bundle's `run` (e.g.
	// --history-lag-ms), after the CLI-managed ones.
	PassThrough []string
	// SkipVersionCheck disables the min-version gate on start (the bundle is run
	// without MinVersionEnv), so a known-older bundle can still be started.
	SkipVersionCheck bool
}

type Deps struct {
	// Doer downloads the bundle and the managed Deno, and probes /v2/time.
	Doer Doer
	// Now is the clock (UnixMilli).
	Now func() int64
	// Log receives one-line USER-FACING progress notes (downloads, the resolved
	// command line, reuse) — program output the CLI routes to a Note, NOT a
	// level-gated log. Kept as a func(string) seam.
	Log func(string)
	// Logger receives structured operational DIAGNOSTICS about the lifecycle —
	// runtime resolution, the resolved command line, detached spawn pid, readiness
	// polling, pidfile reads, the reuse/spawn decision, the port-collision
	// fallback, stop/kill, and the version gate. nil = silent (logging.Or). It is
	// distinct from Log: Log is program output, Logger is --debug telemetry.
	Logger *slog.Logger
	// LookPath resolves an executable (exec.LookPath); tests stub it to control
	// whether a system `deno` appears present.
	LookPath func(string) (string, error)
	// DenoURL / DenoVersion override the managed-Deno pin (KORBIT_CLI_DENO_*).
	DenoURL     string
	DenoVersion string
	// KeyManager imports the seeded key; the caller wires it over KORBIT_CLI_HOME.
	KeyManager *keys.Manager
	// BannerOut, if set, receives the short license notice at the top of `start`
	// (rendered by the bundle's own `license --show-banner`, so the text is never
	// reproduced in the CLI). Wired to the CLI's stderr; nil disables the banner.
	BannerOut io.Writer
}

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

type Manager struct {
	// contains filtered or unexported fields
}

type Pidfile struct {
	PID  int `json:"pid"`
	Port int `json:"port"`
}

type Runtime struct {
	Kind RuntimeKind
	// contains filtered or unexported fields
}

type RuntimeKind string

type ServerState struct {
	Running bool `json:"running"`
	PID     int  `json:"pid,omitempty"`
	Port    int  `json:"port,omitempty"`
	// Reachable is the result of a /v2/time probe against the bound port.
	Reachable bool `json:"reachable"`
}

type StartResult struct {
	PID         int    `json:"pid"`
	Port        int    `json:"port"`
	RestBaseURL string `json:"restBaseUrl"`
	WSBaseURL   string `json:"wsBaseUrl"`
	KeyName     string `json:"keyName"`
	APIKeyID    string `json:"apiKeyId"`
	Runtime     string `json:"runtime"`
	Bundle      string `json:"bundle"`
	DB          string `json:"db"`
	LogPath     string `json:"logPath"`
	Imported    bool   `json:"imported"`
	// Paper reports the started database's ACTUAL mode, read from the bundle's
	// status — not merely whether --paper was passed. True when the database
	// was initialized for paper trading (`init-db --source live`), or when
	// every configured pair mirrors live production market data.
	Paper bool `json:"paper"`
	// WalkPairs lists the pairs still on the simulated walk while Paper is true
	// — pairs production reported non-launched when the database was
	// initialized, so their market data is not mirrored. Omitted from the JSON
	// (not an empty array) for a fully-live paper database and when Paper is
	// false.
	WalkPairs []string `json:"walkPairs,omitempty"`
	// PairCount is the total number of configured pairs.
	PairCount int `json:"pairCount"`
	// Recreated reports that --fresh deleted an existing database before the
	// start (previous balances/orders/trades were discarded). False when
	// --fresh found no database to delete.
	Recreated bool `json:"recreated"`
}

type StatusResult struct {
	CachePath    string      `json:"cachePath"`
	BundleCached bool        `json:"bundleCached"`
	SourceURL    string      `json:"sourceUrl,omitempty"`
	Runtime      string      `json:"runtime"`
	DenoPath     string      `json:"denoPath,omitempty"`
	DenoStatus   deno.Status `json:"deno"`
	Server       ServerState `json:"server"`
	DB           string      `json:"db"`
	KeyName      string      `json:"keyName"`
	KeyImported  bool        `json:"keyImported"`
}

type StopResult struct {
	Stopped bool `json:"stopped"`
	PID     int  `json:"pid"`
	Port    int  `json:"port"`
}