Documentation
¶
Overview ¶
Package wizard implements the interactive setup wizard for Agent Layer.
TOML Parsing Strategy ¶
This package uses custom line-based TOML parsing instead of the go-toml library's tree manipulation for config updates. This is intentional for several reasons:
Comment preservation: go-toml's ToTomlString() loses inline comments and rearranges leading comments. Users expect their config formatting to be preserved.
Deterministic output: The wizard rewrites config.toml in preferred section order (Decision wizard-order-policy). Custom parsing lets us control exact output ordering.
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
- Variables
- func ApprovalModeFieldOptions() []config.FieldOption
- func CleanupBackups(root string) ([]string, error)
- func PatchConfig(content string, choices *Choices) (string, error)
- func Run(root string, ui UI, runSync syncer, pinVersion string) error
- func RunAfterFreshInitWithWriter(root string, ui UI, runSync syncer, pinVersion string, out io.Writer) error
- func RunProfile(root string, runSync syncer, pinVersion string, profilePath string, apply bool, ...) error
- func RunWithWriter(root string, ui UI, runSync syncer, pinVersion string, out io.Writer) error
- func ScanTomlLineForComment(line string, state tomlStringState) (commentPos int, nextState tomlStringState)
- func SupportedAgents() []string
- type CLISkillCatalogEntry
- type Choices
- type DefaultMCPServer
- type HuhUI
- func (ui *HuhUI) Confirm(title string, value *bool) error
- func (ui *HuhUI) Input(title string, value *string) error
- func (ui *HuhUI) MultiSelect(title string, options []string, selected *[]string) error
- func (ui *HuhUI) Note(title string, body string) error
- func (ui *HuhUI) SecretInput(title string, value *string) error
- func (ui *HuhUI) Select(title string, options []string, current *string) error
- type InstructionSet
- type ScriptedUI
- func (ui *ScriptedUI) AssertComplete() error
- func (ui *ScriptedUI) Confirm(title string, value *bool) error
- func (ui *ScriptedUI) Input(title string, value *string) error
- func (ui *ScriptedUI) MultiSelect(title string, options []string, selected *[]string) error
- func (ui *ScriptedUI) Note(string, string) error
- func (ui *ScriptedUI) SecretInput(title string, value *string) error
- func (ui *ScriptedUI) Select(title string, options []string, current *string) error
- type UI
- type WarningDefaults
Constants ¶
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 ¶
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
CleanupBackups removes wizard backup files and returns removed paths relative to repo root.
func PatchConfig ¶
PatchConfig applies wizard choices to TOML config content. content is the current config; choices holds selections; returns updated content or error.
func Run ¶
Run starts the interactive wizard. pinVersion is written to .agent-layer/al.version when install is needed.
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.
func RunWithWriter ¶ added in v0.8.0
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 ScanTomlLineForComment ¶
func ScanTomlLineForComment(line string, state tomlStringState) (commentPos int, nextState tomlStringState)
ScanTomlLineForComment scans a TOML line and returns the position of any inline comment (or -1 if none) along with the next parser state for multiline string tracking. state is the current parser state from the previous line; line is the TOML line to scan.
func SupportedAgents ¶
func SupportedAgents() []string
SupportedAgents returns the agent IDs the wizard can configure. Order matches the config field catalog registration order.
Types ¶
type CLISkillCatalogEntry ¶ added in v0.11.0
type CLISkillCatalogEntry struct {
ID string
Name string
OwnershipMarker string `toml:"ownership_marker"`
Members []string `toml:"members"`
}
CLISkillCatalogEntry describes one wizard-managed CLI skill option. A non-empty Members list is a grouped entry: the catalog id is the checkbox identity only, and each member is a destination directory copied from embedded skills/<member>/ rather than skills-catalog/<id>/.
type Choices ¶
type Choices struct {
// Approvals
ApprovalMode string
ApprovalModeTouched bool
// Agents
EnabledAgents map[string]bool
EnabledAgentsTouched bool
// Models
AntigravityModel string
AntigravityModelTouched bool
ClaudeModel string
ClaudeModelTouched bool
ClaudeReasoning string
ClaudeReasoningTouched bool
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
CodexModel string
CodexModelTouched bool
CodexReasoning string
CodexReasoningTouched 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
CopilotCLIModel string
CopilotCLIModelTouched bool
GrokModel string
GrokModelTouched bool
GrokReasoning string
GrokReasoningTouched bool
MuseModel string
MuseModelTouched bool
MuseReasoning string
MuseReasoningTouched 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 []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.
type DefaultMCPServer ¶
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) MultiSelect ¶
MultiSelect renders a multi-choice prompt.
func (*HuhUI) SecretInput ¶
SecretInput renders a masked input prompt for secrets.
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.
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.