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
@@ -0,0 +1,232 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../../log'
7
+ require_relative '../../secret/hider'
8
+ require_relative '../runner'
9
+ require_relative '../error'
10
+ require_relative 'secrets'
11
+ require_relative '../../schema/reader'
12
+ require_relative '../../schema/registry'
13
+ require_relative '../plugins/mcp'
14
+ require 'json'
15
+ unless defined?(MCP::Tool)
16
+ begin
17
+ require 'mcp'
18
+ rescue LoadError
19
+ raise Cli::Error, "The 'mcp' and 'rack' gems are required. Install them with: gem install mcp rack"
20
+ end
21
+ end
22
+
23
+ module Aspera
24
+ module Cli
25
+ module Mcp
26
+ # MCP Tool: executes an ascli command in-process.
27
+ class Tool < MCP::Tool
28
+ # Default maximum byte size of the JSON text content returned for list results.
29
+ # Items are appended whole until the limit is reached; the full list is always
30
+ # available in structuredContent.
31
+ DEFAULT_MAX_TEXT_BYTES = 100_000
32
+ # Default extra arguments automatically prepended to every ascli call.
33
+ # Keeps the AI from having to remember mandatory flags on every invocation.
34
+ DEFAULT_EXTRA_ARGS = ['--interactive=no', '--transfer.asynchronous=true'].freeze
35
+
36
+ tool_name 'execute_ascli_command'
37
+
38
+ description <<~DESC.strip
39
+ Execute any ascli (Aspera CLI) command in-process and return its result.
40
+
41
+ #{Plugins::Mcp::COMMAND_DISPLAY_INSTRUCTIONS}
42
+
43
+ SYNTAX
44
+ args is a JSON array of strings mirroring the CLI command line.
45
+ Element 0 : plugin name (aoc, faspex5, node, server, config, …).
46
+ Elements 1+: sub-commands, positional arguments, and --option=value flags in any order.
47
+ Structured values use an extended-value prefix on the relevant element:
48
+ "@json:{...}" — inline JSON object or array (preferred: no shell quoting)
49
+ "@preset:name" — expand a saved preset
50
+ "@base64:..." — base64-encoded value
51
+ "@val:..." — literal string (no further decoding)
52
+ "@secret:name" — secret entered by the user on a web page, never visible to you:
53
+ use it for a secret the user did not give, e.g. "--password=@secret:password"
54
+ Note: @stdin: is disabled; @ruby:, @file:, @uri:, @env: depend on the security level of the server.
55
+ A secret (from @secret:, @vault:, @preset:) must be the whole value: no other prefix before it, not in @extend:.
56
+
57
+ AUTOMATIC FLAGS
58
+ The server prepends extra_args to every call (default: #{DEFAULT_EXTRA_ARGS.join(' ')}).
59
+ Do NOT repeat them. To override one, include it in args: later values take precedence.
60
+ Commands never prompt: if credentials are missing, an error is returned; report it and stop.
61
+
62
+ DISCOVERY — never guess command or field names from training data
63
+ Step 1 — commands of a plugin, with syntax:
64
+ ["config", "commands", "<plugin>"]
65
+ Returns { syntax, description } for every command of that plugin.
66
+ Notation: <arg> mandatory, [<arg>] optional, <a|b> enum, <arg...> variadic, <arg:Hash> typed.
67
+ A line ending with <command...> and "(see: <plugin> <path>)" provides the commands of that path:
68
+ list them with ["config", "commands", "<plugin>", "<command>", ...] (command words only).
69
+ Omit <plugin> to list the commands of all plugins (large).
70
+ Step 2 — schema of a Hash argument (shown <name:Hash>), MANDATORY before calling such a command:
71
+ ["<plugin>", "<cmd>", ..., "help"]
72
+ Put the literal "help" in place of the Hash argument. Returns field names, types,
73
+ required flags and descriptions. Never infer fields from server error messages.
74
+ Step 2b — filter parameters of a list command:
75
+ ["<plugin>", "<cmd>", ..., "--query=help"]
76
+ Step 3 — all --flags of a plugin, with allowed values:
77
+ ["config", "options", "<plugin>"]
78
+ Documentation:
79
+ ["config", "documentation", "toc"] → { level, title, anchor } per heading
80
+ ["config", "documentation", "local", "<anchor>"] → one README section
81
+ Presets (saved credentials):
82
+ ["config", "preset", "overview"]
83
+
84
+ RESULT FORMAT
85
+ Structured data is always in structuredContent (a JSON object; lists are under "items").
86
+ For lists, text content is limited to #{DEFAULT_MAX_TEXT_BYTES} bytes (whole items only);
87
+ when truncated, a WARNING line gives the real total. Read structuredContent.items for
88
+ the full dataset — never report counts or search results from a truncated text block.
89
+
90
+ FILE LIST FOR TRANSFERS
91
+ For all transfers (upload, download, package send, …), append source paths at the
92
+ end of args — no --sources flag needed.
93
+
94
+ EXAMPLES
95
+ ["config", "commands", "aoc"]
96
+ ["aoc", "admin", "user", "create", "help"]
97
+ ["config", "options", "aoc"]
98
+ ["config", "documentation", "local", "leveraging-ai-assistance"]
99
+ ["aoc", "--preset=myaoc", "packages", "list"]
100
+ ["aoc", "--preset=myaoc", "admin", "user", "create", '@json:{"email":"a@b.com","name":"Alice"}']
101
+ ["aoc", "--preset=myaoc", "packages", "send",
102
+ '@json:{"name":"pkg","recipients":["user@example.com"]}', "/local/a.txt", "/local/b.txt"]
103
+ ["server", "--preset=myserver", "upload", "--to-folder=/uploads", "/local/a.txt"]
104
+ ["server", "browse", "/", "--url=ssh://host:33001", "--username=user", "--password=secret"]
105
+ DESC
106
+
107
+ input_schema(
108
+ properties: {
109
+ args: {
110
+ type: 'array',
111
+ items: {type: 'string'},
112
+ minItems: 1,
113
+ description: 'ascli arguments: first element is the plugin name, followed by action and --option=value flags'
114
+ }
115
+ },
116
+ required: ['args']
117
+ )
118
+
119
+ class << self
120
+ attr_accessor :max_text_bytes, :extra_args
121
+ # @return [WebSecret, nil] Secret pages for extended value `@secret:`
122
+ attr_accessor :web_secret
123
+
124
+ # Executes the command.
125
+ # If it needs a secret (`@secret:`), returns an `input_required` result: the client opens the page where the user
126
+ # enters the secret, then calls the tool again, and the command is executed again with the secret.
127
+ def call(args:, server_context: nil)
128
+ secret_call = Secrets::Call.new(web_secret, server_context)
129
+ prompt = catch(Secrets::THROW_TAG) do
130
+ response = Secrets.with_call(secret_call) { execute(args) }
131
+ secret_call.finish
132
+ # Secret values (e.g. entered by the user, tokens) never reach the client, even if displayed by the command,
133
+ # also short ones in a text (e.g. a short password in an error message)
134
+ hider = Secret::Hider.instance
135
+ return MCP::Tool::Response.new(
136
+ hider.hidden_copy(response.content, short_in_text: true),
137
+ structured_content: hider.hidden_copy(response.structured_content, short_in_text: true),
138
+ error: response.error?
139
+ )
140
+ end
141
+ return secret_call.input_required(prompt) if secret_call.url_elicitation?
142
+ secret_call.finish
143
+ MCP::Tool::Response.new([{type: 'text', text: "Extended value @secret:#{prompt} requires an MCP client supporting URL mode elicitation"}], error: true)
144
+ end
145
+
146
+ # Executes the command in-process
147
+ # Unsafe extended values are restricted when evaluated, see Security
148
+ # @param args [Array<String>] Arguments of the command
149
+ # @return [MCP::Tool::Response]
150
+ def execute(args)
151
+ effective_args = Array(extra_args || DEFAULT_EXTRA_ARGS) + args
152
+ Log.dump(:mcp_execute, effective_args)
153
+ runner = Runner.new(effective_args)
154
+ result = runner.run_with_result
155
+ # Secrets never reach the AI client, whatever the output format requested in args.
156
+ # As on the command line, `--out.query` applies to the data of an object or list, after secrets are removed
157
+ if result.is_a?(Result::SingleObject) || result.is_a?(Result::ObjectList) || result.is_a?(Result::ValueList)
158
+ result = result.with_data(Secret::Hider.instance.hidden_copy(result.data))
159
+ result = runner.context.formatter.query_result(result)
160
+ end
161
+ case result
162
+ when Result::Nothing, Result::Empty, NilClass
163
+ MCP::Tool::Response.new([{type: 'text', text: ''}])
164
+ when Result::SingleObject, Result::ObjectList, Result::ValueList
165
+ # Apply --select filter (affects both text and structuredContent).
166
+ result = result.with_data(runner.context.formatter.filter_columns_on_select(result.data)) if result.data.is_a?(Array)
167
+ # MCP spec requires structuredContent to be a JSON object (not an array).
168
+ structured = result.data.is_a?(Array) ? {items: result.data} : result.data
169
+ content = if result.data.is_a?(Array)
170
+ text_limit = max_text_bytes || DEFAULT_MAX_TEXT_BYTES
171
+ truncated_items = truncate_items_by_bytes(result.data, text_limit)
172
+ total = result.data.size
173
+ if truncated_items.size < total
174
+ [
175
+ {type: 'text', text: JSON.generate(truncated_items)},
176
+ {type: 'text', text: "WARNING: result truncated to #{truncated_items.size} of #{total} items. Full dataset available in structuredContent."}
177
+ ]
178
+ else
179
+ [{type: 'text', text: JSON.generate(result.data)}]
180
+ end
181
+ else
182
+ [{type: 'text', text: JSON.generate(result.data)}]
183
+ end
184
+ MCP::Tool::Response.new(content, structured_content: structured)
185
+ else
186
+ MCP::Tool::Response.new([{type: 'text', text: Secret::Hider.instance.hide_secrets_in_string(result.data.to_s, all: true)}])
187
+ end
188
+ rescue Cli::SchemaRequest => e
189
+ schema_path = e.path
190
+ if schema_path.nil?
191
+ MCP::Tool::Response.new([{type: 'text', text: "#{e.class}: #{e.message} (no schema available)"}], error: true)
192
+ else
193
+ rows = schema_to_rows(Schema::Registry.instance.reader(schema_path))
194
+ structured = {items: rows}
195
+ MCP::Tool::Response.new([{type: 'text', text: JSON.generate(rows)}], structured_content: structured)
196
+ end
197
+ rescue SystemExit => e
198
+ MCP::Tool::Response.new([{type: 'text', text: "exited with status #{e.status}"}], error: !e.status.zero?)
199
+ rescue => e
200
+ MCP::Tool::Response.new([{type: 'text', text: Secret::Hider.instance.hide_secrets_in_string("#{e.class}: #{dedupe_lines(e.message)}", all: true)}], error: true)
201
+ end
202
+
203
+ # Delegate to Schema::Reader#to_rows — semantic fields, no ANSI, MCP/JSON-ready.
204
+ def schema_to_rows(reader)
205
+ reader.to_rows
206
+ end
207
+
208
+ # Collapse consecutive duplicate lines in a multi-line message.
209
+ # Each run of identical lines is replaced by one line + "(×N)" suffix when N > 1.
210
+ def dedupe_lines(msg)
211
+ return msg unless msg.include?("\n")
212
+ msg.split("\n").chunk_while { |a, b| a == b }.map do |group|
213
+ group.size > 1 ? "#{group.first} (x#{group.size})" : group.first
214
+ end.join("\n")
215
+ end
216
+
217
+ # Returns the largest prefix of `items` whose JSON serialization fits within `max_bytes`.
218
+ # Items are appended whole — no item is ever split mid-JSON.
219
+ def truncate_items_by_bytes(items, max_bytes)
220
+ buf = +''
221
+ items.each_with_index do |item, i|
222
+ fragment = (i.zero? ? '[' : ',') + JSON.generate(item)
223
+ break if buf.bytesize + fragment.bytesize + 1 > max_bytes # +1 for closing ']'
224
+ buf << fragment
225
+ end
226
+ buf.empty? ? [] : JSON.parse("#{buf}]")
227
+ end
228
+ end
229
+ end
230
+ end
231
+ end
232
+ end
@@ -1,7 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/parser'
4
- require 'aspera/cli/command_spec'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'command_spec'
5
7
 
6
8
  module Aspera
7
9
  module Cli
@@ -26,9 +28,11 @@ module Aspera
26
28
  # @param deprecation [Hash, nil] Deprecation `{last:, message:}` forwarded to options.declare (see `Deprecation`)
27
29
  # @param schema [String, nil] Schema reference (e.g. "opts:components.schemas.Foo");
28
30
  # when description: is nil, the schema title or first description line is used
31
+ # @param complete [Symbol, nil] Values proposed by shell completion, one of `Complete::KINDS`
32
+ # @param security [Symbol, nil] Most restrictive security level at which the option is available (see `Security`)
29
33
  def option(name, description: nil,
30
34
  short: nil, allowed: nil, default: nil,
31
- on_set: nil, shorthand: nil, deprecation: nil, schema: nil)
35
+ on_set: nil, shorthand: nil, deprecation: nil, schema: nil, complete: nil, security: nil)
32
36
  register_option_spec(
33
37
  OptionSpec.new(
34
38
  name: name,
@@ -39,7 +43,9 @@ module Aspera
39
43
  on_set: on_set,
40
44
  shorthand: shorthand,
41
45
  deprecation: deprecation,
42
- schema: schema
46
+ schema: schema,
47
+ complete: complete,
48
+ security: security
43
49
  )
44
50
  )
45
51
  end
@@ -1,8 +1,11 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/option_value'
4
- require 'aspera/cli/error'
5
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'option_value'
7
+ require_relative 'error'
8
+ require_relative '../assert'
6
9
 
7
10
  module Aspera
8
11
  module Cli
@@ -1,7 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/error'
4
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'error'
7
+ require_relative '../assert'
5
8
 
6
9
  module Aspera
7
10
  module Cli
@@ -77,6 +80,18 @@ module Aspera
77
80
  STRING = [String].freeze
78
81
  end
79
82
 
83
+ # Values proposed by shell completion for an option, an argument or a schema key (`complete:`, `x-cli-complete`),
84
+ # when they are not a list of allowed values:
85
+ # - `file`: local file or folder
86
+ # - `folder`: local folder
87
+ # - `destination_folder`: local folder, unless the command sends files (the destination is then remote)
88
+ # - `preset`: name of option preset
89
+ # - `preset_parameter`: parameter of the option preset given as first argument of the command
90
+ # - `transfer_job`: identifier of an asynchronous transfer job
91
+ module Complete
92
+ KINDS = %i[file folder destination_folder preset preset_parameter transfer_job].freeze
93
+ end
94
+
80
95
  # Sources of option values.
81
96
  # A value is ignored if the option was already set from a source with higher priority.
82
97
  module OptionSource
@@ -1,13 +1,17 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/option_types'
4
- require 'aspera/cli/extended_value'
5
- require 'aspera/cli/deprecation'
6
- require 'aspera/secret_hider'
7
- require 'aspera/schema/registry'
8
- require 'aspera/schema/validator'
9
- require 'aspera/log'
10
- require 'aspera/assert'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'option_types'
7
+ require_relative 'extended_value'
8
+ require_relative 'security'
9
+ require_relative 'deprecation'
10
+ require_relative '../secret/hider'
11
+ require_relative '../schema/registry'
12
+ require_relative '../schema/validator'
13
+ require_relative '../log'
14
+ require_relative '../assert'
11
15
 
12
16
  module Aspera
13
17
  module Cli
@@ -22,6 +26,12 @@ module Aspera
22
26
  # [Symbol, nil] `OptionSource` of current value, `nil` if never set
23
27
  attr_reader :source
24
28
  attr_reader :sensitive, :schema, :deprecation
29
+ # [Symbol, nil] Most restrictive security level at which the option is available, `nil`: all levels, see `Security`
30
+ attr_reader :security
31
+ # [String, nil] For a `Hash` option: key of a `String` value
32
+ attr_reader :shorthand
33
+ # [Symbol, nil] Values proposed by shell completion, one of `Complete::KINDS`
34
+ attr_reader :complete
25
35
  # [Array] List of allowed values (Symbols and specific values)
26
36
  attr_accessor :values
27
37
  # [String] Help section group name (set by OptionRegistry)
@@ -36,14 +46,17 @@ module Aspera
36
46
  # @param allowed [nil,Class,Array<Class>,Array<Symbol>] Allowed values
37
47
  # @param on_set [#call, nil] Called with the new value each time the value is set
38
48
  # @param shorthand [String, nil] For a `Hash` option: a `String` value is stored as `{shorthand => value}`
49
+ # @param convert [#call, nil] For a `Hash` option: called with a new `Hash` value, returns the value to store, before merge (e.g. conversion of a deprecated form)
39
50
  # @param deprecation [Hash, Deprecation, nil] Deprecation: `{last:, message:}`, see `Deprecation`
40
51
  # @param schema [String] Declaration of schema
52
+ # @param complete [Symbol, nil] Values proposed by shell completion, one of `Complete::KINDS`
53
+ # @param security [Symbol, nil] Most restrictive security level at which the option is available (e.g. `:low`: executes code), see `Security`
41
54
  # `allowed`:
42
55
  # - `nil` No validation, so just a string
43
56
  # - `Class` The single allowed Class
44
57
  # - `Array<Class>` Multiple allowed classes
45
58
  # - `Array<Symbol>` List of allowed values
46
- def initialize(option:, description: nil, allowed: Type::STRING, on_set: nil, shorthand: nil, deprecation: nil, schema: nil)
59
+ def initialize(option:, description: nil, allowed: Type::STRING, on_set: nil, shorthand: nil, convert: nil, deprecation: nil, schema: nil, complete: nil, security: nil)
47
60
  Log.log.trace1 { "option: #{option}, allowed: #{allowed}" }
48
61
  @option = option
49
62
  @description = description
@@ -51,10 +64,16 @@ module Aspera
51
64
  @short = nil
52
65
  @block = nil
53
66
  # by default passwords and secrets are sensitive, else specify when declaring the option
54
- @sensitive = SecretHider.instance.secret?(@option, '')
67
+ @sensitive = Secret::Hider.instance.secret?(@option, '')
55
68
  @deprecation = Deprecation.create(deprecation)
56
69
  @schema = schema
57
70
  @shorthand = shorthand
71
+ Aspera.assert(convert.nil? || convert.respond_to?(:call)) { "#{@option}: convert must respond to call" }
72
+ @convert = convert
73
+ Aspera.assert_values(complete, Complete::KINDS + [nil]) { "#{@option}: complete" }
74
+ @complete = complete
75
+ Aspera.assert_values(security, Security::LEVELS + [nil]) { "#{@option}: security" }
76
+ @security = security
58
77
  @source = nil
59
78
  @value = nil
60
79
  Aspera.assert(on_set.nil? || on_set.respond_to?(:call)) { "#{@option}: on_set callback must respond to call" }
@@ -121,6 +140,8 @@ module Aspera
121
140
  return
122
141
  end
123
142
  Aspera.assert(!@deprecation, type: :warn) { "Option #{@option} is #{@deprecation}" } if warn_deprecation
143
+ # Values set by the program itself are not restricted: those from command line, preset, environment are
144
+ Security.instance.check_level(@security, "option #{@option}") if restricted_source?(source)
124
145
  if schema_request?(value)
125
146
  return if lower
126
147
  raise SchemaRequest.new(:option, @option, @schema) unless @schema.nil?
@@ -129,12 +150,16 @@ module Aspera
129
150
  return
130
151
  end
131
152
  new_value = coerce(ExtendedValue.instance.evaluate(value, context: "option: #{@option}", allowed: @types))
153
+ check_sub_options_security(new_value) if restricted_source?(source)
132
154
  new_value = {@shorthand => new_value} if @shorthand && new_value.is_a?(String)
133
155
  Log.log.trace1 { "#{source}: #{@option} <- (#{new_value.class})#{new_value}" }
134
156
  Aspera.assert_type(new_value, *@types, type: BadArgument) { "Option #{@option}" } if @types
157
+ new_value = @convert.call(new_value) if @convert && new_value.is_a?(Hash)
135
158
  if merge && (new_value.is_a?(Hash) || new_value.is_a?(Array))
136
159
  current_value = @value
137
- mergeable = current_value.is_a?(new_value.is_a?(Hash) ? Hash : Array) && !current_value.empty?
160
+ # An `Array` default value is replaced, not appended to
161
+ mergeable = current_value.is_a?(new_value.is_a?(Hash) ? Hash : Array) && !current_value.empty? &&
162
+ !(new_value.is_a?(Array) && [source, @source].include?(:default))
138
163
  if lower
139
164
  # Current value has priority: merge new value under it, unless explicitly emptied
140
165
  return unless mergeable
@@ -148,8 +173,38 @@ module Aspera
148
173
  nil
149
174
  end
150
175
 
176
+ # Check that the option, and the sub-options present in a `Hash` value (`x-security` in schema), are available at current security level.
177
+ # Used for a value that is not assigned yet, e.g. to store in a preset.
178
+ # @param value [Object] Value of the option
179
+ # @raise [BadArgument] If refused at current level
180
+ def check_security(value)
181
+ Security.instance.check_level(@security, "option #{@option}")
182
+ check_sub_options_security(value)
183
+ end
184
+
151
185
  private
152
186
 
187
+ # Values set by the program, or by the environment of the process (under control of the one who starts it), are not restricted:
188
+ # those from command line, presets (that a client can modify) and interactive input are.
189
+ # @param source [Symbol] `OptionSource`
190
+ # @return [Boolean] `true` if a value from this source is checked against security level
191
+ def restricted_source?(source)
192
+ !%i[default code env].include?(source)
193
+ end
194
+
195
+ # @param value [Object] Value of the option
196
+ # @raise [BadArgument] If a sub-option with `x-security` in the schema is present and refused at current level
197
+ def check_sub_options_security(value)
198
+ return unless @schema && value.is_a?(Hash)
199
+ Schema::Registry.instance.reader(@schema).each_property do |property, _name, full_name, _required|
200
+ level = property['x-security']
201
+ next if level.nil?
202
+ # Value of the sub-option, if given (a `nil` value clears it)
203
+ given = full_name.split('.').reduce(value) { |node, key| node.is_a?(Hash) ? node.find { |k, _| k.to_s.eql?(key) }&.last : nil }
204
+ Security.instance.check_level(level.to_sym, "option #{@option}.#{full_name}") unless given.nil?
205
+ end
206
+ end
207
+
153
208
  # Validate a structured value against the schema of the option.
154
209
  # Value may be partial: completed by other sources or defaults, so `required` is not enforced.
155
210
  # @param value [Object] value to validate
@@ -269,6 +324,12 @@ module Aspera
269
324
  # @param new_value [Object] value to store
270
325
  # @param source [Symbol, nil] `OptionSource` of value
271
326
  def store(new_value, source)
327
+ # Secret values are hidden wherever they appear: logs, results
328
+ if @sensitive
329
+ Secret::Hider.instance.add_secret_values(new_value)
330
+ else
331
+ Secret::Hider.instance.add_secrets_in(new_value)
332
+ end
272
333
  @value = new_value
273
334
  @source = source
274
335
  @on_set&.call(new_value)