keymgmtcmd

type ClaimUpdate struct {
	Status  string
	Result  []string
	Done    bool
	Stop    bool
	Prefill string
}

type KeyContext struct {
	IO       output.IO
	JSONMode bool
	Compact  bool
	Home     string
	KM       *keys.Manager
	// IP, when set (by `setup`), carries the probed public IP(s) so the
	// guidance can name the exact allowlist entries to register.
	IP *probe.Report
	// Perms is the permission bitmask to prefill into the registration deep link.
	// Zero means "unset" — treated as permTrading (the safe default).
	Perms int
	// BaseURL / BaseURLSet carry an explicit --base-url. `setup` (only when it
	// first creates the key) and `key add` persist it as the new key's default
	// endpoint, mirroring `key set-base-url`. Unset leaves the key on the default
	// host.
	BaseURL    string
	BaseURLSet bool
	// WSBaseURL / WSBaseURLSet carry an explicit --ws-base-url for `key
	// set-base-url` and the create commands: when set, it is persisted verbatim;
	// when unset, the WebSocket URL is derived from the REST base URL.
	WSBaseURL    string
	WSBaseURLSet bool
	// Verify, when set, smoke-tests the REST + WebSocket endpoints after `key
	// set-base-url` stores them. Nil when the check is skipped (--no-verify) or
	// not applicable to the command.
	Verify func(restURL, wsBaseURL string) probe.EndpointVerification
	// Getenv reads the process environment; `setup` uses it to detect an inline
	// credential (KORBIT_CLI_API_KEY_*). May be nil (the check is then skipped).
	Getenv func(string) string
	// Doctor, when set, runs the read-only health check for a just-configured
	// BOUND key and returns its report. It is advisory: setup embeds the report in
	// its result and surfaces problems as warnings, but a failing check NEVER
	// changes setup's exit code. Nil when the check is skipped.
	Doctor func(keyName string) *doctorcmd.Report
	// VerifyAPIKey, when set, signs a read-only whoami for the named key using a
	// CANDIDATE api key id — with no binding persisted — to confirm the id is
	// registered and the key can sign with it. Both setup lanes call it before
	// binding. wait selects the tolerance: false (manual paste) is one-shot — any
	// rejection (KEY_NOT_FOUND, signature mismatch) is returned so the prompt can
	// retry without ever writing a bad id; true (auto-claim) rides out the
	// just-registered KEY_NOT_FOUND window within a short budget and is best-effort
	// (the caller treats a failure as soft and binds anyway). ctx lets a session
	// cancel abort the wait. nil means an id is bound without checking.
	VerifyAPIKey func(ctx context.Context, name, apiKeyID string, wait bool) error
	// RunInteractive, when set, takes over the awaiting-registration outcome of
	// `setup` on a TTY: instead of printing the registration link and exiting, it
	// shows intro (the lead-in prose + the public key when there is no link) and
	// prompts for the issued key id, then calls submit, which binds the key and runs
	// the health check. registrationURL is the portal deep link (empty when none
	// could be built); the UI renders it as its own width-wrapped, clickable block
	// and offers copy/QR shortcuts for it, so it is passed separately rather than
	// baked into intro. submit returns the lines to display, done=true when setup is
	// complete, or a retryable error to show while keeping the prompt open. The UI
	// renders on stderr; the final result document is still emitted to stdout after
	// it closes. canceled=true means the user aborted with Ctrl-C: the caller emits
	// nothing (matching the non-interactive SIGINT abort). Nil disables interactive
	// setup (a pipe, --json, the MCP server, --no-interactive), and setup falls back
	// to print-and-exit.
	//
	// autoClaim, when non-nil, runs concurrently with the paste prompt: the runner
	// starts it, shows its status, and lets it complete setup automatically when it
	// detects the registered key (see ClaimUpdate). nil leaves manual paste as the
	// only path.
	RunInteractive func(intro []string, registrationURL string, submit func(token string) (lines []string, done bool, err error), autoClaim func(ctx context.Context) <-chan ClaimUpdate) (canceled bool, err error)

	// PollClaim, when set, runs the background auto-claim poll for the freshly
	// generated key `name`, signing the keyless GET /v2/keys/claim with the key's
	// not-yet-bound private key. It calls onStatus with a short live status for
	// transient states (e.g. a brief back-off) and returns one of:
	//   - (id, "", nil)       the key was claimed — the caller binds it
	//   - ("", code, nil)     polling stopped without a claim; code is the API error
	//                         code (e.g. KEY_CLAIM_CONFLICT, IP_NOT_ALLOWED,
	//                         KEY_DEACTIVATED), "" for a generic/malformed stop. The
	//                         caller renders the user notice (claimStopNotice).
	//   - ("", "", err)       ctx was canceled (session ending) or an unexpected fault
	// It journals nothing and logs through the standard logger. nil disables
	// auto-claim (setup falls back to manual paste only).
	PollClaim func(ctx context.Context, name string, onStatus func(status string)) (apiKeyID, stopCode string, err error)

	// WaitForClaim enables the non-interactive headless auto-claim path (`setup
	// --wait`): instead of printing the registration link and exiting, setup prints
	// the link, then blocks polling PollClaim until the key is claimed (or
	// WaitTimeout elapses) and binds + health-checks it automatically — no prompt,
	// no manual paste. It reuses the same PollClaim / VerifyAPIKey / Doctor seams as
	// the interactive auto-claim and works with or without a TTY (so an agent driving
	// the CLI never has to copy the issued id back). Ignored unless PollClaim is set.
	WaitForClaim bool
	// WaitTimeout bounds the headless wait; zero means wait indefinitely. Only
	// consulted when WaitForClaim is set.
	WaitTimeout time.Duration
}