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
data/CONTRIBUTING.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # Contributing
2
2
 
3
- ## Reporting Issues and Vulnerabilities
3
+ By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
4
4
 
5
- If you encounter a bug or a security vulnerability, please report it via [GitHub Issues](https://github.com/IBM/aspera-cli/issues).
5
+ ## Reporting Issues
6
+
7
+ If you encounter a bug, please report it via [GitHub Issues](https://github.com/IBM/aspera-cli/issues), using the bug report form.
8
+
9
+ **Do not report a security vulnerability in a public issue**: see [SECURITY.md](SECURITY.md).
6
10
 
7
11
  Before submitting a new report:
8
12
 
@@ -39,7 +43,7 @@ bundle install
39
43
  bundle exec rake -T
40
44
  ```
41
45
 
42
- For detailed testing instructions, please refer to [Running Tests](#running-tests).
46
+ For detailed testing instructions, please refer to [Test Environment](#test-environment).
43
47
 
44
48
  ### How to Contribute
45
49
 
@@ -47,16 +51,37 @@ To submit a contribution, follow these steps:
47
51
 
48
52
  1. **Fork** the repository on GitHub.
49
53
 
50
- 1. **Create a feature branch** specifically for your changes.
54
+ 2. **Create a feature branch** specifically for your changes.
51
55
 
52
- 1. **Implement** your feature or bug fix.
56
+ 3. **Implement** your feature or bug fix.
53
57
  See [Development Cycle for a New CLI Command](#development-cycle-for-a-new-cli-command) for the complete checklist.
54
58
 
55
- 1. **Submit a pull request** with a detailed description of your work.
59
+ 4. **Submit a pull request** with a detailed description of your work, and complete the checklist of the pull request template.
56
60
 
57
61
  > [!TIP]
58
62
  > Keep pull requests focused; include only changes relevant to the specific feature or fix.
59
63
 
64
+ ### Code Review
65
+
66
+ A pull request is merged after the approval of a maintainer (see [GOVERNANCE.md](GOVERNANCE.md)): branch `main` requires one approving review.
67
+
68
+ The reviewer checks that:
69
+
70
+ - The automated checks pass: unit tests and RuboCop (`.github/workflows/test.yml`), spell check (`.github/workflows/spell.yml`), CodeQL (`.github/workflows/codeql-analysis.yml`).
71
+ - The change does what the description says, and only that.
72
+ - New or changed behavior has tests in `tests/tests.yml` or `spec/`, including a failure case for invalid input.
73
+ - Inputs from users, files, and servers are validated, and the change keeps the restrictions of the [security levels](docs/README.md#security-level).
74
+ - No secret is in the change (code, tests, documentation): placeholders such as `<PASSWORD>` are used instead.
75
+ - Secrets are not shown in logs or output.
76
+ - The documentation (`docs/README.erb.md`) and `CHANGELOG.md` are updated.
77
+ - New dependencies are needed, maintained, and have a compatible license.
78
+ - The code follows the style of the project.
79
+
80
+ The reviewer asks for changes in comments of the pull request.
81
+ A pull request with an open question about security is not merged.
82
+
83
+ The maintainer may commit minor changes directly on `main` (see [Branching Strategy](#branching-strategy)): the same checks apply.
84
+
60
85
  ### Development Cycle for a New CLI Command
61
86
 
62
87
  When adding or modifying a CLI command, complete **every step** in the following order.
@@ -68,6 +93,10 @@ Each step is self-contained so that an automated agent can apply them independen
68
93
  - If the command belongs to a mixin (e.g. `AscpActions`, `PresetActions`), add the method in the corresponding file under `lib/aspera/cli/`.
69
94
  - Declare the new command with `command(...)` at class level and implement the corresponding `handle_<path>` method.
70
95
  - For agent-related schemas, declare parameters in `lib/aspera/cli/options.schema.yaml` under `components/schemas/`.
96
+ - Commands of an MCP client are untrusted (see [Security Levels and MCP Mode](docs/ARCHITECTURE.md#security-levels-and-mcp-mode)).
97
+ If a new option, sub-option or command executes code or a command, downloads and runs code, loads a plugin, or writes a file whose path the user gives, make it available only at level `low`: `security: :low` on `option` or `command`, or `x-security: low` on a key of a schema.
98
+ Write such a file with `Security.instance.writable_path`.
99
+ Add a spec that checks the refusal at level `high`.
71
100
 
72
101
  #### 2 — Add tests in `tests/tests.yml`
73
102
 
@@ -75,8 +104,8 @@ Every new command needs at least one entry in `tests/tests.yml`.
75
104
  Follow the naming convention `<plugin>_<sub>_<action>` (e.g. `conf_agents_list`).
76
105
 
77
106
  - Add a **happy-path** test (no extra tags).
78
- - Add a **failure test** for invalid input with tags `must_fail` and `nodoc`, and set `expect:` to a substring of the expected error message.
79
- - Tests that should not appear in generated documentation get the `nodoc` tag.
107
+ - Add a **failure test** for invalid input with tags `must_fail` and `no_doc`, and set `expect:` to a substring of the expected error message.
108
+ - Tests that should not appear in generated documentation get the `no_doc` tag.
80
109
  - Insert the new entries near related tests (same plugin/sub-command group).
81
110
 
82
111
  Minimal example:
@@ -90,13 +119,13 @@ conf_agents_list:
90
119
  conf_agents_show_bad:
91
120
  tags:
92
121
  - must_fail
93
- - nodoc
122
+ - no_doc
94
123
  expect: "unknown value"
95
124
  args:
96
125
  - config
97
126
  - agents
98
127
  - show
99
- - badagent
128
+ - bad-agent
100
129
  ```
101
130
 
102
131
  Run only the new tests to validate quickly:
@@ -127,14 +156,16 @@ Add one bullet under `### New Features` (or `### Issues Fixed` / `### Breaking C
127
156
 
128
157
  Style rules:
129
158
 
130
- - Plugin name in backticks: `` `config` ``, `` `aoc` ``, or `**global**` for cross-cutting changes.
159
+ - Entries are grouped by plugin: one first-level bullet per plugin, `` `ascli` `` (cross-cutting changes) first, then `` `config` ``, `` `mcp` ``, then the other plugins in alphabetical order.
160
+ - The entry is a second-level bullet under its plugin, prefixed with the command path inside the plugin, if any.
131
161
  - Command path and argument names in backticks.
132
162
  - One sentence per bullet; end without a period.
133
163
 
134
164
  Example:
135
165
 
136
166
  ```markdown
137
- * `config`: New commands `agents list`, `agents show <name>` and `agents parameters <name>` to discover available transfer agents, their short identifier and their configurable parameters
167
+ * `config`:
168
+ * `agents`: New commands `list`, `show <name>` and `parameters <name>` to discover available transfer agents, their short identifier and their configurable parameters
138
169
  ```
139
170
 
140
171
  #### 5 — Static analysis
@@ -142,10 +173,47 @@ Example:
142
173
  ```shell
143
174
  bundle exec rake tools:rubocop # Ruby style guide
144
175
  bundle exec rake tools:reek # code smell detection
176
+ bundle exec rake tools:spell # spelling (cspell)
177
+ bundle exec rake tools:codeql # security (CodeQL, as GitHub code scanning)
178
+ ```
179
+
180
+ In GitHub Actions, `tools:rubocop` (job `lint` of `.github/workflows/test.yml`, on changes of Ruby files), `tools:spell` (`.github/workflows/spell.yml`, on every push to `main` and every pull request) and CodeQL (`.github/workflows/codeql-analysis.yml`) run automatically.
181
+ `tools:reek` is not run in CI.
182
+
183
+ `tools:codeql` requires the `codeql` CLI (macOS: `brew install --cask codeql`), it downloads the query packs on first use.
184
+ It analyzes the tracked files, with their changes, for the languages of `.github/workflows/codeql-analysis.yml`, and fails if CodeQL reports any result.
185
+
186
+ Polynomial ReDoS in regular expressions is the most frequent finding.
187
+ Optional `pre-commit` hook `build/hooks/pre-commit-codeql` runs `tools:codeql` when the staged Ruby changes add a regular expression (regex literal, `%r`, `Regexp`, `=~`, `match`, `scan`, `gsub`, `sub`, `split`...).
188
+ It runs next to the other `pre-commit` hooks, register it once in the local git configuration:
189
+
190
+ ```shell
191
+ git config --local hook.codeql.event pre-commit
192
+ git config --local hook.codeql.command 'sh build/hooks/pre-commit-codeql'
193
+ ```
194
+
195
+ Environment variable `CODEQL_HOOK=always` forces the analysis, and `CODEQL_HOOK=skip` disables it.
196
+
197
+ Optional `pre-commit` hook `build/hooks/pre-commit-spell` runs `cspell` on the staged files only, with the same version (`cspell@10`) and configuration as the GitHub workflow `spell.yml`, so that a spelling error is found before the push.
198
+ It requires `npx` (Node.js).
199
+ Register it once in the local git configuration:
200
+
201
+ ```shell
202
+ git config --local hook.spell.event pre-commit
203
+ git config --local hook.spell.command 'sh build/hooks/pre-commit-spell'
145
204
  ```
146
205
 
147
- Fix any new offence introduced by your changes before committing.
148
- Pre-existing offences listed in `.rubocop_todo.yml` can be left as-is.
206
+ Environment variable `SPELL_HOOK=skip` disables it.
207
+
208
+ `cspell` (configuration: `.cspell.json`) does not check code in backticks, quoted strings without space (values, identifiers), command line options, and `%w[]`/`%i[]` arrays.
209
+ An unknown word that is a general term goes to a dictionary of folder `.cspell/`: `aspera.dict` (Aspera products and this project), `ruby.dict` (Ruby and gems), `tools.dict` (other tools and technical terms).
210
+ For test data, prefer names made of words (e.g. `test-file`, `bad-agent`): they need no exception.
211
+ A word specific to one file (column names, abbreviations, names imposed by a server) is an exception in that file:
212
+ on a single line, a trailing comment of `cspell` disables the check of that line (as in `lib/aspera/cli/plugins/base.rb`);
213
+ on several lines, an ignore comment of `cspell` at the top of the file lists the words (as in `lib/aspera/cli/plugins/node.rb`).
214
+
215
+ Fix any new offense introduced by your changes before committing.
216
+ Pre-existing offenses listed in `.rubocop_todo.yml` can be left as-is.
149
217
 
150
218
  #### 6 — Full test suite
151
219
 
@@ -159,7 +227,7 @@ All tests must pass (status `passed`) before opening a pull request.
159
227
 
160
228
  The `aspera-cli` architecture is designed to be modular and extensible.
161
229
 
162
- ![Architecture](docs/architecture.png)
230
+ ![Architecture](docs/architecture.svg)
163
231
 
164
232
  ### Structure Highlights
165
233
 
@@ -175,7 +243,7 @@ The `aspera-cli` architecture is designed to be modular and extensible.
175
243
 
176
244
  Located in `lib/aspera/agent`, these components manage data transfer operations.
177
245
 
178
- Detailed class diagrams are available in <docs/uml.png>
246
+ Detailed class diagrams are available in [docs/uml.png](docs/uml.png).
179
247
 
180
248
  ## Ruby Environment
181
249
 
@@ -199,15 +267,15 @@ The build system is powered by Ruby's `rake`.
199
267
 
200
268
  The following environment variables and macros control specific build behaviors:
201
269
 
202
- | Environment variable | Contents | Description |
203
- |-----------------------------|------------| -------------------------------------------------------------|
204
- | `ASPERA_CLI_TEST_CONF_URL` | URL | URL for the configuration file containing secrets for tests. |
205
- | `LOG_SECRETS` | `yes`/`no` | Toggles the logging of secrets in `rake` tasks. |
206
- | `LOG_LEVEL` | `debug`, ... | Sets the logging verbosity for `rake` tasks. |
207
- | `ENABLE_COVERAGE` | set/unset | Enables test coverage analysis when defined. |
208
- | `SIGNING_KEY` | File path or PEM | Path to the signing key file, or PEM content (starts with `-----BEGIN`). |
209
- | `DRY_RUN` | `1` | Simulates execution without performing actual operations (`git`, `gh`). |
210
- | `DEBUG` | `1` | Shows stack trace on errors during documentation generation. |
270
+ | Environment variable | Contents | Description |
271
+ |----------------------------|------------------|--------------------------------------------------------------------------|
272
+ | `ASPERA_CLI_TEST_CONF_URL` | URL | URL for the configuration file containing secrets for tests. |
273
+ | `LOG_SECRETS` | `yes`/`no` | Toggles the logging of secrets in `rake` tasks. |
274
+ | `LOG_LEVEL` | `debug`, ... | Sets the logging verbosity for `rake` tasks. |
275
+ | `ENABLE_COVERAGE` | set/unset | Enables test coverage analysis when defined. |
276
+ | `SIGNING_KEY` | File path or PEM | Path to the signing key file, or PEM content (starts with `-----BEGIN`). |
277
+ | `DRY_RUN` | `1` | Simulates execution without performing actual operations (`git`, `gh`). |
278
+ | `DEBUG` | `1` | Shows stack trace on errors during documentation generation. |
211
279
 
212
280
  These values can be set as standard environment variables or passed directly to the `rake` command.
213
281
 
@@ -224,7 +292,19 @@ export RUBYLIB=$dev_ascli/lib:$RUBYLIB
224
292
 
225
293
  ### Documentation
226
294
 
227
- Documentation is generated with `pandoc` and `LaTeX`.
295
+ The PDF manual is generated from `docs/README.md` by [gfm2pdf-toolchain](https://github.com/laurent-martin/gfm2pdf-toolchain) (version 1.x), with `pandoc` and LuaLaTeX.
296
+ Clone it, and set the environment variable `GFM2PDF_HOME` to its folder (only the `doc` tasks need it):
297
+
298
+ ```shell
299
+ git clone https://github.com/laurent-martin/gfm2pdf-toolchain.git
300
+ export GFM2PDF_HOME=$PWD/gfm2pdf-toolchain
301
+ ```
302
+
303
+ See its `README.md` for the tools it requires.
304
+
305
+ - The look of the PDF manual (cover, fonts) comes from the theme `build/doc/pdf_theme`, also used by other IBM Aspera projects (`GFM2PDF_THEME`).
306
+ - Options of the PDF manual: comment `<!-- gfm2pdf` in `docs/README.erb.md` (subtitle, author), and `docs/README.gfm2pdf.yaml` (page after the cover: `docs/README.preface.tex`).
307
+ - draw.io diagrams of the manual (`docs/*.drawio`): their images (SVG for GitHub, PDF for the PDF manual) are committed, export them again with `rake doc:diagrams` (requires draw.io desktop).
228
308
 
229
309
  The project utilizes the **IBM Plex font**.
230
310
  Installation instructions can be found at [IBM Plex](https://www.ibm.com/plex/).
@@ -244,21 +324,21 @@ tlmgr install fvextra selnolig lualatex-math
244
324
 
245
325
  - Validate URLs during generation with:
246
326
 
247
- ```shell
248
- rake doc:check_links
249
- ```
327
+ ```shell
328
+ rake doc:check_links
329
+ ```
250
330
 
251
331
  - Debug the generation process: `DEBUG=1`.
252
332
 
253
333
  - Build the documentation:
254
334
 
255
- ```shell
256
- rake doc:build
257
- ```
335
+ ```shell
336
+ rake doc:build
337
+ ```
258
338
 
259
339
  ## Test Environment
260
340
 
261
- Detailed testing information can be found in <tests/README.md>.
341
+ Detailed testing information can be found in [tests/README.md](tests/README.md).
262
342
 
263
343
  ## Build
264
344
 
@@ -284,7 +364,7 @@ The gem is signed using the public certificate in `certs` and the **private key*
284
364
  bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
285
365
  ```
286
366
 
287
- For more details, see <certs/README.md>.
367
+ For more details, see [certs/README.md](certs/README.md).
288
368
 
289
369
  ### gRPC stubs for Transfer SDK
290
370
 
@@ -329,29 +409,29 @@ Before a new release, ensure the following:
329
409
 
330
410
  - **Pass all tests**:
331
411
 
332
- ```shell
333
- bundle exec rake test:run
334
- ```
412
+ ```shell
413
+ bundle exec rake test:run
414
+ ```
335
415
 
336
416
  - **Verify container builds** (using the local gem):
337
417
 
338
- ```shell
339
- bundle exec rake container:build'[local]'
340
- bundle exec rake container:test
341
- ```
418
+ ```shell
419
+ bundle exec rake container:build'[local]'
420
+ bundle exec rake container:test
421
+ ```
342
422
 
343
423
  - **Check documentation links**:
344
424
 
345
- ```shell
346
- bundle exec rake doc:check_links
347
- ```
425
+ ```shell
426
+ bundle exec rake doc:check_links
427
+ ```
348
428
 
349
429
  - **Check release procedure**:
350
430
 
351
- ```shell
352
- bundle exec rake release:run DRY_RUN=1
353
- git restore lib/aspera/cli/version.rb CHANGELOG.md docs/README.md
354
- ```
431
+ ```shell
432
+ bundle exec rake release:run DRY_RUN=1
433
+ git restore lib/aspera/cli/version.rb CHANGELOG.md docs/README.md
434
+ ```
355
435
 
356
436
  ### Automated Release Process
357
437
 
@@ -389,22 +469,23 @@ If necessary, you can mirror the automated process manually:
389
469
 
390
470
  - Build the PDF manual:
391
471
 
392
- ```shell
393
- bundle exec rake doc:build
394
- ```
472
+ ```shell
473
+ bundle exec rake doc:build
474
+ ```
395
475
 
396
476
  - Build the signed gem:
397
477
 
398
- ```shell
399
- bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
400
- ```
478
+ ```shell
479
+ bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
480
+ ```
401
481
 
402
482
  - Tag the release and push to GitHub:
403
483
 
404
- ```shell
405
- bundle exec rake release_tag
406
- ```
484
+ ```shell
485
+ bundle exec rake release_tag
486
+ ```
407
487
 
408
- This triggers the `.github/workflows/deploy.yml` action to publish to RubyGems.
488
+ This triggers the `.github/workflows/deploy.yml` action to publish to RubyGems.
489
+ It authenticates with the RubyGems API key in the repository secret `RUBYGEMS_API_KEY` (scope `push rubygem`; the workflow `yank-gem-version.yml` uses the same secret, scope `yank rubygem`).
409
490
 
410
491
  - Update `version.rb` to the next `.pre` development version.
data/GOVERNANCE.md ADDED
@@ -0,0 +1,30 @@
1
+ # Governance
2
+
3
+ `aspera-cli` is an open source project of IBM, hosted in the [IBM GitHub organization](https://github.com/IBM), under the [Apache License 2.0](LICENSE).
4
+
5
+ ## Roles
6
+
7
+ | Role | Who | Responsibilities |
8
+ | ---- | --- | ---------------- |
9
+ | **Maintainer** | Listed in [`.github/CODEOWNERS`](.github/CODEOWNERS) | Decides the direction of the project (see [TODO.md](TODO.md)), reviews and merges pull requests, triages issues, handles vulnerability reports (see [SECURITY.md](SECURITY.md)), and publishes releases. |
10
+ | **Repository administrator** | IBM staff with the administrator role on the repository | Manages access to the repository and its secrets, and appoints maintainers. Ensures the continuity of the project (see below). |
11
+ | **Contributor** | Anyone | Reports issues, proposes changes with pull requests, following [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). |
12
+
13
+ ## Decisions
14
+
15
+ - Proposals and questions are discussed publicly in [GitHub issues](https://github.com/IBM/aspera-cli/issues) and pull requests.
16
+ - The maintainer decides, after the discussion, and gives the reason for the decision in the issue or pull request.
17
+ - A change is accepted when it meets the [code review requirements](CONTRIBUTING.md#code-review).
18
+ - Security issues are discussed privately, as described in [SECURITY.md](SECURITY.md).
19
+
20
+ ## Continuity
21
+
22
+ The project can continue if a maintainer is no longer available:
23
+
24
+ - Several repository administrators (IBM staff) can manage issues, accept pull requests, and appoint a new maintainer.
25
+ - Releases are built, signed, and published by GitHub Actions workflows (see [Release](CONTRIBUTING.md#release)), with secrets stored in the repository settings, not by a single person.
26
+ - The build, test, and release procedures are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
27
+
28
+ ## Changes to this document
29
+
30
+ Changes to the governance are proposed with a pull request, and approved by a repository administrator.
data/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.