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
- 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 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" )
AgentID constants matching config keys
Variables ¶
This section is empty.
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 workflow-bundle install prompt uses 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
CLISkillCatalogEntry describes one wizard-managed CLI skill option.
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
// Agent Layer workflow bundle install action.
// InstallWorkflowBundle=true creates missing bundled workflow files without
// overwriting existing files. false is a no-op for workflow-bundle files.
InstallWorkflowBundle bool
InstallWorkflowBundleTouched 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.
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 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.