aspera-cli 4.25.0.pre → 4.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 412bbcc21114ffbdc44a31e61c2f666e1444a61d991ed8cbc0eff52ffcb43381
-  data.tar.gz: 3a1a191e2e05743c2e800902c17f6637181e4bcd2f8b34bec570ffa24b7913b7
+  metadata.gz: 9e812ee0dbd658feeaea8c37d4095df243f57a656b669e99460ca791585121a6
+  data.tar.gz: a52360171fc63925f01cd7562453484d04e795221c02c36b78e29c99ed25276e
 SHA512:
-  metadata.gz: 7c650e9c2cd0c1a9bf2f264b88464bd148e14acb45bed85f87752146ad91735812c00173dc1dcdb3fe0bfcf7e9ad58362c9a5fed209559be28a545aba8d4f639
-  data.tar.gz: '088400cc458134f6ca68f996e598ad6af70f57bf776de8eadd7687d2b47db805b5e8c91f84beb05c208619f25fb09191b99f0068f13e2d29379d2bd693dacb99'
+  metadata.gz: 70cb5577853b1c8c0a86e85dc55e0e43d9f0c2d18a58f9bf560375c67a76a04e1c06395321789ba8edbcec05c68e7642df2fb9ed5133a8c333992c8254e42dee
+  data.tar.gz: 0d25857a31812782d7f831b5f9b4e95962621d4a712dbcbfa9be3889359dc163ca5914a57d7fe5b543b7010d7051865400adc47c590e33ae6f56b7131183e0a6

data/CHANGELOG.md

@@ -10,9 +10,11 @@ Released: [Place date of release here]
 
 * **global**: All `Hash` and `Array` options are now cumulative (merged). Value `@none:` resets to empty value.
 * **global**: Improved error diagnostic during evaluation of extended value.
-* **global**: New Extended value modifier: `@:` (empty modifier) to evaluate remaining arguments as `Hash` or `Array`.
+* **global**: New extended value modifier: `@:` (empty modifier) to evaluate remaining arguments as `Hash` or `Array`.
+* **global**: New extended value modifier: `@stdin:chomp` reads stdin and removes `\n`.
 * `config`: New option: `parser` allows definition of default parser for extended values when expecting a `Hash` or `Array` type.
 * `orchestrator`: Commands now takes option `query`.
+* `aoc`: The admin command for `node` now support nodes owned by admin, so that secret is no more necessary.
 
 ### Issues Fixed
 
@@ -21,13 +23,17 @@ Released: [Place date of release here]
 
 ### Breaking Changes
 
+* `aoc`: Option `package_folder` is now a Hash instead of formatted String.
+* `aoc`: Deprecated option `scope`. It is selected from the command directly. For `bearer_token --scope=admin:all`, now use: `admin bearer_token`.
 * `server`: By default, SSH option `use_agent` is now `false`.
 * `config`: Removed option `use_product`, replaced with prefix `product:` of option `ascp_path`.
+* `config`: Secret lookup is no more automatic, activate setting option `secret` to `PRESET`.
 * `faspex5`: Removed deprecated (4.18) command in `admin`: `resource`, use resource name as command directly in `admin`.
-* `preview`: Replace gem `mimemagic` with `marcel`.
-* PDF manual is now generated for [releases](https://github.com/IBM/aspera-cli/releases) only.
+* `preview`: Replaced gem `mimemagic` with `marcel`.
+* **global**: Extended value modifier `@stdbin:` is replaced with `@stdin:bin`.
+* Build system uses now `rake` instead of `make` for easier portability on Windows.
+* PDF manual removed from repo, it is now generated for [releases](https://github.com/IBM/aspera-cli/releases) only.
 * HTML manual is not generated anymore.
-* Build system uses now `rake` instead of `make` for easier portability with Windows.
 
 ## 4.24.2
 
@@ -36,7 +42,7 @@ Released: 2025-10-24
 ### New Features
 
 * `direct`: Capability to send management messages to `ascp` on running sessions. e.g. change target rate.
-* `config`: Added command: `sync spec` to get sync parameters documentation. Also added to manual.
+* `config`: Added command: `sync spec` to get sync parameters' documentation. Also added to manual.
 
 ### Issues Fixed
 
@@ -309,17 +315,17 @@ Released: 2024-07-13
 * `config`: Command `remote_certificate` now takes a subcommand.
 * **global**: Moved a few internal classes in new/renamed modules
 * **global**: Deprecated pseudo transfer specification parameters starting with `EX_`:
-  * `EX_ssh_key_paths`. Use spec `ssh_private_key` or option `transfer_info={"ascp_args":["-i","..."]}`
-  * `EX_http_proxy_url`. Use option `transfer_info={"ascp_args":["-x","..."]}`
-  * `EX_http_transfer_jpeg`. Use option `transfer_info={"ascp_args":["-j","1"]}`
-  * `EX_no_read`. Use option `transfer_info={"ascp_args":["--no-read"]}`
-  * `EX_no_write`. Use option `transfer_info={"ascp_args":["--no-write"]}`
-  * `EX_file_list`. Use `ascli` file list feature or option `transfer_info={"ascp_args":["--file-list","..."]}`
-  * `EX_file_pair_list`. Use `ascli` file list feature or option `transfer_info={"ascp_args":["--file-pair-list","..."]}`
-  * `EX_ascp_args`. Use option `transfer_info={"ascp_args":[...]}`
-  * `EX_at_rest_password`. Use spec parameter `content_protection_password`
-  * `EX_proxy_password`. Set password in spec parameter `proxy` or use env var `ASPERA_PROXY_PASS`.
-  * `EX_license_text`. Use env var `ASPERA_SCP_LICENSE`.
+  * `EX_ssh_key_paths`: Use spec `ssh_private_key` or option `transfer_info={"ascp_args":["-i","..."]}`
+  * `EX_http_proxy_url`: Use option `transfer_info={"ascp_args":["-x","..."]}`
+  * `EX_http_transfer_jpeg`: Use option `transfer_info={"ascp_args":["-j","1"]}`
+  * `EX_no_read`: Use option `transfer_info={"ascp_args":["--no-read"]}`
+  * `EX_no_write`: Use option `transfer_info={"ascp_args":["--no-write"]}`
+  * `EX_file_list`: Use `ascli` file list feature or option `transfer_info={"ascp_args":["--file-list","..."]}`
+  * `EX_file_pair_list`: Use `ascli` file list feature or option `transfer_info={"ascp_args":["--file-pair-list","..."]}`
+  * `EX_ascp_args`: Use option `transfer_info={"ascp_args":[...]}`
+  * `EX_at_rest_password`: Use spec parameter `content_protection_password`
+  * `EX_proxy_password`: Set password in spec parameter `proxy` or use env var `ASPERA_PROXY_PASS`.
+  * `EX_license_text`: Use env var `ASPERA_SCP_LICENSE`.
 
 ## 4.16.0
 
@@ -1053,7 +1059,7 @@ Released: 2021-02-03
 
 ### Breaking Changes
 
-* **global**: @stdin is now @stdin
+* **global**: `@stdin` is now `@stdin:`
 
 ## 0.9.10
 

data/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Reporting Issues and Vulnerabilities
 
-If you encounter a problem or vulnerability, please report it at [GitHub Issues](https://github.com/IBM/aspera-cli/issues).
+If you encounter a problem or a security vulnerability, please report it on [GitHub Issues](https://github.com/IBM/aspera-cli/issues).
 
 Before submitting a new issue:
 
@@ -16,8 +16,8 @@ To help us assist you efficiently, include the following in your report:
   ascli version
   ```
 
-- Confirmation that you're using the latest version (update if not).
-- The output of your Ruby environment:
+- Confirmation that you are using the latest version (update it if needed).
+- Your Ruby version information:
 
   ```bash
   ruby -v
@@ -29,7 +29,7 @@ We welcome contributions to improve the `aspera-cli` project!
 
 ### Getting Started
 
-Clone the repository and navigate to the project's main folder:
+Clone the repository and navigate to the project's root directory:
 
 ```bash
 git clone https://github.com/IBM/aspera-cli.git
@@ -50,7 +50,7 @@ To submit a contribution:
 
 1. **Implement** your feature or bug fix.
 
-1. **Write tests** to ensure your changes are robust and won’t break future versions.
+1. **Write tests** to ensure your changes are robust and prevent regressions.
 
 1. Run `rubocop` to ensure your code follows the Ruby style guide.
 
@@ -67,25 +67,25 @@ The overall architecture of `aspera-cli` is modular and extensible.
 
 ![Architecture](docs/architecture.png)
 
-Structure Highlights:
+### Structure Highlights
 
 - Entry Point:
 
-  `lib/aspera/cli/main.rb` - This is where the CLI execution begins.
+  `lib/aspera/cli/main.rb`, CLI startup logic.
 
 - Plugins:
 
-  Located in `lib/aspera/cli/plugins`, plugins extend CLI functionality and encapsulate specific features.
+  Located in `lib/aspera/cli/plugins`; plugins extend CLI functionality and encapsulate specific features.
 
 - Transfer Agents:
 
-  Found in `lib/aspera/agent`, these handle data transfers operations.
+  Found in `lib/aspera/agent`, these handle data transfer operations.
 
-A list of classes are provided in <docs/uml.png>
+Class diagrams are provided in <docs/uml.png>
 
-## Ruby version
+## Ruby Environment
 
-`aspera-cli` is built with Ruby.
+`aspera-cli` is written in Ruby.
 You can install Ruby using any method you prefer (e.g., `rbenv`, `rvm`, system package manager).
 
 To start with a clean state and remove all installed gems:
@@ -97,30 +97,28 @@ bundle exec rake tools:clean_gems
 > [!TIP]
 > This is especially useful before testing across different Ruby versions or preparing for a release.
 
-## Tool chain
+## Toolchain
 
-TODO: document installation of tool chain.
-
-Build system uses Ruby's `rake`.
+The build system uses Ruby's `rake`.
 
 ### Environment
 
-A few macros/env vars control some aspects:
+A few macros and environment variables control certain aspects of the build:
 
-| Environment variable        | Description                                        |
-|-----------------------------|----------------------------------------------------|
-| `ASPERA_CLI_TEST_CONF_FILE` | Path to configuration file with secrets for tests. |
-| `ASPERA_CLI_DOC_CHECK_LINKS`| Check links still exist during doc generation.     |
-| `LOG_LEVEL`                 | Change log level in `rake` tasks.                  |
-| `ENABLE_COVERAGE`           | Tests with coverage analysis if set.               |
-| `SIGNING_KEY`               | Path to signing key to build Gem.                  |
-| `GEM_VERSION`               | Override gem version for builds.                   |
+| Environment variable        | Description                                         |
+|-----------------------------|-----------------------------------------------------|
+| `ASPERA_CLI_TEST_CONF_URL`  | URL for configuration file with secrets for tests.  |
+| `ASPERA_CLI_DOC_CHECK_LINKS`| Check links still exist during doc generation.      |
+| `LOG_LEVEL`                 | Change log level in `rake` tasks.                   |
+| `ENABLE_COVERAGE`           | Enable test coverage analysis when set.             |
+| `SIGNING_KEY`               | Path to the signing key used to build the gem file. |
+| `GEM_VERSION`               | Override gem version for builds.                    |
 
-Those macros can be set either in an env var, or on the `rake` command line.
+These can be set either as environment variables or directly on the `rake` command line.
 
 > [!NOTE]
-> Env vars `ASPERA_CLI_*` are typically set in user's shell profile for development.
-> Others are more for "one shot" use (on command line).
+> Environment variables `ASPERA_CLI_*` are typically set in the user’s shell profile for development.
+> Others are intended for use on the command line.
 
 To use the CLI directly from the development environment, add this to your shell profile (adapt the real path):
 
@@ -134,9 +132,9 @@ export RUBYLIB=$dev_ascli/lib:$RUBYLIB
 
 Documentation is generated with `pandoc` and `LaTeX`.
 
-IBM font `Plex` is used, for installation see [IBM Plex](https://www.ibm.com/plex/).
+The IBM `Plex` font is used; for installation instructions, see [IBM Plex](https://www.ibm.com/plex/).
 
-On macOS to install `lualatex` and all packages:
+On macOS, to install `lualatex` and all packages:
 
 ```bash
 brew install texlive
@@ -149,9 +147,9 @@ tlmgr update --self
 tlmgr install fvextra selnolig lualatex-math
 ```
 
-To check URL during doc generation, set env var: `ASPERA_CLI_DOC_CHECK_LINKS=1`.
+To check URLs during documentation generation, set the environment variable: `ASPERA_CLI_DOC_CHECK_LINKS=1`.
 
-To debug doc generation, set env var: `ASPERA_CLI_DOC_DEBUG=debug`.
+To debug documentation generation, set the environment variable: `ASPERA_CLI_DOC_DEBUG=debug`.
 
 ## Test Environment
 
@@ -159,11 +157,11 @@ Refer to <tests/README.md>.
 
 ## Build
 
-The gem is built with:
+The unsigned gem is built with:
 
 ```bash
 bundle install
-bundle exec rake build
+bundle exec rake unsigned
 ```
 
 If you don't want to install optional gems:
@@ -172,7 +170,7 @@ If you don't want to install optional gems:
 bundle config set without optional
 ```
 
-Build beta version:
+To build a beta version:
 
 ```bash
 export GEM_VERSION=$(env -u GEM_VERSION rake tools:version).$(date +%Y%m%d%H%M)
@@ -180,12 +178,12 @@ export GEM_VERSION=$(env -u GEM_VERSION rake tools:version).$(date +%Y%m%d%H%M)
 
 ### Signed gem
 
-A private key is required to generate a signed Gem.
-Its path must be set using envvar `SIGNING_KEY`.
-The gem is signed with the public certificate found in `certs` and the private key pointed by `SIGNING_KEY` (kept secret by maintainer).
+A private key is required to generate a signed gem.
+Its path must be set using environment variable `SIGNING_KEY`.
+The gem is signed with the public certificate found in `certs` and the private key specified by `SIGNING_KEY` (kept secret by the maintainer).
 
 ```bash
-bundle exec rake build SIGNING_KEY=/path/to/vault/gem-private_key.pem
+bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
 ```
 
 Refer to <certs/README.md>.
@@ -198,7 +196,7 @@ Update with:
 bundle exec rake tools:grpc
 ```
 
-It downloads the latest proto file and then compiles it.
+It downloads the latest `proto` file and then compiles it.
 
 ## Container image build
 
@@ -214,16 +212,90 @@ To list operations:
 bundle exec rake -T ^binary:
 ```
 
-## Development check list for new release
+## Release
+
+### Branching Strategy
+
+This project uses a single `main` branch for development. During the development cycle, the version in `lib/aspera/cli/version.rb` uses a `.pre` suffix (e.g., `x.y.z.pre`) to indicate a pre-release state.
+
+Feature development and bug fixes can be done either:
+
+- Directly on `main` for small changes
+- Via feature branches with pull requests for larger changes
+
+### Checklist Before a New Release
+
+When preparing for a new release, do the following:
+
+- Run the test suite:
+
+```bash
+bundle exec rake test:run
+```
+
+- Verify that the container builds successfully (using the beta version):
+
+```bash
+export GEM_VERSION=$(env -u GEM_VERSION rake tools:version).$(date +%Y%m%d%H%M)
+bundle exec rake container:build
+bundle exec rake container:test
+```
+
+### Automated Release Process
+
+Releases are triggered via the GitHub Actions UI using the **Release** workflow (`.github/workflows/release.yml`).
+
+To create a release:
+
+1. Navigate to **Actions** > **Release** in the GitHub repository
+2. Click **Run workflow**
+3. Optionally specify:
+   - **Release version**: The version to release. If left empty, uses the current version from `version.rb` without the `.pre` suffix.
+   - **Next development version**: The next version to prepare for. If left empty, auto-increments the minor version. The `.pre` suffix is added automatically.
+4. Click **Run workflow**
+
+The workflow automatically:
+
+1. Updates `version.rb` with the release version
+2. Rebuilds documentation (PDF manual, README)
+3. Commits the changes
+4. Creates and pushes the release tag
+5. Triggers the deploy workflow to publish to [rubygems.org](https://rubygems.org/gems/aspera-cli)
+6. Updates `version.rb` to the next development version with `.pre` suffix
+7. Commits and pushes the version bump
+
+### Manual Release Process (Alternative)
+
+If needed, releases can still be done manually:
+
+- Update the version in `lib/aspera/cli/version.rb` (remove `.pre` suffix)
+
+- Build the PDF manual in `pkg`:
+
+```shell
+bundle exec rake doc:build
+```
+
+- Build the signed `.gem` in `pkg`:
+
+```shell
+bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
+```
+
+- Create the release version tag and push it to GitHub:
+
+```shell
+bundle exec rake release_tag
+```
 
-When preparing for a new release do the following:
+This will trigger the action `.github/workflows/deploy.yml`, which builds the gem file and pushes it to RubyGems.
 
-- TODO
+- After release, update `version.rb` to the next development version with `.pre` suffix
 
-## Long Term Implementation and delivery improvements
+## Long‑Term Implementation and Delivery Improvements
 
-- replace Rest and OAuth classes with ruby standard gems:
+- Replace custom REST and OAuth classes with standard Ruby gems:
   - <https://github.com/rest-client/rest-client>
   - <https://github.com/oauth-xx/oauth2>
-- use gem Thor <http://whatisthor.com/> (or other standard Ruby CLI manager)
-- look at <https://github.com/phusion/traveling-ruby>
+- Use the `thor` gem <http://whatisthor.com/> (or other standard Ruby CLI manager)
+- Look at <https://github.com/phusion/traveling-ruby>