aspera-cli 4.27.5 → 4.29.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 (249) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +301 -4
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +139 -58
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +10 -7
  13. data/docs/README.md +2551 -772
  14. data/docs/test-mcp-with-ai.md +13 -11
  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 +34 -22
  19. data/lib/aspera/agent/factory.rb +8 -4
  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 +8 -5
  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 +23 -19
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +84 -42
  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 +354 -0
  41. data/lib/aspera/ascp/management.rb +102 -48
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +16 -37
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -34
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +49 -4
  50. data/lib/aspera/cli/command_spec.rb +34 -4
  51. data/lib/aspera/cli/completion/ascli.bash +53 -5
  52. data/lib/aspera/cli/completion/ascli.fish +27 -8
  53. data/lib/aspera/cli/completion/ascli.ps1 +63 -0
  54. data/lib/aspera/cli/completion/ascli.zsh +36 -4
  55. data/lib/aspera/cli/completion_actions.rb +594 -0
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +45 -0
  59. data/lib/aspera/cli/extended_value.rb +83 -24
  60. data/lib/aspera/cli/formatter.rb +142 -73
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -11
  63. data/lib/aspera/cli/http.rb +17 -13
  64. data/lib/aspera/cli/info.rb +17 -6
  65. data/lib/aspera/cli/mailer.rb +7 -4
  66. data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
  67. data/lib/aspera/cli/mcp/secrets.rb +146 -0
  68. data/lib/aspera/cli/mcp/tool.rb +232 -0
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +72 -11
  73. data/lib/aspera/cli/options.schema.yaml +856 -81
  74. data/lib/aspera/cli/parser.rb +64 -31
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +250 -44
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +51 -25
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +207 -141
  81. data/lib/aspera/cli/plugins/console.rb +9 -4
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +22 -8
  84. data/lib/aspera/cli/plugins/faspex5.rb +37 -44
  85. data/lib/aspera/cli/plugins/faspio.rb +41 -8
  86. data/lib/aspera/cli/plugins/httpgw.rb +8 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +186 -121
  88. data/lib/aspera/cli/plugins/node.rb +41 -34
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +66 -12
  93. data/lib/aspera/cli/plugins/shares.rb +288 -48
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +155 -33
  96. data/lib/aspera/cli/preset_manager.rb +72 -16
  97. data/lib/aspera/cli/prompt.rb +7 -2
  98. data/lib/aspera/cli/result.rb +28 -11
  99. data/lib/aspera/cli/runner.rb +193 -80
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +204 -0
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +119 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +32 -40
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +31 -19
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +197 -50
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.html.erb +61 -0
  113. data/lib/aspera/cli/web_secret.rb +222 -0
  114. data/lib/aspera/cli/wizard.rb +58 -45
  115. data/lib/aspera/command_line_builder.rb +35 -5
  116. data/lib/aspera/command_line_converter.rb +4 -1
  117. data/lib/aspera/coverage.rb +103 -33
  118. data/lib/aspera/data_repository.rb +42 -25
  119. data/lib/aspera/dot_container.rb +4 -1
  120. data/lib/aspera/duration.rb +45 -0
  121. data/lib/aspera/environment.rb +106 -33
  122. data/lib/aspera/exec_spec.rb +9 -5
  123. data/lib/aspera/faspex_gw.rb +105 -35
  124. data/lib/aspera/faspex_postproc.rb +193 -47
  125. data/lib/aspera/formatter_interface.rb +4 -2
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +6 -3
  129. data/lib/aspera/json_rpc/client.rb +55 -35
  130. data/lib/aspera/json_rpc/version.rb +4 -0
  131. data/lib/aspera/line_logger.rb +4 -1
  132. data/lib/aspera/link_header.rb +4 -1
  133. data/lib/aspera/log.rb +20 -10
  134. data/lib/aspera/markdown.rb +155 -115
  135. data/lib/aspera/mime.rb +9 -0
  136. data/lib/aspera/nagios.rb +9 -5
  137. data/lib/aspera/node_emulator.rb +111 -112
  138. data/lib/aspera/oauth/client/base.rb +163 -0
  139. data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
  140. data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
  141. data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
  142. data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
  143. data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
  144. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  145. data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
  146. data/lib/aspera/oauth/client/web.rb +84 -0
  147. data/lib/aspera/oauth/server/authorize.html.erb +34 -0
  148. data/lib/aspera/oauth/server/pkce.rb +427 -0
  149. data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
  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 +11 -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 +4 -1
  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 +30 -1
  165. data/lib/aspera/rest/aspera_errors.rb +55 -60
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +42 -42
  168. data/lib/aspera/rest/error_analyzer.rb +14 -2
  169. data/lib/aspera/rest/list.rb +14 -10
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +13 -4
  172. data/lib/aspera/rest.rb +9 -7
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
  175. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
  176. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  177. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  178. data/lib/aspera/schema/IBM_Aspera_Shares.yaml +819 -7
  179. data/lib/aspera/schema/async_tables.yaml +11 -10
  180. data/lib/aspera/schema/documentation.rb +56 -78
  181. data/lib/aspera/schema/reader.rb +46 -11
  182. data/lib/aspera/schema/registry.rb +45 -24
  183. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  184. data/lib/aspera/schema/validator.rb +4 -1
  185. data/lib/aspera/sealed_hash.rb +166 -0
  186. data/lib/aspera/secret/hider.rb +201 -0
  187. data/lib/aspera/secret/reference.rb +150 -0
  188. data/lib/aspera/secret/resolver.rb +212 -0
  189. data/lib/aspera/secret/store/base.rb +153 -0
  190. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  191. data/lib/aspera/secret/store/factory.rb +103 -0
  192. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  193. data/lib/aspera/secret/store/keeper.rb +141 -0
  194. data/lib/aspera/secret/store/macos_security.rb +284 -0
  195. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  196. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  197. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  198. data/lib/aspera/secret/store/secret_service.rb +125 -0
  199. data/lib/aspera/secret/strength.rb +119 -0
  200. data/lib/aspera/servlet_helpers.rb +114 -0
  201. data/lib/aspera/ssh.rb +10 -7
  202. data/lib/aspera/ssl.rb +5 -2
  203. data/lib/aspera/string_ext.rb +3 -0
  204. data/lib/aspera/sync/args.schema.yaml +6 -1
  205. data/lib/aspera/sync/conf.schema.yaml +25 -10
  206. data/lib/aspera/sync/database.rb +3 -0
  207. data/lib/aspera/sync/operations.rb +34 -12
  208. data/lib/aspera/temp_file_manager.rb +85 -22
  209. data/lib/aspera/timer_limiter.rb +3 -0
  210. data/lib/aspera/transfer/error.rb +4 -1
  211. data/lib/aspera/transfer/faux_file.rb +4 -1
  212. data/lib/aspera/transfer/parameters.rb +22 -14
  213. data/lib/aspera/transfer/result.rb +3 -0
  214. data/lib/aspera/transfer/resumer.rb +6 -4
  215. data/lib/aspera/transfer/spec.rb +45 -18
  216. data/lib/aspera/transfer/spec.schema.yaml +8 -5
  217. data/lib/aspera/transfer/units.rb +75 -0
  218. data/lib/aspera/uri_reader.rb +57 -7
  219. data/lib/aspera/web_auth/index.html.erb +20 -0
  220. data/lib/aspera/web_auth/paste.rb +109 -0
  221. data/lib/aspera/web_auth/receiver.rb +50 -0
  222. data/lib/aspera/web_auth/relay.rb +76 -0
  223. data/lib/aspera/web_auth/reply.html.erb +150 -0
  224. data/lib/aspera/web_auth/server.rb +59 -14
  225. data/lib/aspera/web_page.html.erb +262 -0
  226. data/lib/aspera/web_page.rb +66 -0
  227. data/lib/aspera/web_server_simple.rb +82 -13
  228. data/lib/aspera/yaml.rb +5 -1
  229. data/llms.txt +81 -0
  230. data/skills/ascli/SKILL.md +88 -0
  231. data.tar.gz.sig +0 -0
  232. metadata +116 -48
  233. metadata.gz.sig +0 -0
  234. data/lib/aspera/cli/mcp_tool.rb +0 -189
  235. data/lib/aspera/keychain/base.rb +0 -25
  236. data/lib/aspera/keychain/encrypted_hash.rb +0 -188
  237. data/lib/aspera/keychain/factory.rb +0 -59
  238. data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
  239. data/lib/aspera/keychain/macos_security.rb +0 -171
  240. data/lib/aspera/keychain/one_password_api.rb +0 -86
  241. data/lib/aspera/keychain/one_password_base.rb +0 -34
  242. data/lib/aspera/keychain/one_password_cli.rb +0 -98
  243. data/lib/aspera/oauth/base.rb +0 -141
  244. data/lib/aspera/oauth/web.rb +0 -57
  245. data/lib/aspera/oauth.rb +0 -9
  246. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
  247. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
  248. data/lib/aspera/secret_hider.rb +0 -117
  249. data/lib/aspera/web_auth/index.html +0 -147
@@ -1,19 +1,24 @@
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'
3
7
  require 'io/console'
4
- require 'aspera/assert'
5
8
 
6
9
  module Aspera
7
10
  module Cli
8
11
  # Console input
9
12
  module Prompt
13
+ extend self
14
+
10
15
  # Prompt user for console input
11
16
  # The prompt is displayed on `stderr`, like for sensitive input, so that `stdout` contains only results.
12
17
  # @param prompt [String] prompt string to display
13
18
  # @param sensitive [Boolean] whether to hide typed input
14
19
  # @return [String] user input stripped of trailing newline
15
20
  def prompt_user_input(prompt, sensitive: false)
16
- return $stdin.getpass("#{prompt}> ") if sensitive
21
+ return $stdin.getpass("#{prompt}> ") if sensitive && $stdin.tty?
17
22
  $stderr.print("#{prompt}> ")
18
23
  line = $stdin.gets
19
24
  Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
@@ -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'
@@ -29,6 +33,12 @@ module Aspera
29
33
  @fields = fields
30
34
  end
31
35
 
36
+ # @param data [Object] New data
37
+ # @return [Result] Copy of this result, with other data (e.g. with secrets hidden)
38
+ def with_data(data)
39
+ dup.tap { |r| r.data = data }
40
+ end
41
+
32
42
  # Format this result using the provided formatter
33
43
  # This method implements the Visitor pattern, allowing each Result subclass
34
44
  # to define how it should be formatted without the Formatter needing to know
@@ -81,6 +91,13 @@ module Aspera
81
91
 
82
92
  # Formats rendering the data structure itself
83
93
  STRUCTURED_FORMATS = %i[ruby json jsonpp yaml].freeze
94
+ # Types of a single value result (Text), or of items of a value list
95
+ SCALAR_TYPES = [String, Integer, Float, Symbol, TrueClass, FalseClass].freeze
96
+
97
+ protected
98
+
99
+ # Used by `with_data`
100
+ attr_writer :data
84
101
 
85
102
  private
86
103
 
@@ -174,8 +191,9 @@ module Aspera
174
191
 
175
192
  # Text result
176
193
  class Text < Result
194
+ # @param data [String, Numeric, Symbol, Boolean] The value, hidden if it is a secret declared to `Secret::Hider`
177
195
  def initialize(data)
178
- Aspera.assert_type(data, String, Integer, Symbol, type: ArgumentError) { 'text result data' }
196
+ Aspera.assert_type(data, *SCALAR_TYPES, type: ArgumentError) { 'text result data' }
179
197
  super(data: data)
180
198
  end
181
199
 
@@ -351,12 +369,11 @@ module Aspera
351
369
  all_types = data.map(&:class).uniq
352
370
  return ObjectList.new(data) if all_types.eql?([Hash])
353
371
 
354
- scalar_types = [String, Integer, Symbol]
355
- unsupported_types = all_types - scalar_types
372
+ unsupported_types = all_types - SCALAR_TYPES
356
373
  return ValueList.new(data, name: 'list') if unsupported_types.empty?
357
374
 
358
375
  Aspera.error_unexpected_value(unsupported_types) { 'list item types' }
359
- when String, Integer, Symbol
376
+ when *SCALAR_TYPES
360
377
  Text.new(data)
361
378
  else
362
379
  Aspera.error_unexpected_value(data.class.name) { 'result type' }
@@ -1,27 +1,35 @@
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/plugins/factory'
8
- require 'aspera/cli/bootstrapper'
9
- require 'aspera/cli/plugins/config'
10
- require 'aspera/cli/mailer'
11
- require 'aspera/cli/secret_finder'
12
- require 'aspera/cli/extended_value'
13
- require 'aspera/cli/transfer_agent'
14
- require 'aspera/cli/version'
15
- require 'aspera/cli/info'
16
- require 'aspera/cli/hints'
17
- require 'aspera/cli/result'
18
- require 'aspera/transfer/result'
19
- require 'aspera/secret_hider'
20
- require 'aspera/log'
21
- require 'aspera/assert'
22
- require 'aspera/schema/documentation'
23
- 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 '../duration'
26
+ require_relative '../secret/hider'
27
+ require_relative '../log'
28
+ require_relative '../assert'
29
+ require_relative '../schema/documentation'
30
+ require_relative '../schema/registry'
24
31
  require 'net/ssh/errors'
32
+ require 'net/protocol'
25
33
  require 'openssl'
26
34
 
27
35
  module Aspera
@@ -49,6 +57,17 @@ module Aspera
49
57
  end
50
58
  end
51
59
 
60
+ # Result of a command that creates an object and transfers its files, e.g. `packages send`.
61
+ # @param object [Hash] Created object
62
+ # @param transfer_result [Transfer::Result] Typed result from TransferAgent#start
63
+ # @raise [StandardError] if the transfer failed
64
+ # @return [Result::SingleObject] The object, with field `transfer` (`job_id`) if the transfer is asynchronous
65
+ def result_object_transfer(object, transfer_result)
66
+ status = result_transfer(transfer_result)
67
+ object = object.merge('transfer' => status.data) if status.is_a?(Result::SingleObject)
68
+ Result::SingleObject.new(object)
69
+ end
70
+
52
71
  # Used when one command executes several transfer jobs (each job being possibly multi session)
53
72
  # @param status_table [Array] [{STATUS_FIELD=>Transfer::Result,...},...]
54
73
  # @return [Result] a status object suitable as command result
@@ -94,7 +113,8 @@ module Aspera
94
113
  Plugins::Factory.instance.add_plugins_from_lookup_folders
95
114
  # Help requested without command? Show global options + plugin list
96
115
  return result_usage if @option_help && @context.options.command_or_arg_empty?
97
- @context.config.periodic_check_newer_gem_version
116
+ # Shell completion is executed on each `Tab`: no network access
117
+ @context.config.periodic_check_newer_gem_version unless @context.options.next_arguments?(COMPLETION_COMMAND)
98
118
  command_sym =
99
119
  if @option_show_config && @context.options.command_or_arg_empty?
100
120
  COMMAND_CONFIG
@@ -135,8 +155,8 @@ module Aspera
135
155
  end
136
156
  pid_file = @context.options.get_option(:pid_file)
137
157
  if !pid_file.nil?
138
- File.write(pid_file, Process.pid)
139
- Log.log.debug { "Wrote pid #{Process.pid} to #{pid_file}" }
158
+ File.write(pid_file, ::Process.pid)
159
+ Log.log.debug { "Wrote pid #{::Process.pid} to #{pid_file}" }
140
160
  at_exit { File.delete(pid_file) }
141
161
  end
142
162
  begin
@@ -158,18 +178,18 @@ module Aspera
158
178
  begin
159
179
  result = run_with_result
160
180
  @context.formatter.display_results(result) if result
161
- rescue Net::SSH::AuthenticationFailed => e; exception_info = {e: e, t: 'SSH', security: true}
162
- rescue OpenSSL::SSL::SSLError => e; exception_info = {e: e, t: 'SSL'}
163
- rescue Cli::BadArgument => e; exception_info = {e: e, t: 'Argument', usage: true}
164
- rescue Cli::MissingArgument => e; exception_info = {e: e, t: 'Missing'}
165
- rescue Cli::BadIdentifier => e; exception_info = {e: e, t: 'Identifier'}
166
- rescue Cli::SchemaRequest => e; exception_info = {e: e, t: 'Schema'}
167
- rescue Cli::Error => e; exception_info = {e: e, t: 'Tool', usage: true}
168
- rescue Transfer::Error => e; exception_info = {e: e, t: 'Transfer'}
169
- rescue Rest::CallError => e; exception_info = {e: e, t: 'Rest'}
170
- rescue SocketError => e; exception_info = {e: e, t: 'Network'}
171
- rescue StandardError => e; exception_info = {e: e, t: "Other(#{e.class.name})", debug: true}
172
- rescue Interrupt => e; exception_info = {e: e, t: 'Interruption', debug: true}
181
+ rescue Net::SSH::AuthenticationFailed => e; exception_info = {e: e, t: 'SSH', security: true, exit: ExitCode::AUTH}
182
+ rescue OpenSSL::SSL::SSLError => e; exception_info = {e: e, t: 'SSL', exit: ExitCode::NETWORK}
183
+ rescue Cli::BadArgument => e; exception_info = {e: e, t: 'Argument', usage: true, exit: ExitCode::USAGE}
184
+ rescue Cli::MissingArgument => e; exception_info = {e: e, t: 'Missing', exit: ExitCode::USAGE}
185
+ rescue Cli::BadIdentifier, EntityNotFound => e; exception_info = {e: e, t: 'Identifier', exit: ExitCode::NOT_FOUND}
186
+ rescue Cli::SchemaRequest => e; exception_info = {e: e, t: 'Schema', exit: ExitCode::SUCCESS}
187
+ rescue Cli::Error => e; exception_info = {e: e, t: 'Tool', usage: true, exit: ExitCode::ERROR}
188
+ rescue Transfer::Error => e; exception_info = {e: e, t: 'Transfer', exit: ExitCode::TRANSFER}
189
+ rescue Rest::CallError => e; exception_info = {e: e, t: 'Rest', exit: ExitCode.for_call_error(e)}
190
+ rescue *NETWORK_ERRORS => e; exception_info = {e: e, t: 'Network', exit: ExitCode::NETWORK}
191
+ rescue StandardError => e; exception_info = {e: e, t: "Other(#{e.class.name})", debug: true, exit: ExitCode::ERROR}
192
+ rescue Interrupt => e; exception_info = {e: e, t: 'Interruption', debug: true, exit: ExitCode::INTERRUPTED}
173
193
  end
174
194
  # 1- processing of error condition
175
195
  unless exception_info.nil?
@@ -180,35 +200,28 @@ module Aspera
180
200
  Hints.hint_for(exception_info[:e], @context.formatter)
181
201
  if exception_info[:e].is_a?(Cli::SchemaRequest)
182
202
  Log.log.info { "#{exception_info[:t]}: #{exception_info[:e].message}" }
183
- schema_path = exception_info[:e].path
184
- if schema_path.nil?
185
- Log.log.warn { 'Sorry, no schema provided yet. Please refer to the manual or API.' }
186
- else
187
- reader = Schema::Registry.instance.reader(schema_path)
188
- rows = reader.to_rows.map do |row|
189
- if row.key?('enum')
190
- row = row.dup
191
- row['type'] = 'enum'
192
- row['description'] = "#{row['description']}\nAllowed: #{row['enum'].join(', ')}"
193
- end
194
- row
195
- end
196
- @context.formatter.display_results(Result::ObjectList.new(rows, fields: %w[name type required description]))
197
- end
203
+ display_schema(exception_info[:e].path)
198
204
  end
199
205
  end
200
206
  # 2- processing of unprocessed arguments (skip when help was displayed: sub-commands are not consumed)
201
207
  unless @option_help
202
- @context.options&.final_errors&.each do |msg|
208
+ @context.options&.final_errors(after_error: !exception_info.nil?)&.each do |msg|
203
209
  Log.log.error { "Argument: #{msg}" }
204
- exception_info = {e: Exception.new(msg), t: 'UnusedArg'} if exception_info.nil?
210
+ exception_info = {e: Exception.new(msg), t: 'UnusedArg', exit: ExitCode::USAGE} if exception_info.nil?
205
211
  end
206
212
  end
207
213
  # 3- exit on error
208
214
  unless exception_info.nil?
209
- raise exception_info[:e] if Log.log.debug?
210
- @context.formatter.display_message(:error, 'Use --log-level=debug to get more details.') if exception_info[:debug]
211
- Process.exit(1)
215
+ if Log.log.debug?
216
+ # Same display as an uncaught exception, but keeps the exit code
217
+ $stderr.puts(exception_info[:e].full_message) # rubocop:disable Style/StderrPuts
218
+ elsif exception_info[:debug]
219
+ @context.formatter.display_message(:error, 'Use --log-level=debug to get more details.')
220
+ end
221
+ exit_code = exception_info[:exit]
222
+ # Nagios plugins report the failure of the check itself as UNKNOWN
223
+ exit_code = Nagios::UNKNOWN if !exit_code.eql?(ExitCode::SUCCESS) && @context.formatter&.format_type.eql?(:nagios)
224
+ ::Process.exit(exit_code)
212
225
  end
213
226
  return
214
227
  end
@@ -218,7 +231,7 @@ module Aspera
218
231
  # @return [nil]
219
232
  def show_usage(plugin: nil)
220
233
  @context.formatter.display_message(:error, usage_text(plugin: plugin))
221
- Process.exit(0)
234
+ ::Process.exit(0)
222
235
  end
223
236
 
224
237
  # Return usage as a Result::Text (used by run_with_result, no display, no exit).
@@ -228,6 +241,31 @@ module Aspera
228
241
  Result::Text.new(usage_text(plugin: plugin))
229
242
  end
230
243
 
244
+ # `on_set` callback of the `ui` option (dot-notation sub-properties): `mode`, `web_auth`, `command`
245
+ # A plain value is the `mode`. Values are validated against schema `UiOptions`.
246
+ # @param value [Hash] sub-properties to set
247
+ def option_ui=(value)
248
+ Aspera.assert_type(value, Hash)
249
+ value.each do |k, v|
250
+ case k.to_sym
251
+ when :mode
252
+ Environment.instance.url_method =
253
+ case v.to_s
254
+ when 'auto' then Environment.instance.default_gui_mode
255
+ when 'terminal', 'text' then :text
256
+ when 'browser', 'graphical' then :graphical
257
+ else Aspera.error_unexpected_value(v, type: BadArgument) { 'ui.mode' }
258
+ end
259
+ when :web_auth
260
+ Aspera.assert_values(v.to_s, %w[port paste], type: BadArgument) { 'ui.web_auth' }
261
+ Environment.instance.web_auth = v.to_sym
262
+ when :command
263
+ Environment.instance.browser_command = v.nil? || v.empty? ? nil : v.map(&:to_s)
264
+ else Aspera.error_unexpected_value(k, type: BadArgument) { 'ui sub-option (mode, web_auth, command)' }
265
+ end
266
+ end
267
+ end
268
+
231
269
  # `on_set` callback of the `log` option (dot-notation sub-properties): `level`, `type`, `format`, `secrets`
232
270
  # @param value [Hash] sub-properties to set
233
271
  def option_log=(value)
@@ -237,12 +275,35 @@ module Aspera
237
275
  when :level then Log.instance.level = v.to_sym
238
276
  when :type then Log.instance.logger_type = v.to_sym
239
277
  when :format then Log.instance.formatter = v
240
- when :secrets then SecretHider.instance.log_secrets = Parser.get_from_list(v.to_s, 'log secrets', BoolValue::ALL)
278
+ when :secrets then Secret::Hider.instance.log_secrets = Parser.get_from_list(v.to_s, 'log secrets', BoolValue::ALL)
241
279
  else Aspera.error_unexpected_value(k) { 'log sub-option (level, type, format, secrets)' }
242
280
  end
243
281
  end
244
282
  end
245
283
 
284
+ # `on_set` callback of the `temp` option (dot-notation sub-properties): `folder`, `clean`, `expiry`
285
+ # A plain value is the `folder`. Values are validated against schema `TempOptions`.
286
+ # @param value [Hash] sub-properties to set
287
+ def option_temp=(value)
288
+ Aspera.assert_type(value, Hash)
289
+ value.each do |k, v|
290
+ case k.to_sym
291
+ when :folder then TempFileManager.instance.global_temp = v
292
+ when :clean then TempFileManager.instance.cleanup_on_exit = Parser.get_from_list(v.to_s, 'temp clean', BoolValue::ALL)
293
+ when :expiry
294
+ TempFileManager.instance.expiry_sec =
295
+ case v
296
+ when nil, false then nil
297
+ when Numeric then v
298
+ else Duration.to_unit(v, 's')
299
+ end
300
+ else Aspera.error_unexpected_value(k, type: BadArgument) { 'temp sub-option (folder, clean, expiry)' }
301
+ end
302
+ end
303
+ rescue ParameterError => e
304
+ raise BadArgument, "Option temp: #{e.message}"
305
+ end
306
+
246
307
  private
247
308
 
248
309
  # Build the usage/help text.
@@ -327,16 +388,56 @@ module Aspera
327
388
  # @param arg [ArgumentSpec]
328
389
  # @return [Array<String>]
329
390
  def schema_help_lines(arg)
330
- builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(arg.schema)).build
331
- rows = builder.rows.reject { |row| row['type'].eql?('&nbsp;') }.map do |row|
332
- builder.columns.map { |column| row[column].to_s }
391
+ description = free_form_description(arg.schema)
392
+ return ["\n SCHEMA: #{arg.name}", description.lines.map { |line| " #{line.chomp}" }.join("\n")] unless description.nil?
393
+ builder = schema_documentation(arg.schema)
394
+ rows = builder.rows.map do |row|
395
+ builder.columns.map { |column| Array(row[column]).join("\n") }
333
396
  end
334
397
  style = {}
335
398
  style[:border] = :unicode_round if Environment.terminal_supports_unicode?
336
- table = Terminal::Table.new(headings: builder.columns, rows: rows, style: style).to_s
399
+ table = TableFitter.table(headings: builder.columns, rows: rows, style: style, width: Environment.terminal_columns&.-(4)).to_s
337
400
  ["\n SCHEMA: #{arg.name}", table.lines.map { |line| " #{line.chomp}" }.join("\n")]
338
401
  end
339
402
 
403
+ # Display the documentation of a schema: value `help` given to an option or argument
404
+ # @param schema_path [String, nil] Path of the schema in the registry, `nil` if none
405
+ # @return [nil]
406
+ def display_schema(schema_path)
407
+ if schema_path.nil?
408
+ Log.log.warn { 'Sorry, no schema provided yet. Please refer to the manual or API.' }
409
+ return
410
+ end
411
+ description = free_form_description(schema_path)
412
+ unless description.nil?
413
+ @context.formatter.display_message(:data, description)
414
+ return
415
+ end
416
+ builder = schema_documentation(schema_path)
417
+ @context.formatter.display_results(Result::ObjectList.new(builder.rows, fields: builder.columns))
418
+ nil
419
+ end
420
+
421
+ # A free-form structure (`additionalProperties`, no `properties`) has no property to list: its description is the help.
422
+ # @param schema_path [String] Path of the schema in the registry
423
+ # @return [String, nil] Description of the schema for the terminal, followed by its examples (JSON), `nil` if the schema has properties to list
424
+ def free_form_description(schema_path)
425
+ node = Schema::Registry.instance.reader(schema_path).current
426
+ return if %w[properties allOf oneOf].any? { |key| node.key?(key) }
427
+ # OpenAPI 3.1: `examples` array (3.0: `example`)
428
+ examples = node.key?('examples') ? Array(node['examples']) : [node['example']].compact
429
+ text = TerminalFormatter.markdown_text(node['description'])
430
+ examples.each { |example| text += "\nExample: #{JSON.generate(example)}" }
431
+ text
432
+ end
433
+
434
+ # @param schema_path [String] Path of the schema in the registry
435
+ # @return [Schema::Documentation] Documentation of the schema, for the terminal
436
+ def schema_documentation(schema_path)
437
+ options = schema_path.eql?(Schema::Registry::TRANSFER_SPEC) ? Transfer::Spec.doc_options : {}
438
+ Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(schema_path), **options).build
439
+ end
440
+
340
441
  # Initialize agents and options
341
442
  # This can throw exception if there is a problem with the environment, needs to be caught by execute method
342
443
  # @raise [StandardError] if there is a problem with the environment
@@ -347,22 +448,17 @@ module Aspera
347
448
  @context.formatter = Formatter.new
348
449
  # Create command line manager with arguments
349
450
  @context.options = Parser.new(Info::CMD_NAME, @argv)
350
- ExtendedValue.instance.on(EXTEND_ARGS) { |v| @context.options.args_as_extended(v) }
451
+ ExtendedValue.instance.on(EXTEND_ARGS, description: 'Structure from next arguments: <path>=<value>..., then end marker') { |v| @context.options.args_as_extended(v) }
351
452
  @context.formatter.declare_options(@context.options)
352
453
  # Compare $0 with expected name
353
454
  current_prog_name = File.basename($PROGRAM_NAME)
354
455
  Aspera.assert(current_prog_name.eql?(Info::CMD_NAME), type: :warn) { "Please use '#{Info::CMD_NAME}' instead of '#{current_prog_name}'" }
355
456
  # Declare and parse global options
356
457
  declare_global_options
357
- # Bootstrap: populate context services (main_folder, persistency, presets, http_config,
458
+ # Bootstrap: populate context services (main_folder, persistency, presets, vault, http_config,
358
459
  # progress_bar) and configure global singletons before any plugin is instantiated.
359
- # The vault callback is lazy: @vault extended-values are only resolved after Config.new,
360
- # so @context.config is always set by the time it is called.
361
460
  @bootstrapper = Bootstrapper.new(@context)
362
- @bootstrapper.run(
363
- gem_plugins_folder: Plugins::Config.gem_plugins_folder,
364
- vault_value_cb: ->(v) { @context.config.vault_value(v) }
365
- )
461
+ @bootstrapper.run(gem_plugins_folder: Plugins::Config.gem_plugins_folder)
366
462
  # Do not display config commands if help is asked
367
463
  @context.man_header = false
368
464
  # Config declares remaining plugin options on top of what Bootstrapper already parsed
@@ -397,6 +493,7 @@ module Aspera
397
493
  #{t}execute: #{Info::CMD_NAME} conf doc
398
494
  #{t}or visit: #{Info::DOC_URL}
399
495
  #{t}source repo: #{Info::SRC_URL}
496
+ #{t}AI assistants: #{Info::CMD_NAME} config commands, #{Info::LLMS_URL}
400
497
 
401
498
  ENVIRONMENT VARIABLES
402
499
  #{t}Any option can be set as an environment variable, refer to the manual
@@ -413,6 +510,9 @@ module Aspera
413
510
 
414
511
  ARGS
415
512
  #{t}Some commands require mandatory arguments, e.g. a path.
513
+
514
+ EXIT STATUS
515
+ #{ExitCode::DESCRIPTIONS.map { |code, description| "#{t}#{code.to_s.ljust(5)}#{description}" }.join("\n")}
416
516
  END_OF_BANNER
417
517
  end
418
518
 
@@ -425,11 +525,11 @@ module Aspera
425
525
  @context.help_requested = true
426
526
  end
427
527
  @context.options.declare(:show_config, description: 'Display parameters used for the provided action', allowed: Type::NONE) { @option_show_config = true }
428
- @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
528
+ @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
429
529
  @context.options.declare(
430
- :ui, description: 'Method to start browser',
431
- allowed: USER_INTERFACES, default: Environment.instance.url_method,
432
- on_set: Environment.instance.method(:url_method=)
530
+ :ui, description: 'User interface (dot-notation: mode, web_auth, command)',
531
+ allowed: [Hash, String], shorthand: 'mode', schema: Schema::Registry::UI_OPTIONS,
532
+ on_set: method(:option_ui=)
433
533
  )
434
534
  @context.options.declare(
435
535
  :invalid_characters, description: 'Replacement character and invalid filename characters',
@@ -440,12 +540,19 @@ module Aspera
440
540
  @context.options.declare(:log_format, description: 'Log formatter', allowed: [Proc, Logger::Formatter, String], on_set: Log.instance.method(:formatter=))
441
541
  @context.options.declare(:logger, description: 'Logging method', allowed: Log::LOG_TYPES, on_set: Log.instance.method(:logger_type=))
442
542
  @context.options.declare(:log, description: 'Logging options (dot-notation: level, type, format, secrets)', on_set: method(:option_log=), schema: Schema::Registry::LOG_OPTIONS)
543
+ @context.options.declare(:security, description: 'Security restrictions (dot-notation: level, allowed_paths)', on_set: Security.instance.method(:options=), schema: Schema::Registry::SECURITY_OPTIONS)
443
544
  @context.options.declare(:lock_port, description: 'Prevent dual execution of a command, e.g. in cron', allowed: Type::INTEGER)
444
545
  @context.options.declare(:once_only, description: 'Process only new items (some commands)', allowed: Type::BOOLEAN, default: false)
445
- @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=))
446
- @context.options.declare(:clean_temp, description: 'Cleanup temporary files on exit', allowed: Type::BOOLEAN, default: TempFileManager.instance.cleanup_on_exit, on_set: TempFileManager.instance.method(:cleanup_on_exit=))
447
- @context.options.declare(:temp_folder, description: 'Temporary folder', default: TempFileManager.instance.global_temp, on_set: TempFileManager.instance.method(:global_temp=))
448
- @context.options.declare(:pid_file, description: 'Write process identifier to file, delete on exit')
546
+ @context.options.declare(:dry_run, description: 'Do not perform changes, only show what would be done', allowed: Type::BOOLEAN, default: false)
547
+ @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=))
548
+ @context.options.declare(
549
+ :temp, description: 'Temporary files (dot-notation: folder, clean, expiry)',
550
+ allowed: [Hash, String], shorthand: 'folder', schema: Schema::Registry::TEMP_OPTIONS,
551
+ on_set: method(:option_temp=)
552
+ )
553
+ @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'})
554
+ @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)
555
+ @context.options.declare(:pid_file, description: 'Write process identifier to file, delete on exit', complete: :file, security: :low)
449
556
  @context.options.declare(
450
557
  :parser, description: 'Default parser for structured parameters and options',
451
558
  on_set: ExtendedValue.instance.method(:default_decoder=),
@@ -471,12 +578,18 @@ module Aspera
471
578
  end
472
579
  COMMAND_CONFIG = :config
473
580
  COMMAND_HELP = :help
581
+ # Shell completion commands (scripts and words)
582
+ COMPLETION_COMMAND = %w[config completion].freeze
474
583
  # Types that go to result of type = text
475
584
  SCALAR_TYPES = [String, Integer, Symbol].freeze
476
- USER_INTERFACES = %i[text graphical].freeze
477
585
  EXTEND_ARGS = :''
586
+ # Errors of name resolution, connection and timeout
587
+ NETWORK_ERRORS = [
588
+ SocketError, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
589
+ Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ETIMEDOUT
590
+ ].freeze
478
591
 
479
- private_constant :COMMAND_CONFIG, :COMMAND_HELP, :SCALAR_TYPES, :USER_INTERFACES, :EXTEND_ARGS
592
+ private_constant :COMMAND_CONFIG, :COMMAND_HELP, :COMPLETION_COMMAND, :SCALAR_TYPES, :EXTEND_ARGS, :NETWORK_ERRORS
480
593
  end
481
594
  end
482
595
  end
@@ -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