asterism 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee81a1950e5fffa0f5d299999d7878834a79d897e3b4cbf879e293fc6b00531
-  data.tar.gz: 05a88c6ad24fafe262668cb11f4a48e7e5357678c1903207aae004ac0e518311
+  metadata.gz: 0c6b58e8ab7a548a803e5f44513b3b3dc0e7b7fb3fe26ecd38897c82f0db44cd
+  data.tar.gz: 616899e3dfc111ae5b8a930a8aa4f1725c55fe8123283d17d15fde4ae5d20875
 SHA512:
-  metadata.gz: 4c6e015f5bd202a1cf44dc3d6ee59fe8af406cb899735df5ee828610cb82de5aa67035be2b5c9cbf1b4c603e0477eaba1e9e503f3ed901e81308ea1b98c91fbc
-  data.tar.gz: 717902fdcce318aad8a78776f0f72b4063241868dbc8b50def6a0386f2868f764dbf356403b0ef1cbd727c5dc8df6818ced7d465cfb23338452e892d3e0c6dc1
+  metadata.gz: 11f82e660fda7b6daf50ac5fb39fd76d3f70a40adb2d531ed0ecce702d8aae889cc950af67d318fd16b6c92e084b8f7a0146bd5276c77ef42d4a9af8b83856c8
+  data.tar.gz: 947f18093015774357b5d9a1d136af8e35d7b0c33db23b90646d2ed23938c3759c710a90c8c237b6caa21c6cb46469cd923bca726c64c77ccd86406cd347ed93

data/CHANGELOG.md

@@ -6,6 +6,77 @@ 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.10.0
+
+The command line and its MCP bridge only; the library and the wire are as
+in 0.9.0.
+
+- `asterism mcp` has a tool `asterism_values`: the latest value of each
+  key the applications put on (`asterism/<node>/<app>/<object>/<more>`,
+  e.g. a game table's state), as the server received them since it
+  started (it subscribes to `asterism/**` from the start). Arguments
+  `pattern` (`*`, `**`; default every key) and `wait` (seconds, at most
+  30: for the first put that matches when none has come yet). Each value
+  has its time, its age, its size and whether its application is still on
+  the network (`app`: `alive` / `gone` / `restarted`). Limits: 1000 keys
+  and 16 MiB kept (the oldest forgotten first), a put over 256 KiB as its
+  size only, a value's JSON cut at 8192 bytes in an answer
+  (`truncated`), 100 keys an answer (`more`). A viewer's certificate is
+  enough. README "MCP".
+- `asterism object get PATH [KEY]`: the next value the application puts
+  there (`--timeout`, 5 s). `asterism object echo PATH [KEY]`: the values
+  as they come (the text: a key's value whole, then what changed;
+  `--raw`, `--once`, `--duration`). `-o json` / `-o yaml`, and Tab
+  completion of `PATH`. Both say so when nothing came (not readable, or
+  not changed).
+- The other tools, commands and their output (`--json` too) are as they
+  were; `asterism --help`, `asterism object` and the MCP server's
+  instructions mention the new ones.
+
+## 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.10.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,103 @@ 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 object get  games/games/othello1 state     # the next value the application puts there
+asterism object echo games/games/othello1 state     # the values as they come (what changed)
+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 +519,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 +535,75 @@ $ 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.
+- **object get / echo PATH [KEY]** read what an application puts on its
+  own keys, `asterism/<node>/<app>/<object>/<more>` (docs/protocol.md 2.2;
+  a game table puts its state on `<table>/state`). `PATH` is
+  `node/app/object` (`*` for a part), `KEY` the rest (`*` and `**` as whole
+  parts; `**` by default). A put is kept nowhere and a get has no answer
+  for it, so both wait for puts: `object get` prints the next one and ends
+  (`--timeout`, 5 s; an application puts when its value changes, so a quiet
+  one gives nothing), `object echo` prints them as they come: a key's
+  value whole the first time, then only what changed in it, as
+  `status echo` does (`--raw`: each value whole; `--once`: the first put;
+  `--duration`). The value is MessagePack (Asterism's own) or JSON as it
+  is, other text as a string, bytes as their count; `-o json` gives each
+  put as `{"key", "t", "bytes", "format", "value"}`. When nothing comes
+  they say so: the router does not let this node read the key (a role
+  needs `read` on it), or nothing changed.
+- **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
@@ -481,6 +620,7 @@ claude mcp add asterism -- asterism mcp --credentials admin.tar --allow 'games/o
 | `asterism_nodes` | the nodes, their profiles, applications (with their statuses) and objects |
 | `asterism_objects` | the objects and their methods (meta); `callable_as` names the tool for an allowed method |
 | `asterism_status` | the applications' statuses (`node` / `app` narrow it) |
+| `asterism_values` | the latest value of each key the applications put on (`asterism/<node>/<app>/<object>/<more>`, e.g. a game table's state), as this server received them since it started; `pattern` (`node/app/object/more`, `*` and `**`; default `**`) and `wait` (seconds, at most 30) |
 | `<node>.<app>.<object>.<method>` | one per method an `--allow` pattern names, made from the meta: the arguments' names it tells are the inputs and its doc the description (with the object's doc after it); without names, arity n gives the inputs `arg1` .. `argN` (any JSON value), arity -1 an array `args`; `kwargs` is an object of keyword arguments. The answer is `{"value": ...}`, or an error with its kind |
 
 - `--allow PATTERN` (repeatable): `[node/][app/]object.method`, `*` within
@@ -495,6 +635,38 @@ claude mcp add asterism -- asterism mcp --credentials admin.tar --allow 'games/o
   gives the MCP client its own seat. `--app` names this application (a
   game host that follows its players by the application `game` sees an
   MCP client started with `--app game` come and go).
+- **asterism_values**: from its start the server subscribes to
+  `asterism/**` (the applications' own keys; `@profile` and `@status` are
+  not under it) and keeps the last value of each key with the time it
+  came. A put comes only when a value changes and is kept nowhere else, so
+  a key that has not been put since the server started is not there:
+  `wait` waits (at most 30 s) for the first put that matches when none has
+  come yet. Each value has `key`, `value`, `t`, `age_s` (seconds since it
+  came), `bytes`, `format` and `app`: `alive`, `gone` (the application is
+  not on the network now; the value is its last one, not the present) or
+  `restarted` (it left and came back after this value). A value whose JSON
+  is longer than 8192 bytes is cut (`truncated: true`, the value the start
+  of its JSON text); the server keeps at most 1000 keys and 16 MiB (the
+  key received longest ago is forgotten first; `forgotten` counts them), a
+  single put over 256 KiB as its size only, and an answer lists at most
+  100 keys (`more`). Nothing that matches: `note` says so (not put since
+  the start, or the router does not let the server read it). A console's
+  viewer role (`read` / `watch` on `asterism/**`) is enough.
+
+  Showing an othello table to an AI assistant (the game host puts the
+  table on `games/games/othello1/state` after every move):
+
+  ```
+  claude mcp add asterism -- asterism mcp --credentials viewer.tar
+  > Watch the othello game on games/games/othello1 and tell me who is winning.
+    (the assistant calls asterism_values with pattern games/games/othello1/state, wait 30)
+  {"since":"2026-10-20T02:16:50.191Z","values":[{"key":"games/games/othello1/state",
+   "t":"2026-10-20T02:16:58.583Z","age_s":0.4,"app":"alive","bytes":181,"format":"msgpack",
+   "value":{"v":15,"t":"othello1","st":"play","nm":["CPU","Alice"],"sk":[2,1],...,
+            "bd":"..W.......W.......WBWWW...WBB....W.BBB..........................",
+            "tn":0,"n":10,"last":"c1","lg":"b1b2e2f2g2b3h3b4a6","cnt":[6,8]}}]}
+  ```
+
 - An object that describes its methods at `expose` (`args:` and `doc:`,
   "Describing the methods" below) gives the AI assistant the names and the
   texts; without them it sees only the number of arguments.

data/lib/asterism/cli/complete.rb

@@ -0,0 +1,283 @@
+# 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], ["object get", 0], ["object echo", 0], ["objects", 0], ["call", 0]
+          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