Help us shape the future of Go! Take the 2026 Go Developer Survey

wizard

package
v0.24.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package wizard implements the interactive setup wizard for Agent Layer.

TOML Parsing Strategy

This package uses the line-based TOML parser and patcher in internal/tomlpatch instead of the go-toml library's tree manipulation for config updates. This is intentional for several reasons:

  1. Comment preservation: go-toml's ToTomlString() loses inline comments and rearranges leading comments. Users expect their config formatting to be preserved.

  2. Deterministic output: The wizard rewrites config.toml in preferred section order (Decision wizard-order-policy). Custom parsing lets us control exact output ordering.

  3. Key positioning: When clearing optional keys (like model=""), we convert them to commented lines rather than deleting them, preserving the template structure.

The go-toml/v2 library is still used for syntax validation before processing.

Index

Constants

View Source
const (
	AgentAntigravity  = "antigravity"
	AgentClaude       = "claude"
	AgentClaudeVSCode = "claude_vscode"
	AgentCodex        = "codex"
	AgentVSCode       = "vscode"
	AgentCopilotCLI   = "copilot_cli"
	AgentGrok         = "grok"
	AgentMuse         = "muse"
)

AgentID constants matching config keys

Variables

View Source
var ErrBack = errors.New("wizard back requested")

ErrBack indicates that the user pressed Esc to return from a wizard form.

Functions

func ApprovalModeFieldOptions added in v0.8.2

func ApprovalModeFieldOptions() []config.FieldOption

ApprovalModeFieldOptions returns approval mode options from the config field catalog. Panics if the approvals.mode field is not in the catalog (programming error).

func CleanupBackups added in v0.8.0

func CleanupBackups(root string) ([]string, error)

CleanupBackups removes wizard backup files and returns removed paths relative to repo root.

func MigrateBackups added in v0.23.1

func MigrateBackups(root string) error

MigrateBackups relocates legacy wizard backups without overwriting existing recovery files. Copying exclusively works across filesystems; the source is removed only after the destination has been written, synced, and closed.

func PatchConfig

func PatchConfig(content string, choices *Choices) (string, error)

PatchConfig applies wizard choices to TOML config content. content is the current config; choices holds selections; returns updated content or error.

func RunAfterFreshInitWithWriter added in v0.11.0

func RunAfterFreshInitWithWriter(root string, ui UI, runSync syncer, pinVersion string, out io.Writer) error

RunAfterFreshInitWithWriter runs the wizard immediately after `al init` created the bare operational layout. Provider statusline options and the instruction-set prompt use fresh-setup defaults in this path.

func RunProfile added in v0.8.0

func RunProfile(root string, runSync syncer, pinVersion string, profilePath string, apply bool, out io.Writer) error

RunProfile applies a non-interactive wizard profile from a TOML config file. root is the repo root; runSync executes sync after writes; pinVersion is used when install is required. profilePath points to a TOML file; apply controls whether writes are performed or preview-only output is shown. The profile is validated before any write, and a missing install is performed only when apply is true.

func RunWithWriter added in v0.8.0

func RunWithWriter(root string, ui UI, runSync syncer, pinVersion string, out io.Writer) error

RunWithWriter starts the interactive wizard and writes user-facing output to out. pinVersion is written to .agent-layer/al.version when install is needed.

func SupportedAgents

func SupportedAgents() []string

SupportedAgents returns the agent IDs the wizard can configure. Order matches the config field catalog registration order.

Types

type AgentModelChoice added in v0.24.0

type AgentModelChoice struct {
	Model            string
	ModelTouched     bool
	Reasoning        string
	ReasoningTouched bool
}

AgentModelChoice is the wizard's model and reasoning-effort selection for one agent. Touched records that the user answered the matching prompt.

type Choices

type Choices struct {
	// Approvals
	ApprovalMode        string
	ApprovalModeTouched bool

	// Agents
	EnabledAgents        map[string]bool
	EnabledAgentsTouched bool

	// Models
	AgentModels map[string]AgentModelChoice // keyed by agent ID

	ClaudeLocalConfigDir        bool
	ClaudeLocalConfigDirTouched bool

	// Claude "disable" toggles (disable-intent: true = disable the feature).
	// Each lands in .claude/settings.json via agent_specific passthrough. A key
	// is written only when the toggle is on; leaving it off keeps the client's
	// native default. Gated on Claude || ClaudeVSCode (both write settings.json).
	ClaudeDisableIDEReading        bool // CLAUDE_CODE_AUTO_CONNECT_IDE = "false"
	ClaudeDisableIDEReadingTouched bool

	ClaudeDisableMemory        bool // autoMemoryEnabled = false
	ClaudeDisableMemoryTouched bool

	ClaudeDisableConnectors        bool // ENABLE_CLAUDEAI_MCP_SERVERS = "false"
	ClaudeDisableConnectorsTouched bool

	ClaudeDisableQuestionTool        bool // disable_question_tool flag; sync injects deny + PreToolUse hook
	ClaudeDisableQuestionToolTouched bool

	ClaudeStatusline        bool
	ClaudeStatuslineTouched bool

	CodexLocalConfigDir        bool
	CodexLocalConfigDirTouched bool

	CodexApps        bool
	CodexAppsTouched bool

	CodexPlugins        bool
	CodexPluginsTouched bool

	// CodexDisableBrowser disables Codex browser/computer-use features
	// (browser_use/in_app_browser/computer_use = false). Disable-intent like the
	// Claude toggles above; gated on Codex CLI or Codex VS Code enabled.
	CodexDisableBrowser        bool
	CodexDisableBrowserTouched bool

	CodexStatusline        bool
	CodexStatuslineTouched bool

	// GrokDisableMemory is disable-intent: true writes disable_memory = true.
	GrokDisableMemory        bool
	GrokDisableMemoryTouched bool

	// InstructionSet is the always-on instruction choice: none, rules, or
	// rules_and_memory. Touched is set when the user answers the instruction
	// step. false leaves existing instruction and memory files unchanged.
	InstructionSet        InstructionSet
	InstructionSetTouched bool

	// Catalog CLI skills (Q2).
	// EnabledCLISkills is keyed by catalog entry id. Apply copies the matching
	// embedded skill directory into `.agent-layer/skills/<id>/` for ids set true
	// and removes the on-disk directory for ids set false. Grouped entries
	// (Members) install or remove each member directory instead.
	EnabledCLISkills map[string]bool
	CLISkillsCatalog []templates.CLISkillCatalogEntry

	// Git tracking for Agent Layer-owned folders. The managed source of truth is
	// `.agent-layer/gitignore.block`; these fields are derived from that file at
	// wizard startup and written back to it before sync.
	TrackAgentLayerDir     bool
	TrackDocsAgentLayerDir bool
	GitTrackingTouched     bool

	// MCP
	EnabledMCPServers        map[string]bool
	EnabledMCPServersTouched bool
	DisabledMCPServers       map[string]bool
	DefaultMCPServers        []DefaultMCPServer

	// Custom (non-catalog) MCP servers found in config.toml.
	// CustomMCPServers holds their ids in config order; the wizard surfaces them
	// for keep/disable separately from catalog defaults. CustomMCPServersEnabled
	// records the per-id decision: true keeps the server enabled, false sets
	// enabled = false while preserving the entry (a custom server has no catalog
	// template to restore from, so it is never deleted). CustomMCPServersTouched
	// is true once the user has answered the custom-server step.
	CustomMCPServers        []string
	CustomMCPServersEnabled map[string]bool
	CustomMCPServersTouched bool

	// Secrets (Env vars)
	Secrets map[string]string

	// Warnings
	WarningsEnabled                bool
	WarningsEnabledTouched         bool
	InstructionTokenThreshold      int
	MCPServerThreshold             int
	MCPToolsTotalThreshold         int
	MCPServerToolsThreshold        int
	MCPSchemaTokensTotalThreshold  int
	MCPSchemaTokensServerThreshold int
}

Choices tracks user selections in the wizard.

func NewChoices

func NewChoices() *Choices

NewChoices returns a Choices struct initialized with defaults.

func (*Choices) Clone added in v0.8.7

func (c *Choices) Clone() *Choices

Clone returns a deep copy of the choices state for step-level rollback.

type DefaultMCPServer

type DefaultMCPServer struct {
	ID          string
	RequiredEnv []string
}

DefaultMCPServer describes a default MCP server and its required env vars.

type HuhUI

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

HuhUI implements UI using charmbracelet/huh.

func NewHuhUI

func NewHuhUI() *HuhUI

NewHuhUI creates a new HuhUI using the default terminal check. The default implementation uses terminal.IsInteractive().

func (*HuhUI) Confirm

func (ui *HuhUI) Confirm(title string, value *bool) error

Confirm renders a yes/no prompt.

func (*HuhUI) Input

func (ui *HuhUI) Input(title string, value *string) error

Input renders a plain text input prompt.

func (*HuhUI) MultiSelect

func (ui *HuhUI) MultiSelect(title string, options []string, selected *[]string) error

MultiSelect renders a multi-choice prompt.

func (*HuhUI) Note

func (ui *HuhUI) Note(title string, body string) error

Note renders an informational note screen.

func (*HuhUI) SecretInput

func (ui *HuhUI) SecretInput(title string, value *string) error

SecretInput renders a masked input prompt for secrets.

func (*HuhUI) Select

func (ui *HuhUI) Select(title string, options []string, current *string) error

Select renders a single-choice prompt.

type InstructionSet added in v0.17.3

type InstructionSet string

InstructionSet is the wizard's always-on instruction choice.

const (
	InstructionSetNone           InstructionSet = "none"
	InstructionSetRules          InstructionSet = "rules"
	InstructionSetRulesAndMemory InstructionSet = "rules_and_memory"
)

Canonical instruction-set values. None leaves files unchanged; Rules seeds 00_rules.md; RulesAndMemory also seeds 01_memory.md and memory docs.

type ScriptedUI added in v0.11.0

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

ScriptedUI implements UI from a strict JSON answer file.

func NewScriptedUIFromFile added in v0.11.0

func NewScriptedUIFromFile(path string) (*ScriptedUI, error)

NewScriptedUIFromFile loads a scripted wizard UI from a JSON answer file.

func (*ScriptedUI) AssertComplete added in v0.11.0

func (ui *ScriptedUI) AssertComplete() error

AssertComplete returns an error when the answer file contains unused prompts.

func (*ScriptedUI) Confirm added in v0.11.0

func (ui *ScriptedUI) Confirm(title string, value *bool) error

Confirm applies a scripted yes/no answer for title.

func (*ScriptedUI) Input added in v0.11.0

func (ui *ScriptedUI) Input(title string, value *string) error

Input applies a scripted text answer for title.

func (*ScriptedUI) MultiSelect added in v0.11.0

func (ui *ScriptedUI) MultiSelect(title string, options []string, selected *[]string) error

MultiSelect applies a scripted multi-choice answer for title.

func (*ScriptedUI) Note added in v0.11.0

func (ui *ScriptedUI) Note(string, string) error

Note accepts informational wizard screens without requiring scripted answers.

func (*ScriptedUI) SecretInput added in v0.11.0

func (ui *ScriptedUI) SecretInput(title string, value *string) error

SecretInput applies a scripted secret answer for title.

func (*ScriptedUI) Select added in v0.11.0

func (ui *ScriptedUI) Select(title string, options []string, current *string) error

Select applies a scripted single-choice answer for title.

type UI

type UI interface {
	Select(title string, options []string, current *string) error
	MultiSelect(title string, options []string, selected *[]string) error
	Confirm(title string, value *bool) error
	Input(title string, value *string) error
	SecretInput(title string, value *string) error
	Note(title string, body string) error
}

UI defines the interaction methods.

type WarningDefaults

type WarningDefaults struct {
	InstructionTokenThreshold      int
	MCPServerThreshold             int
	MCPToolsTotalThreshold         int
	MCPServerToolsThreshold        int
	MCPSchemaTokensTotalThreshold  int
	MCPSchemaTokensServerThreshold int
}

WarningDefaults holds wizard defaults sourced from the template config.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL