asterism 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee81a1950e5fffa0f5d299999d7878834a79d897e3b4cbf879e293fc6b00531
-  data.tar.gz: 05a88c6ad24fafe262668cb11f4a48e7e5357678c1903207aae004ac0e518311
+  metadata.gz: 8c3c929e3018c538fab3983c9fffce4fd997bfa8b37cad43fbaa6c0eb5890d65
+  data.tar.gz: b4fc43d2d5d286139eb700c5711786827aab41aa8a7628686b45270a321f1807
 SHA512:
-  metadata.gz: 4c6e015f5bd202a1cf44dc3d6ee59fe8af406cb899735df5ee828610cb82de5aa67035be2b5c9cbf1b4c603e0477eaba1e9e503f3ed901e81308ea1b98c91fbc
-  data.tar.gz: 717902fdcce318aad8a78776f0f72b4063241868dbc8b50def6a0386f2868f764dbf356403b0ef1cbd727c5dc8df6818ced7d465cfb23338452e892d3e0c6dc1
+  metadata.gz: f971a84780f4a1ce1e24554530201f6bccaba7f8de6ec03c5b2dc6742c6c370e2567af5c82e4609fd82f582d32cbe314f82bc5c60d5815b5c33e805980b14a58
+  data.tar.gz: c355695ad9b52f7513f791191eeae8ded62011cdc011c50d1e921f6fa1e58190f491cc3adc0b367fa0087def3cfd6cd03729a43143b19f608b3f3a5603879f3c

data/CHANGELOG.md

@@ -6,6 +6,50 @@ the earlier ones are only in this repository. From 0.4.0 the two Zenoh
 bindings (asterism-zenoh, picoruby-asterism-zenoh) carry the same minor
 version (a patch release of one may come without the other).
 
+## 0.9.0
+
+The command line only; the library and the wire are as in 0.8.0 (0.8.1
+was not published: its changes are here).
+
+- The command line's commands are a noun and a verb, as ros2's are:
+  `node list` / `node info NODE`, `app list` / `app info NODE/APP`,
+  `object list [PATTERN]` / `object info PATH` / `object find METHOD`
+  (the objects that have a method, `*` as a wildcard), `status get` /
+  `status echo` / `status hz NODE/APP`. The lists print the names only, a
+  name a line, sorted (for grep and xargs). `asterism NOUN` lists its
+  verbs; `asterism --help` is grouped by noun. `call`, `ping`, `watch`,
+  `tree` and `mcp` are as they were, and the older `nodes`, `objects` and
+  `echo` stay with the same output. README "The command line".
+- `status echo NODE/APP`: the status, then each change as it comes (the
+  text tells what changed, as `watch` does; `--once`: the status now,
+  once). `status hz NODE/APP`: how often the status changes, as
+  `ros2 topic hz` (the average rate and the intervals' min, max and
+  standard deviation, every `--period`; `--window`).
+- `-o json` / `-o yaml` on every command that reads (YAML with the
+  standard library, the same content as the JSON). `--json` is `-o json`;
+  its output is as it was, byte for byte.
+- Tab completion: `asterism completion bash` / `zsh` prints a script
+  (`source <(asterism completion bash)`). The commands, verbs and options
+  complete without the network; the nodes, `node/app`, `node/app/object`
+  (a part at a time) and an object's methods come from the network named
+  on the line or in the environment, asked for 1.5 s at most and
+  remembered for 20 s in `$XDG_CACHE_HOME/asterism/` (names only; never a
+  key or a certificate). README "Tab completion".
+- The command line's text is easier to read (`--json` is unchanged): a
+  status is shown as indented `key=value` lines instead of one line of
+  JSON (`tree`, `nodes`, the first status of `watch`); `tree` shows how
+  many methods each object has and `tree --methods` lists them, wrapped to
+  the width; `objects` wraps the objects' and methods' descriptions to the
+  width in one column, the signatures in bold; `watch` shows only what
+  changed in a status (`~ status games/games mahjong1.members 0→1`, keys
+  that came with `+`, keys that went with `-`). On a terminal the text has
+  colours and the terminal's width; to a pipe or a file it is plain and 80
+  columns wide (or `COLUMNS`); `NO_COLOR` turns the colours off. Standard
+  library only. README "The command line".
+- The command line takes `ASTERISM_CREDENTIALS` and `ASTERISM_ROUTER`
+  from the environment when none of `--router`, `--credentials`, `--peer`
+  is given (all or nothing). README "The command line".
+
 ## 0.8.0
 
 Needs asterism-zenoh 0.4.1 or later, as 0.7.1. Wire protocol 1 as before:

data/README.md

@@ -101,7 +101,7 @@ build but not yet tested. To install from the repositories instead:
 
 ```
 (cd ../asterism-zenoh && rake gem) && rake gem
-gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.1.gem pkg/asterism-0.8.0.gem
+gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.1.gem pkg/asterism-0.9.0.gem
 ```
 
 From the working trees, without installing:
@@ -130,7 +130,7 @@ rake                  # every suite
 rake test:msgs        # generator, type hashes, CDR, bundled types (CRuby only; no Zenoh, no docker)
 rake test:objects     # objects and Asterism::ROS between CRuby sessions over a local peer link
 rake test:api         # the CRuby API (blocks, receiving threads, Enumerators)
-rake test:cli         # the command line (exe/asterism) and its MCP bridge (the mcp gem's client; skipped without it)
+rake test:cli         # the command line (exe/asterism), its Tab completion and its MCP bridge (the mcp gem's client; skipped without it)
 ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test:objects test:api   # the same through a zenohd router
 rake test:mruby       # the shared layer on mruby (builds mruby; not part of `rake`)
 rake test:protocol    # the wire protocol's conformance samples and driver against CRuby (docs/protocol.md)
@@ -415,31 +415,101 @@ What may be shared between threads:
 The gem has a command, `asterism`, that looks at a network from a terminal
 (CRuby). It is one more node: it connects, reads the liveliness tokens,
 the meta, the profiles and the statuses, and calls a method only when told
-to with `call`.
+to with `call`. Its commands are a noun and a verb, as ros2's are
+(`asterism node` alone lists the node's verbs, `asterism --help` all of
+them):
 
 ```
-asterism nodes   --router tcp/192.0.2.2:7447        # nodes, their apps (with their status), profiles
-asterism objects --router tcp/192.0.2.2:7447 'games/games/*'   # objects and their methods
-asterism tree    --credentials admin.tar             # nodes > apps > objects, with methods and statuses
-asterism watch   --router tcp/192.0.2.2:7447        # nodes, apps and objects coming and going, statuses
-asterism ping    --router tcp/192.0.2.2:7447 games/games/othello1   # round trips (its meta; no method runs)
-asterism ping    ... games/games/othello1 --call view '"<token>"'   # round trips of a call
-asterism call    --router tcp/192.0.2.2:7447 games/games/othello1 join '"Alice"'
-asterism call    ... linux/demo/screen say hello --kwargs '{color: 3}'
+asterism node list   --router tcp/192.0.2.2:7447    # the nodes, a name a line
+asterism node info   games                          # one node: profile, apps, statuses, objects
+asterism app list                                   # node/app, a line each
+asterism app info    games/games                    # its status and its objects
+asterism object list 'games/games/*'                # node/app/object, a line each
+asterism object info games/games/othello1           # its description and its methods
+asterism object find join                           # the objects that have join (* as a wildcard)
+asterism status get  games/games                    # the status now
+asterism status echo games/games                    # the status, then each change (--once: now, once)
+asterism status hz   games/games                    # how often it changes
+asterism call        games/games/othello1 join '"Alice"'
+asterism call        linux/demo/screen say hello --kwargs '{color: 3}'
+asterism ping        games/games/othello1           # round trips (its meta; no method runs)
+asterism ping        games/games/othello1 --call view '"<token>"'   # round trips of a call
+asterism watch                                      # nodes, apps and objects coming and going, statuses
+asterism tree        --credentials admin.tar        # nodes > apps > objects (--methods: the methods)
+asterism completion  bash                           # Tab completion (below)
 ```
 
+The older commands stay, with the same output: `nodes` (every node with
+its applications and statuses, in one listing), `objects [PATTERN]` (each
+object with its description and methods) and `echo` (`ping`).
+
 ```
-$ asterism tree --router tcp/192.0.2.2:7447
+$ export ASTERISM_ROUTER=tcp/192.0.2.2:7447
+$ asterism node list
+games
+linux
+$ asterism object list
+games/games/mahjong1
+games/games/othello1
+linux/demo/screen
+$ asterism app info games/games
+games/games
+  status:
+    mahjong1: st=wait members=0 humans=0 cpus=0 ais=0 away=0
+    othello1: st=wait members=0 humans=0 cpus=0 away=0
+  objects:
+    mahjong1  18 methods
+      A riichi mahjong table (four seats). From a program: call describe first,
+      then join, sit, and look / choose in a loop.
+    othello1  11 methods
+      An othello table (two seats). join, sit, then view / move in a loop.
+$ asterism object info games/games/othello1
+games/games/othello1
+  An othello table (two seats). join, sit, then view / move in a loop.
+  join(name)              Joins the table as name (or gets this node's
+                          membership back). Returns {"token", ...}: every later
+                          call brings the token. {"error" => why} when the table
+                          is full.
+  mine()                  This node's membership ({"token", ...}), or nil when
+                          it has not joined.
+  ...
+$ asterism object find join
+games/games/mahjong1
+games/games/othello1
+$ asterism status get games/games -o yaml
+---
+mahjong1:
+  st: wait
+  members: 0
+  ...
+$ asterism status echo games/games
+12:00:01.204 games/games (now)
+             mahjong1: st=wait members=0 humans=0 cpus=0 ais=0 away=0
+             othello1: st=wait members=0 humans=0 cpus=0 away=0
+12:00:05.120 mahjong1.members 0→1
+12:00:05.133 mahjong1.humans 0→1
+$ asterism status hz games/games
+average rate: 0.409 Hz
+  min: 0.013 s  max: 4.876 s  std dev: 2.432 s  window: 2
+$ asterism tree
 games  (cruby) "asterism-games"
-  games  status {"mahjong1":{"st":"wait","members":0,"humans":0,"cpus":0,"away":0}, ...}
-    mahjong1  join(1) mine(0) leave(1) sit(2) stand(1) ...
+  games
+    status:
+      mahjong1: st=wait members=0 humans=0 cpus=0 ais=0 away=0
+      othello1: st=wait members=0 humans=0 cpus=0 away=0
+    mahjong1  18 methods
+    othello1  11 methods
 linux  (family_mruby/sim)
-  game
-$ asterism watch --router tcp/192.0.2.2:7447
-12:00:01.204 ~ status games/games {"othello1":{"st":"wait","members":0,...}} (now)
+  demo
+    screen  3 methods
+$ asterism watch
+12:00:01.204 ~ status games/games (now)
+               mahjong1: st=wait members=0 humans=0 cpus=0 ais=0 away=0
+               othello1: st=wait members=0 humans=0 cpus=0 away=0
 12:00:04.881 + node wasm-1a2b3c
 12:00:04.881 + app wasm-1a2b3c/game
-12:00:05.120 ~ status games/games {"othello1":{"st":"wait","members":1,...}}
+12:00:05.120 ~ status games/games mahjong1.members 0→1
+12:00:05.133 ~ status games/games mahjong1.humans 0→1
 ```
 
 - **Where the network is.** `--router tcp/HOST:7447` (a router without TLS),
@@ -447,7 +517,12 @@ $ asterism watch --router tcp/192.0.2.2:7447
   and its name; `--router` overrides the router). `--peer LOCATOR` links
   straight to a node listening there (no router). The node ID is the
   certificate's name, otherwise `cli-` and 6 hex digits (`--node`); the
-  application `cli-` and 4 (`--app`).
+  application `cli-` and 4 (`--app`). With none of `--router`,
+  `--credentials`, `--peer` on the line, `ASTERISM_CREDENTIALS` and
+  `ASTERISM_ROUTER` from the environment are used instead (all or nothing:
+  a router on the line never meets a `.tar` from the environment), so
+  `export ASTERISM_CREDENTIALS=~/me.tar` makes `asterism tree` enough, and
+  an MCP client can pass it in the server's environment.
 - **What it sees** is what the router lets it see. With a console's `.tar`
   that is the row's roles: a role for looking only is in the console's
   docs/g1_5.md ("Looking only: a viewer role"): it reads every node, object,
@@ -458,13 +533,60 @@ $ asterism watch --router tcp/192.0.2.2:7447
   literal (nil, true, false, numbers, strings, symbols, arrays, hashes; read
   with Ripper, nothing is evaluated), else the text as written. `--kwargs`
   is a JSON object or a Ruby Hash.
-- **Output**: text, or `--json` (`watch --json`: one object a line, with
-  the time). `--timeout` (2.0 s) is each get's and call's limit, `--settle`
+- **Lists** (`node list`, `app list`, `object list`, `object find`) print
+  the names only, a name a line, sorted, so they go to `grep` and `xargs`
+  as they are (on a terminal the parts are coloured; to a pipe they are
+  plain).
+- **Output**: text, or `-o json` / `-o yaml` on every command that reads
+  (the YAML holds what the JSON does; `--json` is `-o json`, its output as
+  it always was). The streams (`watch`, `status echo`, `status hz`) give a
+  JSON object a line, or a YAML document each (`---`), with the time. The
+  text is for people: on a terminal it has colours (nodes, applications,
+  objects, the `+` `-` `~` of watch; `NO_COLOR=1` turns them off) and is
+  wrapped to the terminal's width; written to a pipe or a file it is plain
+  and 80 columns wide (or `COLUMNS`). A status is shown as `key=value`, a
+  line for each level that holds Hashes (a long text or array is cut with
+  `…`; `-o json` has it whole). `tree` tells how many methods an object
+  has, `tree --methods` lists them; `object info` (and `objects`) lists
+  each method with its description. `watch` and `status echo` show a
+  status whole the first time (and when its application comes back), then
+  only what changed: `a.b 0→1`, `+a.c=…` (a key came), `-a.d` (a key
+  went). `--timeout` (2.0 s) is each get's and call's limit, `--settle`
   (1.5 s) how long it waits for the tokens after connecting.
+- **status hz** counts the changes of the status (a put of the same status
+  again is not one) and prints, every `--period` (1 s) in which a change
+  came, the average rate and the intervals' min, max and standard
+  deviation over the last `--window` (1000) intervals, as `ros2 topic hz`
+  does. An application puts its status when it changes, so this is how
+  often the application has something new to tell.
 - **watch** shows the applications and objects themselves (their tokens),
   not only the nodes: a node with two applications stays while one closes,
   and `watch` shows that one leave.
 
+### Tab completion
+
+```
+source <(asterism completion bash)     # or put this line in ~/.bashrc
+source <(asterism completion zsh)      # zsh, after compinit (~/.zshrc)
+```
+
+The commands, the verbs and the options complete without the network. The
+names on the network complete too: the nodes, `node/app`, `node/app/object`
+a part at a time (`ga<Tab>` gives `games/`, `games/games/<Tab>` the
+objects), and after `call PATH` (or `ping PATH --call`) the object's
+methods. On each Tab the script runs `asterism __complete`, which asks the
+network named on the line (`--router`, `--credentials`, `--peer`) or in
+`ASTERISM_CREDENTIALS` / `ASTERISM_ROUTER`:
+
+- briefly: what does not answer within 1.5 s gives no candidates, and the
+  shell is not kept waiting;
+- remembered for 20 s, a file per network in `$XDG_CACHE_HOME/asterism/`
+  (`~/.cache/asterism/`; the directory 0700, the files 0600), named by a
+  digest of where the network is. It holds the names only, never a key or
+  a certificate. What did not answer is not remembered;
+- as one more node for a moment (a `cli-` node, or the certificate's name),
+  so `asterism watch` shows it come and go.
+
 ### MCP: Asterism as tools of an AI assistant
 
 `asterism mcp` is an MCP server on stdio (it needs the `mcp` gem, which

data/lib/asterism/cli/complete.rb

@@ -0,0 +1,282 @@
+# The shell's Tab completion: `asterism completion bash|zsh` prints a
+# script, and the script calls the hidden `asterism __complete` on each
+# Tab, which prints the candidates, one a line.
+#
+# The commands, the verbs and the options come from the command line's own
+# tables (no network). The names on the network (nodes, node/app,
+# node/app/object, an object's methods) come from the network named on the
+# line (--router, --credentials, --peer) or in the environment, asked
+# briefly (Complete::BUDGET: nothing comes back when it does not answer in
+# time, the shell is not kept waiting) and remembered for a few seconds
+# (Cache: a file per network under $XDG_CACHE_HOME/asterism, named by a
+# digest of where the network is; it holds names only, never a key or a
+# certificate). A name with "/" is completed a part at a time:
+# `ga<Tab>` gives `games/`, `games/games/<Tab>` the objects.
+require "json"
+require "digest"
+require "fileutils"
+require "shellwords"
+
+module Asterism
+  class CLI
+    class Complete
+      # Seconds the network may take to answer one Tab (connecting, the
+      # tokens, a meta get).
+      BUDGET = 1.5
+      # What a line of the output means "complete a file name here".
+      FILES = ":files"
+
+      # spec: the CLI (its command tables and option lists); source: what
+      # the network names (#names, #methods(path), #all_methods), each
+      # nil when it did not answer.
+      def initialize(spec, source)
+        @spec = spec
+        @source = source
+      end
+
+      # The candidates for the last word of words (the words after
+      # `asterism`, the last one the word being completed, "" for a new
+      # one), those that start with it, sorted.
+      def candidates(words)
+        words = words.dup
+        cur = words.pop || ""
+        pos = []
+        prev = nil
+        words.each do |w|
+          if prev
+            prev = nil
+            next
+          end
+          if w.start_with?("-") && w.size > 1
+            prev = w if @spec.option_takes_value?(w)
+            next
+          end
+          pos << w
+        end
+        key, args = @spec.command_key(pos)
+        list =
+          if prev then values(prev, key, args)
+          elsif cur.start_with?("-") then key ? @spec.options_for(key) : []
+          else positional(pos, key, args, cur)
+          end
+        return list if list == [FILES]
+        list.select { _1.start_with?(cur) }.uniq.sort
+      end
+
+      private
+
+      def values(opt, key, args)
+        case opt
+        when "-o", "--output" then %w[json yaml]
+        when "--credentials" then [FILES]
+        when "--call" then key == "ping" && args[0] ? methods_of(args[0]) : []
+        else []
+        end
+      end
+
+      def positional(pos, key, args, cur)
+        return @spec.command_words if pos.empty?
+        return @spec.verbs(pos[0]) if pos.size == 1 && @spec.noun?(pos[0])
+        return [] unless key
+        i = args.size
+        case [key, i]
+        when ["node info", 0] then nodes
+        when ["app info", 0], ["status get", 0], ["status echo", 0], ["status hz", 0] then staged(cur, apps, 2)
+        when ["object list", 0], ["object info", 0], ["objects", 0], ["call", 0] then staged(cur, objects, 3)
+        when ["ping", 0], ["echo", 0] then (cur.include?("/") ? [] : nodes) + staged(cur, objects, 3)
+        when ["object find", 0] then @source.all_methods || []
+        when ["call", 1] then methods_of(args[0])
+        when ["completion", 0] then %w[bash zsh]
+        when ["help", 0] then @spec.nouns
+        else []
+        end
+      end
+
+      def methods_of(path)
+        path.count("/") == 2 ? (@source.methods(path) || []) : []
+      end
+
+      def names
+        @names ||= @source.names || { "apps" => [], "objects" => [] }
+      end
+
+      def objects
+        names["objects"]
+      end
+
+      # The applications, with those that only objects tell of.
+      def apps
+        (names["apps"] + objects.map { _1.split("/")[0, 2].join("/") }).uniq
+      end
+
+      def nodes
+        (apps + objects).map { _1.split("/")[0] }.uniq
+      end
+
+      # The next part of the paths (depth parts each) that start with cur:
+      # the parts up to the one cur is in, with "/" after it when more come.
+      def staged(cur, paths, depth)
+        k = cur.count("/")
+        return [] if k >= depth
+        paths.filter_map do |p|
+          s = p.split("/")
+          next if s.size < depth
+          c = s[0..k].join("/")
+          c += "/" if k + 1 < depth
+          c if c.start_with?(cur)
+        end
+      end
+
+      public
+
+      # The words of a command line up to the cursor (bash's COMP_LINE cut
+      # at COMP_POINT): the words after the command, the last one the word
+      # being completed ("" after a space). An open quote is closed.
+      def self.split_line(line)
+        words = begin
+          Shellwords.split(line)
+        rescue ArgumentError
+          begin
+            Shellwords.split("#{line}\"")
+          rescue ArgumentError
+            Shellwords.split("#{line}'")
+          end
+        end
+        words << "" if line.match?(/\s\z/) || words.empty?
+        words.drop(1)
+      end
+
+      # Bash splits the word being completed at ":" and "=" (COMP_WORDBREAKS):
+      # the candidates without what comes before the last of them in cur.
+      def self.bash_trim(cands, cur)
+        cut = cur.rindex(/[:=]/)
+        return cands unless cut
+        cands.map { _1.start_with?(cur[0..cut]) ? _1[(cut + 1)..] : _1 }
+      end
+
+      # ------------------------------------------------------------ the cache
+
+      # What __complete remembers of a network for a few seconds: a JSON
+      # file per network ({entry => {"t" => seconds, "v" => value}}), the
+      # directory 0700 and the files 0600. The network's identity is a
+      # digest of where it is (router, the credentials file's path, peer);
+      # nothing else about it is written.
+      class Cache
+        TTL = 20
+
+        def initialize(dir:, network:, ttl: TTL, clock: -> { Time.now.to_f })
+          @dir = dir
+          @ttl = ttl
+          @clock = clock
+          id = network.map { _1.to_s }.join("\n")
+          @file = File.join(dir, "#{Digest::SHA256.hexdigest(id)[0, 24]}.json")
+        end
+
+        attr_reader :file
+
+        # The cache directory: $XDG_CACHE_HOME/asterism, else
+        # ~/.cache/asterism.
+        def self.dir(env)
+          base = env["XDG_CACHE_HOME"].to_s
+          base = File.join(Dir.home, ".cache") if base.empty?
+          File.join(base, "asterism")
+        rescue ArgumentError
+          nil
+        end
+
+        # The entry's value when it is fresh, else the block's (kept unless
+        # it is nil: what did not answer is asked again next time).
+        def fetch(entry)
+          data = read
+          e = data[entry]
+          now = @clock.call
+          return e["v"] if e.is_a?(Hash) && e["t"].is_a?(Numeric) && now - e["t"] < @ttl && now >= e["t"]
+          v = yield
+          return v if v.nil?
+          data = read.reject { |_, x| !x.is_a?(Hash) || !x["t"].is_a?(Numeric) || now - x["t"] >= @ttl }
+          data[entry] = { "t" => now, "v" => v }
+          write(data)
+          v
+        end
+
+        private
+
+        def read
+          h = JSON.parse(File.read(@file))
+          h.is_a?(Hash) ? h : {}
+        rescue StandardError
+          {}
+        end
+
+        def write(data)
+          FileUtils.mkdir_p(@dir, mode: 0o700)
+          tmp = "#{@file}.#{Process.pid}.tmp"
+          File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { _1.write(JSON.generate(data)) }
+          File.rename(tmp, @file)
+        rescue StandardError
+          begin
+            File.unlink(tmp) if tmp
+          rescue StandardError
+            nil
+          end
+          nil
+        end
+      end
+
+      # ------------------------------------------------------------ the scripts
+
+      BASH = <<~'BASH'
+        # asterism's Tab completion for bash: source <(asterism completion bash)
+        # (or put that line in ~/.bashrc). Each Tab runs `asterism __complete`;
+        # the names on the network come from the network named on the line
+        # (--router, --credentials, --peer) or in ASTERISM_CREDENTIALS /
+        # ASTERISM_ROUTER, asked briefly and remembered for a few seconds.
+        _asterism() {
+          local cur=${COMP_WORDS[COMP_CWORD]}
+          local IFS=$'\n'
+          local out
+          out=$(asterism __complete --bash "${COMP_LINE:0:COMP_POINT}" 2>/dev/null)
+          if [[ $out == ":files" ]]; then
+            compopt -o filenames 2>/dev/null
+            COMPREPLY=($(compgen -f -- "$cur"))
+            return 0
+          fi
+          COMPREPLY=($out)
+          local c
+          for c in "${COMPREPLY[@]}"; do
+            if [[ $c == */ ]]; then
+              compopt -o nospace 2>/dev/null
+              break
+            fi
+          done
+          return 0
+        }
+        complete -F _asterism asterism
+      BASH
+
+      ZSH = <<~'ZSH'
+        # asterism's Tab completion for zsh: source <(asterism completion zsh)
+        # after compinit (or put that line in ~/.zshrc). Each Tab runs
+        # `asterism __complete`; the names on the network come from the network
+        # named on the line (--router, --credentials, --peer) or in
+        # ASTERISM_CREDENTIALS / ASTERISM_ROUTER, asked briefly and remembered
+        # for a few seconds.
+        _asterism() {
+          local -a cands slash plain
+          cands=("${(@f)$(asterism __complete -- "${(@)words[2,CURRENT]}" 2>/dev/null)}")
+          cands=(${cands:#})
+          if [[ ${cands[1]} == ":files" ]]; then
+            _files
+            return
+          fi
+          slash=(${(M)cands:#*/})
+          plain=(${cands:#*/})
+          (( ${#plain} )) && compadd -- "${plain[@]}"
+          (( ${#slash} )) && compadd -S '' -- "${slash[@]}"
+          return 0
+        }
+        compdef _asterism asterism
+      ZSH
+    end
+  end
+end

data/lib/asterism/cli/hz.rb

@@ -0,0 +1,77 @@
+# `asterism status hz`: how often an application's status changes, as
+# `ros2 topic hz` tells how often a topic is published. Each change is a
+# time (a monotonic clock, given or Process.clock_gettime); the intervals
+# between the last ones (a window of them) give the average rate and the
+# intervals' min, max and standard deviation. A put that brings the same
+# status again (as after a reconnection) is not a change.
+module Asterism
+  class CLI
+    class Hz
+      attr_reader :count
+
+      # window: how many of the last intervals count. clock: a callable
+      # that returns the time in seconds (monotonic).
+      def initialize(window: 1000, clock: nil)
+        @window = window
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @times = []
+        @last = nil
+        @seeded = false
+        @count = 0
+        @reported = 0
+      end
+
+      # The status there at the start: what the first put is compared with
+      # (not a change itself).
+      def seed(status)
+        @last = status
+        @seeded = true
+      end
+
+      # A put of the status: a change (true) when it differs from the last
+      # one seen (the first put without a seed is one).
+      def put(status)
+        return false if @seeded && status == @last
+        @last = status
+        @seeded = true
+        add(@clock.call)
+        true
+      end
+
+      # A change at time t (seconds).
+      def add(t)
+        @count += 1
+        @times << t
+        @times.shift while @times.size > @window + 1
+      end
+
+      # {"rate_hz", "min_s", "max_s", "std_s", "window", "count"} over the
+      # intervals in the window, or nil before two changes.
+      def stats
+        return nil if @times.size < 2
+        ints = @times.each_cons(2).map { |a, b| b - a }
+        avg = ints.sum / ints.size
+        var = ints.sum { (_1 - avg)**2 } / ints.size
+        { "rate_hz" => avg.positive? ? 1.0 / avg : nil, "min_s" => ints.min, "max_s" => ints.max,
+          "std_s" => Math.sqrt(var), "window" => ints.size, "count" => @count }
+      end
+
+      # stats when a change came since the last report (else nil): what a
+      # period prints.
+      def report
+        return nil if @count == @reported
+        s = stats
+        @reported = @count if s
+        s
+      end
+
+      # The lines of a report, as ros2 topic hz prints them.
+      def self.text(s)
+        rate = s["rate_hz"] ? format("%.3f", s["rate_hz"]) : "inf"
+        ["average rate: #{rate} Hz",
+         format("  min: %.3f s  max: %.3f s  std dev: %.3f s  window: %d", s["min_s"], s["max_s"], s["std_s"],
+                s["window"])]
+      end
+    end
+  end
+end