helium 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.spec 'helium' do |p|
+  p.developer('James Coglan', 'james.coglan@othermedia.com')
+  p.extra_deps = [['grit','>= 0'], ['jake','>= 1.0.1'], ['packr','>= 3.1'],
+                  ['oyster','>= 0.9.3'], ['sinatra','>= 0.9.4'], ['rack','>= 1.0']]
+end
+
+# vim: syntax=ruby

data/bin/he

@@ -0,0 +1,126 @@
+#! /usr/bin/env ruby
+$VERBOSE = nil
+home = File.join(File.dirname(__FILE__), '..')
+
+require 'fileutils'
+require 'rubygems'
+require 'oyster'
+require 'jake'
+require 'rack'
+
+require File.join(home, 'lib', 'helium')
+
+spec = Oyster.spec do
+  name 'helium -- the Git-backed JavaScript package server'
+  author 'James Coglan <jcoglan@googlemail.com>'
+  
+  description <<-EOS
+    Helium is a web application for deploying and serving versioned copies of
+    JavaScript libraries from Git repositories. It uses Jake to build libraries
+    and extract dependency data, generating a manifest for JS.Packages so that
+    client sites can load objects from Helium on demand.
+    
+    The following command line tools are available; run each one with `--help`
+    for more information.
+    
+    `he install` creates a copy of the web frontend that you can serve using
+    Rack and Passenger.
+    
+    `he create` generates a stub JavaScript project with all the files required
+    for Helium to deploy it.
+    
+    `he serve` starts a web server to serve static files from any directory,
+    useful for testing code that requires a domain name to function.
+  EOS
+  
+  subcommand :install do
+    synopsis 'he install DIRECTORY'
+    
+    description <<-EOS
+      Installs a copy of the Helium web application in the given directory.
+      Set up an Apache VHost with the DocumentRoot pointing to DIRECTORY/public
+      to serve the app through Phusion Passenger.
+    EOS
+  end
+  
+  subcommand :create do
+    synopsis 'he create NAME'
+    
+    description <<-EOS
+      Creates a new JavaScript project with the given name, containing a stub
+      library file, a jake.yml config file and support code for generating
+      local package listings and running tests.
+    EOS
+  end
+  
+  subcommand :serve do
+    synopsis 'he serve DIRECTORY'
+    
+    description <<-EOS
+      Starts a webserver on port 8000 that serves the given directory over HTTP.
+      Useful for testing pages that require Ajax or services with domain specific
+      API keys like Google Maps.
+    EOS
+  end
+end
+
+begin; options = spec.parse
+rescue; exit
+end
+
+if opts = options[:install]
+  dir = opts[:unclaimed].first
+  if dir.nil?
+    puts "Installation directory required -- type `he install --help` for more info"
+    exit
+  end
+  
+  dir = File.expand_path(dir)
+  d = File.basename(dir)
+  
+  puts "\nInstalling Helium app in #{dir}..."
+  Helium.generate('web', dir)
+  
+  puts "\n... done, now set up your webserver to serve the app:\n\n"
+  puts "  * Point Apache at #{d}/public to serve using Passenger"
+  puts "  * Run `rackup #{d}/config.ru` to run it locally\n\n"
+
+elsif opts = options[:create]
+  name = opts[:unclaimed].first
+  if name.nil?
+    puts "Project name required -- type `he create --help` for more info"
+    exit
+  end
+  
+  dir = File.expand_path(name)
+  d = File.basename(dir)
+  
+  puts "\nGenerating JavaScript project in #{dir}..."
+  Helium.generate('project', dir, :name => name)
+  
+  puts "\nBuilding project using Jake..."
+  jake_hook(:file_created) do |build, package, type, path|
+    puts "create #{d}#{ path.sub(dir, '') }"
+  end
+  Jake.build!(dir)
+  
+  puts "\n... done, now your new JavaScript project is ready.\n\n"
+  puts "  * Build your project by running `jake` in the root directory"
+  puts "  * We've added generated files to your .gitignore"
+  puts "  * Keep your dependencies up-to-date in jake.yml"
+  puts "  * Point test/index.html at your Helium server and write some tests!\n\n"
+
+elsif opts = options[:serve]
+  dir = File.expand_path(opts[:unclaimed].first || '.')
+  app = Rack::File.new(dir)
+  
+  server = %w[thin mongrel webrick].map { |name|
+    begin; Rack::Handler.get(name)
+    rescue LoadError; nil
+    end
+  }.compact.first
+  
+  puts "Serving contents of #{dir} on port 8000..."
+  server.run(app, :Port => 8000)
+end
+

data/lib/helium.rb

@@ -0,0 +1,50 @@
+require 'observer'
+require 'erb'
+require 'yaml'
+require 'fileutils'
+require 'find'
+
+require 'rubygems'
+require 'grit'
+require 'jake'
+require 'packr'
+require 'oyster'
+
+module Helium
+  
+  VERSION = '0.1.0'
+  
+  ROOT          = File.expand_path(File.dirname(__FILE__))
+  TEMPLATES     = File.join(ROOT, '..', 'templates')
+  ERB_EXT       = '.erb'
+  JS_CONFIG_TEMPLATE = File.join(TEMPLATES, 'packages.js.erb')
+  
+  CONFIG_FILE   = 'deploy.yml'
+  REPOS         = 'repos'
+  STATIC        = 'static'
+  PACKAGES      = 'helium-src.js'
+  PACKAGES_MIN  = 'helium.js'
+  WEB_ROOT      = 'js'
+  
+  GIT           = '.git'
+  HEAD          = 'HEAD'
+  
+  JS_CLASS      = 'js.class'
+  LOADER_FILE   = 'loader.js'
+  JAKE_FILE     = Jake::CONFIG_FILE
+  
+  SEP  = File::SEPARATOR
+  BYTE = 1024.0
+  
+  ERB_TRIM_MODE = '-'
+  
+  %w[trie configurable deployer generator logger].each do |file|
+    require File.join(ROOT, 'helium', file)
+  end
+  
+  def self.generate(template, dir, options = {})
+    Generator.new(template, dir, options).run!
+  end
+  
+end
+

data/lib/helium/configurable.rb

@@ -0,0 +1,26 @@
+module Helium
+  module Configurable
+    
+    def configure
+      yield(configuration)
+    end
+    
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias :config :configuration
+    
+    class Configuration
+      def initialize(hash = {})
+        @options = {}.merge(hash)
+      end
+      
+      def method_missing(name, value = nil)
+        @options[name] = value unless value.nil?
+        @options[name]
+      end
+    end
+    
+  end
+end
+

data/lib/helium/deployer.rb

@@ -0,0 +1,216 @@
+module Helium
+  # The +Deployer+ class is responsible for performing all of Helium's central functions:
+  # downloading projects from Git, exporting static copies of branches, building projects
+  # using Jake and generating the dependency file.
+  # 
+  # To run, the class requires a file called `deploy.yml` in the target directory, listing
+  # projects with their Git URLs. (See tests and README for examples.)
+  # 
+  class Deployer
+    include Observable
+    
+    # Initialize using the directory containing the `deploy.yml` file, and the name of
+    # the directory to export repositories and static files to.
+    # 
+    #   deployer = Helium::Deployer.new('path/to/app', 'js')
+    # 
+    def initialize(path, output_dir = 'output', options = {})
+      @path       = File.expand_path(path)
+      @config     = join(@path, CONFIG_FILE)
+      raise "Expected config file at #{@config}" unless File.file?(@config)
+      @output_dir = join(@path, output_dir)
+      @options    = options
+    end
+    
+    # Returns a hash of projects names and their Git URLs.
+    def projects
+      return @projects if defined?(@projects)
+      
+      data = YAML.load(File.read(@config))
+      raise "No configuration for JS.Class" unless js_class = data[JS_CLASS]
+      @jsclass_version = js_class['version']
+      
+      @projects = data['projects'] || {}
+      @projects[JS_CLASS] = js_class['repository']
+      @projects
+    end
+    
+    # Runs all the deploy actions. If given a project name, only checks out and builds
+    # the given project, otherwise builds all projects in `deploy.yml`.
+    def run!(project = nil)
+      return deploy!(project) if project
+      projects.each { |project, url| deploy!(project, false) }
+      run_builds!
+    end
+    
+    # Deploys an individual project by checking it out from Git, exporting static copies
+    # of all its branches and building them using Jake.
+    def deploy!(project, build = true)
+      checkout(project)
+      export(project)
+      run_builds! if build
+    end
+    
+    # Checks out (or updates if already checked out) a project by name from its Git
+    # repository. If the project is new, we use `git clone` to copy it, otherwise
+    # we use `git fetch` to update it.
+    def checkout(project)
+      dir = repo_dir(project)
+      if File.directory?(join(dir, GIT))
+        log :git_fetch, "Updating Git repo in #{ dir }"
+        cd(dir) { `git fetch origin` }
+      else
+        url = projects[project]
+        log :git_clone, "Cloning Git repo #{ url } into #{ dir }"
+        `git clone #{ url } "#{ dir }"`
+      end
+    end
+    
+    # Exports static copies of a project from every branch and tag in its Git repository.
+    # Existing static copies on disk are destroyed and replaced.
+    def export(project)
+      repo_dir = repo_dir(project)
+      repo     = Grit::Repo.new(repo_dir)
+      branches = repo.remotes + repo.tags
+      
+      mkdir_p(static_dir(project))
+      
+      branches.each do |branch|
+        name, commit = branch.name.split(SEP).last, branch.commit.id
+        next if HEAD == name
+        
+        target = static_dir(project, commit)
+        
+        log :export, "Exporting branch '#{ name }' of '#{ project }' into #{ target }"
+        rm_rf(target) if File.directory?(target)
+        cp_r(repo_dir, target)
+        
+        cd(target) {
+          if repo.branches.map { |b| b.name }.include?(name)
+            `git checkout #{ name }`
+            `git merge #{ branch.name }`
+          else
+            `git checkout -b #{ name } #{ branch.name }`
+          end
+        }
+      end
+    end
+    
+    # Scans all the checked-out projects for Jake build files and builds those projects
+    # that have such a file. As the build progresses we use Jake event hooks to collect
+    # dependencies and generated file paths, and when all builds are finished we generate
+    # a JS.Packages file listing all the files discovered. This file should be included
+    # in web pages to set up the the packages manager for loading our projects.
+    def run_builds!(options = nil)
+      options ||= @options
+      
+      @tree    = Trie.new
+      @custom  = options[:custom]
+      @domain  = options[:domain]
+      manifest = []
+      
+      # Loop over checked-out projects. Skip directories with no Jake file.
+      Find.find(static_dir) do |path|
+        next unless File.directory?(path) and File.file?(join(path, JAKE_FILE))
+        
+        project, commit = *path.split(SEP)[-2..-1]
+        branch = Grit::Repo.new(path).head.name
+        Jake.clear_hooks!
+        
+        # Event listener to capture file information from Jake
+        hook = lambda do |build, package, build_type, file|
+          if build_type == :min
+            @js_loader = file if File.basename(file) == LOADER_FILE and
+                                 project == JS_CLASS and
+                                 branch  == @jsclass_version
+            
+            file = file.sub(path, '')
+            manifest << join(project, commit, file)
+            @tree[[project, branch]] = commit
+            @tree[[project, branch, file]] = package.meta
+          end
+        end
+        jake_hook(:file_created, &hook)
+        jake_hook(:file_not_changed, &hook)
+        
+        log :jake_build, "Building branch '#{ branch }' of '#{ project }' from #{ join(path, JAKE_FILE) }"
+        
+        begin; Jake.build!(path)
+        rescue; end
+      end
+      
+      generate_manifest!
+      manifest + [PACKAGES, PACKAGES_MIN]
+    end
+    
+    # Removes any repositories and static files for projects not listed in the the
+    # `deploy.yml` file.
+    def cleanup!
+      [repo_dir, static_dir].each do |dir|
+        next unless File.directory?(dir)
+        (Dir.entries(dir) - %w[. ..]).each do |entry|
+          path = join(dir, entry)
+          next unless File.directory?(path)
+          rm_rf(path) unless projects.has_key?(entry)
+        end
+      end
+    end
+    
+    # Returns the path to the Git repository for a given project.
+    def repo_dir(project = nil)
+      path = [@output_dir, REPOS, project].compact
+      join(*path)
+    end
+    
+    # Returns the path to the static export directory for a given project and branch.
+    def static_dir(project = nil, branch = nil)
+      path = [@output_dir, STATIC, project, branch].compact
+      join(*path)
+    end
+      
+  private
+    
+    # Generates JS.Packages dependency file from ERB template and compresses the result
+    def generate_manifest!
+      template = File.read(JS_CONFIG_TEMPLATE)
+      code     = ERB.new(template, nil, ERB_TRIM_MODE).result(binding)
+      packed   = Packr.pack(code, :shrink_vars => true)
+      
+      mkdir_p(static_dir)
+      File.open(static_dir(PACKAGES), 'w') { |f| f.write(code) }
+      File.open(static_dir(PACKAGES_MIN), 'w') { |f| f.write(packed) }
+    end
+    
+    # Returns +true+ iff the set of files contains any dependency data.
+    def has_manifest?(config)
+      case config
+      when Trie then config.any? { |path, conf| has_manifest?(conf) }
+      when Hash then config.has_key?(:provides)
+      else nil
+      end
+    end
+    
+    # Notifies observers by sending a log message.
+    def log(*args)
+      changed(true)
+      notify_observers(*args)
+    end
+    
+    # Shorthand for <tt>File.join</tt>
+    def join(*args)
+      File.join(*args)
+    end
+    
+    # We use +method_missing+ to create shorthands for +FileUtils+ methods.
+    def method_missing(*args, &block)
+      FileUtils.__send__(*args, &block)
+    end
+    
+    def `(command)
+      puts command
+      system(command)
+    end
+    
+  end
+end
+

data/lib/helium/generator.rb

@@ -0,0 +1,69 @@
+module Helium
+  # The +Generator+ class is used by the command-line tools to create copies of
+  # the web app and the JavaScript project template. It copies the contents of
+  # one of the +template+ directories into a local directory, expanding any files
+  # with .erb extensions as ERB templates.
+  # 
+  # For example, a file <tt>jake.yml.erb</tt> will be copied into the target dir as
+  # <tt>jake.yml</tt> after being evaluated using ERB.
+  # 
+  # If a filename contains variable names enclosed in double-underscores, the
+  # resulting copy will have those replaced by the value of the named instance
+  # variable. For example, <tt>__name__.js</tt> will be copied to <tt>myproj.js</tt>
+  # if <tt>@name = 'myproj'</tt>.
+  # 
+  class Generator
+    
+    # Generators are initialized using the name of the template (a collection of
+    # files in the +templates+ directory, a target directory and an option hash.
+    # Keys in the option hash become instance variables accessible to ERB templates.
+    def initialize(template, dir, options = {})
+      options.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+      @_source    = join(TEMPLATES, template)
+      @_directory = expand_path(dir)
+    end
+    
+    # Runs the generator, copying all files as required. All ERB/name replacement
+    # is handled in this method.
+    def run!
+      Find.find(@_source) do |path|
+        next unless file?(path)
+        content = read(path)
+        
+        # Replace variable names in file paths
+        path = path.sub(@_source, '').gsub(/__(.+?)__/) { instance_variable_get("@#{$1}") }
+        target = join(@_directory, path)
+        
+        # Evaluate using ERB if required
+        if extname(path) == ERB_EXT
+          content = ERB.new(content).result(binding)
+          target  = join(dirname(target), basename(target, ERB_EXT))
+        end
+        
+        # Generate destination file
+        FileUtils.mkdir_p(dirname(target))
+        open(target, 'w') { |f| f.write(content) }
+        puts "create #{ basename(@_directory) }#{ target.sub(@_directory, '') }"
+      end
+    end
+    
+    # Provide shorthand access to all +File+ methods.
+    def method_missing(*args, &block)
+      File.__send__(*args, &block)
+    end
+    
+    # Returns a camelcased copy of the string, for example:
+    # 
+    #   camelize('my-project')
+    #   #=> 'MyProject'
+    # 
+    def camelize(string)
+      string.gsub(/^(.)/) { $1.upcase }.
+             gsub(/[\s\-\_](.)/) { $1.upcase }
+    end
+    
+  end
+end
+