wizard

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Jun 3, 2026 License: MIT Imports: 26 Imported by: 0

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:

  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"
)

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 ClaudeModels

func ClaudeModels() []string

ClaudeModels returns supported Claude model values from the config field catalog.

func ClaudeReasoningEfforts added in v0.8.7

func ClaudeReasoningEfforts() []string

ClaudeReasoningEfforts returns supported Claude reasoning effort values.

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 CodexModels

func CodexModels() []string

CodexModels returns supported Codex model values from the config field catalog.

func CodexReasoningEfforts

func CodexReasoningEfforts() []string

CodexReasoningEfforts returns supported reasoning effort values from the config field catalog.

func CopilotCLIModels added in v0.9.2

func CopilotCLIModels() []string

CopilotCLIModels returns supported Copilot CLI model values from the config field catalog.

func IsTomlStateInMultiline

func IsTomlStateInMultiline(state tomlStringState) bool

IsTomlStateInMultiline returns true if the state indicates we're inside a multiline string.

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 Run

func Run(root string, ui UI, runSync syncer, pinVersion string) error

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 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

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

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
	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

	CodexApps        bool
	CodexAppsTouched 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 enabled.
	CodexDisableBrowser        bool
	CodexDisableBrowserTouched bool

	CodexStatusline        bool
	CodexStatuslineTouched bool

	CopilotCLIModel        string
	CopilotCLIModelTouched bool

	// Agent Layer workflow bundle install/refresh action (Q1).
	// InstallWorkflowBundle=true refreshes managed bundled instruction files and
	// workflow skill dirs, then creates missing conventions and memory 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

	// 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 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