aspera-cli 4.28.0 → 4.29.1

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 (242) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +217 -2
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +135 -56
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +122 -26
  10. data/SECURITY.md +84 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1895 -632
  14. data/docs/test-mcp-with-ai.md +8 -8
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +20 -19
  19. data/lib/aspera/agent/factory.rb +6 -3
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +7 -4
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +29 -22
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +95 -67
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +370 -0
  41. data/lib/aspera/ascp/log_locations.rb +163 -0
  42. data/lib/aspera/ascp/management.rb +16 -8
  43. data/lib/aspera/ascp/session_errors.rb +217 -0
  44. data/lib/aspera/assert.rb +4 -0
  45. data/lib/aspera/cli/ascp_actions.rb +12 -19
  46. data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
  47. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  48. data/lib/aspera/cli/bootstrapper.rb +38 -33
  49. data/lib/aspera/cli/command_line.rb +63 -8
  50. data/lib/aspera/cli/command_registry.rb +9 -1
  51. data/lib/aspera/cli/command_spec.rb +47 -7
  52. data/lib/aspera/cli/completion/ascli.bash +19 -5
  53. data/lib/aspera/cli/completion/ascli.fish +13 -2
  54. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  55. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  56. data/lib/aspera/cli/completion_actions.rb +303 -69
  57. data/lib/aspera/cli/context.rb +9 -4
  58. data/lib/aspera/cli/deprecation.rb +5 -2
  59. data/lib/aspera/cli/error.rb +6 -0
  60. data/lib/aspera/cli/extended_value.rb +66 -31
  61. data/lib/aspera/cli/formatter.rb +43 -30
  62. data/lib/aspera/cli/gem_checker.rb +9 -6
  63. data/lib/aspera/cli/hints.rb +22 -10
  64. data/lib/aspera/cli/http.rb +38 -10
  65. data/lib/aspera/cli/info.rb +12 -7
  66. data/lib/aspera/cli/mailer.rb +6 -3
  67. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  68. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  69. data/lib/aspera/cli/mcp/tool.rb +20 -17
  70. data/lib/aspera/cli/option_declarator.rb +10 -4
  71. data/lib/aspera/cli/option_registry.rb +6 -3
  72. data/lib/aspera/cli/option_types.rb +17 -2
  73. data/lib/aspera/cli/option_value.rb +77 -18
  74. data/lib/aspera/cli/options.schema.yaml +641 -80
  75. data/lib/aspera/cli/parser.rb +71 -35
  76. data/lib/aspera/cli/plugins/alee.rb +7 -4
  77. data/lib/aspera/cli/plugins/aoc.rb +248 -37
  78. data/lib/aspera/cli/plugins/ats.rb +10 -9
  79. data/lib/aspera/cli/plugins/base.rb +50 -18
  80. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  81. data/lib/aspera/cli/plugins/config.rb +210 -104
  82. data/lib/aspera/cli/plugins/console.rb +6 -3
  83. data/lib/aspera/cli/plugins/cos.rb +8 -4
  84. data/lib/aspera/cli/plugins/factory.rb +21 -7
  85. data/lib/aspera/cli/plugins/faspex5.rb +31 -26
  86. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  87. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  88. data/lib/aspera/cli/plugins/mcp.rb +42 -22
  89. data/lib/aspera/cli/plugins/node.rb +39 -38
  90. data/lib/aspera/cli/plugins/oauth.rb +23 -6
  91. data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
  92. data/lib/aspera/cli/plugins/preview.rb +72 -45
  93. data/lib/aspera/cli/plugins/server.rb +66 -14
  94. data/lib/aspera/cli/plugins/shares.rb +87 -18
  95. data/lib/aspera/cli/plugins/transferd.rb +228 -0
  96. data/lib/aspera/cli/poll.rb +236 -0
  97. data/lib/aspera/cli/preset_actions.rb +144 -30
  98. data/lib/aspera/cli/preset_manager.rb +113 -35
  99. data/lib/aspera/cli/prompt.rb +157 -9
  100. data/lib/aspera/cli/result.rb +12 -8
  101. data/lib/aspera/cli/runner.rb +89 -48
  102. data/lib/aspera/cli/secret_finder.rb +4 -1
  103. data/lib/aspera/cli/security.rb +89 -9
  104. data/lib/aspera/cli/special_values.rb +4 -1
  105. data/lib/aspera/cli/sync_actions.rb +15 -10
  106. data/lib/aspera/cli/table_fitter.rb +3 -0
  107. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  108. data/lib/aspera/cli/transfer_actions.rb +11 -8
  109. data/lib/aspera/cli/transfer_agent.rb +43 -20
  110. data/lib/aspera/cli/transfer_progress.rb +14 -45
  111. data/lib/aspera/cli/vault_actions.rb +45 -0
  112. data/lib/aspera/cli/vault_manager.rb +188 -42
  113. data/lib/aspera/cli/version.rb +4 -1
  114. data/lib/aspera/cli/web_secret.rb +12 -10
  115. data/lib/aspera/cli/wizard.rb +42 -39
  116. data/lib/aspera/command_line_builder.rb +9 -5
  117. data/lib/aspera/command_line_converter.rb +4 -1
  118. data/lib/aspera/coverage.rb +103 -33
  119. data/lib/aspera/data_repository.rb +4 -1
  120. data/lib/aspera/dot_container.rb +4 -1
  121. data/lib/aspera/environment.rb +23 -12
  122. data/lib/aspera/exec_spec.rb +3 -0
  123. data/lib/aspera/faspex_gw.rb +13 -9
  124. data/lib/aspera/faspex_postproc.rb +15 -12
  125. data/lib/aspera/formatter_interface.rb +4 -1
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +20 -5
  129. data/lib/aspera/inflate.rb +43 -0
  130. data/lib/aspera/json_rpc/client.rb +6 -5
  131. data/lib/aspera/json_rpc/version.rb +3 -0
  132. data/lib/aspera/line_logger.rb +4 -1
  133. data/lib/aspera/link_header.rb +4 -1
  134. data/lib/aspera/log.rb +18 -5
  135. data/lib/aspera/markdown.rb +5 -2
  136. data/lib/aspera/mime.rb +3 -0
  137. data/lib/aspera/nagios.rb +6 -4
  138. data/lib/aspera/node_emulator.rb +15 -13
  139. data/lib/aspera/oauth/client/base.rb +124 -73
  140. data/lib/aspera/oauth/client/boot.rb +7 -4
  141. data/lib/aspera/oauth/client/factory.rb +41 -18
  142. data/lib/aspera/oauth/client/generic.rb +5 -1
  143. data/lib/aspera/oauth/client/json_credentials.rb +7 -3
  144. data/lib/aspera/oauth/client/jwt.rb +6 -3
  145. data/lib/aspera/oauth/client/shares_web.rb +94 -0
  146. data/lib/aspera/oauth/client/url_json.rb +7 -3
  147. data/lib/aspera/oauth/client/web.rb +40 -13
  148. data/lib/aspera/oauth/server/pkce.rb +6 -5
  149. data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +16 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +17 -2
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +3 -0
  165. data/lib/aspera/rest/aspera_errors.rb +4 -1
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +45 -34
  168. data/lib/aspera/rest/error_analyzer.rb +5 -2
  169. data/lib/aspera/rest/list.rb +8 -4
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +8 -5
  172. data/lib/aspera/rest.rb +9 -6
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  175. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  176. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  177. data/lib/aspera/schema/async_tables.yaml +11 -10
  178. data/lib/aspera/schema/documentation.rb +8 -2
  179. data/lib/aspera/schema/reader.rb +7 -0
  180. data/lib/aspera/schema/registry.rb +44 -28
  181. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  182. data/lib/aspera/schema/validator.rb +4 -1
  183. data/lib/aspera/sealed_hash.rb +150 -0
  184. data/lib/aspera/secret/hider.rb +213 -0
  185. data/lib/aspera/secret/reference.rb +150 -0
  186. data/lib/aspera/secret/resolver.rb +212 -0
  187. data/lib/aspera/secret/store/base.rb +153 -0
  188. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  189. data/lib/aspera/secret/store/factory.rb +103 -0
  190. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  191. data/lib/aspera/secret/store/keeper.rb +141 -0
  192. data/lib/aspera/secret/store/macos_security.rb +284 -0
  193. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  194. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  195. data/lib/aspera/secret/store/one_password_cli.rb +112 -0
  196. data/lib/aspera/secret/store/secret_service.rb +125 -0
  197. data/lib/aspera/secret/strength.rb +119 -0
  198. data/lib/aspera/servlet_helpers.rb +5 -2
  199. data/lib/aspera/ssh.rb +10 -7
  200. data/lib/aspera/ssl.rb +5 -2
  201. data/lib/aspera/string_ext.rb +3 -0
  202. data/lib/aspera/sync/args.schema.yaml +3 -0
  203. data/lib/aspera/sync/conf.schema.yaml +9 -4
  204. data/lib/aspera/sync/database.rb +3 -0
  205. data/lib/aspera/sync/operations.rb +17 -15
  206. data/lib/aspera/temp_file_manager.rb +8 -4
  207. data/lib/aspera/timer_limiter.rb +3 -0
  208. data/lib/aspera/transfer/error.rb +4 -1
  209. data/lib/aspera/transfer/faux_file.rb +4 -1
  210. data/lib/aspera/transfer/parameters.rb +17 -14
  211. data/lib/aspera/transfer/result.rb +23 -0
  212. data/lib/aspera/transfer/resumer.rb +6 -4
  213. data/lib/aspera/transfer/spec.rb +9 -22
  214. data/lib/aspera/units/decimal.rb +67 -0
  215. data/lib/aspera/units/duration.rb +109 -0
  216. data/lib/aspera/uri_reader.rb +64 -9
  217. data/lib/aspera/web_auth/index.html.erb +6 -2
  218. data/lib/aspera/web_auth/paste.rb +109 -0
  219. data/lib/aspera/web_auth/receiver.rb +50 -0
  220. data/lib/aspera/web_auth/relay.rb +76 -0
  221. data/lib/aspera/web_auth/reply.html.erb +150 -0
  222. data/lib/aspera/web_auth/server.rb +47 -10
  223. data/lib/aspera/web_page.rb +7 -2
  224. data/lib/aspera/web_server_simple.rb +6 -3
  225. data/lib/aspera/yaml.rb +5 -1
  226. data/llms-install.md +88 -0
  227. data/llms.txt +87 -0
  228. data/skills/ascli/SKILL.md +94 -0
  229. data.tar.gz.sig +0 -0
  230. metadata +77 -20
  231. metadata.gz.sig +0 -0
  232. data/lib/aspera/duration.rb +0 -42
  233. data/lib/aspera/keychain/base.rb +0 -30
  234. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  235. data/lib/aspera/keychain/factory.rb +0 -58
  236. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  237. data/lib/aspera/keychain/macos_security.rb +0 -277
  238. data/lib/aspera/keychain/one_password_api.rb +0 -91
  239. data/lib/aspera/keychain/one_password_base.rb +0 -39
  240. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  241. data/lib/aspera/secret_hider.rb +0 -196
  242. data/lib/aspera/secret_strength.rb +0 -114
@@ -1,7 +1,15 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../assert'
7
+ require_relative '../environment'
8
+ require_relative '../rainbow'
3
9
  require 'io/console'
4
- require 'aspera/assert'
10
+ require 'unicode/display_width'
11
+
12
+ using Rainbow
5
13
 
6
14
  module Aspera
7
15
  module Cli
@@ -11,15 +19,23 @@ module Aspera
11
19
 
12
20
  # Prompt user for console input
13
21
  # The prompt is displayed on `stderr`, like for sensitive input, so that `stdout` contains only results.
14
- # @param prompt [String] prompt string to display
15
- # @param sensitive [Boolean] whether to hide typed input
22
+ # @param prompt [String] prompt string to display
23
+ # @param sensitive [Boolean] whether to hide typed input
24
+ # @param validate [Proc, nil] Called with the input: raises `ParameterError` (with the reason) if the input is not valid. Its result is not used.
25
+ # On a terminal, hidden input shows whether it is valid, and if not, the error is displayed and the input is asked again.
16
26
  # @return [String] user input stripped of trailing newline
17
- def prompt_user_input(prompt, sensitive: false)
18
- return $stdin.getpass("#{prompt}> ") if sensitive && $stdin.tty?
19
- $stderr.print("#{prompt}> ")
20
- line = $stdin.gets
21
- Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
22
- line.chomp
27
+ def prompt_user_input(prompt, sensitive: false, validate: nil)
28
+ loop do
29
+ line = read_input(prompt, sensitive, validate)
30
+ begin
31
+ validate&.call(line)
32
+ return line
33
+ rescue ParameterError => e
34
+ # not a terminal: nobody to ask again
35
+ raise unless $stdin.tty?
36
+ $stderr.puts("#{e.message}. Try again, or Ctrl-C to stop.".red) # rubocop:disable Style/StderrPuts
37
+ end
38
+ end
23
39
  end
24
40
 
25
41
  # Prompt user for input in a list of symbols
@@ -33,6 +49,138 @@ module Aspera
33
49
  $stderr.puts("No such #{prompt}: #{input}, select one of: #{sym_list.join(', ')}") # rubocop:disable Style/StderrPuts
34
50
  end
35
51
  end
52
+
53
+ private
54
+
55
+ # Characters that erase the last one
56
+ ERASE_CHARS = ["\u007f", "\b"].freeze
57
+
58
+ # Mark of an input checked with `validate`, if valid (`true`) or not: Unicode character, ASCII equivalent, color
59
+ CHECK_MARKS = {
60
+ true => {unicode: '✓', ascii: 'valid', color: :green},
61
+ false => {unicode: '✗', ascii: 'invalid', color: :red}
62
+ }.freeze
63
+
64
+ # Mark shown instead of a hidden input
65
+ Mark = Data.define(:text, :color) do
66
+ # @return [String] Text to display, colored if `color` is set (and colors are enabled)
67
+ def to_s = color.nil? ? text : text.color(color)
68
+
69
+ # @return [String] Characters that erase the mark, by its width on the terminal
70
+ def erase = "\b \b" * Unicode::DisplayWidth.of(text)
71
+ end
72
+ private_constant :ERASE_CHARS, :CHECK_MARKS, :Mark
73
+
74
+ # @param prompt [String] prompt string to display
75
+ # @param sensitive [Boolean] whether to hide typed input
76
+ # @param validate [Proc, nil] Checks the input, for the mark of hidden input
77
+ # @return [String] user input stripped of trailing newline
78
+ def read_input(prompt, sensitive, validate)
79
+ $stderr.print("#{prompt}> ")
80
+ if sensitive && $stdin.tty?
81
+ line = Environment.instance.hidden_silent ? silent_input : masked_input(validate)
82
+ return line unless line.nil?
83
+ end
84
+ read_line
85
+ end
86
+
87
+ # @return [String] Line read from standard input, without trailing newline
88
+ def read_line
89
+ line = $stdin.gets
90
+ Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
91
+ line.chomp
92
+ end
93
+
94
+ # Read a line from the terminal without echoing it, and without any feedback (option `ui.hidden_silent`)
95
+ # @return [String, nil] user input, or `nil` if the terminal cannot disable echo (input not read)
96
+ def silent_input
97
+ line = $stdin.noecho(&:gets)
98
+ $stderr.print("\n")
99
+ Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
100
+ line.chomp
101
+ rescue Errno::ENODEV, Errno::ENOTTY
102
+ nil
103
+ end
104
+
105
+ # Read a line from the terminal without echoing it, but show a mark instead, without revealing the length of the input:
106
+ # a key while the input is empty (waiting for input), then an ellipsis (the paste worked),
107
+ # or, if the input is checked (`validate`), a check mark if it is valid, else a cross.
108
+ # `terminal_supports_unicode?` checks `stdout`, but the mark is on `stderr`: use the locale only.
109
+ # @param validate [Proc, nil] Checks the input
110
+ # @return [String, nil] user input, or `nil` if the terminal has no raw mode (input not read)
111
+ def masked_input(validate)
112
+ unicode = Environment.unicode_environment?
113
+ line = +''
114
+ mark_of = ->(text) { input_mark(text, validate, unicode) }
115
+ shown = mark_of.call(line)
116
+ $stderr.print(shown)
117
+ begin
118
+ $stdin.raw { |tty| read_masked(tty, line, shown, &mark_of) }
119
+ rescue Errno::ENODEV, Errno::ENOTTY
120
+ # e.g. a pseudo terminal without raw mode: erase the mark, the caller reads a line (echoed)
121
+ $stderr.print(shown.erase)
122
+ return
123
+ end
124
+ line
125
+ end
126
+
127
+ # @param line [String] Input
128
+ # @param validate [Proc, nil] Checks the input
129
+ # @param unicode [Boolean] `true` if Unicode is supported
130
+ # @return [Mark] Mark of the input
131
+ def input_mark(line, validate, unicode)
132
+ return Mark.new(Environment.char('🔑', unicode: unicode), nil) if line.empty?
133
+ return Mark.new(Environment.char('…', unicode: unicode), nil) if validate.nil?
134
+ check = CHECK_MARKS[valid?(line, validate)]
135
+ Mark.new(check[unicode ? :unicode : :ascii], check[:color])
136
+ end
137
+
138
+ # @return [Boolean] `true` if `validate` accepts the input
139
+ def valid?(line, validate)
140
+ validate.call(line)
141
+ true
142
+ rescue ParameterError
143
+ false
144
+ end
145
+
146
+ # Read characters until end of line, and update the mark when the input changes
147
+ # @param tty [IO] Terminal in raw mode
148
+ # @param line [String] Input, filled
149
+ # @param shown [Mark] Mark displayed
150
+ # @yieldparam text [String] Input
151
+ # @yieldreturn [Mark] Mark of the input
152
+ # @return [nil]
153
+ def read_masked(tty, line, shown)
154
+ loop do
155
+ before = line.dup
156
+ char = tty.getc
157
+ case char
158
+ when nil, "\r", "\n" then break
159
+ when "\u0003" then raise Interrupt
160
+ # end of input: Ctrl-D (Unix), Ctrl-Z (Windows)
161
+ when "\u0004", "\u001a"
162
+ break unless line.empty?
163
+ raise Aspera::Error, 'Unexpected end of standard input'
164
+ when *ERASE_CHARS then line.chop!
165
+ # Ctrl-W: erase the last word (and spaces after it), like the terminal does
166
+ when "\u0017" then line.sub!(/\S*\s*\z/, '')
167
+ # Ctrl-U: erase all, e.g. to paste again
168
+ when "\u0015" then line.clear
169
+ else
170
+ # ignore other control characters (and escape sequences start)
171
+ line << char unless char.ord < 32
172
+ end
173
+ next if line.eql?(before)
174
+ mark = yield(line)
175
+ next if mark.eql?(shown)
176
+ $stderr.print(shown.erase, mark)
177
+ shown = mark
178
+ end
179
+ nil
180
+ ensure
181
+ # raw mode: no output processing, a line feed alone does not go back to the first column
182
+ $stderr.print("\r\n")
183
+ end
36
184
  end
37
185
  end
38
186
  end
@@ -1,12 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/assert'
4
- require 'aspera/nagios'
5
- require 'aspera/log'
6
- require 'aspera/environment'
7
- require 'aspera/uri_reader'
8
- require 'aspera/preview/terminal'
9
- require 'aspera/dot_container'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'error'
7
+ require_relative '../assert'
8
+ require_relative '../nagios'
9
+ require_relative '../log'
10
+ require_relative '../environment'
11
+ require_relative '../uri_reader'
12
+ require_relative '../preview/terminal'
13
+ require_relative '../dot_container'
10
14
  require 'base64'
11
15
  require 'uri'
12
16
  require 'pp'
@@ -187,7 +191,7 @@ module Aspera
187
191
 
188
192
  # Text result
189
193
  class Text < Result
190
- # @param data [String, Numeric, Symbol, Boolean] The value, hidden if it is a secret declared to `SecretHider`
194
+ # @param data [String, Numeric, Symbol, Boolean] The value, hidden if it is a secret declared to `Secret::Hider`
191
195
  def initialize(data)
192
196
  Aspera.assert_type(data, *SCALAR_TYPES, type: ArgumentError) { 'text result data' }
193
197
  super(data: data)
@@ -1,30 +1,33 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/command_spec'
4
- require 'aspera/cli/context'
5
- require 'aspera/cli/parser'
6
- require 'aspera/cli/formatter'
7
- require 'aspera/cli/table_fitter'
8
- require 'aspera/cli/plugins/factory'
9
- require 'aspera/cli/bootstrapper'
10
- require 'aspera/rest/aspera_errors' # registers error handlers of Aspera REST APIs
11
- require 'aspera/cli/plugins/config'
12
- require 'aspera/cli/mailer'
13
- require 'aspera/cli/secret_finder'
14
- require 'aspera/cli/extended_value'
15
- require 'aspera/cli/security'
16
- require 'aspera/cli/transfer_agent'
17
- require 'aspera/cli/version'
18
- require 'aspera/cli/info'
19
- require 'aspera/cli/hints'
20
- require 'aspera/cli/result'
21
- require 'aspera/transfer/result'
22
- require 'aspera/duration'
23
- require 'aspera/secret_hider'
24
- require 'aspera/log'
25
- require 'aspera/assert'
26
- require 'aspera/schema/documentation'
27
- require 'aspera/schema/registry'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'command_spec'
7
+ require_relative 'context'
8
+ require_relative 'parser'
9
+ require_relative 'formatter'
10
+ require_relative 'table_fitter'
11
+ require_relative 'plugins/factory'
12
+ require_relative 'bootstrapper'
13
+ require_relative '../rest/aspera_errors' # registers error handlers of Aspera REST APIs
14
+ require_relative 'plugins/config'
15
+ require_relative 'mailer'
16
+ require_relative 'secret_finder'
17
+ require_relative 'extended_value'
18
+ require_relative 'security'
19
+ require_relative 'transfer_agent'
20
+ require_relative 'version'
21
+ require_relative 'info'
22
+ require_relative 'hints'
23
+ require_relative 'result'
24
+ require_relative '../transfer/result'
25
+ require_relative '../units/duration'
26
+ require_relative '../secret/hider'
27
+ require_relative '../log'
28
+ require_relative '../assert'
29
+ require_relative '../schema/documentation'
30
+ require_relative '../schema/registry'
28
31
  require 'net/ssh/errors'
29
32
  require 'net/protocol'
30
33
  require 'openssl'
@@ -49,6 +52,9 @@ module Aspera
49
52
  raise transfer_result.exception
50
53
  when Transfer::Result::Success
51
54
  return Result::Nothing.new
55
+ when Transfer::Result::DryRun
56
+ # Secrets are hidden by the formatter, as in any result
57
+ return Result::SingleObject.new(transfer_result.transfer_spec)
52
58
  else
53
59
  raise "Unexpected transfer result type: #{transfer_result.class}"
54
60
  end
@@ -80,6 +86,8 @@ module Aspera
80
86
  item[STATUS_FIELD] = 'success'
81
87
  when Transfer::Result::Async
82
88
  item[STATUS_FIELD] = "async:#{tr.job_id}"
89
+ when Transfer::Result::DryRun
90
+ item[STATUS_FIELD] = 'dry_run'
83
91
  else
84
92
  item[STATUS_FIELD] = tr.to_s
85
93
  end
@@ -93,8 +101,8 @@ module Aspera
93
101
  # @param argv [Array<String>] command line arguments
94
102
  # @return [nil]
95
103
  def initialize(argv)
104
+ # Dumped (trace2) with secrets hidden by `CommandLine`
96
105
  @argv = argv
97
- Log.dump(:argv, @argv, level: :trace2)
98
106
  @option_help = false
99
107
  @option_show_config = false
100
108
  @context = Context.new
@@ -152,8 +160,8 @@ module Aspera
152
160
  end
153
161
  pid_file = @context.options.get_option(:pid_file)
154
162
  if !pid_file.nil?
155
- File.write(pid_file, Process.pid)
156
- Log.log.debug { "Wrote pid #{Process.pid} to #{pid_file}" }
163
+ File.write(pid_file, ::Process.pid)
164
+ Log.log.debug { "Wrote pid #{::Process.pid} to #{pid_file}" }
157
165
  at_exit { File.delete(pid_file) }
158
166
  end
159
167
  begin
@@ -181,6 +189,7 @@ module Aspera
181
189
  rescue Cli::MissingArgument => e; exception_info = {e: e, t: 'Missing', exit: ExitCode::USAGE}
182
190
  rescue Cli::BadIdentifier, EntityNotFound => e; exception_info = {e: e, t: 'Identifier', exit: ExitCode::NOT_FOUND}
183
191
  rescue Cli::SchemaRequest => e; exception_info = {e: e, t: 'Schema', exit: ExitCode::SUCCESS}
192
+ rescue Cli::PollConditionNotMet => e; exception_info = {e: e, t: 'Poll', exit: ExitCode::ERROR}
184
193
  rescue Cli::Error => e; exception_info = {e: e, t: 'Tool', usage: true, exit: ExitCode::ERROR}
185
194
  rescue Transfer::Error => e; exception_info = {e: e, t: 'Transfer', exit: ExitCode::TRANSFER}
186
195
  rescue Rest::CallError => e; exception_info = {e: e, t: 'Rest', exit: ExitCode.for_call_error(e)}
@@ -192,6 +201,7 @@ module Aspera
192
201
  unless exception_info.nil?
193
202
  Log.log.warn(exception_info[:e].message) if Log.instance.logger_type.eql?(:syslog) && exception_info[:security]
194
203
  Log.log.error { "#{exception_info[:t]}: #{exception_info[:e].message}" } unless exception_info[:e].is_a?(Cli::SchemaRequest)
204
+ Log.log.info { "Location: #{plugin_location(exception_info[:e])}" } if exception_info[:debug] && plugin_location(exception_info[:e])
195
205
  Log.log.debug { (['Backtrace:'] + exception_info[:e].backtrace).join("\n") } if exception_info[:debug]
196
206
  @context.formatter.display_message(:error, 'Use option -h to get help.') if exception_info[:usage]
197
207
  Hints.hint_for(exception_info[:e], @context.formatter)
@@ -201,8 +211,9 @@ module Aspera
201
211
  end
202
212
  end
203
213
  # 2- processing of unprocessed arguments (skip when help was displayed: sub-commands are not consumed)
214
+ # With `show_config`, the command is not executed: its arguments are not consumed, but unknown options are reported
204
215
  unless @option_help
205
- @context.options&.final_errors&.each do |msg|
216
+ @context.options&.final_errors(after_error: !exception_info.nil? || @option_show_config)&.each do |msg|
206
217
  Log.log.error { "Argument: #{msg}" }
207
218
  exception_info = {e: Exception.new(msg), t: 'UnusedArg', exit: ExitCode::USAGE} if exception_info.nil?
208
219
  end
@@ -218,7 +229,7 @@ module Aspera
218
229
  exit_code = exception_info[:exit]
219
230
  # Nagios plugins report the failure of the check itself as UNKNOWN
220
231
  exit_code = Nagios::UNKNOWN if !exit_code.eql?(ExitCode::SUCCESS) && @context.formatter&.format_type.eql?(:nagios)
221
- Process.exit(exit_code)
232
+ ::Process.exit(exit_code)
222
233
  end
223
234
  return
224
235
  end
@@ -228,7 +239,7 @@ module Aspera
228
239
  # @return [nil]
229
240
  def show_usage(plugin: nil)
230
241
  @context.formatter.display_message(:error, usage_text(plugin: plugin))
231
- Process.exit(0)
242
+ ::Process.exit(0)
232
243
  end
233
244
 
234
245
  # Return usage as a Result::Text (used by run_with_result, no display, no exit).
@@ -238,7 +249,7 @@ module Aspera
238
249
  Result::Text.new(usage_text(plugin: plugin))
239
250
  end
240
251
 
241
- # `on_set` callback of the `ui` option (dot-notation sub-properties): `mode`, `command`
252
+ # `on_set` callback of the `ui` option (dot-notation sub-properties): `mode`, `web_auth`, `hidden_silent`, `command`
242
253
  # A plain value is the `mode`. Values are validated against schema `UiOptions`.
243
254
  # @param value [Hash] sub-properties to set
244
255
  def option_ui=(value)
@@ -253,9 +264,14 @@ module Aspera
253
264
  when 'browser', 'graphical' then :graphical
254
265
  else Aspera.error_unexpected_value(v, type: BadArgument) { 'ui.mode' }
255
266
  end
267
+ when :web_auth
268
+ Aspera.assert_values(v.to_s, %w[port paste], type: BadArgument) { 'ui.web_auth' }
269
+ Environment.instance.web_auth = v.to_sym
270
+ when :hidden_silent
271
+ Environment.instance.hidden_silent = BoolValue.true?(Parser.get_from_list(v.to_s, 'ui hidden_silent', BoolValue::ALL))
256
272
  when :command
257
273
  Environment.instance.browser_command = v.nil? || v.empty? ? nil : v.map(&:to_s)
258
- else Aspera.error_unexpected_value(k, type: BadArgument) { 'ui sub-option (mode, command)' }
274
+ else Aspera.error_unexpected_value(k, type: BadArgument) { 'ui sub-option (mode, web_auth, hidden_silent, command)' }
259
275
  end
260
276
  end
261
277
  end
@@ -269,7 +285,7 @@ module Aspera
269
285
  when :level then Log.instance.level = v.to_sym
270
286
  when :type then Log.instance.logger_type = v.to_sym
271
287
  when :format then Log.instance.formatter = v
272
- when :secrets then SecretHider.instance.log_secrets = Parser.get_from_list(v.to_s, 'log secrets', BoolValue::ALL)
288
+ when :secrets then Secret::Hider.instance.log_secrets = Parser.get_from_list(v.to_s, 'log secrets', BoolValue::ALL)
273
289
  else Aspera.error_unexpected_value(k) { 'log sub-option (level, type, format, secrets)' }
274
290
  end
275
291
  end
@@ -289,7 +305,7 @@ module Aspera
289
305
  case v
290
306
  when nil, false then nil
291
307
  when Numeric then v
292
- else Duration.to_unit(v, 's')
308
+ else Units::Duration.new(v).to_unit('s')
293
309
  end
294
310
  else Aspera.error_unexpected_value(k, type: BadArgument) { 'temp sub-option (folder, clean, expiry)' }
295
311
  end
@@ -300,6 +316,14 @@ module Aspera
300
316
 
301
317
  private
302
318
 
319
+ # Location of an unexpected error in the code of a plugin (built-in or from option `plugin_folder`)
320
+ # @param error [Exception] Error
321
+ # @return [String, nil] First line of the backtrace in a plugin folder, e.g. `<FOLDER>/my_plugin.rb:12:in 'action_list'`, `nil` if none
322
+ def plugin_location(error)
323
+ folders = Plugins::Factory.instance.lookup_folders.map { |folder| File.join(folder, '') }
324
+ error.backtrace&.find { |line| folders.any? { |folder| line.start_with?(folder) } }
325
+ end
326
+
303
327
  # Build the usage/help text.
304
328
  #
305
329
  # - No plugin: global options + list of top-level plugins
@@ -382,6 +406,8 @@ module Aspera
382
406
  # @param arg [ArgumentSpec]
383
407
  # @return [Array<String>]
384
408
  def schema_help_lines(arg)
409
+ description = free_form_description(arg.schema)
410
+ return ["\n SCHEMA: #{arg.name}", description.lines.map { |line| " #{line.chomp}" }.join("\n")] unless description.nil?
385
411
  builder = schema_documentation(arg.schema)
386
412
  rows = builder.rows.map do |row|
387
413
  builder.columns.map { |column| Array(row[column]).join("\n") }
@@ -400,11 +426,29 @@ module Aspera
400
426
  Log.log.warn { 'Sorry, no schema provided yet. Please refer to the manual or API.' }
401
427
  return
402
428
  end
429
+ description = free_form_description(schema_path)
430
+ unless description.nil?
431
+ @context.formatter.display_message(:data, description)
432
+ return
433
+ end
403
434
  builder = schema_documentation(schema_path)
404
435
  @context.formatter.display_results(Result::ObjectList.new(builder.rows, fields: builder.columns))
405
436
  nil
406
437
  end
407
438
 
439
+ # A free-form structure (`additionalProperties`, no `properties`) has no property to list: its description is the help.
440
+ # @param schema_path [String] Path of the schema in the registry
441
+ # @return [String, nil] Description of the schema for the terminal, followed by its examples (JSON), `nil` if the schema has properties to list
442
+ def free_form_description(schema_path)
443
+ node = Schema::Registry.instance.reader(schema_path).current
444
+ return if %w[properties allOf oneOf].any? { |key| node.key?(key) }
445
+ # OpenAPI 3.1: `examples` array (3.0: `example`)
446
+ examples = node.key?('examples') ? Array(node['examples']) : [node['example']].compact
447
+ text = TerminalFormatter.markdown_text(node['description'])
448
+ examples.each { |example| text += "\nExample: #{JSON.generate(example)}" }
449
+ text
450
+ end
451
+
408
452
  # @param schema_path [String] Path of the schema in the registry
409
453
  # @return [Schema::Documentation] Documentation of the schema, for the terminal
410
454
  def schema_documentation(schema_path)
@@ -422,22 +466,17 @@ module Aspera
422
466
  @context.formatter = Formatter.new
423
467
  # Create command line manager with arguments
424
468
  @context.options = Parser.new(Info::CMD_NAME, @argv)
425
- ExtendedValue.instance.on(EXTEND_ARGS) { |v| @context.options.args_as_extended(v) }
469
+ ExtendedValue.instance.on(EXTEND_ARGS, description: 'Structure from next arguments: <path>=<value>..., then end marker') { |v| @context.options.args_as_extended(v) }
426
470
  @context.formatter.declare_options(@context.options)
427
471
  # Compare $0 with expected name
428
472
  current_prog_name = File.basename($PROGRAM_NAME)
429
473
  Aspera.assert(current_prog_name.eql?(Info::CMD_NAME), type: :warn) { "Please use '#{Info::CMD_NAME}' instead of '#{current_prog_name}'" }
430
474
  # Declare and parse global options
431
475
  declare_global_options
432
- # Bootstrap: populate context services (main_folder, persistency, presets, http_config,
476
+ # Bootstrap: populate context services (main_folder, persistency, presets, vault, http_config,
433
477
  # progress_bar) and configure global singletons before any plugin is instantiated.
434
- # The vault callback is lazy: @vault extended-values are only resolved after Config.new,
435
- # so @context.config is always set by the time it is called.
436
478
  @bootstrapper = Bootstrapper.new(@context)
437
- @bootstrapper.run(
438
- gem_plugins_folder: Plugins::Config.gem_plugins_folder,
439
- vault_value_cb: ->(v) { @context.config.vault_value(v) }
440
- )
479
+ @bootstrapper.run(gem_plugins_folder: Plugins::Config.gem_plugins_folder)
441
480
  # Do not display config commands if help is asked
442
481
  @context.man_header = false
443
482
  # Config declares remaining plugin options on top of what Bootstrapper already parsed
@@ -472,6 +511,7 @@ module Aspera
472
511
  #{t}execute: #{Info::CMD_NAME} conf doc
473
512
  #{t}or visit: #{Info::DOC_URL}
474
513
  #{t}source repo: #{Info::SRC_URL}
514
+ #{t}AI assistants: #{Info::CMD_NAME} config commands, #{Info::LLMS_URL}
475
515
 
476
516
  ENVIRONMENT VARIABLES
477
517
  #{t}Any option can be set as an environment variable, refer to the manual
@@ -503,9 +543,9 @@ module Aspera
503
543
  @context.help_requested = true
504
544
  end
505
545
  @context.options.declare(:show_config, description: 'Display parameters used for the provided action', allowed: Type::NONE) { @option_show_config = true }
506
- @context.options.declare(:version, description: 'Display version', allowed: Type::NONE, short: 'v') { @context.formatter.display_message(:data, Cli::VERSION); Process.exit(0) } # rubocop:disable Style/Semicolon
546
+ @context.options.declare(:version, description: 'Display version', allowed: Type::NONE, short: 'v') { @context.formatter.display_message(:data, Cli::VERSION); ::Process.exit(0) } # rubocop:disable Style/Semicolon
507
547
  @context.options.declare(
508
- :ui, description: 'User interface (dot-notation: mode, command)',
548
+ :ui, description: 'User interface (dot-notation: mode, web_auth, hidden_silent, command)',
509
549
  allowed: [Hash, String], shorthand: 'mode', schema: Schema::Registry::UI_OPTIONS,
510
550
  on_set: method(:option_ui=)
511
551
  )
@@ -521,15 +561,16 @@ module Aspera
521
561
  @context.options.declare(:security, description: 'Security restrictions (dot-notation: level, allowed_paths)', on_set: Security.instance.method(:options=), schema: Schema::Registry::SECURITY_OPTIONS)
522
562
  @context.options.declare(:lock_port, description: 'Prevent dual execution of a command, e.g. in cron', allowed: Type::INTEGER)
523
563
  @context.options.declare(:once_only, description: 'Process only new items (some commands)', allowed: Type::BOOLEAN, default: false)
524
- @context.options.declare(:log_secrets, description: 'Show passwords in logs', allowed: Type::BOOLEAN, default: SecretHider.instance.log_secrets, on_set: SecretHider.instance.method(:log_secrets=))
564
+ @context.options.declare(:dry_run, description: 'Do not perform changes, only show what would be done', allowed: Type::BOOLEAN, default: false)
565
+ @context.options.declare(:log_secrets, description: 'Show passwords in logs', allowed: Type::BOOLEAN, default: Secret::Hider.instance.log_secrets, on_set: Secret::Hider.instance.method(:log_secrets=))
525
566
  @context.options.declare(
526
567
  :temp, description: 'Temporary files (dot-notation: folder, clean, expiry)',
527
568
  allowed: [Hash, String], shorthand: 'folder', schema: Schema::Registry::TEMP_OPTIONS,
528
569
  on_set: method(:option_temp=)
529
570
  )
530
571
  @context.options.declare(:clean_temp, description: 'Cleanup temporary files on exit', allowed: Type::BOOLEAN, on_set: TempFileManager.instance.method(:cleanup_on_exit=), deprecation: {last: '4.27.5', message: 'use --temp.clean'})
531
- @context.options.declare(:temp_folder, description: 'Temporary folder', on_set: TempFileManager.instance.method(:global_temp=), deprecation: {last: '4.27.5', message: 'use --temp.folder'})
532
- @context.options.declare(:pid_file, description: 'Write process identifier to file, delete on exit')
572
+ @context.options.declare(:temp_folder, description: 'Temporary folder', on_set: TempFileManager.instance.method(:global_temp=), deprecation: {last: '4.27.5', message: 'use --temp.folder'}, complete: :folder)
573
+ @context.options.declare(:pid_file, description: 'Write process identifier to file, delete on exit', complete: :file, security: :low)
533
574
  @context.options.declare(
534
575
  :parser, description: 'Default parser for structured parameters and options',
535
576
  on_set: ExtendedValue.instance.method(:default_decoder=),
@@ -1,6 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/log'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../log'
4
7
 
5
8
  module Aspera
6
9
  module Cli