aspera-cli 4.26.2 → 4.27.1

data/CONTRIBUTING.md

@@ -50,18 +50,111 @@ 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.
@@ -312,11 +405,3 @@ bundle exec rake release_tag
 This triggers the `.github/workflows/deploy.yml` action to publish to RubyGems.
 
 - Update `version.rb` to the next `.pre` development version.
-
-## Future Improvements
-
-- 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/TODO.md

@@ -0,0 +1,50 @@
+# TODO
+
+Ideas and TODO list.
+Add improvement ideas here.
+
+## Preview: deletion of orphaned preview files
+
+Deletion of preview files for deleted source files is not yet implemented.
+
+## Architecture: replace custom REST client with `rest-client` gem
+
+Evaluate replacing the custom REST implementation with the standard
+[`rest-client`](https://github.com/rest-client/rest-client) gem.
+
+## Architecture: replace custom OAuth client with `oauth2` gem
+
+Evaluate replacing the custom OAuth 2.0 implementation with the standard
+[`oauth2`](https://github.com/oauth-xx/oauth2) gem.
+
+## Architecture: explore Traveling Ruby for single-executable distribution
+
+Explore [Traveling Ruby](https://github.com/phusion/traveling-ruby)
+(or [truby Traveling Ruby](https://github.com/trubygems/traveling-ruby)) as an alternative
+single-executable distribution method.
+
+## OCRAN packaging
+
+## Add `description:` to all `ArgumentSpec` declarations
+
+The `description` field is user-facing (shown in `--help` output) and should be present on
+every `ArgumentSpec`. Arguments that already carry a `schema:` key or whose name is
+self-explanatory are lower priority, but all should have explicit descriptions eventually.
+
+Example fix:
+
+```ruby
+# Before
+{name: :async_id, type: :identifier, lookup: :async_lookup}
+
+# After
+{name: :async_id, description: 'Async operation identifier', type: :identifier, lookup: :async_lookup}
+```
+
+## DSL: Scoped options declaration and contextual documentation
+
+Improve the DSL to distinguish between global CLI options, plugin-level options, and command-scoped options:
+
+- **DSL declaration**: Allow options to be declared with reduced/specific scopes (e.g., at command/subtree level via `command(..., options: [...])` or `scope:` parameter on `option`) in addition to global and plugin-wide options.
+- **Contextual `--help`**: In `--help` output, display only options relevant to the targeted command/path (command-specific, plugin-wide, and global sections).
+- **Documentation generation**: Enhance documentation generator to display scoped options only under the concerned commands.

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