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.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/BUGS.md +5 -10
- data/CHANGELOG.md +143 -2
- data/CODE_OF_CONDUCT.md +18 -0
- data/CONTRIBUTING.md +135 -56
- data/GOVERNANCE.md +30 -0
- data/LICENSE +201 -0
- data/README.md +103 -26
- data/SECURITY.md +70 -0
- data/bin/ascli +8 -5
- data/bin/asession +9 -6
- data/docs/README.md +1633 -609
- data/docs/test-mcp-with-ai.md +8 -8
- data/lib/aspera/agent/base.rb +23 -2
- data/lib/aspera/agent/connect.rb +16 -12
- data/lib/aspera/agent/desktop.rb +10 -7
- data/lib/aspera/agent/direct.rb +20 -19
- data/lib/aspera/agent/factory.rb +6 -3
- data/lib/aspera/agent/httpgw.rb +7 -5
- data/lib/aspera/agent/node.rb +15 -7
- data/lib/aspera/agent/transferd.rb +167 -43
- data/lib/aspera/api/alee.rb +4 -1
- data/lib/aspera/api/aoc.rb +14 -11
- data/lib/aspera/api/ats.rb +4 -2
- data/lib/aspera/api/cos_node.rb +7 -4
- data/lib/aspera/api/faspex.rb +16 -9
- data/lib/aspera/api/httpgw.rb +9 -6
- data/lib/aspera/api/node.rb +20 -20
- data/lib/aspera/ascmd.rb +8 -5
- data/lib/aspera/ascp/installation.rb +71 -65
- data/lib/aspera/ascp/log.schema.yaml +1084 -0
- data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
- data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
- data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
- data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
- data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
- data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
- data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
- data/lib/aspera/ascp/log_analyzer.rb +354 -0
- data/lib/aspera/ascp/management.rb +16 -8
- data/lib/aspera/ascp/session_errors.rb +217 -0
- data/lib/aspera/assert.rb +4 -0
- data/lib/aspera/cli/ascp_actions.rb +12 -19
- data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
- data/lib/aspera/cli/async_transfer_store.rb +7 -4
- data/lib/aspera/cli/bootstrapper.rb +37 -33
- data/lib/aspera/cli/command_line.rb +24 -6
- data/lib/aspera/cli/command_registry.rb +6 -1
- data/lib/aspera/cli/command_spec.rb +34 -7
- data/lib/aspera/cli/completion/ascli.bash +19 -5
- data/lib/aspera/cli/completion/ascli.fish +13 -2
- data/lib/aspera/cli/completion/ascli.ps1 +31 -9
- data/lib/aspera/cli/completion/ascli.zsh +22 -6
- data/lib/aspera/cli/completion_actions.rb +303 -69
- data/lib/aspera/cli/context.rb +9 -4
- data/lib/aspera/cli/deprecation.rb +5 -2
- data/lib/aspera/cli/error.rb +3 -0
- data/lib/aspera/cli/extended_value.rb +61 -27
- data/lib/aspera/cli/formatter.rb +29 -22
- data/lib/aspera/cli/gem_checker.rb +9 -6
- data/lib/aspera/cli/hints.rb +22 -10
- data/lib/aspera/cli/http.rb +12 -9
- data/lib/aspera/cli/info.rb +12 -7
- data/lib/aspera/cli/mailer.rb +6 -3
- data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
- data/lib/aspera/cli/mcp/secrets.rb +8 -5
- data/lib/aspera/cli/mcp/tool.rb +15 -14
- data/lib/aspera/cli/option_declarator.rb +10 -4
- data/lib/aspera/cli/option_registry.rb +6 -3
- data/lib/aspera/cli/option_types.rb +17 -2
- data/lib/aspera/cli/option_value.rb +65 -12
- data/lib/aspera/cli/options.schema.yaml +487 -63
- data/lib/aspera/cli/parser.rb +56 -32
- data/lib/aspera/cli/plugins/alee.rb +7 -4
- data/lib/aspera/cli/plugins/aoc.rb +244 -35
- data/lib/aspera/cli/plugins/ats.rb +9 -8
- data/lib/aspera/cli/plugins/base.rb +17 -12
- data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
- data/lib/aspera/cli/plugins/config.rb +198 -103
- data/lib/aspera/cli/plugins/console.rb +6 -3
- data/lib/aspera/cli/plugins/cos.rb +8 -4
- data/lib/aspera/cli/plugins/factory.rb +21 -7
- data/lib/aspera/cli/plugins/faspex5.rb +28 -25
- data/lib/aspera/cli/plugins/faspio.rb +7 -5
- data/lib/aspera/cli/plugins/httpgw.rb +7 -4
- data/lib/aspera/cli/plugins/mcp.rb +28 -22
- data/lib/aspera/cli/plugins/node.rb +31 -30
- data/lib/aspera/cli/plugins/oauth.rb +5 -1
- data/lib/aspera/cli/plugins/orchestrator.rb +272 -72
- data/lib/aspera/cli/plugins/preview.rb +69 -44
- data/lib/aspera/cli/plugins/server.rb +63 -11
- data/lib/aspera/cli/plugins/shares.rb +86 -16
- data/lib/aspera/cli/plugins/transferd.rb +223 -0
- data/lib/aspera/cli/preset_actions.rb +144 -30
- data/lib/aspera/cli/preset_manager.rb +52 -18
- data/lib/aspera/cli/prompt.rb +4 -1
- data/lib/aspera/cli/result.rb +12 -8
- data/lib/aspera/cli/runner.rb +69 -46
- data/lib/aspera/cli/secret_finder.rb +4 -1
- data/lib/aspera/cli/security.rb +79 -9
- data/lib/aspera/cli/special_values.rb +4 -1
- data/lib/aspera/cli/sync_actions.rb +13 -10
- data/lib/aspera/cli/table_fitter.rb +3 -0
- data/lib/aspera/cli/terminal_formatter.rb +9 -6
- data/lib/aspera/cli/transfer_actions.rb +11 -8
- data/lib/aspera/cli/transfer_agent.rb +29 -20
- data/lib/aspera/cli/transfer_progress.rb +13 -45
- data/lib/aspera/cli/vault_actions.rb +45 -0
- data/lib/aspera/cli/vault_manager.rb +188 -42
- data/lib/aspera/cli/version.rb +4 -1
- data/lib/aspera/cli/web_secret.rb +12 -10
- data/lib/aspera/cli/wizard.rb +42 -39
- data/lib/aspera/command_line_builder.rb +9 -5
- data/lib/aspera/command_line_converter.rb +4 -1
- data/lib/aspera/coverage.rb +103 -33
- data/lib/aspera/data_repository.rb +4 -1
- data/lib/aspera/dot_container.rb +4 -1
- data/lib/aspera/duration.rb +5 -2
- data/lib/aspera/environment.rb +21 -12
- data/lib/aspera/exec_spec.rb +3 -0
- data/lib/aspera/faspex_gw.rb +13 -9
- data/lib/aspera/faspex_postproc.rb +15 -12
- data/lib/aspera/formatter_interface.rb +4 -1
- data/lib/aspera/graphql.rb +5 -1
- data/lib/aspera/hash_ext.rb +3 -0
- data/lib/aspera/id_generator.rb +4 -2
- data/lib/aspera/json_rpc/client.rb +6 -5
- data/lib/aspera/json_rpc/version.rb +3 -0
- data/lib/aspera/line_logger.rb +4 -1
- data/lib/aspera/link_header.rb +4 -1
- data/lib/aspera/log.rb +18 -5
- data/lib/aspera/markdown.rb +5 -2
- data/lib/aspera/mime.rb +3 -0
- data/lib/aspera/nagios.rb +6 -4
- data/lib/aspera/node_emulator.rb +15 -13
- data/lib/aspera/oauth/client/base.rb +91 -70
- data/lib/aspera/oauth/client/boot.rb +7 -4
- data/lib/aspera/oauth/client/factory.rb +6 -3
- data/lib/aspera/oauth/client/generic.rb +5 -1
- data/lib/aspera/oauth/client/json_credentials.rb +4 -1
- data/lib/aspera/oauth/client/jwt.rb +6 -3
- data/lib/aspera/oauth/client/shares_web.rb +85 -0
- data/lib/aspera/oauth/client/url_json.rb +4 -1
- data/lib/aspera/oauth/client/web.rb +39 -12
- data/lib/aspera/oauth/server/pkce.rb +6 -5
- data/lib/aspera/orchestrator_workflow_checker.rb +119 -1
- data/lib/aspera/persistency_action_once.rb +5 -3
- data/lib/aspera/persistency_folder.rb +6 -3
- data/lib/aspera/preview/file_types.rb +6 -3
- data/lib/aspera/preview/generator.rb +9 -5
- data/lib/aspera/preview/options.schema.yaml +3 -3
- data/lib/aspera/preview/terminal.rb +8 -4
- data/lib/aspera/preview/utils.rb +6 -4
- data/lib/aspera/products/connect.rb +5 -2
- data/lib/aspera/products/desktop.rb +4 -1
- data/lib/aspera/products/other.rb +4 -2
- data/lib/aspera/products/transferd.rb +6 -2
- data/lib/aspera/products/transferd_service.rb +610 -0
- data/lib/aspera/proxy_auto_config.js +2 -2
- data/lib/aspera/proxy_auto_config.rb +5 -2
- data/lib/aspera/rainbow.rb +3 -0
- data/lib/aspera/rest/aspera_errors.rb +4 -1
- data/lib/aspera/rest/call_error.rb +3 -0
- data/lib/aspera/rest/client.rb +22 -29
- data/lib/aspera/rest/error_analyzer.rb +5 -2
- data/lib/aspera/rest/list.rb +8 -4
- data/lib/aspera/rest/parameters.rb +3 -0
- data/lib/aspera/rest/util.rb +8 -5
- data/lib/aspera/rest.rb +9 -6
- data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
- data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
- data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
- data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
- data/lib/aspera/schema/async_tables.yaml +11 -10
- data/lib/aspera/schema/documentation.rb +8 -2
- data/lib/aspera/schema/reader.rb +7 -0
- data/lib/aspera/schema/registry.rb +43 -28
- data/lib/aspera/schema/transferd-config.schema.json +333 -0
- data/lib/aspera/schema/validator.rb +4 -1
- data/lib/aspera/sealed_hash.rb +166 -0
- data/lib/aspera/secret/hider.rb +201 -0
- data/lib/aspera/secret/reference.rb +150 -0
- data/lib/aspera/secret/resolver.rb +212 -0
- data/lib/aspera/secret/store/base.rb +153 -0
- data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
- data/lib/aspera/secret/store/factory.rb +103 -0
- data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
- data/lib/aspera/secret/store/keeper.rb +141 -0
- data/lib/aspera/secret/store/macos_security.rb +284 -0
- data/lib/aspera/secret/store/one_password_api.rb +99 -0
- data/lib/aspera/secret/store/one_password_base.rb +42 -0
- data/lib/aspera/secret/store/one_password_cli.rb +110 -0
- data/lib/aspera/secret/store/secret_service.rb +125 -0
- data/lib/aspera/secret/strength.rb +119 -0
- data/lib/aspera/servlet_helpers.rb +5 -2
- data/lib/aspera/ssh.rb +10 -7
- data/lib/aspera/ssl.rb +5 -2
- data/lib/aspera/string_ext.rb +3 -0
- data/lib/aspera/sync/args.schema.yaml +3 -0
- data/lib/aspera/sync/conf.schema.yaml +9 -4
- data/lib/aspera/sync/database.rb +3 -0
- data/lib/aspera/sync/operations.rb +16 -14
- data/lib/aspera/temp_file_manager.rb +8 -4
- data/lib/aspera/timer_limiter.rb +3 -0
- data/lib/aspera/transfer/error.rb +4 -1
- data/lib/aspera/transfer/faux_file.rb +4 -1
- data/lib/aspera/transfer/parameters.rb +17 -14
- data/lib/aspera/transfer/result.rb +3 -0
- data/lib/aspera/transfer/resumer.rb +6 -4
- data/lib/aspera/transfer/spec.rb +9 -22
- data/lib/aspera/transfer/units.rb +75 -0
- data/lib/aspera/uri_reader.rb +57 -7
- data/lib/aspera/web_auth/index.html.erb +6 -2
- data/lib/aspera/web_auth/paste.rb +109 -0
- data/lib/aspera/web_auth/receiver.rb +50 -0
- data/lib/aspera/web_auth/relay.rb +76 -0
- data/lib/aspera/web_auth/reply.html.erb +150 -0
- data/lib/aspera/web_auth/server.rb +47 -10
- data/lib/aspera/web_page.rb +7 -2
- data/lib/aspera/web_server_simple.rb +6 -3
- data/lib/aspera/yaml.rb +5 -1
- data/llms.txt +81 -0
- data/skills/ascli/SKILL.md +88 -0
- data.tar.gz.sig +0 -0
- metadata +72 -19
- metadata.gz.sig +0 -0
- data/lib/aspera/keychain/base.rb +0 -30
- data/lib/aspera/keychain/encrypted_hash.rb +0 -192
- data/lib/aspera/keychain/factory.rb +0 -58
- data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
- data/lib/aspera/keychain/macos_security.rb +0 -277
- data/lib/aspera/keychain/one_password_api.rb +0 -91
- data/lib/aspera/keychain/one_password_base.rb +0 -39
- data/lib/aspera/keychain/one_password_cli.rb +0 -100
- data/lib/aspera/secret_hider.rb +0 -196
- data/lib/aspera/secret_strength.rb +0 -114
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 22b08acc7dfd929269009bc08f4419d5097e3d170d5095777a099efa9778ba58
|
|
4
|
+
data.tar.gz: c517da2115165b0ee092783ff62753a3f96cbb853758ba9ef5bc56b008dc2983
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
1
|
+
# Reporting bugs
|
|
2
2
|
|
|
3
|
-
Report bug
|
|
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
|
-

|
|
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 |
|
data/CODE_OF_CONDUCT.md
ADDED
|
@@ -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
|
-
|
|
3
|
+
By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
4
4
|
|
|
5
|
-
|
|
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 [
|
|
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
|
-
|
|
54
|
+
2. **Create a feature branch** specifically for your changes.
|
|
51
55
|
|
|
52
|
-
|
|
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
|
-
|
|
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 `
|
|
79
|
-
- Tests that should not appear in generated documentation get the `
|
|
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
|
-
-
|
|
122
|
+
- no_doc
|
|
94
123
|
expect: "unknown value"
|
|
95
124
|
args:
|
|
96
125
|
- config
|
|
97
126
|
- agents
|
|
98
127
|
- show
|
|
99
|
-
-
|
|
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
|
-
|
|
150
|
-
|
|
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
|
-

|
|
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
|
|
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
|
|
205
|
-
|
|
206
|
-
| `ASPERA_CLI_TEST_CONF_URL`
|
|
207
|
-
| `LOG_SECRETS`
|
|
208
|
-
| `LOG_LEVEL`
|
|
209
|
-
| `ENABLE_COVERAGE`
|
|
210
|
-
| `SIGNING_KEY`
|
|
211
|
-
| `DRY_RUN`
|
|
212
|
-
| `DEBUG`
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|