appear 1.0.0

data/lib/appear/revealers.rb

@@ -0,0 +1,183 @@
+require 'appear/service'
+require 'appear/join'
+
+module Appear
+  # stores all the ways we can appear something
+  REVEALERS = []
+
+  # The Revealers are the things that actually are in charge of revealing a PID
+  # in a terminal emulator. They consume the other services to do the real
+  # work.
+  module Revealers
+    # extend to implement more revealers
+    class BaseRevealer < Service
+      def call(tree)
+        target, *rest = tree
+        if supports_tree?(target, rest)
+          return reveal_tree(tree)
+        end
+      end
+
+      # TODO
+      def reveal_tree(tree)
+        raise "not implemented"
+      end
+
+      # appear the first process in this process tree.
+      # should return nil if no action was performed.
+      # otherwise, return true.
+      def supports_tree?(target, rest)
+        raise "not implemented"
+      end
+
+      def self.register!
+        Appear::REVEALERS.push(self)
+      end
+    end
+
+    class MacRevealer < BaseRevealer
+      delegate :join_via_tty, :lsof
+      require_service :mac_os
+
+      def panes
+        raise "not implemented"
+      end
+
+      def reveal_hit(hit)
+        raise "not implemented"
+      end
+
+      def reveal_tree(tree)
+        hits = join_via_tty(tree, panes)
+        actual_hits = hits.uniq {|hit| hit.tty }.
+          reject {|hit| services.mac_os.has_gui?(hit.process) }.
+          each { |hit| reveal_hit(hit) }
+
+        return actual_hits.length > 0
+      end
+
+      # TODO: read the bundle identifier somehow, but this is close enough.
+      # or get the bundle identifier and enhance the process lists with it?
+      def has_gui_app_named?(tree, name)
+        tree.any? do |process|
+          process.name == name && services.mac_os.has_gui?(process)
+        end
+      end
+    end
+
+    class Iterm2 < MacRevealer
+      require_service :processes
+
+      def supports_tree?(target, rest)
+        has_gui_app_named?(rest, 'iTerm2')
+      end
+
+      def panes
+        binding.pry
+        pids = services.processes.pgrep('iTerm2')
+        services.mac_os.call_method('iterm2_panes').map do |hash|
+          hash[:pids] = pids
+          OpenStruct.new(hash)
+        end
+      end
+
+      def reveal_hit(hit)
+        services.mac_os.call_method('iterm2_reveal_tty', hit.tty)
+      end
+    end
+
+    class TerminalApp < MacRevealer
+      require_service :processes
+
+      def supports_tree?(target, rest)
+        has_gui_app_named?(rest, 'Terminal')
+      end
+
+      def panes
+        pids = services.processes.pgrep('Terminal.app')
+        services.mac_os.call_method('terminal_panes').map do |hash|
+          hash[:pids] = pids
+          OpenStruct.new(hash)
+        end
+      end
+
+      def reveal_hit(hit)
+        # iterm2 runs a non-gui server process. Because of implementation
+        # details of MacOs#has_gui?, we don't *techinically* have to worry
+        # about this, but we should in case I ever implement real mac
+        # gui-or-not lookup.
+        return if hit.process.name == 'iTerm2'
+        services.mac_os.call_method('terminal_reveal_tty', hit.tty)
+      end
+    end
+
+    class Tmux < BaseRevealer
+      # TODO: cache services.tmux.panes, services.tmux.clients for this revealer?
+      require_service :tmux
+      require_service :lsof
+      require_service :revealer
+      require_service :processes
+
+      def supports_tree?(target, rest)
+        rest.any? { |p| p.name == 'tmux' }
+      end
+
+      def reveal_tree(tree)
+        relevent_panes = Join.join(:pid, tree, services.tmux.panes)
+        relevent_panes.each do |pane|
+          log("#{self.class.name}: revealing pane #{pane}")
+          services.tmux.reveal_pane(pane)
+        end
+
+        # we should also appear the tmux client for this tree in the gui
+        pid = tmux_client_for_tree(tree)
+        if pid
+          services.revealer.call(pid)
+        end
+
+        return relevent_panes.length > 0
+      end
+
+      # tmux does not tell us the PIDs of any of these clients. The only way
+      # to find the PID of a tmux client is to lsof() the TTY that the client
+      # is connected to, and then deduce the client PID, which will be a tmux
+      # process PID that is not the server PID.
+      def tmux_client_for_tree(tree)
+        tmux_server = tree.find {|p| p.name == 'tmux'}
+
+        # join processes on tmux panes by PID.
+        proc_and_panes = Join.join(:pid, services.tmux.panes, tree)
+
+        # Join the list of tmux clients with process_and_pid on :session.
+        # In tmux, every pane is addressed by session_name:window_index:pane_index.
+        # This gives us back a list of all the clients that have a pane that
+        # contains a process in our given process tree.
+        proc_and_clients = Join.join(:session, services.tmux.clients, proc_and_panes)
+
+        # there *should* be only one of these, unless there are two clients
+        # connected to the same tmux session. In that case we just choose one
+        # of the clients.
+        client = proc_and_clients.last
+
+        # at this point it's possible that none of our tree's processes are
+        # alive inside tmux.
+        return nil unless client
+
+        tty_of_client = client[:tty]
+        connections_to_tty = services.lsof.lsofs(
+          [tty_of_client],
+          :pids => services.processes.pgrep('tmux')
+        )[tty_of_client]
+        client_connection = connections_to_tty.find do |conn|
+          (conn.command_name =~ /^tmux/) && (conn.pid != tmux_server.pid)
+        end
+
+        client_connection.pid if client_connection
+      end
+    end
+
+    Iterm2.register!
+    TerminalApp.register!
+    Tmux.register!
+  end
+end

data/lib/appear/runner.rb

@@ -0,0 +1,101 @@
+require 'open3'
+require 'appear/constants'
+require 'appear/service'
+require 'shellwords'
+require 'json'
+
+module Appear
+  # raised when a command we want to run fails
+  class ExecutionFailure < Error
+    attr_reader :command, :output
+    def initialize(command, output)
+      @command = command
+      @output = output
+      super("Command #{command.inspect} failed with output #{output.inspect}")
+    end
+  end
+
+  # Service for executing commands. Better than a mixin everywhere.
+  class Runner < Service
+    # Run a command. Throws an exception if the command fails. Command can
+    # either be a string, or an array of command name and parameters.
+    # Returns the combinded STDERR and STDOUT of the command.
+    #
+    # @return String
+    def run(command)
+      start = Time.new
+      if command.is_a? Array
+        output, status = Open3.capture2e(*command)
+      else
+        output, status = Open3.capture2e(command)
+      end
+      finish = Time.new
+      log("Runner: ran #{command.inspect} in #{finish - start}s")
+      raise ExecutionFailure.new(command, output) unless status.success?
+      output
+    end
+  end
+
+  # Records every command run to a directory; intended to be useful for later integration tests.
+  class RunnerRecorder < Runner
+    OUTPUT_DIR = MODULE_DIR.join('spec/command_output')
+    INIT_AT = Time.new
+
+    def initialize(*args)
+      super(*args)
+      @command_runs = Hash.new { |h, k| h[k] = [] }
+    end
+
+    def run(command)
+      begin
+        result = super(command)
+        record_success(command, result)
+        return result
+      rescue ExecutionFailure => err
+        record_error(command, err)
+        raise err
+      end
+    end
+
+    private
+
+    def command_name(command)
+      if command.is_a?(Array)
+        File.basename(command.first)
+      else
+        File.basename(command.split(/\s+/).first)
+      end
+    end
+
+    def record_success(command, result)
+      data = {
+          :command => command,
+          :output => result,
+          :status => :success,
+      }
+      record(command, data)
+    end
+
+    def record_error(command, err)
+      data = {
+          :command => command,
+          :output => err.output,
+          :status => :error,
+      }
+      record(command, data)
+    end
+
+    def record(command, data)
+      name = command_name(command)
+      run_index = @command_runs[name].length
+
+      data[:run_index] = run_index
+      data[:record_at] = Time.new
+      data[:init_at] = INIT_AT
+
+      @command_runs[name] << data
+      filename = "#{INIT_AT.to_i}-#{name}-run#{run_index}.json"
+      OUTPUT_DIR.join(filename).write(JSON.pretty_generate(data))
+    end
+  end
+end

data/lib/appear/service.rb

@@ -0,0 +1,65 @@
+require 'ostruct'
+
+module Appear
+  # Dependency-injectable service class. Service will raise errors during
+  # initialization if its dependencies are not met.
+  class BaseService
+    def initialize(given_services = {})
+      req_service_instances = {}
+      self.class.required_services.each do |service|
+        unless given_services[service]
+          raise ArgumentError.new("required service #{service.inspect} not provided to instance of #{self.class.inspect}")
+        end
+
+        req_service_instances[service] = given_services[service]
+      end
+      @services = OpenStruct.new(req_service_instances)
+    end
+
+    # Delegate a method to another service. Declares a dependency on that
+    # service.
+    def self.delegate(method, service)
+      require_service(service)
+      self.send(:define_method, method) do |*args, &block|
+        unless @services.send(service).respond_to?(method)
+          raise NoMethodError.new("Would call private method #{method.inspect} on #{service.inspect}")
+        end
+        @services.send(service).send(method, *args, &block)
+      end
+    end
+
+    # List all the services required by this service class.
+    def self.required_services
+      @required_services ||= []
+
+      if self.superclass.respond_to?(:required_services)
+        @required_services + self.superclass.required_services
+      else
+        @required_services
+      end
+    end
+
+    # Declare a dependency on another service.
+    def self.require_service(name)
+      @required_services ||= []
+
+      return if required_services.include?(name)
+      @required_services << name
+    end
+
+
+    private
+
+    def services
+      @services
+    end
+  end
+
+  # All regular services want to log and output stuff, so they inherit from
+  # here.
+  class Service < BaseService
+    delegate :log, :output
+    delegate :log_error, :output
+    delegate :output, :output
+  end
+end

data/lib/appear/tmux.rb

@@ -0,0 +1,77 @@
+require 'ostruct'
+require 'appear/service'
+
+module Appear
+  # The Tmux service is in charge of interacting with `tmux` processes. It is
+  # used by the Tmux revealer, but could also be used as the building block for
+  # other tmux-related scripts.
+  #
+  # see the man page for tmux if you are curious about what clients, windows,
+  # panes, and sessions are in Tmux world.
+  class Tmux < Service
+    delegate :run, :runner
+
+    def clients
+      ipc([
+        'list-clients',
+        '-F',
+        format_string(
+          :tty => :client_tty,
+          :term => :client_termname,
+          :session => :client_session
+      ),
+      ])
+    end
+
+    def panes
+      panes = ipc([
+        'list-panes',
+        '-a',
+        '-F',
+        format_string(
+          :pid => :pane_pid,
+          :session => :session_name,
+          :window => :window_index,
+          :pane => :pane_index,
+          :command_name => :pane_current_command,
+          :active => :pane_active)
+      ])
+
+      panes.each do |pane|
+        pane.window = pane.window.to_i
+        pane.pid = pane.pid.to_i
+        pane.active = pane.active.to_i != 0
+      end
+
+      panes
+    end
+
+    def reveal_pane(pane)
+      ipc(['select-pane', '-t', "#{pane.session}:#{pane.window}.#{pane.pane}"])
+      ipc(['select-window', '-t', "#{pane.session}:#{pane.window}"])
+    end
+
+    private
+
+    def ipc(args)
+      res = run(['tmux'] + args)
+      res.lines.map do |line|
+        info = {}
+        line.strip.split(' ').each do |pair|
+          key, *value = pair.split(':')
+          info[key.to_sym] = value.join(':')
+        end
+        OpenStruct.new(info)
+      end
+    end
+
+    def format_string(spec)
+      result = ""
+      spec.each do |key, value|
+        part = ' ' + key.to_s + ':#{' + value.to_s + '}'
+        result += part
+      end
+      result
+    end
+  end
+end

data/tools/macOS-helper.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env osascript -l JavaScript
+// osascript is a OS X-native scripting tool that allows scripting the system.
+// Usually scripts are written in AppleScript, but AppleScript really sucks, so
+// we're going to write Javascript instead.
+//
+// osascript is interesting because it can inspect the state of the OS X gui,
+// including enumerating windows and inspecting window contents, if
+// accessibility is enabled in System Preferences.
+//
+// documentation:
+// https://developer.apple.com/library/mac/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/OSX10-10.html#//apple_ref/doc/uid/TP40014508-CH109-SW1
+
+// This script is called from Appear to interact with macOS GUI apps. Both
+// Terminal.app and iTerm2 publish Applescript APIs, so they're super-easy to
+// script without accessibility!
+
+// libaries -----------------------------------------------
+var SystemEvents = Application('System Events')
+
+// allows using things like ThisApp.displayDialog
+var ThisApp = Application.currentApplication()
+ThisApp.includeStandardAdditions = true
+
+// helpful
+var ScriptContext = this
+
+// -----------------------------------------------------------
+var PROGRAM_NAME = 'appear-macOS-helper'
+var Methods = {}
+
+// entrypoint -------------------------------------------------
+// this is the main method of this script when it is called from the command line.
+// the remainer of the file is parsed and evaluated, and then the osascript
+// environment calls this function with two arguments:
+// 1: Array<String> argv
+// 2: Object ???. Could be ScriptContext?
+function run(argv, unknown) {
+  var method_name = argv[0]
+  var data = argv[1]
+  var message = "running method " + method_name
+
+  if (data) {
+    data = JSON.parse(data)
+    message = message + " with data"
+  }
+
+  try {
+    var method = Methods[method_name]
+    if (!method) throw new Error('unknown method ' + method_name)
+    // helpful for debugging sometimes! don't delete. just un-comment
+    //say(message)
+    var result = ok(method(data))
+    Subprocess.cleanup()
+    return JSON.stringify(result)
+  } catch (err) {
+    //say("failed because " + err.message)
+    Subprocess.cleanup()
+    return JSON.stringify(error(err))
+  }
+}
+
+function ok(result) {
+  return {status: 'ok', value: result}
+}
+
+function error(err) {
+  return {status: 'error', error: { message: err.message, stack: err.stack }}
+}
+
+// ------------------------------------------------------------
+
+function TerminalEmulator() {}
+TerminalEmulator.prototype.forEachPane = function(callback) {}
+TerminalEmulator.prototype.panes = function panes() {
+  var panes = []
+  this.forEachPane(function(pane) {
+    panes.push(pane)
+  })
+  return panes;
+}
+TerminalEmulator.prototype.revealTty = function(tty) {}
+
+// ------------------------------------------------------------
+// Iterm2 library
+
+function Iterm2() {
+  this.app = Application('com.googlecode.iterm2')
+}
+
+Iterm2.prototype = new TerminalEmulator();
+
+Iterm2.prototype.forEachPane = function forEachPane(callback) {
+  this.app.windows().forEach(function(win) {
+    win.tabs().forEach(function(tab) {
+      tab.sessions().forEach(function(session) {
+        callback({
+          window: win,
+          tab: tab,
+          session: session,
+          tty: session.tty(),
+        })
+      })
+    })
+  })
+}
+
+Iterm2.prototype.revealTty = function revealTty(tty) {
+  var success = false;
+
+  this.forEachPane(function(pane) {
+    if (pane.tty !== tty) return
+    if (success) return
+
+    pane.tab.select()
+    pane.session.select()
+    pane.window.select()
+    success = true;
+  })
+
+  if (success) smartActivate(this.app)
+  return success;
+}
+
+Methods['iterm2_reveal_tty'] = function iterm2_reveal_tty(tty) {
+  var iterm2 = new Iterm2()
+  return iterm2.revealTty(tty)
+}
+
+Methods['iterm2_panes'] = function iterm2_panes() {
+  var iterm2 = new Iterm2()
+  return iterm2.panes()
+}
+
+// -------------------------------------------------------------
+// Terminal.app library
+
+function Terminal() {
+  this.app = Application('com.apple.Terminal')
+}
+
+Terminal.prototype = new TerminalEmulator();
+
+Terminal.prototype.forEachPane = function iteratePanes(callback) {
+  this.app.windows().forEach(function(win) {
+    win.tabs().forEach(function(tab) {
+      callback({
+        window: win,
+        tab: tab,
+        tty: tab.tty(),
+      })
+    })
+  })
+}
+
+Terminal.prototype.revealTty = function revealTty(tty) {
+  var success = false;
+
+  this.forEachPane(function(pane) {
+    if (pane.tty !== tty) return;
+    if (success) return;
+
+    pane.tab.selected = true
+    pane.window.index = 0
+    success = true
+  })
+
+  if (success) smartActivate(this.app)
+  return success
+}
+
+Methods['terminal_reveal_tty'] = function terminal_reveal_tty(tty) {
+  var terminal = new Terminal()
+  return terminal.revealTty(tty)
+}
+
+Methods['terminal_panes'] = function terminal_panes() {
+  var terminal = new Terminal()
+  return terminal.panes()
+}
+
+// for tests ----------------------------------------------
+
+Methods['test_ok'] = function test_ok(arg1) {
+  return arg1
+}
+
+Methods['test_err'] = function test_err(arg1) {
+  var error = new Error('testing error handling')
+  error.arg1 = arg1
+  throw error
+}
+
+
+// paths ---------------------------------------------------
+Paths = (function(){
+  function splitPath(path) {
+    return path.split('/')
+  }
+
+  function joinPath(pathArray) {
+    var res = pathArray.join('/')
+    if (res[0] != '/') res = '/' + res
+    return res
+  }
+
+  function local(pathIn) {
+    var file = ThisApp.pathTo(ScriptContext).toString()
+    return join(dirname(file), pathIn)
+  }
+
+  function dirname(path) {
+    return joinPath(splitPath(path).slice(0, -1))
+  }
+
+  function basename(path) {
+    return splitPath(path).slice(-1)[0]
+  }
+
+  function join(root, extend) {
+    return joinPath(splitPath(root).concat(splitPath(extend)).filter(Boolean))
+  }
+
+  return {
+    local: local,
+    dirname: dirname,
+    basename: basename,
+    join: join,
+  }
+})();
+
+
+// Subprocess ---------------------------------------------------
+
+var Subprocess = (function() {
+  var FILENAME_PREFIX = Paths.join('/tmp', PROGRAM_NAME + '-' + Date.now() + Math.random() + '-')
+  var _tmpfile = 0;
+  var _threads = [];
+
+  // if the script doesn't have a file to write to, it will block still.
+  function tmpfile() {
+    var filename = FILENAME_PREFIX + _tmpfile++ + '.log'
+    return filename
+  }
+
+  // fork a command, and return the PID.
+  function fork(command, detatch) {
+    var output = tmpfile()
+    var script = command + ' &> ' + output + ' & echo $!'
+    var thread = {
+      command: command,
+      pid: ThisApp.doShellScript(script),
+      output: output,
+      detatch: detatch,
+    }
+    console.log('forked process', JSON.stringify(thread, null, 2))
+    _threads.push(thread)
+    return thread
+  }
+
+  function kill(pid) {
+    try {
+      // this will raise an error if the kill command cant find that process.
+      ThisApp.doShellScript('kill ' + pid)
+      return true
+    } catch (err) {
+      return false
+    }
+  }
+
+  function del(filename) {
+    var path = Path(filename)
+    if (SystemEvents.exists(path)) {
+      SystemEvents.delete(path)
+      return true
+    }
+    return false
+  }
+
+  function cleanup() {
+    _threads.forEach(function(thread) {
+      if (!thread.detatch) kill(thread.pid)
+      del(thread.output)
+    })
+  }
+
+  return {
+    fork: fork,
+    cleanup: cleanup,
+  }
+})();
+
+// various utils ----------------------------------------------
+
+function smartActivate(app) {
+  if (!app.frontmost()) {
+    app.activate()
+  }
+}
+
+function quotedForm(s) {
+  return "'" + s.replace(/'/g, "'\\''") + "'"
+}
+
+// non-blocking say text
+function say(text) {
+  Subprocess.fork('say ' + quotedForm(text), true)
+}
+
+// debugging -----------------------------------------------
+// these are left in here because they're useful if you ever want to develop this file again.
+
+function log(obj, fieldName) {
+  var fn = fieldName || '>'
+  console.log(fn, Automation.getDisplayString(obj))
+}
+
+function typeName(obj) {
+  return Object.prototype.toString.call(obj)
+}
+
+function inspect(obj) {
+  console.log("--------v")
+  log(obj)
+  if (obj !== undefined) inspectDetail(obj)
+  console.log('--------^')
+}
+
+function inspectDetail(obj) {
+  var proto = obj.__proto__;
+  var constructor = obj.constructor;
+  var name = typeName(obj)
+
+  console.log('')
+
+  log(name, 'type name')
+  log(proto, 'prototype')
+
+  console.log('')
+
+  log(Object.keys(obj), 'keys')
+  for (var thing in obj) {
+    log(obj[thing], 'prop ' + Automation.getDisplayString(thing) + ':')
+  }
+
+  console.log('')
+
+  log(constructor, 'constructor')
+}
+// ---------------------------------------------------------