setup

type DefaultHookBackend struct{}

type DefaultMCPBackend struct{}

type DetectedClient struct {
	Name   string
	Binary string
}

type HookBackend interface {
	// Materialize generates the proxy scripts for `client` into a
	// canonical on-disk location (typically
	// ~/.gramaton/hooks/<client>/) and returns the absolute paths of
	// the installed scripts. Idempotent: re-running overwrites with
	// the current proxy template so upgrades propagate when users
	// re-run the wizard.
	Materialize(client string, configDir string) (scriptPaths []string, err error)

	// RegisterClaudeHooks patches ~/.claude/settings.json to point
	// the user-scope hooks at the given script paths. Existing
	// gramaton-owned hook entries (commands under
	// ~/.gramaton/hooks/) are replaced in place; other hook entries
	// (user's own, other tools') are left untouched. Returns (true,
	// nil) when our entries were already present and unchanged,
	// (false, nil) on a successful update, (false, err) on failure.
	RegisterClaudeHooks(ctx context.Context, scriptPaths []string) (unchanged bool, err error)
}

type MCPBackend interface {
	// Detect returns the clients found on this system. Empty slice if
	// nothing was detected; never nil.
	Detect() []DetectedClient

	// Register adds Gramaton to the named client's config. Returns
	// (true, nil) if Gramaton was already registered (a soft success
	// the wizard can report differently), (false, nil) on a new
	// registration, or (false, err) on failure.
	Register(ctx context.Context, client DetectedClient) (alreadyRegistered bool, err error)
}

type Prompter interface {
	// Text reads a line, trims whitespace, and returns it. If the user
	// presses Enter without input and def is non-empty, def is
	// returned. The prompt is whatever the caller wants; Prompter does
	// not print it (the caller prints, the prompter reads). This
	// separation keeps output formatting in Writer and input reading
	// here.
	Text(def string) (string, error)

	// Secret reads a line with echo disabled (if the input is a TTY).
	// No default -- secrets are explicitly typed or skipped by pressing
	// Enter. If the stream is not a TTY (piped input), Secret falls
	// back to plain ReadString; this is acceptable because piped
	// secrets are already flowing through something that could log
	// them, and refusing to read them would break scripted --non-
	// interactive setups.
	Secret() (string, error)

	// Choice presents the options as "  [n] label" lines on the Writer
	// out-of-band (caller prints; Prompter just reads the digit). It
	// parses a 1-indexed digit, validates it's in [1, maxChoice], and
	// returns the 0-indexed result. If the user presses Enter without
	// input and def != -1, def is returned. Any other input is an
	// error the caller should surface and re-prompt.
	Choice(maxChoice, def int) (int, error)

	// YesNo reads a single [y/n] answer. defaultYes controls which
	// letter is returned on a blank Enter. Accepts y, Y, yes, YES, n,
	// N, no, NO.
	YesNo(defaultYes bool) (bool, error)
}

type ScriptedPrompter struct {
	Answers []string
	// contains filtered or unexported fields
}

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

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

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

type Writer interface {
	// StepHeader prints the "Step N of M: Title" banner that frames
	// each section. The implementation should add surrounding
	// whitespace so sections are visually separated.
	StepHeader(n, of int, title string)

	// Section prints a free-standing header used outside the
	// numbered steps (Welcome, Verification, Next steps).
	Section(title string)

	// Paragraph prints one or more lines of prose with indentation
	// matching the checkmark/warning prefix width. Used for the
	// plain-English explanations above each prompt.
	Paragraph(lines ...string)

	// Prompt prints the final inline prompt that immediately
	// precedes input. No trailing newline -- the user types after.
	Prompt(text string)

	// Check prints "  ✓ <msg>" for a completed sub-step.
	Check(msg string)

	// Warn prints "  ⚠ <msg>" for a non-fatal issue. Use when we
	// continued past a minor hiccup; use Error for fatal stops.
	Warn(msg string)

	// ErrorLine prints "  ✗ <msg>" for a fatal failure within a
	// step. Named ErrorLine (not Error) to avoid shadowing the
	// builtin error type in method receivers.
	ErrorLine(msg string)

	// Blank prints a blank line. Used to separate prose from
	// prompts within a step.
	Blank()

	// Raw prints a line verbatim, no indentation or prefix. Used for
	// feature-map tables, example commands, and the end-of-wizard
	// next-steps block where explicit layout is needed.
	Raw(line string)

	// ProgressStart signals the beginning of a long operation (like
	// an embedding-model download). The implementation can choose to
	// show a spinner, a byte counter, or nothing; the wizard only
	// cares that it's told when the op starts and ends.
	ProgressStart(label string)

	// ProgressUpdate reports incremental progress (bytes or count).
	// Total may be zero if the total isn't known up front.
	ProgressUpdate(done, total int64)

	// ProgressEnd closes out the progress display.
	ProgressEnd()
}