aspera-cli 4.29.0 → 4.29.1

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 (78) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +2 -1
  3. data/CHANGELOG.md +76 -2
  4. data/README.md +20 -1
  5. data/SECURITY.md +14 -0
  6. data/docs/README.md +277 -38
  7. data/lib/aspera/api/node.rb +9 -2
  8. data/lib/aspera/ascp/installation.rb +26 -4
  9. data/lib/aspera/ascp/log_analyzer/lines.rb +2 -2
  10. data/lib/aspera/ascp/log_analyzer.rb +19 -3
  11. data/lib/aspera/ascp/log_locations.rb +163 -0
  12. data/lib/aspera/cli/ascp_logs_actions.rb +12 -0
  13. data/lib/aspera/cli/bootstrapper.rb +1 -0
  14. data/lib/aspera/cli/command_line.rb +39 -2
  15. data/lib/aspera/cli/command_registry.rb +3 -0
  16. data/lib/aspera/cli/command_spec.rb +13 -0
  17. data/lib/aspera/cli/error.rb +3 -0
  18. data/lib/aspera/cli/extended_value.rb +5 -4
  19. data/lib/aspera/cli/formatter.rb +14 -8
  20. data/lib/aspera/cli/http.rb +26 -1
  21. data/lib/aspera/cli/info.rb +1 -1
  22. data/lib/aspera/cli/mcp/tool.rb +5 -3
  23. data/lib/aspera/cli/option_value.rb +14 -8
  24. data/lib/aspera/cli/options.schema.yaml +156 -19
  25. data/lib/aspera/cli/parser.rb +15 -3
  26. data/lib/aspera/cli/plugins/aoc.rb +4 -2
  27. data/lib/aspera/cli/plugins/ats.rb +1 -1
  28. data/lib/aspera/cli/plugins/base.rb +33 -6
  29. data/lib/aspera/cli/plugins/config.rb +12 -1
  30. data/lib/aspera/cli/plugins/faspex5.rb +3 -1
  31. data/lib/aspera/cli/plugins/mcp.rb +14 -0
  32. data/lib/aspera/cli/plugins/node.rb +8 -8
  33. data/lib/aspera/cli/plugins/oauth.rb +18 -5
  34. data/lib/aspera/cli/plugins/orchestrator.rb +28 -24
  35. data/lib/aspera/cli/plugins/preview.rb +3 -1
  36. data/lib/aspera/cli/plugins/server.rb +3 -3
  37. data/lib/aspera/cli/plugins/shares.rb +1 -2
  38. data/lib/aspera/cli/plugins/transferd.rb +7 -2
  39. data/lib/aspera/cli/poll.rb +236 -0
  40. data/lib/aspera/cli/preset_manager.rb +63 -19
  41. data/lib/aspera/cli/prompt.rb +153 -8
  42. data/lib/aspera/cli/runner.rb +25 -7
  43. data/lib/aspera/cli/security.rb +10 -0
  44. data/lib/aspera/cli/sync_actions.rb +2 -0
  45. data/lib/aspera/cli/transfer_agent.rb +14 -0
  46. data/lib/aspera/cli/transfer_progress.rb +6 -5
  47. data/lib/aspera/cli/version.rb +1 -1
  48. data/lib/aspera/environment.rb +3 -1
  49. data/lib/aspera/id_generator.rb +16 -3
  50. data/lib/aspera/inflate.rb +43 -0
  51. data/lib/aspera/oauth/client/base.rb +38 -8
  52. data/lib/aspera/oauth/client/factory.rb +35 -15
  53. data/lib/aspera/oauth/client/json_credentials.rb +3 -2
  54. data/lib/aspera/oauth/client/shares_web.rb +13 -4
  55. data/lib/aspera/oauth/client/url_json.rb +3 -2
  56. data/lib/aspera/oauth/client/web.rb +2 -2
  57. data/lib/aspera/orchestrator_workflow_checker.rb +10 -1
  58. data/lib/aspera/preview/terminal.rb +8 -2
  59. data/lib/aspera/products/desktop.rb +13 -1
  60. data/lib/aspera/rest/client.rb +23 -5
  61. data/lib/aspera/schema/registry.rb +1 -0
  62. data/lib/aspera/sealed_hash.rb +2 -18
  63. data/lib/aspera/secret/hider.rb +13 -1
  64. data/lib/aspera/secret/store/one_password_cli.rb +13 -11
  65. data/lib/aspera/sync/operations.rb +4 -4
  66. data/lib/aspera/transfer/result.rb +20 -0
  67. data/lib/aspera/transfer/spec.rb +2 -2
  68. data/lib/aspera/{transfer/units.rb → units/decimal.rb} +4 -12
  69. data/lib/aspera/units/duration.rb +109 -0
  70. data/lib/aspera/uri_reader.rb +11 -6
  71. data/lib/aspera/web_auth/reply.html.erb +1 -1
  72. data/llms-install.md +88 -0
  73. data/llms.txt +6 -0
  74. data/skills/ascli/SKILL.md +6 -0
  75. data.tar.gz.sig +0 -0
  76. metadata +7 -3
  77. metadata.gz.sig +0 -0
  78. data/lib/aspera/duration.rb +0 -45
@@ -119,7 +119,7 @@ module Aspera
119
119
  # @param log [Boolean] whether to log the value retrieval
120
120
  # @return [Object] current value
121
121
  def value(log: true)
122
- Log.log.trace1 { "#{@option} -> (#{@value.class})#{@value}" } if log
122
+ Log.log.trace1 { "#{@option} -> (#{@value.class})#{Secret::Hider.instance.hidden_copy(@value)}" } if log
123
123
  @value
124
124
  end
125
125
 
@@ -152,7 +152,8 @@ module Aspera
152
152
  new_value = coerce(ExtendedValue.instance.evaluate(value, context: "option: #{@option}", allowed: @types))
153
153
  check_sub_options_security(new_value) if restricted_source?(source)
154
154
  new_value = {@shorthand => new_value} if @shorthand && new_value.is_a?(String)
155
- Log.log.trace1 { "#{source}: #{@option} <- (#{new_value.class})#{new_value}" }
155
+ declare_secrets(new_value)
156
+ Log.log.trace1 { "#{source}: #{@option} <- (#{new_value.class})#{Secret::Hider.instance.hidden_copy(new_value)}" }
156
157
  Aspera.assert_type(new_value, *@types, type: BadArgument) { "Option #{@option}" } if @types
157
158
  new_value = @convert.call(new_value) if @convert && new_value.is_a?(Hash)
158
159
  if merge && (new_value.is_a?(Hash) || new_value.is_a?(Array))
@@ -321,15 +322,20 @@ module Aspera
321
322
  end
322
323
  end
323
324
 
324
- # @param new_value [Object] value to store
325
- # @param source [Symbol, nil] `OptionSource` of value
326
- def store(new_value, source)
327
- # Secret values are hidden wherever they appear: logs, results
325
+ # Secret values are hidden wherever they appear: logs, results
326
+ # @param value [Object] value of option
327
+ def declare_secrets(value)
328
328
  if @sensitive
329
- Secret::Hider.instance.add_secret_values(new_value)
329
+ Secret::Hider.instance.add_secret_values(value)
330
330
  else
331
- Secret::Hider.instance.add_secrets_in(new_value)
331
+ Secret::Hider.instance.add_secrets_in(value)
332
332
  end
333
+ end
334
+
335
+ # @param new_value [Object] value to store
336
+ # @param source [Symbol, nil] `OptionSource` of value
337
+ def store(new_value, source)
338
+ declare_secrets(new_value)
333
339
  @value = new_value
334
340
  @source = source
335
341
  @on_set&.call(new_value)
@@ -73,6 +73,12 @@ components:
73
73
  - port
74
74
  - paste
75
75
  default: port
76
+ hidden_silent:
77
+ type: boolean
78
+ description: >-
79
+ Secrets typed or pasted on a terminal are read without any feedback (no echo, no mark), as `getpass`.
80
+ By default, a mark shows whether something was typed or pasted, without revealing the length.
81
+ default: false
76
82
  command:
77
83
  type: array
78
84
  x-security: low
@@ -95,9 +101,9 @@ components:
95
101
  description: >-
96
102
  - `low`: no restriction.
97
103
 
98
- - `medium`: `@file:` reads only files in `allowed_paths`, `@ruby:`, `@uri:` and `@env:` are refused, files are written only in `writable_paths`.
104
+ - `medium`: `@file:` reads only files in `allowed_paths`, `@ruby:`, `@uri:`, `@env:` and `@zlib:` are refused, files are written only in `writable_paths`.
99
105
 
100
- - `high`: `@ruby:`, `@file:`, `@uri:` and `@env:` are refused, files are written only in `writable_paths`.
106
+ - `high`: `@ruby:`, `@file:`, `@uri:`, `@env:` and `@zlib:` are refused, files are written only in `writable_paths`.
101
107
 
102
108
  Features that execute code, load plugins, or write a file chosen by the client (e.g. `--out.file`) are available only at level `low`.
103
109
  enum:
@@ -585,26 +591,46 @@ components:
585
591
 
586
592
  Keys are dispatched at startup to three targets:
587
593
  `Rest::Parameters` (`user_agent`, `download_partial_suffix`, `retry_*`),
588
- `SSL` (`ssl_options`), and `OAuth` (`token_cache_max_age`, `token_refresh_threshold`).
594
+ `SSL` (`ssl_options`), and `OAuth` (`token_*`, `jwt_*`).
589
595
  Any remaining key is forwarded as a setter to the `Net::HTTP` session
590
596
  (e.g. `ca_file`, `verify_mode`) — the list below covers the common ones.
591
597
  additionalProperties: true
592
598
  properties:
593
599
  read_timeout:
594
- type: number
595
- description: Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)
600
+ oneOf:
601
+ - type: string
602
+ - type: number
603
+ minimum: 0
604
+ description: >-
605
+ Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)
606
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
596
607
  default: 60
597
608
  write_timeout:
598
- type: number
599
- description: Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)
609
+ oneOf:
610
+ - type: string
611
+ - type: number
612
+ minimum: 0
613
+ description: >-
614
+ Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)
615
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
600
616
  default: 60
601
617
  open_timeout:
602
- type: number
603
- description: Maximum time in seconds to wait for a connection to be established. (Net::HTTP)
618
+ oneOf:
619
+ - type: string
620
+ - type: number
621
+ minimum: 0
622
+ description: >-
623
+ Maximum time in seconds to wait for a connection to be established. (Net::HTTP)
624
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
604
625
  default: 60
605
626
  keep_alive_timeout:
606
- type: number
607
- description: Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)
627
+ oneOf:
628
+ - type: string
629
+ - type: number
630
+ minimum: 0
631
+ description: >-
632
+ Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)
633
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
608
634
  default: 2
609
635
  ssl_options:
610
636
  type: array
@@ -635,17 +661,60 @@ components:
635
661
  description: Maximum number of retry attempts. (Rest)
636
662
  default: 1
637
663
  retry_sleep:
638
- type: integer
639
- description: Delay in seconds between retry attempts. (Rest)
664
+ oneOf:
665
+ - type: string
666
+ - type: number
667
+ minimum: 0
668
+ description: >-
669
+ Delay in seconds between retry attempts. (Rest)
670
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
640
671
  default: 4
641
672
  token_cache_max_age:
642
- type: integer
643
- description: Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)
673
+ oneOf:
674
+ - type: string
675
+ - type: number
676
+ minimum: 0
677
+ description: >-
678
+ Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)
679
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
644
680
  default: 1800
645
681
  token_refresh_threshold:
646
- type: integer
647
- description: Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)
682
+ oneOf:
683
+ - type: string
684
+ - type: number
685
+ minimum: 0
686
+ description: >-
687
+ Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)
688
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
648
689
  default: 120
690
+ token_refresh_max_age:
691
+ oneOf:
692
+ - type: string
693
+ - type: number
694
+ minimum: 0
695
+ description: >-
696
+ Age in seconds (since it was obtained) above which the token is proactively refreshed, `0` for no limit.
697
+ E.g. keeps a session alive when the refresh token expires at the same time as the token (Shares). (OAuth)
698
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
699
+ default: 0
700
+ jwt_accepted_offset_sec:
701
+ oneOf:
702
+ - type: string
703
+ - type: number
704
+ minimum: 0
705
+ description: >-
706
+ Tolerance of clock difference with the server: a generated JWT is valid since this duration in the past (`nbf`). (OAuth)
707
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
708
+ default: 300
709
+ jwt_expiry_offset_sec:
710
+ oneOf:
711
+ - type: string
712
+ - type: number
713
+ minimum: 0
714
+ description: >-
715
+ Validity of a generated JWT, used to request a token. (OAuth)
716
+ A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
717
+ default: 3600
649
718
  VaultHashicorpOptions:
650
719
  type: object
651
720
  description: >-
@@ -1265,10 +1334,10 @@ components:
1265
1334
  examples:
1266
1335
  - /opt/aspera/orchestrator/var/run/orchestrator/workflows/import/my_workflow.yml
1267
1336
  add_as_revision:
1268
- type: integer
1337
+ type: [integer, 'null']
1269
1338
  description: >-
1270
1339
  ID of an existing workflow: the file is imported as a new revision of this workflow (to be published).
1271
- If not set, a new workflow is created.
1340
+ If not set, or `null`, a new workflow is created.
1272
1341
  examples:
1273
1342
  - 123
1274
1343
  subwf_constraints:
@@ -1437,6 +1506,74 @@ components:
1437
1506
  Default is auto-detected: enabled if stdout is a terminal and the locale is UTF-8, or on Windows, the terminal renders Unicode (e.g. Windows Terminal, VS Code).
1438
1507
  img:
1439
1508
  $ref: "#/components/schemas/ImageOptions"
1509
+ PollOptions:
1510
+ type: object
1511
+ description: >-
1512
+ Repeat a read-only command (e.g. `list`, `show`, `status`) and display its result,
1513
+ until a condition is met, or a number of runs or a time is reached.
1514
+ The command runs first immediately, then again `interval` seconds after the end of each run.
1515
+ Without `max`, `timeout` and `until`, it runs until interrupted (Ctrl-C).
1516
+ Refused on a command that changes state (e.g. `send`, `create`, `delete`, `start`), before anything is executed.
1517
+ Formatting options (`--format`, `--fields`, `--out.query`) apply to each result displayed.
1518
+ A short status line on `stderr` gives the run number and the time before each result displayed.
1519
+ By default, an error of a run (e.g. an API error) ends the command with that error (see `errors`).
1520
+ additionalProperties: false
1521
+ properties:
1522
+ interval:
1523
+ oneOf:
1524
+ - type: number
1525
+ minimum: 0
1526
+ - type: string
1527
+ description: >-
1528
+ Time to wait after a run, before the next one.
1529
+ A duration: a number of seconds, or a `String`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00` (rounded down to seconds).
1530
+ default: 5
1531
+ max:
1532
+ type: integer
1533
+ minimum: 1
1534
+ description: Maximum number of runs. No limit by default.
1535
+ timeout:
1536
+ oneOf:
1537
+ - type: number
1538
+ minimum: 0
1539
+ - type: string
1540
+ description: >-
1541
+ Maximum time since the start of the first run.
1542
+ A duration, as `interval`, e.g. `600`, `10m`, `1h`.
1543
+ A last run occurs at this time. No limit by default.
1544
+ With `max`, polling stops at the first limit reached.
1545
+ until:
1546
+ type: string
1547
+ description: >-
1548
+ JMESPath expression (https://jmespath.org) evaluated on the JSON view of the result data:
1549
+ after `--select` (for a list of objects), before `--fields` and `--out.query`.
1550
+ Polling stops at the first run where it is true: as in JMESPath, `false`, `null`, empty string, empty list and empty object are false, other values are true.
1551
+ So `@` (the data itself) waits for a non-empty result, e.g. a list with at least one item.
1552
+ The syntax is checked before the first run.
1553
+ If the condition is not met after the last run (`max` or `timeout`), the command fails (exit code 1).
1554
+ show:
1555
+ type: string
1556
+ description: >-
1557
+ Which results are displayed.
1558
+
1559
+ - `change`: the first result, then each result whose display differs from the previous one.
1560
+
1561
+ - `each`: every result.
1562
+
1563
+ - `last`: only the last result, when polling stops (including when the condition is not met).
1564
+ enum: [change, each, last]
1565
+ default: change
1566
+ errors:
1567
+ type: string
1568
+ description: >-
1569
+ What an error of a run does (e.g. an API error, an entity not found yet).
1570
+
1571
+ - `fail`: the command ends with this error.
1572
+
1573
+ - `retry`: the error is shown on the status line, and the command runs again, as for a result where `until` is false.
1574
+ If the last run fails, the command ends with its error.
1575
+ enum: [fail, retry]
1576
+ default: fail
1440
1577
  WebServerOptions:
1441
1578
  type: object
1442
1579
  description: >-
@@ -243,13 +243,15 @@ module Aspera
243
243
  #
244
244
  # @param description [String] description of the identifier
245
245
  # @param multiple [Boolean] `true`: read a list of IDs (bulk operation)
246
+ # @param mandatory [Boolean] `false`: the identifier may be absent, then `default` is returned
247
+ # @param default [Object] value when the identifier is absent and not mandatory
246
248
  # @param block [Proc] block to search for identifier based on attribute value
247
249
  # @return [String, Array<String>] identifier or list of IDs (if `multiple`)
248
250
  # @yieldparam field [String] The field name from percent selector
249
251
  # @yieldparam value [String] The value from percent selector
250
252
  # @yieldreturn [String] Resolved identifier
251
- def instance_identifier(description: 'identifier', multiple: false, &block)
252
- res_id = get_next_argument(description, multiple: multiple)
253
+ def instance_identifier(description: 'identifier', multiple: false, mandatory: true, default: nil, &block)
254
+ res_id = get_next_argument(description, multiple: multiple, mandatory: mandatory, default: default)
253
255
  # Can be an Array
254
256
  if res_id.is_a?(String) && (m = Parser.percent_selector(res_id))
255
257
  Aspera.assert(block_given?, type: Cli::BadArgument) { "Percent syntax for #{description} not supported in this context" }
@@ -403,7 +405,8 @@ module Aspera
403
405
  result = {}
404
406
  @command_line.each_long_option_with_value(after_command: after_command) do |tok|
405
407
  path = [tok.name, *tok.dot_path]
406
- Log.log.debug { "option #{path.join(DotContainer::SEPARATOR)}=#{tok.value}" }
408
+ declare_secrets(path.last, tok.value)
409
+ Log.log.debug { "option #{path.join(DotContainer::SEPARATOR)}=#{Secret::Hider.instance.hidden_copy(tok.value)}" }
407
410
  DotContainer.dotted_to_container(path, Parser.smart_convert(tok.value), result)
408
411
  end
409
412
  result
@@ -692,6 +695,7 @@ module Aspera
692
695
  # @param source [Symbol] `OptionSource`
693
696
  # @param replace [Boolean] replace a pending value from same source
694
697
  def add_pending_value(option_symbol, value, source, replace:)
698
+ declare_secrets(option_symbol, value)
695
699
  entries = (@pending_values[option_symbol] ||= [])
696
700
  index = entries.index { |e| e[:source].eql?(source) }
697
701
  if index.nil?
@@ -701,6 +705,14 @@ module Aspera
701
705
  end
702
706
  end
703
707
 
708
+ # Declare secret values of an option not declared yet, by option name (as `OptionValue#store` does for a declared option),
709
+ # so that they are hidden wherever they appear (logs, results), also in a structure (e.g. `{value:, source:}` of a pending value)
710
+ # @param name [Symbol, String] option name
711
+ # @param value [Object] value
712
+ def declare_secrets(name, value)
713
+ Secret::Hider.instance.add_named_secrets(name, value)
714
+ end
715
+
704
716
  # Apply pending values (presets, env) of declared options, lowest priority first
705
717
  def apply_pending_values
706
718
  ready = @pending_values.select { |k, _| @registry.declared?(k) }
@@ -746,7 +746,7 @@ module Aspera
746
746
  Result::ObjectList.new(events)
747
747
  end
748
748
  )
749
- command :transfers, description: 'List transfer events',
749
+ command :transfers, read_only: true, description: 'List transfer events',
750
750
  arguments: [
751
751
  EVENT_RESOURCE_TYPE_ARG,
752
752
  EVENT_RESOURCE_ID_ARG.merge(mandatory: false, default: nil)
@@ -1080,6 +1080,8 @@ module Aspera
1080
1080
 
1081
1081
  # packages > send
1082
1082
  def action_packages_send(package:, **)
1083
+ # The package is created before the transfer
1084
+ transfer.assert_no_dry_run
1083
1085
  package_data = package
1084
1086
  new_user_option = options.get_option(:new_user_option)
1085
1087
  option_validate = options.get_option(:validate_metadata)
@@ -1142,7 +1144,7 @@ module Aspera
1142
1144
  dest_folder = transfer.user_transfer_spec['destination_root'] || destination_folder
1143
1145
  formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{dest_folder}]})
1144
1146
  statuses = transfer.start(transfer_spec, oauth_api: package_node_api)
1145
- File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata
1147
+ File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata && !statuses.is_a?(Transfer::Result::DryRun)
1146
1148
  result_transfer.push({'package' => package_id, Runner::STATUS_FIELD => statuses})
1147
1149
  if skip_ids_persistency && statuses.is_a?(Transfer::Result::Success)
1148
1150
  skip_ids_persistency.data.push(package_id)
@@ -46,7 +46,7 @@ module Aspera
46
46
  command :aws_trust_policy, description: 'Show AWS trust policy', action: ->(**) { Result::SingleObject.new(ats_api.read('aws/trustpolicy', {region: options.get_option(:region, mandatory: true)})) }
47
47
 
48
48
  commands_under :cluster do
49
- command :clouds, description: 'List cloud providers', action: ->(**) { Result::ObjectList.new(@ats_api_open.cloud_names.map { |k, v| CLOUD_TABLE.zip([k, v]).to_h }) }
49
+ command :clouds, read_only: true, description: 'List cloud providers', action: ->(**) { Result::ObjectList.new(@ats_api_open.cloud_names.map { |k, v| CLOUD_TABLE.zip([k, v]).to_h }) }
50
50
  command :list, description: 'List ATS servers', action: ->(**) { Result::ObjectList.new(@ats_api_open.all_servers, fields: %w[id cloud region]) }
51
51
  command :show, description: 'Show a specific server (or use options cloud and region)',
52
52
  arguments: [{name: :server_id, mandatory: false, default: nil}]
@@ -7,6 +7,7 @@ require_relative '../extended_value'
7
7
  require_relative '../parser'
8
8
  require_relative '../../assert'
9
9
  require_relative '../result'
10
+ require_relative '../poll'
10
11
  require_relative '../command_registry'
11
12
  require_relative '../option_declarator'
12
13
  require_relative '../special_values'
@@ -289,6 +290,7 @@ module Aspera
289
290
  option :query, description: 'Additional filter for for some commands (list/delete)', allowed: [Hash, Array, NilClass]
290
291
  option :bulk, description: 'Bulk operation (only some)', allowed: Type::BOOLEAN, default: false
291
292
  option :bfail, description: 'Bulk operation error handling', allowed: Type::BOOLEAN, default: true
293
+ option :poll, description: 'Repeat a read-only command (dot-notation: interval, max, timeout, until, show, errors)', schema: Schema::Registry::POLL_OPTIONS
292
294
 
293
295
  def initialize(context:)
294
296
  Aspera.assert_type(context, Context) { 'context' }
@@ -354,6 +356,8 @@ module Aspera
354
356
  end
355
357
  else
356
358
  Security.instance.check_level(spec.security, "command #{current_path.join(' ')}") if spec
359
+ # Before anything is executed (setup, arguments, action)
360
+ poll = poll_result(current_path, spec) if is_leaf
357
361
  # Phase A - for intermediate nodes only: resolve all ArgumentSpec declared on this node
358
362
  # before dispatching to children (leaf nodes resolve their arguments inside execute_leaf).
359
363
  ctx = resolve_arguments(spec.arguments, ctx) if !is_leaf && spec&.arguments
@@ -362,7 +366,7 @@ module Aspera
362
366
 
363
367
  # Phase B - leaf fast-path or child dispatch
364
368
  if is_leaf
365
- dispatch_leaf(current_path, spec, ctx)
369
+ dispatch_leaf(current_path, spec, ctx, poll: poll)
366
370
  else
367
371
  dispatch_child(current_path, registry, ctx)
368
372
  end
@@ -373,13 +377,32 @@ module Aspera
373
377
  # @param current_path [Array<Symbol>]
374
378
  # @param spec [CommandSpec]
375
379
  # @param ctx [Hash]
380
+ # @param poll [Result::Poll, nil] With option `poll`: result that executes the action when displayed
376
381
  # @return [Object]
377
- def dispatch_leaf(current_path, spec, ctx)
382
+ def dispatch_leaf(current_path, spec, ctx, poll: nil)
378
383
  if @context.help_requested
379
384
  @help_path = current_path
380
385
  raise Cli::HelpRequest, self
381
386
  end
382
- execute_leaf(spec, ctx)
387
+ execute_leaf(spec, ctx, poll: poll)
388
+ end
389
+
390
+ # With option `poll`, check that the command is read-only, and the parameters of `poll`
391
+ # @param current_path [Array<Symbol>] path of the leaf command
392
+ # @param spec [CommandSpec] leaf command
393
+ # @return [Result::Poll, nil] `nil` if option `poll` is not set
394
+ # @raise [Cli::BadArgument] if the command is not read-only, or a parameter is invalid
395
+ def poll_result(current_path, spec)
396
+ parameters = options.get_option(:poll)
397
+ return if parameters.nil? || parameters.empty?
398
+ command = [self.class.name.split('::').last.downcase, *current_path].join(' ')
399
+ Aspera.assert(spec.read_only?, type: Cli::BadArgument) do
400
+ "Option poll: refused on `#{command}`: only a read-only command can be repeated (e.g. list, show, status)"
401
+ end
402
+ # Options that make a read-only command change state at each run
403
+ Aspera.assert(!options.get_option(:once_only), type: Cli::BadArgument) { 'Option poll: refused with option once_only: it saves state at each run' }
404
+ Aspera.assert(options.get_option(:notify_to).nil?, type: Cli::BadArgument) { 'Option poll: refused with option notify_to: it sends emails at each run' }
405
+ Result::Poll.new(parameters, format: formatter&.format_type)
383
406
  end
384
407
 
385
408
  # Phase B, child branch: consume the next command argument, then either continue
@@ -486,13 +509,17 @@ module Aspera
486
509
  # they are not read again from the command line.
487
510
  # @param spec [CommandSpec] a leaf node (no children)
488
511
  # @param ctx [Hash] accumulated context (pre-resolved keys are not re-consumed)
512
+ # @param poll [Result::Poll, nil] With option `poll`: the action is executed when this result is displayed
489
513
  # @return [Object]
490
- def execute_leaf(spec, ctx)
514
+ def execute_leaf(spec, ctx, poll: nil)
491
515
  a = action_for(spec)
492
516
  # Always resolve declared arguments (even when transfer_paths is set — those arguments
493
517
  # are consumed first; ts_source_paths then reads whatever remains in the queue).
494
518
  ctx = resolve_arguments(spec.arguments, ctx) if spec.arguments
495
- invoke_action(a, [], ctx)
519
+ return invoke_action(a, [], ctx) if poll.nil?
520
+ # Arguments are resolved once, the action is executed at each run
521
+ poll.action = -> { invoke_action(a, [], ctx) }
522
+ poll
496
523
  end
497
524
 
498
525
  # Resolve positional arguments from the CLI argument stream, in order.
@@ -555,7 +582,7 @@ module Aspera
555
582
  else
556
583
  case arg_spec.type
557
584
  when :identifier
558
- options.instance_identifier(description: arg_spec.name.to_s, &block)
585
+ options.instance_identifier(description: arg_spec.name.to_s, mandatory: arg_spec.mandatory, default: arg_spec.default, &block)
559
586
  else
560
587
  # Class or Array<Class> -> pass as validation type
561
588
  # When interactive: true, prompt for this argument only when no CLI argument is provided
@@ -158,6 +158,14 @@ module Aspera
158
158
  {name: :location, type: Symbol, mandatory: false, default: :github, allowed: %i[github local toc]},
159
159
  {name: :section, mandatory: false}
160
160
  ]
161
+ command(
162
+ :skill, description: 'Display the agent skill: how an AI drives IBM Aspera products with ascli (same as llms.txt)',
163
+ action: lambda do |**|
164
+ skill_file = File.join(self.class.gem_src_root, '..', 'skills', 'ascli', 'SKILL.md')
165
+ Aspera.assert(File.exist?(skill_file), type: Cli::Error) { "Agent skill not found: #{skill_file}" }
166
+ Result::Text.new(File.read(skill_file))
167
+ end
168
+ )
161
169
  command(
162
170
  :genkey, description: 'Generate a new RSA private key',
163
171
  arguments: [
@@ -173,7 +181,7 @@ module Aspera
173
181
  arguments: [{name: :private_key_pem}],
174
182
  action: ->(private_key_pem:, **) { Result::Text.new(OpenSSL::PKey::RSA.new(private_key_pem).public_key.to_s) }
175
183
  command :remote_certificate, description: 'Retrieve the certificate chain of a remote HTTPS server'
176
- command :echo, description: 'Show the value of a given argument',
184
+ command :echo, read_only: true, description: 'Show the value of a given argument',
177
185
  arguments: [{name: :value, type: nil}],
178
186
  action: ->(value:, **) { Result.auto(value) }
179
187
  command :download, description: 'Download a file from a URL',
@@ -375,6 +383,9 @@ module Aspera
375
383
  command :errors, description: 'Show FASP error codes: of the management port (default), or of sessions (errcode in logs)',
376
384
  arguments: [{name: :kind, allowed: %i[management session], mandatory: false, default: :management}]
377
385
  ascp_logs_commands :logs
386
+ commands_under :logs do
387
+ command :find, description: 'Find the ascp log files of this system: of installed products, and default locations', action: :action_ascp_logs_find
388
+ end
378
389
  command :products, description: 'Manage installed Aspera products'
379
390
  commands_under :products do
380
391
  command :list, description: 'List installed Aspera products',
@@ -299,6 +299,8 @@ module Aspera
299
299
  end
300
300
 
301
301
  def package_send(parameters)
302
+ # The package is created before the transfer
303
+ transfer.assert_no_dry_run
302
304
  # autofill recipient for public url
303
305
  if api_v5.pub_link_context&.key?('recipient_type') && !parameters.key?('recipients')
304
306
  parameters['recipients'] = [{
@@ -499,7 +501,7 @@ module Aspera
499
501
 
500
502
  # :health and :postprocessing work without authentication: they do not use api_v5.
501
503
  command :health, description: 'Check Faspex 5 health'
502
- command :version, description: 'Show Faspex 5 version', action: ->(**) { Result::SingleObject.new(api_v5.read('version')) }
504
+ command :version, read_only: true, description: 'Show Faspex 5 version', action: ->(**) { Result::SingleObject.new(api_v5.read('version')) }
503
505
  command :bearer_token, description: 'Show OAuth bearer token', action: ->(**) { Result::Text.new(api_v5.oauth.authorization) }
504
506
  # Package id argument; with a public link to a package, setup_package_id provides it instead
505
507
  PACKAGE_ID_ARG = [{name: :package_id, type: :identifier}].freeze
@@ -115,6 +115,20 @@ module Aspera
115
115
  ["orchestrator", "workflows", "development", "manual", "section", "<manual_anchor>"]
116
116
  Before importing a workflow file, check it (graph, templates, inputs of steps) and fix all errors:
117
117
  ["orchestrator", "workflows", "check_import", "<file>"]
118
+
119
+ AOC AUTOMATION WORKFLOW DEVELOPMENT
120
+ Before writing or modifying an Aspera on Cloud Automation workflow, read the development guide
121
+ (large: read sections, not the whole document). Start with the section of each trigger and action
122
+ used (for example "Send a package" is action type package_transfer, section "package-transfer"),
123
+ then "payload-rules-enforced-by-the-api" and "finding-the-identifiers":
124
+ ["aoc", "automation", "guide", "section", "package-transfer"]
125
+ Other sections: "triggers", "actions", "substitution-variables", "importing-a-workflow",
126
+ "design-recipes-and-patterns", "common-pitfalls-and-resolutions". List the anchors with:
127
+ ["aoc", "automation", "guide", "toc"]
128
+
129
+ GENERAL GUIDANCE
130
+ For the general rules of use of ascli by an AI (written for a shell: each command line maps to args):
131
+ ["config", "skill"]
118
132
  INST
119
133
 
120
134
  # Keys forwarded to MCP::Server constructor (symbolized)
@@ -129,7 +129,7 @@ module Aspera
129
129
  spec: {description: 'Show transfer spec base'},
130
130
  api_details: {description: 'Show API details'},
131
131
  health: {description: 'Check node health'},
132
- events: {description: 'List events'},
132
+ events: {description: 'List events', read_only: true},
133
133
  info: {description: 'Show node info'},
134
134
  slash: {description: 'Show root info'},
135
135
  license: {description: 'Show license'},
@@ -156,7 +156,7 @@ module Aspera
156
156
  modify: {description: 'Modify file', arguments: [{name: :path}, {name: :file, type: Hash, schema: 'node:components.schemas.files-id-put-request'}]},
157
157
  cat: {description: 'Show file contents', arguments: SINGLE_PATH_ARG},
158
158
  show: {description: 'Show file info', arguments: SINGLE_PATH_ARG},
159
- thumbnail: {description: 'Show file thumbnail', arguments: SINGLE_PATH_ARG},
159
+ thumbnail: {description: 'Show file thumbnail', arguments: SINGLE_PATH_ARG, read_only: true},
160
160
  bearer_token_node: {description: 'Show bearer token for file node', arguments: SINGLE_PATH_ARG},
161
161
  node_info: {description: 'Show node info for file', arguments: SINGLE_PATH_ARG},
162
162
  ls: {description: 'List files', arguments: SINGLE_PATH_ARG, aliases: [:browse]},
@@ -454,19 +454,19 @@ module Aspera
454
454
  Result::Status.new('Done')
455
455
  end
456
456
  )
457
- command :bandwidth, description: 'Show sync bandwidth',
457
+ command :bandwidth, read_only: true, description: 'Show sync bandwidth',
458
458
  arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
459
459
  action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/bandwidth", query_read_delete(default: {}))) }
460
- command :counters, description: 'Show sync counters',
460
+ command :counters, read_only: true, description: 'Show sync counters',
461
461
  arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
462
462
  action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/counters", query_read_delete(default: {}))) }
463
- command :files, description: 'List sync files',
463
+ command :files, read_only: true, description: 'List sync files',
464
464
  arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
465
465
  action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/files", query_read_delete(default: {}))) }
466
- command :state, description: 'Show sync state',
466
+ command :state, read_only: true, description: 'Show sync state',
467
467
  arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
468
468
  action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/state")) }
469
- command :summary, description: 'Show sync summary',
469
+ command :summary, read_only: true, description: 'Show sync summary',
470
470
  arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
471
471
  action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/summary")) }
472
472
  end
@@ -561,7 +561,7 @@ module Aspera
561
561
  Result::Status.new("#{watch_folder_id} deleted")
562
562
  end
563
563
  )
564
- command :state, description: 'Show watch folder state',
564
+ command :state, read_only: true, description: 'Show watch folder state',
565
565
  arguments: [{name: :watch_folder_id, type: :identifier}],
566
566
  action: ->(watch_folder_id:, **) { Result::SingleObject.new(api_node.read("v3/watchfolders/#{watch_folder_id}/state")) }
567
567
  end
@@ -9,6 +9,22 @@ require_relative '../error'
9
9
  module Aspera
10
10
  module Cli
11
11
  module Plugins
12
+ # Options of OAuth web authentication (authorization code): client and redirect URI.
13
+ # For a plugin that uses only this flow: `use_options OauthWebOptions` (without the options of `Oauth`)
14
+ module OauthWebOptions
15
+ extend OptionDeclarator
16
+ option :client_id, description: 'OAuth client identifier'
17
+ option :client_secret, description: 'OAuth client secret'
18
+ option :redirect_uri, description: 'OAuth (Web) redirect URI for web authentication'
19
+ end
20
+
21
+ # Options of OAuth JWT authentication: private key
22
+ module OauthJwtOptions
23
+ extend OptionDeclarator
24
+ option :private_key, description: 'OAuth (JWT) RSA private key PEM value (prefix file path with @file:)'
25
+ option :passphrase, description: 'OAuth (JWT) RSA private key passphrase'
26
+ end
27
+
12
28
  # base class for applications supporting OAuth 2.0 authentication
13
29
  class Oauth < BasicAuth
14
30
  class << self
@@ -33,11 +49,8 @@ module Aspera
33
49
  # Options used for authentication (url, auth, client_id, etc...)
34
50
  AUTH_OPTIONS = %i[url auth client_id client_secret redirect_uri private_key passphrase username password].freeze
35
51
  option :auth, description: 'OAuth type of authentication', allowed: AUTH_TYPES, default: :jwt
36
- option :client_id, description: 'OAuth client identifier'
37
- option :client_secret, description: 'OAuth client secret'
38
- option :redirect_uri, description: 'OAuth (Web) redirect URI for web authentication'
39
- option :private_key, description: 'OAuth (JWT) RSA private key PEM value (prefix file path with @file:)'
40
- option :passphrase, description: 'OAuth (JWT) RSA private key passphrase'
52
+ use_options OauthWebOptions
53
+ use_options OauthJwtOptions
41
54
  end
42
55
  end
43
56
  end