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) 


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

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.



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

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.



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

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.



69
70
71
 
# File 'lib/kward/config/settings.rb', line 69

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.



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

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.



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

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

#editor_agent_setting(config, key) ⇒ Object 



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

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) 


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

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) 


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

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) 


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

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.



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

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.



45
46
47
48
 
# File 'lib/kward/config/settings.rb', line 45

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.



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

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) 


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

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) 


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

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.



220
221
222
223
 
# File 'lib/kward/config/settings.rb', line 220

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 



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

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.



159
160
161
 
# File 'lib/kward/config/settings.rb', line 159

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

#plugin_config(plugin_id, config = read_config) ⇒ Object

Returns the private configuration namespace for one identified plugin.

Raises:

  • (ArgumentError) 


200
201
202
203
204
205
206
207
208
 
# File 'lib/kward/config/settings.rb', line 200

def plugin_config(plugin_id, config = read_config)
  plugins = config.fetch("plugins", {})
  raise ArgumentError, "Kward plugin config must be an object" unless plugins.is_a?(Hash)

  values = plugins.fetch(plugin_id.to_s, {})
  raise ArgumentError, "Kward plugin config for #{plugin_id} must be an object" unless values.is_a?(Hash)

  DeepCopy.dup(values)
end

#project_browser_icon_theme(config = read_config) ⇒ Object

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



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

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) 


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

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.



164
165
166
167
168
169
170
171
172
173
 
# File 'lib/kward/config/settings.rb', line 164

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) 


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

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.



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

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.



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

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.



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

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 



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

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

#transcript_turn_stats(config = read_config) ⇒ Object

Controls transcript presentation only; stats remain available over RPC.



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

def transcript_turn_stats(config = read_config)
  transcript = config["transcript"].is_a?(Hash) ? config["transcript"] : {}
  value = transcript["turn_stats"].to_s
  %w[off compact detailed].include?(value) ? value : "compact"
end

#transport_config(transport_id, config = read_config) ⇒ Object

Returns the private configuration namespace for one transport.



211
212
213
214
215
216
217
 
# File 'lib/kward/config/settings.rb', line 211

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.



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/kward/config/settings.rb', line 226

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.



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

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) 


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

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