aspera-cli 4.27.5 → 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.
Files changed (249) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +301 -4
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +139 -58
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +10 -7
  13. data/docs/README.md +2551 -772
  14. data/docs/test-mcp-with-ai.md +13 -11
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +34 -22
  19. data/lib/aspera/agent/factory.rb +8 -4
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +8 -5
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +23 -19
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +84 -42
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +354 -0
  41. data/lib/aspera/ascp/management.rb +102 -48
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +16 -37
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -34
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +49 -4
  50. data/lib/aspera/cli/command_spec.rb +34 -4
  51. data/lib/aspera/cli/completion/ascli.bash +53 -5
  52. data/lib/aspera/cli/completion/ascli.fish +27 -8
  53. data/lib/aspera/cli/completion/ascli.ps1 +63 -0
  54. data/lib/aspera/cli/completion/ascli.zsh +36 -4
  55. data/lib/aspera/cli/completion_actions.rb +594 -0
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +45 -0
  59. data/lib/aspera/cli/extended_value.rb +83 -24
  60. data/lib/aspera/cli/formatter.rb +142 -73
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -11
  63. data/lib/aspera/cli/http.rb +17 -13
  64. data/lib/aspera/cli/info.rb +17 -6
  65. data/lib/aspera/cli/mailer.rb +7 -4
  66. data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
  67. data/lib/aspera/cli/mcp/secrets.rb +146 -0
  68. data/lib/aspera/cli/mcp/tool.rb +232 -0
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +72 -11
  73. data/lib/aspera/cli/options.schema.yaml +856 -81
  74. data/lib/aspera/cli/parser.rb +64 -31
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +250 -44
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +51 -25
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +207 -141
  81. data/lib/aspera/cli/plugins/console.rb +9 -4
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +22 -8
  84. data/lib/aspera/cli/plugins/faspex5.rb +37 -44
  85. data/lib/aspera/cli/plugins/faspio.rb +41 -8
  86. data/lib/aspera/cli/plugins/httpgw.rb +8 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +186 -121
  88. data/lib/aspera/cli/plugins/node.rb +41 -34
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +66 -12
  93. data/lib/aspera/cli/plugins/shares.rb +288 -48
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +155 -33
  96. data/lib/aspera/cli/preset_manager.rb +72 -16
  97. data/lib/aspera/cli/prompt.rb +7 -2
  98. data/lib/aspera/cli/result.rb +28 -11
  99. data/lib/aspera/cli/runner.rb +193 -80
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +204 -0
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +119 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +32 -40
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +31 -19
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +197 -50
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.html.erb +61 -0
  113. data/lib/aspera/cli/web_secret.rb +222 -0
  114. data/lib/aspera/cli/wizard.rb +58 -45
  115. data/lib/aspera/command_line_builder.rb +35 -5
  116. data/lib/aspera/command_line_converter.rb +4 -1
  117. data/lib/aspera/coverage.rb +103 -33
  118. data/lib/aspera/data_repository.rb +42 -25
  119. data/lib/aspera/dot_container.rb +4 -1
  120. data/lib/aspera/duration.rb +45 -0
  121. data/lib/aspera/environment.rb +106 -33
  122. data/lib/aspera/exec_spec.rb +9 -5
  123. data/lib/aspera/faspex_gw.rb +105 -35
  124. data/lib/aspera/faspex_postproc.rb +193 -47
  125. data/lib/aspera/formatter_interface.rb +4 -2
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +6 -3
  129. data/lib/aspera/json_rpc/client.rb +55 -35
  130. data/lib/aspera/json_rpc/version.rb +4 -0
  131. data/lib/aspera/line_logger.rb +4 -1
  132. data/lib/aspera/link_header.rb +4 -1
  133. data/lib/aspera/log.rb +20 -10
  134. data/lib/aspera/markdown.rb +155 -115
  135. data/lib/aspera/mime.rb +9 -0
  136. data/lib/aspera/nagios.rb +9 -5
  137. data/lib/aspera/node_emulator.rb +111 -112
  138. data/lib/aspera/oauth/client/base.rb +163 -0
  139. data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
  140. data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
  141. data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
  142. data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
  143. data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
  144. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  145. data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
  146. data/lib/aspera/oauth/client/web.rb +84 -0
  147. data/lib/aspera/oauth/server/authorize.html.erb +34 -0
  148. data/lib/aspera/oauth/server/pkce.rb +427 -0
  149. data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +11 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +4 -1
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +30 -1
  165. data/lib/aspera/rest/aspera_errors.rb +55 -60
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +42 -42
  168. data/lib/aspera/rest/error_analyzer.rb +14 -2
  169. data/lib/aspera/rest/list.rb +14 -10
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +13 -4
  172. data/lib/aspera/rest.rb +9 -7
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
  175. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
  176. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  177. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  178. data/lib/aspera/schema/IBM_Aspera_Shares.yaml +819 -7
  179. data/lib/aspera/schema/async_tables.yaml +11 -10
  180. data/lib/aspera/schema/documentation.rb +56 -78
  181. data/lib/aspera/schema/reader.rb +46 -11
  182. data/lib/aspera/schema/registry.rb +45 -24
  183. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  184. data/lib/aspera/schema/validator.rb +4 -1
  185. data/lib/aspera/sealed_hash.rb +166 -0
  186. data/lib/aspera/secret/hider.rb +201 -0
  187. data/lib/aspera/secret/reference.rb +150 -0
  188. data/lib/aspera/secret/resolver.rb +212 -0
  189. data/lib/aspera/secret/store/base.rb +153 -0
  190. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  191. data/lib/aspera/secret/store/factory.rb +103 -0
  192. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  193. data/lib/aspera/secret/store/keeper.rb +141 -0
  194. data/lib/aspera/secret/store/macos_security.rb +284 -0
  195. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  196. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  197. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  198. data/lib/aspera/secret/store/secret_service.rb +125 -0
  199. data/lib/aspera/secret/strength.rb +119 -0
  200. data/lib/aspera/servlet_helpers.rb +114 -0
  201. data/lib/aspera/ssh.rb +10 -7
  202. data/lib/aspera/ssl.rb +5 -2
  203. data/lib/aspera/string_ext.rb +3 -0
  204. data/lib/aspera/sync/args.schema.yaml +6 -1
  205. data/lib/aspera/sync/conf.schema.yaml +25 -10
  206. data/lib/aspera/sync/database.rb +3 -0
  207. data/lib/aspera/sync/operations.rb +34 -12
  208. data/lib/aspera/temp_file_manager.rb +85 -22
  209. data/lib/aspera/timer_limiter.rb +3 -0
  210. data/lib/aspera/transfer/error.rb +4 -1
  211. data/lib/aspera/transfer/faux_file.rb +4 -1
  212. data/lib/aspera/transfer/parameters.rb +22 -14
  213. data/lib/aspera/transfer/result.rb +3 -0
  214. data/lib/aspera/transfer/resumer.rb +6 -4
  215. data/lib/aspera/transfer/spec.rb +45 -18
  216. data/lib/aspera/transfer/spec.schema.yaml +8 -5
  217. data/lib/aspera/transfer/units.rb +75 -0
  218. data/lib/aspera/uri_reader.rb +57 -7
  219. data/lib/aspera/web_auth/index.html.erb +20 -0
  220. data/lib/aspera/web_auth/paste.rb +109 -0
  221. data/lib/aspera/web_auth/receiver.rb +50 -0
  222. data/lib/aspera/web_auth/relay.rb +76 -0
  223. data/lib/aspera/web_auth/reply.html.erb +150 -0
  224. data/lib/aspera/web_auth/server.rb +59 -14
  225. data/lib/aspera/web_page.html.erb +262 -0
  226. data/lib/aspera/web_page.rb +66 -0
  227. data/lib/aspera/web_server_simple.rb +82 -13
  228. data/lib/aspera/yaml.rb +5 -1
  229. data/llms.txt +81 -0
  230. data/skills/ascli/SKILL.md +88 -0
  231. data.tar.gz.sig +0 -0
  232. metadata +116 -48
  233. metadata.gz.sig +0 -0
  234. data/lib/aspera/cli/mcp_tool.rb +0 -189
  235. data/lib/aspera/keychain/base.rb +0 -25
  236. data/lib/aspera/keychain/encrypted_hash.rb +0 -188
  237. data/lib/aspera/keychain/factory.rb +0 -59
  238. data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
  239. data/lib/aspera/keychain/macos_security.rb +0 -171
  240. data/lib/aspera/keychain/one_password_api.rb +0 -86
  241. data/lib/aspera/keychain/one_password_base.rb +0 -34
  242. data/lib/aspera/keychain/one_password_cli.rb +0 -98
  243. data/lib/aspera/oauth/base.rb +0 -141
  244. data/lib/aspera/oauth/web.rb +0 -57
  245. data/lib/aspera/oauth.rb +0 -9
  246. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
  247. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
  248. data/lib/aspera/secret_hider.rb +0 -117
  249. data/lib/aspera/web_auth/index.html +0 -147
@@ -1,141 +1,181 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'assert'
7
+
3
8
  module Aspera
4
9
  # Formatting for Markdown
5
- class Markdown
10
+ module Markdown
11
+ extend self
12
+
6
13
  # Matches: **bold**, `code`, or an HTML entity (&, ©, 💩)
7
- FORMATS = /(?:\*\*(?<bold>[^*]+?)\*\*)|(?:`(?<code>[^`]+)`)|&(?<entity>(?:[A-Za-z][A-Za-z0-9]{1,31}|#\d{1,7}|#x[0-9A-Fa-f]{1,6}));/m
14
+ INLINE_MARKUP_RE = /(?:\*\*(?<bold>[^*]+?)\*\*)|(?:`(?<code>[^`]+)`)|&(?<entity>(?:[A-Za-z][A-Za-z0-9]{1,31}|#\d{1,7}|#x[0-9A-Fa-f]{1,6}));/m
15
+ # HTML line-break tag used in Markdown table cells to separate multi-line values.
8
16
  HTML_BREAK = '<br/>'
17
+ # Matches a Markdown heading line (e.g. `## Title`); group 1 = `#` chars, group 2 = text.
18
+ HEADING_RE = /^(\#{1,6})[ \t]+(\S.*)$/
19
+ # Matches the start or end of a fenced code block; group 1 = fence (``` or ~~~).
20
+ FENCE_RE = /^ {0,3}(`{3,}|~{3,})/
21
+ # Maximum column width (in characters) for generated Markdown tables.
22
+ COL_WIDTH = 80
23
+ # Accepted admonition types.
24
+ ADMONITION_TYPES = %w[NOTE CAUTION WARNING IMPORTANT TIP INFO].freeze
9
25
 
10
- class << self
11
- COL_WIDTH = 80
12
-
13
- # Convert a Markdown heading text to a GitHub-flavoured anchor.
14
- # Rules: downcase, keep letters/digits/spaces/hyphens, replace spaces with hyphens.
15
- # Duplicate anchors are disambiguated by appending -1, -2, … (pass a seen Hash to track).
16
- # @param text [String] raw heading text (without leading # and spaces)
17
- # @param seen [Hash{String=>Integer}, nil] mutable counter; pass the same Hash across a document
18
- # @return [String] anchor slug (without leading #)
19
- def heading_to_anchor(text, seen: nil)
20
- slug = text
21
- .downcase
22
- .gsub(/[`*_]/, '') # strip inline code/bold/italic markers
23
- .gsub(/&[a-z]+;/, '') # strip HTML entities
24
- .gsub(/[^\w\s-]/, '') # keep word chars, spaces, hyphens
25
- .gsub(/\s+/, '-') # spaces → hyphens
26
- .squeeze('-') # collapse consecutive hyphens
27
- .strip
28
- if seen
29
- count = seen[slug].to_i
30
- seen[slug] = count + 1
31
- slug = "#{slug}-#{count}" if count > 0
32
- end
33
- slug
34
- end
26
+ # --- Parsing ---
35
27
 
36
- # Extract the table of contents from a Markdown document.
37
- # @param content [String] full Markdown source
38
- # @return [Array<Hash>] array of { level, title, anchor }
39
- HEADING_RE = /^(\#{1,6})\s+(.+)$/
40
-
41
- def toc(content)
42
- seen = {}
43
- content.each_line.filter_map do |line|
44
- m = line.match(HEADING_RE)
45
- next unless m
46
- title = m[2].strip
47
- {level: m[1].length, title: title, anchor: heading_to_anchor(title, seen: seen)}
48
- end
28
+ # Convert a Markdown heading text to a GitHub-flavoured anchor.
29
+ # Rules: downcase, keep letters/digits/spaces/hyphens, replace spaces with hyphens.
30
+ # Duplicate anchors are disambiguated by appending -1, -2, … (pass a seen Hash to track).
31
+ # @param text [String] raw heading text (without leading # and spaces)
32
+ # @param seen [Hash{String=>Integer}, nil] mutable counter; pass the same Hash across a document
33
+ # @return [String] anchor slug (without leading #)
34
+ def heading_to_anchor(text, seen: nil)
35
+ slug = text
36
+ .downcase
37
+ .gsub(/[`*_]/, '') # strip inline code/bold/italic markers
38
+ .gsub(/&[a-z]+;/, '') # strip HTML entities
39
+ .gsub(/[^\w\s-]/, '') # keep word chars, spaces, hyphens
40
+ .gsub(/\s+/, '-') # spaces → hyphens
41
+ .squeeze('-') # collapse consecutive hyphens
42
+ .strip
43
+ if seen
44
+ count = seen[slug].to_i
45
+ seen[slug] = count + 1
46
+ slug = "#{slug}-#{count}" if count > 0
49
47
  end
48
+ slug
49
+ end
50
50
 
51
- # Extract the content of a single section (heading + body until next heading of same/higher level).
52
- # @param content [String] full Markdown source
53
- # @param anchor [String] GitHub anchor slug (without #)
54
- # @return [String, nil] the section content, or nil if not found
55
- def extract_section(content, anchor)
56
- seen = {}
57
- section_level = nil
58
- result = []
59
- content.each_line do |line|
60
- m = line.match(HEADING_RE)
61
- if m
62
- slug = heading_to_anchor(m[2].strip, seen: seen)
63
- if section_level.nil?
64
- # not yet found: check if this heading matches
65
- next unless slug == anchor
66
- section_level = m[1].length
67
- elsif m[1].length <= section_level
68
- # already in section: stop at same/higher level heading
69
- break
70
- end
51
+ # Iterate on the lines of a Markdown document, with the heading match of each line.
52
+ # A line in a fenced code block is not a heading (e.g. a shell comment `# ...`).
53
+ # @param content [String] full Markdown source
54
+ # @yieldparam line [String] the line
55
+ # @yieldparam heading [MatchData, nil] match of HEADING_RE, or nil if not a heading
56
+ def each_line_with_heading(content)
57
+ fence = nil
58
+ content.each_line do |line|
59
+ if (f = line.match(FENCE_RE))
60
+ # a code block ends with the same kind of fence, at least as long, without info string
61
+ if fence.nil?
62
+ fence = f[1]
63
+ elsif f[1].start_with?(fence) && line.strip.eql?(f[1])
64
+ fence = nil
71
65
  end
72
- result << line if section_level
66
+ yield(line, nil)
67
+ else
68
+ yield(line, fence.nil? ? line.match(HEADING_RE) : nil)
73
69
  end
74
- result.empty? ? nil : result.join
75
70
  end
71
+ end
76
72
 
77
- # Generate markdown from the provided 2D table
78
- # @param table [Array<Array<String>>] 2D array of strings
79
- # @return [String] markdown table
80
- def table(table)
81
- # get max width of each columns
82
- col_widths = table.transpose.map do |col|
83
- [col.flat_map { |c| c.to_s.delete('`').split(HTML_BREAK).map(&:size) }.max, COL_WIDTH].min
84
- end
85
- # do not modify caller's table
86
- table = table.dup
87
- headings = table.shift
88
- table.unshift(col_widths.map { |col_width| '-' * col_width })
89
- table.unshift(headings)
90
- lines = table.map { |line| "| #{line.map { |i| i.to_s.gsub('\\', '\\\\').gsub('|', '\|') }.join(' | ')} |\n" }
91
- lines[1] = lines[1].tr(' ', '-')
92
- return lines.join.chomp
73
+ # Extract the table of contents from a Markdown document.
74
+ # @param content [String] full Markdown source
75
+ # @param max_level [Integer, nil] maximum level of headings, or nil for all
76
+ # @return [Array<Hash>] array of { level, title, anchor } (String keys, as other results: `--select` applies)
77
+ def toc(content, max_level: nil)
78
+ seen = {}
79
+ result = []
80
+ each_line_with_heading(content) do |_line, m|
81
+ next unless m
82
+ title = m[2].strip
83
+ # anchor of every heading, so that duplicate anchors are numbered as in the whole document
84
+ anchor = heading_to_anchor(title, seen: seen)
85
+ result.push({'level' => m[1].length, 'title' => title, 'anchor' => anchor}) if max_level.nil? || m[1].length <= max_level
93
86
  end
87
+ result
88
+ end
94
89
 
95
- # Generate markdown list from the provided list
96
- # @param items [Array<String>] list of items
97
- # @return [String] markdown unordered list
98
- def list(items)
99
- items.map { |i| "- #{i}" }.join("\n")
90
+ # Extract the content of a single section (heading + body until next heading of same/higher level).
91
+ # @param content [String] full Markdown source
92
+ # @param anchor [String] GitHub anchor slug (without #)
93
+ # @return [String, nil] the section content, or nil if not found
94
+ def extract_section(content, anchor)
95
+ seen = {}
96
+ section_level = nil
97
+ result = []
98
+ each_line_with_heading(content) do |line, m|
99
+ if m
100
+ slug = heading_to_anchor(m[2].strip, seen: seen)
101
+ if section_level.nil?
102
+ # not yet found: check if this heading matches
103
+ next unless slug == anchor
104
+ section_level = m[1].length
105
+ elsif m[1].length <= section_level
106
+ # already in section: stop at same/higher level heading
107
+ break
108
+ end
109
+ end
110
+ result << line if section_level
100
111
  end
112
+ result.empty? ? nil : result.join
113
+ end
101
114
 
102
- # Generate a markdown heading
103
- # @param title [String] heading text
104
- # @param level [Integer] heading level (1–6)
105
- # @return [String] markdown heading
106
- def heading(title, level: 1)
107
- "#{'#' * level} #{title}\n\n"
108
- end
115
+ # --- Generation ---
109
116
 
110
- # Generate a GitHub-flavoured admonition block
111
- # @param lines [Array<String>] lines of the admonition body
112
- # @param type [String] admonition type: NOTE, CAUTION, WARNING, IMPORTANT, TIP, INFO
113
- # @return [String] markdown admonition block
114
- def admonition(lines, type: 'INFO')
115
- "> [!#{type}]\n#{lines.map { |l| "> #{l}" }.join("\n")}\n\n"
116
- end
117
+ # Wrap text in inline code backticks
118
+ # @param text [String] text to wrap
119
+ # @return [String] inline code span
120
+ def icode(text)
121
+ "`#{text}`"
122
+ end
117
123
 
118
- # Generate a fenced code block
119
- # @param lines [Array<String>] lines of code
120
- # @param type [String] language identifier for syntax highlighting
121
- # @return [String] markdown fenced code block
122
- def code(lines, type: 'shell')
123
- "```#{type}\n#{lines.join("\n")}\n```\n\n"
124
- end
124
+ # Wrap text in a markdown paragraph (trailing blank line)
125
+ # @param text [String] paragraph content
126
+ # @return [String] paragraph with trailing newlines
127
+ def paragraph(text)
128
+ "#{text}\n\n"
129
+ end
125
130
 
126
- # Wrap text in inline code backticks
127
- # @param text [String] text to wrap
128
- # @return [String] inline code span
129
- def icode(text)
130
- "`#{text}`"
131
- end
131
+ # Generate a markdown heading
132
+ # @param title [String] heading text
133
+ # @param level [Integer] heading level (1–6)
134
+ # @return [String] markdown heading
135
+ def heading(title, level: 1)
136
+ paragraph("#{'#' * level} #{title}")
137
+ end
138
+
139
+ # Generate a fenced code block
140
+ # @param lines [Array<String>] lines of code
141
+ # @param type [String] language identifier for syntax highlighting
142
+ # @return [String] markdown fenced code block
143
+ def code(lines, type: 'shell')
144
+ paragraph("```#{type}\n#{lines.join("\n")}\n```")
145
+ end
146
+
147
+ # Generate a GitHub-flavoured admonition block
148
+ # @param lines [Array<String>] lines of the admonition body
149
+ # @param type [String] admonition type, one of {ADMONITION_TYPES}
150
+ # @return [String] markdown admonition block
151
+ def admonition(lines, type: 'INFO')
152
+ Aspera.assert_values(type, ADMONITION_TYPES) { 'admonition type' }
153
+ paragraph((["[!#{type}]"] + lines).map { |l| "> #{l}" }.join("\n"))
154
+ end
155
+
156
+ # Generate markdown list from the provided list
157
+ # @param items [Array<String>] list of items
158
+ # @return [String] markdown unordered list
159
+ def list(items)
160
+ items.map { |i| "- #{i}" }.join("\n")
161
+ end
132
162
 
133
- # Wrap text in a markdown paragraph (trailing blank line)
134
- # @param text [String] paragraph content
135
- # @return [String] paragraph with trailing newlines
136
- def paragraph(text)
137
- "#{text}\n\n"
163
+ # Generate markdown from the provided 2D table
164
+ # @param table [Array<Array<String>>] 2D array of strings
165
+ # @return [String] markdown table
166
+ def table(table)
167
+ # get max width of each columns
168
+ col_widths = table.transpose.map do |col|
169
+ [col.flat_map { |c| c.to_s.delete('`').split(HTML_BREAK).map(&:size) }.max, COL_WIDTH].min
138
170
  end
171
+ # do not modify caller's table
172
+ table = table.dup
173
+ headings = table.shift
174
+ table.unshift(col_widths.map { |col_width| '-' * col_width })
175
+ table.unshift(headings)
176
+ # Separator row with spaces around pipes, as other rows (markdownlint MD060, style `compact`)
177
+ lines = table.map { |line| "| #{line.map { |i| i.to_s.gsub('\\', '\\\\').gsub('|', '\|') }.join(' | ')} |\n" }
178
+ return lines.join.chomp
139
179
  end
140
180
  end
141
181
  end
data/lib/aspera/mime.rb CHANGED
@@ -1,5 +1,8 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
3
6
  module Aspera
4
7
  # MIME types used in `Content-Type` and `Accept`
5
8
  module Mime
@@ -9,8 +12,14 @@ module Aspera
9
12
  WWW = 'application/x-www-form-urlencoded'
10
13
  # Plain text body
11
14
  TEXT = 'text/plain'
15
+ # XML body
16
+ XML = 'application/xml'
17
+ # Multipart form body (file upload)
18
+ MULTIPART = 'multipart/form-data'
12
19
  # JSON:API body (https://jsonapi.org)
13
20
  JSON_API = 'application/vnd.api+json'
21
+ # Server-Sent Events stream
22
+ EVENT_STREAM = 'text/event-stream'
14
23
  # Check if a media type is JSON: `application/json` or structured syntax suffix `+json` (RFC 6839)
15
24
  # @param mime [String] Media type, without parameters (see `Rest.parse_header`)
16
25
  # @return [Boolean] `true` if JSON
data/lib/aspera/nagios.rb CHANGED
@@ -1,8 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/log'
4
- require 'aspera/assert'
5
- require 'date'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'log'
7
+ require_relative 'assert'
6
8
 
7
9
  module Aspera
8
10
  class Nagios
@@ -13,6 +15,8 @@ module Aspera
13
15
  DATE_WARN_OFFSET = 2
14
16
  DATE_CRIT_OFFSET = 5
15
17
  private_constant :LEVELS, :ADD_PREFIX, :DATE_WARN_OFFSET, :DATE_CRIT_OFFSET
18
+ # Exit code when the check itself fails
19
+ UNKNOWN = LEVELS.index(:unknown)
16
20
 
17
21
  # add methods to add nagios error levels, each take component name and message
18
22
  LEVELS.each_index do |code|
@@ -32,7 +36,7 @@ module Aspera
32
36
  # keep only errors in case of problem, other ok are assumed so
33
37
  data = res_errors unless res_errors.empty?
34
38
  # first is most critical
35
- data.sort! { |a, b| LEVELS.index(a['status'].to_sym) <=> LEVELS.index(b['status'].to_sym) }
39
+ data = data.sort { |a, b| LEVELS.index(a['status'].to_sym) <=> LEVELS.index(b['status'].to_sym) }
36
40
  # build message: if multiple components: concatenate
37
41
  # message = data.map{|i|"#{i['component']}:#{i['message']}"}.join(', ').gsub("\n",' ')
38
42
  message = data
@@ -44,7 +48,7 @@ module Aspera
44
48
  # display status for nagios
45
49
  puts("#{status} - [#{message}]\n")
46
50
  # provide exit code to nagios
47
- Process.exit(LEVELS.index(data.first['status'].to_sym))
51
+ ::Process.exit(LEVELS.index(data.first['status'].to_sym))
48
52
  end
49
53
  end
50
54