kward 0.84.0 → 0.86.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +164 -0
  3. data/CONTRIBUTING.md +1 -1
  4. data/Gemfile.lock +6 -2
  5. data/README.md +5 -5
  6. data/Rakefile +3 -0
  7. data/doc/agent-tools.md +24 -1
  8. data/doc/api.md +20 -2
  9. data/doc/composer.md +5 -4
  10. data/doc/configuration.md +86 -14
  11. data/doc/extensibility.md +4 -1
  12. data/doc/getting-started.md +3 -3
  13. data/doc/git.md +4 -2
  14. data/doc/memory.md +1 -1
  15. data/doc/pan.md +6 -0
  16. data/doc/permissions.md +4 -4
  17. data/doc/plugins.md +504 -20
  18. data/doc/providers.md +10 -4
  19. data/doc/rpc.md +279 -23
  20. data/doc/sandboxing.md +11 -5
  21. data/doc/security.md +7 -1
  22. data/doc/session-management.md +41 -5
  23. data/doc/shell.md +643 -27
  24. data/doc/tabs.md +8 -3
  25. data/doc/transports.md +15 -0
  26. data/doc/troubleshooting.md +1 -1
  27. data/doc/usage.md +25 -12
  28. data/doc/workspace-tools.md +9 -0
  29. data/examples/plugins/openrouter_proxy/README.md +103 -0
  30. data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
  31. data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
  32. data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
  33. data/examples/plugins/openrouter_proxy/server.rb +186 -0
  34. data/examples/plugins/space_invaders.rb +1 -2
  35. data/examples/plugins/stardate_footer.rb +2 -2
  36. data/examples/plugins/telegram/plugin.rb +1 -1
  37. data/exe/kward +2 -2
  38. data/exe/kwsh +7 -0
  39. data/kward.gemspec +3 -1
  40. data/lib/kward/agent.rb +66 -19
  41. data/lib/kward/cli/commands.rb +41 -11
  42. data/lib/kward/cli/compaction.rb +9 -3
  43. data/lib/kward/cli/interactive_turn.rb +10 -0
  44. data/lib/kward/cli/plugins.rb +85 -12
  45. data/lib/kward/cli/prompt_interface.rb +29 -6
  46. data/lib/kward/cli/rendering.rb +24 -28
  47. data/lib/kward/cli/runtime_helpers.rb +168 -56
  48. data/lib/kward/cli/sessions.rb +9 -5
  49. data/lib/kward/cli/settings/menus.rb +745 -0
  50. data/lib/kward/cli/settings/model.rb +316 -0
  51. data/lib/kward/cli/settings.rb +6 -1055
  52. data/lib/kward/cli/slash_commands.rb +45 -4
  53. data/lib/kward/cli/tabs.rb +257 -44
  54. data/lib/kward/cli/tool_summaries.rb +2 -0
  55. data/lib/kward/{cli_transcript_formatter.rb → cli/transcript_formatter.rb} +6 -13
  56. data/lib/kward/cli/worktrees.rb +66 -2
  57. data/lib/kward/cli.rb +82 -31
  58. data/lib/kward/compactor.rb +18 -7
  59. data/lib/kward/config/core.rb +400 -0
  60. data/lib/kward/config/extensions.rb +99 -0
  61. data/lib/kward/config/paths.rb +11 -0
  62. data/lib/kward/config/prompts.rb +313 -0
  63. data/lib/kward/config/settings.rb +257 -0
  64. data/lib/kward/config_files.rb +14 -1008
  65. data/lib/kward/conversation.rb +41 -2
  66. data/lib/kward/entrypoint.rb +14 -0
  67. data/lib/kward/events.rb +2 -0
  68. data/lib/kward/generated_images.rb +237 -0
  69. data/lib/kward/image_attachments.rb +1 -1
  70. data/lib/kward/model/catalog.rb +6 -3
  71. data/lib/kward/model/client.rb +107 -38
  72. data/lib/kward/model/codex_images.rb +83 -0
  73. data/lib/kward/model/copilot_models.rb +10 -6
  74. data/lib/kward/model/model_info.rb +42 -7
  75. data/lib/kward/{openrouter_model_cache.rb → model/openrouter_model_cache.rb} +7 -5
  76. data/lib/kward/model/payloads.rb +18 -8
  77. data/lib/kward/model/sources.rb +3 -1
  78. data/lib/kward/model/stream_parser.rb +4 -7
  79. data/lib/kward/model/typesafe_client.rb +78 -0
  80. data/lib/kward/pan/index.html.erb +8 -1
  81. data/lib/kward/pan/server.rb +23 -8
  82. data/lib/kward/permissions/policy.rb +6 -2
  83. data/lib/kward/plugin_registry.rb +2 -659
  84. data/lib/kward/plugins/actions.rb +453 -0
  85. data/lib/kward/plugins/chat_contract.rb +121 -0
  86. data/lib/kward/{plugin_chat_runtime.rb → plugins/chat_runtime.rb} +62 -18
  87. data/lib/kward/plugins/codex_responses.rb +73 -0
  88. data/lib/kward/plugins/host.rb +248 -0
  89. data/lib/kward/plugins/http_server.rb +83 -0
  90. data/lib/kward/plugins/registry.rb +1229 -0
  91. data/lib/kward/plugins/resources.rb +206 -0
  92. data/lib/kward/plugins/turn_request.rb +36 -0
  93. data/lib/kward/plugins/ui.rb +219 -0
  94. data/lib/kward/prompt_interface/composer_controller.rb +0 -1
  95. data/lib/kward/prompt_interface/composer_renderer.rb +160 -73
  96. data/lib/kward/prompt_interface/composer_state.rb +1 -1
  97. data/lib/kward/prompt_interface/editor/controller.rb +2 -2
  98. data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
  99. data/lib/kward/prompt_interface/editor/runner.rb +1 -1
  100. data/lib/kward/prompt_interface/editor/state.rb +1 -1
  101. data/lib/kward/prompt_interface/file_overlay.rb +3 -3
  102. data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
  103. data/lib/kward/prompt_interface/git_prompt.rb +18 -11
  104. data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
  105. data/lib/kward/prompt_interface/interactive/state.rb +18 -20
  106. data/lib/kward/prompt_interface/key_handler.rb +108 -25
  107. data/lib/kward/prompt_interface/layout.rb +11 -1
  108. data/lib/kward/prompt_interface/overlay_renderer.rb +26 -9
  109. data/lib/kward/prompt_interface/plugin_ui_requests.rb +82 -0
  110. data/lib/kward/prompt_interface/project_browser.rb +27 -54
  111. data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
  112. data/lib/kward/prompt_interface/question_prompt.rb +19 -28
  113. data/lib/kward/prompt_interface/runtime_state.rb +37 -10
  114. data/lib/kward/prompt_interface/screen.rb +30 -20
  115. data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
  116. data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
  117. data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
  118. data/lib/kward/prompt_interface.rb +149 -30
  119. data/lib/kward/prompts/commands.rb +2 -1
  120. data/lib/kward/prompts.rb +7 -1
  121. data/lib/kward/{adaptive_pty_output_sink.rb → pty/adaptive_output_sink.rb} +39 -5
  122. data/lib/kward/{interactive_pty_runner.rb → pty/interactive_runner.rb} +22 -30
  123. data/lib/kward/{local_command_runner.rb → pty/local_command_runner.rb} +1 -1
  124. data/lib/kward/{local_pty_command_runner.rb → pty/local_pty_runner.rb} +3 -9
  125. data/lib/kward/{pty_output_sink.rb → pty/output_sink.rb} +9 -4
  126. data/lib/kward/pty/transcript_normalizer.rb +137 -0
  127. data/lib/kward/rpc/config_manager.rb +3 -0
  128. data/lib/kward/rpc/plugin_chat_manager.rb +30 -10
  129. data/lib/kward/rpc/prompt_bridge.rb +25 -0
  130. data/lib/kward/rpc/server.rb +118 -17
  131. data/lib/kward/rpc/session_manager.rb +208 -60
  132. data/lib/kward/rpc/session_tree_rows.rb +2 -2
  133. data/lib/kward/rpc/tool_metadata.rb +1 -1
  134. data/lib/kward/rpc/transcript_normalizer.rb +11 -7
  135. data/lib/kward/sandbox/command_runner.rb +1 -1
  136. data/lib/kward/{session_catalog.rb → sessions/catalog.rb} +1 -1
  137. data/lib/kward/{session_store.rb → sessions/store.rb} +39 -12
  138. data/lib/kward/{session_tree_nodes.rb → sessions/tree_nodes.rb} +3 -3
  139. data/lib/kward/{session_tree_renderer.rb → sessions/tree_renderer.rb} +4 -4
  140. data/lib/kward/{session_tree_tool_display.rb → sessions/tree_tool_display.rb} +1 -1
  141. data/lib/kward/{kwsh.rb → shell/kwsh.rb} +30 -10
  142. data/lib/kward/{kwshrc.rb → shell/kwshrc.rb} +11 -2
  143. data/lib/kward/shell/native_arithmetic.rb +255 -0
  144. data/lib/kward/shell/native_arrays.rb +102 -0
  145. data/lib/kward/shell/native_braces.rb +96 -0
  146. data/lib/kward/shell/native_builtins.rb +476 -0
  147. data/lib/kward/shell/native_completion.rb +169 -0
  148. data/lib/kward/shell/native_condition.rb +75 -0
  149. data/lib/kward/shell/native_directory.rb +116 -0
  150. data/lib/kward/shell/native_exec_state.rb +73 -0
  151. data/lib/kward/shell/native_expansion.rb +252 -0
  152. data/lib/kward/shell/native_fields.rb +62 -0
  153. data/lib/kward/shell/native_glob.rb +96 -0
  154. data/lib/kward/shell/native_history.rb +242 -0
  155. data/lib/kward/shell/native_interactive.rb +164 -0
  156. data/lib/kward/shell/native_invocation.rb +42 -0
  157. data/lib/kward/shell/native_jobs.rb +250 -0
  158. data/lib/kward/shell/native_line_editor.rb +382 -0
  159. data/lib/kward/shell/native_line_terminal.rb +286 -0
  160. data/lib/kward/shell/native_locale.rb +109 -0
  161. data/lib/kward/shell/native_locals.rb +57 -0
  162. data/lib/kward/shell/native_pattern.rb +200 -0
  163. data/lib/kward/shell/native_process.rb +279 -0
  164. data/lib/kward/shell/native_program.rb +40 -0
  165. data/lib/kward/shell/native_programmable_completion.rb +115 -0
  166. data/lib/kward/shell/native_prompt_format.rb +89 -0
  167. data/lib/kward/shell/native_runtime.rb +964 -0
  168. data/lib/kward/shell/native_substitution.rb +110 -0
  169. data/lib/kward/shell/native_syntax.rb +946 -0
  170. data/lib/kward/shell/native_traps.rb +196 -0
  171. data/lib/kward/shell/native_vi.rb +407 -0
  172. data/lib/kward/shell/native_vi_terminal.rb +19 -0
  173. data/lib/kward/shell/native_worker.rb +82 -0
  174. data/lib/kward/{persistent_shell_session.rb → shell/persistent_session.rb} +187 -193
  175. data/lib/kward/shell/prompt.rb +66 -0
  176. data/lib/kward/shell/prompt_agent.rb +17 -0
  177. data/lib/kward/{shell_prompt_session.rb → shell/prompt_session.rb} +1 -1
  178. data/lib/kward/shell/script_runner.rb +244 -0
  179. data/lib/kward/shell/standalone_agent.rb +31 -0
  180. data/lib/kward/shell/standalone_link.rb +78 -0
  181. data/lib/kward/shell/standalone_terminal.rb +287 -0
  182. data/lib/kward/skills/trust_store.rb +1 -1
  183. data/lib/kward/tabs/driver.rb +194 -0
  184. data/lib/kward/{tab_store.rb → tabs/store.rb} +2 -2
  185. data/lib/kward/{clipboard.rb → terminal/clipboard.rb} +1 -1
  186. data/lib/kward/{terminal_image_support.rb → terminal/image_support.rb} +1 -1
  187. data/lib/kward/{terminal_keys.rb → terminal/keys.rb} +22 -1
  188. data/lib/kward/terminal/locale_text.rb +29 -0
  189. data/lib/kward/{terminal_sequences.rb → terminal/sequences.rb} +45 -4
  190. data/lib/kward/tools/base.rb +18 -0
  191. data/lib/kward/tools/context_for_task.rb +15 -6
  192. data/lib/kward/tools/datetime.rb +85 -0
  193. data/lib/kward/tools/edit_file.rb +9 -6
  194. data/lib/kward/tools/generate_image.rb +36 -0
  195. data/lib/kward/tools/git_commit.rb +13 -7
  196. data/lib/kward/tools/list_directory.rb +4 -4
  197. data/lib/kward/tools/plugin_tool.rb +41 -0
  198. data/lib/kward/tools/prepare_shell_command.rb +1 -1
  199. data/lib/kward/tools/read_file.rb +7 -6
  200. data/lib/kward/tools/registry.rb +130 -21
  201. data/lib/kward/tools/run_shell_command.rb +10 -8
  202. data/lib/kward/tools/search/code.rb +1 -1
  203. data/lib/kward/tools/summarize_file_structure.rb +5 -5
  204. data/lib/kward/tools/tool_call.rb +4 -1
  205. data/lib/kward/tools/typesafe_evaluate.rb +81 -0
  206. data/lib/kward/tools/workspace_targets.rb +58 -0
  207. data/lib/kward/tools/write_file.rb +9 -6
  208. data/lib/kward/{export_path.rb → transcripts/export_path.rb} +1 -1
  209. data/lib/kward/{markdown_transcript.rb → transcripts/markdown_transcript.rb} +10 -2
  210. data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
  211. data/lib/kward/transport/contracts.rb +200 -0
  212. data/lib/kward/transport/gateway.rb +81 -36
  213. data/lib/kward/transport/plugin_chat_gateway.rb +3 -2
  214. data/lib/kward/transport.rb +1 -200
  215. data/lib/kward/turn_summary.rb +68 -0
  216. data/lib/kward/version.rb +1 -1
  217. data/lib/kward/{workspace_factory.rb → workspace/factory.rb} +2 -2
  218. data/lib/kward/{git_worktree_manager.rb → workspace/git_worktree_manager.rb} +28 -0
  219. data/lib/kward/{workspace.rb → workspace/workspace.rb} +3 -3
  220. data/lib/main.rb +6 -3
  221. data/templates/default/fulldoc/html/css/kward.css +125 -0
  222. data/templates/default/fulldoc/html/images/kward_screen_1.png +0 -0
  223. data/templates/default/fulldoc/html/setup.rb +1 -1
  224. data/templates/default/layout/html/layout.erb +16 -4
  225. metadata +150 -48
  226. data/lib/kward/pty_transcript_normalizer.rb +0 -93
  227. data/lib/kward/shell_prompt.rb +0 -52
  228. data/lib/kward/tab_driver.rb +0 -90
  229. data/templates/default/fulldoc/html/images/kward_workflow.svg +0 -52
  230. /data/lib/kward/{editor_prompt.rb → cli/editor_prompt.rb} +0 -0
  231. /data/lib/kward/{editor_prompt_session.rb → cli/editor_prompt_session.rb} +0 -0
  232. /data/lib/kward/{diff_view_mode.rb → prompt_interface/editor/diff_view_mode.rb} +0 -0
  233. /data/lib/kward/{editor_mode.rb → prompt_interface/editor/editor_mode.rb} +0 -0
  234. /data/lib/kward/{markdown_code_block.rb → prompt_interface/editor/markdown_code_block.rb} +0 -0
  235. /data/lib/kward/{scratchpad_languages.rb → prompt_interface/editor/scratchpad_languages.rb} +0 -0
  236. /data/lib/kward/{scratchpad_runner.rb → prompt_interface/editor/scratchpad_runner.rb} +0 -0
  237. /data/lib/kward/{detached_run.rb → pty/detached_run.rb} +0 -0
  238. /data/lib/kward/{session_diff.rb → sessions/diff.rb} +0 -0
  239. /data/lib/kward/{session_naming.rb → sessions/naming.rb} +0 -0
  240. /data/lib/kward/{session_trash.rb → sessions/trash.rb} +0 -0
  241. /data/lib/kward/{ansi.rb → terminal/ansi.rb} +0 -0
  242. /data/lib/kward/{terminal_text.rb → terminal/text.rb} +0 -0
  243. /data/lib/kward/{transcript_export.rb → transcripts/transcript_export.rb} +0 -0
  244. /data/lib/kward/{project_files.rb → workspace/files.rb} +0 -0
  245. /data/lib/kward/{path_guard.rb → workspace/path_guard.rb} +0 -0
@@ -0,0 +1,96 @@
1
+ module Kward
2
+ module NativeShell
3
+ # Brace expansion operates on source word parts, before any substitutions.
4
+ # Quoted braces and braces produced by variables remain literal.
5
+ module Braces
6
+ LIMIT = 4_096
7
+ module_function
8
+
9
+ def expand(word)
10
+ atoms = word.parts.flat_map do |part|
11
+ if part.kind == :literal && !part.text.empty?
12
+ part.text.chars.map { |text| Part.new(kind: :literal, text: text, quoted: part.quoted) }
13
+ else
14
+ [part]
15
+ end
16
+ end
17
+ expand_atoms(atoms, 0).map { |parts| Word.new(parts: coalesce(parts)) }
18
+ end
19
+
20
+ def literal?(part, value)
21
+ part&.kind == :literal && !part.quoted && part.text == value
22
+ end
23
+
24
+ def expand_atoms(atoms, depth)
25
+ raise ExpansionError, "brace nesting exceeds 32 levels" if depth > 32
26
+ atoms.each_index do |start|
27
+ next unless literal?(atoms[start], "{")
28
+ level = 0
29
+ splits = []
30
+ finish = nil
31
+ ((start + 1)...atoms.length).each do |index|
32
+ if literal?(atoms[index], "{")
33
+ level += 1
34
+ elsif literal?(atoms[index], "}")
35
+ if level.zero?
36
+ finish = index
37
+ break
38
+ end
39
+ level -= 1
40
+ elsif level.zero? && literal?(atoms[index], ",")
41
+ splits << index
42
+ end
43
+ end
44
+ next unless finish
45
+ alternatives = if splits.empty?
46
+ sequence(atoms[(start + 1)...finish])
47
+ else
48
+ ([start] + splits).zip(splits + [finish]).map { |left, right| atoms[(left + 1)...right] }
49
+ end
50
+ next unless alternatives
51
+ result = []
52
+ alternatives.each do |alternative|
53
+ result.concat(expand_atoms(atoms[0...start] + alternative + atoms[(finish + 1)..], depth + 1))
54
+ raise ExpansionError, "brace expansion exceeds #{LIMIT} words" if result.length > LIMIT
55
+ end
56
+ return result
57
+ end
58
+ [atoms]
59
+ end
60
+
61
+ def sequence(parts)
62
+ return unless parts.all? { |part| part.kind == :literal && !part.quoted }
63
+ text = parts.map(&:text).join
64
+ match = text.match(/\A(-?\d+|[a-zA-Z])\.\.(-?\d+|[a-zA-Z])(?:\.\.(-?\d+))?\z/)
65
+ return unless match
66
+ first, last, step = match.captures
67
+ raise ExpansionError, "brace sequence exceeds numeric limit" if [first, last, step].compact.any? { |value| value.length > 128 }
68
+ numeric = first.match?(/\A-?\d+\z/) && last.match?(/\A-?\d+\z/)
69
+ return unless numeric || first.length == 1 && last.length == 1 && first.match?(/[a-zA-Z]/) && last.match?(/[a-zA-Z]/)
70
+ from, to = numeric ? [first.to_i, last.to_i] : [first.ord, last.ord]
71
+ stride = step ? step.to_i.abs : 1
72
+ stride = 1 if stride.zero?
73
+ stride = -stride if from > to
74
+ count = (to - from).abs / stride.abs + 1
75
+ raise ExpansionError, "brace expansion exceeds #{LIMIT} words" if count > LIMIT
76
+ padded = numeric && [first, last].any? { |value| value.match?(/\A-?0\d/) }
77
+ width = [first.length, last.length].max
78
+ from.step(to, stride).map do |value|
79
+ text = numeric ? (padded ? format("%0#{width}d", value) : value.to_s) : value.chr
80
+ [Part.new(kind: :literal, text: text, quoted: false)]
81
+ end
82
+ end
83
+
84
+ def coalesce(parts)
85
+ parts.each_with_object([]) do |part, result|
86
+ if part.kind == :literal && result.last&.kind == :literal && result.last.quoted == part.quoted
87
+ previous = result.pop
88
+ result << Part.new(kind: :literal, text: previous.text + part.text, quoted: part.quoted)
89
+ else
90
+ result << part
91
+ end
92
+ end
93
+ end
94
+ end
95
+ end
96
+ end
@@ -0,0 +1,476 @@
1
+ module Kward
2
+ module NativeShell
3
+ # State-changing utilities execute in the interpreter, never in an external
4
+ # shell. Explicit eval and dot-sourcing use the same native parser.
5
+ module Builtins
6
+ private
7
+
8
+ SHELL_OPTIONS = { "a" => "allexport", "b" => "notify", "h" => "hashall", "v" => "verbose", "m" => "monitor", "e" => "errexit", "f" => "noglob", "n" => "noexec", "u" => "nounset", "x" => "xtrace", "C" => "noclobber" }.freeze
9
+
10
+ def builtin_flags(args, allowed, command)
11
+ flags = []
12
+ while args.first&.start_with?("-") && args.first != "-"
13
+ option = args.shift
14
+ break if option == "--"
15
+ option[1..].each_char do |flag|
16
+ raise ExecutionError, "#{command}: unsupported option -#{flag}" unless allowed.include?(flag)
17
+ flags << flag
18
+ end
19
+ end
20
+ flags
21
+ end
22
+
23
+ def times_builtin(args, streams)
24
+ builtin_flags(args, "", "times")
25
+ raise ExecutionError, "times: unexpected operand" unless args.empty?
26
+ usage = Process.times
27
+ [[usage.utime, usage.stime], [usage.cutime, usage.cstime]].each do |pair|
28
+ write_line(streams, pair.map { |seconds| format("%dm%.6fs", seconds.to_i / 60, seconds % 60) }.join(" "))
29
+ end
30
+ 0
31
+ end
32
+
33
+ def hash_builtin(args, streams)
34
+ flags = builtin_flags(args, "r", "hash")
35
+ @command_hash.clear if flags.include?("r")
36
+ if args.empty?
37
+ @command_hash.sort.each { |_, path| write_line(streams, path) } if flags.empty?
38
+ return 0
39
+ end
40
+ result = 0
41
+ args.each do |name|
42
+ next if self.class::BUILTINS.include?(name) || @functions.key?(name)
43
+ path = executable_path(name)
44
+ if path && File.file?(path) && File.executable?(path)
45
+ @command_hash[name] = path unless name.include?("/")
46
+ else
47
+ streams[2]&.puts("kwsh: hash: #{name}: not found")
48
+ result = 1
49
+ end
50
+ end
51
+ result
52
+ end
53
+
54
+ def remember_function_commands(tree)
55
+ return unless tree.is_a?(Node)
56
+ if tree.kind == :simple
57
+ word = tree.values.first.find { |item| !item.assignment }
58
+ name = word&.literal
59
+ if name && !self.class::BUILTINS.include?(name) && !@functions.key?(name)
60
+ path = executable_path(name)
61
+ @command_hash[name] = path if path && File.file?(path) && File.executable?(path)
62
+ end
63
+ end
64
+ tree.values.flatten.each { |child| remember_function_commands(child) if child.is_a?(Node) }
65
+ end
66
+
67
+ def persist_descriptors(redirected, streams)
68
+ redirected.each do |descriptor, io|
69
+ next if streams[descriptor].equal?(io)
70
+ copy = io&.dup
71
+ copy.sync = true if copy
72
+ @owned_descriptors << copy if copy
73
+ @persistent_descriptors[descriptor] = copy
74
+ streams[descriptor] = copy
75
+ @base_streams[descriptor] = copy if @base_streams
76
+ end
77
+ release_descriptors
78
+ end
79
+
80
+ def release_descriptors
81
+ retained = @persistent_descriptors.values + @active_streams.flat_map(&:values)
82
+ @owned_descriptors.delete_if do |io|
83
+ next false if retained.include?(io)
84
+ io.close unless io.closed?
85
+ true
86
+ end
87
+ end
88
+
89
+ def exec_builtin(args, streams)
90
+ raise ExecutionError, "exec: needs a user-driven terminal" if @shell_agent_command
91
+
92
+ clear = false
93
+ argv0 = nil
94
+ login = false
95
+ while args.first&.start_with?("-")
96
+ option = args.shift
97
+ break if option == "--"
98
+ case option
99
+ when "-c" then clear = true
100
+ when "-l" then login = true
101
+ when "-a"
102
+ argv0 = args.shift || raise(ExecutionError, "exec: -a requires a name")
103
+ else raise ExecutionError, "exec: unsupported option #{option}"
104
+ end
105
+ end
106
+ if args.empty?
107
+ persist_descriptors(streams, @streams)
108
+ NativeProcess.redirect_standard_streams(@persistent_descriptors) if @replace_process
109
+ return 0
110
+ end
111
+ recover = @replace_process && interactive_scope?
112
+ persist_descriptors(streams, @streams) if recover
113
+ executable = executable_path(args.first)
114
+ unless executable
115
+ streams[2]&.puts("kwsh: #{args.first}: command not found")
116
+ if recover
117
+ NativeProcess.redirect_standard_streams(@persistent_descriptors)
118
+ raise Flow.new(:abort, 127)
119
+ end
120
+ raise Flow.new(:exit, 127) unless interactive_scope?
121
+ return 127
122
+ end
123
+ arguments = args.dup
124
+ arguments[0] = argv0 || arguments[0]
125
+ arguments[0] = "-#{arguments[0]}" if login
126
+ env = clear ? {} : environment
127
+ NativeProcess.validate(arguments, env)
128
+ if @replace_process
129
+ @history&.commit_pending
130
+ result = NativeProcess.replace(executable, arguments, env, cwd: @directory, streams: streams, mask: @umask, signals: child_signal_dispositions, recover: recover)
131
+ NativeProcess.redirect_standard_streams(@persistent_descriptors) if recover
132
+ raise Flow.new(recover ? :abort : :exit, result)
133
+ else
134
+ pid = NativeProcess.spawn(executable, arguments, env, cwd: @directory, streams: streams, mask: @umask, hosted: @hosted, signals: child_signal_dispositions)
135
+ result = wait(pid)
136
+ pid = nil
137
+ # The protocol worker must return its final state before exiting.
138
+ @traps.delete("EXIT")
139
+ raise Flow.new(:exit, result)
140
+ end
141
+ rescue Interrupt
142
+ @traps.delete("EXIT")
143
+ raise Flow.new(:exit, 130)
144
+ ensure
145
+ terminate(pid) if pid
146
+ end
147
+
148
+ def set_options(args, streams)
149
+ if args.empty?
150
+ @variables.sort.each { |name, value| write_line(streams, "#{name}=#{Shellwords.escape(value)}") }
151
+ return 0
152
+ end
153
+ until args.empty?
154
+ option = args.shift
155
+ if option == "-"
156
+ @options.subtract(%w[verbose xtrace])
157
+ @arguments = args unless args.empty?
158
+ return 0
159
+ end
160
+ if option == "--"
161
+ @arguments = args
162
+ return 0
163
+ end
164
+ unless option.start_with?("-", "+") && option.length > 1
165
+ @arguments = [option] + args
166
+ return 0
167
+ end
168
+ enabled = option.start_with?("-")
169
+ flags = option[1..].chars
170
+ flags.each do |flag|
171
+ name = if flag == "o"
172
+ if args.empty?
173
+ (SHELL_OPTIONS.values + %w[pipefail ignoreeof nolog vi]).each do |entry|
174
+ write_line(streams, "set #{@options.include?(entry) ? '-' : '+'}o #{entry}")
175
+ end
176
+ next
177
+ end
178
+ args.shift
179
+ else
180
+ SHELL_OPTIONS[flag]
181
+ end
182
+ raise ExecutionError, "set: unsupported option #{name || flag}" unless (SHELL_OPTIONS.values + %w[pipefail ignoreeof nolog vi]).include?(name)
183
+ raise ExecutionError, "set: native vi editing is standalone-only" if name == "vi" && enabled && @hosted
184
+ raise ExecutionError, "set: vi editing requires an ANSI-compatible terminal" if name == "vi" && enabled && @interactive && @variables["TERM"] == "dumb"
185
+ enabled ? @options.add(name) : @options.delete(name)
186
+ end
187
+ end
188
+ 0
189
+ end
190
+
191
+ RESOURCE_LIMITS = {
192
+ "c" => [:CORE, 512, "core file size (512 bytes)"],
193
+ "d" => [:DATA, 1024, "data segment size (1024 bytes)"],
194
+ "f" => [:FSIZE, 512, "file size (512 bytes)"],
195
+ "n" => [:NOFILE, 1, "open file descriptors"],
196
+ "s" => [:STACK, 1024, "stack size (1024 bytes)"],
197
+ "t" => [:CPU, 1, "CPU time (seconds)"],
198
+ "v" => [:AS, 1024, "address space size (1024 bytes)"]
199
+ }.transform_values(&:freeze).freeze
200
+
201
+ def ulimit_builtin(args, streams)
202
+ flags = builtin_flags(args, "HSacdfnstv", "ulimit")
203
+ selected = flags & RESOURCE_LIMITS.keys
204
+ all = flags.include?("a")
205
+ if (flags.include?("H") && flags.include?("S")) || selected.length > 1 ||
206
+ (all && (!selected.empty? || !args.empty?)) || args.length > 1
207
+ raise ExecutionError, "ulimit: incompatible options or operands"
208
+ end
209
+ selected = all ? RESOURCE_LIMITS.keys : [selected.first || "f"]
210
+ if args.empty?
211
+ selected.each do |flag|
212
+ resource, unit, label = RESOURCE_LIMITS.fetch(flag)
213
+ value = Process.getrlimit(resource)[flags.include?("H") ? 1 : 0]
214
+ text = value == Process::RLIM_INFINITY ? "unlimited" : (value / unit).to_s
215
+ write_line(streams, all ? "#{label} (-#{flag}) #{text}" : text)
216
+ end
217
+ else
218
+ # Never lower an embedding application's process-wide hard limit.
219
+ # Forked shell environments own their process even when their parent
220
+ # runtime was embedded. Dedicated entrypoints opt in explicitly.
221
+ unless @process_owned || Process.pid != @shell_pid
222
+ raise ExecutionError, "ulimit: setting limits requires an owned shell process"
223
+ end
224
+ resource, unit = RESOURCE_LIMITS.fetch(selected.first)
225
+ operand = args.first
226
+ value = if operand == "unlimited"
227
+ Process::RLIM_INFINITY
228
+ elsif operand.match?(/\A\+?[0-9]+\z/)
229
+ Integer(operand, 10) * unit
230
+ else
231
+ raise ExecutionError, "ulimit: invalid limit"
232
+ end
233
+ soft, hard = Process.getrlimit(resource)
234
+ soft = value unless flags.include?("H")
235
+ hard = value unless flags.include?("S")
236
+ Process.setrlimit(resource, soft, hard)
237
+ end
238
+ 0
239
+ rescue SystemCallError, ArgumentError, RangeError, NotImplementedError => e
240
+ raise ExecutionError, "ulimit: #{e.message}"
241
+ end
242
+
243
+ def umask_builtin(args, streams)
244
+ flags = builtin_flags(args, "S", "umask")
245
+ if args.empty?
246
+ text = unless flags.include?("S")
247
+ format("%04o", @umask)
248
+ else
249
+ %w[u g o].each_with_index.map do |who, index|
250
+ bits = (7 & ~(@umask >> (6 - index * 3)))
251
+ permissions = [[4, "r"], [2, "w"], [1, "x"]].filter_map { |bit, letter| letter if bits & bit != 0 }.join
252
+ "#{who}=#{permissions}"
253
+ end.join(",")
254
+ end
255
+ write_line(streams, text)
256
+ return 0
257
+ end
258
+ raise ExecutionError, "umask: expected one mask" unless args.length == 1
259
+ value = args.first
260
+ if value.match?(/\A[0-7]+\z/) && value.to_i(8) <= 0o777
261
+ @umask = value.to_i(8)
262
+ return 0
263
+ end
264
+ allowed = 0o777 & ~@umask
265
+ executable = allowed & 0o111 != 0
266
+ shifts = { "u" => 6, "g" => 3, "o" => 0 }
267
+ value.split(",", -1).each do |clause|
268
+ match = clause.match(/\A([ugoa]*)((?:[+=-](?:[ugo]|[rwxXst]*))+)\z/)
269
+ raise ExecutionError, "umask: invalid symbolic mask" unless match
270
+ who, actions = match.captures
271
+ who = "ugo" if who.empty? || who.include?("a")
272
+ actions.scan(/([+=-])([ugo]|[rwxXst]*)/).each do |operator, permissions|
273
+ bits = if shifts.key?(permissions)
274
+ (allowed >> shifts.fetch(permissions)) & 7
275
+ else
276
+ # Non-permission s/t bits do not affect the creation mask.
277
+ permissions.chars.reduce(0) { |mask, letter| mask | { "r" => 4, "w" => 2, "x" => 1, "X" => executable ? 1 : 0 }.fetch(letter, 0) }
278
+ end
279
+ who.chars.uniq.each do |group|
280
+ shift = shifts.fetch(group)
281
+ allowed &= ~(7 << shift) if operator == "="
282
+ allowed = operator == "-" ? allowed & ~(bits << shift) : allowed | (bits << shift)
283
+ end
284
+ end
285
+ end
286
+ @umask = 0o777 & ~allowed
287
+ 0
288
+ end
289
+
290
+ def source_script(utility, args, streams)
291
+ raise ExecutionError, "#{utility}: expected a file" if args.empty?
292
+ raise ExecutionError, "source nesting exceeds 100 levels" if @source_depth >= 100
293
+ name = args.first
294
+ input = open_source_file(name)
295
+ raise ExecutionError, "#{utility}: file not found: #{name}" unless input
296
+ previous = @arguments
297
+ @arguments = args.drop(1) if args.length > 1
298
+ @source_depth += 1
299
+ begin
300
+ evaluate_program(input, streams)
301
+ rescue Flow => flow
302
+ raise unless flow.kind == :return
303
+ flow.status
304
+ ensure
305
+ input.close
306
+ @source_depth -= 1
307
+ @arguments = previous
308
+ end
309
+ end
310
+
311
+ def open_source_file(name)
312
+ return @directory.open_file(name) if name.include?("/")
313
+
314
+ @variables.fetch("PATH", "/usr/bin:/bin").split(":", -1).each do |directory|
315
+ candidate = @directory.resolve(File.join(directory.empty? ? "." : directory, name))
316
+ next unless File.file?(candidate)
317
+ begin
318
+ return @directory.open_file(candidate)
319
+ rescue Errno::EACCES, Errno::ENOENT, Errno::ENOTDIR, Errno::ELOOP
320
+ next
321
+ end
322
+ end
323
+ nil
324
+ end
325
+
326
+ def readonly(args, streams)
327
+ flags = builtin_flags(args, "p", "readonly")
328
+ if args.empty? || flags.include?("p")
329
+ @readonly.sort.each do |name|
330
+ value = @variables.key?(name) ? "=#{Shellwords.escape(parameter(name))}" : ""
331
+ write_line(streams, "readonly #{name}#{value}")
332
+ end
333
+ else
334
+ args.each do |argument|
335
+ name, value = argument.split("=", 2)
336
+ validate_name(name)
337
+ assign(name, value) if value
338
+ @readonly.add(name)
339
+ end
340
+ end
341
+ 0
342
+ end
343
+
344
+ def shopt(args, streams)
345
+ mode = args.first&.start_with?("-") ? args.shift : nil
346
+ raise ExecutionError, "shopt: supported options are -s, -u, and -q" unless [nil, "-s", "-u", "-q"].include?(mode)
347
+ raise ExecutionError, "shopt: only globstar is currently supported" unless args.empty? || args == ["globstar"]
348
+ case mode
349
+ when "-s" then @globstar = true
350
+ when "-u" then @globstar = false
351
+ when "-q" then return @globstar ? 0 : 1
352
+ else write_line(streams, "globstar\t#{@globstar ? 'on' : 'off'}")
353
+ end
354
+ 0
355
+ end
356
+
357
+ def command_builtin(args, streams)
358
+ flags = builtin_flags(args, "vVp", "command")
359
+ mode = flags.reverse.find { |flag| %w[v V].include?(flag) }
360
+ old_path = @variables["PATH"]
361
+ saved_hash, saved_hash_path = @command_hash.dup, @hash_path
362
+ @variables["PATH"] = Etc.confstr(Etc::CS_PATH) || "/usr/bin:/bin" if flags.include?("p")
363
+ return 0 if args.empty?
364
+ return describe_commands(args, streams, mode) if mode
365
+ dispatch(args, streams, functions: false)
366
+ ensure
367
+ if flags&.include?("p")
368
+ old_path ? @variables["PATH"] = old_path : @variables.delete("PATH")
369
+ @command_hash, @hash_path = saved_hash, saved_hash_path
370
+ end
371
+ end
372
+
373
+ def which_builtin(args, streams)
374
+ # Preserve the platform utility's options (for example, macOS -a and -s).
375
+ return external(["which", *args], streams) if args.empty? || (args.first.match?(/\A-.+/) && args.first != "--")
376
+
377
+ args.shift if args.first == "--"
378
+ return 1 if args.empty?
379
+
380
+ describe_commands(args, streams, "which")
381
+ end
382
+
383
+ def describe_commands(names, streams, mode)
384
+ result = 0
385
+ names.each do |name|
386
+ if @aliases.key?(name)
387
+ replacement = @aliases.fetch(name)
388
+ text = mode == "which" ? "#{name}: aliased to #{replacement}" : "alias #{name}=#{Shellwords.escape(replacement)}"
389
+ write_line(streams, text)
390
+ next
391
+ end
392
+
393
+ kind = if Parser::RESERVED.include?(name)
394
+ "keyword"
395
+ elsif self.class::SPECIAL.include?(name)
396
+ "shell builtin"
397
+ elsif @functions.key?(name)
398
+ "function"
399
+ elsif self.class::BUILTINS.include?(name)
400
+ "shell builtin"
401
+ end
402
+ path = kind ? name : executable_path(name)
403
+ if path && (kind || File.file?(path) && File.executable?(path))
404
+ text = case mode
405
+ when "V" then "#{name} is #{kind || path}"
406
+ when "which" then kind ? "#{name}: #{kind}" : path
407
+ else path
408
+ end
409
+ write_line(streams, text)
410
+ else
411
+ result = 1
412
+ end
413
+ end
414
+ result
415
+ end
416
+
417
+ def getopts(args, streams)
418
+ @getopts_running = true
419
+ raise ExecutionError, "getopts: expected optstring and variable" if args.length < 2
420
+ spec, name, *explicit = args
421
+ validate_name(name)
422
+ arguments = args.length > 2 ? explicit : @arguments
423
+ index = Integer(@variables.fetch("OPTIND", "1"), 10)
424
+ index = 1 if index < 1
425
+ @getopts_offset = 1 if index != @getopts_index
426
+ @getopts_offset ||= 1
427
+ argument = arguments[index - 1]
428
+ if !argument || !argument.start_with?("-") || argument == "-" || argument == "--"
429
+ index += 1 if argument == "--"
430
+ assign("OPTIND", index.to_s)
431
+ assign(name, "?")
432
+ @variables.delete("OPTARG")
433
+ @getopts_index = index
434
+ @getopts_offset = 1
435
+ return 1
436
+ end
437
+ option = argument[@getopts_offset]
438
+ @getopts_offset += 1
439
+ position = spec.delete_prefix(":").index(option)
440
+ silent = spec.start_with?(":")
441
+ @variables.delete("OPTARG")
442
+ if position.nil? || option == ":"
443
+ assign(name, "?")
444
+ assign("OPTARG", option) if silent
445
+ streams[2]&.puts("#{@name}: getopts: illegal option -- #{option}") unless silent
446
+ else
447
+ assign(name, option)
448
+ if spec.delete_prefix(":")[position + 1] == ":"
449
+ value = argument[@getopts_offset..]
450
+ if value.empty?
451
+ value = arguments[index]
452
+ index += 1 if value
453
+ end
454
+ if value
455
+ assign("OPTARG", value)
456
+ else
457
+ assign(name, silent ? ":" : "?")
458
+ assign("OPTARG", option) if silent
459
+ streams[2]&.puts("#{@name}: getopts: option requires an argument -- #{option}") unless silent
460
+ end
461
+ @getopts_offset = argument.length
462
+ end
463
+ end
464
+ if @getopts_offset >= argument.length
465
+ index += 1
466
+ @getopts_offset = 1
467
+ end
468
+ @getopts_index = index
469
+ assign("OPTIND", index.to_s)
470
+ 0
471
+ ensure
472
+ @getopts_running = false
473
+ end
474
+ end
475
+ end
476
+ end