Skip to content
Kward Search API index

Module: Kward::ConfigFiles::Settings

Extended by:
Settings
Included in:
Kward::ConfigFiles, Settings
Defined in:
lib/kward/config/settings.rb

Instance Method Summary collapse

Instance Method Details

#composer_busy_help?(config = read_config) ⇒ Boolean

Returns whether the composer should show busy-state keyboard help.

Returns:

  • (Boolean) 


25
26
27
28
 
# File 'lib/kward/config/settings.rb', line 25

def composer_busy_help?(config = read_config)
  composer = config["composer"].is_a?(Hash) ? config["composer"] : {}
  composer["busy_help"] != false
end

#composer_tab_keybindings(config = read_config) ⇒ Object

Returns the configured tab keybinding family, or auto when unset/invalid.



31
32
33
34
35
 
# File 'lib/kward/config/settings.rb', line 31

def composer_tab_keybindings(config = read_config)
  composer = config["composer"].is_a?(Hash) ? config["composer"] : {}
  value = composer["tab_keybindings"].to_s.downcase
  %w[auto ctrl alt].include?(value) ? value : "auto"
end

#diff_view(config = read_config) ⇒ Object

Returns the integrated diff viewer display mode.



140
141
142
143
 
# File 'lib/kward/config/settings.rb', line 140

def diff_view(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  DiffViewMode.normalize(editor["diff_view"])
end

#editor_agent_model(config = read_config) ⇒ Object

Returns the optional model override for editor-agent turns.



62
63
64
 
# File 'lib/kward/config/settings.rb', line 62

def editor_agent_model(config = read_config)
  editor_agent_setting(config, "model")
end

#editor_agent_provider(config = read_config) ⇒ Object

Returns the optional provider override for editor-agent turns.



54
55
56
57
58
59
 
# File 'lib/kward/config/settings.rb', line 54

def editor_agent_provider(config = read_config)
  value = ENV["KWARD_EDITOR_PROVIDER"].to_s.strip
  return value unless value.empty?

  editor_agent_setting(config, "provider")
end

#editor_agent_reasoning_effort(config = read_config) ⇒ Object

Returns the optional reasoning-effort override for editor-agent turns.



67
68
69
 
# File 'lib/kward/config/settings.rb', line 67

def editor_agent_reasoning_effort(config = read_config)
  editor_agent_setting(config, "reasoning_effort")
end

#editor_agent_setting(config, key) ⇒ Object 



95
96
97
98
99
100
 
# File 'lib/kward/config/settings.rb', line 95

def editor_agent_setting(config, key)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  agent = editor["agent"].is_a?(Hash) ? editor["agent"] : {}
  value = agent[key].to_s.strip
  value.empty? ? nil : value
end

#editor_auto_close_pairs?(config = read_config) ⇒ Boolean

Returns whether the built-in TUI editor should auto-close typed pairs.

Returns:

  • (Boolean) 


116
117
118
119
 
# File 'lib/kward/config/settings.rb', line 116

def editor_auto_close_pairs?(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  editor["auto_close_pairs"] != false
end

#editor_auto_indent?(config = read_config) ⇒ Boolean

Returns whether the built-in TUI editor should auto-indent new lines.

Returns:

  • (Boolean) 


110
111
112
113
 
# File 'lib/kward/config/settings.rb', line 110

def editor_auto_indent?(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  editor["auto_indent"] != false
end

#editor_bar_cursor?(config = read_config) ⇒ Boolean

Returns whether editable built-in TUI editor buffers should use a bar cursor.

Returns:

  • (Boolean) 


128
129
130
131
 
# File 'lib/kward/config/settings.rb', line 128

def editor_bar_cursor?(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  editor["bar_cursor"] != false
end

#editor_line_numbers(config = read_config) ⇒ Object

Returns the built-in TUI editor line-number display mode.



134
135
136
137
 
# File 'lib/kward/config/settings.rb', line 134

def editor_line_numbers(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  EditorMode.normalize_line_numbers(editor["line_numbers"])
end

#editor_mode(config = read_config) ⇒ Object

Returns the built-in TUI editor keymap mode.



38
39
40
41
 
# File 'lib/kward/config/settings.rb', line 38

def editor_mode(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  EditorMode.normalize(editor["mode"])
end

#editor_runners(config = read_config) ⇒ Object

Returns configured editor runner definitions, or an empty map.

Runner defaults are resolved by the editor runner at execution time so the generated config remains portable across machines.



47
48
49
50
51
 
# File 'lib/kward/config/settings.rb', line 47

def editor_runners(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  runners = editor["runners"]
  runners.is_a?(Hash) ? runners : {}
end

#editor_soft_wrap?(config = read_config) ⇒ Boolean

Returns whether the built-in TUI editor should soft-wrap long lines.

Returns:

  • (Boolean) 


122
123
124
125
 
# File 'lib/kward/config/settings.rb', line 122

def editor_soft_wrap?(config = read_config)
  editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
  editor["soft_wrap"] != false
end

#enforce_workspace_agents_file?(config = read_config) ⇒ Boolean

Returns whether workspace AGENTS.md contents should be injected directly instead of a compact read-when-relevant instruction.

Returns:

  • (Boolean) 


182
183
184
 
# File 'lib/kward/config/settings.rb', line 182

def enforce_workspace_agents_file?(config = read_config)
  config["enforce_workspace_agents_file"] == true
end

#mcp_servers(config = read_config) ⇒ Object

Returns configured MCP stdio servers, or an empty config when absent.



202
203
204
205
 
# File 'lib/kward/config/settings.rb', line 202

def mcp_servers(config = read_config)
  value = config["mcpServers"] || config.dig("mcp", "servers")
  value.is_a?(Hash) ? value : {}
end

#overlay_settings(config = read_config) ⇒ Object 



7
8
9
10
11
12
13
14
15
 
# File 'lib/kward/config/settings.rb', line 7

def overlay_settings(config = read_config)
  overlay = config["overlay"].is_a?(Hash) ? config["overlay"] : {}
  settings = DEFAULT_OVERLAY_SETTINGS.dup
  alignment = overlay["alignment"].to_s
  width = overlay["width"].to_s
  settings["alignment"] = alignment if OVERLAY_ALIGNMENTS.include?(alignment)
  settings["width"] = width if OVERLAY_WIDTHS.include?(width)
  settings
end

#permission_policy(config = read_config) ⇒ Object

Builds the opt-in model-tool permission policy from persisted configuration.



152
153
154
 
# File 'lib/kward/config/settings.rb', line 152

def permission_policy(config = read_config)
  Permissions::Policy.from_config(config)
end

#project_browser_icon_theme(config = read_config) ⇒ Object

Returns the project browser icon theme, or off when unset or invalid.



18
19
20
21
22
 
# File 'lib/kward/config/settings.rb', line 18

def project_browser_icon_theme(config = read_config)
  browser = config["project_browser"].is_a?(Hash) ? config["project_browser"] : {}
  theme = browser["icons"].to_s
  PROJECT_BROWSER_ICON_THEMES.include?(theme) ? theme : "off"
end

#project_skills_trusted?(config = read_config) ⇒ Boolean

Returns whether project-level Agent Skills should be loaded from the workspace.

Returns:

  • (Boolean) 


169
170
171
172
 
# File 'lib/kward/config/settings.rb', line 169

def project_skills_trusted?(config = read_config)
  skills = config["skills"].is_a?(Hash) ? config["skills"] : {}
  skills["trust_project"] == true
end

#sandbox_policy(workspace_root, config = read_config) ⇒ Object

Builds the user-controlled command sandbox policy for a workspace.



157
158
159
160
161
162
163
164
165
166
 
# File 'lib/kward/config/settings.rb', line 157

def sandbox_policy(workspace_root, config = read_config)
  sandbox = config["sandbox"].is_a?(Hash) ? config["sandbox"] : {}
  Sandbox::Policy.new(
    mode: sandbox.fetch("mode", "off"),
    network: sandbox.fetch("network", "deny"),
    workspace_root: workspace_root,
    writable_roots: sandbox.fetch("writable_roots", []),
    protect_git_metadata: sandbox.fetch("protect_git_metadata", true)
  )
end

#session_auto_resume_enabled?(config = read_config) ⇒ Boolean

Returns whether new frontends should resume the last active session automatically.

Returns:

  • (Boolean) 


175
176
177
178
 
# File 'lib/kward/config/settings.rb', line 175

def session_auto_resume_enabled?(config = read_config)
  sessions = config["sessions"].is_a?(Hash) ? config["sessions"] : {}
  sessions["auto_resume"] == true
end

#shell_agent_model(config = read_config) ⇒ Object

Returns the shell-agent model override, preferring the environment.



80
81
82
83
84
85
 
# File 'lib/kward/config/settings.rb', line 80

def shell_agent_model(config = read_config)
  value = ENV["KWSH_MODE"].to_s.strip
  return value unless value.empty?

  shell_agent_setting(config, "model")
end

#shell_agent_provider(config = read_config) ⇒ Object

Returns the shell-agent provider override, preferring the environment.



72
73
74
75
76
77
 
# File 'lib/kward/config/settings.rb', line 72

def shell_agent_provider(config = read_config)
  value = ENV["KWSH_PROVIDER"].to_s.strip
  return value unless value.empty?

  shell_agent_setting(config, "provider")
end

#shell_agent_reasoning_effort(config = read_config) ⇒ Object

Returns the shell-agent reasoning-effort override, preferring the environment.



88
89
90
91
92
93
 
# File 'lib/kward/config/settings.rb', line 88

def shell_agent_reasoning_effort(config = read_config)
  value = ENV["KWSH_REASONING"].to_s.strip
  return value unless value.empty?

  shell_agent_setting(config, "reasoning_effort")
end

#shell_agent_setting(config, key) ⇒ Object 



102
103
104
105
106
107
 
# File 'lib/kward/config/settings.rb', line 102

def shell_agent_setting(config, key)
  shell = config["shell"].is_a?(Hash) ? config["shell"] : {}
  agent = shell["agent"].is_a?(Hash) ? shell["agent"] : {}
  value = agent[key].to_s.strip
  value.empty? ? nil : value
end

#transport_config(transport_id, config = read_config) ⇒ Object

Returns the private configuration namespace for one transport.



193
194
195
196
197
198
199
 
# File 'lib/kward/config/settings.rb', line 193

def transport_config(transport_id, config = read_config)
  transports = config["transports"]
  return {} unless transports.is_a?(Hash)

  values = transports[transport_id.to_s]
  values.is_a?(Hash) ? DeepCopy.dup(values) : {}
end

#update_overlay_settings(values) ⇒ Object

Validates and persists terminal overlay settings.



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/kward/config/settings.rb', line 208

def update_overlay_settings(values)
  raise "Overlay settings must be an object" unless values.is_a?(Hash)

  config = read_config
  overlay = overlay_settings(config)
  values.each do |key, value|
    key = key.to_s
    value = value.to_s
    case key
    when "alignment"
      raise "Overlay alignment must be left, center, or right" unless OVERLAY_ALIGNMENTS.include?(value)
    when "width"
      raise "Overlay width must be capped or maximum" unless OVERLAY_WIDTHS.include?(value)
    else
      raise "Unknown overlay setting: #{key}"
    end
    overlay[key] = value
  end
  config["overlay"] = overlay
  write_config(config)
  overlay_settings(config)
end

#web_search_config(config = read_config) ⇒ Object

Returns the nested web-search config object, or an empty config when absent.



187
188
189
190
 
# File 'lib/kward/config/settings.rb', line 187

def web_search_config(config = read_config)
  value = config["web_search"]
  value.is_a?(Hash) ? value : {}
end

#workspace_guardrails_enabled?(config = read_config) ⇒ Boolean

Returns whether file tools must stay inside the active workspace root.

Returns:

  • (Boolean) 


146
147
148
149
 
# File 'lib/kward/config/settings.rb', line 146

def workspace_guardrails_enabled?(config = read_config)
  tools = config["tools"].is_a?(Hash) ? config["tools"] : {}
  tools["workspace_guardrails"] != false
end