dialog

Documentation

Overview

Package dialog provides a small abstraction over native OS dialogs for LLM-safe credential entry. The LLM driving the CLI never sees what the user types — input goes directly into the OS, and only a redacted receipt comes back over stdout.

Usage

Callers use the package-level Default Prompter. Tests can swap it via SetDefault and restore in t.Cleanup.

Backend

The default backend wraps github.com/ncruces/zenity. It is the only place this package depends on zenity — sibling projects can replace the default with their own Prompter (e.g. a Win32 native popup, a localhost browser form, or a stub) without touching anything else.

Availability contract

Prompter.Available returns nil when a GUI dialog can plausibly be shown. It returns an error wrapping ErrNoGUI when the host is clearly headless (no display server, no SSH local-terminal hint, no interactive Windows session) and an error wrapping ErrUnsupported on platforms with no implementation. Available is best-effort — when it cannot pre-classify, it returns nil and lets the dialog itself surface a platform-specific error from Prompter.Prompt.

Error classification

ClassifyError maps Prompter errors onto a neutral Category + hint string. Sibling projects plug this into their own error envelope (e.g. {"error": err.Error(), "fixable_by": cat, "hint": hint}) without re-deriving the sentinel→category mapping.

Index

• Variables
• func SetDefault(p Prompter) (restore func())
• type Category
  • func ClassifyError(err error) (Category, string)
• type Field
• type InputType
• type Prompter
• type Result
• type Spec

Variables

var (
	ErrCancelled   = errors.New("cancelled by user")
	ErrNoGUI       = errors.New("no GUI dialog available")
	ErrUnsupported = errors.New("platform unsupported")
)

Sentinel errors returned by Prompter implementations. Callers use errors.Is to classify failures.

Functions

func SetDefault

func SetDefault(p Prompter) (restore func())

SetDefault replaces the package-level Default and returns a function that restores the previous value. Intended for tests.

Types

type Category

type Category string

Category groups Prompter errors by who can fix them. Mirrors common LLM-error taxonomies (e.g. agent-sql's fixable_by) but stays free of host-application types so this package is droppable into siblings.

const (
	// CategoryHuman — environment issue. The user must change something
	// (use a graphical machine, install zenity/kdialog, etc.). Don't retry.
	CategoryHuman Category = "human"
	// CategoryRetry — transient. The user cancelled the dialog; re-running
	// the same command is the right next step.
	CategoryRetry Category = "retry"
	// CategoryAgent — anything else. The agent can probably correct it
	// (bad spec, programmer error, unknown InputType, etc.).
	CategoryAgent Category = "agent"
)

func ClassifyError

func ClassifyError(err error) (Category, string)

ClassifyError maps a Prompter error onto a Category and a hint string suitable for surfacing to an LLM. Returns (CategoryAgent, "") for nil or unrecognised errors so callers can treat the result uniformly.

Sibling projects can plug this directly into their own error envelope (e.g. {"error": err.Error(), "fixable_by": cat, "hint": hint}) without re-deriving the sentinel→category mapping.

type Field

type Field struct {
	ID        string
	Label     string
	InputType InputType
}

Field is a single input requested from the user.

type InputType

type InputType int

InputType is the kind of field requested.

const (
	// Text is a plain text entry field.
	Text InputType = iota
	// Password is a hidden entry field (echo off).
	Password
)

type Prompter

type Prompter interface {
	Prompt(ctx context.Context, spec Spec) ([]Result, error)
	Available() error
}

Prompter renders a Spec to the user and returns their answers.

Implementations must:

• Return Result entries in the same order as Spec.Items.
• Return an error wrapping ErrCancelled if the user dismisses any popup.
• Return an error wrapping ErrNoGUI if Available reports the host is unusable.

var Default Prompter = &zenityPrompter{}

Default is the Prompter used by the CLI. Tests swap it via SetDefault.

type Result

type Result struct {
	ID    string
	Value string
}

Result is one filled-in field.

type Spec

type Spec struct {
	Title string
	Items []Field
}

Spec is a complete dialog request.