asterism 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d729d6c233d712c647e7fb1168f2587fa0e81eb1b176a11f12ac7c349f61a592
-  data.tar.gz: fce6e1102b0e4e2c404adf28a299c77efd548f6a07e92dc81a7b54a9efe1951e
+  metadata.gz: 8c3c929e3018c538fab3983c9fffce4fd997bfa8b37cad43fbaa6c0eb5890d65
+  data.tar.gz: b4fc43d2d5d286139eb700c5711786827aab41aa8a7628686b45270a321f1807
 SHA512:
-  metadata.gz: c2050d9890925ad4b0910f3e8063a7d2b6e9ef1e8f68ea3346bea26c02674cce7a6b0c2ee798d2940f2171d7c763c49dd8160a44b3d3204b13ccea813936430c
-  data.tar.gz: 862531b730d5bc6f00c673271fb4d1d8db6ecaaab11969a4be95234c09be4ba6eceed245b24102f490fda6608f946b5d30e8ce3b960255b197b95bcd5a4aa550
+  metadata.gz: f971a84780f4a1ce1e24554530201f6bccaba7f8de6ec03c5b2dc6742c6c370e2567af5c82e4609fd82f582d32cbe314f82bc5c60d5815b5c33e805980b14a58
+  data.tar.gz: c355695ad9b52f7513f791191eeae8ded62011cdc011c50d1e921f6fa1e58190f491cc3adc0b367fa0087def3cfd6cd03729a43143b19f608b3f3a5603879f3c

data/CHANGELOG.md

@@ -6,6 +6,106 @@ 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:
+the statuses and the methods' texts in the meta are additions that older
+nodes ignore. The command line comes with the gem (`exe/asterism`); its MCP
+server needs the mcp gem, which is not a dependency.
+
+- Application statuses (protocol 1, an addition: docs/protocol.md 8).
+  `Asterism.status(tables: 3)` / `Asterism.status({ ... })` sets this
+  application's status, a small Hash that changes while it runs (String
+  keys, nested 4 levels at most, 1024 bytes packed at most); it is put on
+  `asterism/<node>/<app>/@status` when it changes (the same status again
+  puts nothing), at connect and after a lost connection comes back, and a
+  get there answers it. `Asterism.status_of(node, app)` reads another
+  application's (nil when it has none). `Asterism::Status.check` /
+  `.parse` clean what comes in. CRuby: `net.status`, `net.status_of`,
+  `net.on_status(pattern) { |node, app, status| }`. Both on mruby too
+  (`rake test:mruby`). `@status` is a verbatim chunk like `@profile`:
+  `asterism/**` does not reach it. The conformance samples are version 3
+  (status queries, `status_of`, `status_puts`).
+- `Asterism.apps(pattern = "*/*")`: the applications alive now
+  (`"<node>/<app>"`, from their liveliness tokens).
+- The command line `asterism` (exe/asterism, CRuby): `nodes`, `objects`,
+  `tree`, `watch` (nodes, applications and objects coming and going, and
+  statuses), `ping` (alias `echo`: round trips of the meta, a profile or a
+  call), `call` (arguments as JSON or Ruby literals, read with Ripper), with
+  `--router` or `--credentials` (a console's `.tar`) and `--json`.
+  README "The command line". `rake test:cli`.
+- `asterism mcp`: an MCP server on stdio (the mcp gem, not a dependency).
+  Read-only tools (`asterism_nodes`, `asterism_objects`, `asterism_status`)
+  always; a tool per method that `--allow` names, its inputs made from the
+  meta's arity; the list follows the network (tools/list_changed).
+- The meta tells the arguments' names and what a method does (protocol 1,
+  an addition: docs/protocol.md 5). `expose` takes
+  `methods: { "move" => { args: %w[token n square], doc: "..." } }` next to
+  the numbers (`{ add: 2 }`), and `doc:` for the object itself; the names
+  give the number of arguments checked (`arity:` says otherwise, -1 for
+  any). Readers ignore the fields (old nodes and new ones mix). `asterism
+  mcp` makes the tools' inputs from the names and their descriptions from
+  the docs; `objects` and `tree` show them. The conformance samples are
+  version 4 (the object `other` of the node under test has them).
+- `on_app_join { |node, app| }` / `on_app_leave { |node, app| }`: an
+  application of another node came or went (its token
+  `asterism/<node>/<app>`), while the node may stay with others; on mruby
+  too. CRuby: `net.on_app_join` / `net.on_app_leave`, and `off_*`.
+
+- `credentials:` on the boards too: `Asterism::Credentials` moved to
+  `mrblib/credentials.rb` and reads the console's `.tar` in plain Ruby
+  (ustar taken apart with `byteslice` / `getbyte`, base64 without `pack`,
+  `asterism.json` with or without a JSON library). `Asterism.connect` takes
+  `credentials:` on mruby (with picoruby-asterism-zenoh's TLS, ESP-IDF
+  builds); `locator` and `node:` are optional when it is given. CRuby keeps
+  its reading (the standard library's tar reader, the file mode warning,
+  the key pair check) in a module prepended to the class. `rake test:mruby`
+  checks the board's reading against CRuby's.
+
 ## 0.7.1
 
 Needs asterism-zenoh 0.4.1 or later (`Session#reconnecting?`).

data/README.md

@@ -13,7 +13,8 @@ repository holds the pure Ruby layers, written once for every Ruby:
 | `data/icon.png` | CRuby's default profile icon (32x32 PNG; [Profiles](#profiles)) |
 | `data/msgs/` | ROS 2 message types generated from ROS 2 Jazzy's definitions (Apache-2.0; tf2_msgs BSD-3-Clause; see NOTICE) |
 | `tools/` | The type generator `asterism_msggen.rb`, the Jazzy definitions it reads, `ros2_types.rb` (refreshes them from a ROS 2 image) |
-| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_profile.rb` (node profiles), `test_session.rb` (`Asterism.session`, `on_join` / `on_leave`), `test_api_*.rb` (the CRuby API), `bench_poll.rb` (`rake bench:poll`) |
+| `exe/asterism`, `lib/asterism/cli*` | The command line: look at a network, call an object, an MCP server ([The command line](#the-command-line); CRuby only) |
+| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_profile.rb` (node profiles), `test_status.rb` (application statuses), `test_meta_apps.rb` (the meta's args / doc, on_app_join / on_app_leave), `test_cli.rb` (the command line), `test_session.rb` (`Asterism.session`, `on_join` / `on_leave`), `test_api_*.rb` (the CRuby API), `bench_poll.rb` (`rake bench:poll`) |
 | `test/protocol/` | the conformance samples of the wire protocol (`samples.json`), the driver that checks an implementation against them, and the Ruby node it checks (`rake test:protocol`, `rake test:protocol_mruby`; [docs/protocol.md](docs/protocol.md)) |
 | `host_test/` | `rake test:mruby`: the shared layer on mruby (profiles between two mruby processes; `Asterism.session`, `on_join` / `on_leave` and the time of a poll against `peer.rb`) |
 | `examples/` | CRuby: `node.rb` (objects with a board), `node_polled.rb` (the same with the portable API of the boards), `ros2_talker.rb` (topics, a timer, services with ROS 2), `ros2_rover.rb` (drive a ROS 2 robot: `/cmd_vel`, `/odom`, `/imu`), `zenoh.rb` (plain Zenoh), `mujoco/` (MuJoCo run from CRuby through Fiddle, its robot exposed as Asterism objects; see its README) |
@@ -100,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.7.1.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:
@@ -129,6 +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), 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)
@@ -163,7 +165,7 @@ ruby examples/node_polled.rb --router tcp/192.0.2.2:7447    # the same, polled
 ruby examples/ros2_talker.rb --router tcp/192.0.2.2:7447 [--service NAME]
 
 # ROS 2: drive a robot (made for family-mruby's MuJoCo rover,
-# docker-compose.mujoco.yml): 1 m forward and 90 degrees left by /odom,
+# docker/asterism/docker-compose.mujoco.yml): 1 m forward and 90 degrees left by /odom,
 # compared with /ground_truth/odom; or the keyboard
 ruby examples/ros2_rover.rb --router tcp/192.0.2.2:7447 [--keys]
 
@@ -315,6 +317,13 @@ and gives zenoh the CA, the certificate and the key as
 (a Hash) is laid over these keys. A tar that the group or others may read
 is warned about, as ssh does with a key: `chmod 600 alice.tar`.
 
+The boards (mruby / PicoRuby over picoruby-asterism-zenoh) take the same
+file with `Asterism.connect(credentials: "/home/asterism/alice.tar", app: "game")`
+when their Zenoh binding has TLS (`Asterism::Zenoh::TLS`; ESP-IDF builds).
+There `Asterism::Credentials` reads the tar in plain Ruby (no Regexp, no
+`pack`), the boards have no file modes to warn about, and the key pair is
+left for the router to check; `config:` takes the TLS keys only.
+
 The router checks the certificate against its CA, and its ACL can tell the
 nodes apart by the certificate's common name. The name in the locator must
 be one the router's certificate is valid for (zenoh checks it; it is
@@ -401,6 +410,217 @@ What may be shared between threads:
 | The boards | one thread (the application's update loop) |
 | Ractors | not supported |
 
+## The command line
+
+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`. 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 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`).
+
+```
+$ 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 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)
+  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 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),
+  or `--credentials FILE.tar` (a console's `.tar`: mutual TLS, its router
+  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`). 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,
+  profile and status, and the router refuses its calls, so `asterism call`
+  says "nobody answers" and nothing runs. Something the router refuses is
+  left out of a listing; it is not reported as gone.
+- **Arguments** of `call` (and `ping --call`): each is JSON, else a Ruby
+  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.
+- **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
+the asterism gem does not depend on: `gem install mcp`). It reads by
+default, and calls only the methods `--allow` names:
+
+```
+asterism mcp --router tcp/192.0.2.2:7447 --allow 'games/othello1.*'
+claude mcp add asterism -- asterism mcp --credentials admin.tar --allow 'games/othello1.*'
+```
+
+| Tool | What |
+|---|---|
+| `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) |
+| `<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
+  a part as a wildcard. A pattern with fewer parts matches the last parts
+  of the path (`games/othello1.*` is `*/games/othello1.*`); without
+  `.method` every method of the object.
+- The call tools follow the network: when an allowed object appears or
+  goes, the list is made again and the client is told
+  (`notifications/tools/list_changed`).
+- The calls are made as this node (`--node`, or the certificate's name), so
+  an object exposed with `caller: :from` sees who called; a game table
+  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).
+- 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.
+
 ## License
 
 MIT (LICENSE) for Asterism's code. The ROS 2 definitions in
@@ -452,11 +672,12 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 
 | Call | Returns | Raises / notes |
 |---|---|---|
-| `Asterism.connect(locator, node:, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: 1.5)` (CRuby also `credentials:`, see [Over TLS](#over-tls-a-router-on-the-internet)) | `Asterism` | `locator`, `mode:`, `listen:` (and `config:` / `connect_timeout:` when given, CRuby only: TLS and the rest of zenoh's configuration; the boards raise `ArgumentError`) go to `Asterism::Zenoh::Session.open` (client of a router by default; `mode: :peer` with or without `listen:` without one). `node:` is this machine's ID, `app:` the application's name (one key chunk each: no `/ * $ ? #`, not starting with `@`; else `ArgumentError`). `Disconnected` when it cannot connect; `Error` when objects of the same `<node>/<app>` are already alive (a second copy of the application), or when already connected. Waits up to `check_timeout:` seconds for that check (a router answers at once; give more over a slow relay). Returns the module itself: on a board the module is the connection (one per application). The default is plain text without authentication; see [Over TLS](#over-tls-a-router-on-the-internet). |
-| `Asterism.expose(name, obj, methods:, caller: nil)` | `"<node>/<app>/<name>"` | `methods:` is an Array of names, or a Hash `name => number of arguments` (checked before the call; `-1` or the Array form: any). `ArgumentError` when `obj` has no such public method. Exposing a name again replaces it. `caller: :from` passes the calling node's ID to every method as the keyword `from:` and refuses a call that brings `from:` itself ([Who called](#who-called)). |
+| `Asterism.connect(locator = nil, node: nil, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: 1.5, credentials: nil)` (`credentials:` see [Over TLS](#over-tls-a-router-on-the-internet)) | `Asterism` | `locator`, `mode:`, `listen:` (and `config:` / `connect_timeout:` when given: TLS and the rest of zenoh's configuration on CRuby; the boards take the TLS keys of `config:` only and raise `ArgumentError` for the rest) go to `Asterism::Zenoh::Session.open` (client of a router by default; `mode: :peer` with or without `listen:` without one). `node:` is this machine's ID, `app:` the application's name (one key chunk each: no `/ * $ ? #`, not starting with `@`; else `ArgumentError`). `Disconnected` when it cannot connect; `Error` when objects of the same `<node>/<app>` are already alive (a second copy of the application), or when already connected. Waits up to `check_timeout:` seconds for that check (a router answers at once; give more over a slow relay). Returns the module itself: on a board the module is the connection (one per application). The default is plain text without authentication; see [Over TLS](#over-tls-a-router-on-the-internet). |
+| `Asterism.expose(name, obj, methods:, caller: nil, doc: nil)` | `"<node>/<app>/<name>"` | `methods:` is an Array of names, or a Hash `name => number of arguments` (checked before the call; `-1` or the Array form: any) or `name => { args: [names], doc: "text" }` ([Describing the methods](#describing-the-methods)); `doc:` the object's own text. `ArgumentError` when `obj` has no such public method. Exposing a name again replaces it. `caller: :from` passes the calling node's ID to every method as the keyword `from:` and refuses a call that brings `from:` itself ([Who called](#who-called)). |
 | `Asterism.current_call` | `Asterism::CurrentCall` or nil | While an exposed method runs for a call: `from` (the calling node's ID), `verified` (`:claimed`, or `:local` for a call from this application), `object`, `method`. nil outside a call ([Who called](#who-called)). |
 | `Asterism.unexpose(name)` | true / false | |
 | `Asterism.poll` | true / false | Call from the update loop: polls Zenoh, answers the calls that came in, follows who is alive and calls the `on_join` / `on_leave` blocks. `false` once the connection is closed or lost. Cheap when nothing came (0.6.0): each queue is looked at by its count, and the list of nodes is made again only after a liveliness change. |
+| `Asterism.on_app_join { \|node, app\| }` / `Asterism.on_app_leave { \|node, app\| }` | `Asterism` | An application of another node appeared (its token `asterism/<node>/<app>`) / is gone. A node may run several: each comes and goes on its own while the node stays. Told like `on_join` (from `Asterism.poll`; at connect for those there; all leave when the connection is lost); `off_app_join(proc)` / `off_app_leave(proc)`; CRuby `net.on_app_join` / `net.on_app_leave` |
 | `Asterism.on_join { \|node\| }` / `Asterism.on_leave { \|node\| }` | `Asterism` | Another node appeared (one of its applications or objects) / is gone (no application and no object left). The nodes there already join on the first polls after connecting; when the connection is lost, every node known until then leaves (on the next `Asterism.poll`). The blocks run from `Asterism.poll` only, never from the polling inside a waiting call; what they raise comes out of `Asterism.poll`. Each call adds a block; `Asterism.off_join(proc)` / `off_leave(proc)` remove one; `Asterism.close` forgets them (a lost connection does not). |
 | `Asterism[path, timeout: 2.0]` | `Proxy` | `path` is `<node>/<app>/<object>` without wildcards (`ArgumentError`). `timeout:` (seconds) or `timeout_ms:` is the time limit of its calls. Nothing is sent until a method is called. |
 | `proxy.<method>(*args, **kw)` | the remote return value | Waits for the answer (the proxy's time limit). `RemoteError` when it raised there or could not be called (`remote_kind` says which: `raised`, or not exposed `not_exposed` (`NoMethodError`), wrong number of arguments `arguments` (`ArgumentError`), no such object `no_object` (`NameError`); [Errors](#errors)), `TimeoutError` when no answer came in time (also at once when nobody answers that key), `Disconnected`, `EncodeError` (before anything is sent) for a value MessagePack cannot carry. A block cannot be sent (`ArgumentError`). |
@@ -468,12 +689,39 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 | `proxy.asterism_meta` / `proxy.asterism_path` | Hash, String | `{"methods" => [{"name" => name, "arity" => n}, ...]}` |
 | `Asterism.each(pattern = "**") { \|proxy\| }` | count (Array without a block) | The exposed objects alive now (this application's own included) whose `<node>/<app>/<object>` matches; `*` is one chunk, `**` any number. 1.0 returns the proxies from the block form instead of their number (Ruby's `each` returns its receiver); write `Asterism.each(pattern).size` for the count. |
 | `Asterism.nodes` | `[String]` | Node IDs alive now, this one first. |
+| `Asterism.apps(pattern = "*/*")` | `[String]` | The applications alive now, `"<node>/<app>"` (from their liveliness tokens; this one first). |
 | `Asterism.connected?` / `node_id` / `app` / `exposed` / `lost_reason` | | |
 | `Asterism.reconnecting?` | true / false | True while the router is away and the binding opens the connection again ([When the connection is lost](#when-the-connection-is-lost)). |
 | `Asterism.session` | `Asterism::Zenoh::Session` | The connection's own session, for put / subscribe / a ROS 2 node on the same connection ([One connection](#one-connection-asterismsession)). The same object until the connection closes. `Disconnected` when not connected. Its `close` does nothing (warns once); `Asterism.close` closes it. |
 | `Asterism.close` | nil | Withdraws every exposed object. Idempotent. |
 | `Asterism.profile(kind:, name:, host:, icon:)` / `Asterism.profile` | Hash | This node's profile: sets the fields given and returns it; without arguments, returns it. See [Profiles](#profiles). |
 | `Asterism.profile_of(node, icon: true, timeout: 2.0)` | Hash or nil | Another node's profile, nil when it does not answer (an older version, a ROS 2 node). |
+| `Asterism.status(hash = nil, **fields)` / `Asterism.status` | Hash or nil | This application's status: a Hash is the whole status, keywords change those fields (nil removes one); put on the network when it changes. Without arguments, returns it. See [Status](#status). |
+| `Asterism.status_of(node, app, timeout: 2.0)` | Hash or nil | Another application's status, nil when it has none or does not answer. |
+
+## Describing the methods
+
+The meta (what `proxy.respond_to?` reads) can carry the arguments' names
+and what each method does, for the people and the tools that show them
+(`asterism mcp` turns them into an AI assistant's tool inputs and
+descriptions; `asterism objects` prints them). Give them at `expose`, next
+to the numbers:
+
+```ruby
+Asterism.expose("othello1", table, caller: :from, doc: "An othello table. Call view for the board.",
+                methods: { join: 1,                                   # a number, as before
+                           "move" => { args: %w[token n square],
+                                       doc: "Plays square (\"d3\") on the board version n of view." },
+                           view: { args: [:token], doc: "The board as this member sees it." } })
+```
+
+- The names give the number of arguments checked (`args: %w[a b]` is 2);
+  `arity: -1` keeps it unchecked (the names are then the leading ones).
+- The texts are at most 2048 bytes, the names at most 16 of 64 bytes; the
+  first line of a doc is its summary. They travel in every meta reply, so
+  keep them short on a board.
+- Old readers ignore them and old nodes do not send them
+  (docs/protocol.md 5); a proxy works the same either way.
 
 ## Profiles
 
@@ -528,6 +776,41 @@ Asterism.profile_of("an-older-node")                 # => nil
   an acceptable PNG (nil otherwise), for a tool that wants to check an icon
   first.
 
+## Status
+
+An application tells what changes while it runs: how many tables a game
+host has open and who sits at them, a battery level, a mode. The profile
+says once what a node is; the status is the application's and changes.
+
+```ruby
+Asterism.status(tables: 3, humans: 2)           # sets those fields, keeps the others
+Asterism.status(humans: nil)                    # nil removes a field
+Asterism.status({ "mahjong1" => { "st" => "play", "humans" => 1 } })   # a Hash: the whole status
+Asterism.status                                 # => {"mahjong1" => {...}} (nil when none was set)
+Asterism.status_of("games", "games")            # another application's, or nil
+```
+
+- **On the network.** `asterism/<node>/<app>/@status`
+  ([docs/protocol.md](docs/protocol.md) 8): the application answers a get
+  there with its status, and puts it there when it changes (setting the
+  same status again puts nothing), at connect and after a lost connection
+  comes back. An application that never set one answers nothing.
+- **The value.** A Hash with String (or Symbol) keys; the values are
+  anything a call can carry, nested at most 4 levels below the Hash, and
+  the whole packs into 1024 bytes at most. `ArgumentError` otherwise.
+  Whoever may read `asterism/*/*/@status` reads it: counts and states, not
+  secrets.
+- **Following.** Subscribe to `asterism/*/*/@status` and read each put with
+  `Asterism::Status.parse(key, payload)` (`[node, app, status]` or nil); on
+  CRuby, `net.on_status("*/*") { |node, app, status| }`. Only changes are
+  put: ask `status_of` once for an application that appeared.
+- **Behind access control.** `@status` is a verbatim chunk: `asterism/**`
+  does not match it. A router's rules need `asterism/*/*/@status` for a
+  reader (query, subscription) and `asterism/<node>/*/@status` for the
+  application (put, queryable, reply).
+- Kept across `connect` and `close`, like the profile (it belongs to the
+  process, or the VM on a board).
+
 ## One connection: `Asterism.session`
 
 An application that also puts, subscribes or runs a ROS 2 node uses the

data/exe/asterism

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The command line of the asterism gem: look at an Asterism network, call
+# an object, or serve it to an MCP client (lib/asterism/cli.rb; `asterism
+# help`).
+require "asterism/cli"
+exit Asterism::CLI.start(ARGV)

data/lib/asterism/cli/allow.rb

@@ -0,0 +1,53 @@
+# The --allow patterns of `asterism mcp` (lib/asterism/cli/mcp.rb): which
+# methods an MCP client may call.
+module Asterism
+  class CLI
+    # The --allow patterns: [node/][app/]object.method, each part a glob
+    # (* any text within the part). A pattern with fewer parts matches the
+    # last parts of the path ("games/othello1.*" is "*/games/othello1.*";
+    # "othello1" alone is "*/*/othello1.*": a pattern without .method
+    # allows every method).
+    class Allow
+      def initialize(patterns)
+        @list = patterns.map { parse(_1) }
+      end
+
+      def empty? = @list.empty?
+
+      # Whether some pattern names this object (any of its methods).
+      def object?(path)
+        parts = path.split("/")
+        @list.any? { |chunks, _| chunks_match?(chunks, parts) }
+      end
+
+      def method?(path, method)
+        parts = path.split("/")
+        @list.any? { |chunks, m| chunks_match?(chunks, parts) && glob?(m, method.to_s) }
+      end
+
+      private
+
+      def parse(pat)
+        slash = pat.rindex("/") || -1
+        dot = pat.index(".", slash + 1)
+        path = dot ? pat[0...dot] : pat
+        meth = dot ? pat[(dot + 1)..] : "*"
+        chunks = path.split("/", -1)
+        if chunks.empty? || chunks.size > 3 || chunks.any?(&:empty?) || meth.empty?
+          raise ArgumentError, "--allow #{pat.inspect}: expected [node/][app/]object.method (globs allowed)"
+        end
+        [Array.new(3 - chunks.size, "*") + chunks, meth]
+      end
+
+      def chunks_match?(chunks, parts)
+        parts.size == 3 && chunks.each_with_index.all? { |c, i| glob?(c, parts[i]) }
+      end
+
+      # Only * is a wildcard (any text); ? and the rest are themselves (a
+      # method may be called ok?).
+      def glob?(pat, text)
+        Regexp.new("\\A#{pat.split('*', -1).map { Regexp.escape(_1) }.join('.*')}\\z").match?(text)
+      end
+    end
+  end
+end