asterism 0.8.0 → 0.10.0

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

data/lib/asterism/cli/mcp.rb

@@ -9,6 +9,10 @@
 #                      and objects                         (always; reads)
 #   asterism_objects   the objects and their methods (meta) (always; reads)
 #   asterism_status    the applications' statuses           (always; reads)
+#   asterism_values    the latest value of each key the applications put
+#                      on (asterism/<node>/<app>/<object>/<more>), as this
+#                      server received them since it started (always;
+#                      reads; lib/asterism/cli/values.rb)
 #   <node>.<app>.<object>.<method>
 #                      one per method that an --allow pattern names, made
 #                      from the object's meta: the arguments' names the
@@ -30,7 +34,8 @@ module Asterism
         These tools look at an Asterism network: Ruby programs and boards that expose objects to each other over
         Zenoh. Paths are <node>/<app>/<object>. asterism_nodes lists the nodes and their applications (with the
         status each application tells about itself, a JSON object of its own), asterism_objects the objects and
-        their methods, asterism_status the statuses. The other tools call one method each, on the object their
+        their methods, asterism_status the statuses, asterism_values the latest values the applications put on
+        their own keys (a game table's state). The other tools call one method each, on the object their
         name says (<node>.<app>.<object>.<method>); only the methods this server was started to allow are there.
         A call's answer is {"value": ...}; an error says its kind (raised, not_exposed, arguments, ...).
       TEXT
@@ -43,13 +48,17 @@ module Asterism
         @call_tools = {}  # tool name => [path, method, arity, meta entry]
         @signature = nil
         @lock = Mutex.new
+        @values = Values::Store.new(alive: ->(app) { !::Asterism.apps(app).empty? })
       end
 
+      attr_reader :values
+
       def run
         @server = ::MCP::Server.new(name: "asterism", version: ::Asterism::VERSION, instructions: INSTRUCTIONS,
                                     tools: read_tools)
         @transport = ::MCP::Server::Transports::StdioTransport.new(@server)
         @server.transport = @transport
+        remember_values
         refresh
         @log.puts "asterism mcp: #{@net.node_id}/#{@net.app}; #{@call_tools.size} call tools" \
                   "#{@allow.empty? ? ' (no --allow: read-only)' : ''}"
@@ -59,6 +68,16 @@ module Asterism
         @refresher&.kill
       end
 
+      # From now on, the puts on the applications' own keys (asterism/**
+      # does not match @profile and @status), and the applications that
+      # leave (their values are marked).
+      def remember_values
+        @net.session.subscribe("#{Values::PREFIX}**", depth: 1024) { |s| @values.put(s.key, s.payload) }
+        @net.session.liveliness_watch("#{Values::PREFIX}*/*", depth: 1024) do |key, alive|
+          @values.left(key.delete_prefix(Values::PREFIX)) unless alive
+        end
+      end
+
       # ------------------------------------------------------------ the list
 
       def refresh_loop
@@ -153,10 +172,46 @@ module Asterism
                 (node.nil? || node == n) && (app.nil? || app == a)
               end
             end
+          end,
+          ::MCP::Tool.define(
+            name: "asterism_values",
+            description: VALUES_DOC,
+            input_schema: {
+              properties: {
+                pattern: { type: "string",
+                           description: "keys as node/app/object/more, with * (one part) and ** (any parts); " \
+                                        "default ** (every key). A key always has a part after the object: " \
+                                        "games/games/othello1/** or games/*/*/state, not games/games/othello1" },
+                wait: { type: "number",
+                        description: "seconds (at most #{Values::Store::MAX_WAIT}) to wait for the first put " \
+                                     "that matches when none has come yet; default 0 (answer now)" }
+              }
+            },
+            annotations: { read_only_hint: true }
+          ) do |server_context:, pattern: "**", wait: 0|
+            bridge.answer { bridge.values.answer(pattern, wait: wait) }
+          rescue ArgumentError => e
+            bridge.error(e.message)
           end
         ]
       end
 
+      VALUES_DOC = "The latest value each application put on its own keys (asterism/<node>/<app>/<object>/<more>: " \
+                   "a game table's state, a log), as this server received them: {\"since\", \"values\": " \
+                   "[{\"key\", \"value\", \"t\", \"age_s\", \"app\", \"bytes\", \"format\"}]}. " \
+                   "A put comes only when the value changes, and this server remembers only what it received " \
+                   "since it started (since): a key that has not been put since then is not listed. Give wait " \
+                   "(seconds) to wait for the first put that matches when none has come yet (a quiet table, " \
+                   "just after the start). age_s: seconds since it came. app: alive; gone (the application is " \
+                   "not on the network now: this is its last value, not the present); restarted (it left and " \
+                   "came back after this value). value: MessagePack or JSON as it is, text as a string; a " \
+                   "value whose JSON is longer than #{Values::Store::VALUE_CUT} bytes is cut (truncated: " \
+                   "true, value: the start of its JSON text). It keeps at most #{Values::Store::MAX_KEYS} keys " \
+                   "(those received longest ago are forgotten first) and lists at most " \
+                   "#{Values::Store::MAX_ANSWER} (more: how many it left out). Nothing came: the note says so " \
+                   "(not put since the start, or the router does not let this server read it). The statuses " \
+                   "(@status) are asterism_status's."
+
       def objects(pattern)
         paths = @survey.objects(pattern)
         metas = @survey.metas(paths)

data/lib/asterism/cli/nouns.rb

@@ -0,0 +1,493 @@
+# The noun-verb commands of the command line (node, app, object, status:
+# lib/asterism/cli.rb's NOUNS), `completion` and the hidden `__complete`
+# (lib/asterism/cli/complete.rb).
+module Asterism
+  class CLI
+    # ------------------------------------------------------------ node
+
+    def cmd_node_list(_rest)
+      connect do |_net, sv|
+        names = sv.nodes
+        structured? ? emit(names) : names.each { @out.puts paint(_1, :node) }
+      end
+      0
+    end
+
+    def cmd_node_info(rest)
+      node = rest.shift
+      raise ArgumentError, "node info: which node? (asterism node info NODE)" unless node && !node.empty?
+      raise ArgumentError, "node info: NODE is a node's name (no /)" if node.include?("/")
+      code = 0
+      connect do |_net, sv|
+        entry = sv.tree(node: node).first
+        if entry.nil?
+          @err.puts "asterism: no node #{node} is visible"
+          code = 1
+        elsif structured?
+          emit(entry)
+        else
+          @out.puts paint(entry["node"], :node)
+          if entry["profile"]
+            pr = entry["profile"].except("icon")
+            Text.wrap(pr.map { |k, v| Text.pair(k, v) }, style.width, first: "  #{paint('profile:', :note)} ",
+                                                                       rest: "    ", break_long: false)
+                .each { @out.puts _1 }
+          end
+          entry["apps"].each { |a| app_block(a["app"], a, 2) }
+        end
+      end
+      code
+    end
+
+    # ------------------------------------------------------------ app
+
+    def cmd_app_list(_rest)
+      connect do |_net, sv|
+        names = sv.apps
+        structured? ? emit(names) : names.each { @out.puts paint_path(_1) }
+      end
+      0
+    end
+
+    def cmd_app_info(rest)
+      node, app = app_path!(rest, "app info").split("/")
+      code = 0
+      connect do |_net, sv|
+        a = sv.tree(node: node, app: app).first&.dig("apps")&.find { _1["app"] == app }
+        if a.nil?
+          @err.puts "asterism: no application #{node}/#{app} is visible"
+          code = 1
+        elsif structured?
+          emit({ "node" => node }.merge(a))
+        else
+          app_block("#{node}/#{app}", a, 0)
+        end
+      end
+      code
+    end
+
+    # ------------------------------------------------------------ object
+
+    def cmd_object_list(rest)
+      pattern = rest.shift || "**"
+      connect do |_net, sv|
+        paths = sv.objects(pattern)
+        structured? ? emit(paths) : paths.each { @out.puts paint_path(_1) }
+      end
+      0
+    end
+
+    def cmd_object_info(rest)
+      path = rest.shift
+      unless path && path.split("/", -1).size == 3 && path.split("/").none? { _1.empty? || _1.include?("*") }
+        raise ArgumentError, "object info: PATH is node/app/object (a pattern: asterism object list PATTERN)"
+      end
+      code = 0
+      connect do |_net, sv|
+        if sv.objects(path).empty?
+          @err.puts "asterism: no object #{path} is visible"
+          code = 1
+          next
+        end
+        methods = sv.metas([path])[path]
+        if structured?
+          h = { "path" => path, "methods" => methods }
+          h["doc"] = sv.object_doc(path) if sv.object_doc(path)
+          emit(h)
+        else
+          object_entry(path, methods, sv.object_doc(path))
+        end
+      end
+      code
+    end
+
+    def cmd_object_find(rest)
+      want = rest.shift
+      raise ArgumentError, "object find: which method? (asterism object find METHOD; * as a wildcard)" unless want
+      found = []
+      connect do |_net, sv|
+        paths = sv.objects
+        metas = sv.metas(paths)
+        paths.each do |p|
+          ms = (metas[p] || []).select { File.fnmatch?(want, _1["name"]) }
+          found << { "path" => p, "methods" => ms } unless ms.empty?
+        end
+        structured? ? emit(found) : found.each { @out.puts paint_path(_1["path"]) }
+      end
+      0
+    end
+
+    # The next value the application puts on its own keys (PATH/KEY: a put
+    # is kept nowhere, so it waits for one; --timeout, 5.0 s).
+    def cmd_object_get(rest)
+      pattern = put_pattern!(rest, "object get")
+      wait = @opts[:put_timeout] || 5.0
+      raise ArgumentError, "--timeout: more than 0" unless wait.positive?
+      code = 0
+      connect do |net, _sv|
+        q = Queue.new
+        net.session.subscribe(Values.key_expr(pattern), depth: 16) { |s| q << [s.key, s.payload, Time.now] }
+        got = q.pop(timeout: wait)
+        if got.nil?
+          @err.puts nothing_came(pattern, wait)
+          code = 1
+          next
+        end
+        e = Values.entry(*got)
+        if structured?
+          emit(e)
+        else
+          put_lines(got[2], e, nil).each { @out.puts _1 }
+        end
+      end
+      code
+    end
+
+    # The values the application puts on its own keys, as they come: the
+    # text shows a key's value whole the first time (and always with
+    # --raw), then what changed; -o json / yaml each put whole.
+    def cmd_object_echo(rest)
+      pattern = put_pattern!(rest, "object echo")
+      code = 0
+      connect do |net, _sv|
+        q = Queue.new
+        net.session.subscribe(Values.key_expr(pattern), depth: 256) { |s| q << [s.key, s.payload, Time.now] }
+        seen = 0
+        last = {}
+        until_stopped(net) do |left|
+          got = q.pop(timeout: [left || 0.2, 0.2].min)
+          next unless got
+          seen += 1
+          e = Values.entry(*got)
+          if structured?
+            emit_line(e)
+          else
+            whole = @opts[:raw] || !last.key?(e["key"])
+            old = last[e["key"]]
+            last[e["key"]] = e["value"]
+            lines = whole ? put_lines(got[2], e, nil) : put_lines(got[2], e, old, again: true)
+            lines&.each { @out.puts _1 }
+          end
+          @out.flush
+          break if @opts[:once]
+        end
+        if seen.zero?
+          @err.puts nothing_came(pattern, @opts[:duration])
+          code = 1 if @opts[:once]
+        end
+      end
+      code
+    end
+
+    # ------------------------------------------------------------ status
+
+    def cmd_status_get(rest)
+      path = app_path!(rest, "status get")
+      code = 0
+      connect do |_net, sv|
+        st = sv.statuses([path])[path]
+        if st.nil?
+          @err.puts no_status(path)
+          code = 1
+        elsif structured?
+          emit(json_safe(st))
+        else
+          Text.status_lines(json_safe(st), style.width).each { @out.puts _1 }
+        end
+      end
+      code
+    end
+
+    # The status, then each change as it comes (the text: what changed, as
+    # watch tells it); --once: the status now, once.
+    def cmd_status_echo(rest)
+      path = app_path!(rest, "status echo")
+      code = 0
+      connect do |net, sv|
+        q = Queue.new
+        subscribe_status(net, path) { |st| q << [Time.now, st] } unless @opts[:once]
+        st = sv.statuses([path])[path]
+        if st
+          echo_event(Time.now, path, st, true)
+        elsif @opts[:once]
+          @err.puts no_status(path)
+          code = 1
+        end
+        next if @opts[:once]
+
+        until_stopped(net) do |left|
+          got = q.pop(timeout: [left || 0.2, 0.2].min)
+          echo_event(got[0], path, got[1], false) if got
+        end
+      end
+      code
+    end
+
+    # How often the status changes: every --period, when a change came, the
+    # average rate and the intervals (Hz).
+    def cmd_status_hz(rest)
+      path = app_path!(rest, "status hz")
+      raise ArgumentError, "--window: 1 or more" unless @opts[:window].positive?
+      raise ArgumentError, "--period: more than 0" unless @opts[:period].positive?
+      connect do |net, sv|
+        hz = Hz.new(window: @opts[:window])
+        lock = Mutex.new
+        subscribe_status(net, path) { |st| lock.synchronize { hz.put(st) } }
+        st = sv.statuses([path])[path]
+        lock.synchronize { hz.seed(st) } if st
+        @err.puts "asterism: #{path}: counting the status's changes (Ctrl-C to stop)" unless structured?
+        nxt = now + @opts[:period]
+        until_stopped(net) do |_left|
+          sleep 0.05
+          next if now < nxt
+          nxt += @opts[:period]
+          s = lock.synchronize { hz.report }
+          next unless s
+          if structured?
+            emit_line({ "t" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"), "path" => path }.merge(s))
+          else
+            Hz.text(s).each { @out.puts _1 }
+          end
+          @out.flush
+        end
+      end
+      0
+    end
+
+    # ------------------------------------------------------------ completion
+
+    def cmd_completion(rest)
+      case rest.shift
+      when "bash" then @out.write(Complete::BASH)
+      when "zsh" then @out.write(Complete::ZSH)
+      else raise ArgumentError, "completion: bash or zsh (source <(asterism completion bash))"
+      end
+      0
+    end
+
+    # The candidates for the word being completed, one a line. The words
+    # come as arguments (the last one the word being completed), after
+    # "--"; or (--bash LINE) as bash's line up to the cursor.
+    def cmd_complete(argv)
+      bash = argv.first == "--bash"
+      words = if bash
+                Complete.split_line(argv[1].to_s)
+              else
+                argv.first == "--" ? argv.drop(1) : argv
+              end
+      words = [""] if words.empty?
+      @complete_words = words
+      cands = Complete.new(self, CompleteSource.new(self, words)).candidates(words)
+      cands = Complete.bash_trim(cands, words.last) if bash && cands != [Complete::FILES]
+      cands.each { @out.puts _1 }
+      @out.flush
+      # A connection still trying past the budget is left behind: the
+      # process ends without waiting for it.
+      Process.exit!(0) if @complete_abandoned
+      0
+    end
+
+    # What __complete asks the network for, through the cache: the names
+    # (the tokens) and an object's methods (its meta).
+    class CompleteSource
+      def initialize(cli, words)
+        @cli = cli
+        @words = words
+      end
+
+      def names
+        cached("names") do
+          @cli.complete_fetch { |sv| { "apps" => sv.apps, "objects" => sv.objects } }
+        end
+      end
+
+      def methods(path)
+        cached("methods #{path}") do
+          @cli.complete_fetch { |sv| sv.metas([path])[path]&.map { _1["name"] } }
+        end
+      end
+
+      def all_methods
+        cached("methods") do
+          @cli.complete_fetch { |sv| sv.metas(sv.objects).values.flatten.map { _1["name"] }.uniq.sort }
+        end
+      end
+
+      private
+
+      def cached(entry, &blk)
+        net = @cli.complete_network(@words)
+        return nil if net.none?
+        dir = Complete::Cache.dir(@cli.env)
+        return blk.call unless dir
+        Complete::Cache.new(dir: dir, network: net).fetch(entry, &blk)
+      end
+    end
+
+    attr_reader :env
+
+    # Where the network is for __complete: the options among the words,
+    # else the environment (network). [router, credentials (its full path),
+    # peer]
+    def complete_network(words)
+      words.each_cons(2) do |a, b|
+        case a
+        when "--router" then @opts[:router] = b
+        when "--credentials" then @opts[:credentials] = b
+        when "--peer" then @opts[:peer] = b
+        end
+      end
+      r, c, pr = network
+      [r, c && File.expand_path(c), pr]
+    end
+
+    # Connects for at most Complete::BUDGET seconds and yields the Survey;
+    # the block's value, or nil when the network did not answer in time.
+    def complete_fetch
+      @opts[:settle] = 0.6
+      @opts[:timeout] = 0.6
+      out = Queue.new
+      th = Thread.new do
+        err = @err
+        @err = File.open(File::NULL, "w")
+        begin
+          connect { |_net, sv| out << yield(sv) }
+        rescue StandardError, ScriptError
+          out << nil
+        ensure
+          @err = err
+        end
+      end
+      v = out.pop(timeout: Complete::BUDGET)
+      if v.nil? && th.alive?
+        @complete_abandoned = true
+        return nil
+      end
+      th.join(0.5) || (@complete_abandoned = true)
+      v
+    end
+
+    # ------------------------------------------------------------ helpers
+
+    def app_path!(rest, what)
+      path = rest.shift
+      ok = path && path.split("/", -1).size == 2 && path.split("/").none? { _1.empty? || _1.include?("*") }
+      raise ArgumentError, "#{what}: which application? (asterism #{what} NODE/APP)" unless ok
+      path
+    end
+
+    # PATH (node/app/object, * for a part) and KEY (the rest, ** by
+    # default) as one pattern.
+    def put_pattern!(rest, what)
+      path = rest.shift
+      key = rest.shift || "**"
+      parts = path.to_s.split("/", -1)
+      unless parts.size == 3 && parts.none? { _1.empty? || (_1.include?("*") && _1 != "*") }
+        raise ArgumentError, "#{what}: PATH is node/app/object (* for a part), then KEY (asterism #{what} " \
+                             "games/games/othello1 state)"
+      end
+      Values.check_pattern!("#{path}/#{key}")
+    end
+
+    def nothing_came(pattern, seconds)
+      "asterism: nothing came on #{pattern}#{seconds ? " in #{format('%g', seconds)} s" : ''} " \
+        "(the router does not let this node read it, or it has not changed)"
+    end
+
+    # The lines of one put received at t: the time, the key and the value
+    # whole; again (the key's value before was old): a line for each thing
+    # that changed in a Hash, the value whole otherwise (nil: no change).
+    def put_lines(t, e, old, again: false)
+      head = "#{paint(t.strftime('%H:%M:%S.%L'), :time)} "
+      v = e["value"]
+      if again && old.is_a?(Hash) && v.is_a?(Hash)
+        changes = Text.status_diff(old, v)
+        return nil if changes.empty?
+        return changes.map { |c| "#{head}#{paint(e['key'], :object)} #{change_text(c)}" }
+      end
+      return nil if again && old == v
+      first = "#{head}#{paint(e['key'], :object)}"
+      return ["#{first} #{Text.inline(v)}"] unless v.is_a?(Hash)
+      [first, *Text.status_lines(v, style.width, Text.width(head))]
+    end
+
+    def no_status(path)
+      "asterism: no status from #{path} (not there, no status, or no answer in time)"
+    end
+
+    # node/app[/object] painted part by part.
+    def paint_path(path)
+      parts = path.split("/")
+      roles = %i[node app object]
+      parts.each_with_index.map { |p, i| paint(p, roles[i] || :object) }.join(paint("/", :note))
+    end
+
+    # An application (a tree's entry) under its name: its status and its
+    # objects (how many methods, and the object's description).
+    def app_block(name, a, indent)
+      pad = " " * indent
+      @out.puts "#{pad}#{paint(name, :app)}"
+      status_block(a, indent + 2)
+      return if a["objects"].empty?
+      @out.puts "#{pad}  #{paint('objects:', :note)}"
+      a["objects"].each do |o|
+        ms = o["methods"]
+        @out.puts "#{pad}    #{paint(o['name'], :object)}  #{paint(ms ? count(ms.size, 'method') : '(no meta)', :note)}"
+        Text.wrap_text(o["doc"], style.width, first: "#{pad}      ").each { @out.puts _1 } if o["doc"]
+      end
+    end
+
+    # The status's puts of one application, cleaned (Status.parse).
+    def subscribe_status(net, path)
+      net.session.subscribe("asterism/#{path}/@status") do |sample|
+        got = ::Asterism::Status.parse(sample.key, sample.payload)
+        yield got[2] if got
+      end
+    end
+
+    # Yields until Ctrl-C, --duration or a lost connection (the seconds
+    # left of --duration, or nil).
+    def until_stopped(net)
+      deadline = @opts[:duration] && (now + @opts[:duration])
+      loop do
+        left = deadline && (deadline - now)
+        break if left && left <= 0
+        break unless net.connected?
+        yield left
+      end
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # One record of status echo: JSON / YAML, or the text (the status whole
+    # the first time, then a line for each change).
+    def echo_event(t, path, status, first)
+      status = json_safe(status)
+      if structured?
+        h = { "t" => t.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"), "path" => path, "status" => status }
+        h["now"] = true if first
+        emit_line(h)
+      else
+        text = echo_text(t, path, status, first)
+        @out.puts text if text
+      end
+      @out.flush
+    end
+
+    # The text of one record of status echo (nil: no change).
+    def echo_text(t, path, status, first)
+      head = "#{paint(t.strftime('%H:%M:%S.%L'), :time)} "
+      old = @echo_last
+      @echo_last = status
+      if first || !old.is_a?(Hash) || !status.is_a?(Hash)
+        lines = Text.status_lines(status, style.width, Text.width(head))
+        return "#{head}#{paint(path, :app)}#{paint(' (now)', :note) if first}\n#{lines.join("\n")}"
+      end
+      changes = Text.status_diff(old, status)
+      return nil if changes.empty?
+      changes.map { |c| "#{head}#{change_text(c)}" }.join("\n")
+    end
+  end
+end

data/lib/asterism/cli/survey.rb

@@ -115,10 +115,12 @@ module Asterism
 
       # The tree: [{"node", "profile", "apps" => [{"app", "status",
       # "objects" => [{"name", "methods"}]}]}]. meta: false leaves the
-      # methods out (no meta gets).
-      def tree(meta: true)
-        objs = objects
-        app_list = apps
+      # methods out (no meta gets); node: (and app:) narrow it to one node
+      # (one application).
+      def tree(meta: true, node: nil, app: nil)
+        scope = node && "#{node}/#{app || '*'}"
+        objs = scope ? objects("#{scope}/*") : objects
+        app_list = scope ? apps(scope) : apps
         threads = []
         node_list = (app_list.map { _1.split("/")[0] } + objs.map { _1.split("/")[0] }).uniq
         threads << Thread.new { profiles(node_list) }