appear 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49e7e4587f6725e9cf308bd49827e9b4a155904d
+  data.tar.gz: b62a655a7a4173118aa423bf8247c3407c39bd56
+SHA512:
+  metadata.gz: 276900ee030c9bdeba0fe2c85fd60034d7f6e34e976651525809b334afe9075ab74fe3c9555e6eaf3b29ff0b64d9f579eb804cd085539ee0babb23d2f92d3542
+  data.tar.gz: 10859c80d30ad2c950a3f809b0c6a260faf4233436c533f668802af4426c0f0265ec53293d01153ef8984828f685babaec34853dc3d849c7bfeeb820a1585c48

data/.doc-coverage

@@ -0,0 +1 @@
+73.05

data/.gitignore

@@ -0,0 +1,51 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+/logs/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+matrix:
+  # see https://docs.travis-ci.com/user/customizing-the-build/#Build-Matrix
+  # see https://docs.travis-ci.com/user/osx-ci-environment/
+  allow_failures:
+    - os: linux
+  include:
+    - os: linux
+      rvm: 1.9.3
+    - os: linux
+      rvm: 2.2.3
+    - os: osx
+      osx_image: xcode7 # 10.10
+    # - os: osx
+    # - osx_image: xcode7.2 # 10.11
+script:
+  # Please add to Rakefile instead of this section.
+  - bundle exec rake
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in appear.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Airbnb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# Appear
+
+Appear your terminal programs in your gui!
+
+[![Build Status](https://secure.travis-ci.org/airbnb/appear.svg?branch=master)](http://travis-ci.org/airbnb/appear)
+
+![screenshot demo thing](./screenshot.gif)
+
+Appear is a tool for revealing a given process in your terminal. Given a
+process ID, `appear` finds the terminal emulator view (be it a window, tab, or
+pane) containing that process and shows it to you. Appear understands terminal
+multiplexers like `tmux`, so if your target process is in a multiplexer
+session, `appear` will reveal a client connected to that session, or start one
+if needed.
+
+This project intends to support all POSIX operating systems eventually, but
+currently only supports macOS.
+
+## usage
+
+```
+Usage: appear [options] PID - appear PID in your user interface
+    -l, --log-file [PATH]            log to a file
+    -v, --verbose                    tell many tales about how the appear process is going
+        --record-runs                record every executed command as a JSON file
+```
+
+Appear will exit 0 if it managed to reveal something.
+Appear will exit 1 if an exception occured.
+Appear will exit 2 if there were no errors, but nothing was revealed.
+
+## supported terminal emulators
+
+macOS:
+
+ - iTerm2
+ - Terminal
+
+cross-platform:
+
+ - tmux
+
+GNU Screen support is a non-goal. It's time for screen users to switch to tmux.
+
+## system requirements
+
+ - `ruby` >= 2
+ - `lsof` command
+ - `ps` command
+ - `pgrep` command
+ - if you're a mac, then you should have macOS >= 10.10
+
+Appear depends only on the Ruby standard library.
+
+## how it works
+
+Here's how Appear works in a nutshell, given a `target_pid`
+
+1. get all the parent processes of `target_pid`, up to pid1. We end up with a
+   list of ProcessInfos, which have fields `{pid, parent_pid, command, name}`
+2. go through our list of "revealers", one for each terminal emulator (tmux,
+   iterm2, terminal.app) and ask the revealer if it can apply itself to the
+   process tree.
+3. if a revealer finds an associated process in the tree (eg, tmux revealer
+finds the tmux server process), it performs its reveal action
+  - this usually involves invoking `lsof` on a `/dev/ttys*` device to see what
+    processes are talking on what ttys to each other, which takes a bunch of
+    time
+  - `lsof` in Appear is parallel, so grouped lsof calls are less expensive
+  - the Tmux revealer is smart enough to both focus the pane that the
+    `target_pid` is running in, AND to recurse the revealing process with the
+    tmux client id, to reveal the tmux client.
+4. the revealer sends some instructions to the terminal emulator that contains
+the view for the PID
+  - for our Mac apps, this involves a helper process using [Javascript for
+    Automation][jfora], a JavaScript x Applescript crossover episode.
+  - for tmux this is just some shell commands, super easy.
+
+[jfora]: https://developer.apple.com/library/mac/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/OSX10-10.html#//apple_ref/doc/uid/TP40014508-CH109-SW1
+
+## ruby api
+
+The method documented here is the only part of Appear that should be considered
+stable.
+
+```ruby
+require 'appear'
+
+# super simple
+Appear.appear(pid)
+
+# You may customize logging, if needed, using the Config class
+config = Appear::Config.new
+
+# print debug info to STDOUT
+config.silent = false
+# also write to a log file
+config.log_file = '/tmp/my-app-appear.log'
+
+Appear.appear(pid, config)
+```

data/Rakefile

@@ -0,0 +1,53 @@
+require "bundler/gem_tasks"
+require "yard"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+module BasicDocCoverage
+  MINIMUM_COVERAGE = 25.0
+  YARD_COVERAGE_REGEX = /\s(?<percent>[\d\.]+)% documented/
+
+  ROOT_PATH = Pathname.new(File.dirname(File.expand_path(__FILE__)))
+  MINIMUM_COVERAGE_FILE = ROOT_PATH.join('.doc-coverage')
+
+  def self.define_task(task_name)
+    YARD::Rake::YardocTask.new(task_name) do |t|
+      t.files = ['lib/**/*.rb', '-', 'README.md']
+      t.options = ['--protected', '--no-private']
+
+      # make sure we doc the things
+      t.after = proc do
+
+        min_coverage = MINIMUM_COVERAGE
+        if MINIMUM_COVERAGE_FILE.exist?
+          min_coverage = [min_coverage, MINIMUM_COVERAGE_FILE.read.strip.to_f].max
+        end
+
+        yard_result = `bundle exec yard stats --list-undoc`
+        match = YARD_COVERAGE_REGEX.match(yard_result)
+        if !match
+          raise "Could not determine doc coverage using RE #{RE} from YARD output\n" \
+            ">>> start YARD output\n#{yard_result}\n<<< end YARD output"
+        end
+
+        percent = match[:percent].to_f
+        failure = percent < min_coverage
+
+        if failure
+          raise "FAILURE: doc coverage percent #{percent} < #{min_coverage}\n" \
+            "  please write good docs for your methods and attributes!\n" \
+            "  run `bundle exec yard stats --list-undoc` for details"
+        else
+          puts "SUCCESS: doc coverage percent #{percent} >= #{min_coverage}"
+        end
+
+        File.write(MINIMUM_COVERAGE_FILE, [percent, min_coverage].max.to_s)
+      end
+    end
+  end
+end
+
+BasicDocCoverage.define_task(:doc)
+
+task default: [:spec, :doc]

data/appear.gemspec

@@ -0,0 +1,44 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'appear/constants'
+
+Gem::Specification.new do |spec|
+  spec.name          = "appear"
+  spec.version       = Appear::VERSION
+  spec.authors       = ["Jake Teton-Landis"]
+  spec.email         = ["just.1.jake@gmail.com"]
+
+  spec.summary       = %q{Appear your terminal programs in your gui!}
+  spec.description   = <<-EOS
+    Appear is a tool for revealing a given process in your terminal. Given a
+    process ID, `appear` finds the terminal emulator view (be it a window, tab, or
+    pane) containing that process and shows it to you. Appear understands terminal
+    multiplexers like `tmux`, so if your target process is in a multiplexer
+    session, `appear` will reveal a client connected to that session, or start one
+    if needed.
+
+    This project intends to support all POSIX operating systems eventually, but
+    currently only supports macOS.
+  EOS
+  spec.homepage      = "https://github.com/airbnb/appear"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "yard", "~> 0.8.0"
+end

data/bin/appear

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+require 'pathname'
+
+$:.unshift(Pathname.new(__FILE__).realpath.dirname.dirname.join('./lib').to_s)
+
+require 'appear/command'
+command = Appear::Command.new.execute(ARGV)

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "appear"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/pparents

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+require 'pathname'
+
+$:.unshift(Pathname.new(__FILE__).realpath.dirname.dirname.join('./lib').to_s)
+
+require 'appear'
+
+module Appear::PParents
+  def self.main
+    pid = ARGV[0].to_i
+
+    output = Appear::Output.new(nil, true)
+    runner = Appear::Runner.new(:output => output)
+    processes = Appear::Processes.new(:output => output, :runner => runner)
+
+    tree = processes.process_tree(pid)
+    tree.each do |info|
+      puts "#{info.pid} #{info.command.join(' ')}"
+    end
+  end
+end
+
+Appear::PParents.main

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/appear.rb

@@ -0,0 +1,14 @@
+module Appear
+  # This method is an easy public interface to Appear for ruby consumers.
+  # Appear the given PID in your user interfaces.
+  # @param pid [Number] pid to Appear.
+  # @param config [Appear::Config, nil] a config for adjusting verbosity and logging.
+  def self.appear(pid, config = nil)
+    config ||= Appear::Config.new
+    instance = Appear::Instance.new(config)
+    instance.call(pid)
+  end
+end
+
+require 'appear/config'
+require 'appear/instance'

data/lib/appear/command.rb

@@ -0,0 +1,57 @@
+require 'appear/constants'
+require 'appear/config'
+require 'appear/instance'
+require 'optparse'
+
+module Appear
+  class InvalidPidError < Error; end
+
+  # Entrypoint and manager for the command-line `appear` tool.
+  class Command
+    def initialize
+      @config = Appear::Config.new
+      @config.silent = true
+    end
+
+    def option_parser
+      @option_parser ||= OptionParser.new do |o|
+        o.banner = 'Usage: appear [options] PID - appear PID in your user interface'
+        o.on('-l', '--log-file [PATH]', 'log to a file') do |file|
+          @config.log_file = file
+        end
+
+        o.on('-v', '--verbose', 'tell many tales about how the appear process is going') do |flag|
+          @config.silent = false if flag
+        end
+
+        o.on('--record-runs', 'record every executed command as a JSON file') do |flag|
+          @config.record_runs = flag
+        end
+      end
+    end
+
+    def execute(all_args)
+      argv = option_parser.parse!(all_args)
+
+      pid = argv[0].to_i
+      if pid == 0
+        raise InvalidPidError.new("Invalid PID #{argv[0].inspect} given (parsed to 0).")
+      end
+
+      start = Time.now
+      revealer = Appear::Instance.new(@config)
+      revealer.output("STARTING. pid: #{pid}")
+      result = revealer.call(pid)
+      finish = Time.now
+      revealer.output("DONE. total time: #{finish - start} seconds, success: #{result}")
+
+      if result
+        # success! revealed something!
+        exit 0
+      else
+        # did not appear, but no errors encountered
+        exit 2
+      end
+    end
+  end
+end