aspera-cli 4.28.0 → 4.29.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (242) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +217 -2
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +135 -56
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +122 -26
  10. data/SECURITY.md +84 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1895 -632
  14. data/docs/test-mcp-with-ai.md +8 -8
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +20 -19
  19. data/lib/aspera/agent/factory.rb +6 -3
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +7 -4
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +29 -22
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +95 -67
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +370 -0
  41. data/lib/aspera/ascp/log_locations.rb +163 -0
  42. data/lib/aspera/ascp/management.rb +16 -8
  43. data/lib/aspera/ascp/session_errors.rb +217 -0
  44. data/lib/aspera/assert.rb +4 -0
  45. data/lib/aspera/cli/ascp_actions.rb +12 -19
  46. data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
  47. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  48. data/lib/aspera/cli/bootstrapper.rb +38 -33
  49. data/lib/aspera/cli/command_line.rb +63 -8
  50. data/lib/aspera/cli/command_registry.rb +9 -1
  51. data/lib/aspera/cli/command_spec.rb +47 -7
  52. data/lib/aspera/cli/completion/ascli.bash +19 -5
  53. data/lib/aspera/cli/completion/ascli.fish +13 -2
  54. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  55. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  56. data/lib/aspera/cli/completion_actions.rb +303 -69
  57. data/lib/aspera/cli/context.rb +9 -4
  58. data/lib/aspera/cli/deprecation.rb +5 -2
  59. data/lib/aspera/cli/error.rb +6 -0
  60. data/lib/aspera/cli/extended_value.rb +66 -31
  61. data/lib/aspera/cli/formatter.rb +43 -30
  62. data/lib/aspera/cli/gem_checker.rb +9 -6
  63. data/lib/aspera/cli/hints.rb +22 -10
  64. data/lib/aspera/cli/http.rb +38 -10
  65. data/lib/aspera/cli/info.rb +12 -7
  66. data/lib/aspera/cli/mailer.rb +6 -3
  67. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  68. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  69. data/lib/aspera/cli/mcp/tool.rb +20 -17
  70. data/lib/aspera/cli/option_declarator.rb +10 -4
  71. data/lib/aspera/cli/option_registry.rb +6 -3
  72. data/lib/aspera/cli/option_types.rb +17 -2
  73. data/lib/aspera/cli/option_value.rb +77 -18
  74. data/lib/aspera/cli/options.schema.yaml +641 -80
  75. data/lib/aspera/cli/parser.rb +71 -35
  76. data/lib/aspera/cli/plugins/alee.rb +7 -4
  77. data/lib/aspera/cli/plugins/aoc.rb +248 -37
  78. data/lib/aspera/cli/plugins/ats.rb +10 -9
  79. data/lib/aspera/cli/plugins/base.rb +50 -18
  80. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  81. data/lib/aspera/cli/plugins/config.rb +210 -104
  82. data/lib/aspera/cli/plugins/console.rb +6 -3
  83. data/lib/aspera/cli/plugins/cos.rb +8 -4
  84. data/lib/aspera/cli/plugins/factory.rb +21 -7
  85. data/lib/aspera/cli/plugins/faspex5.rb +31 -26
  86. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  87. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  88. data/lib/aspera/cli/plugins/mcp.rb +42 -22
  89. data/lib/aspera/cli/plugins/node.rb +39 -38
  90. data/lib/aspera/cli/plugins/oauth.rb +23 -6
  91. data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
  92. data/lib/aspera/cli/plugins/preview.rb +72 -45
  93. data/lib/aspera/cli/plugins/server.rb +66 -14
  94. data/lib/aspera/cli/plugins/shares.rb +87 -18
  95. data/lib/aspera/cli/plugins/transferd.rb +228 -0
  96. data/lib/aspera/cli/poll.rb +236 -0
  97. data/lib/aspera/cli/preset_actions.rb +144 -30
  98. data/lib/aspera/cli/preset_manager.rb +113 -35
  99. data/lib/aspera/cli/prompt.rb +157 -9
  100. data/lib/aspera/cli/result.rb +12 -8
  101. data/lib/aspera/cli/runner.rb +89 -48
  102. data/lib/aspera/cli/secret_finder.rb +4 -1
  103. data/lib/aspera/cli/security.rb +89 -9
  104. data/lib/aspera/cli/special_values.rb +4 -1
  105. data/lib/aspera/cli/sync_actions.rb +15 -10
  106. data/lib/aspera/cli/table_fitter.rb +3 -0
  107. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  108. data/lib/aspera/cli/transfer_actions.rb +11 -8
  109. data/lib/aspera/cli/transfer_agent.rb +43 -20
  110. data/lib/aspera/cli/transfer_progress.rb +14 -45
  111. data/lib/aspera/cli/vault_actions.rb +45 -0
  112. data/lib/aspera/cli/vault_manager.rb +188 -42
  113. data/lib/aspera/cli/version.rb +4 -1
  114. data/lib/aspera/cli/web_secret.rb +12 -10
  115. data/lib/aspera/cli/wizard.rb +42 -39
  116. data/lib/aspera/command_line_builder.rb +9 -5
  117. data/lib/aspera/command_line_converter.rb +4 -1
  118. data/lib/aspera/coverage.rb +103 -33
  119. data/lib/aspera/data_repository.rb +4 -1
  120. data/lib/aspera/dot_container.rb +4 -1
  121. data/lib/aspera/environment.rb +23 -12
  122. data/lib/aspera/exec_spec.rb +3 -0
  123. data/lib/aspera/faspex_gw.rb +13 -9
  124. data/lib/aspera/faspex_postproc.rb +15 -12
  125. data/lib/aspera/formatter_interface.rb +4 -1
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +20 -5
  129. data/lib/aspera/inflate.rb +43 -0
  130. data/lib/aspera/json_rpc/client.rb +6 -5
  131. data/lib/aspera/json_rpc/version.rb +3 -0
  132. data/lib/aspera/line_logger.rb +4 -1
  133. data/lib/aspera/link_header.rb +4 -1
  134. data/lib/aspera/log.rb +18 -5
  135. data/lib/aspera/markdown.rb +5 -2
  136. data/lib/aspera/mime.rb +3 -0
  137. data/lib/aspera/nagios.rb +6 -4
  138. data/lib/aspera/node_emulator.rb +15 -13
  139. data/lib/aspera/oauth/client/base.rb +124 -73
  140. data/lib/aspera/oauth/client/boot.rb +7 -4
  141. data/lib/aspera/oauth/client/factory.rb +41 -18
  142. data/lib/aspera/oauth/client/generic.rb +5 -1
  143. data/lib/aspera/oauth/client/json_credentials.rb +7 -3
  144. data/lib/aspera/oauth/client/jwt.rb +6 -3
  145. data/lib/aspera/oauth/client/shares_web.rb +94 -0
  146. data/lib/aspera/oauth/client/url_json.rb +7 -3
  147. data/lib/aspera/oauth/client/web.rb +40 -13
  148. data/lib/aspera/oauth/server/pkce.rb +6 -5
  149. data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +16 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +17 -2
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +3 -0
  165. data/lib/aspera/rest/aspera_errors.rb +4 -1
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +45 -34
  168. data/lib/aspera/rest/error_analyzer.rb +5 -2
  169. data/lib/aspera/rest/list.rb +8 -4
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +8 -5
  172. data/lib/aspera/rest.rb +9 -6
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  175. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  176. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  177. data/lib/aspera/schema/async_tables.yaml +11 -10
  178. data/lib/aspera/schema/documentation.rb +8 -2
  179. data/lib/aspera/schema/reader.rb +7 -0
  180. data/lib/aspera/schema/registry.rb +44 -28
  181. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  182. data/lib/aspera/schema/validator.rb +4 -1
  183. data/lib/aspera/sealed_hash.rb +150 -0
  184. data/lib/aspera/secret/hider.rb +213 -0
  185. data/lib/aspera/secret/reference.rb +150 -0
  186. data/lib/aspera/secret/resolver.rb +212 -0
  187. data/lib/aspera/secret/store/base.rb +153 -0
  188. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  189. data/lib/aspera/secret/store/factory.rb +103 -0
  190. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  191. data/lib/aspera/secret/store/keeper.rb +141 -0
  192. data/lib/aspera/secret/store/macos_security.rb +284 -0
  193. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  194. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  195. data/lib/aspera/secret/store/one_password_cli.rb +112 -0
  196. data/lib/aspera/secret/store/secret_service.rb +125 -0
  197. data/lib/aspera/secret/strength.rb +119 -0
  198. data/lib/aspera/servlet_helpers.rb +5 -2
  199. data/lib/aspera/ssh.rb +10 -7
  200. data/lib/aspera/ssl.rb +5 -2
  201. data/lib/aspera/string_ext.rb +3 -0
  202. data/lib/aspera/sync/args.schema.yaml +3 -0
  203. data/lib/aspera/sync/conf.schema.yaml +9 -4
  204. data/lib/aspera/sync/database.rb +3 -0
  205. data/lib/aspera/sync/operations.rb +17 -15
  206. data/lib/aspera/temp_file_manager.rb +8 -4
  207. data/lib/aspera/timer_limiter.rb +3 -0
  208. data/lib/aspera/transfer/error.rb +4 -1
  209. data/lib/aspera/transfer/faux_file.rb +4 -1
  210. data/lib/aspera/transfer/parameters.rb +17 -14
  211. data/lib/aspera/transfer/result.rb +23 -0
  212. data/lib/aspera/transfer/resumer.rb +6 -4
  213. data/lib/aspera/transfer/spec.rb +9 -22
  214. data/lib/aspera/units/decimal.rb +67 -0
  215. data/lib/aspera/units/duration.rb +109 -0
  216. data/lib/aspera/uri_reader.rb +64 -9
  217. data/lib/aspera/web_auth/index.html.erb +6 -2
  218. data/lib/aspera/web_auth/paste.rb +109 -0
  219. data/lib/aspera/web_auth/receiver.rb +50 -0
  220. data/lib/aspera/web_auth/relay.rb +76 -0
  221. data/lib/aspera/web_auth/reply.html.erb +150 -0
  222. data/lib/aspera/web_auth/server.rb +47 -10
  223. data/lib/aspera/web_page.rb +7 -2
  224. data/lib/aspera/web_server_simple.rb +6 -3
  225. data/lib/aspera/yaml.rb +5 -1
  226. data/llms-install.md +88 -0
  227. data/llms.txt +87 -0
  228. data/skills/ascli/SKILL.md +94 -0
  229. data.tar.gz.sig +0 -0
  230. metadata +77 -20
  231. metadata.gz.sig +0 -0
  232. data/lib/aspera/duration.rb +0 -42
  233. data/lib/aspera/keychain/base.rb +0 -30
  234. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  235. data/lib/aspera/keychain/factory.rb +0 -58
  236. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  237. data/lib/aspera/keychain/macos_security.rb +0 -277
  238. data/lib/aspera/keychain/one_password_api.rb +0 -91
  239. data/lib/aspera/keychain/one_password_base.rb +0 -39
  240. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  241. data/lib/aspera/secret_hider.rb +0 -196
  242. data/lib/aspera/secret_strength.rb +0 -114
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:
@@ -144,10 +173,47 @@ Example:
144
173
  ```shell
145
174
  bundle exec rake tools:rubocop # Ruby style guide
146
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'
147
204
  ```
148
205
 
149
- Fix any new offence introduced by your changes before committing.
150
- 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.
151
217
 
152
218
  #### 6 — Full test suite
153
219
 
@@ -161,7 +227,7 @@ All tests must pass (status `passed`) before opening a pull request.
161
227
 
162
228
  The `aspera-cli` architecture is designed to be modular and extensible.
163
229
 
164
- ![Architecture](docs/architecture.png)
230
+ ![Architecture](docs/architecture.svg)
165
231
 
166
232
  ### Structure Highlights
167
233
 
@@ -177,7 +243,7 @@ The `aspera-cli` architecture is designed to be modular and extensible.
177
243
 
178
244
  Located in `lib/aspera/agent`, these components manage data transfer operations.
179
245
 
180
- Detailed class diagrams are available in <docs/uml.png>
246
+ Detailed class diagrams are available in [docs/uml.png](docs/uml.png).
181
247
 
182
248
  ## Ruby Environment
183
249
 
@@ -201,15 +267,15 @@ The build system is powered by Ruby's `rake`.
201
267
 
202
268
  The following environment variables and macros control specific build behaviors:
203
269
 
204
- | Environment variable | Contents | Description |
205
- |-----------------------------|------------| -------------------------------------------------------------|
206
- | `ASPERA_CLI_TEST_CONF_URL` | URL | URL for the configuration file containing secrets for tests. |
207
- | `LOG_SECRETS` | `yes`/`no` | Toggles the logging of secrets in `rake` tasks. |
208
- | `LOG_LEVEL` | `debug`, ... | Sets the logging verbosity for `rake` tasks. |
209
- | `ENABLE_COVERAGE` | set/unset | Enables test coverage analysis when defined. |
210
- | `SIGNING_KEY` | File path or PEM | Path to the signing key file, or PEM content (starts with `-----BEGIN`). |
211
- | `DRY_RUN` | `1` | Simulates execution without performing actual operations (`git`, `gh`). |
212
- | `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. |
213
279
 
214
280
  These values can be set as standard environment variables or passed directly to the `rake` command.
215
281
 
@@ -226,7 +292,19 @@ export RUBYLIB=$dev_ascli/lib:$RUBYLIB
226
292
 
227
293
  ### Documentation
228
294
 
229
- 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).
230
308
 
231
309
  The project utilizes the **IBM Plex font**.
232
310
  Installation instructions can be found at [IBM Plex](https://www.ibm.com/plex/).
@@ -246,21 +324,21 @@ tlmgr install fvextra selnolig lualatex-math
246
324
 
247
325
  - Validate URLs during generation with:
248
326
 
249
- ```shell
250
- rake doc:check_links
251
- ```
327
+ ```shell
328
+ rake doc:check_links
329
+ ```
252
330
 
253
331
  - Debug the generation process: `DEBUG=1`.
254
332
 
255
333
  - Build the documentation:
256
334
 
257
- ```shell
258
- rake doc:build
259
- ```
335
+ ```shell
336
+ rake doc:build
337
+ ```
260
338
 
261
339
  ## Test Environment
262
340
 
263
- Detailed testing information can be found in <tests/README.md>.
341
+ Detailed testing information can be found in [tests/README.md](tests/README.md).
264
342
 
265
343
  ## Build
266
344
 
@@ -286,7 +364,7 @@ The gem is signed using the public certificate in `certs` and the **private key*
286
364
  bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
287
365
  ```
288
366
 
289
- For more details, see <certs/README.md>.
367
+ For more details, see [certs/README.md](certs/README.md).
290
368
 
291
369
  ### gRPC stubs for Transfer SDK
292
370
 
@@ -331,29 +409,29 @@ Before a new release, ensure the following:
331
409
 
332
410
  - **Pass all tests**:
333
411
 
334
- ```shell
335
- bundle exec rake test:run
336
- ```
412
+ ```shell
413
+ bundle exec rake test:run
414
+ ```
337
415
 
338
416
  - **Verify container builds** (using the local gem):
339
417
 
340
- ```shell
341
- bundle exec rake container:build'[local]'
342
- bundle exec rake container:test
343
- ```
418
+ ```shell
419
+ bundle exec rake container:build'[local]'
420
+ bundle exec rake container:test
421
+ ```
344
422
 
345
423
  - **Check documentation links**:
346
424
 
347
- ```shell
348
- bundle exec rake doc:check_links
349
- ```
425
+ ```shell
426
+ bundle exec rake doc:check_links
427
+ ```
350
428
 
351
429
  - **Check release procedure**:
352
430
 
353
- ```shell
354
- bundle exec rake release:run DRY_RUN=1
355
- git restore lib/aspera/cli/version.rb CHANGELOG.md docs/README.md
356
- ```
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
+ ```
357
435
 
358
436
  ### Automated Release Process
359
437
 
@@ -391,22 +469,23 @@ If necessary, you can mirror the automated process manually:
391
469
 
392
470
  - Build the PDF manual:
393
471
 
394
- ```shell
395
- bundle exec rake doc:build
396
- ```
472
+ ```shell
473
+ bundle exec rake doc:build
474
+ ```
397
475
 
398
476
  - Build the signed gem:
399
477
 
400
- ```shell
401
- bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
402
- ```
478
+ ```shell
479
+ bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
480
+ ```
403
481
 
404
482
  - Tag the release and push to GitHub:
405
483
 
406
- ```shell
407
- bundle exec rake release_tag
408
- ```
484
+ ```shell
485
+ bundle exec rake release_tag
486
+ ```
409
487
 
410
- 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`).
411
490
 
412
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.