aspera-cli 4.28.0 → 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 (237) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +143 -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 +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1633 -609
  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 +20 -20
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +71 -65
  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 +16 -8
  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 +12 -19
  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 -33
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +6 -1
  50. data/lib/aspera/cli/command_spec.rb +34 -7
  51. data/lib/aspera/cli/completion/ascli.bash +19 -5
  52. data/lib/aspera/cli/completion/ascli.fish +13 -2
  53. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  54. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  55. data/lib/aspera/cli/completion_actions.rb +303 -69
  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 +3 -0
  59. data/lib/aspera/cli/extended_value.rb +61 -27
  60. data/lib/aspera/cli/formatter.rb +29 -22
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -10
  63. data/lib/aspera/cli/http.rb +12 -9
  64. data/lib/aspera/cli/info.rb +12 -7
  65. data/lib/aspera/cli/mailer.rb +6 -3
  66. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  67. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  68. data/lib/aspera/cli/mcp/tool.rb +15 -14
  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 +65 -12
  73. data/lib/aspera/cli/options.schema.yaml +487 -63
  74. data/lib/aspera/cli/parser.rb +56 -32
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +244 -35
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +17 -12
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +198 -103
  81. data/lib/aspera/cli/plugins/console.rb +6 -3
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +21 -7
  84. data/lib/aspera/cli/plugins/faspex5.rb +28 -25
  85. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  86. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +28 -22
  88. data/lib/aspera/cli/plugins/node.rb +31 -30
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +272 -72
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +63 -11
  93. data/lib/aspera/cli/plugins/shares.rb +86 -16
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +144 -30
  96. data/lib/aspera/cli/preset_manager.rb +52 -18
  97. data/lib/aspera/cli/prompt.rb +4 -1
  98. data/lib/aspera/cli/result.rb +12 -8
  99. data/lib/aspera/cli/runner.rb +69 -46
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +79 -9
  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 +3 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +29 -20
  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 +188 -42
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.rb +12 -10
  113. data/lib/aspera/cli/wizard.rb +42 -39
  114. data/lib/aspera/command_line_builder.rb +9 -5
  115. data/lib/aspera/command_line_converter.rb +4 -1
  116. data/lib/aspera/coverage.rb +103 -33
  117. data/lib/aspera/data_repository.rb +4 -1
  118. data/lib/aspera/dot_container.rb +4 -1
  119. data/lib/aspera/duration.rb +5 -2
  120. data/lib/aspera/environment.rb +21 -12
  121. data/lib/aspera/exec_spec.rb +3 -0
  122. data/lib/aspera/faspex_gw.rb +13 -9
  123. data/lib/aspera/faspex_postproc.rb +15 -12
  124. data/lib/aspera/formatter_interface.rb +4 -1
  125. data/lib/aspera/graphql.rb +5 -1
  126. data/lib/aspera/hash_ext.rb +3 -0
  127. data/lib/aspera/id_generator.rb +4 -2
  128. data/lib/aspera/json_rpc/client.rb +6 -5
  129. data/lib/aspera/json_rpc/version.rb +3 -0
  130. data/lib/aspera/line_logger.rb +4 -1
  131. data/lib/aspera/link_header.rb +4 -1
  132. data/lib/aspera/log.rb +18 -5
  133. data/lib/aspera/markdown.rb +5 -2
  134. data/lib/aspera/mime.rb +3 -0
  135. data/lib/aspera/nagios.rb +6 -4
  136. data/lib/aspera/node_emulator.rb +15 -13
  137. data/lib/aspera/oauth/client/base.rb +91 -70
  138. data/lib/aspera/oauth/client/boot.rb +7 -4
  139. data/lib/aspera/oauth/client/factory.rb +6 -3
  140. data/lib/aspera/oauth/client/generic.rb +5 -1
  141. data/lib/aspera/oauth/client/json_credentials.rb +4 -1
  142. data/lib/aspera/oauth/client/jwt.rb +6 -3
  143. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  144. data/lib/aspera/oauth/client/url_json.rb +4 -1
  145. data/lib/aspera/oauth/client/web.rb +39 -12
  146. data/lib/aspera/oauth/server/pkce.rb +6 -5
  147. data/lib/aspera/orchestrator_workflow_checker.rb +119 -1
  148. data/lib/aspera/persistency_action_once.rb +5 -3
  149. data/lib/aspera/persistency_folder.rb +6 -3
  150. data/lib/aspera/preview/file_types.rb +6 -3
  151. data/lib/aspera/preview/generator.rb +9 -5
  152. data/lib/aspera/preview/options.schema.yaml +3 -3
  153. data/lib/aspera/preview/terminal.rb +8 -4
  154. data/lib/aspera/preview/utils.rb +6 -4
  155. data/lib/aspera/products/connect.rb +5 -2
  156. data/lib/aspera/products/desktop.rb +4 -1
  157. data/lib/aspera/products/other.rb +4 -2
  158. data/lib/aspera/products/transferd.rb +6 -2
  159. data/lib/aspera/products/transferd_service.rb +610 -0
  160. data/lib/aspera/proxy_auto_config.js +2 -2
  161. data/lib/aspera/proxy_auto_config.rb +5 -2
  162. data/lib/aspera/rainbow.rb +3 -0
  163. data/lib/aspera/rest/aspera_errors.rb +4 -1
  164. data/lib/aspera/rest/call_error.rb +3 -0
  165. data/lib/aspera/rest/client.rb +22 -29
  166. data/lib/aspera/rest/error_analyzer.rb +5 -2
  167. data/lib/aspera/rest/list.rb +8 -4
  168. data/lib/aspera/rest/parameters.rb +3 -0
  169. data/lib/aspera/rest/util.rb +8 -5
  170. data/lib/aspera/rest.rb +9 -6
  171. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  172. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  173. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  174. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  175. data/lib/aspera/schema/async_tables.yaml +11 -10
  176. data/lib/aspera/schema/documentation.rb +8 -2
  177. data/lib/aspera/schema/reader.rb +7 -0
  178. data/lib/aspera/schema/registry.rb +43 -28
  179. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  180. data/lib/aspera/schema/validator.rb +4 -1
  181. data/lib/aspera/sealed_hash.rb +166 -0
  182. data/lib/aspera/secret/hider.rb +201 -0
  183. data/lib/aspera/secret/reference.rb +150 -0
  184. data/lib/aspera/secret/resolver.rb +212 -0
  185. data/lib/aspera/secret/store/base.rb +153 -0
  186. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  187. data/lib/aspera/secret/store/factory.rb +103 -0
  188. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  189. data/lib/aspera/secret/store/keeper.rb +141 -0
  190. data/lib/aspera/secret/store/macos_security.rb +284 -0
  191. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  192. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  193. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  194. data/lib/aspera/secret/store/secret_service.rb +125 -0
  195. data/lib/aspera/secret/strength.rb +119 -0
  196. data/lib/aspera/servlet_helpers.rb +5 -2
  197. data/lib/aspera/ssh.rb +10 -7
  198. data/lib/aspera/ssl.rb +5 -2
  199. data/lib/aspera/string_ext.rb +3 -0
  200. data/lib/aspera/sync/args.schema.yaml +3 -0
  201. data/lib/aspera/sync/conf.schema.yaml +9 -4
  202. data/lib/aspera/sync/database.rb +3 -0
  203. data/lib/aspera/sync/operations.rb +16 -14
  204. data/lib/aspera/temp_file_manager.rb +8 -4
  205. data/lib/aspera/timer_limiter.rb +3 -0
  206. data/lib/aspera/transfer/error.rb +4 -1
  207. data/lib/aspera/transfer/faux_file.rb +4 -1
  208. data/lib/aspera/transfer/parameters.rb +17 -14
  209. data/lib/aspera/transfer/result.rb +3 -0
  210. data/lib/aspera/transfer/resumer.rb +6 -4
  211. data/lib/aspera/transfer/spec.rb +9 -22
  212. data/lib/aspera/transfer/units.rb +75 -0
  213. data/lib/aspera/uri_reader.rb +57 -7
  214. data/lib/aspera/web_auth/index.html.erb +6 -2
  215. data/lib/aspera/web_auth/paste.rb +109 -0
  216. data/lib/aspera/web_auth/receiver.rb +50 -0
  217. data/lib/aspera/web_auth/relay.rb +76 -0
  218. data/lib/aspera/web_auth/reply.html.erb +150 -0
  219. data/lib/aspera/web_auth/server.rb +47 -10
  220. data/lib/aspera/web_page.rb +7 -2
  221. data/lib/aspera/web_server_simple.rb +6 -3
  222. data/lib/aspera/yaml.rb +5 -1
  223. data/llms.txt +81 -0
  224. data/skills/ascli/SKILL.md +88 -0
  225. data.tar.gz.sig +0 -0
  226. metadata +72 -19
  227. metadata.gz.sig +0 -0
  228. data/lib/aspera/keychain/base.rb +0 -30
  229. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  230. data/lib/aspera/keychain/factory.rb +0 -58
  231. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  232. data/lib/aspera/keychain/macos_security.rb +0 -277
  233. data/lib/aspera/keychain/one_password_api.rb +0 -91
  234. data/lib/aspera/keychain/one_password_base.rb +0 -39
  235. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  236. data/lib/aspera/secret_hider.rb +0 -196
  237. data/lib/aspera/secret_strength.rb +0 -114
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 53275fa425245c33fe497658f6da1ba3cb13c1d02e0c0e4082d283c44b02af1c
4
- data.tar.gz: 68f60148c6ec53c98143ed2211d8474dc666b29cbf41c43604dc1ec208faaa1b
3
+ metadata.gz: 22b08acc7dfd929269009bc08f4419d5097e3d170d5095777a099efa9778ba58
4
+ data.tar.gz: c517da2115165b0ee092783ff62753a3f96cbb853758ba9ef5bc56b008dc2983
5
5
  SHA512:
6
- metadata.gz: b8fe08d94ac160cf2ec56a351afbb2ba4afde34ce8d80333de9400f3fd26f342041bb63167dd3ce708f3e86add4cee7d0761d843b5362f0169fb574978ff8314
7
- data.tar.gz: bb0c4deb1bd46b3e04a761e7de67730cfbe293a1580fa3a84c4acd33bb7b7d146a906f99985e05b15ba74c6884be1217240d92bf48f81dc2ceb3212fe40b18a7
6
+ metadata.gz: 3eedce17b67bdfa8b838e3d283da26cc30c3d149542aa4e20ca4160698f8412fbf9751a0e20393d77c1a03748a506eaaba2418875057a0ddebe2797de5339b33
7
+ data.tar.gz: b02389f18f68d814fe55a2b2eb98b39d536c894bc8e9e4ede77f72d05861e01077b5f29e29aa43b81767ae4ea7817b9c6bd4463987bd5d5e54d2e64aa43dd625
checksums.yaml.gz.sig CHANGED
Binary file
data/BUGS.md CHANGED
@@ -1,6 +1,8 @@
1
- # Reporting bugs and security vulnerabilities
1
+ # Reporting bugs
2
2
 
3
- Report bug, including vulnerability issues following this:
3
+ Report a bug in a [GitHub issue](https://github.com/IBM/aspera-cli/issues).
4
+
5
+ **Do not report a security vulnerability in a public issue**: see [SECURITY.md](SECURITY.md).
4
6
 
5
7
  Please, make sure to include the following information:
6
8
 
@@ -17,7 +19,7 @@ IMPORTANT: Remove any confidential information from the logs before posting them
17
19
  ## Scope of Support
18
20
 
19
21
  Architecture of `ascli` :
20
- ![architecture](docs/architecture.png)
22
+ ![architecture](docs/architecture.svg)
21
23
 
22
24
  The scope is exclusively the Ruby gem `aspera-cli` (green) and its **_interactions_** with IBM components:
23
25
 
@@ -36,10 +38,3 @@ For example, if `ascp` fails to transfer a file, there are two possibilities:
36
38
 
37
39
  * `ascp` cannot transfer due to a configuration on the server side, in which case the bug should be reported to IBM
38
40
  * `ascli` is not using it correctly (missing or wrong parameter provided to `ascp`), in which case the bug should be reported to this project
39
-
40
- ## Security Policy
41
-
42
- | Version | Supported |
43
- | ------- | ------------------ |
44
- | >= 4.0 | :white_check_mark: |
45
- | < 4.0 | :x: |
data/CHANGELOG.md CHANGED
@@ -1,5 +1,146 @@
1
1
  # Changes (Release notes)
2
2
 
3
+ ## 4.29.0
4
+
5
+ Released: 2026-11-17
6
+
7
+ Highlights:
8
+
9
+ * `ascli` as a tool for AI assistants: `mcp server` is hardened (the AI client can neither execute code nor write files where it chooses) and no longer experimental; commands describe themselves (schema of structured arguments with `help`, development guides of Orchestrator and Aspera on Cloud Automation read by section); new file `llms.txt` (also as an agent skill) that tells an AI how to drive IBM Aspera products with `ascli`.
10
+ * Analysis of `ascp` logs, local (`config ascp logs`) or on a server (`server logs`): statistics, sessions, diagnostics with recommendations.
11
+ * Named secret stores for `vault`, new types `keeper` and `secret_service`, HashiCorp AppRole and token file, secrets inspected without their value.
12
+ * Web login without local port (`--ui.web_auth=paste`), SAML web authentication for `shares` (`--auth=web`).
13
+ * New plugin `transferd`: Transfer Daemon as a service. Export and import of Aspera on Cloud Automation workflows. Many new `orchestrator` commands. Improved shell completion.
14
+ * Project: OpenSSF Best Practices silver badge, test coverage 96.6%.
15
+
16
+ **This version has several breaking changes**: read the **Breaking Changes** section below before upgrading and validate production workflows before deployment. In particular: Ruby 3.3 or later is required, `config wizard`, `config detect` and `config preset lookup` take their arguments as a `Hash` (`@: url=...`), and some `orchestrator` commands are renamed.
17
+
18
+ ### New Features
19
+
20
+ * `ascli`:
21
+ * New file `llms.txt` (in the gem and in the repository): what `ascli` does with IBM Aspera products, and how to discover commands, arguments and options, on the command line or through `mcp server`. Same content as an agent skill in folder `skills/ascli`. The repository is also a Claude Code plugin marketplace: `/plugin install ascli --marketplace IBM/aspera-cli`.
22
+ * Web authentication (`--auth=web`): new key `web_auth` of option `ui`. With `--ui.web_auth=paste`, no local port is opened: after login, the user pastes in the terminal the URL the browser was redirected to. It allows SSO when the browser cannot reach the host that runs `ascli` (e.g. jump server). If `ascli` is also installed on the workstation, it displays a command `ascli config web_login <code>` to run there instead. Default: `port` (unchanged).
23
+ * Improved shell completion: structures, extended values, local files and folders, presets (with their `_comment`), transfer jobs and `--query`.
24
+ * SSH keys of type `ed25519` are supported without additional gem. Gem `bcrypt_pbkdf` is only needed for OpenSSH keys protected by a passphrase.
25
+ * `config`:
26
+ * New command `ascp logs`: analysis of `ascp` log files (`ascp` 4.0 and later), of client and server (joined by session). Sub-commands: statistics, `sessions` (with context columns: product, transport, authentication, proxy, FIPS), `diagnostics` (severity, category, hint and recommended `ascp` options or `aspera.conf` parameters), `health` (Nagios format), multi-session transfers, rates per period, errors by peer, files, licenses, and parsed `records` for `--out.query`. Accepts gzip files, folders and the standard input (`-`). New option `ascp_logs`: thresholds of diagnostics, `timezone`, `health_minutes`.
27
+ * `ascp errors`: optional argument `session` lists error codes found in logs, with category and the corresponding error of the management port.
28
+ * `vault`: option `vault` declares several named stores: `{"default":"<name>","cache_ttl":60,"stores":{"<name>":{"type":...}}}`. A secret can be read from any store with `@vault://<store>/<path>[?<options>][#<field>]`; `@vault:<label>.<field>` uses the default store. New commands `vault stores`, `check`, `overview` and `field <label>`: they inspect stores and secrets without showing values. The former single-store form of option `vault` is deprecated, and converted when the configuration file is loaded (a backup is saved). `@file:` in options `vault` and `vault_password` is restricted by option `security` (refused by default in `mcp server`).
29
+ * `vault` type `file`: parameter `password` (value, or `@file:<path>`) replaces option `vault_password`.
30
+ * `vault` type HashiCorp: `token` accepts `@file:<path>` (read again when modified, e.g. by Vault Agent). New parameters `approle`, `namespace` and `ca_file`.
31
+ * `vault`: new types `keeper` (Keeper Secrets Manager, optional gem `keeper_secrets_manager`) and `secret_service` (Linux Secret Service: GNOME Keyring, KWallet, KeePassXC, with `secret-tool`).
32
+ * `wizard` adds `_comment: "wizard: <application>"` to the preset it creates.
33
+ * Asynchronous transfer jobs (`list`, `status`, `cleanup`) are managed by `agents jobs`. `config transfer` is deprecated.
34
+ * `transferd` (`install`, `list`) and `ascp install` are deprecated, use the new plugin `transferd`.
35
+ * `preset set` merges into the configuration at three levels (see Breaking Changes below). `preset update`, `initialize` and `unset` are deprecated, and show the command to use.
36
+ * `transferd`: new plugin for the Transfer Daemon.
37
+ * `install [version]` and `list`. `install` does nothing if the version is already installed.
38
+ * `info` and `transfers show|cancel <transfer_id>` for a running daemon (options `--url`, `--api-key`, `--ca-file`; requires gem `grpc`).
39
+ * `service` (`spec`, `install`, `configure`, `status`, `uninstall`, `use`, `versions`): run `transferd` as a `systemd` service, with its configuration validated, and SDK versions side by side (`use` for rollback). New global option `--dry-run` shows the actions without change.
40
+ * `server`: new command `logs`: same analysis as `config ascp logs`, on the log files of the server, read over SSH (size limited by key `remote_max_size` of option `ascp_logs`, default 256 MB).
41
+ * `aoc`:
42
+ * `automation` is no longer beta. New commands `automation workflows details`, `export`, `import` and `duplicate`.
43
+ * New command `automation guide` (`toc`, `full`, `section <anchor>`): the Aspera on Cloud Automation Development Guide.
44
+ * `faspex5`: web authentication (`--auth=web`) uses PKCE (`S256`), checked by Faspex 5.0.16 and later. Nothing to change in the configuration.
45
+ * `shares`: new option `--auth=web`: SAML authentication with the web browser, with `--ui.web_auth=port` (default) or `paste`. It requires a patch of Shares, provided in `docs/shares` until it is part of a Shares release (see manual).
46
+ * `node`: `asperabrowser` opens the new Aspera Browser web application (option `asperabrowserurl`), as the former one is no longer available. The node credentials are given in the fragment of the URL, which the browser does not send to the web server.
47
+ * `orchestrator`:
48
+ * New commands: `tasks`, `alerts list`, `queues`, `pools`, `plugins` (`reload`, `enable`, `import`), `workflows` (`parents`, `steps`, `test_step`, `test_status`), `portlets`, `users create`, `workorders delete`, `workorders worksteps`, `worksteps reset`, `monitors activate|deactivate`, statistics (`stats` of `workorders`, `worksteps` and `queues`), and `control` (engine, monitor and workers).
49
+ * `workflows check_import` detects more problems that make a workflow unusable (steps that never start, loops, invalid links or lookups).
50
+ * `workflows development` and `plugins spec` are read by section (`toc`, `full`, `section <anchor>`), so that an AI assistant reads only what it needs.
51
+ * `connect`: IBM Aspera Connect will be deprecated in 2027: the transfer agent `connect` displays a warning that recommends IBM Aspera for Desktop (`--transfer=desktop`).
52
+ * `mcp`: no longer experimental: the plugin follows the same compatibility rules as other plugins.
53
+ * **library**:
54
+ * New class `Aspera::Secret::Resolver`: references `secret://<store>/<path>[?<options>][#<field>]` to secrets of named stores, read when used, with a cache. It can also write secrets (`writable: true`) and inspect stores and references without reading values.
55
+ * `Aspera::Log#logger=` sends logs to the logger of the application.
56
+ * `Aspera::SealedHash.seal` and `unseal`: new parameters `encrypt:` and `reverse:`.
57
+ * New token creator `Aspera::OAuth::SharesWeb` (`grant_method: :shares_web`).
58
+ * Transfer agents: new optional method `transfer_cancel`. Agent `transferd`: parameters `api_key` and `ca_file` for an existing daemon, methods `info` and `create_client`, new fields in `transfer_status`, reader `transfer_id`.
59
+ * **project**:
60
+ * OpenSSF Best Practices: silver badge (<https://www.bestpractices.dev/projects/5861>).
61
+ * Test coverage: 96.6% of lines (was 85%), badge in `README.md`. Branch coverage is also measured.
62
+ * New `GOVERNANCE.md` and `docs/ASSURANCE_CASE.md` (security requirements, threat model). Code review requirements in `CONTRIBUTING.md`.
63
+ * Each source file has an SPDX copyright and license header.
64
+
65
+ ### Issues Fixed
66
+
67
+ * Security:
68
+ * `mcp server` (security level `high`): a client could execute code, or write a file where it chooses, through some options (`notify_template`, `fpac`, `ui` key `command`, `out` key `file`, `output`, `pid_file`, `home`, `plugin_folder`, `sdk_url`, `locations_url`), the folder `plugins` of the configuration folder, `config plugins create` and `faspex5 postprocessing`. They are now available only at level `low`, on the command line and in presets. At levels `medium` and `high`, `config preset set` refuses them, `config commands` does not list refused commands, and local files are written only in the new key `writable_paths` of option `security` (none by default).
69
+ * `config transferd install`, `config ascp install`: a file or a link of the SDK archive cannot be written outside of the installation folder. Reported by [@thesmartshadow](https://github.com/thesmartshadow).
70
+ * `config plugins create` refuses a plugin name that is not made of lowercase letters, digits and underscores.
71
+ * `ascli`:
72
+ * `--out.select` with a dot-path key (e.g. `directory_user.type`) selected no item with formats `json`, `jsonpp`, `yaml` and `ruby`. Matching no item displayed a table with headings only, instead of `<empty>`.
73
+ * An argument without `=` collected by `@:` is reported as a bad argument, instead of an assertion failure. Errors of extended values name their modifier (e.g. `@file:`).
74
+ * `@extend:` no longer evaluates again the values it inserts (e.g. read by `@env:` or `@file:`).
75
+ * An unknown key of a `Hash` option in dot notation (e.g. `--ui.foo=1`) gave an extra `unprocessed values` error.
76
+ * When the renewal of an expired OAuth token fails, the error of the renewal is reported, instead of the original authorization error.
77
+ * In debug logs, a command argument that contains a single quote was quoted wrongly.
78
+ * Gem dependency: excludes `regexp_parser` 2.13.2, with which `json_schemer` fails to load.
79
+ * `config`:
80
+ * `preset update` saved all the options of the command line in the preset, also those placed before `update` (e.g. `--home`, `--log-level`, `--format`).
81
+ * `preset set`: the value is evaluated once: `@val:@file:<path>` stores `@file:<path>`, as documented, not the content of the file. The result of an evaluation is no longer evaluated again.
82
+ * `initdemo`: the demo server preset allows the SSH host key `ssh-rsa`, the only one offered by the demo server, so that `server browse` and other file operations work. To fix a preset created by an earlier version: recreate it, or add `--ssh-options=@json:'{"host_key":["ssh-rsa"]}'`.
83
+ * `vault` type `file`: the vault keeps its owner, group and mode when it is changed by another user, e.g. root.
84
+ * `vault` type HashiCorp: responses of Vault failed with `wrong number of arguments` with gem `json` 3.
85
+ * `aoc`:
86
+ * `automation instances show` did not return. It now accepts the numeric identifier or the UUID.
87
+ * `packages receive` with option `package_folder`: two fields (e.g. `{"fld":["name","id"]}`) gave `<name>.id` instead of `<name>.<id>`, and with `seq` or `opt` the existence of the folder was checked in the current folder instead of `to_folder`.
88
+ * `faspex5`: web authentication (`--auth=web`) failed when HTTP basic authentication is enabled on the API client: option `client_secret` is now sent.
89
+ * `orchestrator`: authentication with option `apikey` was rejected (HTTP 401): the API requires `username` with the API key. Option `username` is now required with `apikey`.
90
+ * `node`:
91
+ * Browsing a folder with `--query.per_page` or `--query.page` failed when API v4 is not used.
92
+ * `telemetry`: an integer value of key `interval` (e.g. `0`, as documented) was refused. Same for keys `spawn_timeout_sec` and `spawn_delay_sec` of `transfer_info` (agent `direct`), and `font_ratio` of option `out` (key `img`).
93
+ * `access_keys do <id> show` and `thumbnail` ask the node not to use its cache.
94
+ * `preview`:
95
+ * `events` generated no preview: it now generates previews of new and modified files (option `filter` applies), and deletes the previews of deleted files.
96
+ * Option `skip_format` failed with `FrozenError`.
97
+ * An existing preview is also detected with the preview of the file (`files/<id>/preview`), when the information of the file has no `preview`.
98
+ * **library**: agent `transferd`:
99
+ * `transfer_status` no longer blocks on an ended transfer. When the daemon cannot be reached, does not answer in time, or does not know the transfer, the status is `unknown` instead of `running`. Calls have a timeout: key `timeout` of `agent_params`, default 10 seconds.
100
+ * A process that attaches to an external daemon for each transfer (e.g. Orchestrator) accumulated `at_exit` handlers.
101
+
102
+ ### Breaking Changes
103
+
104
+ * Ruby 3.3 or later is required (3.2 reached end of life in March 2026). Future minimum is 3.4. Policy: a Ruby version is supported until 6 months after its end of official support. Gem dependencies: `net-ssh` 8, `marcel` 2.
105
+ * `orchestrator`:
106
+ * Command `workstep` is renamed `worksteps` (e.g. `worksteps status`), consistent with `workorders`.
107
+ * `workflows development`: document `authoring` is replaced by `guide` (the Aspera Orchestrator Development Guide, which includes the Workflow Authoring Guide): `workflows development authoring toc` is now `workflows development guide toc`, and `workflows development templates customruby` is now `workflows development templates section customruby`.
108
+ * `plugins spec` is now `plugins spec toc`, and `plugins spec <plugin> [section]` is now `plugins spec show <plugin> [section]`.
109
+ * `config`: arguments given in a fixed order are replaced by a `Hash`, usually given with `@:` (items `key=value` in any order):
110
+ * `detect <url> [<plugin>]` is now `detect @: url=<url> plugin=<plugin>`. `url` is still asked if not given.
111
+ * `wizard <url> [<plugin> [<preset>]]` is now `wizard @: url=<url> plugin=<plugin> preset=<preset>`. `url` is still asked if not given. Options `--override` and `--default` are replaced by keys `override` and `default` of the `Hash`. Options of the plugin (`--username`, `--password`, `--private-key`, `--client-id`, `--use-generic-client`...) are unchanged. Option `--key-path` is removed: give the key itself with `--private-key=@file:<path>`. The wizard still uses the default key, or generates one, if `--private-key` is empty.
112
+ * `preset lookup --url=<url> --username=<user>` is now `preset lookup @: url=<url> username=<user>`. Options `--url` and `--username` are no longer used by this command.
113
+ * `preset set` merges into the configuration (JSON Merge Patch: deep merge, `@none:` removes a key) at one of three levels: `set <Hash>` (presets by name, e.g. `set @: p1.url=https://example.com default.server=p1`, `set @: p1=@none:` deletes preset `p1`), `set <name> <Hash>` (parameters of a preset, e.g. `set p1 @: url=https://example.com username=bob`), or `set <name> <param> <value>` (unchanged). Options of the command line are not saved in the preset. Commands `update`, `initialize` and `unset` are deprecated, and show the command to use: `update <name> --url=...` is `set <name> @: url=...` (it now saves only the options placed after `update`), `initialize <name> <Hash>` is `delete <name>` then `set <name> <Hash>`, `unset <name> <param>` is `set <name> <param> @none:`.
114
+ * `config completion`: completion scripts saved in a file must be saved again (see manual). Keys of an option are proposed with a trailing `=` or `.`.
115
+ * **library**: Modules about secrets are in `Aspera::Secret`: `SecretHider` is now `Secret::Hider`, `SecretStrength` is now `Secret::Strength`, `Keychain` is now `Secret::Store`. `Secret::Store::Factory.create` takes only the parameters of the store, and `Factory::LIST` is replaced by `Factory.types`.
116
+
117
+ ### Server Versions
118
+
119
+ Tested with Ruby 4.0.9 on osx-arm64.
120
+
121
+ | Plugin | Product | Version |
122
+ | ------------ | ------------------------------------------------ | ---------------- |
123
+ | `aoc` | IBM Aspera on Cloud | SaaS |
124
+ | `console` | IBM Aspera Console | 3.4.11 |
125
+ | `faspex5` | IBM Aspera Faspex | 5.0.19 |
126
+ | `faspio` | IBM Aspera faspio Gateway | 1.3.7 |
127
+ | `httpgw` | IBM Aspera HTTP Gateway | 2.3.4 |
128
+ | `node` | IBM Aspera High-Speed Transfer Server (Node API) | 4.4.9.3472 |
129
+ | `orchestrator` | IBM Aspera Orchestrator | 4.1.6.2036-00000 |
130
+ | `server` | IBM Aspera High-Speed Transfer Server (SSH) | 4.4.9.3472 |
131
+ | `shares` | IBM Aspera Shares | 1.11.5 |
132
+
133
+ ### Transfer Agent Versions
134
+
135
+ | Agent | Product | Version |
136
+ | --------- | ------------------------------------------------ | ---------- |
137
+ | `connect` | IBM Aspera Connect | 4.2.16 |
138
+ | `desktop` | IBM Aspera for Desktop | 1.1.2 |
139
+ | `direct` | IBM Aspera ascp | 4.4.8.2592 |
140
+ | `httpgw` | IBM Aspera HTTP Gateway | 2.3.4 |
141
+ | `node` | IBM Aspera High-Speed Transfer Server (Node API) | 4.4.9.3472 |
142
+ | `transferd` | IBM Aspera Transfer Daemon | 1.1.9 |
143
+
3
144
  ## 4.28.0
4
145
 
5
146
  Released: 2026-10-22
@@ -136,7 +277,7 @@ Highlights: security hardening of local web servers (authentication, minimum sec
136
277
  ### Server Versions
137
278
 
138
279
  | Plugin | Product | Version |
139
- |--------------|--------------------|------------------|
280
+ | -------------- | -------------------- | ------------------ |
140
281
  | `aoc` | Aspera on Cloud | SaaS |
141
282
  | `console` | IBM Aspera Console | 3.4.11 |
142
283
  | `faspex5` | Faspex v5 | F5.0.17 |
@@ -148,7 +289,7 @@ Highlights: security hardening of local web servers (authentication, minimum sec
148
289
  ### Transfer Agent Versions
149
290
 
150
291
  | Agent | Product | Version |
151
- |-----------|--------------------------------|---------|
292
+ | ----------- | -------------------------------- | --------- |
152
293
  | `connect` | IBM Aspera Connect Client | 4.2.14 |
153
294
  | `desktop` | IBM Aspera Desktop Client | 4.4.3 |
154
295
  | `direct` | IBM Aspera Transfer SDK (ascp) | 1.1.9 |
@@ -0,0 +1,18 @@
1
+ # Code of Conduct
2
+
3
+ This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
4
+
5
+ Contributors and maintainers pledge to make participation in this project a harassment-free experience for everyone, and to behave in a respectful and constructive way.
6
+
7
+ Unacceptable behavior includes harassment, insulting or derogatory comments, personal or political attacks, and publishing the private information of others without permission.
8
+
9
+ ## Reporting
10
+
11
+ Report unacceptable behavior privately to the maintainers at laurent.martin.aspera@fr.ibm.com.
12
+ All reports are reviewed and investigated promptly and fairly, and the privacy of the reporter is respected.
13
+
14
+ ## Enforcement
15
+
16
+ Maintainers can remove, edit or reject comments, commits, issues and other contributions that do not follow this Code of Conduct, and can temporarily or permanently ban a contributor for behavior they consider inappropriate.
17
+
18
+ The [enforcement guidelines](https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines) of the Contributor Covenant apply.
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.