minvee 0.0.1

data/lib/minvee/serverbox.rb

@@ -0,0 +1,2038 @@
+require 'minvee'
+require 'timeout'
+require 'json'
+require 'json/file'
+require 'open3'
+require 'pathname'
+require 'securerandom'
+require 'fileutils'
+require 'date'
+require 'xeme'
+require 'nokogiri/plus'
+# require 'exception/plus'
+
+
+#===============================================================================
+# Minvee::ServerBox
+#
+module Minvee::ServerBox
+	#---------------------------------------------------------------------------
+	# timeout
+	#
+	@@timeout = 60 * 100
+	
+	def self.timeout(opts={})
+		return opts['timeout'] || @@timeout
+	end
+	#
+	# timeout
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# default paths
+	#
+	@@paths = {}
+	@@paths['zip'] = '/usr/bin/zip'
+	@@paths['unzip'] = '/usr/bin/unzip'
+	@@paths['tar'] = '/bin/tar'
+	@@paths['diff'] = '/usr/bin/diff'
+	@@paths['xdelta3'] = '/usr/bin/xdelta3'
+	@@paths['tmp'] = '/tmp'
+	@@paths['file'] = '/usr/bin/file'
+	@@paths['md5sum'] = '/usr/bin/md5sum'
+	
+	# accessor
+	def self.paths
+		return @@paths
+	end
+	
+	# path to repo merge-requests dir
+	MERGE_REQUESTS_DIR = 'merge-requests'
+	
+	#
+	# paths
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# get_path
+	# TODO: Clean up the process for setting/getting paths
+	#
+	def self.get_path(path_id)
+		# $tm.hrm
+		
+		# get possibilities
+		poss = *@@paths[path_id]
+		
+		# TESTING
+		# $tm.show poss
+		
+		# loop through possibilities until we find a real file
+		poss.each do |path|
+			if File.exist?(path)
+				return path
+			end
+		end
+		
+		# did not find a path
+		raise 'did not find a path for ' + path_id.to_s
+	end
+	#
+	# get_path
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# path shortcuts
+	#
+	def self.zip
+		return self.get_path('zip')
+	end
+	
+	def self.unzip
+		return self.get_path('unzip')
+	end
+	
+	def self.tar
+		return self.get_path('tar')
+	end
+	
+	def self.diff
+		return self.get_path('diff')
+	end
+	
+	def self.tmp
+		return self.get_path('tmp')
+	end
+	#
+	# path shortcuts
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# dirs_same
+	#
+	def self.dirs_same(a, b)
+		# $tm.hrm
+		
+		# build cmd
+		cmd = [
+			Minvee::ServerBox.diff,
+			'--brief',
+			'--recursive',
+			a,
+			b,
+		]
+		
+		# run command
+		results = Open3.capture3(*cmd)
+		
+		# return
+		return results[0] == ''
+	end
+	#
+	# dirs_same
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_delta
+	#
+	def self.build_delta(old_tgz, new_tgz, opts={})
+		# $tm.hrm
+		
+		# get tmp path
+		zip_tgt = self.TempPath('ext'=>'delta')
+		
+		# build command
+		# xdelta3 -q -s revision.2.tgz revision.2.tgz revision.1.delta
+		cmd = [
+			Minvee::ServerBox.get_path('xdelta3'),
+			'-q',
+			'-s',
+			new_tgz,
+			old_tgz,
+			zip_tgt,
+		]
+		
+		# run command
+		Timeout::timeout(Minvee::ServerBox.timeout(opts)) do
+			system(*cmd)
+		end
+		
+		# return
+		return zip_tgt
+	end
+	#
+	# build_delta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# TempPath
+	#
+	def self.TempPath(opts={})
+		return Minvee::Utils::TempPath.new(self.tmp, opts)
+	end
+	#
+	# TempPath
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# TempDir
+	#
+	def self.TempDir(opts={})
+		return Minvee::Utils::TempDir.new(self.tmp, opts)
+	end
+	#
+	# TempDir
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# extract_tgz
+	#
+	def self.extract_tgz(src_path)
+		# $tm.hrm
+		
+		# tmp_dir
+		tmp_dir = Minvee::ServerBox.TempDir()
+		
+		# extract into tmp dir
+		Dir.chdir(tmp_dir) do
+			#$tm.hr("extract #{src_path}") do
+			
+			# run extract command
+			cmd = [Minvee::ServerBox.tar, '-xzf', src_path]
+			sysrv = Open3.capture3(*cmd)
+			
+			# if error, output and exit
+			# TODO: Need to throw proper exception when there's an error.
+			if sysrv[1].match(/\S/mu)
+				raise sysrv[1]
+				exit
+			end
+		end
+		
+		# return
+		return tmp_dir
+	end
+	#
+	# extract_tgz
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# tgz_from_delta
+	#
+	def self.tgz_from_delta(delta_path, tgz_path)
+		# $tm.hrm
+		
+		# get temp path
+		temp_tgz = self.TempPath('ext'=>'tgz')
+		
+		# build command
+		# xdelta3 -q -d -s revision.2.tgz revision.1.delta revision.1.restored.tgz
+		cmd = [
+			Minvee::ServerBox.get_path('xdelta3'),
+			'-q',
+			'-d',
+			'-s',
+			tgz_path,
+			delta_path,
+			temp_tgz
+		]
+		
+		# run command
+		system(*cmd)
+		
+		# return
+		return temp_tgz
+	end
+	#
+	# tgz_from_delta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# diff_compare
+	# Given two arrays of strings, uses Diff::LCS to produce a structure that
+	# holds both complete arrays, and indicates the addition, subtraction or
+	# staying the same for each element as the first array is transformed into
+	# the second array.
+	#
+	def self.diff_compare(myorg, mynew)
+		# $tm.hrm
+		
+		# get diff
+		mydiff = Diff::LCS.sdiff(myorg, mynew)
+		
+		# initialize changes array
+		changes_full = []
+		changes_compact = []
+		
+		# build changes array
+		mydiff.each do |change|
+			# convenience
+			myold = change.old_element
+			mynew = change.new_element
+			
+			# if they're the same
+			if myold == mynew
+				changes_full.push ( {'action' => 's', 'str' => myold} )
+				
+				# else get old and new
+			else
+				# old element
+				if not myold.nil?
+					changes_full.push ( {'action' => '-', 'str' => myold} )
+				end
+				
+				# new element
+				if not mynew.nil?
+					changes_full.push ( {'action' => '+', 'str' => mynew} )
+				end
+			end
+		end
+		
+		# initialize latest action
+		latest_action = ''
+		
+		# compact
+		changes_full.each_with_index do |change, index|
+			# if same action as last iteration
+			if change['action'] == latest_action
+				changes_compact[-1]['strs'].push(change['str'])
+				
+				# else different action
+			else
+				changes_compact.push( {'action'=>change['action'], 'strs'=>[change['str']] } )
+				latest_action = change['action']
+			end
+		end
+		
+		# return
+		return changes_compact
+	end
+	#
+	# diff_compare
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# show_comparison
+	# A convienience method for displaying the contents of a comparison
+	# structure. Don't use this method in production work.
+	#
+	def self.show_comparison(mycomp)
+		# Testmin.hr(__method__.to_s)
+		
+		mycomp.each do |change|
+			puts change['action'] + '  ' + change['strs'].show
+		end
+	end
+	#
+	# show_comparison
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# tree_description
+	#
+	def self.tree_description(root)
+		# $tm.hrm
+		
+		# initialize return hash
+		rv = {}
+		
+		# traverse tree
+		content = rv['content'] = {}
+		content['name'] = 'content'
+		content['uuid'] = SecureRandom.uuid
+		self.dir_description root, content
+		
+		# remove minvee.json
+		rv['content']['files'].delete('minvee.json')
+		
+		# return
+		return rv
+	end
+	#
+	# tree_description
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# dir_description
+	#
+	def self.dir_description(dir_name, dir)
+		# $tm.hrm
+		
+		# initialize return hash
+		dir['type'] = 'dir'
+		dir['files'] = {}
+		
+		# go to dir
+		Dir.chdir(dir_name) do
+			# get list of files
+			entries = Dir.entries('.')
+			entries = entries.grep_v(/\A\.+\z/)
+			
+			# loop through files
+			entries.each do |file_name|
+				# KLUDGE
+				# I really hate unconditionally untainting any variable.
+				# However, there doesn't seem to be any good way to test if a
+				# given file name references a directory. Given that we just got
+				# this file name from the current directory, it should be ok to
+				# untaint the string.
+				# file_name.untaint
+				
+				# file meta
+				file = dir['files'][file_name] = {}
+				
+				# add file name
+				# KLUDGE: It feels awkward adding the file name to the meta hash
+				# given that the file name is already the in the dir['files'].
+				# However, it was getting awkward passing around thew file name
+				# and other file meta info as separate pieces of information.
+				file['name'] = file_name
+				
+				# uuid
+				file['uuid'] = SecureRandom.uuid
+				
+				# symlink
+				if File.symlink?(file_name)
+					self.symlink_description file_name, file
+				
+				# directory
+				elsif File.directory?(file_name)
+					self.dir_description file_name, file
+				
+				# file
+				else
+					self.file_description file_name, file
+				end
+			end
+		end
+	end
+	#
+	# dir_description
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# symlink_description
+	#
+	def self.symlink_description(file_name, file)
+		file['type'] = 'symlink'
+	end
+	#
+	# symlink_description
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# file_description
+	#
+	def self.file_description(file_name, file)
+		# $tm.hrm
+		
+		# return hash
+		file['type'] = 'file'
+		
+		# file size
+		file['size'] = File.size(file_name)
+		
+		# mime type
+		file['mime'] = file_mime(file_name)
+		
+		# md5sum
+		file['md5sum'] = file_md5sum(file_name)
+	end
+	#
+	# file_description
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# file_mime
+	#
+	def self.file_mime(file)
+		# build file command
+		cmd = [
+			Minvee::ServerBox.get_path('file'),
+			'--brief',
+			'--mime-type',
+			file,
+		];
+		
+		# run command
+		results = Open3.capture3(*cmd)
+		results[0].sub!(/\s+\z/imu, '')
+		
+		# return
+		return results[0]
+	end
+	#
+	# file_mime
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# file_md5sum
+	#
+	def self.file_md5sum(file)
+		# build file command
+		cmd = [
+			Minvee::ServerBox.get_path('md5sum'),
+			file,
+		];
+		
+		# run command
+		results = Open3.capture3(*cmd)
+		results[0].sub!(/\s.*\z/imu, '')
+		
+		# return
+		return results[0]
+	end
+	#
+	# file_mime
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# run
+	#
+	def self.run(cmd)
+		# $tm.hrm
+		# $tm.show cmd
+		
+		# run command
+		results = Open3.capture3(*cmd)
+		
+		# if error, output and exit
+		# TODO: Need to throw proper exception when there's an error.
+		if results[1].match(/\S/mu)
+			raise results[1]
+		end
+		
+		# return
+		return true
+	end
+	#
+	# run
+	#---------------------------------------------------------------------------
+end
+#
+# Minvee::ServerBox
+#===============================================================================
+
+
+#===============================================================================
+# Minvee::Project
+#
+class Minvee::Project
+	attr_reader :root
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(p_root)
+		# set @root
+		@root = p_root.dup
+		
+		# normalize @root
+		@root.sub!(/\/+\z/imu, '')
+		
+		# check that project exists
+		if not Dir.exist?(@root)
+			raise 'project-dir-found-not-exist'
+		end
+		
+		# TESTING
+		# if @root.match(/static\-3/mu)
+		#	$tm.hr do
+		#		$tm.puts 'calling ensure_revisions_dir()'
+		#		$tm.puts '@root: ' + @root
+		#	end
+		# end
+		
+		# ensure revisions directory
+		ensure_revisions_dir()
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# name
+	#
+	def name
+		# $tm.hrm
+		rv = root
+		rv = rv.sub(/\A.*\//mu, '')
+		return rv
+	end
+	#
+	# name
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# overrides
+	#
+	def revision_class
+		return Minvee::Project::Revision
+	end
+	#
+	# overrides
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# merge_request_names
+	#
+	def merge_request_names
+		# $tm.hrm
+		rv = []
+		
+		# if no merge requests dir, return empty
+		if not File.exist?(self.merge_requests_dir)
+			return rv
+		end
+		
+		# loop through files in merge requests dir
+		# Yes, I like to nest if's instead of having one long conditional.
+		Dir.chdir(self.merge_requests_dir) do
+			Dir.entries('./').each do |entry|
+				if entry.match(/\A[0-9\-\~\:]+\z/mu)
+					# untaint entry directory name
+					entry_ut = entry.dup
+					
+					# Having to remove untainting.
+					# entry_ut.untaint
+					
+					# check if this really appears to be a merge request
+					if File.directory?(entry_ut)
+						if File.exist?("#{entry_ut}/merge-request.json")
+							if File.exist?("#{entry_ut}/uploaded.tgz") or File.exist?("#{entry_ut}/uploaded.zip")
+								rv.push entry_ut
+							end
+						end
+					end
+				end
+			end
+		end
+		
+		# return
+		return rv.sort
+	end
+	#
+	# merge_request_names
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# merge_requests
+	#
+	def merge_requests
+		# $tm.hrm
+		rv = []
+		
+		# loop through names
+		merge_request_names.each do |name|
+			rv.push Minvee::Project::MergeRequest.new(self, name)
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# merge_requests
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# process_merge_requests
+	#
+	def process_merge_requests(opts={})
+		# $tm.hrm
+		verbose = opts['verbose']
+		id_output = false
+		
+		# run inside lock block
+		self.revision_dir_lock('x') do
+			# loop through merge requests
+			self.merge_requests.each do |mr|
+				if mr.approved
+					send_opts = opts.clone
+					xeme = Xeme.new
+					send_opts['xeme'] = xeme
+					mr.merge send_opts
+					
+					# verbosify
+					if verbose and (not xeme.misc['already_up_to_date'])
+						if not id_output
+							puts self.name
+							id_output = true
+						end
+						
+						puts "\t" + xeme.misc['revision'].to_s
+					end
+				end
+			end
+		end
+	end
+	#
+	# process_merge_requests
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# working_copy_same_as_latest
+	#
+	def working_copy_same_as_latest(wc_path)
+		# $tm.hrm
+		
+		# if no revisions, return false
+		if not self.any_revisions?
+			return false
+		end
+		
+		# put inside block to close rev_path
+		begin
+			# get latest revision
+			rev_path = self.latest_revision_extracted()
+			
+			# TESTING
+			# puts 'latest: ' + rev_path + '/content'
+			# puts 'new:    ' + wc_path
+			
+			# compare the two directories
+			return Minvee::ServerBox.dirs_same(rev_path + '/content', wc_path)
+		ensure
+			if rev_path.respond_to?('close')
+				rev_path.close
+			end
+		end
+	end
+	#
+	# working_copy_same_as_latest
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# latest_revision_extracted
+	#
+	def latest_revision_extracted
+		# $tm.hrm
+		
+		# if no revisions
+		if not self.any_revisions?
+			return nil
+		end
+		
+		# get latest revision number
+		tgz_path = self.revision_path(self.latest_revision_number)
+		
+		# return
+		return Minvee::ServerBox.extract_tgz(tgz_path)
+	end
+	#
+	# latest_revision_extracted
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# paths
+	#
+	def revisions_dir
+		return @root + '/revisions'
+	end
+	
+	def merge_requests_dir
+		return @root + '/' + Minvee::ServerBox::MERGE_REQUESTS_DIR
+	end
+	
+	def revision_dir(number)
+		return self.revisions_dir + '/' + number.to_s
+	end
+	
+	def revision_path(number, opts={})
+		# $tm.hrm
+		
+		# number must be defined
+		if number.nil?
+			raise 'revision-path-nil'
+		end
+		
+		# default opts
+		opts = {'ext'=>'tgz'}.merge(opts)
+		
+		# return dir
+		return revision_dir(number) + '/revision.' + opts['ext']
+	end
+	
+	def delta_path(number)
+		return revision_dir(number) + '/revision.delta'
+	end
+	#
+	# paths
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# ensure directories
+	#
+	def ensure_revisions_dir
+		FileUtils::mkdir_p self.revisions_dir
+	end
+	
+	def ensure_merge_requests_dir
+		FileUtils::mkdir_p self.merge_requests_dir
+	end
+	#
+	# ensure directories
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# revision_dir_lock
+	#
+	def revision_dir_lock(p_lock_type, opts={})
+		# $tm.hrm
+		
+		# ensure existence of revisions dir
+		self.ensure_revisions_dir()
+		
+		# get lock type
+		if p_lock_type == 'x'
+			lock_type = File::LOCK_EX
+		else
+			lock_type = File::LOCK_SH
+		end
+		
+		# get timeout
+		timeout = Minvee::ServerBox.timeout(opts)
+		
+		# set timeout, get lock on revisions directory
+		Timeout::timeout(timeout) do
+			File.open(self.revisions_dir + '/lock.txt', 'a') do |lock|
+				lock.flock(lock_type)
+				
+				# yield, but ensure unlock
+				begin
+					yield()
+				ensure
+					lock.flock(File::LOCK_UN)
+				end
+			end
+		end
+	end
+	#
+	# revision_dir_lock
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# revision_tmp_to_zip
+	#
+	def revision_tmp_to_zip(revision_tmp, opts={})
+		# $tm.hrm
+		
+		# default opts
+		opts = {'save'=>true}.merge(opts)
+		
+		# new revision number
+		new_number = self.next_revision_number
+		
+		# zip to revisions dir
+		zip_tgt = self.zip_revision(revision_tmp)
+		
+		# we don't need the revision_tmp dir anymore
+		revision_tmp.close
+		
+		# move file, except if indicated not to
+		if opts['save']
+			FileUtils.mkdir_p self.revision_dir(new_number)
+			FileUtils.mv zip_tgt, self.revision_path(new_number)
+		end
+		
+		# return next_revision
+		return new_number
+	end
+	#
+	# revision_tmp_to_zip
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# revision_files
+	#
+	def revision_files()
+		Dir[self.revisions_dir + '/revision.*'].each do |file|
+			file.match(/revision\.(\d+)\.(?:delta|tgz)/imu) do |m|
+				if c = m.captures[0]
+					# untaint c
+					# Yes, we're doing an extra pattern check here.
+					if c.match(/\A\d+\z/imu)
+						# Having to remove untainting.
+						# c.untaint
+					else
+						raise 'invalid-revision-number-pattern'
+					end
+					
+					# yield
+					yield c.to_i
+				end
+			end
+		end
+	end
+	#
+	# revision_files
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# latest_revision_number
+	#
+	def latest_revision_number()
+		# $tm.hrm
+		return self.revision_numbers[0]
+	end
+	#
+	# latest_revision_number
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# next_revision_number
+	#
+	def next_revision_number
+		if lrn = self.latest_revision_number
+			return lrn + 1
+		else
+			return 1
+		end
+	end
+	#
+	# next_revision_number
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# revision_numbers
+	#
+	def revision_numbers(opts={})
+		# $tm.hrm
+		rv = []
+		
+		# early exit: no revisions dir
+		if not File.exist?(self.revisions_dir)
+			return rv
+		end
+		
+		# loop through files
+		Dir.entries(self.revisions_dir).each do |file|
+			if file.match(/\A\d+\z/)
+				if opts['any']
+					return true
+				end
+				
+				num = file.to_i
+				rv.push num
+			end
+		end
+		
+		# if we get this far with the any option, there are no revisions
+		if opts['any']
+			return false
+		end
+		
+		# return sorted and reversed
+		return rv.sort.reverse
+	end
+	#
+	# revision_numbers
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# revision
+	#
+	def revision(num)
+		# return Minvee::Project::Revision.new(self, num)
+		return revision_class.new(self, num)
+	end
+	#
+	# revision
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# revisions
+	#
+	def revisions
+		rv = nil
+		
+		self.revision_numbers.each do |num|
+			rev = self.revision(num)
+			
+			if block_given?
+				yield rev
+			else
+				rv ||= []
+				rv.push rev
+			end
+		end
+		
+		if block_given?
+			return nil
+		else
+			return rv || []
+		end
+	end
+	#
+	# revisions
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# any_revisions?
+	#
+	def any_revisions?()
+		# $tm.hrm
+		return self.revision_numbers('any'=>true)
+	end
+	#
+	# any_revisions?
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# latest_revision
+	#
+	def latest_revision
+		# $tm.hrm
+		if lrn = self.latest_revision_number()
+			return self.revision(lrn)
+		else
+			return nil
+		end
+	end
+	#
+	# latest_revision
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# next_needed_delta
+	#
+	def next_needed_delta
+		# $tm.hrm
+		
+		# get numbers
+		numbers = self.revision_numbers
+		
+		# remove latest revision number, which does not ever need a delta
+		numbers.shift
+		
+		# if less than one, nothing to do
+		if numbers.length < 1
+			return nil
+		end
+		
+		# loop through numbers until we find a revision that doesn't have a delta
+		numbers.each do |num|
+			# build path
+			path = self.revisions_dir + '/' + num.to_s + '/revision.delta'
+			
+			# if delta file doesn't exist, return the number
+			if not File.exist?(path)
+				return num
+			end
+		end
+		
+		# return nil
+		return nil
+	end
+	#
+	# next_needed_delta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# extract_revision
+	#
+	# def extract_revision(revision_number)
+	# 	# $tm.hrm
+	# 	
+	# 	# get path to revision file
+	# 	tgz_path = rev = self.revision(revision_number).tgz_path
+	# 	
+	# 	# path to extracted dir
+	# 	tmp_dir = Minvee::ServerBox.extract_tgz(tgz_path)
+	# 	
+	# 	# yield or return
+	# 	if block_given?
+	# 		begin
+	# 			yield tmp_dir
+	# 		ensure
+	# 			tmp_dir.close
+	# 		end
+	# 	else
+	# 		return tmp_dir
+	# 	end
+	# end
+	#
+	# extract_revision
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# tgz_to_delta
+	#
+	def tgz_to_delta(old_num, new_num, opts={})
+		# $tm.hrm
+				
+		# verbosify
+		if opts['verbose']
+			puts "	#{old_num} -> #{new_num}"
+		end
+		
+		# paths
+		old_tgz_path = self.revision_path(old_num)
+		
+		# check that old revision exists
+		if not File.exist?(old_tgz_path)
+			raise 'do-not-have-old-revision: ' + old_tgz_path
+		end
+		
+		# tgz for newer revision
+		new_tgz_path = self.revision(new_num).tgz
+		
+		# build delta
+		tmp_delta = Minvee::ServerBox.build_delta(old_tgz_path, new_tgz_path)
+		
+		# move into revisions dir
+		FileUtils.mv tmp_delta, self.delta_path(old_num)
+		
+		# delete old_tgz_path, which is now no longer needed
+		File.delete old_tgz_path
+	
+	# always close temp path
+	ensure
+		if new_tgz_path.respond_to?('close')
+			new_tgz_path.close
+		end
+	end
+	#
+	# tgz_to_delta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_needed_deltas
+	#
+	def build_needed_deltas(opts={})
+		# $tm.hrm
+		verbose = opts['verbose']
+		verbosified = false
+		
+		# while there are more deltas
+		while needed = self.next_needed_delta
+			if verbose and (not verbosified) and (not opts['title_verbosified'])
+				puts @root
+				verbosified = true
+			end
+			
+			# create delta
+			self.tgz_to_delta needed, needed + 1, opts
+		end
+	end
+	#
+	# build_needed_deltas
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# latest_tgz
+	#
+	def latest_tgz
+		# $tm.hrm
+		
+		# loop through revisions
+		self.revisions do |rev|
+			tgz_path = rev.root + '/revision.tgz'
+			
+			if File.exist?(tgz_path)
+				return tgz_path
+			end
+		end
+		
+		# don'thave latest
+		return nil
+	end
+	#
+	# latest_tgz
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# delete_tmp_files
+	#
+	def delete_tmp_files
+		# $tm.hrm
+		
+		# loop through tmp files
+		Dir[self.revisions_dir + '/*.tmp'].each do |file|
+			File.delete(file)
+		end
+	end
+	#
+	# delete_tmp_files
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# clean_revisions_dir
+	#
+	def clean_revisions_dir(opts={})
+		# $tm.hrm
+		
+		# run inside lock block
+		self.revision_dir_lock('x', opts) do
+			# build deltas as needed
+			self.build_needed_deltas()
+			
+			# clean out tmp files
+			self.delete_tmp_files()
+			
+			# revision descriptions
+			self.build_revision_descriptions()
+		end
+	end
+	#
+	# clean_revisions_dir
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_revision_metas
+	#
+	def build_revision_metas(opts={})
+		# $tm.hrm
+		opts['verbose'] and puts @root
+		
+		# loop through revisions
+		self.revisions.reverse.each do |rev|
+			rev.build_meta opts
+		end
+	end
+	#
+	# build_revision_metas
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# meta_file_path
+	#
+	def meta_file_path(rev_num)
+		return "#{self.revisions_dir}/#{rev_num}/revision.json"
+	end
+	#
+	# meta_file_path
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_revision_meta
+	#
+	def build_revision_meta(rev_dir)
+		# $tm.hrm
+		# puts 'rev_dir: ' + rev_dir
+		
+		# go into revision dir
+		Dir.chdir(rev_dir) do
+			rev = {}
+			mrj_path = './revision/merge-request.json'
+			
+			# slurp in save.json
+			# KLUDGE: For now, silently rescuing if there's an error
+			# reading or parsing the save.json file.
+			if File.exist?(mrj_path)
+				begin
+					mrj = JSON.parse(File.read mrj_path)
+					rev['merge-request'] = mrj
+				rescue
+				end
+			end
+			
+			# get tree description
+			rev['tree'] = Minvee::ServerBox.tree_description('./content')
+			
+			# return
+			return rev
+		end
+	end
+	#
+	# build_revision_meta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# summary
+	#
+	def summary()
+		# $tm.hrm
+		rv = {}
+		
+		# basic info
+		rv['root'] = self.root
+		
+		# revisions hash
+		revs_arr = rv['revisions'] = []
+		
+		# loop through revisions
+		self.revisions() do |rev|
+			rev_hsh = {}
+			revs_arr.push rev_hsh
+			meta = rev.meta
+			
+			# basic info
+			rev_hsh['num'] = rev.num
+			rev_hsh['saved'] = meta['saved']
+			rev_hsh['merge-request'] = meta['merge-request']
+			
+			# additional info from subclasses
+			summary_rev_additional rev, rev_hsh
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# summary
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# summary_rev_additional
+	#
+	def summary_rev_additional(rev, rev_hsh)
+	end
+	#
+	# summary_additional
+	#---------------------------------------------------------------------------
+end
+#
+# Minvee::Project
+#===============================================================================
+
+
+#===============================================================================
+# Minvee::Project::MergeRequest
+#
+class Minvee::Project::MergeRequest
+	attr_reader :project
+	attr_reader :name
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(p_project, p_name)
+		# $tm.hrm
+		@project = p_project
+		@name = p_name
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# root
+	#
+	def root
+		return @project.root + '/merge-requests/' + @name
+	end
+	#
+	# root
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# approved
+	#
+	def approved
+		if status = self.meta['status']
+			return status['approved']
+		end
+		
+		return false
+	end
+	#
+	# approved
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# meta
+	#
+	def meta
+		# $tm.hrm
+		return JSON.parse(File.read self.root + '/merge-request.json')
+	end
+	#
+	# meta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# uploaded_path
+	#
+	def uploaded_path
+		# $tm.hrm
+		
+		# loop through extension possibilities
+		['tgz', 'zip'].each do |ext|
+			rv = self.root + '/uploaded.' + ext
+			
+			if File.exist?(rv)
+				return rv
+			end
+		end
+		
+		# error: could not find uploaded file
+		raise 'merge-request-no-uploaded-file'
+	end
+	#
+	# uploaded_path
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_save_revision
+	#
+	def build_save_revision()
+		# $tm.hrm
+		
+		# go into content directory
+		Dir.chdir('./content') do |content_dir|
+			# run command
+			cmd = [Minvee::ServerBox.tar, '-xzf', self.uploaded_path]
+			sysrv = Open3.capture3(*cmd)
+			
+			# if error, output and exit
+			if sysrv[1].match(/\S/mu)
+				raise 'build-save-revision-unzip-error: ' + sysrv[1]
+			end
+			
+			# delete minvee.json, which is only relevent to working copies
+			if File.exist?('./minvee.json')
+				File.delete('./minvee.json')
+			end
+		end
+	end
+	#
+	# build_save_revision
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# merge
+	#
+	def merge(opts={})
+		# $tm.hrm
+		
+		# create a temp directory for processing this revision
+		revision_tmp = Minvee::ServerBox.TempDir()
+		
+		# change into revision_tmp
+		Dir.chdir(revision_tmp) do
+			# create revision and content dir
+			FileUtils::mkdir_p './revision'
+			FileUtils::mkdir_p './content'
+			
+			# build revision dir
+			self.build_save_revision()
+			
+			# check if working copy is identical to latest revision
+			if @project.working_copy_same_as_latest(revision_tmp + '/content')
+				# note results
+				if xeme = opts['xeme']
+					xeme.misc['already_up_to_date'] = true
+					xeme.misc['revision'] = @project.latest_revision_number
+				end
+			else
+				# path to merge-request.json
+				mrj_path = self.root + '/merge-request.json'
+				
+				# copy merge-request.json
+				if File.exist?(mrj_path)
+					FileUtils.cp mrj_path, './revision/merge-request.json'
+				end
+				
+				# build meta file
+				File.write 'revision/revision.json', JSON.pretty_generate(@project.build_revision_meta(revision_tmp))
+				
+				# zip content into revision dir
+				self.zip_content()
+				
+				# move into final destination
+				self.commit revision_tmp
+				
+				# note results
+				if xeme = opts['xeme']
+					xeme.misc['already_up_to_date'] = false
+					xeme.misc['revision'] = @project.latest_revision_number
+				end
+			end
+		end
+		
+		# delete own directory
+		self.delete_self()
+		
+		# note success
+		# if xeme = opts['xeme']
+		#	xeme.succeed
+		# end
+		
+		# return success
+		return true
+	end
+	#
+	# merge
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# delete_self
+	#
+	def delete_self
+		if File.exist?(self.root)
+			FileUtils.rm_rf self.root
+		end
+	end
+	#
+	# delete_self
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# commit
+	#
+	def commit(revision_tmp)
+		# $tm.hrm
+		@project.ensure_revisions_dir
+		src = revision_tmp + '/revision'
+		tgt = @project.root + '/revisions/' + @project.next_revision_number.to_s
+		FileUtils.mv src, tgt
+		return true
+	end
+	#
+	# commit
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# zip_content
+	#
+	def zip_content()
+		# $tm.hr(__method__.to_s)
+		
+		# build command
+		cmd = [
+			Minvee::ServerBox.tar,
+			'-czf',
+			'./revision/revision.tgz',
+			'./content'
+		]
+		
+		# TODO: Run with open3
+		# run system command
+		system(*cmd)
+	end
+	#
+	# zip_content
+	#---------------------------------------------------------------------------
+end
+#
+# Minvee::Project::MergeRequest
+#===============================================================================
+
+
+#===============================================================================
+# Minvee::Project::Revision
+#
+class Minvee::Project::Revision
+	attr_reader :project
+	attr_reader :num
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(p_project, p_num)
+		@meta_file_cache = nil
+		@project = p_project
+		@num = p_num
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# paths
+	#
+	def root
+		return @project.root + '/revisions/' + @num.to_s
+	end
+	
+	def tgz_path
+		return root + '/revision.tgz'
+	end
+	
+	def meta_path
+		return root + '/revision.json'
+	end
+	#
+	# paths
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# meta
+	#
+	def meta()
+		return JSON.parse( ::File.read(meta_path()) )
+	end
+	#
+	# meta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# meta_file
+	#
+	def meta_file()
+		# create cache if necessary
+		if @meta_file_cache.nil?
+			@meta_file_cache = JSON::File.new(meta_path())
+			@meta_file_cache.locked = true
+		end
+		
+		# return cache
+		return @meta_file_cache
+	end
+	#
+	# meta_file
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# timestamp
+	#
+	def timestamp
+		begin
+			ts = meta['merge-request']['status']['timestamp']
+			return DateTime.parse(ts)
+		rescue
+			return nil
+		end
+	end
+	#
+	# timestamp
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# org_merge_request
+	# NOTE: This routine looks for a file called "save.json" was used in an
+	# early version of Minvee. That file is only sought out if
+	# merge-request.json isn't present and if a tmp_dir was sent as an option.
+	#
+	def org_merge_request(opts={})
+		# $tm.hrm
+		mr_path = self.root + '/merge-request.json'
+		
+		# if revision.json exists
+		if File.exist?(mr_path)
+			return JSON.parse(File.read(mr_path))
+		elsif opts['tmp_dir']
+			save_path = opts['tmp_dir'] + '/save.json'
+			
+			if File.exist?(save_path)
+				return JSON.parse(File.read(save_path))
+			end
+		end
+		
+		# nothing found
+		return nil
+	end
+	#
+	# org_merge_request
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_meta
+	# KLUDGE: This routine is redundant to the routine that builds the meta
+	# information when the merge-request is committed.
+	#
+	def build_meta(opts={})
+		# if meta file doesn't exist, or force
+		if (not File.exist?(self.meta_path())) or opts['force']
+			opts['verbose'] and puts self.num
+			
+			# process in temp dir
+			@project.extract_revision(self.num) do |tmp_dir|
+				Dir.chdir(tmp_dir) do
+					rev = JSON::File.new(self.meta_path, 'create_ok'=>true)
+					rev.clear
+					
+					# merge request settings
+					if mr_settings = self.org_merge_request('tmp_dir'=>tmp_dir)
+						rev['merge-request'] = mr_settings
+					end
+					
+					# tree
+					rev['tree'] = Minvee::ServerBox.tree_description("#{tmp_dir}/content")
+					
+					# save
+					rev.save
+				end
+			end
+		end
+	end
+	#
+	# build_meta
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# next_revision
+	#
+	def next_revision()
+		# $tm.hrm
+		return @project.revision(@num + 1)
+	end
+	#
+	# next_revision
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# tgz
+	# KLUDGE: This routine gets a bit spaghettish.
+	#
+	def tgz()
+		# $tm.hrm
+		existing_path = self.root + '/revision.tgz'
+		
+		# TESTING
+		# puts 'existing_path: ' + existing_path
+		
+		# path to existing tgz if it exists, just use it
+		if ::File.exist?(existing_path)
+			# yield or return
+			if block_given?
+				yield existing_path
+				return nil
+			else
+				return existing_path
+			end
+		
+		# else build a path from deltas
+		else
+			# old_path
+			old_path = self.next_revision.tgz()
+			
+			# build tgz from delta
+			rv = Minvee::ServerBox.tgz_from_delta(self.root + '/revision.delta', old_path)
+			
+			# close old_path
+			if old_path.respond_to?('close')
+				old_path.close
+			end
+			
+			# yield or return
+			if block_given?
+				begin
+					yield rv
+				ensure
+					rv.close
+				end
+				
+				return nil
+			else
+				return rv
+			end
+		end
+	end
+	#
+	# tgz
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# extract
+	#
+	def extract
+		# $tm.hrm
+		
+		# source and extracted dir
+		src = self.tgz()
+		dir = Minvee::ServerBox.extract_tgz(src)
+		
+		# close source if necessary
+		if src.respond_to?('close')
+			src.close
+		end
+		
+		# yield or return
+		if block_given?
+			begin
+				yield dir
+			ensure
+				dir.close
+			end
+		else
+			return dir
+		end
+	end
+	#
+	# extract
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# extract_file
+	#
+	def extract_file(path)
+		# $tm.hrm
+		
+		# get tgz
+		tgz_path = self.tgz()
+		
+		# temp dir to extract file into
+		tmp_dir = Minvee::ServerBox.TempDir()
+		
+		# normalize path
+		path = path.sub(/\A\//mu, '')
+		path = 'content/' + path
+		
+		# build command
+		# tar --extract --one-top-level=out --file=revision.tgz
+		cmd = []
+		cmd.push Minvee::ServerBox.paths['tar']
+		cmd.push '--extract'
+		cmd.push '--file'
+		cmd.push tgz_path
+		cmd.push "./#{path}"
+		
+		# go to tmp dir and run command
+		Dir.chdir(tmp_dir) do
+			Minvee::ServerBox.run cmd
+		end
+		
+		# path to extracted file
+		extracted_path = tmp_dir + '/' + path
+		
+		# tmp path
+		tmp_path = Minvee::ServerBox.TempPath()
+		
+		# move file to tmp path
+		FileUtils.mv extracted_path, tmp_path
+		
+		# close tmp dir
+		tmp_dir.close()
+		
+		# return
+		return tmp_path
+		
+	# always close tgz_path
+	ensure
+		if tgz_path.respond_to?('close')
+			tgz_path.close
+		end
+	end
+	#
+	# extract_file
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# file
+	#
+	def file(uuid)
+		return Minvee::Project::Revision::File.new(self, uuid)
+	end
+	#
+	# file
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# summary
+	#
+	def summary
+	end
+	#
+	# summary
+	#---------------------------------------------------------------------------
+end
+#
+# Minvee::Project::Revision
+#===============================================================================
+
+
+#===============================================================================
+# Minvee::Project::Revision::File
+# TODO: This ancestor routines in this class could be a lot more efficient.
+#
+class Minvee::Project::Revision::File
+	attr_reader :uuid
+	attr_reader :rev
+	attr_reader :meta
+	attr_reader :ancestor_metas
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(p_rev, p_uuid)
+		@rev = p_rev
+		@uuid = p_uuid
+		@meta = nil
+		@ancestor_metas = nil
+		
+		# find file record
+		# search_file_for_uuid @rev.meta['tree']['content']
+		search_dir_for_uuid @rev.meta['tree']['content']
+		
+		# error if no meta
+		# if not @meta
+		#	# TESTING
+		#	puts 'do-not-find-uuid-for-file: ' + @uuid
+		#	$tm.devexit
+		#	
+		#	raise 'do-not-find-uuid-for-file: ' + @uuid
+		# end
+		
+		# freeze ancestor uuids
+		# @ancestor_uuids.freeze
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# simple accessors
+	#
+	def name
+		return @meta['name']
+	end
+	#
+	# simple accessors
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# path
+	#
+	def path
+		# $tm.hrm
+		names = []
+		
+		@ancestor_metas.each do |anc|
+			names.push anc['name']
+		end
+		
+		return '/' + names.join('/')
+	end
+	#
+	# path
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# ancestors
+	#
+	def ancestors
+		if v_parent = self.parent
+			rv = v_parent.ancestors
+			rv.push v_parent
+			return rv
+		else
+			return []
+		end
+	end
+	#
+	# ancestors
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# parent
+	#
+	def parent
+		# $tm.hrm
+		
+		# if there are any ancestors, return the first
+		if @ancestor_metas.any?
+			return @rev.file(@ancestor_metas[-1]['uuid'])
+		
+		# else return nil
+		else
+			return nil
+		end
+	end
+	#
+	# parent
+	#---------------------------------------------------------------------------
+	
+	
+	# private
+	private
+	
+	#---------------------------------------------------------------------------
+	# search_dir_for_uuid
+	#
+	def search_dir_for_uuid(dir, p_ancestors=[])
+		# indent = ' ' * p_ancestors.length
+		# puts indent + dir['name']
+		
+		# loop through files
+		dir['files'].values.each do |file|
+			# puts indent + '-' + file['name'] + ': ' + file['uuid']
+			
+			if file['uuid'] == @uuid
+				@meta = file
+				@ancestor_metas = p_ancestors
+				return true
+			end
+			
+			if file['type'] == 'dir'
+				if search_dir_for_uuid(file, p_ancestors + [file])
+					return true
+				end
+			end
+		end
+		
+		# didn't find the file
+		return false
+	end
+	#
+	# search_dir_for_uuid
+	#---------------------------------------------------------------------------
+end
+#
+# Minvee::Project::Revision::File
+#===============================================================================
+
+