0.47.0

list of ports to other languages added to README

Changelog.md

@@ -1,3 +1,49 @@
+## 0.46.0 (2012-05-02)
+
+* Add Profile load/write/append API  [Michael Granger]
+* Guard against missing Procfile in engine.rb  [Brian Kaney]
+
+## 0.45.0 (2012-04-26)
+
+* create and chown log dir in upstart export.  [Phil Hagelberg]
+* remove parka from dist files  [David Dollar]
+
+## 0.44.0 (2012-04-23)
+
+* make var output order repeatable in supervisord export [David Dollar]
+* make --procfile and --app-root influence each other in a more intuitive way  [David Dollar]
+* Look for .env and app_root in the same dir as the Procfile.  [Phil Hagelberg]
+
+## 0.43.0 (2012-04-20)
+
+* wrap supervisord env vars in quotes  [Raphael Randschau]
+
+## 0.42.0 (2012-04-18)
+
+* Move read_environment to a public class method.  [Phil Hagelberg]
+* Drop parka dependency  [Phil Hagelberg]
+* add group support for supervisord  [Raphael Randschau]
+* fix enviroment export  [Raphael Randschau]
+
+## 0.41.0 (2012-03-16)
+
+* replace term-ansicolor with built-in colorization  [David Dollar]
+* supervisord export template  [Raphael Randschau]
+
+## 0.40.0 (2012-02-24)
+
+* support various quoting styles in .env  [David Dollar]
+* remove load_env! as it's made unnecessary by foreman run  [David Dollar]
+* Provide a useful error if `foreman check` fails to find a Procfile  [R. Tyler Croy]
+* update docs  [David Dollar]
+
+## 0.39.0 (2012-02-07)
+
+* rename bin/runner to bin/foreman-runner  [David Dollar]
+* fix tgz release  [David Dollar]
+* bundle update hpricot  [John Firebaugh]
+* touch up .pkg release tasks  [David Dollar]
+
 ## 0.38.0 (2012-02-02)
 
 * bring back single process starting  [David Dollar]

Gemfile

@@ -12,7 +12,6 @@ end
 
 group :development do
   gem 'aws-s3'
-  gem 'parka'
   gem 'rake'
   gem 'ronn'
   gem 'fakefs', '~> 0.3.2'

Gemfile.lock

@@ -1,8 +1,7 @@
 PATH
   remote: .
   specs:
-    foreman (0.39.0)
-      term-ansicolor (~> 1.0.7)
+    foreman (0.47.0)
       thor (>= 0.13.6)
 
 GEM
@@ -13,7 +12,6 @@ GEM
       mime-types
       xml-simple
     builder (3.0.0)
-    crack (0.1.8)
     diff-lcs (1.1.3)
     fakefs (0.3.2)
     hpricot (0.8.6)
@@ -21,15 +19,9 @@ GEM
     mime-types (1.16)
     multi_json (1.0.4)
     mustache (0.11.2)
-    parka (0.6.2)
-      crack
-      rest-client
-      thor
     posix-spawn (0.3.6)
     rake (0.9.2.2)
     rdiscount (1.6.5)
-    rest-client (1.6.1)
-      mime-types (>= 1.16)
     ronn (0.7.3)
       hpricot (>= 0.8.2)
       mustache (>= 0.7.0)
@@ -47,7 +39,6 @@ GEM
       multi_json (~> 1.0.3)
       simplecov-html (~> 0.5.3)
     simplecov-html (0.5.3)
-    term-ansicolor (1.0.7)
     thor (0.14.6)
     win32console (1.3.0-x86-mingw32)
     xml-simple (1.0.15)
@@ -61,7 +52,6 @@ DEPENDENCIES
   aws-s3
   fakefs (~> 0.3.2)
   foreman!
-  parka
   posix-spawn (~> 0.3.6)
   rake
   ronn

README.md

@@ -27,13 +27,19 @@ Manage Procfile-based applications
 * [wiki](http://github.com/ddollar/foreman/wiki)
 * [changelog](https://github.com/ddollar/foreman/blob/master/Changelog.md)
 
+## Ports
+
+* [shoreman](https://github.com/hecticjeff/shoreman) - shell
+* [honcho](https://github.com/nickstenning/honcho) - python
+* [norman](https://github.com/josh/norman) - node.js
+
 ## Authors
 
 #### Created and maintained by
 David Dollar
 
 #### Patches contributed by
-Adam Wiggins, Chris Continanza, Chris Lowder, Craig R Webster, Dan Farina, Dan Peterson, David Dollar, Fletcher Nichol, Florian Apolloner, Gabriel Burt, Gamaliel Toro, Greg Reinacker, Hugues Le Gendre, Hunter Nield, Iain Hecker, Jay Zeschin, John Firebaugh, Keith Rarick, Khaja Minhajuddin, Lincoln Stoll, Marcos Muino Garcia, Mark McGranaghan, Matt Griffin, Matt Haynes, Matthijs Langenberg, Michael Dwan, Michael van Rooijen, Mike Javorski, Nathan Broadbent, Nathan L Smith, Nick Zadrozny, Phil Hagelberg, Ricardo Chimal, Jr, Thom May, Tom Ward, brainopia, clifff, jc00ke
+[Contributor List](https://github.com/ddollar/foreman/contributors)
 
 ## License
 

bin/foreman-runner

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-#/ Usage: foreman-runner [-d <dir>] <command>
+#/ Usage: foreman-runner [-d <dir>] <command> [<args>...]
 #/
 #/ Run a command with exec, optionally changing directory first
 
@@ -27,10 +27,6 @@ done
 
 shift $((OPTIND-1))
 
-command=$1
+[ -z "$1" ] && usage
 
-if [ -z "$1" ]; then
-  usage
-fi
-
-exec $1
+exec "$@"

data/export/bluepill/master.pill.erb

@@ -11,8 +11,9 @@ Bluepill.application("<%= app %>", :foreground => false, :log_file => "/var/log/
 
     process.working_dir = "<%= engine.directory %>"
     process.daemonize = true
-    process.environment = {"PORT" => "<%= port %>"}
+    process.environment = {"PORT" => "<%= port %>"<% engine.environment.each_pair do |var,env| %> , "<%= var.upcase %>" => "<%= env %>" <% end %>}
     process.stop_signals = [:quit, 30.seconds, :term, 5.seconds, :kill]
+    process.stop_grace_time = 45.seconds
 
     process.stdout = process.stderr = "<%= log_root %>/<%= app %>-<%= process.name %>-<%=num%>.log"
 

data/export/launchd/launchd.plist.erb

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string><%= "#{app}-#{process.name}-#{num}" %></string>
+    <key>ProgramArguments</key>
+    <array>
+        <string><%= process.command %></string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardErrorPath</key>
+    <string><%= log_root %>/<%= app %>-<%= process.name %>-<%=num%>.log</string>
+    <key>UserName</key>
+    <string><%= user %></string>
+    <key>WorkingDirectory</key>
+    <string><%= engine.directory %></string>
+</dict>
+</plist>

data/export/supervisord/app.conf.erb

@@ -0,0 +1,27 @@
+<%
+app_names = []
+engine.procfile.entries.each do |process|
+  next if (conc = self.concurrency[process.name]) < 1
+  1.upto(self.concurrency[process.name]) do |num|
+    port = engine.port_for(process, num, self.port)
+    name = if (conc > 1); "#{process.name}-#{num}" else process.name; end
+    environment = (engine.environment.keys.sort.map{ |var| %{#{var.upcase}="#{engine.environment[var]}"} } + [%{PORT="#{port}"}])
+    app_name = "#{app}-#{name}"
+    app_names << app_name
+%>
+[program:<%= app_name %>]
+command=<%= process.command %>
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=<%= log_root %>/<%=process.name%>-<%=num%>-out.log
+stderr_logfile=<%= log_root %>/<%=process.name%>-<%=num%>-err.log
+user=<%= user %>
+directory=<%= engine.directory %>
+environment=<%= environment.join(',') %><%
+  end
+end
+%>
+
+[group:<%= app %>]
+programs=<%= app_names.join(',') %>

data/export/upstart/process.conf.erb

@@ -2,4 +2,4 @@ start on starting <%= app %>-<%= process.name %>
 stop on stopping <%= app %>-<%= process.name %>
 respawn
 
-exec su - <%= user %> -c 'cd <%= engine.directory %>; export PORT=<%= port %>;<% engine.environment.each_pair do |var,env| %> export <%= var.upcase %>=<%= env %>; <% end %> <%= process.command %> >> <%= log_root %>/<%=process.name%>-<%=num%>.log 2>&1'
+exec su - <%= user %> -c 'cd <%= engine.directory %>; export PORT=<%= port %>;<% engine.environment.each_pair do |var,env| %> export <%= var.upcase %>=<%= shell_quote(env) %>; <% end %> <%= process.command %> >> <%= log_root %>/<%=process.name%>-<%=num%>.log 2>&1'

dist/gem.rake

@@ -10,5 +10,5 @@ task "gem:clean" do
 end
 
 task "gem:release" => "gem:build" do |t|
-  sh "parka push -f #{pkg("foreman-#{version}.gem")}"
+  sh "gem push #{pkg("foreman-#{version}.gem")} || echo 'error'"
 end

dist/jruby.rake

@@ -12,5 +12,5 @@ task "jruby:clean" do
 end
 
 task "jruby:release" => "jruby:build" do |t|
-  sh "parka push -f #{pkg("foreman-#{version}-jruby.gem")}"
+  sh "gem push #{pkg("foreman-#{version}-jruby.gem")} || echo 'error'"
 end

dist/mingw32.rake

@@ -12,5 +12,5 @@ task "mingw32:clean" do
 end
 
 task "mingw32:release" => "mingw32:build" do |t|
-  sh "parka push -f #{pkg("foreman-#{version}-mingw32.gem")}"
+  sh "gem push #{pkg("foreman-#{version}-mingw32.gem")} || echo 'error'"
 end

foreman.gemspec

@@ -16,8 +16,7 @@ Gem::Specification.new do |gem|
   gem.files = Dir["**/*"].select { |d| d =~ %r{^(README|bin/|data/|ext/|lib/|spec/|test/)} }
   gem.files << "man/foreman.1"
 
-  gem.add_dependency 'term-ansicolor', '~> 1.0.7'
-  gem.add_dependency 'thor',           '>= 0.13.6'
+  gem.add_dependency 'thor', '>= 0.13.6'
 
   if ENV["PLATFORM"] == "java"
     gem.add_dependency "posix-spawn", "~> 0.3.6"

lib/foreman.rb

@@ -4,12 +4,6 @@ module Foreman
 
   class AppDoesNotExist < Exception; end
 
-  # load contents of env_file into ENV
-  def self.load_env!(env_file = './.env')
-    require 'foreman/engine'
-    Foreman::Engine.load_env!(env_file)
-  end
-
   def self.runner
     File.expand_path("../../bin/foreman-runner", __FILE__)
   end

lib/foreman/cli.rb

@@ -2,6 +2,7 @@ require "foreman"
 require "foreman/helpers"
 require "foreman/engine"
 require "foreman/export"
+require "shellwords"
 require "thor"
 require "yaml"
 
@@ -54,16 +55,17 @@ class Foreman::CLI < Thor
   desc "check", "Validate your application's Procfile"
 
   def check
+    check_procfile!
     error "no processes defined" unless engine.procfile.entries.length > 0
     puts "valid procfile detected (#{engine.procfile.process_names.join(', ')})"
   end
 
-  desc "run COMMAND", "Run a command using your application's environment"
+  desc "run COMMAND [ARGS...]", "Run a command using your application's environment"
 
   def run(*args)
     engine.apply_environment!
     begin
-      exec args.join(" ")
+      exec args.shelljoin
     rescue Errno::EACCES
       error "not executable: #{args.first}"
     rescue Errno::ENOENT
@@ -82,7 +84,11 @@ private ######################################################################
   end
 
   def procfile
-    options[:procfile] || "Procfile"
+    case
+      when options[:procfile] then options[:procfile]
+      when options[:app_root] then File.expand_path(File.join(options[:app_root], "Procfile"))
+      else "Procfile"
+    end
   end
 
   def error(message)

lib/foreman/color.rb

@@ -0,0 +1,40 @@
+require "foreman"
+
+module Foreman::Color
+
+  ANSI = {
+    :reset          => 0,
+    :black          => 30,
+    :red            => 31,
+    :green          => 32,
+    :yellow         => 33,
+    :blue           => 34,
+    :magenta        => 35,
+    :cyan           => 36,
+    :white          => 37,
+    :bright_black   => 30,
+    :bright_red     => 31,
+    :bright_green   => 32,
+    :bright_yellow  => 33,
+    :bright_blue    => 34,
+    :bright_magenta => 35,
+    :bright_cyan    => 36,
+    :bright_white   => 37,
+  }
+
+  def self.enable(io)
+    io.extend(self)
+  end
+
+  def color?
+    return false unless self.respond_to?(:isatty)
+    self.isatty && ENV["TERM"]
+  end
+
+  def color(name)
+    return "" unless color?
+    return "" unless ansi = ANSI[name.to_sym]
+    "\e[#{ansi}m"
+  end
+
+end

lib/foreman/engine.rb

@@ -1,36 +1,33 @@
 require "foreman"
+require "foreman/color"
 require "foreman/process"
 require "foreman/procfile"
 require "foreman/utils"
 require "tempfile"
 require "timeout"
-require "term/ansicolor"
 require "fileutils"
 require "thread"
 
 class Foreman::Engine
 
+  attr_reader :environment
   attr_reader :procfile
   attr_reader :directory
   attr_reader :options
 
-  extend Term::ANSIColor
+  COLORS = %w( cyan yellow green magenta red blue intense_cyan intense_yellow
+               intense_green intense_magenta intense_red, intense_blue )
 
-  COLORS = [ cyan, yellow, green, magenta, red, blue,
-             intense_cyan, intense_yellow, intense_green, intense_magenta,
-             intense_red, intense_blue ]
+  Foreman::Color.enable($stdout)
 
   def initialize(procfile, options={})
-    @procfile  = Foreman::Procfile.new(procfile)
+    @procfile  = Foreman::Procfile.new(procfile) if File.exists?(procfile)
     @directory = options[:app_root] || File.expand_path(File.dirname(procfile))
     @options = options.dup
-    @environment = read_environment_files(options[:env])
     @output_mutex = Mutex.new
-  end
 
-  def self.load_env!(env_file)
-    @environment = read_environment_files(env_file)
-    apply_environment!
+    @options[:env] ||= default_env
+    @environment = read_environment_files(@options[:env])
   end
 
   def start
@@ -39,6 +36,7 @@ class Foreman::Engine
 
     trap("TERM") { puts "SIGTERM received"; terminate_gracefully }
     trap("INT")  { puts "SIGINT received";  terminate_gracefully }
+    trap("HUP")  { puts "SIGHUP received";  terminate_gracefully }
 
     assign_colors
     spawn_processes
@@ -52,6 +50,26 @@ class Foreman::Engine
     base_port.to_i + offset + num - 1
   end
 
+  def apply_environment!
+    environment.each { |k,v| ENV[k] = v }
+  end
+
+  def self.read_environment(filename)
+    return {} unless File.exists?(filename)
+
+    File.read(filename).split("\n").inject({}) do |hash, line|
+      if line =~ /\A([A-Za-z_0-9]+)=(.*)\z/
+        key, val = [$1, $2]
+        case val
+          when /\A'(.*)'\z/ then hash[key] = $1
+          when /\A"(.*)"\z/ then hash[key] = $1.gsub(/\\(.)/, '\1')
+          else hash[key] = val
+        end
+      end
+      hash
+    end
+  end
+
 private ######################################################################
 
   def spawn_processes
@@ -67,7 +85,7 @@ private ######################################################################
   end
 
   def base_port
-    options[:port] || 5000
+    options[:port] || environment["PORT"] || ENV["PORT"] || 5000
   end
 
   def kill_all(signal="SIGTERM")
@@ -128,11 +146,11 @@ private ######################################################################
   rescue Errno::ECHILD
   end
 
-  def info(message, name="system", color=Term::ANSIColor.white)
+  def info(message, name="system", color=:white)
     output  = ""
-    output += color
+    output += $stdout.color(color)
     output += "#{Time.now.strftime("%H:%M:%S")} #{pad_process_name(name)} | "
-    output += Term::ANSIColor.reset
+    output += $stdout.color(:reset)
     output += message.chomp
     puts output
   end
@@ -182,8 +200,8 @@ private ######################################################################
   end
 
   def assign_colors
-    procfile.entries.each do |entry|
-      colors[entry.name] = next_color
+    procfile.entries.each_with_index do |entry, idx|
+      colors[entry.name] = COLORS[idx % COLORS.length]
     end
   end
 
@@ -191,49 +209,20 @@ private ######################################################################
     readers.invert[reader]
   end
 
-  def next_color
-    @current_color ||= -1
-    @current_color  +=  1
-    @current_color = 0 if COLORS.length < @current_color
-    COLORS[@current_color]
+  def read_environment_files(filenames)
+    environment = {}
+
+    (filenames || "").split(",").map(&:strip).each do |filename|
+      error "No such file: #{filename}" unless File.exists?(filename)
+      environment.merge!(Foreman::Engine.read_environment(filename))
+    end
+
+    environment
   end
 
-  module Env
-    attr_reader :environment
-
-    def read_environment_files(filenames)
-      environment = {}
-
-      (filenames || "").split(",").map(&:strip).each do |filename|
-        error "No such file: #{filename}" unless File.exists?(filename)
-        environment.merge!(read_environment(filename))
-      end
-
-      environment.merge!(read_environment(".env")) unless filenames
-      environment
-    end
-
-    def read_environment(filename)
-      return {} unless File.exists?(filename)
-
-      File.read(filename).split("\n").inject({}) do |hash, line|
-        if line =~ /\A([A-Za-z_0-9]+)=(.*)\z/
-          hash[$1] = $2
-        end
-        hash
-      end
-    end
-
-    def apply_environment!
-      @environment.each { |k,v| ENV[k] = v }
-    end
-
-    def error(message)
-      puts "ERROR: #{message}"
-      exit 1
-    end
+  def default_env
+    env = File.join(directory, ".env")
+    File.exists?(env) ? env : ""
   end
 
-  include Env
-  extend  Env
 end

lib/foreman/export.rb

@@ -30,3 +30,6 @@ require "foreman/export/inittab"
 require "foreman/export/upstart"
 require "foreman/export/bluepill"
 require "foreman/export/runit"
+require "foreman/export/supervisord"
+require "foreman/export/launchd"
+

lib/foreman/export/base.rb

@@ -48,4 +48,19 @@ private ######################################################################
     end
   end
 
+  # Quote a string to be used on the command line. Backslashes are escapde to \\ and quotes 
+  # escaped to \"
+  #
+  #   str - string to be quoted
+  #
+  # Examples
+  # 
+  #  shell_quote("FB|123\"\\1")
+  #  # => "\"FB|123\"\\"\\\\1\""
+  #
+  # Returns the the escaped string surrounded by quotes 
+  def shell_quote(str)
+    "\"#{str.gsub(/\\/){ '\\\\' }.gsub(/["]/){ "\\\"" }}\""
+  end
+
 end

lib/foreman/export/launchd.rb

@@ -0,0 +1,27 @@
+require "erb"
+require "foreman/export"
+
+class Foreman::Export::Launchd < Foreman::Export::Base
+
+  def export
+    error("Must specify a location") unless location
+    
+    app = self.app || File.basename(engine.directory)
+    user = self.user || app
+    log_root = self.log || "/var/log/#{app}"
+    template_root = self.template
+    
+    FileUtils.mkdir_p(location)
+    
+    engine.procfile.entries.each do |process|
+      1.upto(self.concurrency[process.name]) do |num|
+
+        master_template = export_template("launchd", "launchd.plist.erb", template_root)
+        master_config   = ERB.new(master_template).result(binding)
+        write_file "#{location}/#{app}-#{process.name}-#{num}.plist", master_config
+      end
+    end
+    
+  end
+
+end

lib/foreman/export/supervisord.rb

@@ -0,0 +1,26 @@
+require "erb"
+require "foreman/export"
+
+class Foreman::Export::Supervisord < Foreman::Export::Base
+
+  def export
+    error("Must specify a location") unless location
+
+    FileUtils.mkdir_p location
+
+    app = self.app || File.basename(engine.directory)
+    user = self.user || app
+    log_root = self.log || "/var/log/#{app}"
+    template_root = self.template
+
+    Dir["#{location}/#{app}*.conf"].each do |file|
+      say "cleaning up: #{file}"
+      FileUtils.rm(file)
+    end
+
+    app_template = export_template("supervisord", "app.conf.erb", template_root)
+    app_config   = ERB.new(app_template, 0, '<').result(binding)
+    write_file "#{location}/#{app}.conf", app_config
+  end
+
+end

lib/foreman/export/upstart.rb

@@ -36,6 +36,8 @@ class Foreman::Export::Upstart < Foreman::Export::Base
         write_file "#{location}/#{app}-#{process.name}-#{num}.conf", process_config
       end
     end
-  end
 
+    FileUtils.mkdir_p(log_root) rescue error "could not create #{log_root}"
+    FileUtils.chown(user, nil, log_root) rescue error "could not chown #{log_root} to #{user}"
+  end
 end

lib/foreman/process.rb

@@ -62,7 +62,7 @@ private
         $stdout.reopen writer
         $stderr.reopen writer
         reader.close
-        exec Foreman.runner, "-d", basedir, command
+        exec Foreman.runner, "-d", basedir, *command.shellsplit
       end
     end
     [ reader, pid ]

lib/foreman/procfile.rb

@@ -13,8 +13,9 @@ class Foreman::Procfile
 
   attr_reader :entries
 
-  def initialize(filename)
-    @entries = parse_procfile(filename)
+  def initialize(filename=nil)
+    @entries = []
+    load(filename) if filename
   end
 
   def [](name)
@@ -25,12 +26,31 @@ class Foreman::Procfile
     entries.map(&:name)
   end
 
-private
+  def load(filename)
+    entries.clear
+    parse_procfile(filename)
+  end
+
+  def write(filename)
+    File.open(filename, 'w') do |io|
+      entries.each do |ent|
+        io.puts(ent)
+      end
+    end
+  end
+
+  def <<(entry)
+    entries << Foreman::ProcfileEntry.new(*entry)
+    self
+  end
+
+
+protected
 
   def parse_procfile(filename)
     File.read(filename).split("\n").map do |line|
       if line =~ /^([A-Za-z0-9_]+):\s*(.+)$/
-        Foreman::ProcfileEntry.new($1, $2)
+        self << [ $1, $2 ]
       end
     end.compact
   end

lib/foreman/procfile_entry.rb

@@ -19,4 +19,8 @@ class Foreman::ProcfileEntry
     end
   end
 
+  def to_s
+    "#{name}: #{command}"
+  end
+
 end

lib/foreman/version.rb

@@ -1,5 +1,5 @@
 module Foreman
 
-  VERSION = "0.39.0"
+  VERSION = "0.47.0"
 
 end

man/foreman.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "FOREMAN" "1" "January 2012" "Foreman 0.37.2" "Foreman Manual"
+.TH "FOREMAN" "1" "April 2012" "Foreman 0.46.0" "Foreman Manual"
 .
 .SH "NAME"
 \fBforeman\fR \- manage Procfile\-based applications
@@ -10,10 +10,13 @@
 \fBforeman start [process]\fR
 .
 .br
+\fBforeman run <command>\fR
+.
+.br
 \fBforeman export <format> [location]\fR
 .
 .SH "DESCRIPTION"
-\fBForeman\fR is a manager for Procfile\-based applications\. Its aim is to abstract away the details of the Procfile format, and allow you to either run your application directly or export it to some other process management format\.
+Foreman is a manager for Procfile\-based applications\. Its aim is to abstract away the details of the Procfile format, and allow you to either run your application directly or export it to some other process management format\.
 .
 .SH "RUNNING"
 \fBforeman start\fR is used to run your application directly from the command line\.
@@ -32,9 +35,20 @@ The following options control how the application is run:
 Specify the number of each process type to run\. The value passed in should be in the format \fBprocess=num,process=num\fR
 .
 .TP
+\fB\-e\fR, \fB\-\-env\fR
+Specify one or more \.env files to load
+.
+.TP
+\fB\-f\fR, \fB\-\-procfile\fR
+Specify an alternate Procfile to load, implies \fB\-d\fR at the Procfile root\.
+.
+.TP
 \fB\-p\fR, \fB\-\-port\fR
 Specify which port to use as the base for this application\. Should be a multiple of 1000\.
 .
+.P
+\fBforeman run\fR is used to run one\-off commands using the same environment as your defined processes\.
+.
 .SH "EXPORTING"
 \fBforeman export\fR is used to export your application to another process management format\.
 .
@@ -61,10 +75,14 @@ Specify the directory to place process logs in\.
 Specify which port to use as the base for this application\. Should be a multiple of 1000\.
 .
 .TP
+\fB\-t\fR, \fB\-\-template\fR
+Specify an alternate template to use for creating export files\. See \fIhttps://github\.com/ddollar/foreman/tree/master/data/export\fR for examples\.
+.
+.TP
 \fB\-u\fR, \fB\-\-user\fR
 Specify the user the application should be run as\. Defaults to the app name
 .
-.SH "OPTIONS"
+.SH "GLOBAL OPTIONS"
 These options control all modes of foreman\'s operation\.
 .
 .TP

man/foreman.1.ronn

@@ -4,11 +4,12 @@ foreman(1) -- manage Procfile-based applications
 ## SYNOPSIS
 
 `foreman start [process]`<br>
+`foreman run <command>`<br>
 `foreman export <format> [location]`
 
 ## DESCRIPTION
 
-**Foreman** is a manager for Procfile-based applications. Its aim is to
+Foreman is a manager for Procfile-based applications. Its aim is to
 abstract away the details of the Procfile format, and allow you to either run
 your application directly or export it to some other process management
 format.
@@ -29,10 +30,19 @@ The following options control how the application is run:
     Specify the number of each process type to run. The value passed in
     should be in the format `process=num,process=num`
 
+  * `-e`, `--env`:
+    Specify one or more .env files to load
+
+  * `-f`, `--procfile`:
+    Specify an alternate Procfile to load, implies `-d` at the Procfile root.
+
   * `-p`, `--port`:
     Specify which port to use as the base for this application. Should be
     a multiple of 1000.
 
+`foreman run` is used to run one-off commands using the same environment
+as your defined processes.
+
 ## EXPORTING
 
 `foreman export` is used to export your application to another process
@@ -58,11 +68,15 @@ The following options control how the application is run:
     Specify which port to use as the base for this application. Should be
     a multiple of 1000.
 
+  * `-t`, `--template`:
+    Specify an alternate template to use for creating export files.
+    See <https://github.com/ddollar/foreman/tree/master/data/export> for examples.
+
   * `-u`, `--user`:
     Specify the user the application should be run as. Defaults to the
     app name
 
-## OPTIONS
+## GLOBAL OPTIONS
 
 These options control all modes of foreman's operation.
 

spec/foreman/cli_spec.rb

@@ -34,6 +34,15 @@ describe "Foreman::CLI", :fakefs do
         subject.start("alpha")
       end
     end
+
+    describe "with an alternate root" do
+      it "reads the Procfile from that root" do
+        write_procfile "/some/app/Procfile"
+        mock(Foreman::Procfile).new("/some/app/Procfile")
+        mock.instance_of(Foreman::Engine).start
+        foreman %{ start -d /some/app }
+      end
+    end
   end
 
   describe "export" do
@@ -120,6 +129,14 @@ describe "Foreman::CLI", :fakefs do
         end
       end
     end
+
+    describe "without a Procfile" do
+      it "displays an error" do
+        mock_error(subject, "Procfile does not exist.") do
+          subject.check
+        end
+      end
+    end
   end
 
   describe "run" do
@@ -127,7 +144,7 @@ describe "Foreman::CLI", :fakefs do
       before { write_procfile }
 
       describe "and a command" do
-        let(:command) { ["ls", "-l"] }
+        let(:command) { ["ls", "-l", "foo bar"] }
 
         before(:each) do
           stub(subject).exec
@@ -143,8 +160,8 @@ describe "Foreman::CLI", :fakefs do
           ENV["FOO"].should be_nil
         end
 
-        it "should runute the command as a string" do
-          mock(subject).exec(command.join(" "))
+        it "should exec the argument list as a shell command" do
+          mock(subject).exec(command.shelljoin)
           subject.run *command
         end
       end

spec/foreman/color_spec.rb

@@ -0,0 +1,31 @@
+require "spec_helper"
+require "foreman/color"
+
+describe Foreman::Color do
+
+  let(:io) { Object.new }
+
+  it "should extend an object with colorization" do
+    Foreman::Color.enable(io)
+    io.should respond_to(:color)
+  end
+
+  it "should not colorize if the object does not respond to isatty" do
+    mock(io).respond_to?(:isatty) { false }
+    Foreman::Color.enable(io)
+    io.color(:white).should == ""
+  end
+
+  it "should not colorize if the object is not a tty" do
+    mock(io).isatty { false }
+    Foreman::Color.enable(io)
+    io.color(:white).should == ""
+  end
+
+  it "should colorize if the object is a tty" do
+    mock(io).isatty { true }
+    Foreman::Color.enable(io)
+    io.color(:white).should == "\e[37m"
+  end
+
+end

spec/foreman/engine_spec.rb

@@ -12,12 +12,6 @@ describe "Foreman::Engine", :fakefs do
   end
 
   describe "initialize" do
-    describe "without an existing Procfile" do
-      it "raises an error" do
-        lambda { subject }.should raise_error
-      end
-    end
-
     describe "with a Procfile" do
       before { write_procfile }
 
@@ -49,18 +43,28 @@ describe "Foreman::Engine", :fakefs do
     end
   end
 
+  describe "directories" do
+    it "has the directory default relative to the Procfile" do
+      write_procfile "/some/app/Procfile"
+      engine = Foreman::Engine.new("/some/app/Procfile")
+      engine.directory.should == "/some/app"
+    end
+  end
+
   describe "environment" do
     before(:each) do
       write_procfile
       stub(Process).fork
+      any_instance_of(Foreman::Engine) do |engine|
+        stub(engine).info
+        stub(engine).spawn_processes
+        stub(engine).watch_for_termination
+      end
     end
 
     it "should read if specified" do
       File.open("/tmp/env", "w") { |f| f.puts("FOO=baz") }
       engine = Foreman::Engine.new("Procfile", :env => "/tmp/env")
-      stub(engine).info
-      mock(engine).spawn_processes
-      mock(engine).watch_for_termination
       engine.environment.should == {"FOO"=>"baz"}
       engine.start
     end
@@ -69,13 +73,21 @@ describe "Foreman::Engine", :fakefs do
       File.open("/tmp/env1", "w") { |f| f.puts("FOO=bar") }
       File.open("/tmp/env2", "w") { |f| f.puts("BAZ=qux") }
       engine = Foreman::Engine.new("Procfile", :env => "/tmp/env1,/tmp/env2")
-      stub(engine).info
-      mock(engine).spawn_processes
-      mock(engine).watch_for_termination
       engine.environment.should == { "FOO"=>"bar", "BAZ"=>"qux" }
       engine.start
     end
 
+    it "should handle quoted values" do
+      File.open("/tmp/env", "w") do |f|
+        f.puts 'FOO=bar'
+        f.puts 'BAZ="qux"'
+        f.puts "FRED='barney'"
+        f.puts 'OTHER="escaped\"quote"'
+      end
+      engine = Foreman::Engine.new("Procfile", :env => "/tmp/env")
+      engine.environment.should == { "FOO" => "bar", "BAZ" => "qux", "FRED" => "barney", "OTHER" => 'escaped"quote' }
+    end
+
     it "should fail if specified and doesnt exist" do
       mock.instance_of(Foreman::Engine).error("No such file: /tmp/env")
       engine = Foreman::Engine.new("Procfile", :env => "/tmp/env")
@@ -84,8 +96,22 @@ describe "Foreman::Engine", :fakefs do
     it "should read .env if none specified" do
       File.open(".env", "w") { |f| f.puts("FOO=qoo") }
       engine = Foreman::Engine.new("Procfile")
-      mock(engine).spawn_processes
-      mock(engine).watch_for_termination
+      engine.environment.should == {"FOO"=>"qoo"}
+      engine.start
+    end
+
+    it "should set port from .env if specified" do
+      File.open(".env", "w") { |f| f.puts("PORT=8017") }
+      engine = Foreman::Engine.new("Procfile")
+      engine.send(:base_port).should == "8017"
+      engine.start
+    end
+
+    it "should be loaded relative to the Procfile" do
+      FileUtils.mkdir_p "/some/app"
+      File.open("/some/app/.env", "w") { |f| f.puts("FOO=qoo") }
+      write_procfile "/some/app/Procfile"
+      engine = Foreman::Engine.new("/some/app/Procfile")
       engine.environment.should == {"FOO"=>"qoo"}
       engine.start
     end

spec/foreman/export/launchd_spec.rb

@@ -0,0 +1,24 @@
+require "spec_helper"
+require "foreman/engine"
+require "foreman/export/launchd"
+require "tmpdir"
+
+describe Foreman::Export::Launchd, :fakefs do
+  let(:procfile) { FileUtils.mkdir_p("/tmp/app"); write_procfile("/tmp/app/Procfile") }
+  let(:engine)   { Foreman::Engine.new(procfile) }
+  let(:options)  { Hash.new }
+  let(:launchd) { Foreman::Export::Launchd.new("/tmp/init", engine, options) }
+
+  before(:each) { load_export_templates_into_fakefs("launchd") }
+  before(:each) { stub(launchd).say }
+
+  it "exports to the filesystem" do
+    launchd.export
+    
+    normalize_space(File.read("/tmp/init/app-alpha-1.plist")).should == normalize_space(example_export_file("launchd/launchd-a.default"))
+    
+    normalize_space(File.read("/tmp/init/app-bravo-1.plist")).should == normalize_space(example_export_file("launchd/launchd-b.default"))
+    
+  end
+
+end

spec/foreman/export/supervisord_spec.rb

@@ -0,0 +1,85 @@
+require "spec_helper"
+require "foreman/engine"
+require "foreman/export/supervisord"
+require "tmpdir"
+
+describe Foreman::Export::Supervisord, :fakefs do
+  let(:procfile) { FileUtils.mkdir_p("/tmp/app"); write_procfile("/tmp/app/Procfile") }
+  let(:engine)   { Foreman::Engine.new(procfile) }
+  let(:options)  { Hash.new }
+  let(:supervisord)  { Foreman::Export::Supervisord.new("/tmp/init", engine, options) }
+
+  before(:each) { load_export_templates_into_fakefs("supervisord") }
+  before(:each) { stub(supervisord).say }
+
+  it "exports to the filesystem" do
+    supervisord.export
+
+    File.read("/tmp/init/app.conf").should == example_export_file("supervisord/app.conf")
+  end
+
+  it "cleans up if exporting into an existing dir" do
+    mock(FileUtils).rm("/tmp/init/app.conf")
+    supervisord.export
+    supervisord.export
+  end
+
+  context "with concurrency" do
+    let(:options) { Hash[:concurrency => "alpha=2"] }
+
+    it "exports to the filesystem with concurrency" do
+      supervisord.export
+      File.read("/tmp/init/app.conf").should == example_export_file("supervisord/app-alpha-2.conf")
+    end
+  end
+
+  context "with alternate templates" do
+    let(:template_root) { "/tmp/alternate" }
+    let(:supervisord) { Foreman::Export::Supervisord.new("/tmp/init", engine, :template => template_root) }
+
+    before do
+      FileUtils.mkdir_p template_root
+      File.open("#{template_root}/app.conf.erb", "w") { |f| f.puts "alternate_template" }
+    end
+
+    it "can export with alternate template files" do
+      supervisord.export
+      File.read("/tmp/init/app.conf").should == "alternate_template\n"
+    end
+  end
+
+  context "with alternate templates from home dir" do
+    let(:default_template_root) {File.expand_path("#{ENV['HOME']}/.foreman/templates")}
+
+    before do
+      ENV['_FOREMAN_SPEC_HOME'] = ENV['HOME']
+      ENV['HOME'] = "/home/appuser"
+      FileUtils.mkdir_p default_template_root
+      File.open("#{default_template_root}/app.conf.erb", "w") { |f| f.puts "default_alternate_template" }
+    end
+
+    after do
+      ENV['HOME'] = ENV.delete('_FOREMAN_SPEC_HOME')
+    end
+
+    it "can export with alternate template files" do
+      supervisord.export
+      File.read("/tmp/init/app.conf").should == "default_alternate_template\n"
+    end
+  end
+
+  context "environment export" do
+    it "correctly translates environment when exporting" do
+      File.open("/tmp/supervisord_env", "w") { |f| f.puts("QUEUE=fastqueue,slowqueue\nVERBOSE=1") }
+
+      engine = Foreman::Engine.new(procfile,:env => "/tmp/supervisord_env")
+      supervisor = Foreman::Export::Supervisord.new("/tmp/init", engine, options)
+      stub(supervisor).say
+
+      supervisor.export
+
+      File.read("/tmp/init/app.conf").should == example_export_file("supervisord/app-env-with-comma.conf")
+    end
+  end
+
+end

spec/foreman/export/upstart_spec.rb

@@ -33,6 +33,12 @@ describe Foreman::Export::Upstart, :fakefs do
     upstart.export
   end
 
+  it "quotes and escapes environment variables" do
+    engine.environment['KEY'] = 'd"\|d'
+    upstart.export
+    File.read("/tmp/init/app-alpha-1.conf").should include('KEY="d\"\\\\|d"')
+  end
+
   context "with concurrency" do
     let(:options) { Hash[:concurrency => "alpha=2"] }
 

spec/foreman/process_spec.rb

@@ -121,11 +121,25 @@ describe Foreman::Process do
         output.should include('777')
       end
 
-      it 'should handle arguments' do
-        pending
+      it 'should handle multi-word arguments (old test)' do
+        # TODO: This test used to be marked pending; it now passes,
+        # but is very slow.  The next test is a fast replacement.
         run %{ sh -c "trap '' TERM; sleep 10" }
         subject.should be_alive
       end
+
+      it 'should handle multi-word arguments' do
+        # We have to be a little clever here since Foreman will always
+        # print a status message that includes the command.
+        run %{ sh -c 'echo abcdef | tr a-c x | tr d-f y' }
+        output.should include('xxxyyy')
+      end
+
+      it 'should not clobber "$x"-subexpressions' do
+        pending 'this conflicts with the variable interpolation hack'
+        run %{ sh -c 'echo \$abcdef | tr \$ %' }
+        output.should include('%abcdef')
+      end
     end
   end
 end

spec/foreman/procfile_entry_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+require 'foreman/procfile_entry'
+require 'pathname'
+require 'tmpdir'
+
+describe Foreman::ProcfileEntry do
+  subject { described_class.new('alpha', './alpha') }
+
+  it "stringifies as a Procfile line" do
+    subject.to_s.should == 'alpha: ./alpha'
+  end
+
+end

spec/foreman/procfile_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+require 'foreman/procfile'
+require 'pathname'
+require 'tmpdir'
+
+describe Foreman::Procfile do
+  subject { described_class.new }
+
+  let(:testdir) { Pathname(Dir.tmpdir) }
+  let(:procfile) { testdir + 'Procfile' }
+
+  it "can have a process appended to it" do
+    subject << ['alpha', './alpha']
+    subject['alpha'].should be_a(Foreman::ProcfileEntry)
+  end
+
+  it "can write itself out to a file" do
+    subject << ['alpha', './alpha']
+    subject.write(procfile)
+    procfile.read.should == "alpha: ./alpha\n"
+  end
+
+  it "can re-read entries from a file" do
+    procfile.open('w') { |io| io.puts "gamma: ./radiation", "theta: ./rate" }
+    subject << ['alpha', './alpha']
+    subject.load(procfile)
+    subject.process_names.should have(2).members
+    subject.process_names.should include('gamma', 'theta')
+  end
+
+end

spec/foreman_spec.rb

@@ -8,24 +8,6 @@ describe Foreman do
     it { should be_a String }
   end
 
-  describe "::load_env!(env_file)", :fakefs do
-    after do
-      ENV['FOO'] = nil
-    end
-
-    it "should load env_file into ENV" do
-      File.open("/tmp/env1", "w") { |f| f.puts("FOO=bar") }
-      Foreman.load_env!("/tmp/env1")
-      ENV['FOO'].should == 'bar'
-    end
-
-    it "should assume env_file in ./.env" do
-      File.open("./.env", "w") { |f| f.puts("FOO=bar") }
-      Foreman.load_env!
-      ENV['FOO'].should == 'bar'
-    end
-  end
-
   describe "runner" do
     it "should exist" do
       File.exists?(Foreman.runner).should == true

spec/resources/export/bluepill/app-concurrency.pill

@@ -13,6 +13,7 @@ Bluepill.application("app", :foreground => false, :log_file => "/var/log/bluepil
     process.daemonize = true
     process.environment = {"PORT" => "5000"}
     process.stop_signals = [:quit, 30.seconds, :term, 5.seconds, :kill]
+    process.stop_grace_time = 45.seconds
 
     process.stdout = process.stderr = "/var/log/app/app-alpha-1.log"
 
@@ -31,6 +32,7 @@ Bluepill.application("app", :foreground => false, :log_file => "/var/log/bluepil
     process.daemonize = true
     process.environment = {"PORT" => "5001"}
     process.stop_signals = [:quit, 30.seconds, :term, 5.seconds, :kill]
+    process.stop_grace_time = 45.seconds
 
     process.stdout = process.stderr = "/var/log/app/app-alpha-2.log"
 

spec/resources/export/bluepill/app.pill

@@ -13,6 +13,7 @@ Bluepill.application("app", :foreground => false, :log_file => "/var/log/bluepil
     process.daemonize = true
     process.environment = {"PORT" => "5000"}
     process.stop_signals = [:quit, 30.seconds, :term, 5.seconds, :kill]
+    process.stop_grace_time = 45.seconds
 
     process.stdout = process.stderr = "/var/log/app/app-alpha-1.log"
 
@@ -30,6 +31,7 @@ Bluepill.application("app", :foreground => false, :log_file => "/var/log/bluepil
     process.daemonize = true
     process.environment = {"PORT" => "5100"}
     process.stop_signals = [:quit, 30.seconds, :term, 5.seconds, :kill]
+    process.stop_grace_time = 45.seconds
 
     process.stdout = process.stderr = "/var/log/app/app-bravo-1.log"
 

spec/resources/export/launchd/launchd-a.default

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>app-alpha-1</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>./alpha</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardErrorPath</key>
+    <string>/var/log/app/app-alpha-1.log</string>
+    <key>UserName</key>
+    <string>app</string>
+    <key>WorkingDirectory</key>
+    <string>/tmp/app</string>
+</dict>
+</plist>

spec/resources/export/launchd/launchd-b.default

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>app-bravo-1</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>./bravo</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardErrorPath</key>
+    <string>/var/log/app/app-bravo-1.log</string>
+    <key>UserName</key>
+    <string>app</string>
+    <key>WorkingDirectory</key>
+    <string>/tmp/app</string>
+</dict>
+</plist>

spec/resources/export/supervisord/app-alpha-2.conf

@@ -0,0 +1,24 @@
+
+[program:app-alpha-1]
+command=./alpha
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/alpha-1-out.log
+stderr_logfile=/var/log/app/alpha-1-err.log
+user=app
+directory=/tmp/app
+environment=PORT="5000"
+[program:app-alpha-2]
+command=./alpha
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/alpha-2-out.log
+stderr_logfile=/var/log/app/alpha-2-err.log
+user=app
+directory=/tmp/app
+environment=PORT="5001"
+
+[group:app]
+programs=app-alpha-1,app-alpha-2

spec/resources/export/supervisord/app-env-with-comma.conf

@@ -0,0 +1,24 @@
+
+[program:app-alpha]
+command=./alpha
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/alpha-1-out.log
+stderr_logfile=/var/log/app/alpha-1-err.log
+user=app
+directory=/tmp/app
+environment=QUEUE="fastqueue,slowqueue",VERBOSE="1",PORT="5000"
+[program:app-bravo]
+command=./bravo
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/bravo-1-out.log
+stderr_logfile=/var/log/app/bravo-1-err.log
+user=app
+directory=/tmp/app
+environment=QUEUE="fastqueue,slowqueue",VERBOSE="1",PORT="5100"
+
+[group:app]
+programs=app-alpha,app-bravo

spec/resources/export/supervisord/app-env.conf

@@ -0,0 +1,21 @@
+
+[program:app-alpha]
+command=./alpha
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/alpha-1-out.log
+stderr_logfile=/var/log/app/alpha-1-err.log
+user=app
+directory=/tmp/app
+environment=FOO="bar",PORT="5000"
+[program:app-bravo]
+command=./bravo
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/bravo-1-out.log
+stderr_logfile=/var/log/app/bravo-1-err.log
+user=app
+directory=/tmp/app
+environment=FOO="bar",PORT="5100"

spec/resources/export/supervisord/app.conf

@@ -0,0 +1,24 @@
+
+[program:app-alpha]
+command=./alpha
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/alpha-1-out.log
+stderr_logfile=/var/log/app/alpha-1-err.log
+user=app
+directory=/tmp/app
+environment=PORT="5000"
+[program:app-bravo]
+command=./bravo
+autostart=true
+autorestart=true
+stopsignal=QUIT
+stdout_logfile=/var/log/app/bravo-1-out.log
+stderr_logfile=/var/log/app/bravo-1-err.log
+user=app
+directory=/tmp/app
+environment=PORT="5100"
+
+[group:app]
+programs=app-alpha,app-bravo

tasks/release.rake

@@ -27,14 +27,6 @@ task :pages => "man:commit" do
   }
 end
 
-desc "Generate an authors list"
-task :authors do
-  authors = %x{ git log --pretty=format:"%an" | sort -u }.split("\n")
-  readme = File.read("README.md")
-  readme.gsub!(/#### Patches contributed by\n([^\n]*)\n/m, "#### Patches contributed by\n#{authors.join(", ")}\n")
-  File.open("README.md", "w") { |f| f.print readme }
-end
-
 def latest_release
   latest = File.read("Changelog.md").split("\n").first.split(" ")[1]
 end