wizard

package
v0.12.1 Latest Latest
Warning

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

Go to latest
Published: Jul 4, 2026 License: MIT Imports: 30 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 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 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 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

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

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