setup

type ClientSyncResult struct {
	// Client is the harness display name ("Claude Code").
	Client string
	// Action is what happened for this harness.
	Action SyncAction
	// Err carries the failure when Action is SyncFailed; nil otherwise.
	// Per-harness failures never abort the whole sync (warn-and-continue,
	// matching the wizard's install posture), so the caller inspects
	// this to report or escalate.
	Err error
}

type DefaultHookBackend struct{}

type DefaultMCPBackend struct{}

type DetectedClient struct {
	Name   string
	Binary string
}

type EntryState int

type Harness struct {
	// Name is the human-readable label shown in wizard output AND
	// the identifier used for registry lookups.
	Name string

	// DetectBinary is the PATH binary whose presence marks this
	// harness as installed. Empty when the harness has no CLI
	// binary (e.g. a GUI IDE) — DetectDir is consulted instead.
	DetectBinary string

	// DetectDir is a home-relative directory whose existence marks
	// the harness as installed, for harnesses without a PATH
	// binary. Ignored when DetectBinary is non-empty.
	DetectDir string

	// RegisterMCP registers gramaton as an MCP server with this
	// harness. bin is the detected binary path (empty for
	// dir-detected harnesses). Returns alreadyRegistered=true when
	// the entry was already present (a soft success the wizard
	// reports differently). Nil means Step 3 cannot register this
	// harness programmatically.
	RegisterMCP func(ctx context.Context, bin string) (alreadyRegistered bool, err error)

	// RegisterMCPStore registers an attached named store's MCP entry
	// with this harness: entry storeMCPEntryName(store), running
	// `gramaton --store <store> mcp`. Used by the wizard's read-only
	// attach route. Nil means that route cannot register this
	// harness programmatically.
	RegisterMCPStore func(ctx context.Context, bin, storeName string) (alreadyRegistered bool, err error)

	// ManualMCPHint is the one-line manual-registration hint shown
	// when no clients are detected or the user skips Step 3.
	ManualMCPHint string

	// VerifyMCPRegistered reports whether a gramaton entry is
	// present in this harness's MCP config, for the wizard's
	// unnumbered verification pass (and registration idempotency
	// probes where the vendor CLI lacks replace-on-add). bin is the
	// detected binary path, empty for dir-detected harnesses. Nil
	// means the registration state can't be surveyed (kiro-cli:
	// list-output format unverified) and the check is skipped.
	VerifyMCPRegistered func(ctx context.Context, bin string) (bool, error)

	// InstructionsRelPath locates the agent-guidance file this
	// harness reads, as path elements relative to the user's home
	// directory. Empty means Step 4 (instructions) cannot target
	// this harness.
	InstructionsRelPath []string

	// ConfigRootEnv names an environment variable that relocates
	// this harness's config root (Codex's CODEX_HOME). When the
	// variable is set and non-empty, its value replaces the FIRST
	// element of InstructionsRelPath -- the home-relative config
	// dir -- when resolving the instructions path. Requires
	// len(InstructionsRelPath) >= 2.
	ConfigRootEnv string

	// InstructionsLayout selects the install strategy for the
	// guidance file: fenced block inside a shared user-owned file,
	// or a whole file Gramaton owns end to end.
	InstructionsLayout instructionsLayout

	// InstructionsHeader, when non-nil, returns a preamble prepended
	// verbatim to the rendered guidance body on install (Cursor's
	// SKILL.md YAML frontmatter + version stamp). Only meaningful
	// for wholeFileOwned layouts -- the fenced layout carries its
	// stamp in the fence line and never needs a header. A func, not
	// a string, because the stamp interpolates
	// templates.GuidanceVersion.
	InstructionsHeader func() string

	// Addendum is the harness-specific guidance block substituted
	// at the CLIENT_ADDENDUM marker in the base template. Empty
	// strips the marker (graceful default for harnesses with no
	// divergent guidance).
	Addendum string

	// ReconnectHint fills {{mcp_reconnect_hint}} in the guidance
	// prose: a short clause telling the user how to re-attach a
	// disconnected MCP server in this harness (e.g. "for Claude
	// Code: `/mcp` in the prompt"). Required when
	// InstructionsRelPath is set — an empty hint would leave the
	// variable unfilled in the installed file.
	ReconnectHint string

	// HookEmbedDir is the directory name under <configDir>/hooks/
	// that Materialize writes this harness's proxy scripts into
	// (matching the historical hooks/ layout at repo root). Empty
	// means no hook scripts are bundled for this harness.
	HookEmbedDir string

	// HookEvents are the lifecycle events Gramaton wires for this
	// harness. Order is stable for deterministic Materialize
	// output and test assertions.
	HookEvents []hookEventSpec

	// ProxyStyle selects which proxy-script variants Materialize
	// writes: .sh always (Claude Code bundles Git Bash on Windows),
	// .sh-or-.cmd by host OS (kiro: native Windows, no bash), or
	// both variants on every host (Codex: its hook config carries
	// command + commandWindows and picks at runtime).
	ProxyStyle proxyStyle

	// WireHooks patches this harness's hook configuration to route
	// lifecycle events at the materialized scripts, preserving
	// non-gramaton entries. Nil means Step 5 cannot wire hooks
	// automatically -- the wizard prints the script paths with
	// manual wiring guidance instead.
	WireHooks func(ctx context.Context, scriptPaths []string) (unchanged bool, err error)

	// HookConfigPathHint resolves the location WireHooks patches,
	// for wizard success copy. A func (resolved at print time)
	// because some locations depend on the environment — Codex's
	// hooks.json moves with CODEX_HOME, and printing the default
	// path while writing the relocated one would mislead. Required
	// when WireHooks is set.
	HookConfigPathHint func() string

	// ListMCPEntries enumerates the gramaton-owned MCP entry names
	// currently registered with this harness: the default "gramaton"
	// entry plus any "gramaton-<store>" attached-store entries
	// (storeMCPEntryName). Enumeration is by naming convention from
	// the harness's own config — never from a record of what init
	// wrote — so hand-added entries and stale entries for
	// since-deleted stores are caught too. bin is the detected
	// binary path (empty for dir-detected harnesses). Nil means
	// uninstall cannot enumerate this harness's MCP entries.
	ListMCPEntries func(ctx context.Context, bin string) ([]string, error)

	// RemoveMCPEntries removes the named MCP entries from this
	// harness's config in one pass. Returns the entries actually
	// removed (a prefix of the input when a mid-run failure stops
	// the loop) and, for harnesses that rewrite a config file
	// directly (Cursor), the backup written before the rewrite.
	// Required when ListMCPEntries is set.
	RemoveMCPEntries func(ctx context.Context, bin string, entries []string) (removed []string, backupPath string, err error)

	// ManualMCPRemoveHint returns the exact command (or edit) a user
	// can perform by hand to remove one MCP entry — shown when the
	// harness binary has gone missing or enumeration fails. Required
	// when ListMCPEntries is set.
	ManualMCPRemoveHint func(entry string) string

	// MCPBestEffort marks a harness whose MCP integration is
	// best-effort (kiro: registration syntax unverified, integration
	// parked). Uninstall downgrades an MCP removal failure to an
	// informative skip instead of failing the run, mirroring the
	// wizard's warn-and-continue install behavior.
	MCPBestEffort bool

	// UnwireHooks strips gramaton-owned entries from this harness's
	// hook config: the strip-only counterpart of WireHooks, sharing
	// its ownership rule (isGramatonHookCommand). scriptPaths
	// carries ownership paths so hooks materialized under a
	// relocated config dir are matched (#83). apply=false probes
	// without touching the file. Existence-driven — runs whenever
	// the config file exists, regardless of whether the harness
	// binary is still installed. Required when WireHooks is set, so
	// uninstall coverage automatically tracks hook-wiring coverage.
	UnwireHooks func(ctx context.Context, scriptPaths []string, apply bool) (changed bool, backupPath string, err error)

	// OwnsInstructionsDir marks a wholeFileOwned harness whose
	// instructions file lives in a gramaton-dedicated directory
	// (Cursor's ~/.cursor/skills/gramaton/). Uninstall removes the
	// directory after the file — but only when empty, so user-added
	// siblings survive. Meaningless for fenced layouts.
	OwnsInstructionsDir bool
}

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)

	// RegisterHooks wires the materialized scripts into the named
	// client's hook configuration; client is the hook embed-dir
	// name, same as Materialize. 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.
	RegisterHooks(ctx context.Context, client string, 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)

	// RegisterStore adds an attached named store's MCP entry to the
	// client's config: entry storeMCPEntryName(storeName) running
	// `gramaton --store <storeName> mcp`. Same result semantics as
	// Register. Used by the wizard's read-only attach route.
	RegisterStore(ctx context.Context, client DetectedClient, storeName string) (alreadyRegistered bool, err error)

	// RemoveStore removes a store's MCP entry from the client's config:
	// the default "gramaton" entry when storeName is empty, else the
	// "gramaton-<storeName>" entry. It enumerates by naming convention
	// first, so a foreign entry is never removed and an already-absent
	// entry is a no-op: removed=false, err=nil. The store-scoped
	// counterpart to Register/RegisterStore, used by SyncStoreHarness.
	RemoveStore(ctx context.Context, client DetectedClient, storeName string) (removed bool, err error)

	// ListEntries returns the gramaton-owned MCP entry names currently
	// registered with the client, enumerated by naming convention
	// ("gramaton" + "gramaton-<store>"). Used to report registration
	// state (store list) and find orphaned entries (store
	// sync-harness). Empty when the client has none.
	ListEntries(ctx context.Context, client DetectedClient) ([]string, 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 SyncAction string

type SyncReport struct {
	// Entry is the MCP entry name reconciled ("gramaton" or
	// "gramaton-<store>").
	Entry string
	// Want is the desired state that produced this report.
	Want EntryState
	// Clients holds one result per detected harness, in detection order.
	// Empty when no harnesses were detected.
	Clients []ClientSyncResult
}

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

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

type UninstallOutcome string

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

type UninstallResult struct {
	// Harness is the registry display name ("Claude Code").
	Harness string
	// Surface is the human-readable surface description, path
	// included where one exists.
	Surface string
	// Outcome classifies what happened (or would happen).
	Outcome UninstallOutcome
	// Detail carries the skip/failure reason or extra context.
	Detail string
	// Backup is the path of the backup written before a rewrite.
	Backup string
}

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()
}