kit 0.3.0 → 1.0.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+test_kit/

data/.yardopts

@@ -0,0 +1,2 @@
+--exclude spec/
+--exclude test_kit/

data/CHANGELOG.rdoc

@@ -1,10 +1,19 @@
 = Kit ChangeLog
 
+== 1.0.0
+
+=== Breaking changes
+
+Kit has been completely rewritten using Active Record.
+See the {README}[http://rubydoc.info/gems/kit/frames] and {wiki}[https://github.com/razor-x/kit/wiki] for new documentation.
+
 == 0.3.0
 
 === Breaking changes
 
-* Kits are now expected to have an actions.rb file and specific global action files in the actions directory. This allows one to write methods available to all actions and methods available to specific actions (helps with DRY).  See the skeleton kit for the updated structure.
+* Kits are now expected to have an actions.rb file and specific global action files in the actions directory.
+This allows one to write methods available to all actions and methods available to specific actions (helps with DRY).
+See the skeleton kit for the updated structure.
 
 === Enhancements
 

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Evan Boyd Sosenko
+
+MIT License
+
+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.rdoc

@@ -1,46 +1,111 @@
 = Kit
 
+<b>A framework for making simple management tools called kits.</b>
+
+<em>Write your shell scripts in beautiful Ruby, put them in a kit, and keep them DRY.</em>
+
 == What is Kit?
 
-Kit is a framework for making simple management tools called kits. Each kit keeps track of a set of objects (the bits) and info about them. Actions of different types can be queued as tasks and run separately. Bits are put into groups so that code for each action type can be different for each group. The tasks are stored in a separate database, so the permissions for adding tasks and managing bit meta information can be set separately.
+Kit is written using Active Record, so if you have worked with Rails, then Kit should feel familiar.
 
-== Using Kit
+Each kit keeps track of a set of objects (the bits) and info about them.
+Bits know how to preform actions you create for them,
+and can be put into groups so each type of bit can have its own set of actions.
+Users and permissions can be set to control access to bits and actions.
 
-To use Kit, you fist need a kit. You can download a {pre-build kit}[https://github.com/razor-x/kit/wiki/Pre-built-kits] or {build your own kit}[https://github.com/razor-x/kit/wiki/Building-your-own-kit]. Once you have a kit, create a new kit object with
 
-  k = Kit.new "/path_to/config.yml"
+Kit supports a robust action queue though {Delayed_job}[https://github.com/tobi/delayed_job].
+One process can be responsible for queuing tasks and another for running them.
 
-where the config file is either the default config file included with the kit, or your own that may override some of the defaults. Now you can start adding bits and queuing and running tasks:
+=== Example use scenario
 
-  bit = {  :name => "foo", :group_name => "bar" }
-  k.add_bit bit
+What can you use kit for? Here is an example a web server admin might be familiar with.
 
-  { :baz => { :bit => 1 } }.each do |action, options|
-    k.add_task action, options
-  end
+Say you are running Apache with multiple virtual hosts (vhosts).
+You are constantly adding new domain names, updating their configurations, etc.
+Here is how a Kit could manage the vhosts.
 
-  k.run_tasks
+* Each vhost is a bit.
+* Actions might look like
 
-For more information on what methods are available see the {YARD documentation}[https://rubygems.org/gems/kit] which is hosted at RubyGems.org. For more detailed information on how to use Kit, check out the wiki[https://github.com/razor-x/kit/wiki].
+    vhost.create                 #=> set up directory structure
+    vhost.generate_apache_config #=> generate new apache config files from ERB template
+    vhost.online                 #=> make website accessible
+    vhost.offline                #=> set a static 'site is down' page
+    vhost.destroy                #=> remove all trace of the vhost
+
+* By grouping the vhosts, each action can depend on the type of web application the vhost will be running.
+* Kit can store metadata about the vhosts which you can use when defining actions.
 
 == Installation
 
-=== Gem Installation
+Add this line to your application's Gemfile:
+
+  gem 'kit'
+
+And then execute:
+
+  $ bundle
+
+Or install it yourself as:
+
+  $ gem install kit
+
+== Getting started with kit
+
+=== Documentation
+
+* {Full source documentation}[rubydoc.info/gems/kit/frames] is hosted on the {gem page}[https://rubygems.org/gems/kit].
+* A {comprehensive wiki}[https://github.com/razor-x/kit/wiki] is available on github.
+
+=== Kit basics
+
+To use Kit, you will need a kit. You can either
+* Download a {community built kit}[https://github.com/razor-x/kit/wiki/Community-built-kits].
+* {Build your own kit}[https://github.com/razor-x/kit/wiki/Building-your-own-kit].
+If you skipped the above links and just want to get started, run
 
-Download and install Kit with
+  $ mkdir my_kit && cd my_kit && git init && git pull git://github.com/razor-x/kits_skeleton.git
 
- gem install kit
+Once you have a kit, navigate to the root directory and run
+
+  $ rake db:migrate
+
+This will set up the database.
+Create an action by adding a method to the +KitActionsDefault+ module located in +actions/default.rb+.
+
+Open the kit
+
+  require 'kit'
+  Kit.open 'config.yml'
+
+and make a new bit.
+
+  Kit::Bit.create :name => 'lilac'
+
+Now you can call the action with
+
+  Kit::Bit.find_by_name('lilac').plant_seeds
+
+If you got this far, refer to the documentation listed above for more examples of what kit can do.
 
 == Development
 
 === Source Repository
 
-Kit is currently hosted at github. The github web page is
-https://github.com/razor-x/kit. To clone the project run
+The {Kit source}[https://github.com/razor-x/kit] is currently hosted at github.
+To clone the project run
+
+  $ git clone git://github.com/razor-x/kit.git
+
+After cloning, you can run +yard+ to generate documentation for the source
+
+  $ cd kit
+  $ yard
 
-  git clone git://github.com/razor-x/kit.git
+You will also need to set up the test_kit to run specs. Do this with
 
-After cloning, you should run yard to generate documentation for the source.
+  $ rake develop:prepare
 
 == License
 

data/Rakefile

@@ -0,0 +1,21 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'git'
+
+namespace 'develop' do
+
+  test_kit = File.expand_path '../test_kit', __FILE__
+
+  task :prepare do |t|
+    puts 'Test kit exists, no need to clone it.' if File.exists? test_kit
+    Git.clone 'git://github.com/razor-x/kits_skeleton.git', test_kit unless File.exists? test_kit
+  end
+
+  task :update  => [ :prepare ] do |t|
+    Git.open(test_kit).pull
+  end
+
+  task :reset => [ :prepare, :update ] do |t|
+    Git.open(test_kit).reset_hard('master')
+  end
+end

data/kit.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path( '../lib/kit/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ['Evan Boyd Sosenko']
+  gem.email         = ['razorx@evansosenko.com']
+  gem.description   = %q{Extendable tool to manage site development and more.}
+  gem.summary       = %q{Kit is a framework for making simple management tools called kits.}
+  gem.homepage      = "http://evansosenko.com"
+  gem.license       = 'MIT'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = 'kit'
+  gem.require_paths = ['lib']
+  gem.platform      = Gem::Platform::RUBY
+  gem.version       = Kit::VERSION
+
+  gem.add_dependency 'activerecord'
+  gem.add_dependency 'rake'
+
+  gem.add_development_dependency 'sqlite3'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'git'
+
+end

data/lib/kit.rb

@@ -1,175 +1,72 @@
-require 'yaml'
+require 'active_record'
+require 'sqlite3'
 
-# Primary class for Kit.
-class Kit
-
-	require 'kit/bit'
-
-	# Exceptions.
-
-	# Raised when an action is specified that is not in the defined actions for the kit.
-	class NoAction < RuntimeError
-	end
-
-	# Loads the settings for the kit.
-	# @param [String, Hash] config path to kit config file or hash of kit settings
-	def initialize config
-		# Load the config and merge with the default config.
-		config = load_config_file config if File.exists? config
-
-		fail "No path to kit set" unless config[:kits_path]
-
-		@@kit_path = config[:kits_path]
-		defaults = YAML.load File.read @@kit_path + "/config.yml"
-		config = defaults.merge config
-
-		# Load backend for selected database type.
-		load 'kit/db_sqlite3.rb' if config[:db_backend] == :sqlite3
-
-		# Load class files for the kit
-		begin
-			load @@kit_path + "/bit.rb"
-			load @@kit_path + "/kit.rb"
-			load @@kit_path + "/actions.rb"
-		rescue LoadError
-		end
-
-		# Set the class variables.
-		@@info = config[:info]
-		@@unique = config[:unique]
-		@@actions = config[:actions]
-		@@status_types = [ :pending, :completed, :failed, :running ]
-		@@db = Backend.new config[:db_config]
-
-		# Run initialization specific to the kit.
-		begin
-			self.kit_initialize
-		rescue NoMethodError
-		end
-	end
-
-	# Kit related methods.
-
-	# @return [Hash] names of actions defined for this kit
-	def action_types
-		@@actions.keys
-	end
-
-	# @return [Array] names of task status types defined for this kit
-	def status_types
-		@@status_types
-	end
-
-	# Deletes the kit's databases.
-	def delete_dbs
-		@@db.delete
-	end
+require 'kit/version'
+require 'kit/db_support'
+require 'kit/models/bit'
+require 'kit/models/group'
+require 'kit/models/user'
+require 'kit/models/permission'
 
-	# Bit related methods.
-
-	# Creates bit object if it is unique enough.
-	# @param [Hash] info requested initial properties of the bit
-	# @return [Bit, nil] the new bit or nil if too similar to a bit that already exists
-	def add_bit info
-		begin
-			Bit.new info
-		rescue Bit::DuplicateElement
-			nil
-		end
-	end
-
-	# Gets a bit that matches id or info.
-	# @param [Integer, Hash] bit id or hash of info unique enough to identify a bit
-	# @return [Bit, nil] the Bit or nil if no unique bit could be found
-	def get_bit info
-		begin
-			if info.is_a? Integer
-				Bit.new info
-			elsif info.is_a? Hash
-				ids = Bit::lookup_id info
-				raise Bit::DuplicateElement unless ids.length == 1
-				Bit.new ids.first
-			end
-		rescue Bit::NoElement, Bit::DuplicateElement
-			nil
-		end
-	end
-
-	# Task related methods.
-
-	# Gets all tasks with requested status for one action type.
-	# @param [Symbol] name of action type to get tasks for
-	# @param [Symbol] task status
-	# @return [Array] tasks for given action type with requested status
-	def get_tasks_by_status action, status
-		@@db.select_all_actions_by_status action, @@actions[action], status
-	end
-
-	# Adds a new task to the corresponding action table.
-	# @param [Symbol] action name of the action type
-	# @param [Hash] options options for the corresponding action type
-	def add_task action, options
-		begin
-			fail NoAction, "#{action}" unless @@actions.include? action
-			@@db.insert_action action, options
-		rescue NoAction => ex
-			puts "Could not add task, no such action: '#{ex.message}'."
-		end
-	end
-
-	# Runs all pending tasks.
-	def run_tasks
-		collect_tasks_by_bit.each do |bit, tasks|
-			b = get_bit bit
-			next if b.nil?
-
-			actions = tasks.group_by { |t| t[:action] } . keys
-			actions.each do |a|
-				load @@kit_path + "/actions/#{a}.rb"
-				load @@kit_path + "/actions/#{b.group_name}/#{a}.rb"
-				b.extend Actions
-			end
-
-			tasks.each do |t|
-				b.queue_task t
-			end
-
-			b.run_all
-		end
-	end
-
-	private
-	# Gets all pending tasks with requested status and groups them by bit.
-	# @return [Hash{Integer => Hash}] tasks grouped by bit id
-	def collect_tasks_by_bit
-		tasks = []
-		@@actions.each_key do |action|
-			tasks.push get_tasks_by_status action, :pending
-		end
-		tasks.flatten!
-		tasks.group_by { |t| t[:bit] }
-	end
-
-	# Converts a kit config file into a hash of kit settings.
-	# @param [String] file path to a kit config file in YAML format
-	# @return [Hash] kit settings
-	def load_config_file file
-
-		# Load the file using YAML.
-		config = YAML.load File.read file
-		@@config_path = File.absolute_path File.dirname file
-
-		# Determine the path to the kit.
-		config[:kits_path] = \
-			if config[:kits_path].nil?
-				@@config_path
-			elsif ! [ "/", "~" ].include? config[:kits_path][0]
-				File.absolute_path @@config_path + config[:kits_path]
-			else
-				config[:kits_path]
-			end
+class Kit
 
-		return config
-	end
+  # Load a kit with its configuration.
+  # @param [String, Hash] config_file path to kit config file in kit root directory
+  def initialize config_file
+    @config_file = File.absolute_path config_file
+    Dir["#{path}/models/*.rb"].each { |f| require f }
+    Dir["#{path}/actions/*.rb"].each { |f| require f }
+  end
+
+  # Load a kit with its configuration and connect to its database.
+  # @param config_file (see #initialize)
+  def self.open config_file
+    kit = self.new config_file
+    kit.db_connect
+    kit
+  end
+
+  # Determines and returns the kit's root directory.
+  # @return [String] path to kit's root directory
+  def path
+    @path ||= File.dirname @config_file
+  end
+
+  # Loads settings from the config file (only loads from file on first call).
+  # @return [Hash] kit settings
+  def config
+    @config ||= YAML.load File.read(@config_file)
+  end
+
+  # Dynamically define actions handled by KitDBSupport.
+  [:create, :destroy, :connect, :migrate, :migrate_to].each do |action|
+    define_method "db_#{action}".to_sym do |*args|
+      db_action action, *args
+      return self
+    end
+  end
+
+  # Some actions have bang versions.
+  [:create, :destroy].each do |action|
+    define_method "db_#{action}!".to_sym do |*args|
+      db_action action, *args
+      return self
+    end
+  end
+
+  private
+
+  # Passes db_* method calls to KitSupportDB.
+  def db_action action, *args
+    if [:migrate, :migrate_to].include? action
+      KitDBSupport.send action, path, *args
+    else
+      if config[:db][:adapter] == 'sqlite3'
+        db_path = config[:db][:database]
+        config[:db][:database] = "#{path}/#{db_path}" unless db_path =~ /^(\/|~)/
+      end
+      KitDBSupport.send action, config[:db], *args
+    end
+  end
 
 end