aspera-cli 4.26.1 → 4.27.0

data/CONTRIBUTING.md

@@ -50,18 +50,110 @@ To submit a contribution, follow these steps:
 1. **Create a feature branch** specifically for your changes.
 
 1. **Implement** your feature or bug fix.
-
-1. **Write tests** to ensure your changes are robust and prevent regressions.
-
-1. **Run** `rubocop` to ensure your code adheres to the Ruby style guide.
-
-1. **Update** `CHANGELOG.md` with a concise summary of your changes.
+   See [Development Cycle for a New CLI Command](#development-cycle-for-a-new-cli-command) for the complete checklist.
 
 1. **Submit a pull request** with a detailed description of your work.
 
 > [!TIP]
 > Keep pull requests focused; include only changes relevant to the specific feature or fix.
 
+### Development Cycle for a New CLI Command
+
+When adding or modifying a CLI command, complete **every step** in the following order.
+Each step is self-contained so that an automated agent can apply them independently.
+
+#### 1 — Implement
+
+- Add the command logic in the relevant plugin file under `lib/aspera/cli/plugins/`.
+- If the command belongs to a mixin (e.g. `AscpActions`, `PresetActions`), add the method in the corresponding file under `lib/aspera/cli/`.
+- Declare the new command with `command(...)` at class level and implement the corresponding `handle_<path>` method.
+- For agent-related schemas, declare parameters in `lib/aspera/cli/options.schema.yaml` under `components/schemas/`.
+
+#### 2 — Add tests in `tests/tests.yml`
+
+Every new command needs at least one entry in `tests/tests.yml`.
+Follow the naming convention `<plugin>_<sub>_<action>` (e.g. `conf_agents_list`).
+
+- Add a **happy-path** test (no extra tags).
+- Add a **failure test** for invalid input with tags `must_fail` and `nodoc`, and set `expect:` to a substring of the expected error message.
+- Tests that should not appear in generated documentation get the `nodoc` tag.
+- Insert the new entries near related tests (same plugin/sub-command group).
+
+Minimal example:
+
+```yaml
+conf_agents_list:
+  args:
+    - config
+    - agents
+    - list
+conf_agents_show_bad:
+  tags:
+    - must_fail
+    - nodoc
+  expect: "unknown value"
+  args:
+    - config
+    - agents
+    - show
+    - badagent
+```
+
+Run only the new tests to validate quickly:
+
+```shell
+bundle exec rake test:run'[conf_agents_list conf_agents_show_bad]'
+```
+
+#### 3 — Update `docs/README.erb.md`
+
+`docs/README.erb.md` is the source for the generated documentation (`docs/README.md` and the PDF manual).
+**Never edit `docs/README.md` directly.**
+
+- Find the section closest to the new command (search for the parent command or a sibling).
+- Add a short prose paragraph and one or more fenced `shell` blocks showing usage.
+- Use ERB variables: `<%=cmd%>` for the tool name, `<%=tool%>` for the display name, `<%=ph :name%>` for placeholders.
+- For parameter tables generated from JSON schema, use `<%=schema_to_table(Aspera::Schema::Registry::MY_SCHEMA_KEY)%>`.
+
+Regenerate and verify:
+
+```shell
+bundle exec rake doc:prep
+```
+
+#### 4 — Update `CHANGELOG.md`
+
+Add one bullet under `### New Features` (or `### Issues Fixed` / `### Breaking Changes`) in the current `.pre` section at the top of `CHANGELOG.md`.
+
+Style rules:
+- Plugin name in backticks: `` `config` ``, `` `aoc` ``, or `**global**` for cross-cutting changes.
+- Command path and argument names in backticks.
+- One sentence per bullet; end without a period.
+
+Example:
+
+```markdown
+* `config`: New commands `agents list`, `agents show <name>` and `agents parameters <name>` to discover available transfer agents, their short identifier and their configurable parameters
+```
+
+#### 5 — Static analysis
+
+```shell
+bundle exec rake tools:rubocop   # Ruby style guide
+bundle exec rake tools:reek      # code smell detection
+```
+
+Fix any new offence introduced by your changes before committing.
+Pre-existing offences listed in `.rubocop_todo.yml` can be left as-is.
+
+#### 6 — Full test suite
+
+```shell
+bundle exec rake test:run
+```
+
+All tests must pass (status `passed`) before opening a pull request.
+
 ## Architecture
 
 The `aspera-cli` architecture is designed to be modular and extensible.
@@ -72,7 +164,7 @@ The `aspera-cli` architecture is designed to be modular and extensible.
 
 - **Entry Point**:
 
-  `lib/aspera/cli/main.rb` contains the core CLI startup logic.
+  `lib/aspera/cli/runner.rb` contains the core CLI startup logic.
 
 - **Plugins**:
 
@@ -112,15 +204,12 @@ The following environment variables and macros control specific build behaviors:
 | `LOG_SECRETS`               | `yes`/`no` | Toggles the logging of secrets in `rake` tasks.              |
 | `LOG_LEVEL`                 | `debug`, ... | Sets the logging verbosity for `rake` tasks.                 |
 | `ENABLE_COVERAGE`           | set/unset  | Enables test coverage analysis when defined.                 |
-| `SIGNING_KEY`               | File path  | Path to the signing key used for building the gem file.      |
-| `SIGNING_KEY_PEM`           | PEM Value  | The PEM content of the signing key.                          |
+| `SIGNING_KEY`               | File path or PEM | Path to the signing key file, or PEM content (starts with `-----BEGIN`). |
 | `DRY_RUN`                   | `1`        | Simulates execution without performing actual operations (`git`, `gh`). |
 | `DEBUG`                     | `1`        | Shows stack trace on errors during documentation generation. |
 
 These values can be set as standard environment variables or passed directly to the `rake` command.
 
-Setting `SIGNING_KEY_PEM` automatically generates a file at `$HOME/.gem/signing_key.pem` and sets the `SIGNING_KEY` variable accordingly.
-
 > [!NOTE]
 > `ASPERA_CLI_TEST_CONF_URL` is typically defined in your shell profile for development, while others are usually for ad-hoc command-line use.
 
@@ -321,5 +410,4 @@ This triggers the `.github/workflows/deploy.yml` action to publish to RubyGems.
 - Evaluate replacing custom REST and OAuth implementations with standard gems:
   - [rest-client](https://github.com/rest-client/rest-client)
   - [oauth2](https://github.com/oauth-xx/oauth2)
-- Integrate `thor` <http://whatisthor.com/> or another standard Ruby CLI framework.
 - Explore [Traveling Ruby](https://github.com/phusion/traveling-ruby) for distribution, or [truby Traveling Ruby](https://github.com/trubygems/traveling-ruby).

data/bin/ascli

@@ -20,9 +20,9 @@ Aspera::Log.instance.program_name = Aspera::Cli::Info::CMD_NAME
 ARGV.each do |arg|
   case arg
   when '--' then break
-  when /^--log-level=(.*)/ then Aspera::Log.instance.level = Regexp.last_match(1).to_sym
-  when /^--log-format=(.*)/ then Aspera::Log.instance.formatter = Regexp.last_match(1) unless Regexp.last_match(1).start_with?('@ruby:')
-  when /^--logger=(.*)/ then Aspera::Log.instance.logger_type = Regexp.last_match(1).to_sym
+  when /^--log-level=(.*)/, /^--log\.level=(.*)/ then Aspera::Log.instance.level = Regexp.last_match(1).to_sym
+  when /^--log-format=(.*)/, /^--log\.format=(.*)/ then Aspera::Log.instance.formatter = Regexp.last_match(1) unless Regexp.last_match(1).start_with?('@ruby:')
+  when /^--logger=(.*)/, /^--log\.type=(.*)/ then Aspera::Log.instance.logger_type = Regexp.last_match(1).to_sym
   end
 rescue => e
   $stderr.puts("Error: #{e}") # rubocop:disable Style/StderrPuts
@@ -31,6 +31,6 @@ end
 
 require 'aspera/coverage'
 require 'aspera/environment'
-require 'aspera/cli/main'
+require 'aspera/cli/runner'
 Aspera::Environment.instance.fix_home
-Aspera::Cli::Main.new(ARGV).process_command_line
+Aspera::Cli::Runner.new(ARGV).run