flor 0.14.0 → 0.15.0

data/lib/flor/punit/signal.rb

@@ -1,5 +1,59 @@
 
 class Flor::Pro::Signal < Flor::Procedure
+  #
+  # Used in conjuction with "on".
+  #
+  # An external (or internal) agent may send a signal to an execution and the
+  # execution may have a "on" handler for it.
+  #
+  # For example, imagine an execution with a sub part that checks every day
+  # at noon and closes cases that are over a certain date:
+  #
+  # ```
+  # on 'close'
+  #   # close the case and then cancel main part...
+  #   cancel ref: 'main'
+  #
+  # every 'day at noon'
+  #   signal 'close' if f.date_to < today
+  #
+  # sequence tag: 'main'
+  #   # main part ...
+  # ```
+  #
+  # The "every day at noon" sub part could be replaced by a signal emitted by
+  # a Ruby script triggered by a cron daemon, thus going from internal agent
+  # to external agent.
+  #
+  # The `Flor::Unit` class has a `#signal` method handy for that:
+  # ```ruby
+  # flor_unit.signal('close', exid: execution_id)
+  # ```
+  # It accepts `exid:` and `payload:` messages.
+  #
+  # ## signal payloads
+  #
+  # The payload at the point of signalling is transmitted over to the
+  # receiving "on" or "trap".
+  #
+  # ```
+  # set f.a 'A'
+  # signal 'close'
+  #   set f.b 'B'
+  #   [ 0 1 2 ]
+  # set f.c 'C'
+  # ```
+  # passes `{ 'ret' => [ 0, 1, 2 ], 'a' => 'A', 'b' => 'B' }` as payload
+  # to any intercepting "on" or "trap" (`c` is not passed).
+  #
+  # Externally, you can signal with a specific payload thanks to:
+  # ```ruby
+  # flor_unit.signal('close', exid: execution_id, payload: { 'f0' => 'zero' })
+  # ```
+  #
+  # ## see also
+  #
+  # On and trap.
 
   name 'signal'
 

data/lib/flor/punit/sleep.rb

@@ -19,7 +19,7 @@ class Flor::Pro::Sleep < Flor::Procedure
   def receive_last
 
     t = att('for', nil)
-    fail ArgumentError.new("missing a sleep time duration") unless t
+    fail Flor::FlorError.new("missing a sleep time duration", self) unless t
 
     m = wrap('point' => 'receive').first
 

data/lib/flor/punit/task.rb

@@ -43,11 +43,11 @@ class Flor::Pro::Task < Flor::Procedure
     wrap(
       'point' => 'task',
       'exid' => exid, 'nid' => nid,
+      'tags' => list_tags,
       'tasker' => tasker,
       'taskname' => taskname,
       'attl' => attl, 'attd' => attd,
       'payload' => determine_payload)
-#.tap { |x| pp x.first }
   end
 
   def cancel
@@ -59,6 +59,7 @@ class Flor::Pro::Task < Flor::Procedure
     wrap(
       'point' => 'detask',
       'exid' => exid, 'nid' => nid,
+      'tags' => list_tags,
       'tasker' => att(nil),
       'attl' => attl, 'attd' => attd,
       'payload' => determine_payload)
@@ -66,6 +67,8 @@ class Flor::Pro::Task < Flor::Procedure
 
   protected
 
+  # Returns an array attribute list / attribute dictionary.
+  #
   def determine_atts
 
     attl, attd = [], {}

data/lib/flor/punit/trap.rb

@@ -1,17 +1,186 @@
 
-# # trap
-#
-# ## range:/scope:
-# * subnid (default)
-# * execution/exe
-# * domain
-# * subdomain
-#
-# ## bind:
-# * parent (default)
-# * root
-#
+# Would it be worth the pain implementing bind:?
+
 class Flor::Pro::Trap < Flor::Procedure
+  #
+  # Watches the messages emitted in the execution and reacts when
+  # a message matches certain criteria.
+  #
+  # Once the trap is set (once the execution interprets its branch), it
+  # will trigger for any matching message, unless the `count:` attribute
+  # is set.
+  #
+  # When the execution terminates, the trap is removed as well.
+  #
+  # By default, the observation range is the execution, only messages
+  # in the execution where the trap was set are considered.
+  # The trap can be extended via the `range:` attribute.
+  #
+  # "trap" triggers a function, while "on" triggers a block.
+  #
+  # ## the point: criterion
+  #
+  # The simplest thing to trap is a 'point'. Here, the trap is set for
+  # any message whose point is 'terminated':
+  # ```
+  # sequence
+  #   trap 'terminated'
+  #     def msg \ trace "terminated(f:$(msg.from))"
+  #   trace "here($(nid))"
+  #     # OR
+  # #sequence
+  # #  trap 'terminated'
+  # #    def msg \ trace "terminated(f:$(msg.from))"
+  # #  trace "here($(nid))"
+  # ```
+  #
+  # ## the heap: criterion
+  #
+  # Given a procedure like `sequence`, `concurrence` or `apply`, trigger
+  # a piece of code each time the procedure receives the "execute" or the
+  # "receive" message.
+  #
+  # ```
+  # trap heap: 'sequence'
+  #   def msg
+  #     trace "$(msg.point)-$(msg.tree.0)-$(msg.nid)<-$(msg.from)"
+  # sequence
+  #   noret _
+  # #
+  # # will trace:
+  # #  0:execute-sequence-0_1<-0
+  # #  1:receive--0_1<-0_1_0
+  # #  2:receive--0<-0_1
+  # ```
+  #
+  # ## the heat: criterion
+  #
+  # While `heap:` filters on the actual flor procedure names, `heat:` is
+  # looser, it catches whatever stands "at the beginning of the flor line".
+  # It's useful to catch function calls.
+  #
+  # ```
+  # trap heat: 'fun0'
+  #   def msg
+  #     trace "t-$(msg.tree.0)-$(msg.nid)"
+  # define fun0
+  #   trace "c-fun0-$(nid)"
+  # sequence
+  #   fun0 _
+  #   fun0 # not a call
+  #
+  # # will trace:
+  # # 0:t-fun0-0_2_0
+  # # 1:c-fun0-0_1_1_0_0-2
+  # # 2:t--0_2_0
+  # # 3:t--0_2_0
+  # # 4:t-fun0-0_2_1
+  # ```
+  #
+  # `heat:` accepts strings or regular expressions:
+  #
+  # ```
+  # trap heat: [ /^fun\d+$/ 'funx' ]
+  #   def msg \ trace "t-$(msg.tree.0)-$(msg.nid)"
+  # ```
+  #
+  # ## the tag: criterion
+  #
+  # Traps one or multiple tags. Default to trapping on "entered". May trap
+  # leaving tags with `point: 'left'` or any with
+  # `point: [ 'entered', 'left' ]`.
+  #
+  # ```
+  # trap tag: 'x'
+  #   def msg
+  #     trace "$(msg.tags.-1)-$(msg.point)"
+  # # ...
+  # sequence tag: 'x'
+  #   trace 'c'
+  #
+  # # will trace "x-entered" and "c"
+  # ```
+  #
+  # ## the signal: criterion
+  #
+  # `signal:` traps signals directed at the execution. Signals are
+  # directly
+  # ```
+  # trap signal: 'S0'
+  #   def msg
+  #     trace "S0"
+  # # ...
+  # signal 'S0'
+  # ```
+  #
+  # Note that it's OK to trap all signals, whatever their name, directed at
+  # the execution by using `point: 'signal'`, as in:
+  # ```
+  # trap point: 'signal'
+  #   def msg
+  #     trace "caught signal '$(sig)'"
+  # ```
+  #
+  # [on](on.md) is a macro that turns
+  # ```
+  # on 'rejected'
+  #   trace "execution received signal $(sig)"
+  # ```
+  # into
+  # ```
+  # trap signal: 'rejected'
+  #   def msg
+  #     trace "execution received signal $(sig)"
+  # ```
+  # Please note how "on" accepts a block while "trap" accepts a function.
+  #
+  # ## the range: limit
+  #
+  # The range limit determines what is the range, or scope of the trap.
+  # By default the trap only care about nodes below its parent. In other words,
+  # the trap binds itself to its parent and observes the messages occuring
+  # in the execution in the branch of nodes whose root is the parent.
+  #
+  # The possible values for `range:` are:
+  # * 'subnid' (default)
+  # * 'execution'
+  # * 'domain'
+  # * 'subdomain'
+  #
+  # With 'execution', the trap observes all the messages emitted within the
+  # same execution.
+  #
+  # With 'domain', all the messages in all the execution of the same domain are
+  # observed. For example,
+  # ```
+  # trap point: 'signal', domain: 'net.acme'
+  #   def msg \ trace "signal '$(sig)' caught"
+  # ```
+  # once set, will be triggered for each signal received by an execution in the
+  # 'net.acme' domain.
+  #
+  # Likewise,
+  # ```
+  # trap point: 'signal', subdomain: 'org.acme'
+  #   def msg \ trace "signal '$(sig)' caught"
+  # ```
+  # Will trap all signals in the domain "org.acme" and its subdomains,
+  # (org.acme.accounting, org.acme.engineering, org.acme.whatever.x.y.z, ...)
+  #
+  #
+  # ## the count: limit
+  #
+  # ```
+  # trap tag: 'x' count: 2
+  #   # ...
+  # ```
+  # will trigger when the execution enters the tag 'x', but will trigger only
+  # twice.
+  #
+  #
+  # ## see also
+  #
+  # On and signal.
 
   name 'trap'
 
@@ -40,9 +209,15 @@ class Flor::Pro::Trap < Flor::Procedure
     points = att_a(nil, nil) unless points || tags
     points = [ 'entered' ] if tags && ! points
 
+    att_a('sig', 'signal', 'signals', [])
+      .each { |sig| (points ||= []) << 'signal'; (names ||= []) << sig }
+
+    points = points.uniq if points
+    names = names.uniq if names
+
     msg =
       if fun
-        apply(fun, [], tree[2], false).first
+        apply(fun, [], tree[2], anid: false).first
       else
         wrap_reply.first
       end

data/lib/flor/tools/shell.rb

@@ -1,8 +1,10 @@
 
+require 'io/console'
 require 'terminal-table'
 
 require 'flor'
 require 'flor/unit'
+require 'flor/tools/shell_out'
 
 
 module Flor::Tools
@@ -25,6 +27,8 @@ module Flor::Tools
       prepare_hooks
 
       @hook = 'on'
+      @mute = false
+      @paging = true
 
       @unit.start
 
@@ -35,7 +39,9 @@ module Flor::Tools
 
       @c = Flor.colours({})
 
-      if argv.any?
+      load_floshrc
+
+      if argv && argv.any?
         do_eval(argv.join(' '))
       else
         print_header
@@ -47,6 +53,11 @@ module Flor::Tools
 
     protected
 
+    def parse_single_json_value(s)
+
+      Flor::ConfExecutor.interpret_line(s) rescue nil
+    end
+
     def prepare_home
 
       home = File.join(@root, 'home')
@@ -102,15 +113,35 @@ module Flor::Tools
       end
     end
 
+    def load_floshrc
+
+      @mute = true
+
+      [
+        File.join(@root, 'etc/floshrc'),
+        File.join(@root, 'home/.floshrc'),
+        '.floshrc'
+      ].each { |f| (File.readlines(f) rescue []).each { |l| do_eval(l) } }
+
+    ensure
+
+      @mute = false
+    end
+
     def print_header
 
-      puts "flosh - a flor #{Flor::VERSION} shell"
+      git = (' ' + `git log -1`.lines.first.split.last[0, 7]) rescue ''
+      git = "#{@c.yellow}#{git}#{@c.reset}"
+
+      puts "flosh - a flor #{Flor::VERSION}#{git} shell"
     end
 
     def prompt
 
       root = @c.dark_gray(@root + '/')
 
+      time = Time.now.strftime(' %H:%M:%S')
+
       ec = @unit.executions.where(status: 'active').count
       exes = ' ' + @c.yellow("ex#{ec}")
 
@@ -123,13 +154,13 @@ module Flor::Tools
       end
       tas = ta > 0 ? ' ' + @c.yellow("ta#{ta}") : ''
 
-      "#{root}#{exes}#{tis}#{tas} > "
+      "#{root}#{time}#{exes}#{tis}#{tas} > "
     end
 
     def do_eval(line)
 
-      line = line.strip
-      return if line[0, 1] == '#'
+      line = line.match(/\A([^#]*)(#.+)?\n*\z/)[1]
+      return if line == ''
 
       md = line.split(/\s/).first
       cmd = "cmd_#{md}".to_sym
@@ -155,7 +186,6 @@ module Flor::Tools
         line = prompt_and_read
 
         break unless line
-        next if line.strip == ''
 
         do_eval(line)
       end
@@ -166,15 +196,26 @@ module Flor::Tools
     #
     # command helpers
 
+    ALIASES = {}
+
     def self.make_alias(a, b)
 
       define_method("hlp_#{a}") { "alias to #{b.inspect}" }
       alias_method "man_#{a}", "man_#{b}" rescue nil
       alias_method "cmd_#{a}", "cmd_#{b}"
+
+      (ALIASES[b] ||= []) << a
     end
 
-    def fname(line, index=1); line.split(/\s+/)[index]; end
-    alias arg fname
+    def self.is_alias?(c)
+
+      !! ALIASES.values.find { |a| a.include?(c) }
+    end
+
+    def args(line); line.split(/\s+/); end
+    def argc(line); args(line).count; end
+    def arg(line, index=1); args(line)[index]; end
+    alias fname arg
 
     def choose_path(line)
 
@@ -186,9 +227,19 @@ module Flor::Tools
       when /\Ap/
         @payload_path
       when /\At/
+        fail ArgumentError.new("'frag' argument missing") unless b
         Dir[File.join(@root, 'var/tasks/**/*.json')].find { |pa| pa.index(b) }
       when /\Ar/
         @ra_flow_path
+      when /\Ae/
+        exe = lookup_execution(b)
+#p exe
+#pp exe.data
+#puts JSON.pretty_generate(exe.data)
+#puts JSON.dump(exe.data)
+#puts JSON.generate(exe.data, indent: '  ', space: ' ', object_nl: "\n", array_nl: "\n")
+puts Flor.to_d(exe.data, width: true, colours: true)
+fail NotImplementedError
       else
         @flow_path
       end
@@ -232,19 +283,162 @@ module Flor::Tools
         .find { |e| e.data['nodes'][nid] }
 
       fail ArgumentError.new(
-        "found #{exes.count} execution#{exes.count > 1 ? 's' : ''} " +
+        "found #{exes.count} execution#{exes.count != 1 ? 's' : ''} " +
         "matching \"%#{exid}%\", but none with a #{onid.inspect} node"
       ) unless exe
 
       [ exe.exid, nid ]
     end
 
+    def print(o)
+
+      ::Kernel.print(o) unless @mute
+    end
+
+    def puts(o)
+
+      ::Kernel.puts(o) unless @mute
+    end
+
+    def page_puts(s)
+      ::Kernel.puts s
+    end
+    def page_vi(s)
+      IO.popen(
+        @unit.conf['fls_vi'] || 'vi -',
+        mode: 'w'
+      ) { |io| io.write(Flor.decolour(s)) }
+    end
+    def page_more(s)
+      IO.popen(
+        @unit.conf['fls_more'] || 'less -R -N',
+        mode: 'w'
+      ) { |io| io.write(s) }
+    end
+
+    def page(o)
+
+      return if @mute
+
+      s = o.is_a?(String) ? o : o.string
+
+      if @paging == false
+        page_puts(s)
+      elsif @paging == :vi
+        page_vi(s)
+      elsif @paging == :more
+        page_more(s)
+      else
+        if s.lines.to_a.size > IO.console.winsize[0]
+          page_more(s)
+        else
+          page_puts(s)
+        end
+      end
+    end
+
     #
     # the commands
 
+    def hlp_paging
+      %{ sets the paging mode }
+    end
+    def man_paging
+      %{
+        * paging off
+          disable paging, command output will always be output to stdout
+        * paging on
+          enable paging, command output longer than terminal height will be paged
+        * paging vi|vim
+          always page into vim, whatever length, loses the colours
+        * paging more|less
+          always page into vim, whatever length, loses the colours
+      }
+    end
+    def cmd_paging(line)
+
+      @paging =
+        case arg(line)
+        when 'vi', 'vim' then :vi
+        when 'no', 'off', 'false' then false
+        when 'more', 'less' then :more
+        #when 'on', 'true' then true
+        else true
+        end
+      puts "paging set to #{@paging}"
+    end
+
+    def hlp_read
+      %{ reads (pages) a file }
+    end
+    def man_read
+      %{
+        * read filename
+          reads (pages) a file
+      }
+    end
+    def cmd_read(line)
+      page(File.read(arg(line)))
+    end
+
+    def hlp_page
+      %{ pages the output of the remainder of the command line }
+    end
+    def man_page
+      %{
+        * page filepath
+          reads the file and pages it
+        * page command arg0 arg1 ... argN
+          runs `command arg0 arg1 ... argN` and pages its output
+      }
+    end
+    def cmd_page(line, paging=:more)
+
+      current_paging = @paging
+      @paging = paging
+
+      line = line.strip.split(/\s+/, 2)[1]
+
+      if line.nil? || line.empty?
+        do_eval('man page')
+      elsif File.exist?(line) && ! File.directory?(line)
+        page(File.read(line))
+      else
+        do_eval(line)
+      end
+
+    ensure
+
+      @paging = current_paging
+    end
+
+    def hlp_vi
+      %{ runs the remainder of the command line and then edit output in vi }
+    end
+    def man_vi
+      %{
+        * vi filepath
+          reads the file and edits it
+        * vi command arg0 arg1 ... argN
+          runs `command arg0 arg1 ... argN` and opens its output with vi
+      }
+    end
+    def cmd_vi(line)
+      cmd_page(line, :vi)
+    end
+    make_alias('vim', 'vi')
+
     def hlp_launch
       %{ launches a new execution of #{@flow_path} }
     end
+    def man_launch
+      %{
+        * launch
+          launches an execution of the current flow
+        * launch k0: v0, k1: v1, ...
+          launches an execution with the given variables
+      }
+    end
     def cmd_launch(line)
 
       flow = File.read(@flow_path)
@@ -252,6 +446,9 @@ module Flor::Tools
       payload = Flor::ConfExecutor.interpret(@payload_path)
       domain = 'shell'
 
+      vars = Flor::ConfExecutor.interpret_line("\n" + line[6..-1]) rescue {}
+      variables.merge!(vars)
+
       exid = @unit.launch(
         flow, domain: domain, vars: variables, payload: payload)
 
@@ -271,13 +468,16 @@ module Flor::Tools
     end
     def cmd_help(line)
 
+      o = StringIO.new
+
       if cmd = arg(line)
+
         begin
           send("man_#{cmd}").split("\n").collect(&:strip).each do |l|
             if l[0, 1] == '*'
-              puts " #{@c.dg}*#{@c.rs} #{l[1..-1].strip}"
+              o.puts " #{@c.dg}*#{@c.rs} #{l[1..-1].strip}"
             else
-              puts "   #{@c.dark_gray(l)}"
+              o.puts "   #{@c.dark_gray(l)}"
             end
           end
         rescue => err
@@ -286,16 +486,20 @@ module Flor::Tools
 
       else
 
-        puts
-        puts "## available commands:"
-        puts
+        o.puts
+        o.puts "## available commands:"
+        o.puts
         COMMANDS.each do |cmd|
-          print "* #{@c.yellow(cmd)}"
-          if hlp = (send("hlp_#{cmd}") rescue nil); print " - #{hlp.strip}"; end
-          puts
+          o.print "* #{@c.yellow(cmd)}"
+          if hlp = (send("hlp_#{cmd}") rescue nil)
+            o.print " - #{hlp.strip}"
+          end
+          o.puts
         end
-        puts
+        o.puts
       end
+
+      page(o)
     end
     make_alias('h', 'help')
     make_alias('man', 'help')
@@ -324,7 +528,7 @@ module Flor::Tools
     def cmd_parse(line)
 
       source = File.read(@flow_path)
-      tree = Flor::Lang.parse(source, nil, {})
+      tree = Flor.parse(source, nil, {})
 
       case arg(line)
       when 'd', 'raw'
@@ -336,7 +540,7 @@ module Flor::Tools
       when 'p'
         p tree
       else
-        Flor.print_tree(tree, '0', headers: false)
+        puts Flor.tree_to_s(tree, '0', headers: false)
       end
     end
 
@@ -365,20 +569,62 @@ module Flor::Tools
         puts "not found"
       end
     end
+    make_alias('e', 'edit')
+
+    def hlp_cat
+      %{ prints the current flow }
+    end
+    def man_cat
+      %{
+        * cat
+          prints the current flow
+      }
+    end
+    def cmd_cat(line)
+
+      puts "  # #{@flow_path}\n"
+      File.readlines(@flow_path).each { |line| puts "  #{line}" }
+    end
 
     def hlp_conf
-      %{ prints current unit configuration }
+      %{ prints or sets in current unit configuration }
+    end
+    def man_conf
+      %{
+        * conf
+          prints current unit configuration
+        * conf key
+          prints value for a single key
+        * conf key value
+          sets value for key
+      }
     end
     def cmd_conf(line)
-      puts Flor.to_d(@unit.conf, colour: true, indent: 1, width: true)
+
+      key, value = arg(line), (args(line)[2..-1] || []).join(' ')
+
+      if key && @unit.conf.has_key?(key)
+        puts Flor.to_d(
+          { key: @unit.conf[key] }, colour: true, indent: 1, width: true)
+      end
+
+      if key && argc(line) > 2
+        @unit.conf[key] = parse_single_json_value(value)
+        puts "   #{@c.dg}# ==>#{@c.reset}"
+        puts Flor.to_d(
+          { key: @unit.conf[key] }, colour: true, indent: 1, width: true)
+      elsif key
+        # alreay done
+      else
+        page(Flor.to_d(@unit.conf, colour: true, indent: 1, width: true))
+      end
     end
 
     def hlp_t
       %{ prints the file hierarchy for #{@root} }
     end
     def cmd_t(line)
-      puts
-      system("tree -C #{@root}")
+      page(`tree -C #{@root}`)
     end
 
     def hlp_tasks
@@ -394,6 +640,8 @@ module Flor::Tools
     end
     def cmd_tasks(line)
 
+      o = StringIO.new
+
       frag = arg(line)
 
       table = Terminal::Table.new(
@@ -425,33 +673,54 @@ module Flor::Tools
           table.add_row([
             aright(i), tasker, nid, @c.yellow(exid), pl, mt ]) }
 
-      puts table
-      puts "#{tas.count} task#{tas.count > 1 ? 's' : ''}.\n"
+      o.puts table
+      o.puts "#{tas.count} task#{tas.count != 1 ? 's' : ''}.\n"
+
+      page(o)
     end
     make_alias('tas', 'tasks')
 
     def hlp_executions
       %{ lists the executions currently active }
     end
+    def man_executions
+      %{
+        * executions
+          lists all the executions currently active
+        * executions all
+          lists all the executions
+      }
+    end
     def cmd_executions(line)
 
+      o = StringIO.new
+
       exes = @unit.executions
       exes = exes.where(status: 'active') unless arg(line) == 'all'
 
       table = Terminal::Table.new(
         #title: 'executions',
-        headings: %w[ id exid started ],
+        headings: %w[ id exid name started tis status ],
         style: table_style)
       #table.align_column(0, :right)
 
       exes
         .each { |e|
+          vs = e.zero_variables
           table.add_row([
-            aright(e.id), @c.yl(e.exid), e.ctime[0, 19]
+            aright(e.id),
+            @c.yl(e.exid),
+            %w[ execution_name process_name flow_name name ]
+              .collect { |k| vs[k] }.compact.first,
+            e.ctime[0, 19],
+            aright(@unit.timers.where(exid: e.exid, status: 'active').count),
+            e.failed? ? 'failed' : 'running'
           ]) }
 
-      puts table
-      puts "#{exes.count} execution#{exes.count > 1 ? 's' : ''}.\n"
+      o.puts table
+      o.puts "#{exes.count} execution#{exes.count != 1 ? 's' : ''}.\n"
+
+      page(o)
     end
     make_alias('exes', 'executions')
 
@@ -460,6 +729,8 @@ module Flor::Tools
     end
     def cmd_timers(line)
 
+      o = StringIO.new
+
       tis = @unit.timers
       tis = tis.where(status: 'active') unless arg(line) == 'all'
 
@@ -477,8 +748,10 @@ module Flor::Tools
             aright(t.schedule), t.ntime[0, 19]
           ]) }
 
-      puts table
-      puts "#{tis.count} timer#{tis.count > 1 ? 's' : ''}.\n"
+      o.puts table
+      o.puts "#{tis.count} timer#{tis.count != 1 ? 's' : ''}.\n"
+
+      page(o)
     end
     make_alias('tis', 'timers')
 
@@ -508,6 +781,8 @@ module Flor::Tools
         "couldn't find a task matching #{t.inspect}"
       ) unless path
 
+      puts "found task at #{path}"
+
       m = JSON.parse(File.read(path))
       @unit.return(m)
       FileUtils.rm(path)
@@ -530,10 +805,13 @@ module Flor::Tools
       @unit.conf.select! { |k, v| ! k.match(/\Alog_/) }
 
       rest = line.match(/\A[a-z]+(\s+.+)?/)[1]
-      rest = nil if rest && rest.strip == 'off'
-      rest = 'stdout,dbg' if rest && rest.strip == 'on'
+      rest = rest.strip if rest
+      rest = nil if rest && rest == 'off'
+      rest = 'stdout,dbg' if rest && %w[ on 1 ].include?(rest)
+
+      @unit.conf.merge!(Flor::Conf.interpret_flor_debug(debug: rest)) if rest
 
-      @unit.conf.merge!(Flor::Conf.interpret_flor_debug(rest)) if rest
+      cmd_conf('') # display conf
     end
 
     def hlp_hook
@@ -584,39 +862,49 @@ module Flor::Tools
       table
     end
 
+    def lookup_execution(id)
+
+      if id.match(/\A\d+\z/)
+        @unit.executions[id.to_i] ||
+        fail(ArgumentError.new("execution #{id} not found"))
+      else
+        @unit.executions.first(Sequel.like(:exid, "%#{id}%")) ||
+        fail(ArgumentError.new("execution matching \"%#{id}%\" not found"))
+      end
+    end
+
     def detail_execution(id)
 
-      exe =
-        if id.match(/\A\d+\z/)
-          @unit.executions[id.to_i] ||
-          fail(ArgumentError.new("execution #{id} not found"))
-        else
-          @unit.executions.first(Sequel.like(:exid, "%#{id}%")) ||
-          fail(ArgumentError.new("execution matching \"%#{id}%\" not found"))
-        end
+      o = StringIO.new
+
+      exe = lookup_execution(id)
 
       eid = { id: exe.id, exid: exe.exid }.inspect
       con = Flor::Storage.from_blob(exe.values.delete(:content))
       exe.values[:content] = '...'
 
-      puts @c.dg("--- exe #{eid} :")
-      puts h_to_table(exe.values)
-      puts @c.dg("  exe #{eid} content:")
+      o.puts @c.dg("--- exe #{eid} :")
+      o.puts h_to_table(exe.values)
+      o.puts @c.dg("  exe #{eid} content:")
       nodes = con.delete('nodes')
       con['nodes'] = '...'
-      puts indent('  ', h_to_table(con))
-      puts @c.dg("    exe #{eid} content/nodes:")
+      o.puts indent('  ', h_to_table(con))
+      o.puts @c.dg("    exe #{eid} content/nodes:")
       table = Terminal::Table.new(
         headings: %w[ nid data ],
         style: table_style.merge(all_separators: true))
       nodes.each do |k, v|
         table.add_row([ k, Flor.to_d(v, colour: true, indent: 0, width: 70) ])
       end
-      puts indent('    ', table)
+      o.puts indent('    ', table)
+
+      page(o)
     end
 
     def detail_timer(id)
 
+      o = StringIO.new
+
       timer = @unit.timers[id.to_i]
 
       fail ArgumentError.new("timer #{id} not found") unless timer
@@ -626,15 +914,33 @@ module Flor::Tools
       con = Flor::Storage.from_blob(timer.delete(:content))
       timer[:content] = '...'
 
-      puts @c.dg("--- timer #{tid} :")
-      puts Flor.to_d(timer, colour: true, indent: 1, width: true)
-      puts @c.dg("--- timer #{tid} content:")
-      puts Flor.to_d(con, colour: true, indent: 1, width: true)
+      o.puts @c.dg("--- timer #{tid} :")
+      o.puts Flor.to_d(timer, colour: true, indent: 1, width: true)
+      o.puts @c.dg("--- timer #{tid} content:")
+      o.puts Flor.to_d(con, colour: true, indent: 1, width: true)
+
+      page(o)
     end
 
     def detail_task(id)
 
-fail NotImplementedError
+      pa = Dir["#{@root}/var/tasks/**/*#{id}*.json"].first
+
+      fail ArgumentError.new("found no task matching #{id}") unless pa
+
+      ta = JSON.load(File.read(pa))
+      tconf = ta['tconf']; ta['tconf'] = '...'
+      payload = ta['payload']; ta['payload'] = '...'
+
+      o = StringIO.new
+      o.puts "#{@c.dg} #\n # path: #{pa}\n ##{@c.reset}"
+      o.puts Flor.to_d(ta, colour: true, indent: 1, width: true)
+      o.puts "#{@c.dg} # tconf:#{@c.reset}"
+      o.puts Flor.to_d(tconf, colour: true, indent: 3, width: true)
+      o.puts "#{@c.dg} # payload:#{@c.reset}"
+      o.puts Flor.to_d(payload, colour: true, indent: 3, width: true)
+
+      page(o)
     end
 
     def hlp_detail
@@ -646,7 +952,7 @@ fail NotImplementedError
           displays full execution information
         * detail ti|timer id
           displays full timer information
-        * detail task frag
+        * detail t|task frag
           displays task
       }
     end
@@ -688,7 +994,7 @@ fail NotImplementedError
     end
     make_alias('can', 'cancel')
 
-    def render_node(t, nid)
+    def render_node(o, t, nid)
 
       ni = nid
       head = t[0]
@@ -703,12 +1009,12 @@ fail NotImplementedError
         rest = @c.green("  <--")
       end
 
-      puts "  #{ni} #{head}#{rest}"
+      o.puts "  #{ni} #{head}#{rest}"
 
       return unless t[1].is_a?(Array)
 
       t[1].each_with_index do |ct, i|
-        render_node(t[1][i], "#{nid}_#{i}")
+        render_node(o, t[1][i], "#{nid}_#{i}")
       end
     end
 
@@ -724,12 +1030,18 @@ fail NotImplementedError
     end
     def cmd_render(line)
 
+      o = StringIO.new
+
       frag = arg(line)
 
       exe =
         @unit.executions.first(Sequel.like(:exid, "%#{frag}%")) ||
-        fail(ArgumentError.new("execution matching \"%#{id}%\" not found"))
-#p exe
+        fail(ArgumentError.new("execution matching \"%#{frag}%\" not found"))
+      o.puts
+      o.puts "  exid:    #{@c.yellow(exe.exid)}"
+      o.puts "  status:  #{@c.yellow(exe.status)}"
+      o.puts
+
       tree = exe.full_tree
       nodes = exe.nodes
 
@@ -752,7 +1064,9 @@ fail NotImplementedError
         end
       end
 
-      render_node(tree, '0')
+      render_node(o, tree, '0')
+
+      page(o)
     end
     make_alias('r', 'render')
 
@@ -776,12 +1090,44 @@ fail NotImplementedError
       puts @c.yellow("re-apply message queued for #{exid} #{nid}")
     end
 
+    def hlp_flosh
+      %{ displays flosh explanation }
+    end
+    def man_flosh
+      %{
+        * flosh
+          displays flosh explanation
+      }
+    end
+    def cmd_flosh(line)
+      page %{
+#{@c.yellow}# flosh#{@c.reset}
+
+Flosh is a flor shell.
+
+It's meant for demonstration purposes, to show how flor works.
+
+Opening a flor shell, starts a flor scheduler pointing to #{@root}
+
+#{@c.yellow}# flosh provided taskers#{@c.reset}
+
+The following names can be used as "nato" taskers: alpha, bravo, charly, delta, fox, foxtrott, golf, echo, and hotel.
+
+Nato taskers simply put their tasks under #{@root}/var/tasks/{tasker-name}/ as JSON files. Those file can be edited with the `edit task {frag}`.
+
+Once edited (or not), a nato tasker task can be returned to flor (to the scheduler) with `return {frag}`.
+      }
+    end
+
     #
-    # use Readline if possible
+    # enumerate commands (for cmd_help)
 
     COMMANDS = self.allocate.methods \
       .select { |m| m.to_s.match(/^cmd_/) }.collect { |m| m[4..-1] }.sort
 
+    #
+    # use Readline if possible
+
     begin
       require 'readline'
       def prompt_and_read